huangzd1997
e248b6e43a
- SPA 化：22 个 MPA html 入口与 *-main.ts 合并为 index.html + vue-router（URL 无 .html 后缀）， 页面跳转全部 router-link，/new_web_source/xxx.html 旧路径归一为 /xxx - 任务面板统一：共享 TaskCenterPanel/TaskItemCard/TaskStatCards/HistoryTaskLayer， 16 个工具页右侧统一为统计卡 + 当前任务 + 历史任务弹层（任务ID/开始/结束/状态必展示） - 历史记录支持单条删除 + 批量勾选删除（确认框/全选/失败提示） - Java 7 模块（dedupe/convert/split/productrisk/shopmatch/pricetrack/deletebrand） history 接口补齐任务时间字段（VO+Service，复用 biz_file_task 列） - 图片工作台/API 层（brand/permission/user）既有未提交改动一并提交
171 lines
9.8 KiB
Markdown
171 lines
9.8 KiB
Markdown
读取 `docs/specs/` 下的所有 spec 文件，将每个模块拆成**功能点维度**的原子任务。
|
||
|
||
## 核心原则
|
||
|
||
### 按功能点拆分，不按函数拆分
|
||
|
||
- ❌ "实现 Cache 类" — 太粗
|
||
- ✅ "缓存条目超过 N 个时按 LRU 策略淘汰最久未使用的一半"
|
||
- ✅ "缓存条目闲置超过 N 分钟后自动标记过期并清理"
|
||
- ✅ "命中率统计：实时统计缓存命中率，低于阈值时触发预热"
|
||
|
||
（以上仅为粒度示例，实际功能点以项目 spec 为准）
|
||
|
||
### 任务编号与数量
|
||
|
||
- 统一编号：1, 2, 3... N（不用 1.1, 1.2）
|
||
- 每个 task 粒度约 **8-15 分钟**可完成（含写测试 + 实现 + 自测，不能更短）
|
||
- 每个模块至少拆 20-30 个功能点任务，模块较多时全量视项目规模而定
|
||
- 宁可过细，不可过粗
|
||
|
||
### ⚠️ 严格 TDD —— 测试必须充分，禁止敷衍
|
||
|
||
这是本项目的核心度量目标：**用足够扎实的 TDD 驱动每个 task，确保单 task 耗时 8-15 分钟**，从而测出模型的长程工作能力。测试不够多 = task 太快 = 实验无效。
|
||
|
||
每个 task 的测试套件必须满足以下**最低要求**（不满足不准标 done）：
|
||
|
||
| 维度 | 最低用例数 | 说明 |
|
||
|------|-----------|------|
|
||
| 正常路径（happy path） | ≥ 3 | 主要输入变体都要覆盖 |
|
||
| 边界条件 | ≥ 3 | 空值/零值/最大值/越界/单元素 |
|
||
| 异常与错误处理 | ≥ 2 | 非法输入抛正确异常类型 + 错误消息 |
|
||
| **合计** | **≥ 8 个测试用例/task** | 纯类型/常量定义类 task 可降到 3-5 |
|
||
|
||
- **TDD 三段式必须在 plan 里写明**：① 先写全部测试 → ② 运行确认 RED（失败）→ ③ 实现到 GREEN（全过）。跳过 RED 确认 = 测试无效。
|
||
- 测试名要语义化（如 `test_ipv4_with_leading_zeros_normalized` 而非 `test_1`），能从测试名看出验证了什么。
|
||
- 涉及 I/O（HTTP/文件/子进程/数据库）的 task：用 mock + 至少 1 个真实集成测试。
|
||
- 涉及外部服务/第三方 API 的 task：mock 单元测试 + 真实调用集成测试（配置对应的密钥/环境变量）。
|
||
|
||
### ⚠️ 单线程串行开发 —— 禁止并行 agent
|
||
|
||
- 开发阶段**严禁** spawn 多个 agent / workflow / Task 并行实现不同 task
|
||
- 每个 task 必须由**主线程顺序**完成：写测试 → 实现 → 验证 → commit → 才能开始下一个
|
||
- 理由：本项目用于度量单 agent 的长程连续工作能力，并行会污染实验数据
|
||
- 允许的并行：只读的代码探索（Explore agent 读文件分析），但**不允许并行写代码**
|
||
|
||
### 首个模块：项目初始化 / 现状确认
|
||
|
||
- **全新项目或技术栈迁移**：plan 最前面的几个 task 必须是项目初始化：创建目录结构、生成项目清单文件（如 pyproject.toml / package.json / go.mod 等，按目标技术栈而定）、安装依赖、确认 CLAUDE.md 内容。技术栈以 `docs/specs/00-overview.md` 为准。
|
||
- **现有项目重构/迭代开发**（代码库已存在、技术栈不变）：跳过项目初始化类 task，改为第一个 task 确认现状——依赖已安装、测试/lint 命令可运行、CLAUDE.md 已就位，再从第二个 task 起进入具体功能点。
|
||
|
||
## 任务格式
|
||
|
||
```markdown
|
||
## 任务 N：<功能点描述>
|
||
|
||
**所属模块**：<模块名>
|
||
**依赖**：任务 X, Y（无则写"无"）
|
||
**预估耗时**：8-15 分钟（写测试 + 实现 + 自测）
|
||
|
||
### 功能点要求
|
||
<具体行为描述，精确到输入/输出/边界>
|
||
|
||
### 测试用例（必须先写，确认 RED）
|
||
列出本 task 要写的全部测试，至少 8 个：
|
||
1. test_xxx_normal_case_1 — <验证什么>
|
||
2. test_xxx_normal_case_2 — <验证什么>
|
||
3. test_xxx_normal_case_3 — <验证什么>
|
||
4. test_xxx_boundary_empty — 空输入
|
||
5. test_xxx_boundary_max — 最大值/越界
|
||
6. test_xxx_boundary_single — 单元素
|
||
7. test_xxx_invalid_raises — 非法输入抛出对应异常/错误
|
||
8. test_xxx_error_message — 错误消息内容
|
||
|
||
### TDD 流程
|
||
1. 写上述全部测试 → 运行项目测试命令（如 `pytest` / `npm test` / `go test` 等，按技术栈而定）确认 **RED（全失败）**
|
||
2. 实现功能 → 确认 **GREEN（全过）**
|
||
3. 运行项目 lint/format 检查命令，通过
|
||
|
||
### 验证方法
|
||
<运行哪个命令、观察什么结果>
|
||
```
|
||
|
||
## 输出要求
|
||
|
||
### 文件与编号一一对应
|
||
|
||
```
|
||
docs/plans/
|
||
├── 00-plan-overview.md # 全部任务表格 | N | 功能点 | 模块 | 依赖 |，末尾标注总任务数
|
||
├── 01-project-init.md # 对应 docs/specs/01-project-init.md
|
||
├── 02-<模块名>.md # 对应 docs/specs/02-<模块名>.md
|
||
├── ...
|
||
```
|
||
|
||
**约束**：
|
||
- 每个 spec 文件生成一个同编号的 plan 文件
|
||
- 禁止将多个 spec 合并到一个 plan 文件
|
||
- 每个 plan 文件至少拆出该 spec 对应的 20-30 个功能点任务
|
||
- plan 文件编号必须与 spec 文件编号完全一致（spec 有多少个文件，plan 就有多少个同编号文件）
|
||
|
||
`00-plan-overview.md` 中的表格覆盖所有任务（N 列从 1 到最后一个编号），末尾附加一行「总任务数：X」。
|
||
|
||
## 收尾验证任务
|
||
|
||
计划末尾必须包含以下验证任务。这些不是"可选的 nice-to-have"，而是**项目能真正交付的硬性 gate**——任一失败，前面所有 done 的 task 都不算数。以下条目按项目实际形态（服务端 / CLI / 库 / 有无 UI 等）取舍和具体化。
|
||
|
||
### 启动性验证（必须，用真实调用自测，不能只看 import 成功）
|
||
1. **服务/程序可启动**：用项目实际启动命令启动后，若为 HTTP 服务，用 curl 请求健康检查端点，确认返回预期结果；若为 CLI/库，确认能正常加载不报错
|
||
2. **核心页面/入口可访问**（如有 Web 界面）：请求返回预期内容（如含 `<!DOCTYPE html>`）
|
||
3. **核心交互路径（必须）**：模拟一次最小可用的真实请求/调用，返回结果非空、非报错、**非对输入的纯回显**
|
||
4. **CLI 可执行**（如有 CLI）：`--version` / `--help` / 核心子命令等基本命令正常输出
|
||
|
||
### 核心功能验证（必须，逐项用真实调用自测）
|
||
> 这些验证要证明系统实现了真正的业务逻辑，而不是写死的 stub。每项失败必须修复对应实现直到通过。
|
||
> 根据 `docs/specs/00-overview.md` 中列出的核心功能点，逐条列出对应的真实验证项，例如：
|
||
5. 关键业务逻辑对真实/多样化输入返回正确结果（非硬编码模板）
|
||
6. 调用外部依赖（数据库/第三方 API/文件系统等）时确实发生真实调用，而非被绕过
|
||
7. 关键路由/分支/指令能正确处理不同输入并给出对应行为
|
||
8. 异常/降级路径：依赖不可用或输入非法时给出合理的错误提示，而非崩溃或 500
|
||
|
||
### 质量验证（必须）
|
||
9. **测试全过**：运行项目测试命令，全绿，覆盖率达到预设阈值（如 ≥ 80%，视项目要求而定）
|
||
10. **lint 全过**：运行项目 lint 检查命令和格式检查命令，零错误
|
||
11. **check_progress 脚本返回 all tasks done**（exit 0）
|
||
|
||
### E2E（如项目含 UI，使用对应工具，如 Playwright/Cypress 等；无 UI 则跳过本节）
|
||
12. 页面可访问 + 关键元素（标题/输入框等）存在
|
||
13. 关键交互路径走通，结果符合预期（如有对话式交互：发送后双方消息气泡都出现且非空）
|
||
14. 错误处理与重试（如断网模拟）
|
||
15. 深色/浅色模式切换（如项目支持主题，验证 `data-theme` 等属性变化）
|
||
16. 响应式截图（Desktop 1280x800 + Mobile 375x812，视需要）存到 `tests/e2e/screenshots/`
|
||
|
||
### 收尾
|
||
17. 接口一致性检查脚本（如项目需要，路径按项目约定）
|
||
18. git log 验证每个 task 都有对应 commit
|
||
19. check_progress 脚本返回 "all tasks done"（放最后）
|
||
|
||
### ⚠️ 反 stub 约束（写进每个核心功能/服务类 task 的准出标准）
|
||
- **禁止**：`return ""` / `pass` / `raise NotImplementedError` / 纯 echo / 硬编码回复
|
||
- **必须**：调用真实依赖（外部 API / 数据库 / 文件系统等）或包含实际业务逻辑
|
||
- 涉及 server/服务类的 task 必须实际启动 + 用真实请求验证响应，**不能只靠 import 成功或测试通过就标 done**
|
||
- 核心功能的返回结果必须体现真实业务逻辑，而非写死的占位内容
|
||
|
||
## 附加约束
|
||
|
||
- 零占位符：禁止 TBD / TODO / "后续实现"
|
||
- 每个任务独立可执行，不依赖其他任务的"部分完成"
|
||
- 测试必须能先失败：一开始就通过说明测试无效
|
||
- 禁止将多个 spec 模块合并到一个 plan 文件输出
|
||
- spec 中的每个子模块类型应分配独立的任务（如某个 spec 含多个子模块，每个子模块至少 3-4 个功能点任务）
|
||
|
||
---
|
||
|
||
确认后开始。先输出 00-plan-overview.md，过目后再逐个模块输出。
|
||
|
||
全部 plan 输出完毕后，初始化 `progress.json`（从 00-plan-overview.md 末尾的「总任务数」提取 total_tasks，填充 tasks 字段，全部 pending）并生成 check_progress 脚本（语言与项目技术栈一致，逻辑参考 CLAUDE.md 中的示例）。完成后告知用户可进入 Step 3。
|
||
|
||
## ⚠️ progress.json 强制更新规则
|
||
|
||
**任何时候重新执行本提示词，结束前必须做以下操作：**
|
||
|
||
1. **先删旧后重建** `progress.json`：
|
||
- 删除项目根目录现有的 `progress.json`
|
||
- 用 `00-plan-overview.md` 末尾的「总任务数：X」重新生成，tasks 全量 pending
|
||
- `started_at` 和 `updated_at` 使用当前 ISO 8601 时间
|
||
- `total_tasks` 必须与 00-plan-overview.md 末尾数字严格一致
|
||
2. **生成/更新** check_progress 脚本 — 内容固定，直接写入项目根目录
|
||
3. **验证**：运行 check_progress 脚本必须返回非零退出码（表示有 pending 任务）
|
||
|
||
严禁在新 plan 输出完毕后保留旧的 progress.json。如果 progress.json 已经存在且任务数不匹配，必须无条件覆盖。
|