From 3be3f3e7c17094480fbfaed8f9dff3cdc5c3f9c2 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Tue, 3 Nov 2026 05:39:07 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=E8=AE=BE=E8=AE=A1(=E6=9E=B6?= =?UTF-8?q?=E6=9E=84=E5=AE=A1=E6=9F=A55.1=E5=B0=81=E8=A3=85=E4=BF=AE?= =?UTF-8?q?=E5=A4=8D=C2=B7=E7=94=A8=E6=88=B7=E8=A3=81):=20=E8=AE=BE?= =?UTF-8?q?=E8=AE=A1=E8=AE=A8=E8=AE=BA=E7=BB=93=E8=AE=BA=E8=90=BD=E6=A1=A3?= =?UTF-8?q?=E4=B8=A4=E4=BA=A4=E4=BB=98=E2=80=94=E2=80=94=E2=91=A0=E5=A4=84?= =?UTF-8?q?=E7=BD=AE=E8=AE=B0=E5=BD=95=20reports/=E5=A4=84=E7=BD=AE-?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E5=AE=A1=E6=9F=A55.1=E5=B0=81=E8=A3=85?= =?UTF-8?q?=E4=BF=AE=E5=A4=8D-2026-11-03.md(=E6=80=BB=E5=88=A4=E6=8D=AE?= =?UTF-8?q?=E5=85=AD=E6=9D=A1/=E6=A0=B9=E5=9B=A0=E5=AE=9A=E7=A8=BF?= =?UTF-8?q?=E4=B8=89=E6=97=A0=E5=8F=A0=E5=8A=A0/=E6=99=AE=E6=9F=A5?= =?UTF-8?q?=E4=BA=94=E5=A4=84=20core=20105=E8=A1=8C107=E5=A4=8419=E7=AC=A6?= =?UTF-8?q?=E5=8F=B7+presentation=20227=E8=A1=8C=E5=87=BA=E5=8D=A1/?= =?UTF-8?q?=E9=80=90=E9=A1=B9=E8=A3=81=E5=86=B3=E8=AE=B0=E5=BD=95/19?= =?UTF-8?q?=E7=AC=A6=E5=8F=B7=E8=A1=8C=E4=B8=BA=E5=BD=92=E5=B1=9E=E6=80=BB?= =?UTF-8?q?=E8=A1=A8/=E6=9E=B6=E6=9E=84=E9=94=9A=E7=82=B9;=20=E6=8E=A5?= =?UTF-8?q?=E6=94=B6=E6=96=B9=3D=E9=9C=80=E6=B1=82=E5=8D=A1=E7=89=87-?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E5=AE=A1=E6=9F=A55.1=E5=B0=81=E8=A3=85?= =?UTF-8?q?=E4=BF=AE=E5=A4=8D-2026-11-03.md+=E5=BE=85=E5=8A=9E=E6=B8=85?= =?UTF-8?q?=E5=8D=95=E6=9E=B6=E6=9E=84=E5=AE=A1=E6=9F=A5=E4=BC=98=E5=8C=96?= =?UTF-8?q?=E8=AE=A8=E8=AE=BA=E6=9D=A1=E7=9B=AE,=20=E5=8D=A1=E7=89=87?= =?UTF-8?q?=E6=88=90=E7=AB=8B=E5=8D=B3=E9=80=80=E5=BD=B9);=20=E2=91=A1code?= =?UTF-8?q?-conventions.md=20=E6=96=B0=E5=A2=9E=20=C2=A71.6=20=E6=8B=86?= =?UTF-8?q?=E5=88=86=E4=BA=A4=E6=8E=A5=E4=B8=8E=E5=B0=81=E8=A3=85=E8=BE=B9?= =?UTF-8?q?=E7=95=8C(=E6=9D=A1=E4=B8=80=E6=8B=86=E5=88=86=E4=BA=A4?= =?UTF-8?q?=E6=8E=A5=E5=AE=9A=E4=B9=89=3D=E8=81=8C=E8=B4=A3=E8=BE=B9?= =?UTF-8?q?=E7=95=8C+=E4=BA=A4=E6=8E=A5=E5=AE=9A=E4=B9=89=E5=8F=8C?= =?UTF-8?q?=E9=BD=90=E5=A4=87=E6=89=8D=E7=AE=97=E6=8B=86=E5=88=86=E5=90=88?= =?UTF-8?q?=E6=A0=BC,=20=E5=85=88=E4=BE=8B=3DBoardInstaller=20=E5=BC=95?= =?UTF-8?q?=E7=94=A8=E6=9D=9F=E6=B3=A8=E5=85=A5;=20=E6=9D=A1=E4=BA=8C?= =?UTF-8?q?=E5=B0=81=E8=A3=85=E8=BE=B9=E7=95=8C=3D=E8=B7=A8=E5=AF=B9?= =?UTF-8?q?=E8=B1=A1=E7=A6=81=E8=AE=BF=E9=97=AE=E4=B8=8B=E5=88=92=E7=BA=BF?= =?UTF-8?q?=E6=88=90=E5=91=98=E5=8F=AA=E8=B5=B0=E5=85=AC=E5=BC=80=E9=9D=A2?= =?UTF-8?q?)=E2=80=94=E2=80=94=E6=9C=AC=E6=89=B9=E4=BF=AE=E5=A4=8D?= =?UTF-8?q?=E4=B8=8E=E5=90=8E=E7=BB=AD=E9=97=B8=E4=BB=B6=E5=85=B1=E5=90=8C?= =?UTF-8?q?=E4=BE=9D=E6=8D=AE;=20GDD=20=E9=9B=B6=E6=94=B9=E5=8A=A8;=20?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=9F=9F=E9=97=B8=E5=85=A8=E7=BB=BF(8?= =?UTF-8?q?=E9=97=B8=20all=5Fgreen)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- design/engineering/code-conventions.md | 6 ++ .../处置-架构审查5.1封装修复-2026-11-03.md | 93 +++++++++++++++++++ 2 files changed, 99 insertions(+) create mode 100644 reports/处置-架构审查5.1封装修复-2026-11-03.md diff --git a/design/engineering/code-conventions.md b/design/engineering/code-conventions.md index 7f7f07a9..1d3bafdc 100644 --- a/design/engineering/code-conventions.md +++ b/design/engineering/code-conventions.md @@ -34,6 +34,12 @@ ### 1.5 禁止事实约定 任何"大家默认这么做"的惯例必须成文进本文件（或 AGENTS.md）才算存在。写代码时发现未成文但必须遵守的约定 → 当场补条文，不许靠惯性延续。 +### 1.6 拆分交接与封装边界 +本节管拆分类改动的交接面与封装面，与 §1.1 拆分判据（职责轴）配合使用：§1.1 管怎么切，本节管切完之后件与件之间怎么往来。 + +1. **拆分交接定义**：拆出一个新类时，交付物必须同时写明职责边界与交接定义——新类构造时需要哪些依赖，由拆出它的类在构造它时一次交给它；新类需要回调拆出它的类的哪些方法，以 Callable 形式交付。两者齐备才算拆分合格。为什么：只切职责不定义交接，新件会伸手回原类内部拿东西，封装从拆件那天起就破了。正面先例＝装板件的引用束注入（表数据、随机流、装板所需对象与出错回调一次性交付——架构文档「战斗编排域拆件定稿」节 BoardInstaller 行在册）。 +2. **封装边界**：任何代码不得访问其他对象的下划线成员；跨对象往来只走公开方法与属性。为什么：下划线只是命名约定，语言不设防、无编译期检查——此条是封装硬纪律，违者即红。 + --- ## 2. 契约纪律——跨层/跨类调用的语义 diff --git a/reports/处置-架构审查5.1封装修复-2026-11-03.md b/reports/处置-架构审查5.1封装修复-2026-11-03.md new file mode 100644 index 00000000..5e5f3b61 --- /dev/null +++ b/reports/处置-架构审查5.1封装修复-2026-11-03.md @@ -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 的登记原样出处）。