docs: 初始化项目文档集与一致性补丁

建立 harness coding 文档体系并完成一致性修正:

- 文档集:AGENTS.md/CLAUDE.md 入口,docs/00-05 规范文档,
  api.md/routes.md/current-state.md,根目录 tasks.md/progress.md。
- 一致性补丁:TaskStatus 中英映射、支付模式收敛为全局 PaymentConfig、
  执行器级 RunnerState 暂停语义、progress 与 current-state 职责边界。
- 工程地基:新增 .gitignore,忽略运行产物/敏感数据与 .claude 本地设置。
- 合规留痕:02 需求新增平台规则与合规风险条目。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
chengma
2026-06-24 16:15:46 +08:00
co-authored by Claude Opus 4.8
commit 541dfab967
15 changed files with 1487 additions and 0 deletions
+72
View File
@@ -0,0 +1,72 @@
# 技术栈(Tech Stack)
> “用什么”的统一速查表。选型与理由在此集中维护;“怎么把它们搭起来”见 [架构设计](04-architecture.md)。
> 未定项必须标为待定,不要让 agent 在代码里自行决定。
## 一、技术栈一览
| 维度 | 选型 | 状态 | 理由 / 说明 |
| --- | --- | --- | --- |
| 主语言 | Python 3.x | 已定 | 与 `uiautomator2`、Excel 处理、桌面 GUI 衔接快。具体版本待项目初始化确认。 |
| 桌面 GUI | PySide6 | 已定 | 适合 Windows 桌面程序,用户不需要部署 Web 服务。 |
| Android 控制 | ADB + `uiautomator2` | 已定 | MVP 只控制 Android 真机,开发成本低于 Appium。 |
| Excel 处理 | `openpyxl` | 已定 | 读取/写入 `.xlsx`,适合固定表头和结果回写。 |
| 图像/截图 | `uiautomator2` 截图能力;Pillow 待定 | 部分待定 | MVP 先保存截图;如需图片处理再引入 Pillow。 |
| OCR | 待定 | 待定 | MVP 不优先引入;UI XML 识别不足时再评估。 |
| 数据库 | 无数据库 | 已定 | MVP 以 Excel 文件作为输入输出,避免过早引入数据库。 |
| 鉴权方式 | 无工具账号 | 已定 | 本地内部工具;拼多多账号由真机 App 登录态承担。 |
| 后端服务 | 无独立后端 | 已定 | 单机 GUI 内直接调用本地模块。 |
| 日志 | Python `logging` | 已定 | 保存执行日志,便于排查。 |
| 测试 | `pytest` | 待定 | 建议用于 Excel 解析、状态机、SKU 匹配等纯逻辑测试。 |
| 打包 | PyInstaller | 待定 | MVP 稳定后打包为 Windows 可执行程序。 |
## 二、决策记录与演进
- 当前选择 **桌面 GUI**,因为功能少、给运营内部使用、运行环境就是连接手机的 Windows 电脑,落地快。
- 当前选择 **`uiautomator2 + ADB`**,因为只做 Android 真机控制,不需要 Appium 的跨平台和服务端复杂度。
- 当前选择 **Excel 输入输出**,因为运营后期可直接整理历史文档,MVP 不需要数据库。
- 当前不引入 **Web 后台 / 多设备调度 / 数据库**,避免第一版复杂度过高。
- OCR、图像识别、Appium、SQLite 作为后续选项,仅在真实页面验证需要时引入。
## 三、构建与运行命令
当前代码尚未初始化。以下为计划命令,初始化后必须改成真实命令。
| 用途 | 命令 |
| --- | --- |
| 创建虚拟环境 | `python -m venv .venv` |
| 激活虚拟环境 | `.venv\Scripts\Activate.ps1` |
| 安装依赖 | `pip install -r requirements.txt` |
| 本地运行 | `python src/main.py` |
| 测试 | `python -m pytest` |
| 语法检查 | `python -m compileall src` |
| 打包 | `pyinstaller app.spec` |
Windows PowerShell:
```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python src/main.py
python -m pytest
```
## 四、设备与环境要求
- Windows 电脑。
- Android 真机,已开启开发者选项和 USB 调试。
- ADB 可用,电脑能看到设备。
- 真机已安装拼多多 App,并已登录可下单账号。
- 真机网络稳定,屏幕常亮或执行期间不锁屏。
- 支付默认由运营人工确认;开启受控自动支付时,必须由配置、金额上限和二次校验控制。
- 验证码、风控、人脸、短信等安全校验节点由运营人工处理。
## 五、依赖纪律
- 新增第三方依赖前,先说明用途、替代方案和维护成本。
- 不确定的技术选型先更新本文,再进入代码。
- 不允许同一职责并存两套框架或两套状态管理方案。
- 不允许为了绕过平台安全校验而引入逆向、Hook、抓包改包等依赖。