№ · REVIEWS CH.07.13
主页 · 📄 reviews · W29 代码质量审计与有界优化 v1

W29 代码质量审计与有界优化 v1

📅 2026-07-13 · 📦 9.2 KB · 📄 reviews · 📝 MD 文档 🆕 14d 🏷️ Buff🏷️ 装备🏷️ 剧情🏷️ 联机🏷️ 计划🏷️ 拍卖

审计时间:2026-07-13(Asia/Shanghai) 审计角色:[长工]#代码质量-W29收口审计优化@v1.0 单一 Goal:让 W29 已落代码更可验证、更符合三层架构,同时不改变玩家可见行为、业务数值、UI 或存档语义。 真值来源:AGENTS.md,docs/plans/active/2026-07-13-5日开发计划-v1.md,R7-R14/T3 task 卡,当前工作树,build/lint/tests 实跑结果。

0. TL;DR

  • 五日计划按实际证据统计:7/10 条已完成或代码/测试已落,1 条 partial,2 条未收口。
  • 构建:通过;W29/T3 统一回归:39/39 passed。
  • lint:68 -> 68。68 条均不在本长工触碰文件中,未为追求数字越过 R10/R11、UI、拍卖、Buff 或剧情编辑器禁区。
  • 本轮落地 2 项无行为变化的质量优化:
    1. AFFIX_POOL_STATS 从数据层运行时 filter() 派生改为静态元数据,并新增逻辑层回归防漂移。
    2. 新增 npm run test:w29,把 R7/R8/R13/R14/T3/词条 39 个回归场景收束成一条验收命令。
  • 主要残余风险:R10 缺浏览器/截图/P1 视觉签字;R11 收口文档未落;oldLedger.ts 与道具数据文件仍有历史三层架构债。

1. 五日计划完成度

| lane | 当前结论 | 证据 | 未完成项 | | :--- | :--- | :--- | :--- | | R7 P2P 实时竞价 | 代码/测试完成,卡面状态漂移 | realtimeBidding.regression.ts 5/5;build 通过;task 卡仍写 documented | task 卡未吸收为 verified | | R8 流拍 + 重连 | 代码/测试完成,卡面状态漂移 | timeout 5/5 + reconnect 5/5;build 通过;task 卡仍写 documented | task 卡未吸收为 verified | | R9 胜利数值 | verified | R9 task 卡 verified;R14/R9 回归链 11/11 | 无 | | R10 联机 UI | partial / accepted residual risk | R10 task 卡明确代码/build 已落 | 缺真实 browser click-through、7 张截图、P1 视觉签字 | | R11 W29 收口 | 未收口 | task 卡仍 active / waiting callback | 2026-07-13-5日开发计划-v1-收口.md 未落盘 | | R12 剧情字段净化 | verified | R12 task 卡 verified | 无 | | R13 旧账风波 | verified | R13 task 卡 verified;回归 5/5 | 二段桥接已提前存在,但控制面仍需按卡面口径收束 | | R14 跨周目锚点 | verified | R14 task 卡 verified;R9+R14 11/11 | 0.95 跨年衰减仅文档化,未进入函数,属已接受契约说明 | | T3 装备字段 | verified | T3 task 卡 verified;Zod + 5/5 | 无 | | 联机骨架 v1.1 文档 sync | 未执行 | task 卡 waiting_callback | 联机P2P房间骨架-v1.1.md 未落 |

完成度口径:

  • 已完成或代码/测试已落:R7,R8,R9,R12,R13,R14,T3 = 7。
  • partial:R10 = 1。
  • 未收口:R11,doc-sync = 2。
  • R7/R8 的实现证据成立,但控制面卡面仍是 documented;本报告不擅自改 handoff 真值。

2. 基线验证

| 检查 | 结果 | 说明 | | :--- | :--- | :--- | | cmd /c npm run build | PASS | 2330 modules;仅既有静态资源解析与大 chunk warning | | cmd /c npm run lint | FAIL(基线) | 68 条 TypeScript 错误 | | cmd /c npm run test:w29 | PASS | 39 tests / 39 passed / 0 failed | | targeted git diff --check | PASS | package.json,affixes.ts,affixLogic.regression.ts,本报告 | | 工作树 | dirty | 大量用户/其他 lane 改动;本轮未回退任何无关文件 |

39 个回归场景组成:

  • R7 实时竞价:5。
  • R8 timeout:5;reconnect:5。
  • R13 旧账风波:5。
  • R9/R14 跨周目:11。
  • T3 装备:5。
  • 词条静态元数据与基础契约:3。

3. 68 条 lint 错误分组

3.1 按领域

| 领域 | 数量 | 主因 | 本轮处置 | | :--- | ---: | :--- | :--- | | Buff 数据 | 27 | buffConfigs.ts 引用缺失的定义/查询符号 | P0 候选,但不属于 W29 已落域,未越界修 | | 拍卖 | 21 | 运行时字段与类型契约漂移(statusEffects,entryFeePaid,winner_choice 等) | 强制禁区,未修 | | 核心 UI / 运行时 | 13 | 缺 import、unknown 未收窄、存档 tables 缺失、组件导出漂移 | R10/R11 与 UI 禁区,未修 | | 剧情编辑器 tools | 4 | unknown 比较、导出名漂移、双 Vite 类型冲突 | 强制禁区,未修 | | 根目录残片 types_append.ts | 3 | 缺 StaffId | 非产品真值文件,未擅自删除/修复 | | 合计 | 68 | | |

3.2 按 TypeScript 错误码

