feat(admin): initialize procurement service skeleton

2026-08-03 18:13:30 +08:00
parent b7559a9451
commit c72371ce90
11 changed files with 288 additions and 37 deletions
@@ -85,13 +85,12 @@ cmbuyer 是一个自动化采购系统：**采购服务**（网页端，`admin/`

 ## 当前阶段

-**Phase 0 · 地基（尚未开始编码）。** 仓库目前只有文档，没有生产代码。
+**Phase 0 · 地基。** 采购服务骨架已初始化，采购工具骨架仍在进行；尚无采购业务代码。

 执行按任务依赖驱动，**不按 Phase 整段串行等待**。当前优先路径：

-1. 并行完成 T-001 采购服务骨架与 T-002 采购工具骨架。
-2. T-001 完成后推进 T-004 数据模型；T-002 完成后立即推进
-   **T-101 → T-102 → T-103 真机取证**；两端骨架都完成后可并行补 T-003 统一入口。
+1. 继续完成 T-002 采购工具骨架；采购服务方向可并行推进 T-004 数据模型。
+2. T-002 完成后立即推进 **T-101 → T-102 → T-103 真机取证**，并可并行补 T-003 统一入口。
 3. T-103 结论确认后，才开始依赖真机可读字段的 Phase 2 生产页面；采购服务核心与
   T-104 → T-107 后续真机安全判据按依赖并行推进。
 4. Phase 3：双端打通与**第一趟试选**端到端。
@@ -173,15 +172,17 @@ cmbuyer 是一个自动化采购系统：**采购服务**（网页端，`admin/`

 ## 验证命令

-> **占位符。** T-001 / T-002 落地后由该任务替换为真实命令，并同步
-> [`03-tech-stack.md`](03-tech-stack.md) 和 [`current-state.md`](current-state.md)。
+> 采购服务命令已由 T-001 实际验证；采购工具命令在 T-002 完成前仍是占位路径。

 ```bash
 # 采购服务 admin/（改了 Go 代码后）
+cd admin
 go test ./...
 go vet ./...
+go build ./...

-# 采购工具 client/（改了 Python 代码后）
+# 采购工具 client/（T-002 完成后启用）
+cd client
 python -m unittest discover -s tests -t .
 python -m compileall -q src tests

@@ -59,14 +59,13 @@

 ## 五、构建与运行命令

-> **占位符。** 代码尚未初始化，以下命令分别在 T-001 / T-002 落地后由对应任务替换为真实可运行命令，
-> 并同步到 [`00-ai-start-here.md`](00-ai-start-here.md) 和 [`current-state.md`](current-state.md)。
+> 采购服务命令已由 T-001 实际验证；采购工具命令由 T-002 完成后替换剩余占位项。

 | 用途 | 采购服务（`admin/`） | 采购工具（`client/`） |
 | --- | --- | --- |
 | 安装依赖 | `go mod download` | `python -m venv .venv` + `pip install -r requirements.txt` |
-| 本地开发 | 【T-001 填写】 | 【T-002 填写】 |
-| 构建 | 【T-001 填写】 | 【T-002 填写】 |
+| 本地开发 | `go run ./cmd/server` | 【T-002 填写】 |
+| 构建 | `go build ./...` | 【T-002 填写】 |
 | 测试 | `go test ./...` | `python -m unittest discover -s tests -t .` |
 | 静态检查 | `go vet ./...` | `python -m compileall -q src tests` |

@@ -12,30 +12,29 @@
 ## 当前快照

 - 日期：2026-08-03
- 阶段：**Phase 0 · 地基（先确认原型，尚未开始生产编码）**
+- 阶段：**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 驱动封装；尚无采购业务代码
+- 测试：采购服务 2 项离线单元测试
 - 数据：**无**
- 标准启动路径：`./init.ps1`（Windows）/ `./init.sh`。已存在，以 `admin/go.mod` 和
-  `client/requirements.txt` 判断两端是否初始化；当前会以退出码 3 结束并列出 T-001 / T-002
-  ——这是预期行为
- 标准验证路径：目前只有 `python scripts/validate_agent_context.py` 可跑通
- 当前 blocker：无外部 blocker。T-001 / T-002 尚未落成任务文件和初始化代码；两者是
-  下一波可并行任务。T-002 完成后立即进入 T-101，不等待整个 Phase 0 收尾。
+- 标准启动路径：`./init.ps1`（Windows）/ `./init.sh`。当前会验证采购服务，再因
+  `client/requirements.txt` 尚不存在以退出码 3 提示 T-002——这是预期行为
+- 标准验证路径：`admin/` 下运行 `go test ./...`、`go vet ./...`、`go build ./...`；仓库根运行
+  `python scripts/validate_agent_context.py`
+- 当前 blocker：无外部 blocker。T-002 正在实现；T-004 已因 T-001 完成而可领取。

 ## 当前目录要点

 | 路径 | 状态 | 说明 |
 | --- | --- | --- |
 | `docs/` | 已有 | 项目规范化文档，本次已完整生成 |
-| `docs/tasks/` | 已有（T-005～T-009） | T-005～T-008 已完成；T-009 记录关键路径与并行波次 |
+| `docs/tasks/` | 已有（T-001、T-002、T-005～T-009） | T-001 已完成；T-002 正在进行；其余既有任务已完成 |
 | `docs/design/` | 已有（6 个原型） | web 登录 / 建单 / 工作台 / 详情，desk 采购执行 / 配置；均已人工确认 |
 | `scripts/` | 已有 | 上下文门禁、Vikunja 单向导出与 MCP 启动包装 |
-| `admin/` | **待建** | “采购服务”Go 后端与管理页面（T-001） |
+| `admin/` | 已初始化 | Go 1.23+ / gin / SQLite 骨架与健康检查；无采购业务路由 |
 | `client/` | **待建** | “采购工具”Python 桌面端（T-002） |
 | `init.ps1` / `init.sh` | 已有（骨架） | 统一入口。两端目录建好后由 T-003 补全并验证 |

@@ -44,29 +43,37 @@
 任务状态以 `docs/tasks/` 各任务文件 frontmatter 的 `status` 为准。本节只写项目级摘要：

 - 已完成：T-005（采购服务交互原型）、T-006（采购工具交互原型）、T-007（产品名称与
-  源码目录契约）、T-008（Vikunja 任务权威与单向导出）、T-009（MVP 关键路径与并行波次）。
- **下一步：并行落成并启动 T-001 与 T-002。** T-001 完成后可推进 T-004；T-002 完成后
-  立即推进 T-101 → T-102 → T-103；两端骨架都完成后可并行补 T-003。
+  源码目录契约）、T-008（Vikunja 任务权威与单向导出）、T-009（MVP 关键路径与并行波次），
+  以及 T-001（采购服务 Go 骨架）。
+- 正在进行：T-002（采购工具 Python 骨架）。采购服务方向可并行落成 T-004；T-002 完成后
+  立即推进 T-101 → T-102 → T-103，并可补 T-003 统一入口。
 - T-103 是当前最高优先级和 MVP 生死线。通过前不开发依赖真机可读字段的 Phase 2 生产页面。
 - 已确认原型继续只作信息架构依据；原型假数据不调用真实接口、不驱动真机。真机结论改变
  可读字段时必须先回修原型与交互清单。

 ## 当前可运行内容

-**目前没有可运行的代码。** 唯一可运行的检查：
+采购服务当前可运行：

 ```bash
