写卡(L1 深度 3 改混编): 新增 reports/需求卡片-L1深度3混编-2026-11-04.md——八条验收断言 R1-R8(键序/混编构成/骰和 3/行值整行复用/双池/≥2 敌夹具/夹具换 id/零残留)、三张任务卡估 2 个工作日、关联文档同步面五项零动作(文档批 4aaa154e 已落文)、落位与复用预检零新增件、零待裁点; 待办清单条目状态推进「文档设计已闭合+已写卡」证据落实况。验证: pipeline_gate PASS(28 条目/卡片口径 3 张全过),--docs 验收通过无新增红。未跑: MC 与读数(Alpha 零读数,2026-11-04 用户裁); grilling 复核门待执行。

This commit is contained in:
DKChan committed 2026-11-04 00:54:46 +08:00
1 parent 4aaa154ec6
commit 1fbdefb41c
2 files changed
+170 -2

No files matched your search

@@ -0,0 +1,168 @@
# 需求卡片 · L1 深度 3 改地精+熊地精混编(大地精数据行退役)
来源:待办清单「L1 深度 3 改地精+熊地精混编(大地精数据行退役)」(2026-11-04 登记,文档设计已闭合+待写卡)(唯一事实源:`design/gdd/systems/冒险循环/难度曲线与Boss.md` v1.3「混编行集难度归属注记」投放记录段 + `design/gdd/systems/战斗循环/敌人系统.md` v1.6 核心规则「开战生成」「技能池」前的敌种表段与「行集构成纪律」条)
日期 2026-11-04 | 段位=写卡(第三段)| 开工门=用户发令 U0
## 一、目标与完成定义
把敌人表里未经过设计的大地精数据行(`hobgoblin`)退役,同一坐标改为「熊地精 + 地精」两行混编,让第一关深度 3–5 的战斗由「2–3 只同种」变成「一只前排熊地精 + 一到两只地精」。
完成定义(四条全中才算完):① 敌人表不再有 `hobgoblin`,该坐标是两行混编且行序为「熊地精在前」;② 两行行值逐字等于既有 `(1,battle,2)` 与 `(1,battle,0)` 行值(零数值新增);③ 全仓代码与表注再无 `hobgoblin` 残留;④ 冒烟与单元闸全绿。
## 二、设计事实源
- 投放决定与行序、数量、行值取定:`design/gdd/systems/冒险循环/难度曲线与Boss.md` v1.3「混编行集难度归属注记」的投放记录段(第二行 = (1,3) 地精 + 熊地精,2026-11-04 用户裁)
- 混编合法性四条纪律:`design/gdd/systems/战斗循环/敌人系统.md` v1.6 核心规则「行集构成纪律」条
- 读数义务口径(Alpha 零读数):`design/engineering/process-conventions.md` §3 第 5 条 Alpha 阶段口径段
- 待办清单条目:`待办清单.md`「L1 深度 3 改地精+熊地精混编(大地精数据行退役)」条
## 三、现状事实(代码级,开工自行复核)
| # | 事实 | 位置 |
|---|---|---|
| 1 | 大地精行在役:`(1,battle,3)`、2–3 只、hp14、atk 1 区间 [0,2]、池 attack6/charge2/heavy2、light、ac2 | `game/data/tables/enemy.tres:82-105` |
| 2 | 前排取用行:熊地精 `(1,battle,2)` 1 只定值、hp22、ac2、池 attack6/charge2/heavy2 | `game/data/tables/enemy.tres:58-80` |
| 3 | 后排取用行:地精 `(1,battle,0)` 1–2 只、hp8、ac0、池 attack9/lunge1/desperate_guard1 | `game/data/tables/enemy.tres:7-31` |
| 4 | 另一条熊地精行 `(1,battle,6)` 1–2 只、hp30、ac4 —— 本卡不取用(深档,第三战放它偏硬) | `game/data/tables/enemy.tres:107-131` |
| 5 | 敌人表共 28 行,键序被逐行钉死 | `game/tests/unit/data_config/table_structure_guard_test.gd:209-231` |
| 6 | 现有断言「hobgoblin 行在 (1,battle,3) 留任随迁」 | `game/tests/unit/data_config/table_structure_guard_test.gd:234-239` |
| 7 | 池模板断言表逐键写死,含 `1_battle_3_hobgoblin` | `game/tests/unit/battle_settlement/round_flow_skill_pool_test.gd:567-578`(函数 `_smoke_skill_pool_data`) |
| 8 | 个体池/个体 AC 对照用例以 depth 3 为「≥2 敌」夹具 | `game/tests/unit/battle_settlement/damage_controller_test.gd:412-440`;`game/tests/unit/presentation/battle_narrator_test.gd:108-118` |
| 9 | 行序/落带夹具用 hobgoblin 作合成行 | `game/tests/unit/core/config_db_resolver_test.gd:40-46`;断言在 `:56-78` |
| 10 | 行集纪律用例用 hobgoblin 作「不相邻」样本 | `game/tests/unit/data_config/config_db_test.gd:220-230`(函数 `_test_rowset_discipline`) |
| 11 | 首行即默认单体目标与开战叙述取首行 | `design/gdd/systems/战斗循环/敌人系统.md` v1.6「开战生成」节;实现侧 `game/core/unit_container.gd:34-45` |
| 12 | 混编定点断言先例(L2)写法可直接照抄 | `game/tests/unit/core/level_shop_economy_test.gd:623-640` |
| 13 | 术语审计注释里列了 hobgoblin | `tools/doc_term_audit.py:144` |
## 四、设计契约(🔴 违反=停机呈报)
1. 🔴 **行集构成纪律三条**:行集内 `enemy_id` 唯一;同带键多行必须文件内相邻且行序=声明序=生成序;行集实例总数 ≤ 4、单行数量域 [1,3]。本卡静态最坏骰和 = 熊地精 1 + 地精 2 = 3。
2. 🔴 **行值零新增**:两行行值必须整行复制既有行(第 2、3 条现状事实),不得顺手改 hp/atk/池权重/ac;若实施中发现必须改数值,停卡退回写卡段。
3. 🔴 **行序固定**:熊地精行在前、地精行在后。行序变更会改默认单体目标与开战叙述首行,属设计面变更,不在本卡授权内。
4. 🔴 **Alpha 零读数**:本卡不跑 MC、不采改前改后读数,实现报告注明「未取证」,读数义务归数值统一修正批(`process-conventions` §3 第 5 条)。
5. 🔴 **禁碰敌种表与技能表**:`敌人系统.md` 敌种表维持八种;`skills.tres` 零改动——地精与熊地精的池已存在。
6. 🔴 **禁改闸件口径**:`standee_asset_check`/`path_check` 的 `ENEMY_KEYS` 是美术侧键集,与本卡无关,禁顺手改。
## 五、范围边界
**做**:敌人表删一行加两行+表注三处改写;六处测试换锚与补断言;`tools/doc_term_audit.py` 注释一行。
**不做**:任何数值调整(hp/atk/池权重/ac);敌种表或技能表改动;立绘与美术面(不做该敌种,无素材需求);L1 其余四行;Boss 多行第二批;读数与模拟。
**不收件去向**:数值带位移读数 → 数值统一修正批;L1 实机混编目检 → `体验验证清单.md` ⑱(本卡只登记,不阻塞合并)。
## 六、关联文档同步面(实现批禁写文档)
| 文档 | 关联点 | 同步义务 |
|---|---|---|
| `design/gdd/systems/冒险循环/难度曲线与Boss.md` v1.3 | 「混编行集难度归属注记」已写入 (1,3) 投放记录 | 零动作(文档批已落文,commit 4aaa154e) |
| `design/gdd/systems/战斗循环/敌人系统.md` v1.6 | 大地精缺口登记已删除、敌种表维持八种 | 零动作(文档批已落文,commit 4aaa154e) |
| `体验验证清单.md` ⑱ | 已扩为 L1 节点 3 + L2 节点 5 双点目检 | 零动作(文档批已落文);实现批只把目检项抄进实现报告 |
| `design/gdd/08-Alpha版本标准.md` v1.26 | 混编遭遇行集状态行已补 (1,3) | 零动作(文档批已落文) |
| `game/tests/README.md` 能力表 | 本批不新增能力、不改既有用例函数名(改的是既有函数体内的断言与夹具) | 零动作;若实现期不得不改函数名,按反哺点列出 |
## 七、文件结构图
| 路径 | 职责 | 改动类型 | 对照表行 |
|---|---|---|---|
| `game/data/tables/enemy.tres` | 删 (1,3) 大地精行、原位起两行混编、改三处表注 | 行为改动 | R1–R5 |
| `game/tests/unit/data_config/table_structure_guard_test.gd` | 行数与键序换 29 行、留任断言换混编构成断言、补骰和与行值复用断言、补零残留断言 | 行为改动(测试面) | R1–R4、R8 |
| `game/tests/unit/battle_settlement/round_flow_skill_pool_test.gd` | 池模板表两键换原一键 | 行为改动(测试面) | R6 |
| `game/tests/unit/core/config_db_resolver_test.gd` | 合成夹具 enemy_id 换成既有键(行序/落带语义不变) | 非行为改动(夹具) | R7 |
| `game/tests/unit/data_config/config_db_test.gd` | 行集纪律样本 enemy_id 换既有键 | 非行为改动(夹具) | R7 |
| `game/tests/unit/battle_settlement/damage_controller_test.gd` | depth 3 夹具注释改述(前提「≥2 敌」仍成立) | 非行为改动(注释) | R7 |
| `game/tests/unit/presentation/battle_narrator_test.gd` | 同上 | 非行为改动(注释) | R7 |
| `tools/doc_term_audit.py` | 第 144 行注释里的敌种枚举去掉 hobgoblin | 非行为改动(注释) | R8 |
无新增文件、无新增类、无新增公开方法。
## 八、落位与可复用性预检
- **复用面**:本批零新增文件/函数/数据件。新增的两条表行不是新结构——`pool`、`armor_class`、`attack_type` 等字段全部沿用既有行字段集,直接整行复制既有行(第 2、3 条现状事实),不引入任何新字段或新默认值。
- **唯一面**:混编构成的事实只有两处——表的行序(`enemy.tres`)与钉住它的断言(`table_structure_guard_test.gd`)。行值不在测试里复写:断言比对「(1,3) 两行 == (1,2) 与 (1,0) 行」而不是写死 22/8/权重,防双写漂移。
- **分层与交互面**:本批不新增调用路径。运行时读取仍走 `ConfigDb` → `ConfigDbResolver.resolve_rowset(1, depth, "battle")` → `UnitContainer.spawn()`(`game/core/unit_container.gd:34-45`),分层与红线(Core 零 UI、数值只读表)不变。
## 九、实现规范预算
零新增文件与新增成员,`gdstyle` 阈值不适用。存量触面一查:本卡触碰的六个测试文件不新增成员变量与公开方法(只在既有函数体内改断言与夹具),S13 键「较登记值只降不升」在 T0 读数步骤核对。
## 十、拆分边界纪律
本卡不是拆分/收敛/重构类卡,条款不适用。
## 十一、任务卡
### T1 · 敌人表换行(估时 0.5 日)
取用:无(本卡首卡)。产出:`enemy.tres` 的 (1,3) 两行 —— 供 R1–R4 断言读取。
- [ ] 删 `game/data/tables/enemy.tres:82-105` 的整行(`enemy_id: hobgoblin`)
- [ ] 原位按序插入两行:第一行 `enemy_id: "bugbear"`/`display_name: "熊地精"`/`depth_band: 3`/`unit_count: 1`/无 `unit_count_max`/`hp: 22`/`atk: 1`/`atk_min: 0`/`atk_max: 2`/`pool: [attack 6, charge 2, heavy 2]`/`attack_type: "normal"`/`armor_type: "light"`/`armor_class: 2`
- [ ] 第二行 `enemy_id: "goblin"`/`display_name: "地精"`/`depth_band: 3`/`unit_count: 1`/`unit_count_max: 2`/`hp: 8`/`atk: 1`/`atk_min: 0`/`atk_max: 2`/`pool: [attack 9, lunge 1, desperate_guard 1]`/`attack_type: "normal"`/`armor_type: "light"`/`armor_class: 0`
- [ ] 改表注 `enemy.tres:886-891`:把「(1,3) 熊地精双雄 → 大地精」那段沿革注改为一行留痕「(1,3) 大地精行已于 2026-11-04 用户裁退役,改地精+熊地精混编——沿革见 git 提交史」
- [ ] 改表注 `enemy.tres:906-918`:把「首个混编行落表 = (2,5)」改为「混编投放两行:(2,5) 2026-10-07、(1,3) 2026-11-04」,并把句末「随 Alpha 收官 M4 数值批统一执行」改为「随数值统一修正批统一执行」
- [ ] 删表注 `enemy.tres:929` 整句(hobgoblin 行为缺口行)
- [ ] 回读:`grep -n "hobgoblin" game/data/tables/enemy.tres` 输出为空
### T2 · 测试面换锚与补断言(估时 1 日)
取用:T1 产出的两行。产出:八条断言(R1–R8)落地,供 T3 收口核对。
- [ ] `table_structure_guard_test.gd:209-231`:行数 28→29;`expect_keys` 里 `"1|battle|3|hobgoblin"` 换成相邻两键 `"1|battle|3|bugbear", "1|battle|3|goblin"`;函数头与 `print` 的「28 行键序 · hobgoblin 留任」文案同步改
- [ ] `table_structure_guard_test.gd:234-239`:删除「hobgoblin 留任随迁」断言块,替换为混编构成断言(R1–R4 四条,判据写在对照表)
- [ ] `round_flow_skill_pool_test.gd:567-578`:删 `"1_battle_3_hobgoblin": {"attack": 6, "charge": 2, "heavy": 2}`,改为 `"1_battle_3_bugbear": {"attack": 6, "charge": 2, "heavy": 2}` + `"1_battle_3_goblin": {"attack": 9, "lunge": 1, "desperate_guard": 1}`,行序按上表顺序
- [ ] `config_db_resolver_test.gd:40-46`:`_enemy_rows()` 里的 `"hobgoblin"` 换为 `"bugbear"`;`:56-78` 三条断言的期望串同步改(行序与落带语义不变)
- [ ] `config_db_test.gd:220-230`:`_test_rowset_discipline()` 的「不相邻」样本 `"hobgoblin"` 换为 `"giant_spider"`
- [ ] `damage_controller_test.gd:413` 与 `battle_narrator_test.gd:114`:注释由「depth 3 = hobgoblin 行集」改为「depth 3 = 混编行集(熊地精 1 + 地精 1–2,最少 2 只)」;断言逻辑零改动
- [ ] `tools/doc_term_audit.py:144`:注释里的敌种枚举去掉 hobgoblin
- [ ] 回读:`grep -rn "hobgoblin" game/ tools/` 输出为空
### T3 · 产出物落位(估时 0.5 日)
取用:T2 的八条断言全绿。产出:两份报告。
- [ ] 写 `reports/iter<N>-实现报告-<日期>.md`:各卡状态、实机目检总清单(L1 节点 3 混编三项,抄自 `体验验证清单.md` ⑱)、遗留读数义务(Alpha 零读数、读数归数值统一修正批)、实现决定记录
- [ ] 写 `reports/iter<N>-反哺点-<日期>.md`:按第六节同步面逐条落点(预计零条,也写「零条」)
- [ ] 核对 `game/tests/README.md` 能力表:用例函数名未变则可零动作;变了回表
估时合计 2 个工作日。
## 十二、验证闸(改动—验收对照表)
| 行 | 需求点 | 改动(文件:行/行为) | 验收测试(名称+落点+尾缀) | 层级 | 真实入口 | 判据绑定面 | 能力行 |
|---|---|---|---|---|---|---|---|
| R1 | 行数与键序 | `enemy.tres:82-105` 一行换两行 | `table_structure_guard_test.gd:_smoke_enemy_bands`「敌人表 29 行且键序 = 覆盖表序((1,3) 两行相邻、熊地精在前)」〔L1混编 v1〕 | 单元 | `ConfigDb.load_tables()` → `EnemyTable.rows` | 遍历 rows 拼「关卡、行类、深度带、敌种」四段串逐行比对期望串 | 既有:表结构守卫:域校验/行序键/跨字段互锁/配额锚 |
| R2 | 混编构成(两行同带键、敌种唯一) | 同上 | 同函数「(1,3) 行集恰两行且 enemy_id = {bugbear, goblin} 无重复」〔L1混编 v2〕 | 单元 | `ConfigDbResolver.resolve_rowset(1,3,"battle")` | 返回数组长度与 enemy_id 序列 | 既有:行集寻址、行序保序与难度乘数 clamp |
| R3 | 静态最坏骰和 ≤ 4 | 同上 | 同函数「(1,3) Σ(unit_count_max,固定行缺省 unit_count) = 3 ≤ 4」〔L1混编 v3〕 | 单元 | 同上 | 求和值与上限常量比较 | 既有:表结构守卫:域校验/行序键/跨字段互锁/配额锚 |
| R4 | 行值整行复用(零数值新增) | 同上 | 同函数「(1,3) 两行行值逐字段 == (1,2) 与 (1,0) 行(hp/atk 区间/池/ac/armor_type/attack_type)」〔L1混编 v4〕 | 单元 | `EnemyTable.rows` | 两行字段逐项比对,不写死数值字面量 | 既有:表结构守卫:域校验/行序键/跨字段互锁/配额锚 |
| R5 | 双池各自独立 | 同上 | `round_flow_skill_pool_test.gd:_smoke_skill_pool_data`「(1,3) 两行池模板 = 熊地精池 attack6/charge2/heavy2 与地精池 attack9/lunge1/desperate_guard1」 | 单元 | 同上 | 断言表的键与权重逐项 | 既有:技能池数据面与回放独立 |
| R6 | depth 3 落到混编且最少 2 敌 | 同上 | `damage_controller_test.gd:_test_pool_consumption_per_unit` 前置「行集 ≥2 敌」+ `battle_narrator_test.gd:_test_snapshot_effects_per_unit` 前置「≥2 敌」在混编下仍绿 | 单元 | `UnitContainer.spawn({"level_index":1,"node_depth":3})` | 生成后 `all_enemies().size() ≥ 2` | 既有:敌方增益自体落点与乘区池按个体 |
| R7 | 夹具不依赖已退役 id | 三个夹具文件改 id | `config_db_resolver_test.gd:_test_band_hit` / `_test_rowset_order_preserved` / `_test_top_band_clamp` / `config_db_test.gd:_test_rowset_discipline` 全绿 | 单元 | 合成表 → `validate()` / `resolve_*()` | 错误类别与返回序列 | 既有:行集寻址、行序保序与难度乘数 clamp;既有:表结构守卫:域校验/行序键/跨字段互锁/配额锚 |
| R8 | 全仓零 hobgoblin 残留 | 表与六处测试与注释 | `table_structure_guard_test.gd` 补「表内 enemy_id 无 hobgoblin」断言(并入 `_smoke_enemy_bands`)+ T1/T2 的 grep 回读 | 单元 | `EnemyTable.rows` 遍历 | 集合不含该字符串 | 既有:表结构守卫:域校验/行序键/跨字段互锁/配额锚 |
**测试削弱申报**:R8 删除了一条旧断言(`table_structure_guard_test.gd:234-239`「hobgoblin 留任随迁」)——该断言钉的是一个已退役事实,删除理由=对象不存在。除此外本批不删任何断言、不放宽阈值、不缩小扫描面。
**判据绑定面说明**:本批全部判据绑在表数据与解析返回序列上(数据改动的可观测提交面),不做注入破坏或回退取证(`process-conventions` §3 第 14 条口径);R1–R4 的期望值从同表既有行推导,不写死字面量,避免与表双写。
**独立验收审计**:入口=未参与本卡实现的会话或子代理,按上表逐行复核(判据是否绑在被改动的表数据与解析序列上、真实入口是否绕过改动点);报告文件 `reports/iter<N>-验收审计-<日期>.md`;未过不得合并。
**闸口径**:本批改动含 `game/` 下行为载体,按域选档由闸脚本判定(卡内不列闸件名单)。里程碑出口跑一次全套;波内修复只做出红最小单元的最窄确认。
## 十三、异常分级
- L1 自救:缩进/格式/语法类错误,直接改到绿。
- L2 记录继续:某条断言在不改设计的前提下换写法仍能表达同一判据(例如求和断言改写循环形式),记入实现报告「实现决定记录」。
- L3 停机呈报:① 混编后 `spawn` 抛行集越域警告(静态骰和算错或别处也改了表);② 需要改数值才能过闸;③ 出现卡内没写的第七个引用点;④ 机检预算互斥(本批零新增件,若出现即判上游缺陷,停卡退回写卡段)。
## 十四、代拍板白名单
1. 断言函数内的循环写法、局部变量命名、断言文案措辞。
2. 表注改写后的行文措辞(须保留日期 2026-11-04 与「用户裁」字样)。
3. `expect_keys` 数组的换行排版。
4. 注释改述的字面(不改语义)。
超清单必呈报。
## 十五、待裁点
**零待裁点**,开工门=用户发令 U0。已裁记录:① 数量与行值(1/2/3 项)用户 2026-11-04 委托取定,本卡按「地精 1–2 + 熊地精 1、行值整行复用、熊地精在前」写入;② L1 首见混编用户 2026-11-04 判「无阻碍、可接受」;③ Alpha 零读数用户 2026-11-04 裁「先机制与内容填充,数值统一后修」,已落 `process-conventions` §3 第 5 条。
+2 -2
View File
@@ -4,11 +4,11 @@
#### L1 深度 3 改地精+熊地精混编(大地精数据行退役)(2026-11-04 登记,来源=会话提及)
**实况**:关联文档清单——[敌人系统](design/gdd/systems/战斗循环/敌人系统.md) v1.6(hobgoblin 缺口登记整块删除,敌种表维持八种)· [难度曲线与Boss](design/gdd/systems/冒险循环/难度曲线与Boss.md) v1.3(混编投放记录与 Alpha 读数义务口径)· [08-Alpha版本标准](design/gdd/08-Alpha版本标准.md) v1.26(混编遭遇行集状态行补第二行)· [流程规范](design/engineering/process-conventions.md) §3 第 5 条(Alpha 阶段零读数口径,2026-11-04 用户裁)· [体验验证清单](体验验证清单.md) ⑱(目检范围扩至 L1 节点 3)。事项来由与设计定值:用户 2026-11-04 裁不做大地精敌种,原「hobgoblin 内容三件套补齐」条目同批删除;(1, battle, 3) 改双行混编,行值整行复用 (1, battle, 2) 熊地精(1 只 / hp22 / ac2)与 (1, battle, 0) 地精(1–2 只 / hp8 / ac0),行序熊地精在前(默认单体目标与开战叙述取首行),静态最坏骰和 1+2=3,Alpha 阶段零读数。
**实况**:关联文档清单——[敌人系统](design/gdd/systems/战斗循环/敌人系统.md) v1.6(hobgoblin 缺口登记整块删除,敌种表维持八种)· [难度曲线与Boss](design/gdd/systems/冒险循环/难度曲线与Boss.md) v1.3(混编投放记录与 Alpha 读数义务口径)· [08-Alpha版本标准](design/gdd/08-Alpha版本标准.md) v1.26(混编遭遇行集状态行补第二行)· [流程规范](design/engineering/process-conventions.md) §3 第 5 条(Alpha 阶段零读数口径,2026-11-04 用户裁)· [体验验证清单](体验验证清单.md) ⑱(目检范围扩至 L1 节点 3)· 需求卡片 [需求卡片-L1深度3混编](reports/需求卡片-L1深度3混编-2026-11-04.md)(2026-11-04 写卡,八条验收断言 R1–R8、零待裁点)。事项来由与设计定值:用户 2026-11-04 裁不做大地精敌种,原「hobgoblin 内容三件套补齐」条目同批删除;(1, battle, 3) 改双行混编,行值整行复用 (1, battle, 2) 熊地精(1 只 / hp22 / ac2)与 (1, battle, 0) 地精(1–2 只 / hp8 / ac0),行序熊地精在前(默认单体目标与开战叙述取首行),静态最坏骰和 1+2=3,Alpha 阶段零读数。
**改动面**:文档+游戏代码+工具代码
**状态**:文档设计已闭合+待写卡
**状态**:文档设计已闭合+已写卡
#### 架构审查余项——闸面缺口、豁免存废、零测试点名与架构文档漂移(2026-11-03 登记,来源=批次移交)