cmbot/tasks.md

# 开发任务清单

## 任务文档说明

本文档用于跟踪自动合成印花服饰效果图工具的整体开发任务。后续 AI 或开发者领取任务前，必须先阅读对应任务的前置文档，并严格遵守 `docs/04-development-rules.md`。

任务状态说明：

- `[x]` 已完成。
- `[ ]` 未开始。
- `[~]` 进行中或部分完成。

## 任务执行顺序

任务编号即建议开发顺序，后续任务依赖前序任务的产出：

```
1（基础服务）→ 2（数据模型）→ 3/4（文件/模板服务）
→ 5（图片合成核心）→ 6（批量任务核心）→ 7（主界面布局）→ 8-13（各 UI 面板）→ 14（微调状态）→ 15（测试）→ 16（打包）
```

任务 1-6 完成前不应开始任务 7 及以后的 UI 任务，否则 UI 层将缺少可依赖的数据模型和服务层。

执行每个「完善 xxx.py」类任务前，必须先读取该文件的当前内容，了解骨架代码现状，再决定新增或修改哪些内容，避免覆盖已有实现。

## 0. 已完成基础工作

- [x] 编写项目愿景文档：`docs/01-product-vision.md`
- [x] 编写 PRD：`docs/02-prd.md`
- [x] 编写技术栈文档：`docs/03-technical-stack.md`
- [x] 编写开发规则文档：`docs/04-development-rules.md`
- [x] 编写项目架构文档：`docs/05-project-architecture.md`
- [x] 编写 UI 效果图提示词：`docs/06-ui-mockup-prompt.md`
- [x] 整理 Claude UI 提示词版本：`docs/06-ui-mockup-prompt-claude.md`
- [x] 保存 UI 效果图设计稿：`docs/ui-v1.html`
- [x] 保存 UI 效果图截图：`docs/ui-v1.png`
- [x] 编写 UI 设计文档：`docs/07-ui-design.md`
- [x] 编写图像编辑器设计文档：`docs/08-image-editor-design.md`
- [x] 编写本地打包发布文档：`docs/09-packaging-release.md`
- [x] 创建 `requirements.txt`
- [x] 创建 `src/version.py`，统一维护 `APP_NAME` 和 `APP_VERSION`
- [x] 创建 `src/main.py` 最小 PySide6 入口
- [x] 创建 `src/app/main_window.py` 最小主窗口
- [x] 创建 `src/app/widgets/` 占位模块
- [x] 创建 `src/core/` 占位模块
- [x] 创建 `src/services/` 占位模块
- [x] 创建 `src/resources/` 资源目录
- [x] 创建 `tests/` 测试目录
- [x] 验证本机 Python 版本为 `3.7.9`
- [x] 验证 PySide6 版本为 `6.5.3`
- [x] 通过 `python -m py_compile` 语法检查
- [x] 验证最小 PySide6 窗口可以创建并关闭
- [x] 已提交文档规划代码
- [x] 已提交 PySide6 工程骨架代码

## 1. 工程基础完善

### 1.1 日志服务

前置阅读：

- `docs/04-development-rules.md`
- `docs/05-project-architecture.md`

任务：

- [x] 先读取 `src/services/log_service.py` 现有内容
- [x] 完善 `src/services/log_service.py`
- [x] 启动时创建 `logs/` 目录
- [x] 日志文件按启动时间或日期命名
- [x] 日志格式包含时间、模块、级别、消息
- [x] 在 `src/main.py` 中初始化日志

验收：

- [x] 启动程序后生成日志文件
- [x] 程序启动信息写入日志
- [x] 不使用 `print` 作为正式日志

### 1.2 路径与资源服务

前置阅读：

- `docs/04-development-rules.md`
- `docs/05-project-architecture.md`
- `docs/09-packaging-release.md`

任务：

- [x] 在 `src/services/file_service.py` 中新增路径辅助函数（不单独建模块）
- [x] 实现 `get_app_dir()`：返回程序根目录，兼容开发环境和 PyInstaller 打包环境
- [x] 实现 `get_resource_path(relative_path)`：返回资源文件绝对路径
- [x] 实现 `get_config_path(relative_path)`：返回配置文件绝对路径
- [x] 实现 `get_log_dir()`：返回日志目录路径
- [x] 实现 `get_output_dir()`：返回默认输出目录路径
- [x] 保证 Windows 中文路径可用

验收：

- [x] 路径函数不使用开发机绝对路径
- [x] 程序目录下缺少 `logs/` 或 `output/` 时可自动创建

