99 lines
7.3 KiB
Markdown
99 lines
7.3 KiB
Markdown
---
|
||
id: T-556
|
||
title: ②AI生成运行日志运营化与错误脱敏
|
||
phase: 7
|
||
deps: [T-519, T-553, T-555]
|
||
status: TODO
|
||
created: 2026-07-08
|
||
---
|
||
|
||
## 问题 / 背景
|
||
|
||
②「AI生成」已经有用户可见滚动日志、标题/图片双进度条和阶段用时，但当前日志仍偏工程调试视角：cmhub 失败时可能把 `requests` 原始异常、URL、接口路径、`/api/v1/...` 或下载地址相关细节带到运行日志里；本轮开始/结束也缺少明确开始时间、完成时间和总用时。对正式用户来说，这些信息既增加理解负担，也会带来服务端结构暴露、截图发客服时泄露环境细节、售后沟通成本变高的问题。
|
||
|
||
从独立盈利的全栈开发工程师角度看，②日志应该服务三件事：
|
||
|
||
- **让运营知道发生了什么**：本轮什么时候开始、生成多少标题/图片、当前卡在哪、失败是否会重试、最终用了多久。
|
||
- **让客服/开发能定位问题**：用户可见日志给出商品 ID、店铺、阶段、可操作原因；更细的 URL、接口路径、traceback 留在本地诊断日志，不放在 GUI 滚动日志。
|
||
- **降低商业风险**：不把 cmhub API 路径、媒体 URL、Base URL、query token、请求方法等技术细节暴露给普通用户或截图，避免用户误以为软件“报了一堆接口错误”，也避免把可复用内部结构传播出去。
|
||
|
||
## 全栈工程分析
|
||
|
||
- 当前②可见日志主要由 `app/gui/workers.py` 的 `GenerateWorker._format_generation_event()`、`_retry_message()`、`_format_generate_completion()` 和 `_log_run_event()` 生成；底层 AI/cmhub 调用在 `app/ai.py` 中抛出 `CMHubError` / `AIError`。
|
||
- 最小改动点应放在 **GUI worker 的用户日志格式化层**，不要改 cmhub HTTP 协议、重试策略、并发策略或 DB schema。
|
||
- 技术细节不能简单“全部吞掉”：本地 `data/logs/cmshopee.log` 和 SQLite `run_log_events` 仍需要保留可排查的阶段、错误码、状态码、耗时；但 GUI 滚动日志和可持久化的业务运行日志应使用用户可读、脱敏后的文案。
|
||
- T-555 已提供标题/生图实时用时标签，但日志仍需要最终总结行，便于用户复制一段日志给客服时包含完整上下文。
|
||
|
||
## 方案
|
||
|
||
1. **新增②用户日志脱敏/运营化格式化口径**
|
||
- 在 `GenerateWorker` 增加专用 helper，例如 `_user_log_detail(detail, phase=None, step=None, code=None, status=None)`。
|
||
- 用户可见日志中禁止出现：
|
||
- `http://...` / `https://...` 完整 URL。
|
||
- `/api/...`、`/api/v1/...`、`/generated/images/...` 等接口或媒体路径。
|
||
- `GET https://...`、`POST https://...`、`ConnectionError(... url=...)` 等原始请求异常片段。
|
||
- `image_url` 完整值、query string、token、API Key、Cookie、Authorization。
|
||
- 保留用户能行动的信息：错误类型、阶段、是否会重试、建议动作。例如：
|
||
- `cmhub 上游生成失败，请稍后重试`
|
||
- `等待 cmhub 返回超时，本条已失败；可稍后重试`
|
||
- `连接 cmhub 超时，请检查网络或稍后重试`
|
||
- `cmhub 模型别名不可用，请去⑤设置刷新别名并保存`
|
||
- `点数不足，请先充值`
|
||
- 诊断日志仍可写脱敏后的 code/status/step/traceback；普通 GUI 滚动日志不展示接口路径。
|
||
|
||
2. **本轮开始日志增加绝对开始时间**
|
||
- `GenerateWorker.execute()` 开始时记录：
|
||
- `started_at_text`：本地时间，如 `2026-07-08 19:30:12`。
|
||
- `started_monotonic`：用于计算总用时。
|
||
- 第一行日志从当前：
|
||
- `[开始] 本轮生成 7 条：标题0，图片7；...`
|
||
- 调整为类似：
|
||
- `[开始] 2026-07-08 19:30:12 本轮生成 7 条：标题0，图片7；标题并发4，图片并发5，cmhub实际生图并发5，下载并发5`
|
||
- 标题-only 模式也同样带开始时间。
|
||
|
||
3. **本轮完成/停止/失败总结增加完成时间和总用时**
|
||
- `_format_generate_completion(summary)` 增加：
|
||
- 完成/停止/失败时间。
|
||
- 总用时，格式建议 `12秒`、`3分08秒`、`1小时02分05秒`。
|
||
- 标题/图片/失败计数继续保留。
|
||
- 成功示例：
|
||
- `[完成] AI生成完成：标题7/7，图片7/7，失败0；完成时间 2026-07-08 19:38:22，总用时 8分10秒`
|
||
- 停止示例：
|
||
- `[停止] AI生成已停止：标题3/7，图片1/7，失败0；停止时间 2026-07-08 19:33:40，总用时 3分28秒`
|
||
- 失败示例：
|
||
- `[失败] AI生成失败：标题2/7，图片0/7，失败5；失败时间 2026-07-08 19:34:02，总用时 3分50秒`
|
||
|
||
4. **重试与失败行统一为用户可读中文**
|
||
- 重试行保留“第几次重试”，但 reason 走 `_user_log_detail()`：
|
||
- `[标题] 1/7 商品 28431952912（主店）调用失败，准备重试 1/2：cmhub 上游暂不可用`
|
||
- 单条失败行不要显示 `cmhub upstream_error: ...`、接口路径或原始 URL：
|
||
- `[失败] 商品 28431952912（主店）标题生成失败：cmhub 上游生成失败，请稍后重试`
|
||
- 如果底层错误包含 `not_found`，用户可见文案不要写 `/api/v1/models`，改成：
|
||
- `cmhub 网关接口不可用，请检查⑤设置中的 Base URL，或联系服务方确认网关版本`
|
||
|
||
5. **保留排障能力但分层**
|
||
- GUI 滚动日志和 SQLite `run_log_events.message`：偏运营可读、脱敏、可截图。
|
||
- 本地诊断日志 `data/logs/`：保留脱敏后的 `code/status/phase/step/elapsed_ms` 和 traceback；如确需 URL，也必须去掉 query token 和 API Key，并优先只记录 host 或 route 分类。
|
||
- `CMSHOPEE_DEBUG_CMHUB_IMAGE_URL=1` 的调试 URL 输出仍只用于本机调试；普通用户默认不可见、不持久化。
|
||
|
||
6. **单测覆盖**
|
||
- `tests/test_gui.py` 增加/更新 `GenerateWorker` 相关测试：
|
||
- 开始日志包含日期时间，不破坏原有任务数、并发数信息。
|
||
- 完成/停止/失败总结包含总用时。
|
||
- cmhub 网络错误、404/not_found、上游失败、图片下载失败中包含 URL/接口路径时，GUI 日志和 `run_log_events` 不出现 `http://`、`https://`、`/api/v1/`、`/generated/images/`、`image_url`。
|
||
- 错误原因仍保留可行动中文文案。
|
||
|
||
## 验收要点
|
||
|
||
- ②AI生成运行日志第一行显示本轮开始时间。
|
||
- ②AI生成完成、停止、失败总结行显示完成/停止/失败时间和总用时。
|
||
- cmhub 调用失败、重试、单条失败日志不暴露完整 URL、接口路径、媒体路径、query token 或 API Key。
|
||
- 用户仍能从日志看出失败阶段、商品 ID、店铺、是否重试、下一步应检查网络/余额/别名/Base URL/稍后重试。
|
||
- 本地诊断日志仍保留脱敏后的工程排障信息，不影响开发定位。
|
||
- 不改 AI 生成流程、cmhub HTTP 协议、并发策略、重试策略、DB schema、Excel、Shopee/CDP。
|
||
- `python -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`py -3.10 -m unittest discover -s tests` 通过。
|
||
|
||
## 边界（不改什么）
|
||
|
||
本任务只优化②AI生成“用户可见滚动日志/业务运行日志”的文案、脱敏与总结信息；不新增日志窗口、不改进度条布局、不改 T-555 用时标签、不改 cmhub API、下载逻辑、计费 metadata、图片保存格式、SQLite schema、Excel 回写或蝦皮更新流程。
|