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`

任务：

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

验收：

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

## 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] ~~实现应用为模板入口~~（后移除：与模板区域「另存为」重复，见 17.3）
- [x] ~~实现重置为模板入口~~（后移除：与模板区域「重置为模板」重复，见 17.3）
- [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`

任务：

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

验收：

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

## 17. 体验优化（持久化与独立重置）

第二阶段根据实际使用反馈新增。

### 17.1 用户偏好持久化

前置阅读：

- `docs/02-prd.md`（6.6 模板选择、6.9 批量合成导出、9 数据与文件结构）
- `docs/05-project-architecture.md`（4.12 config_service）

任务：

- [ ] 先读取 `src/services/config_service.py` 与 `src/app/main_window.py` 现有内容
- [ ] 在 `main_window` 启动时调用 `load_config()` 并把初值分发给各面板（集中管理，不让控件各自读写）
- [ ] 在 `config_service` 默认配置中新增 `last_template`、`last_batch_mode`
- [ ] 记住并在启动时恢复上次选择的模板；自定义模板已删除时回退到第一个内置模板
- [ ] 记住并在启动时恢复上次选择的批量模式；持久化值非法时回退默认（全组合）
- [ ] 面板选择变化时「改一次存一次」回写配置
- [ ] `template_panel` 增加模板选择变化信号（携带模板名）
- [ ] `queue_panel` 增加 `set_batch_mode()` 与批量模式变化信号

验收：

- [ ] 重启后自动恢复上次选择的模板和批量模式
- [ ] 自定义模板被删除或批量模式值非法时安全回退，不报错
- [ ] UI 控件不直接读写配置文件

### 17.2 位置 / 尺寸 / 旋转独立重置

前置阅读：

- `docs/07-ui-design.md`（7 右侧参数栏、10 视觉规范）
- `docs/08-image-editor-design.md`

任务：

- [ ] 先读取 `src/app/widgets/transform_panel.py` 现有内容
- [ ] 在 `位置` / `尺寸` / `旋转` 三个分区标题右侧各加一个独立 `重置` 按钮
- [ ] 各重置只把对应参数还原为当前选中模板的值，互不影响（位置→仅 X/Y；尺寸→仅宽/高，位置不变；旋转→仅角度）
- [ ] 移除合并的 `重置位置 / 尺寸 / 角度` 按钮与角度旁的 `归零` 按钮
- [ ] 重置按钮采用幽灵样式（静止灰、悬停蓝、按下深蓝、禁用更灰），不使用红色
- [ ] 未选模板或未加载衣服/印花时三个按钮置灰
- [ ] 由 `main_window` 取模板换算值并按项合并进当前 `TransformState`

验收：

- [ ] 位置、尺寸、旋转可分别独立重置，互不影响
- [ ] 尺寸重置只改变宽 / 高，不改变位置 X / Y
- [ ] 按钮视觉层级符合 `docs/07-ui-design.md` 第 10 节

### 17.3 按钮去重（导出面板模板入口）

前置阅读：

- `docs/07-ui-design.md`（7.1 模板区域、7.7 操作按钮）

任务：

- [ ] 移除导出面板的 `应用为模板` 与 `重置为模板` 按钮（与模板区域的 `另存为` / `重置为模板` 是同一动作的重复入口）
- [ ] 模板相关操作统一留在模板区域，导出面板只负责输出与导出

验收：

- [ ] 同一个动作在界面上只出现一次，命名一致
- [ ] 导出面板仅保留输出设置与 `导出当前单张`

### 17.4 「重置为模板」归位并更名为「位置尺寸旋转重置为当前模板」

前置阅读：

- `docs/07-ui-design.md`（7 右侧参数栏、10 视觉规范）

任务：

- [ ] 把模板区域的 `重置为模板` 按钮移出，移到参数栏底部（旋转分区下方）
- [ ] 更名为 `位置尺寸旋转重置为当前模板`，与三个分项 `↺ 重置` 构成「全部 + 分项」两级
- [ ] 还原逻辑改为把位置/尺寸/旋转整体设为模板值，并与分项重置同走 `_apply_preview_transform`
- [ ] 与三个分项重置一起受「未加载图片时置灰」控制
- [ ] 采用安静、全宽、悬停出强调色的样式（不使用红色）

验收：

- [ ] 模板区域只剩 `保存` / `另存为`，不含整体重置
- [ ] `位置尺寸旋转重置为当前模板` 在旋转分区下方，未加载图片时置灰
- [ ] 点击后位置、尺寸、旋转一并还原为当前选中模板

### 17.5 模板删除按钮

前置阅读：

- `docs/07-ui-design.md`（7.1 模板区域）

任务：

- [ ] 在模板区域增加 `删除` 按钮（复用 `template_service.delete_template`）
- [ ] `删除` 仅对自定义模板可用，选中内置模板时隐藏（与 `保存` 一致）
- [ ] 删除前弹二次确认对话框；确认后才删除
- [ ] 删除后刷新下拉框并回选第一个内置模板，同步持久化选择
- [ ] `删除` 用红色文字提示危险但保持安静样式

验收：

- [ ] 可在界面上删除自定义模板，无需手改 `templates.json`
- [ ] 内置模板不显示 `删除`
- [ ] 删除有二次确认，取消则不删

### 17.6 参数/导出面板紧凑化与命名

前置阅读：

- `docs/07-ui-design.md`（7.2 位置区域、7.3 尺寸区域、7.5 输出设置区域）

任务：

- [ ] 「位置」的 X、Y 输入框放在同一行（标签简化为 `X` / `Y`）
- [ ] 「尺寸」的宽、高输入框放在同一行（标签简化为 `宽` / `高`），`锁定宽高比例` 在其下方
- [ ] 导出面板「格式」「质量」放在同一行
- [ ] 底部整体重置按钮更名为 `位置尺寸旋转重置为当前模板`
- [ ] 仅改布局/文案，不动同步与导出逻辑

验收：

- [ ] X/Y 一行、宽/高一行、格式/质量一行，界面更紧凑
- [ ] 拖动/缩放预览后输入框仍正常同步
- [ ] 质量仍仅在 JPG 时可用

## 18. 后续暂缓任务

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

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