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

• 编写项目愿景文档：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 和日志使用

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

任务：

• 先读取 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
• 实现输出目录选择
• 实现输出格式选择
• 实现质量选择
• 实现导出当前单张
• 实现应用为模板入口（后移除：与模板区域「另存为」重复，见 17.3）
• 实现重置为模板入口（后移除：与模板区域「重置为模板」重复，见 17.3）
• 显示当前操作影响范围提示

验收：

• 缺少衣服或印花时导出按钮禁用
• 输出目录不可写时提示用户并记录日志
• 单张导出调用 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. 体验优化（持久化与独立重置）

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

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 穿搭
• 导出上架流程
• 自动抠图
• 自动识别衣服区域
• 移动端应用