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. 已完成基础工作

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

1. 工程基础完善

1.1 日志服务

前置阅读：

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

任务：

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

验收：

• 启动程序后生成日志文件
• 程序启动信息写入日志
• 不使用 print 作为正式日志

1.2 路径与资源服务

前置阅读：

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

任务：

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

验收：

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

1.3 配置服务

前置阅读：

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

任务：

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

验收：

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

2. 核心数据模型

前置阅读：

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

任务：

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

验收：

• models.py 不依赖 PySide6 UI 控件
• 变换状态包含 x/y/width/height/rotation/keep_aspect_ratio
• 模型可以被 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 穿搭
• 导出上架流程
• 自动抠图
• 自动识别衣服区域
• 移动端应用