-# 校验 agent 上下文清单
+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
 ```

-T-001 / T-002 完成后，本节替换为真实命令：
-
-```bash
-# 采购服务 admin/（T-001 后填写）
-# 采购工具 client/（T-002 后填写）
-# 统一入口（T-003 后填写）
-```
+采购工具与统一入口的真实命令分别等待 T-002、T-003 完成后补齐。

 ## 关键背景

@@ -3,7 +3,7 @@ id: T-001
 title: 初始化采购服务 admin Go 骨架
 phase: 0
 deps: []
-status: DOING
+status: DONE
 created: 2026-08-03
 vikunja_task_id: 18
 context_ref: a63bdb8
@@ -18,7 +18,7 @@ write_paths:
  - docs/current-state.md
 ---

-<!-- BEGIN VIKUNJA EXPORT id=18 synced=2026-08-03T09:57:43Z sha256=fffb570a4a2f143a9c935215abc6f19798bf38dcc8358aaac816bbaef30b4538 -->
+<!-- BEGIN VIKUNJA EXPORT id=18 synced=2026-08-03T10:13:08Z sha256=81e7657246ae88d8b8c8c9eeb370989c11a524a7ed2e7bd25d647dc77efd747e -->
 ## 问题 / 背景

 仓库尚无 admin/go.mod 和可运行的采购服务代码，init.ps1 因此按预期以退出码 3 停止。没有稳定的 Go 骨架、健康检查和真实验证命令，后续数据模型与服务端任务无法开始。
@@ -47,7 +47,9 @@ write_paths:

 ## 执行记录

-（暂无）
+### 2026-08-03T10:11:42Z · ila
+
+T-001 实施与主审完成（2026-08-03）：新增 admin Go 1.23 模块、gin 路由、GET /healthz、mattn/go-sqlite3 封装及 2 项离线测试；未实现业务路由、真机判据、下单或付款。主 agent 逐文件审查并独立运行：go mod tidy；gofmt -d .（无差异）；go test -count=1 -race ./...（2 项通过）；go vet ./...；go build ./...；python scripts/validate_agent_context.py；init.ps1（按 T-002 未完成预期退出 3）。已更新 admin 的真实运行/验证文档。风险：go-sqlite3 依赖 CGO；init.ps1 的“仓库只有文档”旧提示留给 T-003 修正。
 <!-- END VIKUNJA EXPORT -->

 ## 边界