# {{PRODUCT_NAME}} 实施计划

## 执行规则

- 本文件采用 Kiro 风格 checklist：每个编号任务都必须能被开发者直接执行、单独勾选、单独验收。
- 严格按编号顺序执行；未完成当前任务的测试/验收前，不得进入下一个任务。
- 每个编号任务只处理一个清晰目标，通常改动 1 个文件、1 个类/组件、1 个方法、1 条接口或 1 组紧密相关的小文件。
- 每个任务下保留 3-6 条具体动作，不写长篇解释；最后必须包含测试/验收动作。
- 每个任务必须用 `_需求: ..._` 追溯到 PRD 功能编号或工程准备项。
- 开发前必须先锁定技术基线：语言版本、框架版本、包管理器、脚手架创建命令、依赖安装命令、启动命令和测试命令。
- 禁止开发执行者自行默认包管理器、依赖文件或脚手架方式；例如用户要求 `uv` 时不得改用 `requirements.txt`，Next.js 项目必须优先使用官方脚手架命令创建。

## 任务拆分规则

- 可以直接执行：创建某个目录和空文件、定义一个模型、实现一个仓储方法、实现一个 service 方法、注册一条路由、补一个测试场景。
- 需要继续拆分：实现完整模块、完成全部接口、搭建整个项目、创建所有测试、接入完整业务流程。
- 如果一个任务需要同时改模型、服务、路由、页面和测试，必须拆成多个连续编号任务。
- 如果一个任务的验证方式无法写成明确命令或明确人工验收步骤，说明粒度仍然过大或结果不清楚。
- 如果 `docs/tech-architecture.md` 未明确语言版本、框架版本、包管理器或脚手架命令，必须在任务计划中标记为阻塞问题并要求用户确认，不得自行选择默认值。

## 实施计划

- [ ] 1. 锁定技术基线和脚手架方案

  - 从 `docs/tech-architecture.md` 摘取语言运行时版本、框架名称和框架版本
  - 明确包管理器和依赖文件形态，例如 `uv`/`pyproject.toml`、`pnpm`/`package.json`、`npm`/`package-lock.json`
  - 明确项目创建方式：使用官方脚手架命令、已有项目内增量开发，或用户确认的手工目录方案
  - 写出真实脚手架创建命令、依赖安装命令、启动命令和测试命令；缺失则标记为阻塞确认项
  - 验收/测试：运行版本检查命令和脚手架 dry-run/帮助命令，确认版本、包管理器和创建方式与架构文档一致
  - _需求: 工程准备_

- [ ] 2. 使用确认的脚手架创建或校验项目骨架

  - 如果是新项目，严格执行上一任务确认的官方脚手架命令创建项目骨架
  - 如果是已有项目，先检查现有脚手架痕迹、配置文件和目录结构，不重新手写脚手架文件
  - 禁止绕过脚手架手工创建 `package.json`、框架配置或依赖锁文件，除非架构文档明确要求
  - 验收/测试：运行脚手架生成后的官方检查命令或项目启动命令，确认骨架可运行
  - _需求: 工程准备_

- [ ] 3. 配置测试命令和最小测试样例

  - 使用已确认的包管理器添加或校验测试依赖，不混用未确认包管理器
  - 创建一个最小测试文件，验证测试框架能被执行
  - 在已确认的项目配置文件中补齐测试命令，例如 `pyproject.toml`、`package.json` 或框架配置
  - 验收/测试：运行测试命令，确认最小测试通过且退出码为 0
  - _需求: 工程准备_

- [ ] 4. 实现第一个业务子模块的数据结构

  - 在对应模型、类型或 schema 文件中定义第一个 P0 功能需要的数据结构
  - 配置字段类型、必填规则、默认值和必要约束
  - 对照 `docs/prd.md` 检查字段是否覆盖页面字段、接口字段和状态流转要求
  - 验收/测试：运行模型、类型或 schema 校验测试，确认正常和缺失字段场景符合预期
  - _需求: M1-F1_

- [ ] 5. 实现第一个业务子模块的数据访问或状态读取

  - 在 repository、store、query hook 或数据访问文件中实现一个读取方法
  - 只处理一个明确查询场景，不混入聚合、写入或跨模块逻辑
  - 添加空数据、异常数据或权限不足时的返回规则
  - 验收/测试：运行该读取方法的单元测试，确认正常、空数据和异常场景通过
  - _需求: M1-F1_

- [ ] 6. 实现第一个业务子模块的业务处理方法

  - 在 service、use case、action 或组件逻辑文件中实现一个核心处理方法
  - 调用上一任务的数据访问能力，并按 PRD 业务规则转换结果
  - 添加业务异常、边界输入和状态转换处理
  - 验收/测试：运行该业务方法测试，确认正常、异常和边界场景通过
  - _需求: M1-F1_

- [ ] 7. 暴露第一个业务子模块的接口或页面入口

  - 在 router、controller、page 或组件入口中接入上一任务的业务方法
  - 添加请求参数、页面输入或组件 props 的校验逻辑
  - 按 UI/接口设计返回或展示统一格式的成功和失败结果
  - 验收/测试：运行接口测试、组件测试或页面交互测试，确认入口可用且错误反馈正确
  - _需求: M1-F1_

- [ ] 8. 补齐第一个业务子模块的回归测试

  - 为第一个业务子模块补充正常路径测试
  - 为第一个业务子模块补充异常路径测试
  - 为第一个业务子模块补充边界输入或空状态测试
  - 验收/测试：运行该子模块完整测试命令，确认全部测试通过且覆盖 PRD 验收标准
  - _需求: M1-F1_

- [ ] 9. 按 P0 功能重复拆解后续子模块任务

  - 为每个剩余 P0 功能按“数据结构 -> 数据访问/状态读取 -> 业务处理 -> 接口/页面入口 -> 回归测试”的顺序生成连续编号任务
  - 每个任务只保留一个主要代码意图，避免把完整模块塞进一个任务
  - 每个任务都写明具体文件、方法、接口、组件或测试场景
  - 验收/测试：确认每个 P0 功能都至少对应一个可执行任务和一个测试/验收动作
  - _需求: 全部 P0 功能_

- [ ] 10. 执行集成回归和交付检查

  - 运行全量单元测试、集成测试或端到端测试命令
  - 验证 PRD 中的 P0 主流程能按原型或接口设计完整走通
  - 检查 `docs/dev-tasks.md`、架构文档和实际实现是否仍一致
  - 验收/测试：全量验证命令通过后，才允许进入 `$pm-workflow deliver`
  - _需求: 交付验收_

## 文档同步检查

`plan` 阶段若发现环境、脚手架、框架版本、模块边界、接口、测试策略或验收标准与前文不一致，必须先回写对应 PRD/架构/UI 文档，再继续开发任务规划。不能只在本文件中新增或修正范围。

| 变更项 | 影响类型 | 是否影响上游事实 | 已检查文档 | 已同步文档 | 不需要同步原因 | 责任阶段 | 检查结论 |
|---|---|---|---|---|---|---|---|
| 开发任务规划 | 环境/脚手架/框架版本/接口/测试策略/验收标准 | 是/否 | `docs/prd.md`、`docs/tech-architecture.md`、`docs/ui-design.md`、`docs/handoff-prd.md`、`docs/handoff-architecture.md`、`docs/handoff-ui.md` | 待填写 | 待填写 | plan | 待确认 |
