144 lines
4.2 KiB
Markdown
144 lines
4.2 KiB
Markdown
# 技术栈说明
|
||
|
||
## 目标运行环境
|
||
|
||
- 操作系统：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 的版本。
|
||
|
||
推荐版本：
|
||
|
||
```text
|
||
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 的版本可以避免依赖解析到不兼容版本。
|
||
|
||
安装时建议使用：
|
||
|
||
```bash
|
||
pip install PySide6==6.5.3
|
||
```
|
||
|
||
`shiboken6` 会作为依赖自动安装对应版本；在正式依赖文件中仍建议显式锁定。
|
||
|
||
## 图片处理
|
||
|
||
使用 Pillow 处理最终图片合成。
|
||
|
||
用途：
|
||
|
||
- 读取衣服底图和印花图。
|
||
- 保持透明 PNG 的 alpha 通道。
|
||
- 对印花执行缩放、旋转。
|
||
- 将处理后的印花叠加到衣服底图。
|
||
- 导出 PNG 或 JPG。
|
||
|
||
可选使用 numpy 辅助处理图像数组，但第一阶段不应把 numpy 作为必须依赖，除非实际实现需要。
|
||
|
||
## Excel 与 HTTP（AI 穿搭）
|
||
|
||
AI 穿搭模块需要读取/写回 Excel，并通过 HTTP(S) 调用外部 AI 图像接口。该能力属于可选扩展页签，不改变「添加印花」主流程的本地合成能力。
|
||
|
||
依赖约束：
|
||
|
||
```text
|
||
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` 的已知风险影响生产接口调用。
|
||
|
||
## 预览交互
|
||
|
||
预览区建议使用：
|
||
|
||
```text
|
||
QGraphicsView
|
||
QGraphicsScene
|
||
QGraphicsPixmapItem
|
||
自定义可变换印花 Item
|
||
```
|
||
|
||
设计原则：
|
||
|
||
- 衣服底图作为基础图层。
|
||
- 印花图作为可交互图层。
|
||
- 印花支持拖动、缩放和旋转。
|
||
- 预览交互状态需要转换为衣服底图原始像素坐标。
|
||
- 导出时以原始像素坐标为准，确保预览和导出结果一致。
|
||
|
||
## 打包工具
|
||
|
||
使用 PyInstaller 打包。
|
||
|
||
推荐使用 onedir 模式：
|
||
|
||
```bash
|
||
pyinstaller --onedir --windowed main.py
|
||
```
|
||
|
||
选择 onedir 的原因：
|
||
|
||
- PySide6 / Qt 依赖文件较多，onedir 更容易排查缺失插件或 DLL 问题。
|
||
- 启动速度通常优于 onefile。
|
||
- 后续局域网分发和增量替换更容易。
|
||
- 配置文件、模板文件和日志目录更容易管理。
|
||
|
||
## 依赖锁定
|
||
|
||
精确依赖版本应放在项目根目录的 `requirements.txt` 中维护，而不是放在 PRD 中。
|
||
|
||
建议初始依赖：
|
||
|
||
```text
|
||
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`：定义实际安装的精确依赖版本。
|