W30 5 日开发计划 · v1.0 · 活跃计划

版本定位:可直接拆 lane 的 v1.0 执行计划。五日只表示一轮容量边界，不是日期门、截止门或等待门。 调度方式:完成即接力 + 文件锁互斥 + 工程证据收口。 明确移除:日期、时刻、等待天数、callback 前置、P1 审批前置。 继续保留:build、tests、lint、三层架构、文件边界、实际运行证据和 dirty-tree 保护。

0. TL;DR

单一 Goal:在不改变玩家可见行为、业务数值、UI 和存档语义的前提下，把全仓 TypeScript lint 从 68 errors 恢复到 0，并如实完成 W29 证据收口。
质量覆盖:Buff 27、auction 21、core runtime/UI 13、story editor/root 7；文件锁独立的领域可并行，最终统一回归。
可并行:文件锁不交叉的质量领域、联机骨架 doc-sync、R11 收口文档。
R10:保持 partial / accepted residual risk，浏览器/截图/P1 视觉验收进入 checklist；pending 不阻塞本计划。
新功能:失败链、跨周目 UI、角色深度 UI、内容池、WebRTC 都不进入本轮代码施工，质量收口后按路线图接力。

1. 单一 Goal 与成功定义

1.1 Goal

恢复仓库质量基线并完成 W29 的可信证据闭环，使下一条功能需求建立在 lint 0、build 通过、W29 回归全绿和架构边界明确的代码上。

1.2 成功定义

| 维度 | 收口要求 | | :--- | :--- | | TypeScript | cmd /c npm run lint PASS，68 → 0 | | 构建 | cmd /c npm run build PASS | | W29 回归 | cmd /c npm run test:w29 39/39 PASS | | 运行时 | 开档 → 进游戏 → 玩 1 个周期 smoke PASS | | 架构 | data 无新增函数，utils 无原始配置，UI 无新增业务计算；无反向 import | | 行为 | 玩家可见行为、业务数值、UI 与存档语义不变 | | W29 收口 | R11 如实落盘；R10 缺失证据保留为 residual risk，不伪造 verified | | 工作树 | 不回退、不覆盖无关改动；targeted git diff --check PASS |

其中任一工程硬门失败，本轮工程 Goal 不算完成。owner review pending 只作为后续 checklist，不属于工程失败。

2. 2026-07-13 执行状态

2.1 Q5 工程硬门

运行时没有记录到浏览器 error，但“进入后重新回到存档入口”使 Q5 的稳定周期验收不成立。直接代码证据是 consumeLoginEntryBootstrap() 在 state initializer 中消费并清空一次性标记，而入口运行在 React StrictMode 下；该启动链需先形成有界修复并复验。启动时已有的 redDot register ... overwriting 为 warning，不计作本轮新增运行时错误。

2.2 R10 非阻塞 checklist

R10 仍为 partial / accepted residual risk。
R10 owner review: pending，不阻塞 Q5 或后续工程派工。
四态点击链、掉线/重连/房主转移、7 张截图和 P1 结论仍未形成 formal evidence；不得由本次 smoke 代替。

3. 开工真值

3.1 已确认

build 已通过。
test:w29 已通过 39/39。
lint 已从 68 errors 恢复到 0，已复跑确认。
已完成或代码/测试已落:R7、R8、R9、R12、R13、R14、T3。
Q1 Buff、Q2 Auction、Q3-A 存档运行时、Q3-B/Q4 core UI/editor 残差均已完成定向验收；R11 与联机骨架 doc-sync 已收口。
Q5 的 lint/build/tests 已通过，真实运行 smoke 因继续存档后返回存档入口而未收口。
R10 为 partial / accepted residual risk，owner review pending，不阻塞后续工程。
R13 的 storyline-old-ledger.ts 桥接表、index 注册和年末输入已存在，不再安排旧计划中的“二段施工”。

3.2 原始 68 errors 分组

