docs: establish MVP safety and prototype baseline

2026-08-03 12:13:39 +08:00
commit dfe3d56428
31 changed files with 3513 additions and 0 deletions
@@ -0,0 +1,89 @@
+# 任务文件
+
+> 默认一任务一文件：`docs/tasks/T-<编号>.md`。
+> 路线图（[`../06-tasks.md`](../06-tasks.md)）只负责建议拆分，不跟踪状态。
+
+## 命名与状态
+
+- 文件名：`T-001.md`；细分任务用 `T-001a.md`。
+- 状态：`TODO`、`DOING`、`DONE`、`BLOCKED`。
+- 路线图已有编号时沿用；新编号不得覆盖已存在文件。
+- `_template.md` 不是任务。
+
+## 编号段位
+
+| 段位 | 阶段 |
+| --- | --- |
+| T-0xx | Phase 0 地基 |
+| T-1xx | Phase 1 真机取证 |
+| T-2xx | Phase 2 web 端核心 |
+| T-3xx | Phase 3 双端打通与第一趟试选 |
+| T-4xx | Phase 4 第二趟下单与收尾 |
+| T-5xx | V2 及以后（图搜、Excel、ERP、订单核对、AI 辅助） |
+
+## 领取规则
+
+1. 每个 agent 同时最多一个 `DOING` 任务。
+2. 领取编号最小、状态 `TODO`、依赖全部 `DONE` 的任务。
+3. 开工前写清 `write_paths`；与其他活跃任务路径重叠时不得并行。
+4. 记录默认分支头 `context_ref` 和工作分支。
+5. 状态改为 `DOING` 后再修改生产代码。
+6. 验收全部有证据后改 `DONE`；无法继续时标 `BLOCKED` 并写清所需外部输入。
+
+## 任务文件结构
+
+```yaml
+---
+id: T-101
+title: 一句话任务名
+phase: 1
+deps: [T-002]
+status: TODO
+created: 2026-08-03
+context_ref: null
+work_branch: null
+needs_device: true          # 是否需要真机验收
+needs_human_review: false   # 是否需要人审原型 / 文案 / 决策后才能 DONE
+write_paths:
+  - docs/tasks/T-101.md
+  - desk/src/android/**
+  - desk/tests/**
+---
+```
+
+正文必须包含：
+
+- 问题 / 背景
+- 关联需求与交互
+- 方案
+- 验收要点
+- 边界
+- 执行记录
+
+## 验证证据
+
+执行记录至少写：
+
+- 修改的文件。
+- 实际运行的**完整命令**（含参数）。
+- 结果是成功、失败还是未运行。
+- 未验证范围与 blocker。
+
+涉及真机的任务，额外必须写：
+
+- 设备型号、Android 版本、连接方式（USB / WiFi）。
+- **拼多多 App 版本。**
+- 使用的 `goods_id`（若涉及具体商品）。
+- 截图与页面 XML 的产物路径。
+- 是否触发了创建订单的动作；若触发，订单是否已产生、如何处置。
+- 安全停止证据（若涉及）。
+
+## 硬规则
+
+- **「代码写完」「看起来可以」不能作为 `DONE` 证据。**
+- **`needs_device: true` 的任务，agent 不得自行标 `DONE`。** 真机验收只能由人完成；
+  agent 保持 `DOING` 并写明等待人工验收的具体事项。
+- **`needs_human_review: true` 的任务，agent 完成可自动验证部分后仍保持 `DOING`。** 执行记录
+  必须列出给人检查的文件、关键状态和确认问题；只有人明确确认后才能改 `DONE`。
+- 涉及 [`../04-architecture.md`](../04-architecture.md) 第四节安全边界的任务，执行记录
+  必须列出对应的测试用例名。
@@ -0,0 +1,49 @@
+---
+id: T-XXX
+title: 一句话任务名
+phase: 0
+deps: []
+status: TODO
+created: YYYY-MM-DD
+context_ref: null
+work_branch: null
+needs_device: false
+needs_human_review: false
+write_paths:
+  - docs/tasks/T-XXX.md
+  - path/to/allowed/module/**
+---
+
+## 问题 / 背景
+
+说明当前事实、为什么要做，以及不做会阻塞什么。
+
+## 关联需求与交互
+
+- 功能：F-XXX
+- 用户故事：US-XXX
+- 交互：IX-XXX；无界面时写不适用
+- 架构 / API：对应章节
+
+## 方案
+
+按文件和模块写清怎么实现、如何处理失败、安全边界如何保证。
+
+涉及 `04-architecture.md` 第四节安全边界时，逐条列出本任务触及哪些边界、用哪个测试
+用例证明未被放宽。
+
+## 验收要点
+
+- 写明可观察结果。
+- 写明实际验证命令。
+- 涉及真机时写明取证要求（设备、Android 版本、**拼多多 App 版本**、产物路径）。
+- 涉及不可逆动作时写明安全停止证据。
+- 涉及人工评审时写明评审入口、检查清单和未确认项；确认前不得标 `DONE`。
+
+## 边界
+
+明确不修改的模块、不实现的后续功能、不得放宽的既有约束。
+
+## 执行记录
+
+开工后记录修改、命令、结果、环境、决策和 blocker。