写卡(EffectPort蓄力层删键批): 卡v1.0——biz_fact五键收窄四键+蓄力层账本/转蓄分支/charge_full/词表两位+注释15处一次清退; 现状考证补全(transfer形态无执行体·transfer=true零测试·effect_port_test无charge_layers直接断言→验收改V4宿主应答null新断言; treasure_effects_test三处调用签名适配断言值零变已申报); 蓄力周转/敌方蓄力/RAP三域零触碰红线+MC零跑; 零待裁点开工门=grilling+用户裁决+编迭代(单卡≈1.0工作日待凑批); 待办条目推进已写卡; pipeline_gate PASS

This commit is contained in:
DKChan committed 2026-11-04 00:58:58 +08:00
1 parent ce3a86a989
commit 5be1ebd47e
2 files changed
+177 -2

No files matched your search

@@ -0,0 +1,173 @@
# 需求卡片:EffectPort 蓄力层删键批
> 来源:待办清单「EffectPort biz_fact 键 charge_layers——无属主数据游离出领域实体的处置」(2026-11-02 登记,来源=审计发现;需求性工程条目,证据指认在条目实况)。**唯一事实源:该条目实况所引证据链+本卡「现状事实」节代码级考证(2026-11-04 全部实查复核)。**
> 裁决沿革:删除方向 2026-11-02 用户裁(总判据「机制数据一律长在所属封装实体的内部属性(表行字段)里,全局常量与无主账本清零」);2026-11-04 本会话全仓考证确认死代码(零内容消费面)后用户发令删除。
> 版本:v1.0(2026-11-04)
## 1. 目标与完成定义
把 `charge_layers`(玩家侧蓄力层)这条从未运转的死链整链退役:
- biz_fact 闭面五键收窄为四键(charge_layers/dig_streak/hp_ratio/rider_tier_bonus/rider_tier_crit → 后四键);
- 行动经济侧蓄力层账本、上限常量、转蓄分支、`charge_full` 事件发射全部删除;`finish_round_stop` 签名简化为纯 RAP 转存;
- 效果引擎两词表位(事件 `charge_full`、事实 `charge_layers`)退役;
- 代码注释里引用退役专长名(整备军备/铁壁整备/厚积薄发)与蓄力层的全部残留句清零。
**完成定义**:`game/` 下除 `swap_charge_layers` 计数器域(蓄力周转专长,在役另物)外,「蓄力层」概念零残留(grep 判据见 T1);两套件既有断言全绿+本卡新断言绿;`--code` 域全套闸绿;RAP 转存读数逐位零漂移。
## 2. 设计事实源
需求性工程条目(删死码,无设计线):设计事实源=**证据指认**——待办清单条目实况证据链(`reports/审计-全库架构审查-2026-10-29.md` §3.1 B 类第 2 行+`game/core/effect_port.gd:4`+`game/core/action_economy.gd:14/37/203`)+本卡第 3 节 2026-11-04 代码级复核(file:line 逐条实查)。
## 3. 现状事实(2026-11-04 代码级考证)
死链判据——入口死、出口假想、内容零注册三面同时成立:
1. **入口死**:账本唯一写点=「停手转蓄力」分支(`game/core/action_economy.gd:202-205`),触发条件=效果表有行注册 `grant_ap(mode:transfer)`(`game/core/settlement/grant_segment.gd:281` 经 `has_effect_on` 查询);全仓 `.tres` 零命中(feats.tres 三条 grant_ap 行 :46/:284/:719、treasure_items.tres 两条 :38/:150,全无 transfer)。transfer 形态无执行体——唯一读点就是这条存在性查询(`game/core/effect_engine.gd:203/461/467` 三处注释句为仅余痕迹)。
2. **出口假想**:消费面「厚积薄发/整备军备/铁壁按层缩放」只存在于 `game/core/damage_controller.gd:271/338/352/433` 四处注释;三名词=2026-10-08 退役旧专长(armory_prep/iron_wall/patient_burst,`design/content-archive/道具退役素材库.md:53-55`),GDD 与专长表零行。
3. **满层事件无订阅**:`charge_full` 发射(`action_economy.gd:205`)自注「现无订阅者」(:199);`game/core/effect_engine.gd:14` 事件词表位在册。
4. **transfer=true 分支零测试**:全仓仅 `game/tests/unit/core/treasure_effects_test.gd:132/138/144` 三处调用 `finish_round_stop(false, …)`(RAP 转存态)。
5. **RAP 转存=在役正路**:术语表.md:34-35(RAP 词条与停手/转存率词条)、行动经济.md:80-82(停手整节)、`game/tests/README.md:123`(「停手转存储备与轮内刷新」能力行)。
残留面全清单(13 处+词表注释 3 处,处置见 T 卡):
| # | 文件:行 | 残留 |
|---|---|---|
| 1 | `game/core/action_economy.gd:14` | `CHARGE_LAYER_CAP := 3` 常量 |
| 2 | `game/core/action_economy.gd:35-43` | 蓄力流注释块+`_charge_layers` 账本+`charge_layers` getter |
| 3 | `game/core/action_economy.gd:168` | 「转蓄力层替代 RAP 转存」注释句 |
| 4 | `game/core/action_economy.gd:196-205` | `finish_round_stop` transfer 分支+`charge_full` 发射 |
| 5 | `game/core/effect_port.gd:4-5` | 闭面五键声明 |
| 6 | `game/core/effect_engine.gd:14` | EVENTS 词表 `charge_full` 位 |
| 7 | `game/core/effect_engine.gd:59` | FACTS 词表 `charge_layers` 位 |
| 8 | `game/core/effect_engine.gd:203/461/467` | transfer 订阅查询与族分类注释句三处 |
| 9 | `game/core/battle_fx_host.gd:2/37` | 头注与 facts_inject 注释句 |
| 10 | `game/core/battle_fx_host.gd:92-98/219-223` | charge_layers 应答分支两处(读 `action_economy.charge_layers`) |
| 11 | `game/core/battle_orchestrator.gd:113` | 「charge_layers 归 fx_host 自答」注释句 |
| 12 | `game/core/damage_controller.gd:271/338/352/433` | 退役专长名注释四处 |
| 13 | `game/core/settlement/grant_segment.gd:262/279-282` | 「整备转蓄力」注释+`has_effect_on(…,"transfer")` 判定入参 |
| 14 | `game/core/settlement/combat_segment.gd:35-36` | 蓄力层注释 |
| 15 | `game/tests/unit/battle_settlement/effect_port_test.gd:16/57/103` | 注释把在役蓄力周转计数器误标为「整备军备蓄力层」、把合成对照行说成「现役铁壁」 |
## 4. 设计契约(🔴 违反即 L3 停机呈报)
1. 🔴 **RAP 转存路径逐位零变化**——`finish_round_stop` 的 RAP 分支、`transfer_pct` 通道、`rap_transfer_mult`(储备罐 125=1.25:1)读数逐位不动;`treasure_effects_test` 既有断言期望值零变化(仅调用签名适配,见第 8 节申报)。
2. 🔴 **蓄力周转专长域零触碰**——`feats.tres:1007-1056`(swap_charge_layers 计数器行)、`refresh_feats_test.gd` V8 全组、`game/tests/README.md:126` 能力行、GDD 战斗结算.md:278 与奇物.md:109 行,全部不动。
3. 🔴 **敌方蓄力域零触碰**——empower 增益技(status_effects.tres)、敌方节点级蓄力层(01-核心循环.md:79/88)、音频.md 蓄力拍等 GDD 行,全部不动;术语表**不新增**任何「蓄力」词条。
4. 🔴 **biz_fact 闭面只收窄不扩**——四键为终态,禁顺手加新键;未绑缺省与未知事实回落 null 语义不变(fail-fast 既有机制零回归)。
5. 🔴 **禁保留无效成员**——禁兼容别名、空 getter、词表空位、恒 false 分支、注释式「以后要用」存根;机检键与本卡契约互斥时停卡呈报,禁自造第三条路。
6. 🔴 **实现批禁写 `design/` 整个目录与根规则文件**——architecture.md 两处(:124/:146)走反哺点清单由文档批落文。
7. 🔴 **MC/模拟零跑**——本批无数值改动(死码删除零表值触面)。
8. 🔴 **车道铁律**——实现走独立 worktree,主区只作合并落点。
## 5. 范围边界
**做**:上表 15 处残留一次清完+两处测试适配+1 条新断言。
**不做**:
- `test_charge_layers_consumed_same_round` 函数**不改名**——它是 swap_charge_layers(蓄力周转)测试,函数名属该计数器域;且 README:126 能力行代表用例名锚定此名,实现批禁写 README。
- 蓄力周转、敌方蓄力、RAP/转存率任何面(契约 1–3)。
- 蓄力周转测试面牵连核对结论:`refresh_feats_test` V8 组全部经效果引擎计数器域运行,不触 `action_economy.charge_layers`(全仓 grep 已证)——零牵连,无需同批改动。
**明示不收件的去向**:无——单链清退一次做完,无拆尾。
## 6. 关联文档同步面
| 文档 | 关联点(本批实现会改变它的哪条陈述) | 同步义务 |
|---|---|---|
| `design/engineering/architecture/architecture.md` | :124(BattleFxHost 行「A3 action_economy(queue_ap_delta/charge_layers 读)」依赖句);:146(轴戊 EffectPort 句「闭面五键」与「facts 取值束 dig_streak/charge_layers/rider_tier_*」) | 实现批禁写——逐条登记进 `reports/iter<N>-反哺点-<日期>.md`,由用户裁决后归文档批改四键、删读依赖句 |
| `game/tests/README.md` | :88 能力行「效果发射端口单点」代表用例 `_test_biz_fact_face_closed` | 实现批禁写——计划函数名不变,批末收尾核对名实一致;若实现改名则回表(记反哺点) |
| 待办清单 | 本条目状态(写卡段→已写卡;实现完成→整条删除) | 状态推进由流水线各段承载,实现批不碰 |
| 术语表/GDD 各系统文档 | 零关联(敌方蓄力/蓄力周转/RAP 各行不受影响) | 无同步义务 |
## 7. 任务卡
**卡前文件结构图**(本批零新增文件;改动文件 9+测试 2,全部「非行为改动/行为改动」已标):
| 文件 | 职责与改动 | 行为改动 |
|---|---|---|
| `game/core/action_economy.gd` | 删常量/账本/getter/transfer 分支;`finish_round_stop` 签名简化;注释两处清 | 是(对照表行 2) |
| `game/core/settlement/grant_segment.gd` | 调用简化(删 has_effect_on 入参)+注释清 | 是(对照表行 2) |
| `game/core/effect_engine.gd` | EVENTS/FACTS 删位+注释三处清 | 是(对照表行 3) |
| `game/core/battle_fx_host.gd` | 应答分支两处删+头注/注释清 | 是(对照表行 1) |
| `game/core/effect_port.gd` | 闭面五键句改四键 | 否(注释) |
| `game/core/battle_orchestrator.gd` | 注释句清 | 否(注释) |
| `game/core/settlement/combat_segment.gd` | 注释清 | 否(注释) |
| `game/core/damage_controller.gd` | 退役专长名注释四处清 | 否(注释) |
| `game/tests/unit/battle_settlement/effect_port_test.gd` | 新断言+误标注释三处清 | 是(对照表行 1) |
| `game/tests/unit/core/treasure_effects_test.gd` | 三处调用签名适配(断言值零变化) | 否(适配,申报见第 8 节) |
### T0 契约收窄原子批(≈0.625 工作日)
> 九文件一次改完——`battle_fx_host.gd:98/223` 读 `action_economy.charge_layers`,拆卡必产生不可编译中间态,故同卡原子交付。
- [ ] `action_economy.gd`:删 :14 常量、:35-43 账本块(`_charge_layers`/getter/注释)、:168 句;`finish_round_stop` 改签名 `func finish_round_stop(transfer_pct: int = 100) -> void`,体只留 RAP 转存行 `_rap += _last_stop_ap * maxi(1, transfer_pct) / 100` 与 `_last_stop_ap = 0`;:196-199 注释改写为纯 RAP 转存口径(禁残留 transfer/charge_full 字样)
- [ ] `grant_segment.gd`::281-282 调用改 `oc.action_economy.finish_round_stop(rap_pct if rap_pct > 0 else 100)`;:262 注释删「整备转蓄力」句(保留 round_end 其余语义句)
- [ ] `effect_engine.gd`:EVENTS 删 `"charge_full"` 位(:14)、FACTS 删 `"charge_layers"` 位(:59);:203 句改「发射点缺省行为仲裁用——round_end 走 RAP 转存」、:461/:467 删「grant_ap(mode:transfer)」字样(族分类句同步改写)
- [ ] `battle_fx_host.gd`:删 :92-98 与 :219-223 两处 charge_layers 分支(`biz_fact`/补充事实面走既有「未知事实回落 null」末行);:2 头注「charge_layers 自答,余五事实转宿主」改「余事实转宿主」口径;:37 注释删 charge_layers 句
- [ ] `effect_port.gd`::4-5 闭面句改四键(dig_streak/hp_ratio/rider_tier_bonus/rider_tier_crit)
- [ ] `battle_orchestrator.gd:113`:注释删「charge_layers 归 fx_host 自答」句
- [ ] `combat_segment.gd:35-36`:注释改写(删蓄力层句,保留端口闭面语义句)
- [ ] `effect_port_test.gd`:V3 组 `_test_biz_fact_face_closed` 末尾增断言——经 `begin_battle` 真实装配链取宿主 `biz_fact("charge_layers")`,`Kit.check("V4 闭面收窄:charge_layers 键退役——宿主事实应答 null", orch.fx_host().biz_fact("charge_layers") == null)`(print 标签文案可代拍板)
- [ ] `treasure_effects_test.gd:132/138/144`:三处调用改单参 `finish_round_stop(100)`/`finish_round_stop(125)`/`finish_round_stop(125)`(断言期望值逐字不动)
- [ ] 孤立验证:`…console.exe --script res://tests/run_all.gd` 单测域全绿(重点 effect_port_test/treasure_effects_test/refresh_feats_test 三套件)
### T1 注释清尾与零残留核验(≈0.25 工作日)
- [ ] `damage_controller.gd:271/338/352/433`:四处退役专长名注释删或改写为现状口径(禁残留整备军备/铁壁/厚积薄发/charge_layers 字样;:433 行剩余的 shield 订阅面注释主体保留,只删按层缩放句)
- [ ] `effect_port_test.gd:16/57/103`:三处误标注释改写——:16 改「蓄力周转计数器(feats.tres swap_charge_layers 行)」、:57/:103 删「整备军备/铁壁」字样改现状描述
- [ ] 零残留判据:`grep -rn "charge_layers\|charge_full\|CHARGE_LAYER\|蓄力层\|转蓄力\|厚积薄发\|铁壁\|整备军备" game/ --include="*.gd" --include="*.tres"` 除 `swap_charge_layers` 域(`refresh_feats_test.gd` 函数名 `test_charge_layers_consumed_same_round` 与 `feats.tres` swap 行)外零命中
- [ ] S13 核对:`action_economy.gd` 类变量数较登记值只降不升(删 `_charge_layers` 后预期 10→9);其余触面同判据
- [ ] 里程碑步出口:`tools/run_all_gates.sh --code` 全绿
### T2 产出物落位卡(≈0.125 工作日)
- [ ] `reports/iter<N>-实现报告-<日期>.md`:各卡状态+实现决定记录+测试削弱申报执行情况+实机目检总清单(本批无玩家可观测变化——登记「无实机目检项」并写明死码删除零提交面)
- [ ] `reports/iter<N>-反哺点-<日期>.md`:architecture.md :124/:146 两条逐条落点
- [ ] 待办清单条目整条删除归收尾段(实现批不碰)
## 8. 验证闸(改动—验收对照表)
| # | 需求点 | 改动(文件:行/行为) | 验收测试(名称+落点+尾缀) | 层级 | 真实入口 | 判据绑定面 | 能力行 |
|---|---|---|---|---|---|---|---|
| 1 | 事实应答面收窄——charge_layers 键退役 | `battle_fx_host.gd:92-98/219-223` 两分支删 | `effect_port_test.gd` V3 组新增「V4 闭面收窄:charge_layers 键退役——宿主事实应答 null」 | 接口(单元) | `BattleOrchestrator.begin_battle()` 真实装配链(端口接线后取宿主 biz_fact) | 宿主事实应答 null 化=本批特有提交面(键在→返 0,键退役→null) | 既有:效果发射端口单点 |
| 2 | 蓄力层账本与转蓄分支退役、签名简化 | `action_economy.gd:14/35-43/168/196-205`+`grant_segment.gd:262/281` | `treasure_effects_test.gd` 既有断言三处全绿(停手 1:1 与储备罐 1.25:1 两态读数零变) | 单元 | 真实停手路径 `request_stop()`→`round_end`→`finish_round_stop` | RAP 转存既有读数零漂移(行为零变化回归锚) | 既有:停手转存储备与轮内刷新(上限/AP 不重置/刷新图零清图奖励) |
| 3 | 事件/事实两词表位退役 | `effect_engine.gd:14/59` 删位 | 静态判据:T1 零残留 grep 词表零位+`--code` 域全套闸绿 | 静态+单元 | —(词表为常量面) | 静态判据+评审注记:词表位删除无独立运行期提交面(加载期 fail-fast 校验为既有机制,非本批新增) | 既有:效果发射端口单点 |
**测试方式两分法**:本批全部归调试接口验证(单元/接口断言);**无用户目检项**——死码删除零玩家可观测提交面(实现报告登记「无实机目检项」并写明缘由)。
**测试削弱申报**:`treasure_effects_test.gd:132/138/144` 三处调用实参 `(false, 100/125/125)` → `(100/125/125)`——签名适配,断言期望值与检查语义逐字零变化;无断言删除、无阈值放宽、无扫描面缩小。
**独立验收审计**:`reports/iter<N>-验收审计-<日期>.md`,由未参与实现的会话或子代理执行,未过不得合并(test-conventions §8.7)。
**回归措辞**:里程碑步(T1)出口跑一次 `--code` 域全套闸;卡内修复只做出红最小单元的最窄确认;新断言先行孤立验证再并入全套。
## 9. 异常分级
- **L1 自救**:注释改写笔误、grep 白名单笔误、print 标签文案。
- **L2 记录继续**:注释改写措辞超出删除语义的级微调(记录进实现报告「实现决定记录」)。
- **L3 停机呈报**:①删除时发现任何现役表行/效果规格/内容件引用 `charge_layers`/`charge_full`/transfer 订阅(与「零内容件」考证矛盾=上游考证缺陷,停卡退回写卡段);②S13 键上升;③全套闸红不可最小单元收敛;④机检键与本卡契约互斥(含 static_scan 计数文本冲突——禁改闸件豁免);⑤实测发现 `biz_fact("charge_layers")` 在四键终态下不返 null(宿主回落语义与考证不符)。
## 10. 代拍板白名单
1. 注释改写的具体措辞(保持原注释密度与风格,语义=删除后现状)。
2. V4 断言的 print 标签文案。
3. 删除后空行/排版微调。
4. `treasure_effects_test` 三处实参写法跟随文件内既有风格(字面 100/125)。
## 11. 待裁点
零待裁点——删除方向 2026-11-02 用户裁、2026-11-04 死代码确认后发令。开工门=本卡经 grilling 复核+用户裁决+迭代编排(编入迭代批次,注意单卡 ≈1.0 工作日,迭代估时总量 <5 工作日=冻结待凑批)。
## 12. 落位与可复用性预检
- **复用面**:零新增件——验收断言复用 `effect_port_test.gd` V3 闭面组既有结构(同函数内追加,不新增文件/套件);删码批无「不能复用既有件」问题。
- **唯一面**:删除不产生第二落点;grep 同名核查已证 `swap_charge_layers`(在役)与 `charge_layers`(退役)是两个标识符域,删除不触碰前者。
- **分层与交互面**:删除面全在 core/settlement 内部与两测试件;效果端口六 Callable 束契约(bind_port 组装期注入)不变;Core 层零 UI 依赖不因删除面新增绕行;无数值表触面。
## 13. 禁为机检文本保留无效成员
🔴 适用:禁为迎合机检消息文本(含派生计数、S13 键值)保留或新增无效成员/别名/空位;机检键与本卡契约互斥时实现段一律停卡呈报,不得自造第三条路。
## 14. 实现规范预算
零新增文件——三查不适用。存量触面预期:`action_economy.gd` 类变量数只降不升(删 `_charge_layers`,预期 10→9);`battle_fx_host.gd` 分支删除成员数不变;其余触面仅注释行。全部触面 S13 键较登记值只降不升(T1 核对步骤承载)。
## 15. 拆分边界纪律
本卡为删除类(非拆分/收敛类),无拆出单元。红线:禁为凑指标或摊薄审查把同链残留拆多批留尾——15 处残留同链一次清完(T0/T1 的切分是审查门粒度,非范围拆分;T0 九文件原子性由编译依赖承载,见 T0 卡头注)。
+4 -2
View File
@@ -311,11 +311,13 @@
#### EffectPort biz_fact 键 charge_layers——无属主数据游离出领域实体的处置(2026-11-02 登记,来源=审计发现)
**实况**:证据=reports/审计-全库架构审查-2026-10-29.md §3.1 B 类第 2 行(`CHARGE_LAYER_CAP` 自标「机制结构常量」)+`game/core/effect_port.gd:4`(biz_fact 闭面五键声明)+`game/core/action_economy.gd:14/37/203`(常量、`_charge_layers` 裸账本、transfer 分支唯一写点)。2026-11-02 架构审查讨论逐键核闭面:其余四键各有领域实体持有数据(hp_ratio=主角生命、dig_streak=战斗轮次事实、rider_tier 两键=每战复位的战斗事实束),唯 charge_layers 背后是 action_economy 裸账本——全仓零内容件注册「停手转蓄力」订阅(.tres 零命中),damage_controller 三处「厚积薄发/铁壁按层缩放」仅存于代码注释描述的假想订阅面,无任何表行或效果规格实际消费。用户裁决=删除方向,总判据「机制数据一律长在所属封装实体的内部属性(表行字段)里,全局常量与无主账本清零」。处置范围:①闭面五键收窄为四键(charge_layers 键退役、effect_port_test 对应断言同改——触及迭代 49 卡①刚立的端口契约,卡内申报契约改动);②`_charge_layers` 账本、`finish_round_stop` transfer 分支、`charge_full` 事件位、`CHARGE_LAYER_CAP` 常量随键退役;③蓄力周转专长(feats.tres swap_charge_layers 计数器,文档口径「成功刷新攒层」与实现一致)不受影响,写卡时核对其测试面无牵连。
**实况**:证据=reports/审计-全库架构审查-2026-10-29.md §3.1 B 类第 2 行(`CHARGE_LAYER_CAP` 自标「机制结构常量」)+`game/core/effect_port.gd:4`(biz_fact 闭面五键声明)+`game/core/action_economy.gd:14/37/203`(常量、`_charge_layers` 裸账本、transfer 分支唯一写点)。
需求卡片 reports/需求卡片-EffectPort蓄力层删键批-2026-11-04.md(2026-11-04,v1.0——写卡段代码级复核补全残留面 15 处与词表注释 3 处、transfer 形态无执行体考证、transfer=true 零测试考证;新增考证修正=effect_port_test 实测无 charge_layers 直接断言,V3 闭面组用 hp_ratio/battle_index 两对照行,故验收断言改为 V4「宿主 biz_fact 应答 null」新断言)。2026-11-02 架构审查讨论逐键核闭面:其余四键各有领域实体持有数据(hp_ratio=主角生命、dig_streak=战斗轮次事实、rider_tier 两键=每战复位的战斗事实束),唯 charge_layers 背后是 action_economy 裸账本——全仓零内容件注册「停手转蓄力」订阅(.tres 零命中),damage_controller 三处「厚积薄发/铁壁按层缩放」仅存于代码注释描述的假想订阅面,无任何表行或效果规格实际消费。用户裁决=删除方向,总判据「机制数据一律长在所属封装实体的内部属性(表行字段)里,全局常量与无主账本清零」。处置范围:①闭面五键收窄为四键(charge_layers 键退役、effect_port_test 对应断言同改——触及迭代 49 卡①刚立的端口契约,卡内申报契约改动);②`_charge_layers` 账本、`finish_round_stop` transfer 分支、`charge_full` 事件位、`CHARGE_LAYER_CAP` 常量随键退役;③蓄力周转专长(feats.tres swap_charge_layers 计数器,文档口径「成功刷新攒层」与实现一致)不受影响,写卡时核对其测试面无牵连。
**改动面**:游戏代码
**状态**:待写卡
**状态**:已写卡
#### 主角棋盘小人像素管线重产——原「美术资产链路审计两项 P0」之 P0②(2026-10-09 登记,来源=审计发现)