| 错误码 | 数量 | 含义概括 | | :--- | ---: | :--- | | TS2304 | 31 | 未解析符号 | | TS2339 | 12 | 类型缺字段 | | TS2353 | 7 | 对象包含类型未声明字段 | | TS2741 | 3 | 必填字段缺失 | | TS2322 / TS2365 / TS2367 / TS2739 / TS2307 | 各 2 | 赋值、比较、记录完整性、模块路径问题 | | TS2724 / TS2769 / TS2345 / TS2459 / TS2347 | 各 1 | 导出、配置类型、unknown、可见性、泛型调用问题 |

结论:当前 lint 失败主要是少数大根因聚集,不是 W29 新增模块散落 68 个独立问题。应按领域开独立修复 lane,不能在质量长工里混改。

4. 三层架构审计

4.1 已通过

  • W29 新增 src/data/endgame/**、src/data/multiplayer/**、src/data/items/equipmentSchema.ts 未发现 data → utils/components 反向 import。
  • src/data/eventTables/storyline-old-ledger.ts 为静态桥接数据,未发现函数声明或数组派生调用。
  • src/utils/endgame/**,src/utils/multiplayer/**,src/utils/items/equipmentLogic.ts 的依赖方向为 utils → data。
  • T3 Zod schema 留在数据层;派生索引与 computeAffixPower 留在逻辑层。

4.2 本轮已修

src/data/items/affixes.ts 的 AFFIX_POOL_STATS 原先在数据层执行 5 次 AFFIX_POOL.filter(...)。这与“数据层只放 type/interface/const/静态数组”冲突。

处理:

  • 改为静态元数据 total=40,N=10,P=10,S=8,K=6,T=6。
  • 新增 src/utils/items/affixLogic.regression.ts,在测试/逻辑侧重新统计并断言静态元数据未漂移。
  • 玩家行为、词条数据、权重和数值均未改变。

4.3 已发现但未实施

| 优先级 | 架构债 | 证据 | 未实施原因 | | :---: | :--- | :--- | :--- | | P1 | src/data/storyEvents/oldLedger.ts 含 9 个状态/查询/权重函数 | getOldLedgerStoryState 到 choice effect 区域 | 消费方位于 data/eventTables/selection.ts 与 side-old-ledger.ts;正确迁移需同时重划 event selection 层,超过 8 文件/跨层门 | | P1 | src/data/items/equipment.ts 尾部含 reduce/filter 派生索引 | EQUIPMENT_ITEMS_MAP、BY_RARITY/QUALITY/STAFF/BUILDTAG/SET | year1Plan.ts 与 data/items/index.ts 仍消费数据层索引;迁移会触及 R12 数据与整个目录聚合 API | | P2 | consumables.ts,storyItems.ts,legacyItems.ts,itemConfigs.ts,data/items/index.ts 有历史派生逻辑 | reduce/filter/forEach/for 循环扫描 | 非 W29 新增,应按 item catalog 专项迁移,不与本轮混做 |

5. 本轮优化

Fix 1 · 数据层词条统计静态化

  • 修改:src/data/items/affixes.ts。
  • 新增:src/utils/items/affixLogic.regression.ts。
  • 直接证据:数据层函数扫描命中 5 个 filter()。
  • 验收:3 个新回归通过;build 通过;lint 无新增;diff-check 通过。
  • 回退:恢复 AFFIX_POOL_STATS 原派生表达式并删除对应回归文件。

Fix 2 · W29 回归入口统一

  • 修改:package.json。
  • 新增命令:npm run test:w29。
  • 直接证据:此前 R7/R8/R13/R14/T3 测试只能靠人工拼接命令,容易漏测。
  • 验收:单命令跑出 39/39 passed。
  • 回退:删除 test:w29 script,不影响产品运行。

6. 测试可信度与缺口

已具备:

  • 实时竞价、timeout、reconnect 状态机均有确定性时间输入与 node:test 回归。
  • R13 静态节点结构、触发门、选项数、跨年字段有数据契约测试。
  • R14/T3 有数值、上限、Zod、索引与静态映射测试。
  • 词条元数据新增防漂移测试。

仍缺:

  • R10 浏览器真实点击链、截图和 P1 视觉签字;单元测试/build 不能替代。
  • R7/R8 task 卡状态未吸收实现证据,控制面可能误判为未派工。
  • 没有“开档 → 进游戏 → 玩 1 个周期”的自动化回归;当前仅 build + 模块测试。
  • 68 条全局 lint 基线让新错误对比依赖计数与文件过滤,尚未达到全仓 tsc 绿。

7. 下一轮 shortlist

| 优先级 | lane | 最小目标 | 边界 | 验收 | | :---: | :--- | :--- | :--- | :--- | | P0 | Buff 编译恢复 | 收口 buffConfigs.ts 27 个未解析符号的单一来源 | src/data/buffs/** + 对应 src/utils/buffs/**;不动 UI | lint 68 → ≤41;build + Buff tests | | P0 | 拍卖类型契约对齐 | 对齐 21 个字段/联合类型漂移,不改竞拍数值 | src/data/auction/**,src/utils/auctionRules.ts;独立 lane | lint 再降 21;拍卖回归/build | | P1 | oldLedger 分层迁移设计 | 先产出 selection/data/utils 边界图,再拆 2 个短工迁移 | oldLedger.ts,side-old-ledger.ts,selection.ts,新 utils/storyEvents/** | data 层零函数,5 个 R13 tests + build |

R10/R11 仍应按现有流水线优先收口;上述质量 lane 不应抢占其 UI 文件。

8. 最终判定

  • 本轮状态:完成。
  • 质量改进遵守单一 Goal,未扩展玩法或设计。
  • lint 数字没有下降,但原因明确:安全可改项属于架构与可验证性,68 条编译错误全部位于本轮禁区或独立领域。
  • 可接受收口条件满足:build 通过,39/39 tests,lint 未增加,targeted diff-check 通过,报告落盘。