cmpdd/docs/03-tech-stack.md

技术栈（Tech Stack）

“用什么”的统一速查表。选型与理由在此集中维护；“怎么把它们搭起来”见 架构设计。 未定项必须标为待定，不要让 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：

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、抓包改包等依赖。