adminandClaude Opus 4.8
f767ec2660
§17.1 Preferences persistence: - Wire the previously-unused config_service; remember and restore the last-selected template and last batch mode. main_window loads config, distributes initial values, then persists on change (save-on-change). - template_panel: template_changed signal, select_template, current_template_state. queue_panel: set_batch_mode + batch_mode_changed. §17.2 Independent resets: - Replace the combined reset and 归零 with per-section 位置/尺寸/旋转 reset buttons (quiet ghost styling) that restore only their own aspect to the selected template. Size reset changes width/height only, leaving X/Y. Button de-dup: - Remove the export panel's 应用为模板 / 重置为模板 — literal duplicates of the template panel's 另存为 / 重置为模板. Template actions now live only in the template area; the export panel handles output only. Docs: PRD (6.6/6.9/9/10), architecture (4.12), UI design (7.x/10), development-rules (6, single-home actions + consistent naming), tasks.md (17). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
8.3 KiB
8.3 KiB
开发规则
1. 文档定位
本文档用于约束 AI 和开发者在本项目中的代码修改行为。后续任何开发、重构、检查、修复任务，都必须遵守本文档。
本文档优先级高于个人习惯和临时偏好。若任务说明与本文档冲突，必须先向用户确认，不能自行改变规则。
2. 开始任务前必须阅读
执行编码任务前，必须先阅读：
docs/01-product-vision.mddocs/02-prd.mddocs/03-technical-stack.mddocs/04-development-rules.md
若任务涉及图片预览、拖动、缩放、旋转、坐标换算或导出一致性，还必须阅读后续的图像编辑器设计文档。
若任务涉及打包、发布、局域网更新、多版本分发，还必须阅读后续的打包发布文档。
3. 技术栈约束
必须遵守：
- 使用 Python 3.7。
- 使用 PySide6 作为 GUI 框架。
- PySide6 使用兼容 Python 3.7 的版本，推荐
PySide6==6.5.3。 - 使用 Pillow 处理最终图片合成。
- 使用 JSON 保存配置和模板。
- 使用 PyInstaller 打包 Windows 桌面程序。
- 第一阶段目标系统为 Windows 10 / Windows 11。
禁止事项：
- 禁止切换到 Electron、Web 前端、C#、C++、Tkinter、wxPython 或其他 GUI 技术栈。
- 禁止将项目改造成前后端分离应用。
- 禁止依赖公网服务完成核心功能。
- 禁止在未说明必要性的情况下新增第三方依赖。
- 禁止使用只支持 Python 3.8 及以上的依赖版本。
4. 代码结构规则
必须遵守：
- UI 逻辑、业务逻辑、图片处理逻辑、配置逻辑应分离。
- 图片合成逻辑必须可以脱离 GUI 单独调用。
- 批量任务逻辑必须与单张合成逻辑复用同一套核心合成能力。
- 模板读写必须集中在专门模块中，不能散落在 UI 事件里。
- 日志写入必须集中管理，不能使用零散
print作为正式日志。
禁止事项：
- 禁止把所有功能写进一个
main.py或一个窗口类。 - 禁止在按钮点击事件中直接堆叠大量图片处理代码。
- 禁止复制粘贴两套近似的单张合成和批量合成逻辑。
- 禁止在多个模块中重复定义同一类配置结构。
- 禁止把临时调试代码提交为正式代码。
5. 图片处理规则
必须遵守：
- 衣服底图是最终导出画布的基础。
- 印花图叠加到衣服底图之上。
- 导出尺寸默认与衣服底图原始尺寸一致。
- 坐标、宽高、旋转角度应以衣服底图原始像素坐标系为准保存。
- 预览区缩放不应改变真实合成参数。
- 预览结果和最终导出结果必须尽量一致。
- 透明 PNG 的 alpha 通道必须正确保留。
- 文件路径必须兼容 Windows 中文路径。
禁止事项：
- 禁止修改原始衣服图片和原始印花图片。
- 禁止只按预览控件尺寸保存合成参数。
- 禁止把屏幕坐标直接当作最终导出坐标。
- 禁止在未确认的情况下裁剪、拉伸或压缩原始素材。
- 禁止忽略透明通道导致 PNG 印花出现黑底、白底或异常背景。
6. UI 与交互规则
必须遵守：
- UI 应优先服务批量制图工作流，避免装饰性复杂设计。
- 关键操作必须有明确按钮或输入入口。
- 拖动、缩放、旋转印花后，参数输入框必须同步更新。
- 用户通过参数输入框修改坐标、尺寸、角度后，预览必须同步更新。
- 批量处理时界面不能长时间无响应。
- 失败、缺文件、格式不支持、导出失败等情况必须给出用户可理解的提示。
- 同一个动作只应有一个入口；确需在多处触发时，必须使用同一个名称，且指向同一个实现。
- 「某个动作放在哪个面板」是一次性决定，不在每个面板各自重复设置。
- 逐面板实现 UI 后，应做一次跨面板整体走查，确认没有重复入口或同义不同名的按钮。
禁止事项：
- 禁止为了视觉效果牺牲操作效率。
- 禁止隐藏核心操作入口。
- 禁止让用户只能通过拖拽完成精确定位，必须保留参数输入能力。
- 禁止批量处理期间阻塞主界面且没有进度反馈。
- 禁止使用含糊错误提示，例如只显示“失败”。
- 禁止同一个动作在不同面板出现重复入口，或用不同名称表示同一个动作（例如「另存为」与「应用为模板」）。
7. 配置与模板规则
必须遵守：
- 配置文件使用 JSON。
- 自定义模板必须保存到本地配置或模板文件中。
- 内置模板和用户自定义模板需要能区分。
- 配置读取失败时应使用安全默认值，并记录日志。
- 配置写入前应尽量避免破坏已有用户配置。
禁止事项：
- 禁止把用户模板硬编码进业务逻辑。
- 禁止在程序启动时无提示清空用户配置。
- 禁止因为单个模板损坏导致整个程序无法启动。
- 禁止将配置写入程序安装目录中不适合写入的位置，除非该目录明确可写。
8. 日志与异常规则
必须遵守：
- 程序启动、图片加载、模板加载、导出开始、导出完成、异常信息都应记录日志。
- 日志保存到本地
logs目录。 - 用户可理解的错误提示和开发者可排查的日志信息应同时存在。
- 批量任务中单个文件失败时，应记录失败原因并继续处理剩余文件。
禁止事项：
- 禁止吞掉异常不记录。
- 禁止只在控制台输出异常。
- 禁止将完整异常堆栈直接作为普通用户提示。
- 禁止因单张图片失败中断整个批量任务，除非是全局不可恢复错误。
9. 文件修改规则
必须遵守：
- 每次任务只修改与当前任务直接相关的文件。
- 修改已有文件前必须先理解现有结构和调用关系。
- 新增文件应放在符合架构文档约定的位置。
- 删除文件、移动文件、重命名文件前必须确认不会破坏引用。
禁止事项：
- 禁止顺手重构与当前任务无关的代码。
- 禁止大范围格式化无关文件。
- 禁止删除用户素材、输出图片、配置文件或日志文件。
- 禁止把测试素材、临时输出、缓存文件混入源代码目录。
10. 依赖管理规则
必须遵守：
- 依赖版本应写入
requirements.txt。 - 新增依赖前必须说明原因。
- 新增依赖必须确认支持 Python 3.7 和 Windows。
- GUI、图片处理、打包相关依赖需要优先选择稳定版本。
禁止事项：
- 禁止直接使用未锁定版本的核心依赖进行正式开发。
- 禁止引入体积巨大但只使用很小功能的依赖。
- 禁止引入需要复杂系统安装步骤的依赖，除非用户明确同意。
- 禁止引入与 PySide6 事件循环冲突的 GUI 依赖。
11. 版本号规则
必须遵守：
- 软件名称和版本号必须从统一模块读取，例如
src/version.py。 - 标题栏显示版本号、打包产物版本号、发布目录版本号必须保持一致。
- 修改版本号时必须同步检查 UI 显示和打包发布配置。
禁止事项：
- 禁止在 UI、打包脚本、业务代码中重复硬编码软件名称和版本号。
- 禁止让多个模块各自维护不同版本号。
12. 验证规则
完成开发任务后，必须根据任务范围做验证：
- 文档修改：检查文件路径、标题、引用和明显格式问题。
- 依赖修改：验证依赖是否可在 Python 3.7 环境安装。
- GUI 修改：至少启动程序检查窗口是否能打开。
- 图片处理修改：至少验证一张衣服图和一张印花图的合成结果。
- 批量处理修改：至少验证成功、失败和进度反馈路径。
- 打包修改：验证 PyInstaller 打包产物能启动。
如果因为环境限制无法验证，必须在最终说明中明确说明未验证项和原因。
13. AI 执行规则
AI 执行任务时必须遵守：
- 先读相关文档，再改代码。
- 先说明将修改哪些文件，再执行修改。
- 遇到不明确需求时，优先根据现有文档保守实现；影响范围较大时必须询问用户。
- 不得自行扩大需求范围。
- 不得自行替换技术栈。
- 不得把临时方案伪装成最终方案。
- 不得为了完成任务隐藏失败、跳过验证或省略风险说明。
- 最终回复必须说明改了什么、验证了什么、还有什么未完成或未验证。