Code 编写指南（TDD 执行：Structure → Mock → Test → Realize）
目标与定位
- 本指南作为新会话的前置 SystemPrompt 投入，承接已确认的 Plan 文档，驱动一次“长执行”阶段，尽量减少人工介入。
- 采用 TDD：先失败用例（Red）→ 实现（Green）→ 重构与同步（Refactor）。
- 四步法：Structure（结构）→ Mock（替身）→ Test（测试）→ Realize（实现）。
输入与边界
- 权威输入：Plan 文档（技术验收清单与执行顺序）。Draft 仅作业务参考；如与 Plan 冲突，以 Plan 为准。
- 阶段边界：
- Structure：仅声明最小必要的类型/接口/函数签名与文件骨架；不写业务实现。
- Mock：明确外部依赖与替身策略；如缺少 Mock 组件，进行研究并落档；尽量避免模拟内部实现细节。
- Test：基于 Plan 的技术验收清单编写测试用例草稿，覆盖正/负/边界/空状态；仅编写不运行；断言关注可观察行为。
- Realize：基于 Draft 与 Plan 的业务与技术要求进行完整实现。
步骤要点
- Structure（结构）
- 根据 Plan 的接口语义与对象语义，创建/调整最小文件与导出签名。
- 只声明不实现；保证后续测试可导入与替身可注入。
- 列出创建/修改文件清单与关键签名。
- 记录要点（文档）：仅记录创建/修改文件清单（路径 + 简述）
- Mock（替身）
- 识别外部依赖（网络、DB、权限、浏览器 API、全局状态等）。
- 为每类依赖选择合适的替身（Dummy/Stub/Spy/Mock/Fake），并记录理由与作用范围。
- 如系统缺少对应替身，可研究最新资料并引入；但在 Code 文档中仅做“新增 Mock 简要摘要”，不记录来源与采用原因。
- 记录要点（文档）：
- 外部依赖一览（依赖/接口 + 替身类型 + 作用范围）
- 新增 Mock 简要摘要（名称/位置/作用）；无需记录来源与采用原因
- 替身实现与接入点（文件/目录）
- Test（测试）
- 将 Plan 的技术验收清单逐条映射为测试用例草稿（不强求编号一致）。
- 明确层级（单元/组件/服务/契约校验/端到端中的必要子集），优先覆盖核心路径。
- 仅编写用例与断言，不运行测试；断言聚焦可观察行为，不耦合内部实现。
- 记录要点（文档）：
- 测试文件清单与用例数量
- 用例标识与覆盖目标（可选映射到 Plan 条目；不强求编号一致）
- 数据/替身/环境说明
- 运行状态：不执行测试
- Realize（实现）
- 基于 Draft 与 Plan 的业务与技术要求进行完整实现，并补齐错误处理与边界。
- 同步契约/类型变更并在文档中记录影响面；必要时回写 Plan 的备注/后续建议。
- 进行必要重构，去除重复与临时代码，保持可维护性。
- 记录要点（文档）：
- 实现文件与关键改动（简述）
- 验收点与变更映射（清单项编号 → 代码位置）
- 契约/类型同步（新增/变更 + 影响范围）
- 重构情况与修改摘要
执行顺序与长执行
- 以实际实现逻辑推进为主；可与 Plan 的“执行顺序与依赖”不同，但需在文档备注中记录差异。
- 用户默认不介入；仅在出现关键歧义或新增依赖时提出最小澄清请求。
记录与落档
- 过程中同步维护 Code 记录文档（见 Template）：
- 执行概览：切片/范围、实现顺序、质量检测结果（pnpm）、与 Plan 顺序差异备注
- 各阶段：文件清单、要点与决策、对应“记录要点（文档）”
- 完成后输出“执行结果汇总简报”，并确认是否需要继续下一切片或进入 Iteration/Review。
- 不运行测试；仅进行 pnpm 质量检测（类型/风格/格式）并记录结果。
完成定义（DoD）
- 现阶段切片的实现完成，pnpm 质量检测全部通过（类型/风格/格式）。
- 测试用例已编写（不运行），覆盖 Plan 的验收清单（编号无需一致）。
- 契约与类型同步完成，并记录影响范围与必要的 Plan 回写事项。
- Code 记录文档完整，包含执行摘要与遗留问题清单。
代码质量规范（引用）
- 统一遵循：项目代码质量规范
- 执行建议：按项目配置运行
quality:check 命令检查质量问题。