121 lines
21 KiB
Markdown
121 lines
21 KiB
Markdown
# 工程路线图（批次执行制：里程碑 + 批次序列 + loop 规范）
|
||
|
||
> 一句话：项目级进度视图——走到哪了、接下来按什么顺序走、每个批怎么跑。待办与待裁事项以 [待办清单](待办清单.md) 为唯一登记处（条目级）；批次过程与结论查 git 提交信息与 `reports/`（2026-10-18 用户裁：根目录会话状态文件已废除，本节顶部「当前位」三行即其替代）。
|
||
|
||
## 当前位（只回答「现在该做什么」；三行内随批次换代，禁止在此扩写成状态快照）
|
||
|
||
- **阶段**：M3——Alpha 版本的完整实现（2026-10-09 立规：未明令宣布完成前停留 M3，迭代只排 M3 需求，M4 不排期；根目录 stage.txt 为旧阶段开关仅存档）。
|
||
- **迭代位**：迭代 1–51 全部已完成——迭代 51（四卡：EffectPort 蓄力层删键／架构审查 5.1 封装修复／P2 NODE_TYPES 词表单点化／L1 深度 3 混编）2026-11-04 合回（合并提交 fb27dc2f，独立验收审计终判通过），批后收尾闭合（2026-11-04）：反哺点十条落文 architecture.md（第十一条落点不存在跳过、呈报在案）＋S13 无凭证基线键经用户裁撤销（--refresh 重生成入口同批删除、基线改人工修订，gdstyle 红在案由还债 P0 追绿）＋还债与死函数清退两条 P0 登记＋presentation 卡未编迭代迁出承接条目＋产出物退役三件＋待办三条目删除。迭代 50 收尾记录见 git 提交 47c752ea，迭代 49 见 aa396eb9。远端 CI：run 51/52 红（runner 中断非闸红）、run 53–55 排队待 Mac 上线。
|
||
- **下一步**：P0 两条待写卡（minesweeper_rules 公开面还债——gdstyle 红在案追绿；EffectEngine 死函数与全仓孤儿函数清退）；presentation 层封装修复卡已写卡待编迭代（4.125 工作日）。待编池：改写族孤儿（待处置方向裁决）、二三关棋盘观感（待设计＋待美术）、EC8 热重载实装（待用户另立条目）。
|
||
|
||
## 里程碑时间线
|
||
|
||
| 时间 | 里程碑 |
|
||
|---|---|
|
||
| 2026-09-07 ~ 09-14 | Systems Design 阶段：玩法系统 GDD 全树收口；概念原型 v3 终验 PROCEED（09-12，垂直切片承接）；GDD 体系重构（09-14，旧树封存） |
|
||
| 2026-09-15 ~ 09-16 | 切片数值语言定型：格面资源批、加法核数值语言拍板、护甲等级掷点批落地（smoke 233）、AP6+AC 验收判读口径 v1.0、待办清单建账改版 |
|
||
| 2026-09-17 ~ 09-19 | 切片机制完备：敌人技能池批落地（smoke 263）、关卡节点地图 v1.0 定稿+分支图批、加法核 80 遍试玩基线、无伤通关根因批（AP 压速）、验收读数重测批、掷点流种子偏置修复 A+B、插旗不可逆批、worktree 铁律立规 |
|
||
| 2026-09-20 ~ 09-21 | **一局完整冒险闭合**：冒险结构实现批（三关正式序列，smoke 482）、GP+商店房批（smoke 437）、存档序列化批（smoke 518）、元进度实现批（跨局循环闭合，smoke 549）、第三关内容批、八型批 |
|
||
| 2026-09-22 | Package B 七轮数值批+成长对齿已入库（用户拍板接受 B 曲线）；美术圣经 §6–9 全章成文（v2.0）；balance-verifier 数值验证工具批；美术文档过期账清偿批 |
|
||
| 2026-09-23 | 换算率标定批（6/9/1+护甲断链修复）；停点前移批实施（关卡开局即出图+三区化+LevelStripView 退役）；UI 复用候选批 |
|
||
| 2026-09-24 | **垂直切片转正（prototypes/ → game/）**；棋盘 Node2D 迁移 Phase A（BoardView 五层叠序）；伤害管线单据化（DamageController 唯一管线）；棋盘立体中档定稿冻结；状态图标接入 |
|
||
| 2026-09-25 | 棋盘小人贴图系列五批（1.5× 档+脚锚自底边+椭圆影）；AI 生图退出角色资产管线（定位=上游草稿引擎）；生图直出像素网格调研双报告 |
|
||
| 2026-09-26 | **战斗舞台 Node2D 迁移 Phase B（循环 1 收口，MC 逐位对拍零漂移）**；高墙瓦片 v9.3 定稿+换肤批（格面瓦片/敌像槽/接触带微光接线）；封印紫批；UX 文档欠账处置（level-clear 建档）；GP 归属拍板对齐；目录三层收敛大重构（design/artwork/game+熵增闸前身） |
|
||
| 2026-09-27 | 熵增闸已入库（repo_structure_audit 四查）；单元测试与契约层补建登记 P0；UX 文档面三 spec 齐（battle 欠账处置 / level-clear / level-map 三拍板收口）；关卡节点图生成 v0.1→v0.4 立项落文+统一流评估→用户裁丙→**统一随机流批落地（七流并一+全事件日志，329c7a2，状态记录 210）**；**roadmap 重整为批次执行制（本批，状态记录 208）** |
|
||
| 2026-09-28 | **M-1 切片表现收口完成（迭代 1+2 已入库，初步验收通过）**：样张 v2 机检 16/16 四冻结（art-bible v2.13）/框材组 8 件换皮/演出密度终稿/棋盘数字终稿/关卡画面三拍板实装/单元九套件/瓦片换色两套；同日**关卡画面独立化立项 M-2 高优先级**（用户裁决独立屏为最终形态，本批） |
|
||
| 2026-09-28 | **M-2 关卡画面独立化完成（迭代 3+4 已入库，出口闸目检通过）**：独立屏 LevelMapScreen+独立性断言（状态记录 224）/关卡画面样张 v1 机检 11/11 冻结+节点图标组接线+终稿落码+换层挂点（art-bible v2.14，状态记录 225）；出口检查单 `design/qa/m2-exit-gate-checklist-2026-09-28.md` 用户八项目检通过（状态记录 227） |
|
||
| 2026-09-29 | **迭代重排（用户裁决「内容逻辑闭环先于验收」）**：M-3 更名「数值标定与 Alpha 创建」——战斗演出完善前移迭代 6、魔法道具+元进度标定编入迭代 7、Alpha 验收后移迭代 8；M-4 转 Alpha 后深化与内容扩展（本批，状态记录 242） |
|
||
|
||
> **里程碑语义（2026-10-09 用户立规，现行口径）**：现行里程碑 = **M3「Alpha 版本的完整实现」**；M4 = Beta 版本的完整实现。用户未明令宣布 M3 完成前，项目停留在 M3 阶段——迭代规划只编排 M3（Alpha 完整实现）相关需求，M4 内容一律不排期、不进迭代，M4 的门 = 用户明令 M3 完成。2026-10-03「M-3 关闭、Alpha 到手」为验收史记录保留（旧口径 = Alpha 验收到手）；上表旧编号 M-1~M-4 保留作历史序列（M-3 旧名「数值标定与 Alpha 创建」，M-4 旧义「Alpha 后深化与内容扩展」），语义以本注为准。
|
||
|
||
## 迭代总表
|
||
|
||
一行一个迭代，回答一个问题：这个迭代编入了哪些卡、做到哪一步。各列格式与判据见 doc-conventions §12.2，由流水线闸（`tools/pipeline_gate.py`）机检。
|
||
|
||
| 迭代代号 | 状态 | 需求卡片 | 编入时间 | 预计周期 | 实现报告 |
|
||
|---|---|---|---|---|---|
|
||
| 迭代 1 | 已完成（2026-09-28） | — | — | — | 已退役（git 历史可考） |
|
||
| 迭代 2 | 已完成（2026-09-28） | — | — | — | 已退役（git 历史可考） |
|
||
| 迭代 3 | 已完成（2026-09-28） | — | — | — | 已退役（git 历史可考） |
|
||
| 迭代 4 | 已完成（2026-09-28） | — | — | — | 已退役（git 历史可考） |
|
||
| 迭代 5 | 已完成（2026-09-30） | — | — | — | 已退役（git 历史可考） |
|
||
| 迭代 6 | 已完成（2026-09-29） | — | — | — | 已退役（git 历史可考） |
|
||
| 迭代 7 | 已完成（2026-09-29） | — | — | — | 已退役（git 历史可考） |
|
||
| 迭代 8 | 已完成（2026-09-29） | — | — | — | 已退役（git 历史可考） |
|
||
| 迭代 9 | 已完成（2026-10-03） | 已退役（git 历史可考） | 2026-09-30 | — | 已退役（git 历史可考） |
|
||
| 迭代 10 | 已完成（2026-10-01） | — | 2026-09-30 | — | 已退役（git 历史可考） |
|
||
| 迭代 11 | 已完成（2026-10-03） | 已退役（git 历史可考） | 2026-10-03 | — | 已退役（git 历史可考） |
|
||
| 迭代 12 | 已完成（2026-10-04） | 已退役（git 历史可考） | 2026-10-03 | — | 已退役（git 历史可考） |
|
||
| 迭代 13 | 已完成（2026-10-04） | 已退役（git 历史可考） | — | — | 已退役（git 历史可考） |
|
||
| 迭代 14 | 已完成（2026-10-05） | 已退役（git 历史可考） | 2026-10-04 | — | 已退役（git 历史可考） |
|
||
| 迭代 15 | 已完成（2026-10-05） | 已退役（git 历史可考） | 2026-10-05 | — | 已退役（git 历史可考） |
|
||
| 迭代 16 | 已完成（2026-10-06） | 已退役（git 历史可考） | 2026-10-05 | — | 已退役（git 历史可考） |
|
||
| 迭代 17 | 已完成（2026-10-07） | 已退役（git 历史可考） | 2026-10-06 | — | 已退役（git 历史可考） |
|
||
| 迭代 18 | 已完成（2026-10-07） | 已退役（git 历史可考） | 2026-10-07 | — | 已退役（git 历史可考） |
|
||
| 迭代 19 | 已完成（2026-10-08） | 已退役（git 历史可考） | 2026-10-08 | — | 已退役（git 历史可考） |
|
||
| 迭代 20 | 已完成（2026-10-11） | 已退役（git 历史可考） | 2026-10-11 | — | 已退役（git 历史可考） |
|
||
| 迭代 21 | 已完成（2026-10-12） | 已退役（git 历史可考） | 2026-10-11 | — | 已退役（git 历史可考） |
|
||
| 迭代 22 | 已完成（2026-10-12） | 已退役（git 历史可考） | 2026-10-11 | — | 已退役（git 历史可考） |
|
||
| 迭代 23 | 已完成（2026-10-12） | 已退役（git 历史可考） | 2026-10-12 | — | 已退役（git 历史可考） |
|
||
| 迭代 24 | 已完成（2026-10-13） | 已退役（git 历史可考） | 2026-10-13 | — | 已退役（git 历史可考） |
|
||
| 迭代 25 | 已完成（2026-10-13） | 已退役（git 历史可考） | 2026-10-13 | — | 已退役（git 历史可考） |
|
||
| 迭代 26 | 已完成（2026-10-14） | 已退役（git 历史可考） | 2026-10-14 | — | 已退役（git 历史可考） |
|
||
| 迭代 27 | 已完成（2026-10-14） | 已退役（git 历史可考） | 2026-10-14 | — | 已退役（git 历史可考） |
|
||
| 迭代 28 | 已完成（2026-10-15） | 已退役（git 历史可考） | 2026-10-15 | — | 已退役（git 历史可考） |
|
||
| 迭代 29 | 已完成（2026-10-16） | 已退役（git 历史可考） | 2026-10-16 | — | 已退役（git 历史可考） |
|
||
| 迭代 30 | 已完成（2026-10-17） | 已退役（git 历史可考） | 2026-10-16 | — | 已退役（git 历史可考） |
|
||
| 迭代 31 | 已完成（2026-10-19） | 已退役（git 历史可考） | 2026-10-18 | ≈7.5 个工作日 | 已退役（git 历史可考） |
|
||
| 迭代 32 | 已完成（2026-10-21） | 已退役（git 历史可考） | 2026-10-20 | ≈8.75 个工作日 | 已退役（git 历史可考） |
|
||
| 迭代 33 | 已完成（2026-10-22） | 已退役（git 历史可考） | 2026-10-21 | ≈13.25 个工作日〔用户特批 2026-10-21 超 10 个工作日〕 | 已退役（git 历史可考） |
|
||
| 迭代 34 | 已完成（2026-10-22） | 已退役（git 历史可考） | 2026-10-21 | ≈11 个工作日〔用户特批 2026-10-21 超 10 个工作日〕 | 已退役（git 历史可考） |
|
||
| 迭代 35 | 已完成（2026-10-25） | 已退役（git 历史可考） | 2026-10-21 | ≈15.25 个工作日〔用户特批 2026-10-21 超 10 个工作日〕 | 已退役（git 历史可考） |
|
||
| 迭代 36 | 已完成（2026-10-25） | 已退役（git 历史可考） | 2026-10-24 | ≈5.25 个工作日 | 已退役（git 历史可考） |
|
||
| 迭代 37 | 已完成（2026-10-25） | 已退役（git 历史可考） | 2026-10-25 | ≈8.25 个工作日 | 已退役（git 历史可考） |
|
||
| 迭代 38 | 已完成（2026-10-26） | 已退役（git 历史可考） | 2026-10-26 | ≈5.225 个工作日 | 已退役（git 历史可考） |
|
||
| 迭代 39 | 已完成（2026-10-27） | 已退役（git 历史可考） | 2026-10-26 | ≈10.15 个工作日〔用户特批 2026-10-26 超 10 个工作日〕 | 已退役（git 历史可考） |
|
||
| 迭代 40 | 已完成（2026-10-28） | 已退役（git 历史可考） | 2026-10-27 | ≈6.375 个工作日 | 已退役（git 历史可考） |
|
||
| 迭代 41 | 已完成（2026-10-29） | 已退役（git 历史可考） | 2026-10-27 | ≈13.15 个工作日〔用户特批 2026-10-27 超 10 个工作日〕 | 已退役（git 历史可考） |
|
||
| 迭代 42 | 已完成（2026-10-29） | 已退役（git 历史可考） | 2026-10-29 | ≈5.375 个工作日 | 已退役（git 历史可考） |
|
||
| 迭代 43 | 已完成（2026-10-30） | 已退役（git 历史可考） | 2026-10-29 | ≈6.5 个工作日 | 已退役（git 历史可考） |
|
||
| 迭代 44 | 已完成（2026-10-30） | 已退役（git 历史可考） | 2026-10-29 | ≈7.875 个工作日 | 已退役（git 历史可考） |
|
||
| 迭代 45 | 已完成（2026-10-31） | 已退役（git 历史可考） | 2026-10-29 | ≈7 个工作日 | 已退役（git 历史可考） |
|
||
| 迭代 46 | 已完成（2026-11-01） | 已退役（git 历史可考） | 2026-11-01 | ≈8.625 个工作日 | 已退役（git 历史可考） |
|
||
| 迭代 47 | 已完成（2026-11-01） | 已退役（git 历史可考） | 2026-11-01 | ≈15 个工作日〔用户特批 2026-11-01 超 10 个工作日〕 | 已退役（git 历史可考） |
|
||
| 迭代 48 | 已完成（2026-11-02） | 已退役（git 历史可考） | 2026-11-01 | ≈6.1 个工作日 | 已退役（git 历史可考） |
|
||
| 迭代 49 | 已完成（2026-11-02） | 已退役（git 历史可考） | 2026-11-02 | ≈7.25 个工作日 | 已退役（git 历史可考） |
|
||
| 迭代 50 | 已完成（2026-11-03） | 已退役（git 历史可考） | 2026-11-03 | ≈12.875 个工作日〔用户特批 2026-11-03 超 10 个工作日〕 | 已退役（git 历史可考） |
|
||
| 迭代 51 | 已完成（2026-11-04） | 已退役（git 历史可考） | 2026-11-04 | ≈6.625 个工作日 | 已退役（git 历史可考） |
|
||
|
||
- 迭代 38 收口为带红合并〔用户特批 2026-10-26〕：09 静态扫描 S13 gdstyle 恶化 2 条经批准记入基线存量红（git 提交 c4c69701），卡② 停卡退上游，处方已于 2026-10-26 修订定稿 v1.3（git 提交 b3ea7532），随「gdstyle 存量债全量清偿」条目波 7 待编排。
|
||
- 迭代 39 收口为带红合并〔用户特批 2026-10-27〕：02 EV 锚 goblin 0.9148∉[1.00,1.20]（触发器批有意行为改动，fp f74b9a48ef4a）已随 EV 锚重锚批换带归绿（git 提交 ba5105aa）；08d 生涯.md:55 行号漂移已随 2026-10-28 批后收尾反哺落文修复归绿。三卡拆分后终局 gdstyle 恶化 2 条（battle_orchestrator max-file-length、level_map_screen max-class-variables）归迭代 40 卡①还债与迭代 41 存量债序列。
|
||
- 迭代 40 收口为用户特许免闸直合〔2026-10-28〕：全量域验收回执未取得（回执环节断于用户特许，验收审计报告如实记档不作绿报；独立审计结论＝通过，F1 一行修 iter40 8a319369 先行入库）。卡① 契约 2 宿主行数残余债（实测 1036 行，合并适配带入 36 行）经用户裁登记归后续批清偿（待办清单「战斗域结构深拆批」条目承载）；09 存量红剩 level_map_screen 类变量一条归迭代 41 卡③。
|
||
- 迭代 41 收口为测试特许移交＋用户裁直接合回〔2026-10-28／2026-10-29〕：全部套件与闸停跑（gdstyle 结构闸除外——开发期读数反馈在跑），验收断言、golden 对拍与独立验收审计一并移交用户执行，2026-10-29 用户裁直接合回（合并提交 eb9bb537）；golden 改前锚未建让步与四项实机目检已迁体验验证清单 ㊵；gdstyle 基线 152 死键 refresh 已执行（2026-10-29 人工重锚 168→16 键，git 提交 fafb4fee）。
|
||
- 历史行的「—」= 该列事实不可考：迭代 1~8 早于需求卡片制；编排时点与预计周期不再回溯，细节查 git 提交史。
|
||
- 「已退役（git 历史可考）」= 需求卡片或实现报告曾存在，已按「证据只留最新」退役；已完成迭代的实现报告列只填 reports/ 现存路径或本保留字，不填「—」。
|
||
- 新迭代行的编排与各列判据见 doc-conventions §12.2 与 iter-plan 技能，由流水线闸（`tools/pipeline_gate.py`）机检。
|
||
|
||
## 执行纪律（2026-09-27 用户立规）
|
||
|
||
1. **一迭代一 loop**：所有更改任务（功能/文档/数值/素材接线）一律进本路线图的迭代，每迭代先立计划书再开工，一个迭代一次合并登记——**零散并行会话退场**（多会话并行 = 冲突源+介入成本；2026-09-27 起单迭代串行执行）。状态记录记「批」= 本文件记「迭代」，同物异名。
|
||
2. **例外 = 零碎 bug**：单独会话 mini-loop 修复（修→只测自己改的东西→状态记录登记），不立计划书、不占迭代位；同屏同类 bug 攒够一笔可并入下一个迭代当任务卡。
|
||
3. **用户输入闸显式化**：迭代门里所有需要用户表态的点（否决原因/裁决/试玩）登记在 [待办清单](待办清单.md) 的状态列（待裁决／待美术设计／待写卡），解一个开一个。
|
||
|
||
## 批次 loop 规范（loop engineering）
|
||
|
||
> 模板先例 = 循环 1 计划书（`.zcode/plans/battle-stage-node2d-loop-plan-2026-09-26.md`，已完整跑通收口）。每迭代照此八件成文，缺件不开工。
|
||
>
|
||
> **迭代粒度界定（对齐敏捷迭代/Sprint）**：一个迭代 = 一句迭代目标 + **3–8 个更改任务** + 一份计划书 loop + 一次合并登记，交付一个可验证增量（≈一次迭代交付）。单交付物不成迭代——并入相邻迭代当任务卡；用户输入闸未解的任务不进迭代（留待办清单当 backlog，解闸后编入下一个迭代）；**迭代周期**：常规 5–10 个工作日（1–2 周）、直接编；超过 10 个工作日（超过 2 周）须经用户确认；低于 5 或超过 20 个工作日不得编（硬下限/硬上限，2026-10-21 用户裁定；列形态与闸判据见 doc-conventions §12.2 与流水线闸）。**里程碑 = 2–4 个迭代的发布级目标 + 出口验收闸（≈Release）**。
|
||
>
|
||
1. **计划书**（`.zcode/plans/<迭代名>-loop-plan-<日期>.md`）：迭代目标与完成定义 / 现状事实（代码级，开工自行复核）/ 设计契约（违反即返工，标 🔴 触碰=L3 停机）/ 范围边界 / 任务卡 T0..Tn（逐卡估时）/ 验证闸 / 异常分级 / 代拍板白名单。
|
||
2. **T0 开工**：建 worktree + 拷素材与导入缓存（冷检出三件套照坑速查）+ `git status` 归属核对（并行遗留只登记不触碰）——**检出工作区零测试，直接开工**（2026-10-22 频率规则；master 经合回闸保证可用）。
|
||
3. **循环骨架**：一轮 = 一个任务卡——读卡 → 对事实源 → 实装（验收测试随对应 T 卡同轮落地；**本卡新增/改动的验收测试自己跑绿即收口，没改的不测**）→ 提交（代拍板随 commit 记录）→ 状态记录追加（查撞号）→ 下一轮。单 worktree 多点提交一次合并；轮内禁开第二个 worktree；轮内不跑闸；断点续跑 = `git log` 对任务卡定轮次。
|
||
4. **全量闸时机（2026-10-22 频率规则，无例外）**：全量只有批末＋合回两个时机，轮内零跑闸（含 `--quick` 中段自检档）——卡内只测自己改的东西；既有「验收测试随卡落地」「调试期出红只重跑红件最小单元」两条保留（闸机轮次纪律见 process-conventions §6）。
|
||
5. **全量域闸**（批末 Tn）：`tools/run_all_gates.sh` **按本批改动域跑**（代码面＝`game/` 下非 `.md` 的行为载体 → `--code`，这是代码域唯一触发；只有文档件——`game/` 内 `.md` 及 `game/` 外一切路径 → `--docs`；两类同批都有 → 不带参数全量），所选域全绿——闸件清单、顺序与域划分只在该脚本里定义，本文件与 AGENTS.md/规约均不另列；改闸件自身（`tools/` 下机检脚本与闸壳）不占合回全量，质量义务＝落批时人工确认闸可跑通且判据口径未变；涉核心的 MC 与基线逐位比对、素材批的机检断言另行。
|
||
6. **人闸**（停机交付）：真人目检清单 + 代拍板追认清单 + 异步终审触点（样张类）——本循环内唯一必经人审。
|
||
7. **异常分级**：L1 自救（一次重试）→ L2 记录继续（连续 3 次同红灯升级）→ L3 停机写报告等用户。
|
||
8. **批次完成后的五步登记**：①待办清单条目状态按 doc-conventions §12.1 推进（做完整条删除）②本文件顶部「当前位」三行换代，涉及里程碑移动时同步里程碑表 ③**实现批禁写本文件与 `design/`**（代码实现批只准写 `reports/`），该改哪一行写进 `reports/iter<N>-反哺点-<日期>.md`，由文档批执行 ④阶段变更改 stage.txt ⑤批末闸序列**按本批改动域**全绿留痕（回执 commit 对齐分支尖）。
|
||
|
||
## 维护纪律
|
||
|
||
同「批次 loop 规范」第 8 条五步登记；本文件由里程碑移动与「当前位」换代触发更新（批次开工不强制改本文件，待办明细改待办清单）。「当前位」限三行，装不下的细节进待办清单条目与 git 提交信息。
|