## 规划与排期：需求分解、估算与迭代排期（`/vspec:plan`）

[English](../../en-US/theory/planning.md) | [中文](../../zh-CN/theory/planning.md) | [日本語](../../ja-JP/theory/planning.md)

`/vspec:plan` 的目标不是“拍脑袋排期”，而是在需求口径收敛、关键遗漏/矛盾被识别之后，用可追溯的结构化输入把工作拆解、估算并装入迭代，生成一份可评审、可复用、可持续更新的交付计划。

### `/vspec:plan` 的前置与产物

- 前置（通常是 hard gate）：`/vspec:detail` 已输出可实现粒度的细节规格，并已完成 `/vspec:qc` 质量检查
- 核心产物：
  - `/specs/plan/plan_estimate.md`：基于功能清单的故事点估算（SP）
  - `/specs/plan/plan_story_map.json`：用户故事地图的数据（结构化、可复用）
  - `/specs/plan/plan_schedule.html`：用户故事地图的展示模板（从 JSON 加载并渲染）

### 需求分解：从“场景骨架”到“可交付切片”

需求分解的关键不是拆得越细越好，而是保证可交付、可验证、可追溯。

- 以场景为主线：把“流程 → 功能 → 页面/接口 → 数据/规则 → 验收”串成一条背骨，避免只按菜单/页面拆导致主流程不闭环
- 以可交付切片为最小单元：优先拆出能跑通的 P0 主流程闭环（即使功能不全，也能端到端验证）
- 以风险与依赖驱动拆分：外部依赖不确定的能力，先拆出“可内部完成”的部分（模型/页面/流程/模拟对接），把真实对接拆到后续迭代并显式标注阻塞点
- 以规模约束强制拆分：任何一项若合理估算会超过单次迭代容量或单卡过大，应继续拆到更小的可交付部分（例如保证单项 SP 不超过 13）

### 估算：用故事点做容量与装载

visual-spec 的估算以“故事点（Story Points）”表达相对成本，并用于后续排期装载。

- 统一估值标尺：全团队使用同一组点数与参照表，避免同类工作项估值漂移
- 显式表达不确定性：对依赖未定、口径不清、资源不可控的项，在估算中追加风险标记，防止“看起来都能做”
- 控制单卡大小：单卡过大会导致评审与追踪失效，也会掩盖关键风险；必要时拆成多卡并保持可追溯

### 排期：把“估算表”变成“迭代计划”

排期的输出不是简单分组，而是把目标、容量、依赖和风险放在同一张地图上，便于干系人评审与决策。

- 以迭代目标组织：每个 Sprint 用 1~3 句明确“交付什么、验证什么”
- 以容量装载：基于 Velocity/团队规模/迭代长度装载 SP，并按缓冲比例扣减有效容量
- 以依赖排序：先排主流程闭环与关键链路；外部对接/关键模块按串并行约束排布
- 以发布与验收闭环：把验收、联调、回归、发布窗口作为计划的一部分，而不是计划之外的“额外工作”

### 用户故事地图为什么采用 HTML

用户故事地图的核心用途是“评审与对齐”，HTML 比纯 Markdown/表格更适合作为评审入口。

- 可视化组织信息：按“迭代 × 模块”的二维结构展示，快速看清每个迭代交付范围与覆盖面
- 评审成本低：浏览器直接打开即可评审，适合业务/研发/测试/管理者共同参与
- 便于讨论与迭代：地图上的卡片可直接呈现估算与依赖，减少来回翻文档的上下文切换

### 为什么采用 JSON + HTML 模板（加载并展示）

`/vspec:plan` 将“计划数据”与“展示方式”解耦，避免每次调整都重写整份页面。

- 数据可复用：JSON 便于被其他工具消费（例如导出到项目管理系统、生成报表、做对比分析）
- 展示可演进：HTML 模板可以持续增强交互（筛选/搜索/高亮风险/对比迭代），而不改变数据结构
- 变更更可控：计划调整优先体现在 JSON（更干净的 diff），HTML 维持稳定的渲染逻辑
