docs: 延后Phase4真实冒烟到设置安全开关后
- 新增T-404真实单条更新冒烟任务，并依赖T-501c安全开关 - 新增T-501c Shopee更新安全开关任务，默认关闭真实提交和封面更新 - 补充Phase4验收复核、取消语义、真机冒烟范围和tab策略 - 纳入Phase3/Phase4验收报告并同步current-state与progress
This commit is contained in:
chengma
@@ -0,0 +1,48 @@
|
||||
# 验收报告 · T-301 ~ T-303（含 T-302p + 采集关页修复）· Phase 3 AI 生成
|
||||
|
||||
- 日期：2026-06-27
|
||||
- 范围：Codex 完成的 Phase 3——T-301 `app/ai.py` 生成接口、T-302 Tab② 左右布局、T-302p `app/prompts.py` 提示词管理、T-303 开始生成（两段并发）+停止+进度；附带修复 e6d7de3（采集后关闭自动新建商品页）
|
||||
- 评审方式：编译检查 + 单元测试（本机实跑 ai/prompts）+ 逐模块源码阅读 + 对照 `docs/06-tasks.md` 验收要点
|
||||
- 结论：**通过，质量偏上。AI 接口健壮（脱敏/重试/多 API 形态/两段并发/失败隔离），提示词管理有完整防穿越校验。**
|
||||
|
||||
## 一、验证方法与结果
|
||||
|
||||
```
|
||||
python3 -m unittest discover -s tests -p "test_ai.py" # Ran 6 tests, OK（本机实跑）
|
||||
python3 -m unittest discover -s tests -p "test_prompts.py" # Ran 3 tests, OK（本机实跑）
|
||||
python3 -m unittest discover -s tests # Ran 53 tests, OK (skipped=2)
|
||||
```
|
||||
|
||||
- 本评审在 WSL 沙箱进行：临时安装 openpyxl + Pillow 后，**ai/prompts 测试本机实跑通过**（含重试、脱敏、jpeg 分辨率/质量、两段并发持久化、失败隔离、停止保持 collected）。
|
||||
- 仅 PySide6 的 `test_gui`/`test_workers` 在本机 skip；其“绿”以 Codex 在 Windows（`python` = PySide6 6.5.3）的运行为准。
|
||||
|
||||
## 二、逐任务核对
|
||||
|
||||
| 任务 | 结论 | 关键核对 |
|
||||
| --- | --- | --- |
|
||||
| T-301 `ai.py` | ✅ | `gen_title`/`gen_cover` 经 `get_model` 读 `config/ai_models.json` 明文 Key；角色模型校验类别/启用/必填字段；`gen_cover` 支持 `resolution`(512/1k/2k/4k)+`jpg_quality`+Pillow 存盘；`_call_with_retry` 退避重试；错误中文化；`_redact` 把 api_key 从异常/HTTP body 抹成 `***`；兼容两种图像 API（`images_edits` multipart / chat `image_url`），图片提取覆盖 b64/data-url/远程 url 下载 |
|
||||
| T-302 Tab② 布局 | ✅ | 左提示词（标题/封面多行）、右 批次/店铺/状态 三筛选 + 任务列表（店铺/商品id/旧/新标题/状态）；筛选变更即刷新 |
|
||||
| T-302p `prompts.py`+管理 | ✅ | 标题 `title_prompt.txt` 存/启动回显；封面多模板下拉 + 新建/保存/另存为/重命名/删除（存 `prompts/cover/`，模板名做非法字符 + `.`/`..` + 路径穿越校验、重名保护）；「插入标题」插 `{新标题}`；「预览」走 `render_prompt`；`render_prompt` 已接入 `generate_batch` 封面渲染 |
|
||||
| T-303 开始生成 | ✅ | 单「开始生成」+「停止」+进度 `标题/封面/失败`；`generate_batch` 先 `title_concurrency` 并发标题、再 `image_concurrency` 并发封面；每条封面成功即 `set_generated` 立即写库；停止取消未开始项（ThreadPoolExecutor 语义，符合“可取消未开始项”）；双击弹窗左右对照旧/新封面 |
|
||||
| 修复 e6d7de3 | ✅ | 区分“断开 CDP”与“关闭 target”，采集只关本轮自动新建的商品页，保留用户原有 tab。良好卫生修复 |
|
||||
|
||||
## 三、设计上做得好
|
||||
|
||||
1. **失败隔离**：某条标题失败→该条不进封面阶段、`mark_failed("generate")` 后其余继续；`summary.ok=False` 但不阻塞（test 实测覆盖）。
|
||||
2. **脱敏贯穿**：错误信息、HTTP 错误体、URLError 全走 `_redact`，不泄 Key。
|
||||
3. **两段式并发**严格按文档：标题全部完成→只对成功标题的任务并发生成封面。
|
||||
|
||||
## 四、小问题（不影响验收）
|
||||
|
||||
1. **标题提示词不做变量替换**：`generate_batch` 把 `title_prompt` 原样喂给 `gen_title`，只有封面提示词走 `render_prompt`。与设计自洽（新标题此时尚不存在，旧标题由 user 消息单独传入），但若用户在标题提示词里写 `{旧标题}` 不会被替换。建议在 Tab② 标题框旁注明“标题提示词不支持变量”，或也接入 `render_prompt`（仅旧标题/商品id/店铺）。
|
||||
2. `_call_once` 用单一 `timeout=max(connect, read)`（urllib 不分连接/读超时），取最大值合理，但 `connect_timeout_seconds` 语义偏弱。可接受。
|
||||
3. `_looks_base64` 是启发式判断，已先用 `data:`/`http` 前缀挡掉，误判风险低。
|
||||
|
||||
## 五、待办 / 边界
|
||||
|
||||
- ⚠️ `gen_title`/`gen_cover` 对真实 AI 服务商仍是 mock（urllib 全程打桩），未真连过一次；`config/ai_models.json` 里的真实 Key 仅本地、gitignore。
|
||||
- **建议**：进 Phase 4（③ 更新 shopee）前，做一次端到端真机冒烟——账号④登录 → ① 真机采集 1~2 条出图 → ② 用真实模型各生成 1 条标题 + 1 张封面 → 看 `images/<slug>/<id>_new.jpg` 落盘且分辨率/质量正确。这同时验掉之前累计的 CDP + AI 两条未冒烟链路。
|
||||
|
||||
## 六、总评
|
||||
|
||||
合格偏上的工程交付：ai.py 健壮（脱敏/重试/多 API 形态/两段并发/失败隔离）且本机实测通过，prompts 文件操作有完整防穿越校验，Tab② 提示词管理与生成闭环按文档落地。可推进 Phase 4（T-401 Tab③ 列表 + 筛选 + 开始更新确认弹窗）。
|
||||
@@ -0,0 +1,59 @@
|
||||
# 验收报告 · T-401 ~ T-403 · Phase 4 更新 Shopee
|
||||
|
||||
- 日期：2026-06-27
|
||||
- 范围：Codex 完成的 Phase 4——T-401 Tab③ 列表+批次/店铺/状态筛选+开始更新确认弹窗、T-402 确认后串行 apply、T-403 结果回写原 Excel + 结束弹窗汇总
|
||||
- 评审方式：编译检查 + 单元测试（本机实跑 excel）+ 逐模块源码阅读 + 对照 `docs/06-tasks.md` 验收要点
|
||||
- 结论：**代码层面通过，质量偏上。但 Phase 4 直接提交线上商品，真机冒烟为 0，是上线前的硬门槛缺口（验收覆盖问题，非代码问题）。**
|
||||
|
||||
## 一、验证方法与结果
|
||||
|
||||
```
|
||||
python3 -m unittest discover -s tests -p "test_excel.py" # Ran 8 tests, OK（含 write_back_results 实跑）
|
||||
python3 -m unittest discover -s tests # Ran 54 tests, OK (skipped=2)
|
||||
```
|
||||
|
||||
- 本评审在 WSL 沙箱进行：临时安装 openpyxl + Pillow 后，**excel 8/8 本机实跑通过**（含新增结果回写测试）。
|
||||
- UpdateTab/ApplyWorker 的 9 个 GUI 用例（含确认门控、串行成功/失败/未匹配、自动结果回写、结束弹窗、锁文件提示、预检拦截、引导去④）读源码 + 测试清单核对；其“绿”以 Codex 在 Windows（`python` = PySide6 6.5.3）的运行为准。
|
||||
|
||||
## 二、逐任务核对
|
||||
|
||||
| 任务 | 结论 | 关键核对 |
|
||||
| --- | --- | --- |
|
||||
| T-401 Tab③ 列表+筛选+确认弹窗 | ✅ | 批次/店铺/状态三筛选；「开始更新」仅作用于当前筛选的 actionable 任务；确认弹窗显示 批次/店铺/状态/任务数 + 明确写“打开编辑页、替换标题封面、点更新提交线上”风险；取消即 `已取消开始更新` 不执行；状态=失败可被筛出重试；无常驻提交开关 |
|
||||
| T-402 确认后串行 apply | ✅ | `QMessageBox.question` 默认 No，仅 Yes 才建 worker（`test_..._requires_confirmation` 实测“未确认不调用 apply”）；`ApplyWorker` 串行，逐条 `mark_running→apply_task→set_applied(True/False)`；单条失败继续；别名未匹配→`mark_skipped`；异常→`set_applied(False,error)` 继续；预检（无账号/Chrome 未起/未登录）→`blocked` 弹窗引导去④；停止取消未开始项 |
|
||||
| T-403 回写结果+结束弹窗 | ✅ | apply 完成后自动 `write_back_results` 回写 `新标题/新封面路径/更新状态` 到原 Excel（锁处理同 T-204）；`_update_status` 映射完整（成功/失败:原因/略过:原因/处理中/已取消/待更新）；结束 `QMessageBox` 汇总 成功/失败/略过；手动「回写结果」按钮作为锁文件失败后的重试入口 |
|
||||
|
||||
## 三、做得好
|
||||
|
||||
1. **失败状态可重试闭环**：`set_applied(False)` 只置 `status=failed`、保留 `stage=generated`，故失败任务仍满足 `_is_actionable_task`，再点「开始更新」即重试。与“状态=失败可重试”吻合。
|
||||
2. **committed 双重判定**：`bool(result.committed) and not result.error`，避免 editor 返回里 clicked 但带错时误判成功。
|
||||
3. **apply_task 不自动关页**（承 e6d7de3 决策）：③ 提交后保留商品页便于人工复核/排查，与采集自动关页区分清晰。
|
||||
|
||||
## 四、小问题（不影响验收）
|
||||
|
||||
1. **批量更新会堆积商品页**：③ 不自动关 tab，大批量后 Chrome 会累积多个编辑页。属已记录的有意决策，但 V2 可考虑成功提交后延时关页。
|
||||
2. 显示用 `_is_update_task` 比执行用 `_is_actionable_task` 宽（前者含 applied 及失败/略过带新数据的），两个谓词并存，逻辑正确但建议注释说明“显示集 ⊇ 可执行集”，防后续误改。
|
||||
|
||||
## 五、待办 / 边界（本阶段最关键）
|
||||
|
||||
- ⚠️ **T-402 是整条流水线唯一不可逆、真提交线上的步骤，却从未真机冒烟过。** `apply_task → change_title/replace_cover/click_update` 全程 mock，真实 Shopee 提交路径一次没跑；之前累计的 CDP 采集、AI 生成也都还没真连。
|
||||
- **强烈建议**（建议作为 Phase 4 正式验收门槛，当前单测全是 mock，不能替代）：在任何真实批量更新前，先做一次单条端到端真机冒烟——
|
||||
1. 账号④ 启动 + 人工登录；
|
||||
2. ① 真机采集 1 条出图；
|
||||
3. ② 真实模型生成 1 标题 + 1 封面；
|
||||
4. ③ 只选这 1 条、确认弹窗 → 看商品页标题/封面真被改且「更新」提交成功 → 看原 Excel 回写 `更新状态=成功`。
|
||||
|
||||
确认无回归后再放量。
|
||||
|
||||
## 六、总评
|
||||
|
||||
代码层面合格偏上的工程交付：串行执行/确认门控/失败隔离/预检引导/结果回写都按文档落地，且 excel 侧本机实测通过。但 Phase 4 直接操作线上商品，真机冒烟是上线前的硬门槛，目前为 0——务必在真用之前补上单条端到端冒烟。可在补冒烟的同时推进 Phase 5（T-501 设置·AI 模型管理 UI）。
|
||||
|
||||
## 七、Codex 复核补充
|
||||
|
||||
- 本报告总体结论有效：T-401/T-402/T-403 代码层面已满足当前文档验收，主要缺口是未对 Tab③ 真实线上提交做单条冒烟。
|
||||
- 测试数量需按环境区分：上文记录的是 Claude Code 在 WSL 沙箱的结果；Codex 完成 T-403 时本地验证为 `test_excel.py` 8 tests OK、`test_gui.py` 32 tests OK、`compileall` OK、全量 `python -m unittest discover -s tests` 88 tests OK。
|
||||
- “停止取消未开始项”应理解为协作式取消：不会中断正在执行中的当前商品更新，只阻止后续未开始任务继续执行。
|
||||
- “之前累计的 CDP 采集、AI 生成也都还没真连”表述需细化：Tab① 旧标题/旧封面采集此前已有真机冒烟记录；真实 AI 生成和 Tab③ 在线提交更新仍未完成端到端冒烟。
|
||||
- 当前决策：暂不立即真实更新 Shopee 商品。先推进设置模块，并新增 T-501c “Shopee 更新安全开关”；T-404 单条真实更新冒烟依赖 T-501c 完成后再执行。T-404 默认先只测标题更新，封面更新作为可选子项。
|
||||
- ③ 更新成功后不自动关闭商品编辑 tab 仍按当前保守策略处理；是否支持“成功后关闭本次新开 tab”放入 T-501c 设置项，不作为本次 Phase 4 验收阻塞。
|
||||
Reference in New Issue
Block a user