### 1.3 配置服务

前置阅读：

- `docs/04-development-rules.md`
- `docs/05-project-architecture.md`

任务：

- [x] 先读取 `src/services/config_service.py` 现有内容
- [x] 完善 `src/services/config_service.py`
- [x] 定义默认配置
- [x] 支持读取 JSON 配置
- [x] 支持保存 JSON 配置
- [x] 配置损坏时使用安全默认值并记录日志

验收：

- [x] 缺少配置文件时程序可启动
- [x] 配置文件损坏时程序可启动并记录日志
- [x] 不会无提示清空用户配置

## 2. 核心数据模型

前置阅读：

- `docs/02-prd.md`
- `docs/04-development-rules.md`
- `docs/05-project-architecture.md`
- `docs/08-image-editor-design.md`

任务：

- [x] 先读取 `src/core/models.py` 现有内容
- [x] 完善 `src/core/models.py`
- [x] 定义 `ImageAsset`
- [x] 定义 `TransformState`
- [x] 定义 `Template`
- [x] 定义 `ExportOptions`
- [x] 定义 `BatchOptions`
- [x] 定义 `ComposeResult`
- [x] 定义 `BatchResult`

验收：

- [x] `models.py` 不依赖 PySide6 UI 控件
- [x] 变换状态包含 `x/y/width/height/rotation/keep_aspect_ratio`
- [x] 模型可以被 core、services 和 UI 层复用

## 3. 文件扫描与素材导入

前置阅读：

- `docs/02-prd.md`
- `docs/04-development-rules.md`
- `docs/05-project-architecture.md`
- `docs/07-ui-design.md`

任务：

- [ ] 先读取 `src/services/file_service.py` 现有内容
- [ ] 完善 `src/services/file_service.py`
- [ ] 支持递归扫描衣服图片文件夹
- [ ] 支持递归扫描印花图片文件夹
- [ ] 支持格式：PNG、JPG、JPEG、WEBP
- [ ] 忽略不支持格式并记录日志
- [ ] 保留来源子文件夹信息
- [ ] 生成安全输出文件名

验收：

- [ ] 可以扫描包含子文件夹的中文路径
- [ ] 不修改原始素材文件
- [ ] 不支持文件格式不会导致扫描失败

## 4. 模板服务

前置阅读：

- `docs/02-prd.md`
- `docs/04-development-rules.md`
- `docs/05-project-architecture.md`

任务：

- [ ] 先读取 `src/services/template_service.py` 现有内容
- [ ] 完善 `src/services/template_service.py`
- [ ] 定义内置模板
- [ ] 支持读取自定义模板 JSON
- [ ] 支持保存自定义模板 JSON
- [ ] 支持新增、重命名、删除自定义模板
- [ ] 校验模板字段

验收：

- [ ] 内置模板和自定义模板可区分
- [ ] 单个模板损坏不影响全部模板加载
- [ ] UI 不直接操作模板 JSON 文件

## 5. 图片合成核心

前置阅读：

- `docs/02-prd.md`
- `docs/04-development-rules.md`
- `docs/05-project-architecture.md`
- `docs/08-image-editor-design.md`

任务：

- [ ] 先读取 `src/core/composer.py` 现有内容
- [ ] 完善 `src/core/composer.py`
- [ ] 使用 Pillow 读取衣服底图和印花图
- [ ] 支持透明 PNG alpha 合成
- [ ] 支持按 `TransformState` 缩放印花
- [ ] 支持按 `TransformState` 旋转印花
- [ ] 支持旋转后按中心点对齐粘贴
- [ ] 支持 PNG 导出
- [ ] 支持 JPG 导出
- [ ] 输出文件名避免默认覆盖

验收：

- [ ] 合成逻辑不依赖 PySide6 UI 控件
- [ ] 输出尺寸默认与衣服底图一致
- [ ] 透明 PNG 不出现黑底或白底
- [ ] 印花部分超出画布时不会报错

## 6. 批量任务核心

前置阅读：

- `docs/02-prd.md`
- `docs/04-development-rules.md`
- `docs/05-project-architecture.md`

任务：

- [ ] 先读取 `src/core/batch.py` 现有内容
- [ ] 完善 `src/core/batch.py`
- [ ] 支持多衣服 × 单印花
- [ ] 支持单衣服 × 多印花
- [ ] 支持一一匹配
- [ ] 支持全组合
- [ ] 复用 `core/composer.py`
- [ ] 单个任务失败时继续处理剩余任务
- [ ] 汇总成功数量、失败数量和失败原因

