diff --git a/docs/tasks/T-637.md b/docs/tasks/T-637.md index ede12e5..96b7d8c 100644 --- a/docs/tasks/T-637.md +++ b/docs/tasks/T-637.md @@ -32,6 +32,8 @@ created: 2026-07-16 ## 实现方案 +> 推进顺序建议:先完成纯逻辑(renderer、占位符校验、默认模板、分类说明迁移进 `build_job_specs()`)并测试绿,再动弹窗 GUI,最后补打包断言;避免 20 条验收项一次性集中风险。 + ### 1. 主界面标题行 - 调整 `ProductSuiteTab._build_prompt_section()` 的标题行顺序: @@ -51,10 +53,10 @@ created: 2026-07-16 - 弹窗使用可调整的左右分栏,初始比例 `1:1`,设置合理最小尺寸;左侧是可编辑模板,右侧是只读最终提示词预览。 - 第一行从左到右提供: - 「保存」:校验通过后原子写入用户模板,并显示轻量中文成功提示; - - 「恢复默认」:二次确认后用安装包内置模板覆盖当前用户模板,同时更新编辑区和预览区;恢复完成后已落盘,不要求再次点击保存; + - 「恢复默认」:二次确认后仅把内置模板回填到编辑区并刷新预览,**不直接写盘**;确认弹窗需明示会丢弃编辑区当前未保存修改。落盘仍走「保存」,未保存关闭时由统一的三选项流程兜底,保证全程只有「保存」一条原子写盘路径; - 右侧「预览分类」下拉框:默认选中「白底图」,可切换当前固定分类和当前项目已有自定义分类。 - 左侧编辑区顶部提供「插入变量」菜单或按钮菜单。用户选择变量后,在当前光标位置插入,不要求手工记忆占位符。 -- 右侧预览区不可编辑、不可获得保存语义;内容使用当前商品任务的真实平台、地区、语言、比例、商品 ID、分类、参考图序号和卖点。当前值为空时使用明确的中文示例值,内部 `draft_` 标识不得出现在预览中。 +- 右侧预览区不可编辑、不可获得保存语义;内容使用当前商品任务的真实平台、地区、语言、比例、商品 ID、分类、参考图序号和卖点。预览的序号类占位符使用固定值:`{主参考图序号}`=1、`{分类序号}`=1、`{分类总数}`=该分类当前配置数量,不随预览分类切换之外的因素变化。当前值为空时使用明确的中文示例值,内部 `draft_` 标识不得出现在预览中。 - 编辑内容变化后使用约 `200ms` 单次防抖刷新,连续输入不得触发大量重复渲染或造成界面卡顿。 - 关闭存在未保存修改的弹窗时,提供「保存」「不保存」「取消」三种中文选择;保存校验失败时保持弹窗打开。 @@ -78,9 +80,9 @@ created: 2026-07-16 {商品卖点与要求} ``` -- `{分类要求}`、`{图片比例}`、`{参考图规则}`、`{商品卖点与要求}`为必需占位符;缺失时预览区显示中文校验结果,「保存」禁用。 +- `{分类要求}`、`{套图分类}`、`{图片比例}`、`{参考图规则}`、`{商品卖点与要求}`为必需占位符;缺失时预览区显示中文校验结果,「保存」禁用。`{套图分类}`列为必需是因为固定分类的说明文案不保证包含分类名,删掉后最终提示词可能丢失分类信息。 - 未知占位符、未闭合花括号和渲染后仍残留的占位符都视为错误,不得静默原样发送给模型。 -- 重复使用合法占位符允许保存;普通花括号文本如确有需要,应定义明确转义规则并覆盖测试,不使用字符串猜测。 +- 重复使用合法占位符允许保存;第一版模板**不支持字面花括号**,任何非合法占位符形式的花括号一律校验报错,不定义转义规则,也不做字符串猜测。 - 占位符替换必须使用结构化上下文字典和统一 renderer,不允许在 GUI 中连续手写 `.replace()` 拼接另一套规则。 ### 4. 默认模板和分类要求 @@ -103,6 +105,7 @@ created: 2026-07-16 - 将当前仅存在于 GUI 的固定分类说明迁移或集中到业务层,渲染为 `{分类要求}`;GUI 通过同一来源显示说明,不能复制另一份字典。 - 自定义分类的 `{分类要求}`必须明确包含自定义分类名称,例如「生成商品套图中的『使用方法图』,按照该分类名称表达用途」,不能使用不含分类名的泛化文案。 - `{差异化要求}`至少包含分类内序号和“与本分类其他图片采用不同构图、角度或场景”的约束。若第一版没有可靠的商品语义,不自动编造具体卖点、参数或使用场景。 +- 退化规则:分类总数为 1 时 `{差异化要求}`渲染为空,最终提示词不得出现“与本分类其他图片不同”这类无意义残句;renderer 需折叠占位符独占一行且替换为空后产生的空白行。 - `{参考图规则}`必须与当前实际请求一致。每个 `image_studio_job` 只有一个 `source_asset_id` 时,应明确表述当前图片是本任务唯一主参考图,不得声称未提交的其他图片也参与参考。 ### 5. 强制保护规则 @@ -143,15 +146,16 @@ created: 2026-07-16 - [ ] 点击「提示词设置」打开左右等宽弹窗,左侧可编辑、右侧只读,默认预览白底图最终提示词。 - [ ] 预览分类下拉可以切换固定分类和当前自定义分类;切换只刷新预览,不修改项目配置。 - [ ] 从「插入变量」菜单选择每个合法变量,都会插入到当前光标位置并在约 200ms 后刷新预览。 -- [ ] 当前商品数据完整时,预览正确替换平台、地区、语言、比例、商品 ID、参考图序号、分类序号/总数和商品卖点。 +- [ ] 当前商品数据完整时,预览正确替换平台、地区、语言、比例、商品 ID 和商品卖点;序号类占位符按约定固定为主参考图序号 1、分类序号 1/该分类配置总数。 - [ ] 临时草稿预览使用 `未绑定商品` 或等价中文值,不显示内部 `draft_` 标识。 - [ ] 删除必需占位符、输入未知变量、花括号未闭合或渲染残留变量时不能保存,并显示中文校验错误。 - [ ] 固定分类说明实际进入提示词;自定义分类提示词明确包含自定义分类名称。 - [ ] 同一分类多张任务的最终提示词包含各自序号/总数和差异化要求,不再完全相同。 +- [ ] 分类总数为 1 时,该分类最终提示词不含差异化残句,也不留悬空空行。 - [ ] 参考图规则与实际单个 `source_asset_id` 一致,不声称未提交图片参与参考。 - [ ] 强制商品一致性、禁止虚构参数/价格/尺码等规则始终出现在最终预览和真实请求中,用户不能从编辑器删除。 - [ ] 保存后关闭并重启程序仍加载用户模板;已有用户模板不会被启动初始化或软件升级覆盖。 -- [ ] 「恢复默认」经确认后立即恢复、落盘并刷新预览,只影响商品套图模板。 +- [ ] 「恢复默认」经确认后回填编辑区并刷新预览,不直接写盘;经「保存」后才落盘,且只影响商品套图模板。 - [ ] 弹窗存在未保存修改时关闭会出现保存/不保存/取消三选项,任何失败都不损坏原模板。 - [ ] 同一 context 下右侧预览文本与新建 job 保存的最终 prompt 完全一致。 - [ ] 生成开始后再修改模板不影响本轮已经冻结的 job;历史重试继续使用历史 prompt 快照。 @@ -161,8 +165,8 @@ created: 2026-07-16 ## 测试要求 -- 新增纯逻辑测试覆盖全部合法占位符、必需变量、未知变量、未闭合/转义花括号、重复变量、强制规则追加和 Unicode 文本。 -- 覆盖白底图、其他固定分类、自定义分类、正式商品、临时草稿、分类多张和单参考图 context。 +- 新增纯逻辑测试覆盖全部合法占位符、必需变量(含 `{套图分类}`)、未知变量、未闭合/字面花括号报错、重复变量、强制规则追加和 Unicode 文本。 +- 覆盖白底图、其他固定分类、自定义分类、正式商品、临时草稿、分类多张、分类总数为 1 的差异化退化与空行折叠,以及单参考图 context。 - 覆盖用户模板首次初始化、不覆盖已有文件、原子保存失败保持原文件和恢复默认。 - `tests/test_product_suite_gui.py` 覆盖标题行按钮顺序、AI 帮写运行时取消按钮、弹窗初始分栏、默认白底图、分类切换、变量插入、防抖刷新、只读预览、保存校验和未保存关闭三选项。 - 覆盖预览 renderer 与 `build_job_specs()` 最终 prompt 相等,以及生成运行中模板变更不污染本轮 job。 @@ -197,4 +201,5 @@ git diff --check ## 执行记录 +- 2026-07-16 补:按全栈评审调整规格——`{套图分类}`升为必需占位符;第一版禁止字面花括号(不做转义规则);「恢复默认」改为只回填编辑区、落盘统一走「保存」;预览序号类占位符固定值约定;分类总数为 1 时差异化要求退化为空并折叠空行;补充纯逻辑先行的推进顺序建议。 - 待实现。