cmbuyer/docs/03-tech-stack.md

技术栈（Tech Stack）

「用什么」的统一速查表。选型与理由在此集中维护；「怎么把它们搭起来」见 架构设计。未定项必须标为待定，不要让 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。 同一职责不并存两套方案。

五、构建与运行命令

init.ps1 已由 T-003 在 Windows PowerShell 实际验证：它优先复用合规的既有采购工具虚拟环境 （本机实际为 Python 3.12）；仅在虚拟环境不存在时，才从 Python Launcher 的已安装版本中确定性选择 最高的 Python 3.11+ 创建它，以 editable 方式安装采购工具，并跑两端 离线门禁。桌面 GUI 和真机流程不属于该入口的验收范围。

用途	采购服务（admin/）	采购工具（client/）
安装依赖	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 ./...	.\.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，不满足采购工具的 Python 3.11+ 下限； 不得把未加版本选择器的 python 当作采购工具命令。统一入口优先使用既有合规 venv，仅在需要创建时 自动选择 Launcher 中最高的合规版本；本机现有 venv 实际为 Python 3.12。桌面 GUI 与真机流程不属于 T-003 验收范围。

Windows PowerShell 差异：

# Go 工具链固定用本机版本，避免自动下载
$env:GOTOOLCHAIN = "local"

六、验证矩阵与构建产物

层级	触发条件	命令 / 操作	通过证据
任务相关验证	每个任务必跑	改 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 路径	人工结论 + 证据文件路径

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

七、依赖纪律

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