diff --git a/docs/tasks/T-611.md b/docs/tasks/T-611.md new file mode 100644 index 0000000..4f859b0 --- /dev/null +++ b/docs/tasks/T-611.md @@ -0,0 +1,88 @@ +--- +id: T-611 +title: ③更新蝦皮恢复每条商品前台激活以保障封面上传与拖拽 +phase: 7 +deps: [T-571, T-562] +status: TODO +created: 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 条封面更新,记录每条上传、拖首位、确认提交结果;如线上环境不可用,在执行记录中如实说明。 + +验证命令: + +```bash +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、图片目录、任务排序、账号并行、生成、导出或任何①至⑥之外的模块。 + +## 执行记录 + +- 待执行。