文档设计(架构审查5.1封装修复·用户裁): 设计讨论结论落档两交付——①处置记录 reports/处置-架构审查5.1封装修复-2026-11-03.md(总判据六条/根因定稿三无叠加/普查五处 core 105行107处19符号+presentation 227行出卡/逐项裁决记录/19符号行为归属总表/架构锚点; 接收方=需求卡片-架构审查5.1封装修复-2026-11-03.md+待办清单架构审查优化讨论条目, 卡片成立即退役); ②code-conventions.md 新增 §1.6 拆分交接与封装边界(条一拆分交接定义=职责边界+交接定义双齐备才算拆分合格, 先例=BoardInstaller 引用束注入; 条二封装边界=跨对象禁访问下划线成员只走公开面)——本批修复与后续闸件共同依据; GDD 零改动; 文档域闸全绿(8闸 all_green)
This commit is contained in:
DKChan committed
1 parent
6261b36ecd
commit
3be3f3e7c1
2 files changed
+99
No files matched your search
@@ -34,6 +34,12 @@
|
||||
### 1.5 禁止事实约定
|
||||
任何"大家默认这么做"的惯例必须成文进本文件（或 AGENTS.md）才算存在。写代码时发现未成文但必须遵守的约定 → 当场补条文，不许靠惯性延续。
|
||||
|
||||
### 1.6 拆分交接与封装边界
|
||||
本节管拆分类改动的交接面与封装面，与 §1.1 拆分判据（职责轴）配合使用：§1.1 管怎么切，本节管切完之后件与件之间怎么往来。
|
||||
|
||||
1. **拆分交接定义**：拆出一个新类时，交付物必须同时写明职责边界与交接定义——新类构造时需要哪些依赖，由拆出它的类在构造它时一次交给它；新类需要回调拆出它的类的哪些方法，以 Callable 形式交付。两者齐备才算拆分合格。为什么：只切职责不定义交接，新件会伸手回原类内部拿东西，封装从拆件那天起就破了。正面先例＝装板件的引用束注入（表数据、随机流、装板所需对象与出错回调一次性交付——架构文档「战斗编排域拆件定稿」节 BoardInstaller 行在册）。
|
||||
2. **封装边界**：任何代码不得访问其他对象的下划线成员；跨对象往来只走公开方法与属性。为什么：下划线只是命名约定，语言不设防、无编译期检查——此条是封装硬纪律，违者即红。
|
||||
|
||||
---
|
||||
|
||||
## 2. 契约纪律——跨层/跨类调用的语义
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
# 处置：架构审查 5.1 封装修复批（2026-11-03）
|
||||
|
||||
> **性质**：设计讨论段过程稿（裁决记录＋取证事实）。**接收方**＝reports/需求卡片-架构审查5.1封装修复-2026-11-03.md ＋ 待办清单条目「架构审查优化讨论——全库架构审计读数的逐条裁决与整改分批」（2026-10-29 登记）。**寿命**：需求卡片成立即退役（吸收即死——结论吸收进卡片与 code-conventions，未决迁待办清单）。
|
||||
> **输入**：reports/审计-全库架构审查-2026-10-29.md §5.1（settlement 五段类直读写编排器私有成员；讨论段把普查扩到全库同模式面）＋ 2026-11-03 讨论会话用户逐项裁决 ＋ 2026-11-03 会话取证（19 符号逐个核过、行号为当日现址——行号写卡段复核）。
|
||||
|
||||
## 一、总判据（用户 2026-11-03 裁，本批一切设计遵循）
|
||||
|
||||
1. **拆分判「错」的口径＝交付物缺交接**：拆分的完整交付物是一个独立的类，须同时含职责边界与交接定义——构造时拿到什么、回调原类什么、只经公开面往来。五次拆件五次不合格。
|
||||
2. **修复＝把五次拆件没做完的交接补完**：代码位置不动、职责归属零改动，只补构造交付与回调。
|
||||
3. **编排器保留面＝architecture.md:141 登记原样**（战斗状态机与生命周期、行发射基建 _emit_row/_assert_row_source/_fatal、呈现投影、刷新面、nest_preview_count），本批零增零减。
|
||||
4. **法律先于修复**：code-conventions 两条增补先落（＝§1.6 拆分交接定义＋封装边界，本批交付二），两条是本批修复与后续闸件的共同依据。
|
||||
5. **GDD 零改动**（零行为变更的设计讨论，不触任何系统规则）。
|
||||
6. **范围**：core 五处进卡（编入需求卡片）；presentation 层约 227 行出卡（不在本卡，冻结期内单开设计讨论——修法＝视图补公开设置方法、装配代码改走设置方法）；sim/probe/tests 出卡（测量面直构惯例＋测试受控例外）。
|
||||
|
||||
## 二、根因（定稿陈述）
|
||||
|
||||
拆件交付物只写了职责边界、没写交接定义——拆出的件没拿到它需要的东西，每次需要都变成伸手回原类内部。三层防护全部缺位，三无叠加：
|
||||
|
||||
- 语言层：GDScript 无访问修饰符，下划线纯命名约定；
|
||||
- 规约层：code-conventions 全文无跨对象访问条文（已核）；
|
||||
- 闸层：S1–S13 无此扫描。
|
||||
|
||||
局部每处合理（19 符号逐个核过全是正当需要），整体边界溶解：累计约 390 行、20+ 文件。
|
||||
|
||||
## 三、普查五处（core 层；2026-11-03 会话取证现址，行号写卡段复核）
|
||||
|
||||
1. **settlement 七段→编排器**：105 行／107 处／19 符号（七段＝五段段类＋round_cycle＋battle_refresh_flow）。分布＝grant_segment 54／combat_segment 23／round_cycle 10／verdict_segment 9／battle_refresh_flow 5／aura_segment 2／decay_segment 2。构成＝成员引用 72 处＋编排器方法 35 处（逐符号与修后归属见五、总表）。
|
||||
2. **adventure_runner→BreakpointStore**：37 行直读写（_pending_next_level、_loadout_seeded、_resume_bp、_save_manager、_last_level_payload、_last_treasure_cleared、_bp_read）——adventure_runner.gd:37 注释自述「宿主读写经件」未落实。
|
||||
3. **save_manager→SlotStore**：9 行（slots._path 直读写 ×8＋slots._migrate_legacy_save 私有方法调用；save_manager.gd:51/66/69/105/111/118-119/285-286）。
|
||||
4. **grant_segment→BattleFxHost**：6 行直写 _fx_new_resource_types（:82/:84）与 _fx_bonus_delta（:169-170/:378-379）。
|
||||
5. **config_db→三表容器**：3 行装配期写 _resolver（config_db.gd:157-159）。
|
||||
|
||||
presentation 层同模式约 227 行（抽样核实、未逐行判读）——出卡另议：
|
||||
|
||||
| 文件 | 行数 |
|
||||
|---|---|
|
||||
| level_map_screen | 87 |
|
||||
| main_ui_build | 70 |
|
||||
| main_adventure_flow | 25 |
|
||||
| standee_body | 16 |
|
||||
| main_overlay_flow | 15 |
|
||||
| main_debug_flow | 11 |
|
||||
| main_esc_flow | 2 |
|
||||
| board_view | 1 |
|
||||
|
||||
## 四、逐项裁决记录
|
||||
|
||||
| 项 | 裁决 |
|
||||
|---|---|
|
||||
| 方向＝补交接 | settlement 七段构造时收六个子对象引用（战斗事实 BattleFacts、单位容器 UnitContainer、伤害控制器 DamageController、奖励经济 RewardEconomy、状态容器 StatusContainer、效果宿主件 BattleFxHost）＋七个编排器方法回调（_emit_row、_fatal、_install_and_reset、_battle_over、_exit_distribution、_emit_settlement_snapshot、_emit_composition_effects，以 Callable 交付）＋段间引用（授予段引用直接交换——battle_refresh_flow 不再经编排器 _rounds 链式取授予段，改为直接持有授予段引用）；编排器公开读数（round_index、db、action_economy、battle_result）一并改注入；段类对编排器引用归零。 |
|
||||
| 搬家五方法 | _hero_atk→伤害域、_feat_yield_adjust→奖励域（奖励授予件）、_harmful_variants 与 _harmful_adjacent→地形棋盘域、_hits_of→伤害域。 |
|
||||
| verdict 轮推进保留 | verdict 段经 _exit_distribution 触发轮推进保留现设计（架构在册七段结构，battle_orchestrator 段序骨架冻结——architecture.md:119）。 |
|
||||
| battle_refresh_flow 同形 | battle_refresh_flow 同批同形改造（can_refresh／execute 两入口的 oc/self 入参一并改依赖交付）。 |
|
||||
| 其余三处补公开面 | BreakpointStore 补公开读写方法；SlotStore 补路径公开读取口与迁移方法（或序列化职责归位，写卡定形态）；BattleFxHost 补两个公开累积方法；表容器补 resolver 公开挂载方法。 |
|
||||
| S13 成员数约束 | 段类新增依赖受 gdstyle 成员阈值约束，依赖可经束成员持有（先例＝BoardInstaller 引用束注入——architecture.md:124「构造＝引用束注入」）。 |
|
||||
| 验证方式 | 同种子逐项比对（主证，手法先例＝3.1+3.2 卡 battle_driver_drive_test 动作序列快照）＋battle_settlement 套件全绿＋五搬家方法各配真实入口断言＋core 五处跨对象私取 grep 恒零（扫描面非空前置＋零命中）；对照表按「非行为改动＋零行为变更证明」登记；禁变异类测试、禁撤销类取证。 |
|
||||
| 排序 | 实现排队在 reports/需求卡片-架构审查3.1+3.2整改批-2026-11-02.md 之后（combat_segment 同文件避让——该卡甲案删 attack_segments 分支 :59-70）。 |
|
||||
| 估时域 | 2–3 个工作日（写卡期精估）。 |
|
||||
|
||||
## 五、19 符号行为归属总表（2026-11-03 会话取证）
|
||||
|
||||
| 符号 | 处数 | 现在长在哪 | 修后归属 | 段类修后怎么拿到 |
|
||||
|---|---|---|---|---|
|
||||
| _facts | 24 | 编排器成员（BattleFacts 件引用，battle_orchestrator.gd:38） | BattleFacts 件（战斗事实域，架构在册） | 构造注入 BattleFacts 引用（六子对象之一） |
|
||||
| _enemy_system | 22 | 编排器成员（UnitContainer 引用，battle_orchestrator.gd:48） | UnitContainer（B2 单位容器） | 构造注入 UnitContainer 引用 |
|
||||
| _damage | 18 | 编排器成员（DamageController 引用，battle_orchestrator.gd:51） | DamageController（伤害单据管线） | 构造注入 DamageController 引用 |
|
||||
| _reward_economy | 5 | 编排器成员（RewardEconomy 引用，battle_orchestrator.gd:50） | RewardEconomy（B4 奖励经济） | 构造注入 RewardEconomy 引用 |
|
||||
| _status_effects | 2 | 编排器成员（StatusContainer 引用，battle_orchestrator.gd:49） | StatusContainer（B3 状态容器） | 构造注入 StatusContainer 引用 |
|
||||
| _fx_host | 1 | 编排器成员（BattleFxHost 引用，battle_orchestrator.gd:52） | BattleFxHost（效果宿主件） | 构造注入 BattleFxHost 引用 |
|
||||
| _rounds._grant_seg（链式） | 1 | battle_refresh_flow.gd:42 经编排器 _rounds 链式取授予段成员 | 段间引用——授予段引用直接交换 | 组装期直接交付授予段引用，不再穿编排器 |
|
||||
| _emit_row | 16 | 编排器私有方法（行发射基建，架构在册保留面） | 留宿主（保留面登记原样，零增零减） | 构造注入 Callable（七回调之一） |
|
||||
| _hits_of | 5 | 编排器私有方法 | 搬家→伤害域 | 经注入的 DamageController 公开方法直调 |
|
||||
| _emit_composition_effects | 2 | 编排器私有方法 | 留宿主（保留面） | 构造注入 Callable |
|
||||
| _battle_over | 2 | 编排器私有方法（battle_result 状态机写点域） | 留宿主（保留面） | 构造注入 Callable |
|
||||
| _feat_yield_adjust | 2 | 编排器私有方法 | 搬家→奖励域（奖励授予件） | 经注入的奖励授予件公开方法直调 |
|
||||
| _fatal | 1 | 编排器私有方法（行发射基建族） | 留宿主（保留面） | 构造注入 Callable |
|
||||
| _hero_atk | 1 | 编排器私有方法 | 搬家→伤害域 | 经注入的 DamageController 公开方法直调 |
|
||||
| _harmful_variants | 1 | 编排器私有方法 | 搬家→地形棋盘域 | 经注入的所属域件公开方法直调（具体形态写卡定） |
|
||||
| _harmful_adjacent | 1 | 编排器私有方法 | 搬家→地形棋盘域 | 同上 |
|
||||
| _install_and_reset | 1 | 编排器私有薄壳（装板复位，架构在册轴丙） | 留宿主（保留面） | 构造注入 Callable |
|
||||
| _exit_distribution | 1 | 编排器私有方法（verdict 段经它触发轮推进） | 留宿主（现设计保留——七段结构冻结） | 构造注入 Callable |
|
||||
| _emit_settlement_snapshot | 1 | 编排器私有方法（结算快照发射） | 留宿主（呈现投影出口不变） | 构造注入 Callable |
|
||||
| **合计** | **107 处／105 行** | — | — | — |
|
||||
|
||||
取证注意：成员七符号逐项加总 73、编排器方法十二符号逐项加总 34，与三、构成行记写的 72＋35 有 ±1 出入（总处数 107 两路一致）；行号与计数一律以写卡段复核为准。
|
||||
|
||||
## 六、架构锚点（architecture.md）
|
||||
|
||||
- :119——B1 battle_orchestrator 职责列：段序骨架（七段结构冻结）、B2/B3/B4 唯一调用方＝B1 域文件集。
|
||||
- :124——BoardInstaller 行：构造＝引用束注入先例（装板薄壳＋表数据、随机流、装板所需对象与出错回调一次性交付）。
|
||||
- :137——「战斗编排域拆件定稿」节头（拆件定稿全文入口）。
|
||||
- :139——轴甲两件：宿主保留面首登记与呈现投影「唯一出口不变」。
|
||||
- :141——轴丁两件：零豁免裁宿主保留面原文（总判据 3 的登记原样出处）。
|
||||
Reference in new issue
Block a user