cmbot/docs/03-technical-stack.md

技术栈说明

目标运行环境

• 操作系统：Windows 10 及以上，优先适配 Windows 10 / Windows 11。
• 开发语言：Python。
• 指定 Python 版本：Python 3.7。
• 发布形态：打包为 Windows 桌面程序，目标电脑无需预装 Python 环境。

GUI 框架

使用 PySide6 作为桌面 GUI 框架。

选择原因：

• PySide6 是 Qt 官方 Python 绑定。
• 授权相对适合闭源或内部工具场景。
• Qt 的 QGraphicsView / QGraphicsScene 适合实现图片预览、拖动、缩放和旋转。
• 可以通过 PyInstaller 打包为 Windows 可执行程序。

PySide6 版本约束

由于项目指定使用 Python 3.7，PySide6 需要锁定在仍支持 Python 3.7 的版本。

推荐版本：

PySide6==6.5.3
shiboken6==6.5.3

原因：

• PySide6 6.5.3 支持 Python >=3.7, <3.12。
• PySide6 6.6.0 起要求 Python >=3.8，不适用于当前 Python 3.7 约束。
• 固定 PySide6 和 shiboken6 的版本可以避免依赖解析到不兼容版本。

安装时建议使用：

pip install PySide6==6.5.3

shiboken6 会作为依赖自动安装对应版本；在正式依赖文件中仍建议显式锁定。

图片处理

使用 Pillow 处理最终图片合成。

用途：

• 读取衣服底图和印花图。
• 保持透明 PNG 的 alpha 通道。
• 对印花执行缩放、旋转。
• 将处理后的印花叠加到衣服底图。
• 导出 PNG 或 JPG。

可选使用 numpy 辅助处理图像数组，但第一阶段不应把 numpy 作为必须依赖，除非实际实现需要。

Excel 与 HTTP（AI 穿搭）

AI 穿搭模块需要读取/写回 Excel，并通过 HTTP(S) 调用外部 AI 图像接口。该能力属于可选扩展页签，不改变「添加印花」主流程的本地合成能力。

依赖约束：

requests==2.31.0
urllib3==1.26.20
openpyxl==3.1.3

版本说明：

• requests 2.31.0 是仍支持 Python 3.7 的版本；requests 2.32.x 起要求 Python 3.8+。
• urllib3 固定在 1.26.x，避免解析到 2.x 后在旧 Python / 旧 Windows 环境中引入兼容风险。
• openpyxl 3.1.3 支持 Python 3.7；openpyxl 3.1.5 起要求 Python 3.8+，因此不能使用宽泛的 openpyxl>=3.1,<4 作为本项目锁定依赖。
• 后续 AI 接口代码不得使用 verify=False 关闭 TLS 校验；如使用 requests.Session，应显式控制环境凭据读取，避免旧版 requests 的已知风险影响生产接口调用。

预览交互

预览区建议使用：

QGraphicsView
QGraphicsScene
QGraphicsPixmapItem
自定义可变换印花 Item

设计原则：

• 衣服底图作为基础图层。
• 印花图作为可交互图层。
• 印花支持拖动、缩放和旋转。
• 预览交互状态需要转换为衣服底图原始像素坐标。
• 导出时以原始像素坐标为准，确保预览和导出结果一致。

打包工具

使用 PyInstaller 打包。

推荐使用 onedir 模式：

pyinstaller --onedir --windowed main.py

选择 onedir 的原因：

• PySide6 / Qt 依赖文件较多，onedir 更容易排查缺失插件或 DLL 问题。
• 启动速度通常优于 onefile。
• 后续局域网分发和增量替换更容易。
• 配置文件、模板文件和日志目录更容易管理。

依赖锁定

精确依赖版本应放在项目根目录的 requirements.txt 中维护，而不是放在 PRD 中。

建议初始依赖：

PySide6==6.5.3
shiboken6==6.5.3
Pillow==9.5.0
PyInstaller==5.13.2
requests==2.31.0
urllib3==1.26.20
openpyxl==3.1.3

注意：

• Python 3.7 已停止官方维护，部分第三方库的新版本不再支持 Python 3.7。
• 实际开发前需要验证 Pillow、PyInstaller 等依赖的最新可用兼容版本。
• 一旦验证通过，应把这些依赖固定为明确版本，避免后续安装环境变化导致打包失败。
• 新增依赖前必须先核对其 Requires-Python 元数据，不能只写宽版本范围。

文档分工

• docs/01-product-vision.md：定义项目是什么、给谁用、为什么存在、不做什么。
• docs/02-prd.md：定义用户需求、功能范围、交互要求和验收标准。
• docs/03-technical-stack.md：定义技术选型、版本约束和工程环境。
• requirements.txt：定义实际安装的精确依赖版本。