build: establish unified project entry
This commit is contained in:
QiuSW
+16
-12
@@ -89,8 +89,8 @@ cmbuyer 是一个自动化采购系统：**采购服务**（网页端，`admin/`
|
||||
|
||||
执行按任务依赖驱动，**不按 Phase 整段串行等待**。当前优先路径：
|
||||
|
||||
1. T-004 核心数据模型正在进行；T-003 统一入口与 T-101 真机环境盘点可开始。
|
||||
2. T-002 已完成，立即推进 **T-101 → T-102 → T-103 真机取证**，并可并行补 T-003 统一入口。
|
||||
1. T-003 统一入口与 T-004 核心数据模型已完成；T-101 真机环境盘点已就绪，但尚未真机验收。
|
||||
2. T-002 已完成，立即推进 **T-101 → T-102 → T-103 真机取证**。
|
||||
3. T-103 结论确认后，才开始依赖真机可读字段的 Phase 2 生产页面；采购服务核心与
|
||||
T-104 → T-107 后续真机安全判据按依赖并行推进。
|
||||
4. Phase 3：双端打通与**第一趟试选**端到端。
|
||||
@@ -172,25 +172,29 @@ cmbuyer 是一个自动化采购系统：**采购服务**（网页端，`admin/`
|
||||
|
||||
## 验证命令
|
||||
|
||||
> 采购服务命令已由 T-001 实际验证；采购工具的离线测试、编译和 wheel 元数据命令已由
|
||||
> Python 3.12 实际验证。当前默认 `python` 是 Python 3.10.11，统一入口尚未正确选择
|
||||
> Python 3.11+，此缺口由 T-003 修复。
|
||||
> Windows 标准入口 `./init.ps1` 已由 T-003 实际验证。它优先使用合规的既有 venv（本机实际为
|
||||
> Python 3.12），仅在 venv 缺失时才从 Python Launcher 自动选择最高的 Python 3.11+，避免回退到
|
||||
> 默认 Python 3.10；通过后会输出两端真实启动命令。
|
||||
|
||||
```powershell
|
||||
# Windows 统一安装、离线验证与启动命令提示
|
||||
.\init.ps1
|
||||
|
||||
# 以下为诊断或单独验证时使用的等价命令
|
||||
# 采购服务 admin/（改了 Go 代码后）
|
||||
cd admin
|
||||
go test ./...
|
||||
go vet ./...
|
||||
go build ./...
|
||||
|
||||
# 采购工具 client/（使用 Python 3.11+；本机已验证 3.12）
|
||||
# 采购工具 client/（由 init.ps1 创建的 Python 3.11+ 虚拟环境）
|
||||
cd client
|
||||
py -3.12 -m unittest discover -s tests -t .
|
||||
py -3.12 -m compileall -q src tests scripts
|
||||
.\.venv\Scripts\python.exe -m unittest discover -s tests -t .
|
||||
.\.venv\Scripts\python.exe -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
|
||||
.\.venv\Scripts\python.exe -m pip wheel --no-deps . --wheel-dir $wheelDir
|
||||
.\.venv\Scripts\python.exe scripts/verify_wheel_metadata.py (Get-ChildItem $wheelDir -Filter '*.whl').FullName
|
||||
|
||||
# 跨端契约改动：两端全跑
|
||||
```
|
||||
@@ -198,5 +202,5 @@ py -3.12 scripts/verify_wheel_metadata.py (Get-ChildItem $wheelDir -Filter '*.wh
|
||||
验证层级何时触发见 [`03-tech-stack.md`](03-tech-stack.md) 第六节验证矩阵。
|
||||
`requirements.txt` 是采购工具唯一的运行时依赖来源，`pyproject.toml` 动态读取它写入 wheel
|
||||
元数据。规范安装是 Python 3.11+ 虚拟环境中的 `python -m pip install -e .`，已由 Python 3.12
|
||||
验证通过；桌面 GUI 和真机流程不属于本次验收。`init.ps1` 仍未正确选择 Python 3.11+，统一入口
|
||||
由 T-003 修复。若命令当前不可运行，必须在回复里如实说明原因。
|
||||
验证通过；桌面 GUI 和真机流程不属于本次验收。`init.ps1` 使用合规既有 venv，或在缺失时自动选择
|
||||
Python 3.11+ 创建它；本机现有 venv 实际验证为 3.12。若命令当前不可运行，必须在回复里如实说明原因。
|
||||
|
||||
+19
-11
@@ -59,25 +59,33 @@
|
||||
|
||||
## 五、构建与运行命令
|
||||
|
||||
> 采购服务命令已由 T-001 实际验证。采购工具以下离线测试、编译和 wheel 元数据命令已由
|
||||
> Python 3.12 实际验证；桌面 GUI 和真机流程不属于 T-002 验收范围。
|
||||
> `init.ps1` 已由 T-003 在 Windows PowerShell 实际验证：它优先复用合规的既有采购工具虚拟环境
|
||||
> （本机实际为 Python 3.12）；仅在虚拟环境不存在时，才从 Python Launcher 的已安装版本中确定性选择
|
||||
> 最高的 Python 3.11+ 创建它，以 editable 方式安装采购工具，并跑两端
|
||||
> 离线门禁。桌面 GUI 和真机流程不属于该入口的验收范围。
|
||||
|
||||
| 用途 | 采购服务（`admin/`） | 采购工具（`client/`） |
|
||||
| --- | --- | --- |
|
||||
| 安装依赖 | `go mod download` | `py -3.12 -m venv .venv` 后运行 `.\.venv\Scripts\python.exe -m pip install -e .` |
|
||||
| 安装依赖 | `go mod download` | Windows 运行 `./init.ps1`；它复用合规 venv，或选择 Python Launcher 中最高的 Python 3.11+ 创建 venv 后执行 `pip install -e .` |
|
||||
| 本地开发 | `go run ./cmd/server` | `.\.venv\Scripts\python.exe -m cmbuyer_client` |
|
||||
| 构建 | `go build ./...` | `py -3.12 -m pip wheel --no-deps . --wheel-dir <输出目录>`，再运行 `py -3.12 scripts/verify_wheel_metadata.py <wheel 路径>` |
|
||||
| 测试 | `go test ./...` | `py -3.12 -m unittest discover -s tests -t .` |
|
||||
| 静态检查 | `go vet ./...` | `py -3.12 -m compileall -q src tests scripts` |
|
||||
| 构建 | `go build ./...` | `.\.venv\Scripts\python.exe -m pip wheel --no-deps . --wheel-dir <输出目录>`，再运行 `.\.venv\Scripts\python.exe scripts/verify_wheel_metadata.py <wheel 路径>` |
|
||||
| 测试 | `go test ./...` | `.\.venv\Scripts\python.exe -m unittest discover -s tests -t .` |
|
||||
| 静态检查 | `go vet ./...` | `.\.venv\Scripts\python.exe -m compileall -q src tests scripts` |
|
||||
|
||||
Windows 的标准入口是仓库根 `./init.ps1`。它要求 Go、两端目录及其哨兵文件存在；已有合规
|
||||
`client/.venv` 时，所有采购工具检查与 validator 都使用该解释器。只有 venv 不存在时，才从 `py -0p`
|
||||
枚举的版本中确定性选择最高的 Python 3.11+ 创建它；没有合规版本时明确失败，绝不回退默认 `python`。
|
||||
它执行 admin 的 `go mod download` / test / vet / build、client 的 editable install / 包导入 / unittest /
|
||||
compileall。既有 `client/.venv` 若不是 Python 3.11+ 会明确失败，不会自动覆盖用户环境。`init.sh` 保持等价门禁语义；WSL 或 Unix 环境缺少所需 Go、Python 3.11+
|
||||
或项目文件时必须非零退出，语法通过或 Unix 成功不构成 Windows / 真机验收。
|
||||
|
||||
采购工具的运行时依赖只维护在 `client/requirements.txt`。`client/pyproject.toml` 通过 setuptools
|
||||
动态读取该文件生成 wheel 的 `Requires-Dist`，避免两份依赖列表漂移；
|
||||
`scripts/verify_wheel_metadata.py` 会验证生成 wheel 已声明全部这些依赖。
|
||||
|
||||
当前 Windows 默认 `python` 指向 Python 3.10.11，不满足采购工具的 Python 3.11+ 下限，
|
||||
不得把未加版本选择器的 `python` 当作采购工具的已验证命令。T-003 负责统一入口与解释器选择；
|
||||
在此之前使用 `py -3.12` 或 Python 3.11+ 虚拟环境。Python 3.12 虚拟环境中的完整
|
||||
`pip install -e .` 已验证通过；桌面 GUI 与真机流程不属于 T-002 验收范围。
|
||||
当前 Windows 默认 `python` 仍可能指向 Python 3.10，不满足采购工具的 Python 3.11+ 下限；
|
||||
不得把未加版本选择器的 `python` 当作采购工具命令。统一入口优先使用既有合规 venv，仅在需要创建时
|
||||
自动选择 Launcher 中最高的合规版本；本机现有 venv 实际为 Python 3.12。桌面 GUI 与真机流程不属于 T-003 验收范围。
|
||||
|
||||
Windows PowerShell 差异：
|
||||
|
||||
@@ -90,7 +98,7 @@ $env:GOTOOLCHAIN = "local"
|
||||
|
||||
| 层级 | 触发条件 | 命令 / 操作 | 通过证据 |
|
||||
| --- | --- | --- | --- |
|
||||
| 任务相关验证 | 每个任务必跑 | 改 `admin/` 跑 `go test ./...` + `go vet ./...`；改 `client/` 跑 `py -3.12 -m unittest discover -s tests -t .` + `py -3.12 -m compileall -q src tests scripts` | 退出码 0、测试数 |
|
||||
| 任务相关验证 | 每个任务必跑 | 改 `admin/` 跑 `go test ./...` + `go vet ./...`；改 `client/` 跑 `.venv\Scripts\python.exe -m unittest discover -s tests -t .` + `.venv\Scripts\python.exe -m compileall -q src tests scripts` | 退出码 0、测试数 |
|
||||
| 完整门禁 | 发布前；修改 HTTP 契约、数据库 schema、依赖或构建配置时；跨端改动时 | 两端全部测试 + 静态检查 + 两端构建 | 退出码 0、测试数、产物路径 |
|
||||
| 人工 / 设备验收 | 任何涉及真机页面判据、下单动作或付款路径的任务 | 连接真机执行，记录设备型号、Android 版本、拼多多版本、goods_id、截图与页面 XML 路径 | 人工结论 + 证据文件路径 |
|
||||
|
||||
|
||||
+34
-39
@@ -12,34 +12,35 @@
|
||||
## 当前快照
|
||||
|
||||
- 日期：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 驱动封装；`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 已验收。
|
||||
- 生产代码：`admin/` 已有最小 Go 服务、健康检查、核心领域模型、SQLite 迁移与任务状态机；
|
||||
`client/` 已有 Python 包、PySide6 最小入口、运行目录与日志脱敏策略；尚无真机采购流程
|
||||
- 测试：采购服务已覆盖健康检查、核心模型、迁移与状态机等离线包级测试；采购工具 6 项离线单元测试
|
||||
（不连接真机）
|
||||
- 数据：SQLite 核心表与迁移已落成；无业务实例数据
|
||||
- 标准启动路径：Windows PowerShell 运行 `./init.ps1`，Unix shell 运行 `./init.sh`。Windows 入口
|
||||
优先使用合规的既有 venv；仅在其缺失时才从 Python Launcher 已安装版本中选择最高的 Python 3.11+，
|
||||
并且不覆盖低版本环境；成功后打印真实启动命令。
|
||||
- 标准验证路径：`./init.ps1` 已实际跑通 admin 的 mod download / test / vet / build、client 的
|
||||
editable install / 包导入 / unittest / compileall，以及仓库上下文校验。可单独运行两端命令诊断。
|
||||
- 当前 blocker：无外部 blocker。T-002、T-003、T-004 已完成；T-101 真机环境盘点已就绪，
|
||||
但尚未真机验收。桌面 GUI 与真机流程尚未验收。
|
||||
|
||||
## 当前目录要点
|
||||
|
||||
| 路径 | 状态 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `docs/` | 已有 | 项目规范化文档，本次已完整生成 |
|
||||
| `docs/tasks/` | 已有（T-001、T-002、T-004～T-009） | T-001、T-002 已完成；T-004 正在进行；其余既有任务已完成 |
|
||||
| `docs/tasks/` | 已有（T-001～T-004、T-005～T-009、T-101） | T-001～T-004 已完成；T-101 已就绪、待真机验收 |
|
||||
| `docs/design/` | 已有（6 个原型） | web 登录 / 建单 / 工作台 / 详情，desk 采购执行 / 配置；均已人工确认 |
|
||||
| `scripts/` | 已有 | 上下文门禁、Vikunja 单向导出与 MCP 启动包装 |
|
||||
| `admin/` | 已初始化 | Go 1.23+ / gin / SQLite 骨架与健康检查；无采购业务路由 |
|
||||
| `admin/` | 已初始化 | Go 1.23+ / gin / SQLite，含核心模型、迁移与状态机；无真机采购执行 |
|
||||
| `client/` | 已初始化 | Python 3.11+ 包、依赖源、PySide6 最小入口、离线测试与 wheel 元数据检查；无真机或采购流程 |
|
||||
| `init.ps1` / `init.sh` | 已有（骨架） | 统一入口。两端目录建好后由 T-003 补全并验证 |
|
||||
| `init.ps1` / `init.sh` | 已完成 | 统一安装与离线验证入口；PowerShell 优先复用合规 venv，缺失时自动选择最高的 Python 3.11+，Unix 缺工具链明确失败 |
|
||||
|
||||
## 任务状态
|
||||
|
||||
@@ -48,59 +49,53 @@
|
||||
- 已完成：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-002（采购工具 Python 骨架）、T-003（双端统一初始化与验证入口）、
|
||||
T-004（核心数据模型）。T-101（真机环境盘点）已建档并就绪，尚未真机验收，接续推进
|
||||
T-101 → T-102 → T-103。
|
||||
- T-103 是当前最高优先级和 MVP 生死线。通过前不开发依赖真机可读字段的 Phase 2 生产页面。
|
||||
- 已确认原型继续只作信息架构依据；原型假数据不调用真实接口、不驱动真机。真机结论改变
|
||||
可读字段时必须先回修原型与交互清单。
|
||||
|
||||
## 当前可运行内容
|
||||
|
||||
采购服务当前可运行：
|
||||
Windows 统一安装、离线验证与启动命令提示已可运行：
|
||||
|
||||
```bash
|
||||
cd admin
|
||||
go mod download
|
||||
go run ./cmd/server
|
||||
```powershell
|
||||
.\init.ps1
|
||||
```
|
||||
|
||||
采购服务验证与仓库级上下文门禁：
|
||||
它会在成功后输出以下真实启动命令，而不自动启动或连接设备：
|
||||
|
||||
```bash
|
||||
cd admin
|
||||
go test ./...
|
||||
go vet ./...
|
||||
go build ./...
|
||||
|
||||
cd ..
|
||||
python scripts/validate_agent_context.py
|
||||
```text
|
||||
采购服务：cd admin; go run ./cmd/server
|
||||
采购工具：cd client; .\.venv\Scripts\python.exe -m cmbuyer_client
|
||||
```
|
||||
|
||||
采购工具当前可运行的离线验证与 wheel 元数据检查：
|
||||
|
||||
```powershell
|
||||
cd client
|
||||
py -3.12 -m unittest discover -s tests -t .
|
||||
py -3.12 -m compileall -q src tests scripts
|
||||
.\.venv\Scripts\python.exe -m unittest discover -s tests -t .
|
||||
.\.venv\Scripts\python.exe -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
|
||||
.\.venv\Scripts\python.exe -m pip wheel --no-deps . --wheel-dir $wheelDir
|
||||
.\.venv\Scripts\python.exe scripts/verify_wheel_metadata.py (Get-ChildItem $wheelDir -Filter '*.whl').FullName
|
||||
```
|
||||
|
||||
采购工具规范安装与本地开发入口：
|
||||
|
||||
```powershell
|
||||
# 在仓库根执行统一初始化；成功后再进入 client/
|
||||
.\init.ps1
|
||||
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 验收执行。
|
||||
（`pip install -e .`）已通过。`init.ps1` 优先使用合规既有 venv，缺失时自动选择最高的 Python 3.11+；
|
||||
本机现有 venv 实际验证为 Python 3.12。桌面 GUI 与真机流程未作为 T-003 验收执行。
|
||||
|
||||
## 关键背景
|
||||
|
||||
|
||||
+7
-3
@@ -3,7 +3,7 @@ id: T-003
|
||||
title: 建立双端统一初始化与验证入口
|
||||
phase: 0
|
||||
deps: [T-001, T-002]
|
||||
status: DOING
|
||||
status: DONE
|
||||
created: 2026-08-03
|
||||
vikunja_task_id: 20
|
||||
context_ref: bcec012
|
||||
@@ -19,7 +19,7 @@ write_paths:
|
||||
- docs/current-state.md
|
||||
---
|
||||
|
||||
<!-- BEGIN VIKUNJA EXPORT id=20 synced=2026-08-03T10:35:06Z sha256=24a880be86ebfda9b3176ed3fdbfae289c750427baa67eaa5207e4eb69a1841e -->
|
||||
<!-- BEGIN VIKUNJA EXPORT id=20 synced=2026-08-03T10:55:26Z sha256=ded66098a74140a3738f1afd64299eb429325a72fdd018aeb1dabbedc89cca56 -->
|
||||
## 问题 / 背景
|
||||
|
||||
T-001 与 T-002 已建立两端可运行骨架，但仓库根 init.ps1 / init.sh 仍沿用占位命令：Windows 默认 Python 3.10 不满足 client 的 Python 3.11+ 下限，桌面端仍按 requirements.txt 安装而不是规范的 editable package，启动命令也指向不存在的 src/main.py。统一入口若不能主动验证工具链和两端基线，后续任务会在错误环境上叠加实现。
|
||||
@@ -48,7 +48,11 @@ T-001 与 T-002 已建立两端可运行骨架，但仓库根 init.ps1 / init.sh
|
||||
|
||||
## 执行记录
|
||||
|
||||
（暂无）
|
||||
### 2026-08-03T10:54:57Z · ila
|
||||
|
||||
主 agent 终审通过：init.ps1/init.sh 已成为双端统一安装与离线门禁入口；不启动产品、不连接设备、不触发采购、下单或付款动作。
|
||||
Windows 入口优先复用并验证现有 Python 3.11+ venv，仅缺失时从 Launcher 合规版本确定性创建；安装、包导入、unittest、compileall、validator 全部使用同一 venv Python。当前实测 venv 为 Python 3.12。
|
||||
独立验证：在已合入 T-004 的最新组合基线上连续两次运行 init.ps1 成功；admin test/vet/build、client 6 tests/compileall、validator 通过。Python 3.10 venv fixture 与仅 3.10/3.9 Launcher fixture 均 fail closed；bash -n 通过，WSL 缺 Go 时明确非零退出。
|
||||
<!-- END VIKUNJA EXPORT -->
|
||||
|
||||
## 边界
|
||||
|
||||
Reference in New Issue
Block a user