验收：

- [ ] 不复制第二套合成算法
- [ ] 单张失败不会中断整个批量任务
- [ ] 失败原因可供 UI 和日志使用

## 7. 主界面布局

前置阅读：

- `docs/04-development-rules.md`
- `docs/05-project-architecture.md`
- `docs/07-ui-design.md`

任务：

- [ ] 先读取 `src/app/main_window.py` 现有内容
- [ ] 将 `src/app/main_window.py` 从最小窗口扩展为主布局
- [ ] 实现顶部标题和版本号
- [ ] 实现流程页签区域
- [ ] 实现左侧素材栏容器
- [ ] 实现中间预览区容器
- [ ] 实现右侧参数栏容器
- [ ] 实现底部合成队列容器
- [ ] 实现底部状态栏

验收：

- [ ] 窗口标题显示 `APP_NAME` 和 `APP_VERSION`
- [ ] UI 布局接近 `docs/ui-v1.png`
- [ ] 不把所有业务逻辑塞进 `main_window.py`

## 8. 素材列表 UI

前置阅读：

- `docs/02-prd.md`
- `docs/05-project-architecture.md`
- `docs/07-ui-design.md`

任务：

- [ ] 先读取 `src/app/widgets/image_list_panel.py` 现有内容
- [ ] 实现衣服图片列表
- [ ] 实现印花图片列表
- [ ] 实现打开文件夹按钮
- [ ] 实现全选和取消全选
- [ ] 实现单张勾选和取消勾选
- [ ] 显示已选数量和总数量（例如：`含子文件夹 · 共 12`）
- [ ] 显示来源子文件夹标签和文件名
- [ ] 实现排序选择器（默认按文件夹+名称排序）
- [ ] 点击素材后更新当前预览选择

验收：

- [ ] 支持递归导入素材
- [ ] 当前预览选中态和批量勾选态可区分
- [ ] 不在 UI 层重复实现文件扫描规则

## 9. 图像预览编辑器

前置阅读：

- `docs/04-development-rules.md`
- `docs/05-project-architecture.md`
- `docs/07-ui-design.md`
- `docs/08-image-editor-design.md`

任务：

- [ ] 先读取 `src/app/widgets/image_canvas.py` 现有内容
- [ ] 使用 `QGraphicsView / QGraphicsScene`
- [ ] 显示衣服底图（scene 坐标与原图像素坐标保持一致）
- [ ] 显示印花图层
- [ ] 实现印花拖动
- [ ] 实现缩放控制点（至少四角）
- [ ] 实现旋转控制点（顶部中心外侧）
- [ ] 实现预览缩放（通过 `QGraphicsView` view transform，不修改 scene 内容）
- [ ] 实现预览顶部栏：显示当前底图文件名、印花文件名、操作模式按钮（移动/缩放/旋转）、缩放比例控制
- [ ] 实现画布操作提示 Overlay（拖动移动 / 四角缩放 / 顶部旋转 / Shift 锁比例）
- [ ] 将交互结果同步为 `TransformState`

验收：

- [ ] 预览缩放不改变真实合成参数
- [ ] 拖动后坐标为衣服原图像素坐标
- [ ] 缩放后宽高同步
- [ ] 旋转后角度同步
- [ ] 不使用截图作为导出结果

## 10. 参数面板 UI

前置阅读：

- `docs/05-project-architecture.md`
- `docs/07-ui-design.md`
- `docs/08-image-editor-design.md`

任务：

- [ ] 先读取 `src/app/widgets/transform_panel.py` 现有内容
- [ ] 完善 `src/app/widgets/transform_panel.py`
- [ ] 实现 X/Y 坐标输入
- [ ] 实现宽度/高度输入
- [ ] 实现锁定宽高比例
- [ ] 实现角度输入
- [ ] 实现左旋 90 度和右旋 90 度按钮
- [ ] 与 `ImageCanvas` 双向同步 `TransformState`

验收：

- [ ] 参数输入后预览同步更新
- [ ] 预览交互后参数输入框同步更新
- [ ] 程序化更新输入框不会造成信号循环

## 11. 模板面板 UI

前置阅读：

- `docs/02-prd.md`
- `docs/05-project-architecture.md`
- `docs/07-ui-design.md`

任务：

