docs(project): align product names and source directories

2026-08-03 16:27:05 +08:00
parent fe0c867948
commit b9e29ed970
16 changed files with 177 additions and 154 deletions
@@ -3,9 +3,10 @@
 > 「用什么」的统一速查表。选型与理由在此集中维护；「怎么把它们搭起来」见
 > [架构设计](04-architecture.md)。未定项必须标为待定，不要让 agent 在代码里自行决定。

-本项目是**双端**结构，两端技术栈独立，通过 HTTP 契约耦合。
+本项目是**双产品**结构：采购服务位于 `admin/`，采购工具位于 `client/`；两套技术栈独立，
+通过 HTTP 契约耦合。

-## 一、web 端（Go）
+## 一、采购服务（网页端，`admin/`，Go）

 | 维度 | 选型 | 状态 | 理由 / 说明 |
 | --- | --- | --- | --- |
@@ -21,7 +22,7 @@
 | 测试 | `go test` | 已定 | 标准库足够 |
 | 部署 | 单二进制 + 数据目录 | 已定 | 运营电脑本机运行 |

-## 二、desk 端（Python）
+## 二、采购工具（Windows 桌面端，`client/`，Python）

 | 维度 | 选型 | 状态 | 理由 / 说明 |
 | --- | --- | --- | --- |
@@ -31,7 +32,7 @@
 | 桌面 GUI | `PySide6` | 已定 | 前序项目已验证；执行员需要看设备状态和批次进度 |
 | 截图处理 | `Pillow` | 已定 | 判断页面是否渲染完成，避免保存白屏壳层 |
 | HTTP 客户端 | 标准库 `urllib` 或 `httpx` | **待定** | 先用标准库；确有重试/连接池需求再评估 |
-| Excel | 不引入 | 已定 | Excel 解析移到 web 端；desk 端不再直接读表 |
+| Excel | 不引入 | 已定 | Excel 解析移到采购服务；采购工具不再直接读表 |
 | 测试 | `unittest`（标准库） | 已定 | 前序项目 171 项测试均用标准库，无需 pytest |
 | 打包 | `pyinstaller` | 已定 | 交付给运营电脑；开发期依赖 |

@@ -39,9 +40,9 @@

 | 维度 | 选型 | 状态 | 说明 |
 | --- | --- | --- | --- |
-| 调用位置 | desk 端 | 已定 | PC 有算力；改 prompt 不需要重新打包 |
+| 调用位置 | 采购工具 | 已定 | PC 有算力；改 prompt 不需要重新打包 |
 | provider | 待定 | **待定** | 需先确认预算与合规；不得由 agent 自行选定 |
-| 凭据存储 | desk 端本机配置文件，不入库、不上传 | 已定 | web 端不保存、不代理、不下发任何模型凭据 |
+| 凭据存储 | 采购工具本机配置文件，不入库、不上传 | 已定 | 采购服务不保存、不代理、不下发任何模型凭据 |
 | 输入 | 完整节点树 XML + 页面截图 | 已定 | `dump_hierarchy(compressed=False)` 不丢节点 |

 ## 四、决策记录与演进
@@ -50,10 +51,10 @@
  实时视图再评估，届时以整页替换为单位迁移，不做半 SPA。
 - **SQLite 而不是 Postgres。** MVP 单机、单写入者。出现多实例或跨机访问需求时再迁移；
  数据访问层不得写死 SQLite 方言。
- **Excel 解析放 web 端而不是 desk 端。** 建单入口集中在一处才能统一审计。代价是要在
+- **Excel 解析放采购服务而不是采购工具。** 建单入口集中在一处才能统一审计。代价是要在
  Go 侧重写表头校验和行级报错，不能直接复用前序项目的 Python 实现。
- **desk 端不持有业务权威。** 金额上限、授权有效性、任务状态流转的判定权在 web 端；
-  desk 端本地校验只作为第二道防线，两边不一致时一律转人工。
+- **采购工具不持有业务权威。** 金额上限、授权有效性、任务状态流转的判定权在采购服务；
+  采购工具本地校验只作为第二道防线，两边不一致时一律转人工。
 - **不引入 pytest / 不引入 ORM。** 同一职责不并存两套方案。

 ## 五、构建与运行命令
@@ -61,7 +62,7 @@
 > **占位符。** 代码尚未初始化，以下命令分别在 T-001 / T-002 落地后由对应任务替换为真实可运行命令，
 > 并同步到 [`00-ai-start-here.md`](00-ai-start-here.md) 和 [`current-state.md`](current-state.md)。

-| 用途 | web 端 | desk 端 |
+| 用途 | 采购服务（`admin/`） | 采购工具（`client/`） |
 | --- | --- | --- |
 | 安装依赖 | `go mod download` | `python -m venv .venv` + `pip install -r requirements.txt` |
 | 本地开发 | 【T-001 填写】 | 【T-002 填写】 |
@@ -80,14 +81,14 @@ $env:GOTOOLCHAIN = "local"

 | 层级 | 触发条件 | 命令 / 操作 | 通过证据 |
 | --- | --- | --- | --- |
-| 任务相关验证 | 每个任务必跑 | 改 web 端跑 `go test ./...` + `go vet ./...`；改 desk 端跑 `python -m unittest discover -s tests -t .` + `python -m compileall -q src tests` | 退出码 0、测试数 |
+| 任务相关验证 | 每个任务必跑 | 改 `admin/` 跑 `go test ./...` + `go vet ./...`；改 `client/` 跑 `python -m unittest discover -s tests -t .` + `python -m compileall -q src tests` | 退出码 0、测试数 |
 | 完整门禁 | 发布前；修改 HTTP 契约、数据库 schema、依赖或构建配置时；跨端改动时 | 两端全部测试 + 静态检查 + 两端构建 | 退出码 0、测试数、产物路径 |
 | 人工 / 设备验收 | 任何涉及真机页面判据、下单动作或付款路径的任务 | 连接真机执行，记录设备型号、Android 版本、拼多多版本、goods_id、截图与页面 XML 路径 | 人工结论 + 证据文件路径 |

 - 任务相关验证不能省略。跨端契约改动必跑完整门禁——两端会同时坏。
 - **真机验收只能由人完成。** agent 不得据自身判断把需要真机的任务标为 `DONE`。
 - 真机验收必须记录**拼多多 App 版本**。页面判据与版本绑定，换版本即失效。
- 交付 desk 端安装包时记录产物路径与 SHA-256；**版本号不能单独证明部署的是本次构建**。
+- 交付采购工具安装包时记录产物路径与 SHA-256；**版本号不能单独证明部署的是本次构建**。

 ## 七、依赖纪律