cmshoppe/docs/tasks/T-576.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-576	②③生成/更新内容模式下拉与缺失内容阻断	7	T-575	DONE	2026-07-09

问题 / 背景

当前②AI生成模块用「生成封面图片（成本较高）」checkbox 控制是否生成封面：

• 关闭：只生成标题。
• 开启：生成标题和封面。

这个设计能控制生图成本，但正式使用时不够精确：

• 用户无法只补生成封面；例如已生成标题后，想单独补封面，需要依赖当前增量逻辑和 checkbox 语义，不够直观。
• 「图片」文案不够准确，本模块实际处理的是商品封面，不是商品全部图片。
• ③更新蝦皮目前依赖⑤设置里的「允许更新封面」checkbox。这个开关离真实更新动作太远，用户在③点击开始更新时不一定清楚本轮到底更新标题、封面还是图文。
• 如果②只生成了标题，③却想更新封面，当前需要更明确地在开始前阻断并提示缺少新封面，避免进入 Chrome/CDP 后才失败。

产品结论

需求合理，建议做，但需要统一成“内容模式”而不是布尔开关。

②AI生成模块下拉：

• 只生成标题
• 只生成封面
• 生成标题和封面

③更新蝦皮模块下拉：

• 只更新标题
• 只更新封面
• 更新标题和封面

文案统一使用「封面」，不用「图片」，避免用户误解为商品详情图或所有商品图片。

方案

1. ②AI生成模式

• app/appconfig.py

  • 增加兼容字段 ai.generate_mode，取值：
    • title
    • cover
    • title_cover
  • 兼容旧字段 ai.generate_cover：
    • false → generate_mode=title
    • true → generate_mode=title_cover
  • 保存设置时可继续写回 generate_cover 兼容值，但 GUI 主逻辑以 generate_mode 为准。

• app/ai.py

  • is_generatable_task()、generation_component_totals()、generate_batch() 支持三种生成模式。
  • title：只补缺失标题，不调用生图。
  • cover：只补缺失封面；需要当前任务已有 new_title，否则该任务不进入本轮，并在 GUI 给出可理解提示。
  • title_cover：缺标题先生成标题，再生成封面；已有标题只补封面，已有封面只补标题或跳过。

• app/gui/tabs/generate.py

  • 把「生成封面图片（成本较高）」checkbox 改成下拉框，例如 label「生成内容」。
  • 下拉选项：
    • 只生成标题
    • 只生成封面
    • 生成标题和封面
  • 开始生成时按选项筛选任务和计算标题/封面进度。
  • 只生成封面但当前筛选任务都缺少新标题时，中止并中文提示：当前筛选结果没有可生成封面的任务，请先生成标题。
  • 日志开头写明本轮生成内容，例如：本轮生成内容：只生成封面。

2. ③更新蝦皮模式

• app/appconfig.py

  • 增加兼容字段 shopee_update.update_mode，取值：
    • title
    • cover
    • title_cover
  • 兼容旧字段 shopee_update.allow_cover_update：
    • false → update_mode=title
    • true → 默认 update_mode=title_cover，或保留用户当前选择。
  • allow_real_submit 仍保留在⑤设置里，继续作为真实提交总开关。

• app/gui/tabs/settings.py

  • 移除普通设置页里的「允许更新封面」用户控件。
  • 保存设置时保留旧字段兼容，不破坏已有配置文件。

• app/gui/tabs/apply.py

  • 在③更新蝦皮左下角增加「更新内容」下拉框。
  • 下拉选项：
    • 只更新标题
    • 只更新封面
    • 更新标题和封面
  • 原「检查本轮更新」「开始更新」「停止」等按钮向右挪，避免控件拥挤。
  • 选择包含封面的模式时，确认弹窗中明确提示：本轮将更新线上封面。
  • 选择「只更新标题」时，不要求 new_cover_path，也不触发封面更新。
  • 选择「只更新封面」时，不要求标题改动，但必须有 new_cover_path。
  • 选择「更新标题和封面」时，必须同时有 new_title 和 new_cover_path。

3. 开始更新前置校验

点击③「开始更新」后，在账号预检和 CDP 打开商品页之前，先按当前更新模式校验当前筛选结果：