| 领域 | 数量 | 主要文件/根因 | | :--- | ---: | :--- | | Buff | 27 | src/data/buffs/buffConfigs.ts 未解析查询/定义符号，且文件含应归逻辑层的函数 | | Auction | 21 | src/data/auction/** 与 src/utils/auctionRules.ts 的字段/联合类型漂移 | | Core runtime/UI | 13 | src/App.tsx、运行时存档 tables、组件导出/unknown 收窄/环境类型等契约漂移 | | Story editor | 4 | unknown 比较、导出漂移、双 Vite 类型冲突 | | Root residue | 3 | types_append.ts 缺 StaffId，来源与是否仍被消费待核定 | | 合计 | 68 | 4 个质量领域，按文件锁拆分 |

4. 执行规则

4.1 完成即接力

lane 达到自己的定向验收后立即释放文件锁，依赖该锁的下一 lane 可以开工。
callback 只传递完成证据，不是下一 lane 的启动门。
没有 callback 时可直接读取文件、测试和构建真值；不得伪造他人回执。
独立文件域可以并行，同一文件或同一类型 owner 不并发写。

4.2 owner review 非阻塞

状态只允许:pending / approved / changes_requested。
pending = 已记录、没有代签、后续工程继续。
changes_requested = 新开有界 follow-up；不回滚与意见无关且已经验证的工程结果。
所有 owner review 必须附 checklist、证据、推荐默认值和最小回退点。

4.3 工程硬门

三层架构和相对 import 规则不可豁免。
类型修复不能用 any、无依据断言、扩大 unknown 逃逸或删除业务字段掩盖错误。
拍卖/Buff 修复不得改变业务数值或运行规则。
存档类型修复必须兼容现有数据，不得静默丢字段。
每个 lane 先过定向测试和错误归零，再释放文件锁。

5. P1 验收 checklist（非阻塞）

R10 联机 UI

[ ] 4 态真实浏览器路径已走通并留 4 张截图。
[ ] 重连、离线、房主转移已留 3 张截图。
[ ] 视觉规范 12 项与 auction console 一致性 6 项已记录。
[ ] P1 结论已写为 pending / approved / changes_requested 之一。
[ ] 回退点已记录:RoomCard.tsx 视觉调整 + App.tsx multiplayer 入口。
owner review: pending。

处理原则:

上述项目未完成时，R10 继续标 partial / accepted residual risk。
R11、doc-sync 和质量 lane 继续推进。
本轮不以 lint/build 反推浏览器或视觉验证通过。

6. Lane 设计

C1 · W29 文档证据收口

| 项 | 内容 | | :--- | :--- | | 目标 | 完成联机骨架 doc-sync 与 R11 收口，形成可信 W29 基线 | | 文件锁 | doc-sync:docs/design/active/联机P2P房间骨架-v1.md；R11 按既有 task 卡持有自己的收口文档/handoff 文件 | | 执行 | 两项可并行；都读取当前证据，不等待 R10 owner review 或 callback | | 验收 | doc-sync v1.1 7 段真填；R11 明确各 lane 工程状态、R10 residual risk、后续路线图 | | 非目标 | 不改 src/**；不重开 R7-R10；不在本计划代写 R11 产物 | | 工量 | S |

Q1 · Buff 编译与分层恢复（27 errors）

| 项 | 内容 | | :--- | :--- | | 目标 | 恢复 Buff 单一来源，消除 27 个未解析符号，同时修正 buffConfigs.ts 的数据/逻辑混层 | | 文件锁 | src/data/buffs/**、新建/调整的 src/utils/buffs/**、必要的 Buff import consumer；不碰 UI | | 实施边界 | 静态定义/配置留 data；summary、分类统计、查询与标签派生进 utils；不复制两份 Buff truth | | 定向验收 | Buff 错误 27 → 0；Buff 效果/权重快照不变；新增查询回归；build PASS | | 非目标 | 不加新 Buff，不调数值，不改显示 | | 风险/回退 | re-export 迁移导致 consumer 断裂；保留兼容导出层，按 Buff 领域补丁独立回退 | | 工量 | M |

Q2 · Auction 类型契约对齐（21 errors）

| 项 | 内容 | | :--- | :--- | | 目标 | 对齐 runtime 实际使用与 auction 数据类型，消除字段和联合类型漂移 | | 文件锁 | src/data/auction/**、src/utils/auctionRules.ts、auction 定向回归；不碰 auction UI | | 实施边界 | 对每个字段确认真实 owner；winner_choice、statusEffects、entryFeePaid、settled lot 等只保留一种语义 | | 定向验收 | Auction 错误 21 → 0；既有竞拍数值/顺序/结算快照不变；auction 回归 + build PASS | | 非目标 | 不重做竞拍玩法，不调费用/概率，不接 multiplayer transport | | 风险/回退 | 为消错误改 union 导致运行分支不可达；用 fixture/回归固定每个分支，按 auction 领域整体回退 | | 工量 | M |

Q3-A · Core save/runtime 契约恢复

| 项 | 内容 | | :--- | :--- | | 目标 | 收口 unknown 与 PlaythroughRuntimeSaveData.tables 契约，修复 App/验证桥的运行时类型错误 | | 文件锁 | src/App.tsx、src/data/playthroughs/types.ts、src/utils/playthroughVerification.ts 及直接类型 owner | | 启动条件 | R10 释放 src/App.tsx 文件锁即可；不等待 R10 callback/P1 回复 | | 定向验收 | 相关错误归零；旧存档缺字段有显式默认/迁移；存档 round-trip 回归 + build PASS | | 非目标 | 不改 App 其他 tab，不改 gameplay 值，不顺手重构 App | | 风险/回退 | 默认 tables 语义不当导致存档损坏；新增旧 payload fixture，失败时回退类型桥与默认值 | | 工量 | M |

Q3-B · Core UI 合约残差恢复

| 项 | 内容 | | :--- | :--- | | 目标 | 修复模块路径、组件导出、环境类型、helper 缺失与 unknown 收窄错误 | | 文件锁 | SideCardsRow.tsx、src/components/AppHeaderBar.tsx、DesktopConsolePanel.tsx、PortraitWorkspacePanel.tsx、WarningTab.tsx、src/data/eventTables/storyline-guo-lu-pilot.ts 及直接 owner | | 实施边界 | UI 仅渲染；drops 等静态契约回到 data type；helper 计算回到 utils | | 定向验收 | 该组错误归零；相关组件最小渲染/类型回归 + build PASS；玩家文案不暴露内部字段 | | 非目标 | 不改布局和视觉，不重写郭吕 pilot 内容，不扩大组件 props | | 风险/回退 | 错误 import 指向历史文件；先确认唯一真值，再改 consumer，按文件回退 | | 工量 | M |

Q4 · Story editor 与 root residue 恢复（7 errors）

| 项 | 内容 | | :--- | :--- | | 目标 | 消除剧情编辑器 4 个错误并核定 types_append.ts 3 个错误的真实归属 | | 文件锁 | tools/剧情编辑器/**、根 types_append.ts；不碰产品剧情数据 | | 实施边界 | unknown 显式收窄；统一 REAL_QUESTS 导出语义；解决双 Vite 类型来源；types_append.ts 若未被消费则在保留证据后移出编译面，若被消费则引入真实 StaffId owner | | 定向验收 | Story editor/root 错误 7 → 0；编辑器 build/typecheck PASS；主项目 build PASS | | 非目标 | 不改剧情内容，不升级整套工具链，不删除来源不明文件掩盖错误 | | 风险/回退 | 双 node_modules 处理影响本地编辑器；锁定依赖树/配置差异，保留可恢复的依赖清单 | | 工量 | M |

Q5 · 全仓合流与行为验证

| 项 | 内容 | | :--- | :--- | | 目标 | 证明各领域修复合流后仍保持产品行为不变 | | 文件锁 | 原则上不写产品文件；若发现回归，退回对应领域 lane 修复 | | 验收 | lint 0；build PASS；test:w29 39/39；开档 → 进游戏 → 玩 1 个周期 PASS；targeted git diff --check PASS | | 失败处理 | 不在 Q5 混改；按错误归属退回 Q1/Q2/Q3/Q4，修复并重新合流 | | 工量 | S |

7. 文件锁矩阵

| 锁 | 首持有 lane | 可并行 | 接力规则 | | :--- | :--- | :--- | :--- | | docs/design/active/联机P2P房间骨架-v1.md | C1 doc-sync | 所有质量 lane | 文档验收后释放 | | R11 收口文档/handoff 文件 | C1 R11 | 所有质量 lane | R11 自己收口；本计划不写 | | src/data/buffs/** | Q1 | Q2、Q3、Q4 | Q1 定向错误归零后释放；内容扩容以后再接 | | auction data/utils | Q2 | Q1、Q3、Q4 | Q2 回归通过后释放 | | src/App.tsx | R10 follow-up → Q3-A | Q1、Q2、Q3-B、Q4 | R10 释放即接力，不等待 callback/P1 | | core UI component set | Q3-B | Q1、Q2、Q3-A、Q4 | 文件列表冻结后执行 | | story editor/root | Q4 | C1、Q1、Q2、Q3 | 只在工具域内处理 |

同一文件出现新持有者时，以先登记的真实写锁为准；后来者缩边界或等待锁释放，不能靠覆盖解决冲突。

8. 依赖图

                         ┌─ C1 doc-sync
现状/锁登记 ─────────────┼─ C1 R11 收口
                         ├─ Q1 Buff ───────────────┐
                         ├─ Q2 Auction ────────────┤
                         ├─ Q3-B Core UI ──────────┤
                         └─ Q4 Tools/Root ─────────┤
                                                   ├─ Q5 全仓合流
R10 释放 App.tsx ─────────── Q3-A Save/Runtime ────┘
                                                        │
                                                        ▼
                                            后续需求路线图 F1

C1 与所有 Q lane 无代码文件交叉，可并行。
Q1/Q2/Q3-B/Q4 可在锁登记后并行。
Q3-A 只依赖 src/App.tsx 锁释放，不依赖 R10 的 owner review 或 callback。
Q5 只接受实际测试/构建证据；某 lane 尚未给出证据时，Q5 不伪造其完成。

9. 派工顺序

| 顺位 | 动作 | 接力触发 | | :---: | :--- | :--- | | 1 | 冻结 68-error 基线并登记当前文件锁 | 基线/锁表已记录即完成 | | 2 | 并行启动 C1、Q1、Q2、Q3-B、Q4 | 各自文件锁互不交叉 | | 3 | src/App.tsx 释放后启动 Q3-A | 文件锁释放，不等待其他状态 | | 4 | 每个 Q lane 定向错误归零、测试/build 通过后释放锁 | 工程证据成立 | | 5 | Q5 全仓合流验证 | Q1/Q2/Q3-A/Q3-B/Q4 均给出证据 | | 6 | Goal 收口，接力路线图 F1 失败链 v1.2 | lint/build/tests/smoke/diff-check 全过 |

本表只描述完成关系，不是日历、时刻或 callback 队列。

10. 收口判定

| # | 判定 | 失败时状态 | | :-: | :--- | :--- | | 1 | Buff 27、auction 21、core 13、tools/root 7 均归零 | 未完成，退回对应领域 lane | | 2 | cmd /c npm run lint PASS | 未完成，不得以“无新增”代替 lint 0 | | 3 | cmd /c npm run build + cmd /c npm run test:w29 39/39 PASS | 未完成，定位归属后回退修复 | | 4 | 开档 → 进游戏 → 玩 1 个周期 smoke PASS | 未完成，保留运行时 blocker 证据 | | 5 | 三层架构、文件锁、玩家文案、dirty-tree 与 diff-check 通过 | 未完成，按违规文件修正 | | 6 | R11 收口如实区分 R10 partial 与已验证 lane | 文档收口不可信，不能写 W29 all-green |

R10 owner review 可以保持 pending；这不会阻塞本轮工程 Goal，但必须继续出现在 R11 residual risk 和 checklist 中。

11. 残余风险

12. 非目标

不实现失败链 v1.2、跨周目 UI、角色深度 UI、内容池扩展或 WebRTC。
不重开 R7、R8、R9、R12、R13、R14、T3。
不重复实现 R13 旧账桥接二段。
不改变拍卖、Buff、胜利、跨周目或装备业务数值。
不借 lint 修复重做页面布局、视觉或导航。
不迁移全部 oldLedger/items 历史架构债。
不把 owner review pending 写成 P1 approved。
不用删除、exclude、any 或无依据断言掩盖真实类型错误。
不在本计划创建 task 卡或派发 worker。

13. lane 回执字段

- lane:<Q1 / Q2 / Q3-A / Q3-B / Q4 / Q5 / C1>
- result:<completed / partial / blocked>
- files changed:<实际文件>
- file locks released:<实际释放的锁>
- targeted errors:<before -> after>
- tests:<命令 + 结果>
- build/lint:<命令 + 结果>
- architecture check:<PASS / FAIL>
- behavior change:<none / 明细>
- owner review:<pending / approved / changes_requested / not_applicable>
- residual risks:<明细>
- rollback:<最小回退面>
- next relay:<依赖该完成证据的 lane>

只有实际文件、测试、构建和运行证据可以进入回执；callback 只是承载回执的渠道。

14. W30+ 后续候选(不进入本轮施工)

本节列出已拍板但不在 W30 实施范围的需求 lane；仅作 W31+ 排程参考，不进入本轮派工、文件锁或验收。

L1 · 启动页 v1.3 按钮接入

候选但未拍板(不进入本表)

烛火音乐真实音频(等 Q1 音频资源)
用户协议/隐私政策/游戏许可 modal(法务文案未定)
语言选择接真实 i18n(项目无 i18n 框架)
游戏设置 modal(走独立 v1.3 切片)