cmbuyer/docs/03-tech-stack.md

# 技术栈（Tech Stack）

> 「用什么」的统一速查表。选型与理由在此集中维护；「怎么把它们搭起来」见
> [架构设计](04-architecture.md)。未定项必须标为待定，不要让 agent 在代码里自行决定。

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

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

| 维度 | 选型 | 状态 | 理由 / 说明 |
| --- | --- | --- | --- |
| 语言 | Go 1.23+ | 已定 | 单二进制部署，前序项目同栈，无运行时依赖 |
| HTTP 框架 | `gin` | 已定 | 前序项目已验证；路由、中间件、绑定够用 |
| 页面渲染 | Go `html/template`（服务端渲染） | 已定 | 管理后台交互密度低，不引入前端构建链 |
| UI 样式 | 手写 CSS，单文件 | 已定 | 无构建步骤；原型见 `docs/design/` |
| 数据库 | SQLite（`mattn/go-sqlite3`） | 已定 | 单机部署，单写入者；并发压力低 |
| 迁移 | `goose` | 已定 | 前序项目已验证 |
| 管理端鉴权 | Session Cookie + CSRF Token | 已定 | 服务端渲染的标准做法 |
| 设备端鉴权 | Bearer Token + 设备绑定 | 已定 | 桌面端是机器身份，不用 Cookie |
| 对象存储 | 本地文件系统 + SHA-256 寻址 | 已定 | MVP 单机；接口留抽象以便后续换 S3 |
| 测试 | `go test` | 已定 | 标准库足够 |
| 部署 | 单二进制 + 数据目录 | 已定 | 运营电脑本机运行 |

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

| 维度 | 选型 | 状态 | 理由 / 说明 |
| --- | --- | --- | --- |
| 语言 | Python 3.11+ | 已定 | AI 生态原生；`uiautomator2` 官方语言 |
| 真机控制 | `uiautomator2` | 已定 | 前序项目真机验证过选规格与订单确认页读取 |
| 传输 | ADB（USB 或 WiFi） | 已定 | `uiautomator2` 3.x 走 adb 通道，`ip:port` 与 USB serial 同等对待 |
| 桌面 GUI | `PySide6` | 已定 | 前序项目已验证；执行员需要看设备状态和批次进度 |
| 截图处理 | `Pillow` | 已定 | 判断页面是否渲染完成，避免保存白屏壳层 |
| HTTP 客户端 | 标准库 `urllib` 或 `httpx` | **待定** | 先用标准库；确有重试/连接池需求再评估 |
| Excel | 不引入 | 已定 | Excel 解析移到采购服务；采购工具不再直接读表 |
| 测试 | `unittest`（标准库） | 已定 | 前序项目 171 项测试均用标准库，无需 pytest |
| 打包 | `pyinstaller` | 已定 | 交付给运营电脑；开发期依赖 |

## 三、AI 辅助（P1，MVP 不启用）

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

## 四、决策记录与演进

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

## 五、构建与运行命令

> 采购服务命令已由 T-001 实际验证。采购工具以下离线测试、编译和 wheel 元数据命令已由
> Python 3.12 实际验证；桌面 GUI 和真机流程不属于 T-002 验收范围。

| 用途 | 采购服务（`admin/`） | 采购工具（`client/`） |
| --- | --- | --- |
| 安装依赖 | `go mod download` | `py -3.12 -m venv .venv` 后运行 `.\.venv\Scripts\python.exe -m 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` |

采购工具的运行时依赖只维护在 `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 PowerShell 差异：

```powershell
# Go 工具链固定用本机版本，避免自动下载
$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、测试数 |
| 完整门禁 | 发布前；修改 HTTP 契约、数据库 schema、依赖或构建配置时；跨端改动时 | 两端全部测试 + 静态检查 + 两端构建 | 退出码 0、测试数、产物路径 |
| 人工 / 设备验收 | 任何涉及真机页面判据、下单动作或付款路径的任务 | 连接真机执行，记录设备型号、Android 版本、拼多多版本、goods_id、截图与页面 XML 路径 | 人工结论 + 证据文件路径 |

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

## 七、依赖纪律

- 新增第三方依赖前，先说明用途、替代方案和维护成本，并同步本文。
- 依赖随任务按需引入，不为「将来可能用到」提前添加。
- 不确定的技术选型先更新本文，再进入代码。
- 不允许同一职责并存两套框架。