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,109 @@
+# 当前实现状态
+
+> 本文是可覆盖的**项目级快照**，记录代码与任务的现实状态。
+> 执行记录写进各任务文件（`docs/tasks/T-<编号>.md`）的 `## 执行记录`，不在本文重复维护。
+
+## 职责边界
+
+- [`tasks/`](tasks/README.md)：任务规格、依赖、状态（frontmatter）和执行记录，一任务一文件。
+- [`06-tasks.md`](06-tasks.md)：只读路线图，维护阶段划分、里程碑和待办池。
+- `current-state.md`：当前快照，可覆盖更新。
+
+## 当前快照
+
+- 日期：2026-08-03
+- 阶段：**Phase 0 · 地基（先确认原型，尚未开始生产编码）**
+- MVP 形态：手工填链接建单 → 定时轮询 → **第一趟试选** → 人工确认 → **第二趟下单** → 待付款
+- 技术栈：已定。web 端 Go 1.23+ / gin / SQLite；desk 端 Python 3.11+ / uiautomator2 / PySide6。
+  详见 [`03-tech-stack.md`](03-tech-stack.md)
+- 生产代码：**无**。仓库目前只有文档
+- 测试：**无**
+- 数据：**无**
+- 标准启动路径：`./init.ps1`（Windows）/ `./init.sh`。已存在但会因两端目录未初始化而以
+  退出码 3 结束并列出待办任务——这是预期行为
+- 标准验证路径：目前只有 `python scripts/validate_agent_context.py` 可跑通
+- 当前 blocker：生产 UI 实现需先完成人工确认原型；下一步先落成并并行执行 T-005 / T-006。
+
+## 当前目录要点
+
+| 路径 | 状态 | 说明 |
+| --- | --- | --- |
+| `docs/` | 已有 | 项目规范化文档，本次已完整生成 |
+| `docs/tasks/` | 已有（空） | 任务文件目录，含 `README.md` 与 `_template.md` |
+| `docs/design/` | 已有（仅约定） | 原型目录；下一步生成 `web-*.html` 与 `desk-*.html` |
+| `scripts/` | 已有 | `validate_agent_context.py` |
+| `web/` | **待建** | Go 后端与管理页面（T-001） |
+| `desk/` | **待建** | Python 桌面端（T-002） |
+| `init.ps1` / `init.sh` | 已有（骨架） | 统一入口。两端目录建好后由 T-003 补全并验证 |
+
+## 任务状态
+
+任务状态以 `docs/tasks/` 各任务文件 frontmatter 的 `status` 为准。本节只写项目级摘要：
+
+- 已完成：无。
+- 正在进行：无。
+- **下一个可领取任务：T-005（网页端 MVP 交互原型）与 T-006（桌面端 MVP 交互原型）。**
+  两者无相互依赖、使用 `web-*` / `desk-*` 文件名前缀且 `write_paths` 不重叠，可并行。
+- 原型使用假数据、不调用真实接口、不驱动真机；经人工确认前任务保持 `DOING`。
+- T-001 / T-002 骨架仍可在原型确认后并行，Phase 2 生产页面必须等待相关真机结论。
+
+## 当前可运行内容
+
+**目前没有可运行的代码。** 唯一可运行的检查：
+
+```bash
+# 校验 agent 上下文清单
+python scripts/validate_agent_context.py
+```
+
+T-001 / T-002 完成后，本节替换为真实命令：
+
+```bash
+# web 端（T-001 后填写）
+# desk 端（T-002 后填写）
+# 统一入口（T-003 后填写）
+```
+
+## 关键背景
+
+本项目是 `cmroubao`（Go 后端 + Android AccessibilityService）与 `cmpdd`
+（Python + uiautomator2）两个前序项目的合并重启。
+
+- 取 `cmroubao` 的后端任务生命周期、设备侧 API 形状、下单授权状态机、ERP 对接、管理 Web。
+- 取 `cmpdd` 的 uiautomator2 真机自动化、按维度精确选规格、订单确认页读取、付款闸门。
+- 丢弃自研 Android APK 与 AccessibilityService 感知层。
+
+**前序项目是设计依据，不是事实来源。** 其中的结论（尤其是拼多多页面判据）必须在本项目
+用真机重新验证，且记录取证时的拼多多 App 版本。
+
+## 已知风险（开工前须知）
+
+1. **M2 是生死线**：真机能按链接打开商品、精确勾选颜色分类和尺码、**读到该 SKU 单价**
+   （T-103）。Phase 1 不通过之前不要写生产页面；Phase 0 原型只确认流程和信息架构，真机
+   结论改变字段时必须回修。
+2. **拼多多页面结构随版本变化**，已观察到详情页无独立规格入口、价格节点被拆分等情况。
+3. **授权卡死**：前序项目出现过 `EXECUTING` 授权永不推进导致任务锁死。本项目在 T-207
+   实现围栏前超时 / 放弃，在 T-208 实现围栏后调和；围栏后不得释放或重试。
+4. **规格面板单价位置未取证**：闸门一依赖它，T-103 必须一并取证。若读不可靠，
+   确认页设计要改。
+5. **MVP 已收窄**：只做手工填链接 + 两趟执行。Excel、ERP、图搜、订单自动核对、
+   AI 辅助全部推到 V2（见 `06-tasks.md` 的 T-501~T-508）。
+6. **App 版本必须 fail closed**：运行时拼多多版本与本项目已取证版本不一致就停止领取，
+   不允许用旧判据继续跑。
+
+## 开始编码前检查
+
+1. 读 [`../AGENTS.md`](../AGENTS.md)。
+2. 读 [`00-ai-start-here.md`](00-ai-start-here.md)，特别是「本项目的四条特有纪律」。
+3. 读 [`05-coding-rules.md`](05-coding-rules.md)，特别是第 1 节红线。
+4. 在 `docs/tasks/` 找 `status: TODO` 且依赖均 `DONE` 的任务文件；暂无时先按
+   [`06-tasks.md`](06-tasks.md) 落成任务文件。
+5. 在独立分支 / worktree 把任务改为 `DOING` 后再改生产代码。
+
+## 维护规则
+
+实际代码状态变化时同步更新本文：新增或移动入口文件、初始化框架、新增可运行命令、
+发现文档与代码不一致、阶段或 blocker 变化。
+
+任务长期状态改在对应任务文件的 frontmatter；每轮执行记录、验证命令、阻塞点和关键决策
+写进该任务文件的 `## 执行记录`。本文只保留当前快照，不保留完整历史。