From 74f97231fd64593237998dc34556cb7d243b5a75 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Sun, 11 Oct 2026 18:42:01 +0800 Subject: [PATCH] =?UTF-8?q?docs(dev+gdd):=20=E6=B5=8B=E8=AF=95=E5=87=BD?= =?UTF-8?q?=E6=95=B0=E8=90=BD=E7=A0=81=E8=A7=84=E8=8C=83=E8=90=BD=20code-c?= =?UTF-8?q?onventions=20=C2=A73.5=20+=20=E6=9C=AF=E8=AF=AD=E8=A1=A8?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E6=B5=81=E7=A8=8B=E4=B8=A4=E8=AF=8D=E6=9D=A1?= =?UTF-8?q?=EF=BC=88=E9=80=BB=E8=BE=91=E9=AA=8C=E6=94=B6=E6=96=B9=E6=B3=95?= =?UTF-8?q?=E8=AE=BA=E6=89=B9=EF=BC=8C2026-10-11=20=E7=94=A8=E6=88=B7?= =?UTF-8?q?=E8=A3=81=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- design/dev/code-conventions.md | 20 ++++++++++++++++++++ design/gdd/术语表.md | 8 ++++++++ 2 files changed, 28 insertions(+) diff --git a/design/dev/code-conventions.md b/design/dev/code-conventions.md index cdf20ee7..6f2d8ffb 100644 --- a/design/dev/code-conventions.md +++ b/design/dev/code-conventions.md @@ -95,6 +95,25 @@ 交付前必须全绿：`smoke_all.gd` + 全部场景探针（ui_probe / ui_click_probe / ui_tune_probe）。 行为探针使用随机化玩家行为（旗/停手/刷新/无效点击）——自动玩家不做的动作就是测试盲区。 +### 3.5 测试函数怎么写——验收清单条目的落码规范（2026-10-11 用户立规） + +需求卡片 §7「逐需求点验收清单」每一条都要落成可执行的验证；本节定统一写法，卡里定每批的具体内容（测什么/注入哪里）。写卡期查不出执行载体的条目=不可测，当场呈报，禁拖到实现期。 + +1. **执行载体五选一，逐条声明**：单元测试（`tests/run_all`）／冒烟断言（`smoke_all.gd` 对应场景段）／场景探针（`smoke/` 下 `*_probe`）／MC 同种子对拍／人工核对（仅限无法自动化的纪律类需求点，如命名锁定、数值占位）。行为类条目以自动化载体为主。 +2. **粒度与对应关系**：每条清单条目至少一个自动断言；多条条目可合用一个测试函数。断言失败消息末尾带编号尾缀〔卡短名 Vn〕（如〔秘宝批 V3〕）——断言与卡片清单可互相 grep 查找。 +3. **断言词汇按验证对象五选一**： + + | 词汇 | 适用场景 | + |---|---| + | 逐位相等 | 同种子下确定性公式与结算的精确对拍 | + | 区间/差值带 | 概率与平衡读数（MC 同种子配对比较，出带即红） | + | 快照比对 | 存档域结构、配置表行结构 | + | 重放 | 同种子断点回放、改前改后配对 | + | 状态/计数器断言 | 条件解锁、限次、充能——置数据→走路径→断计数值 | + +4. **调试注入两层（测试方式两分法的落码面）**：自动化测试=测试代码直调核心层写口构造状态（直改数据表行/计数器/存档域，不经 UI、不走正常资源积累流程——冒烟现役做法）；人工体验=DebugOverlay/DS_DEBUG 调试面，服务用户目检。清单条目的「怎么测」必须写到数据面粒度：改哪张表哪行、置哪个计数、调哪个核心写口。 +5. **换代批旧验证约束同生死**：删除旧数据行/旧实现代码的批次，必须同批摘除只验证旧实现的断言与护栏校验，由新断言替代——旧件断言残留=冒烟假绿来源；合并后冒烟全绿且全仓无旧件残留引用为证。 + --- ## 4. 语言纪律——GDScript 4.x 实战坑（本项目踩实） @@ -160,3 +179,4 @@ |---|---|---| | v1 | 2026-09-11 | 首版成文（垂直切片评审用户逐一指出，全部附真实反面案例） | | v2 | 2026-10-09 | 文档正确性审查批·独立复核（worktree docaudit-2026-10-09）：§6 流程纪律第 2 条「production/session-state/active.md」过期路径改「根目录 active.md」（会话状态唯一状态源，2026-10-09 用户定性为状态文件并迁根目录）；本表系本批补建 | +| v3 | 2026-10-11 | 新增 §3.5「测试函数怎么写——验收清单条目的落码规范」（2026-10-11 用户立规，需求卡片逻辑验收方法论批）：执行载体五选一逐条声明／断言消息带〔卡短名 Vn〕编号尾缀／断言词汇五选一表／调试注入两层／换代批旧验证约束同生死 | diff --git a/design/gdd/术语表.md b/design/gdd/术语表.md index 6577c297..a93ef764 100644 --- a/design/gdd/术语表.md +++ b/design/gdd/术语表.md @@ -51,6 +51,13 @@ | 专长 | 奇物的分类之一：改写规则的机制件 | | 专长凭证 | 换取一次专长三选一资格的凭证——奖励节点与商店不直接给专长，给凭证（原「凭证」，2026-10-11 用户裁更名） | +## 开发流程 + +| 术语 | 定义 | +|---|---| +| 逐需求点验收清单 | 需求卡片验证闸的必备清单：每个需求点列明测什么（具体断言或行为）/怎么测（测试落点与注入方式）/谁验（自动闸或用户目检）；查不出验收条目的需求点=卡片不成立（规矩见 req-card 技能，测试落码写法见 [code-conventions](../dev/code-conventions.md) §3.5） | +| 测试方式两分法 | 能力验证与体验验证分开走（2026-10-11 用户定）：能力验证=通过调试接口直接修改游戏数据（改钥石/槽位/解锁状态等，不走正常资源积累流程）；体验验证=用户目检完整流程，登记 07-体验验证清单观测项 | + ## 退役词对照（文档正文禁用） | 退役词 | 现行词 | @@ -84,3 +91,4 @@ | v1.5 | 2026-10-11 | 拾取渠道废止批随批：删「未知秘宝」词条（用户终裁装配只在冒险开始前配置、冒险中零更换途径） | | v1.6 | 2026-10-11 | **对外命名纪律节新增（用户令「对外命名不要有雷跟插旗相关名词」）**：禁「雷/插旗」字面入对外命名；插旗对外=封印、危险格对外风味=地下城陷阱/怪物巢穴（风味层巢穴除外）；适用=件名/显示名/UI 文案/成就百科，机制文档内部用语不受限；首例=专长 27 件第一版命名（奇物.md v3.15 九件换代） | | v1.7 | 2026-10-11 | **通关术语裁定（用户裁）**：通关=打通整局冒险、通过第 N 关=打通第 N 关卡，两词非同义；存量文档中「通关次数」指每关卡澄清（历史行不动，全库口径统一随术语执行批） | +| v1.8 | 2026-10-11 | 新增「开发流程」节两词条：逐需求点验收清单（req-card 技能 §7 三层结构核心名词）、测试方式两分法（能力验证走调试接口/体验验证用户目检）——需求卡片逻辑验收方法论批随批登记 |