cmshoppe/docs/tasks/T-611.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-611	③更新蝦皮恢复每条商品前台激活以保障封面上传与拖拽	7	T-571 T-562	DONE	2026-07-11

问题 / 背景

T-571 为降低③更新蝦皮批量运行时抢焦点，将同一账号本轮仅第一条任务设为 bring_to_front=True，后续任务改为后台新建/复用商品 tab。实际运行表明，该策略会让新增详情 tab 不切换到前台，蝦皮封面上传、图片管理器刷新和拖拽到第一位经常失败。

这不是单纯的 CDP 连通问题。蝦皮封面更新依赖可见页面的渲染、计时器、上传状态和拖拽排序；后台/被遮挡 tab 可能被 Chrome 节流。T-571 的失败后前台恢复发生在旧图已删除、上传中或拖拽失败之后，只能覆盖少量已识别 reason，无法作为生产稳定性的主要保障。

①导入采集和⑥AI工场拉取主图均是只读流程，T-562 的“不主动切前台”仍有价值，不能一并回滚。

本任务目标：只恢复③更新蝦皮每条商品在操作前的前台 tab 激活，优先保障上传、拖拽和线上提交稳定；保持①采集和⑥AI工场的后台读取行为。

方案

1. 仅回滚③的低频前台策略

修改 app/gui/workers.py、必要时 app/editor.py：

• ApplyWorker 对每条③更新任务都调用 editor.apply_task(..., bring_to_front=True)；不再按账号维护“本轮仅第一条前台”的集合、锁或判断 helper。
• 每条更新在 editor.open_product(..., bring_to_front=True) 中：
  • 新建商品 tab 使用前台创建语义，不能传 background=True。
  • 复用已有商品 tab 时显式执行 Page.bringToFront。
  • 在标题更新、封面删除/上传/拖拽、站点确认框和最终「更新」提交前，当前商品页必须是本轮操作目标。
• 保留 open_product(..., bring_to_front=...) 与 apply_task(..., bring_to_front=...) 参数，供①采集、⑥AI工场和单元测试继续明确表达后台读取；不做破坏性 API 删除。
• T-571 的后台失败前台恢复代码可保留为兼容兜底，但③标准批量路径不再依赖该分支；不得因此重新实现或重复执行删除/上传/拖拽步骤。

2. 明确保留①和⑥静默读取边界

• editor.collect() 继续调用 open_product(..., bring_to_front=False)。
• image_studio.pull_remote_main_image_urls() 继续调用 open_product(..., bring_to_front=False)。
• 后台创建 tab 的 background=True 仅用于上述只读路径；不得因本任务改成所有 CDP 新 tab 都前台。
• 不增加⑤设置开关。③是真实线上提交和封面交互流程，本版以稳定性优先，不向用户暴露“后台更新”这种容易导致不稳定的选项。

3. 文档与运行提示同步

• 更新 docs/04-architecture.md、docs/routes.md 中 T-571 留下的“③每账号仅一次前台 + 失败升级”现状，改为：①/⑥静默读取，③每条更新前台激活；明确这是一项可靠性边界。
• T-571 任务文件保留历史事实，不倒改其执行记录；T-611 作为后续策略修正记录。
• ③运行日志与普通 UI 不展示 CDP 参数、Page.bringToFront 或英文技术细节；现有中文进度/失败文案保持。

验收要点

• 同一账号连续 N 条③更新任务，editor.apply_task 每条均收到 bring_to_front=True；不再出现第二条起传 False。
• 新建更新商品 tab 不使用后台创建；复用 tab 时执行前台激活，当前商品页成为本轮操作目标。
• ①采集与⑥AI工场拉图继续传 bring_to_front=False，不会因本任务恢复抢前台。
• T-571 的后台恢复代码不在正常③路径执行，不导致二次删图、二次上传或二次拖拽。
• 多账号并行时，每个真实更新任务仍会在自身账号 Chrome 前台执行；不改任务分配、并行上限或提交确认边界。
• 使用同一账号连续更新至少 3 个带封面的测试商品：每条都能加载详情页、上传新图、拖至第一位、点击站点确认框中的「更新」并返回结果页。
• 不改 CDP 选择器、Chrome 启动参数、账号登录、SQLite、Excel、AI/cmhub、①至⑥其他业务流程。

测试要求

更新或新增：

• tests/test_gui.py
  • 将 T-571 的同账号跨分批前台断言改为：每条③更新均前台。
  • 覆盖多账号并行时每个任务均传 bring_to_front=True，不再依赖账号前台集合。
• tests/test_editor_login.py / tests/test_cdp.py
  • 覆盖 open_product(..., bring_to_front=True) 新建 tab 不传后台参数、调用 Page.bringToFront；复用 tab 同样激活。
  • 保留 bring_to_front=False 的采集/AI工场后台创建与不前台激活断言。
• 真实冒烟：使用测试商品连续执行至少 3 条封面更新，记录每条上传、拖首位、确认提交结果；如线上环境不可用，在执行记录中如实说明。

验证命令：

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

边界（不改什么）

• 不用 git revert 回滚整个 T-562/T-571 提交；只修正③的调用策略，保留①/⑥静默读取、T-571 的安全恢复逻辑和其它已验证修复。
• 不改变封面删除、上传、稳定等待、拖拽、站点确认框、提交结果判断或 tab 关闭语义。
• 不新增 Chrome 启动参数，不尝试绕过 Chrome/Shopee 的可见性、风控或限流机制。
• 不做用户设置开关、后台更新模式或自动登录。
• 不改数据库 schema、图片目录、任务排序、账号并行、生成、导出或任何①至⑥之外的模块。

执行记录

• 2026-07-11：移除 ApplyWorker 的账号前台集合与锁，③每条更新任务固定传 bring_to_front=True；open_product 既有前台新建/复用 tab 与 Page.bringToFront 路径保持不变。
• 2026-07-11：保留①采集与⑥AI工场的 bring_to_front=False 后台只读调用，也保留 T-571 的后台失败安全恢复代码作为兼容直接调用兜底；正常③批量路径不再进入该分支。
• 2026-07-11：更新 docs/04-architecture.md、docs/routes.md，明确③每条真实更新以前台交互稳定性优先；更新 GUI/editor 单测，覆盖同账号跨批次每条均前台、前台新建 tab 和后台采集路径。
• 2026-07-11：干净 worktree 验证通过：python -m ruff check app tests main.py、py -3.10 -m compileall app main.py、py -3.10 -m unittest discover -s tests（387 项）、git diff --check。无提交 CDP 冒烟先遇到首个账号调试端口未运行，后在已运行账号打开默认测试商品时收到“商品 ID 不正确”；两次均未上传、删图或提交。连续 3 条真实封面更新需在具备有效测试商品的账号环境中补验。