cmbot/tasks.md

# 开发任务清单

## 任务文档说明

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

任务状态说明：

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

## 任务执行顺序

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

```
1（基础服务）→ 2（数据模型）→ 3/4（文件/模板服务）
→ 5（图片合成核心）→ 6（批量任务核心）→ 6.5（低对比组合筛选核心）→ 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`

任务：

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

验收：

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

## 4. 模板服务

前置阅读：

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

任务：

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

验收：

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

## 5. 图片合成核心

前置阅读：

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

任务：

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

验收：

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

## 6. 批量任务核心

前置阅读：

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

任务：

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

验收：

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

## 6.5 低对比组合筛选核心

前置阅读：

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

任务：

- [ ] 定义可见度状态：`正常`、`偏低`、`不明显`、`无法判断`
- [ ] 新增低对比分析核心函数，位置应符合架构分层，不能写进 UI 事件
- [ ] 基于当前模板或 `TransformState` 获取衣服目标区域
- [ ] 只分析衣服目标区域颜色，不使用整张衣服图判断
- [ ] 只统计印花 alpha 有效像素，例如 `alpha > 20`
- [ ] 计算 RGB 颜色距离
- [ ] 计算亮度差
- [ ] 根据阈值输出可见度状态和评分
- [ ] 单个组合分析失败时返回 `无法判断`，不得中断整个队列
- [ ] 为后续队列项保存可见度结果预留字段或结果结构

验收：

- [ ] 白色衣服配浅色印花时可标记为 `偏低` 或 `不明显`
- [ ] 深色衣服配深色印花时可标记为 `偏低` 或 `不明显`
- [ ] 透明 PNG 的透明区域不参与印花颜色判断
- [ ] 低对比分析不修改原始衣服图片和原始印花图片
- [ ] 分析逻辑不依赖 PySide6 UI 控件
- [ ] 失败项不会中断批量队列生成或导出流程

## 7. 主界面布局

前置阅读：

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

任务：

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

验收：

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

## 8. 素材列表 UI

前置阅读：

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

任务：

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

验收：

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

## 9. 图像预览编辑器

前置阅读：

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

任务：

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

验收：

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

## 10. 参数面板 UI

前置阅读：

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

任务：

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

验收：

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

## 11. 模板面板 UI

前置阅读：

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

任务：

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

验收：

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

## 12. 导出面板 UI

前置阅读：

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

任务：

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

验收：

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

## 13. 合成队列 UI

前置阅读：

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

任务：

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

验收：

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

## 14. 微调状态

前置阅读：

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

任务：

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

验收：

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

## 15. 测试

前置阅读：

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

任务：

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

验收：

- [x] 核心逻辑测试不依赖 GUI
- [x] 测试可在 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 穿搭
- [ ] 导出上架流程
- [ ] 自动抠图
- [ ] 自动识别衣服区域
- [ ] 移动端应用