- [ ] 先读取 `src/app/widgets/template_panel.py` 现有内容
- [ ] 完善 `src/app/widgets/template_panel.py`
- [ ] 显示模板下拉框
- [ ] 支持选择模板
- [ ] 支持保存模板
- [ ] 支持另存为模板
- [ ] 支持重置为模板
- [ ] 通过 `template_service` 操作模板

验收：

- [ ] 选择模板后更新预览和参数面板
- [ ] UI 不直接修改模板 JSON
- [ ] 自定义模板重启后仍可用

## 12. 导出面板 UI

前置阅读：

- `docs/05-project-architecture.md`
- `docs/07-ui-design.md`
- `docs/09-packaging-release.md`

任务：

- [ ] 先读取 `src/app/widgets/export_panel.py` 现有内容
- [ ] 完善 `src/app/widgets/export_panel.py`
- [ ] 实现输出目录选择
- [ ] 实现输出格式选择
- [ ] 实现质量选择
- [ ] 实现导出当前单张
- [ ] 实现应用为模板入口
- [ ] 实现重置为模板入口
- [ ] 显示当前操作影响范围提示

验收：

- [ ] 缺少衣服或印花时导出按钮禁用
- [ ] 输出目录不可写时提示用户并记录日志
- [ ] 单张导出调用 `core/composer.py`

## 13. 合成队列 UI

前置阅读：

- `docs/02-prd.md`
- `docs/05-project-architecture.md`
- `docs/07-ui-design.md`

任务：

- [ ] 实现底部合成队列表格（建议使用 `QTableView` + 模型视图结构）
- [ ] 实现队列头部批量模式切换：多衣服×单印花 / 单衣服×多印花 / 一一匹配 / 全组合（矩阵）
- [ ] 实现队列统计显示（共 N 项 · 完成 · 进行 · 失败 · 待导出）
- [ ] 实现「重置全部」按钮
- [ ] 实现「导出选中」按钮
- [ ] 实现「开始批量导出」按钮（导出中切换为停止/暂停）
- [ ] 实现队列折叠/展开
- [ ] 显示任务状态（已完成 / 待导出 / 导出中 / 失败）
- [ ] 导出中任务显示进度条
- [ ] 显示失败原因
- [ ] 支持选中队列项并更新预览区和参数面板

验收：

- [ ] 队列统计显示总数、完成、进行、失败、待导出
- [ ] 导出中任务显示进度条
- [ ] 失败行显示可理解原因
- [ ] 选中队列项可以加载对应状态

## 14. 微调状态

前置阅读：

- `docs/07-ui-design.md`
- `docs/08-image-editor-design.md`

任务：

- [ ] 定义队列项微调状态
- [ ] 手动调整队列项后标记为 `已微调`
- [ ] 微调项保存独立 `TransformState`
- [ ] 批量导出时微调项使用自己的参数
- [ ] 未微调项使用模板参数

验收：

- [ ] 已微调项不会被无提示覆盖
- [ ] 队列表格能显示 `模板` 和 `已微调`

## 15. 测试

前置阅读：

- `docs/04-development-rules.md`
- `docs/05-project-architecture.md`
- `docs/08-image-editor-design.md`

任务：

- [ ] 编写 `tests/test_composer.py`
- [ ] 编写 `tests/test_templates.py`
- [ ] 测试透明 PNG 合成
- [ ] 测试缩放参数
- [ ] 测试旋转中心
- [ ] 测试文件扫描
- [ ] 测试模板读写
- [ ] 测试批量任务生成

验收：

- [ ] 核心逻辑测试不依赖 GUI
- [ ] 测试可在 Python 3.7 环境运行

## 16. 打包

前置阅读：

- `docs/03-technical-stack.md`
- `docs/04-development-rules.md`
- `docs/09-packaging-release.md`

任务：

- [ ] 创建打包脚本
- [ ] 验证 PyInstaller `onedir` 打包
- [ ] 打包资源文件
- [ ] 打包默认配置和模板
- [ ] 验证打包后程序启动
- [ ] 验证标题栏版本号
- [ ] 验证单张导出

验收：

- [ ] 打包产物可在无 Python 环境的 Windows 电脑启动
- [ ] 发布包不包含源代码、缓存、测试输出和私人配置

## 17. 后续暂缓任务

以下任务第一阶段暂不做，后续需要时再新增设计文档：

- [ ] 局域网分发
- [ ] 自动更新
- [ ] 多版本启动器
- [ ] 按电脑名控制版本
- [ ] AI 穿搭
- [ ] 导出上架流程
- [ ] 自动抠图
- [ ] 自动识别衣服区域
- [ ] 移动端应用