• 只更新标题：缺 new_title 的任务阻断。
• 只更新封面：缺 new_cover_path 的任务阻断。
• 更新标题和封面：缺任一内容的任务阻断。

阻断时不启动 ApplyWorker、不打开 Chrome tab、不改 DB 状态，弹中文提示，例如：

当前筛选结果中有 3 条缺少新封面，不能执行“只更新封面”。
请先回到②AI生成选择“只生成封面”或“生成标题和封面”。
示例商品ID：25120403046、26887160467、28431952912

商品 ID 最多展示 5 个，避免弹窗过长。

「检查本轮更新」也应按当前更新模式展示缺失汇总，但检查模式可以只报告、不真实执行。

验收要点

• ②AI生成页不再显示「生成封面图片（成本较高）」checkbox，改为「生成内容」下拉。
• ②选择 只生成标题 时不调用生图、不要求旧封面/封面提示词。
• ②选择 只生成封面 时只补封面；缺新标题的任务不进入本轮，并给中文提示。
• ②选择 生成标题和封面 时保持原图文生成闭环，仍支持增量补缺。
• ⑤设置页普通 UI 不再显示「允许更新封面」checkbox。
• ③更新蝦皮左下角新增「更新内容」下拉，按钮布局不拥挤。
• ③选择 只更新标题 时允许任务无新封面。
• ③选择 只更新封面 时缺新封面必须在开始更新前阻断。
• ③选择 更新标题和封面 时缺新标题或新封面都必须阻断。
• 阻断发生在打开 Chrome 商品详情页之前，不写失败状态，不启动真实更新。
• 确认弹窗能按更新模式展示本轮将更新标题/封面/图文。
• 保留敏感和高风险边界：仍需要⑤ allow_real_submit=true 和③最终确认弹窗。
• 验证命令：
  • py -3.10 -m unittest tests.test_gui
  • python -m ruff check app tests main.py
  • py -3.10 -m compileall app main.py
  • py -3.10 -m unittest discover -s tests
  • git diff --check

边界（不改什么）

• 不改 AI/cmhub HTTP 协议、并发、重试、下载保存逻辑。
• 不改 DB schema，继续使用 new_title / new_cover_path 判断内容是否就绪。
• 不改 Excel 导入/回写格式。
• 不改 CDP/Shopee 页面操作细节；只在进入真实更新前增加本地前置校验。
• 不增加逐条人工审核流程。

执行记录

• 2026-07-09 完成。
• 文档：同步 docs/04-architecture.md、docs/02-requirements.md、docs/api.md、docs/routes.md、docs/current-state.md，明确②「生成内容」下拉、③「更新内容」下拉、旧布尔字段兼容和开始更新前缺失内容阻断。
• 配置：app/appconfig.py 新增 ai.generate_mode / shopee_update.update_mode 归一与兼容 helper；旧 ai.generate_cover、shopee_update.allow_cover_update 继续写回兼容。
• ②AI生成：app/gui/tabs/generate.py 将封面 checkbox 改为「生成内容」下拉；app/ai.py、GenerateWorker 支持只生成标题、只生成封面、生成标题和封面，进度和日志按模式统计。
• ③更新蝦皮：app/gui/tabs/apply.py 新增「更新内容」下拉；开始更新/检查前按模式校验缺少的新标题或新封面，阻断时不启动 ApplyWorker、不打开 Chrome、不写失败状态；确认弹窗和运行日志展示更新内容。
• ⑤设置：app/gui/tabs/settings.py 从普通设置页移除「允许更新封面」用户入口，仅保留旧字段兼容写回；保存设置时尽量读取磁盘最新更新模式，避免覆盖③下拉选择。
• 更新执行：app/editor.py、ApplyWorker 按 update_mode 只传递本轮需要改的标题/封面，避免只更新标题时误换封面、只更新封面时误改标题。
• 测试：补充/更新 tests/test_appconfig.py、tests/test_ai.py、tests/test_gui.py，覆盖模式兼容、只生成封面、②/③下拉持久化、③缺失内容阻断和 worker 传参。
• 验证通过：python -m compileall app main.py；python -m unittest discover -s tests（313 tests）；git diff --check。