149 lines
7.8 KiB
Markdown
149 lines
7.8 KiB
Markdown
# 当前实现状态
|
||
|
||
> 本文是可覆盖的**项目级快照**，记录代码与任务的现实状态。
|
||
> 执行记录写进各任务文件（`docs/tasks/T-<编号>.md`）的 `## 执行记录`，不在本文重复维护。
|
||
|
||
## 职责边界
|
||
|
||
- [`tasks/`](tasks/README.md)：任务规格、依赖、状态（frontmatter）和执行记录，一任务一文件。
|
||
- [`06-tasks.md`](06-tasks.md)：只读路线图，维护阶段划分、里程碑和待办池。
|
||
- `current-state.md`：当前快照，可覆盖更新。
|
||
|
||
## 当前快照
|
||
|
||
- 日期：2026-08-03
|
||
- 阶段：**Phase 0 · 地基（采购服务与采购工具骨架已初始化，尚无采购业务代码）**
|
||
- MVP 形态：手工填链接建单 → 批量开始试选 → 定时轮询 → **第一趟试选** → 人工确认 → **第二趟下单** → 待付款
|
||
- 技术栈：已定。采购服务（`admin/`）使用 Go 1.23+ / gin / SQLite；采购工具（`client/`）
|
||
使用 Python 3.11+ / uiautomator2 / PySide6。
|
||
详见 [`03-tech-stack.md`](03-tech-stack.md)
|
||
- 生产代码：`admin/` 已有最小 Go 服务、`GET /healthz` 与 SQLite 驱动封装；`client/` 已有
|
||
Python 包、PySide6 最小入口、运行目录与日志脱敏策略；两端均尚无采购业务代码
|
||
- 测试：采购服务 2 项离线单元测试；采购工具 6 项离线单元测试（不连接真机）
|
||
- 数据：**无**
|
||
- 标准启动路径：`./init.ps1`（Windows）/ `./init.sh`。两端骨架现已存在，但 `init.ps1` 仍使用
|
||
默认 Python 3.10，不能正确验证要求 Python 3.11+ 的采购工具；T-003 负责统一入口与解释器选择。
|
||
- 标准验证路径：`admin/` 下运行 `go test ./...`、`go vet ./...`、`go build ./...`；`client/` 下使用
|
||
`py -3.12 -m unittest discover -s tests -t .`、`py -3.12 -m compileall -q src tests scripts`；仓库根运行
|
||
`python scripts/validate_agent_context.py`
|
||
- 当前 blocker：无外部 blocker。T-002 已完成；T-004 核心数据模型正在进行；T-003 统一入口与
|
||
T-101 真机环境盘点已就绪。当前不宣称统一入口或桌面 GUI 已验收。
|
||
|
||
## 当前目录要点
|
||
|
||
| 路径 | 状态 | 说明 |
|
||
| --- | --- | --- |
|
||
| `docs/` | 已有 | 项目规范化文档，本次已完整生成 |
|
||
| `docs/tasks/` | 已有（T-001、T-002、T-004～T-009） | T-001、T-002 已完成；T-004 正在进行；其余既有任务已完成 |
|
||
| `docs/design/` | 已有（6 个原型） | web 登录 / 建单 / 工作台 / 详情，desk 采购执行 / 配置；均已人工确认 |
|
||
| `scripts/` | 已有 | 上下文门禁、Vikunja 单向导出与 MCP 启动包装 |
|
||
| `admin/` | 已初始化 | Go 1.23+ / gin / SQLite 骨架与健康检查；无采购业务路由 |
|
||
| `client/` | 已初始化 | Python 3.11+ 包、依赖源、PySide6 最小入口、离线测试与 wheel 元数据检查；无真机或采购流程 |
|
||
| `init.ps1` / `init.sh` | 已有（骨架） | 统一入口。两端目录建好后由 T-003 补全并验证 |
|
||
|
||
## 任务状态
|
||
|
||
任务状态以 `docs/tasks/` 各任务文件 frontmatter 的 `status` 为准。本节只写项目级摘要：
|
||
|
||
- 已完成：T-005（采购服务交互原型）、T-006（采购工具交互原型）、T-007（产品名称与
|
||
源码目录契约）、T-008（Vikunja 任务权威与单向导出）、T-009（MVP 关键路径与并行波次），
|
||
以及 T-001（采购服务 Go 骨架）。
|
||
- 已完成：T-002（采购工具 Python 骨架）。正在进行：T-004（核心数据模型）。
|
||
T-003（统一入口）与 T-101（真机环境盘点）已就绪，立即推进 T-101 → T-102 → T-103。
|
||
- T-103 是当前最高优先级和 MVP 生死线。通过前不开发依赖真机可读字段的 Phase 2 生产页面。
|
||
- 已确认原型继续只作信息架构依据；原型假数据不调用真实接口、不驱动真机。真机结论改变
|
||
可读字段时必须先回修原型与交互清单。
|
||
|
||
## 当前可运行内容
|
||
|
||
采购服务当前可运行：
|
||
|
||
```bash
|
||
cd admin
|
||
go mod download
|
||
go run ./cmd/server
|
||
```
|
||
|
||
采购服务验证与仓库级上下文门禁：
|
||
|
||
```bash
|
||
cd admin
|
||
go test ./...
|
||
go vet ./...
|
||
go build ./...
|
||
|
||
cd ..
|
||
python scripts/validate_agent_context.py
|
||
```
|
||
|
||
采购工具当前可运行的离线验证与 wheel 元数据检查：
|
||
|
||
```powershell
|
||
cd client
|
||
py -3.12 -m unittest discover -s tests -t .
|
||
py -3.12 -m compileall -q src tests scripts
|
||
$wheelDir = Join-Path $env:TEMP ('cmbuyer-client-wheel-' + [guid]::NewGuid())
|
||
New-Item -ItemType Directory -Path $wheelDir | Out-Null
|
||
py -3.12 -m pip wheel --no-deps . --wheel-dir $wheelDir
|
||
py -3.12 scripts/verify_wheel_metadata.py (Get-ChildItem $wheelDir -Filter '*.whl').FullName
|
||
```
|
||
|
||
采购工具规范安装与本地开发入口：
|
||
|
||
```powershell
|
||
cd client
|
||
py -3.12 -m venv .venv
|
||
.\.venv\Scripts\python.exe -m pip install -e .
|
||
.\.venv\Scripts\python.exe -m cmbuyer_client
|
||
```
|
||
|
||
`client/requirements.txt` 是唯一依赖来源，`client/pyproject.toml` 动态读取它生成 wheel 的
|
||
`Requires-Dist`。Python 3.12 已验证 6 项离线测试、编译与 wheel 元数据；完整运行时依赖安装
|
||
（`pip install -e .`）已通过。`init.ps1` 当前仍选择 Python 3.10，因此不能声称统一入口已正确；
|
||
桌面 GUI 与真机流程未作为 T-002 验收执行。
|
||
|
||
## 关键背景
|
||
|
||
本项目是 `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；每轮执行记录、验证命令、阻塞点和关键决策
|
||
写进该任务文件的 `## 执行记录`。本文只保留当前快照，不保留完整历史。
|