chengma
01e319cad8
- 保存或变更账号密码、AI API Key 前弹出本地明文保存提示 - 新增敏感值打码、结构化日志脱敏和自由文本替换工具 - 补充 GUI/appconfig 单测，覆盖明文提示和脱敏边界 - 同步任务看板、当前状态、架构、API、路由和编码规则文档
178 lines
16 KiB
Markdown
178 lines
16 KiB
Markdown
# 界面与流程结构
|
||
|
||
> 桌面工具，无前端路由。用 **5 Tab GUI（PySide6 `QMainWindow` + `QTabWidget`）+ 流水线** 约定界面职责与导航。
|
||
|
||
## Tab 顺序与职责（工作流优先）
|
||
|
||
```
|
||
① 导入采集 │ ② AI生成 │ ③ 更新shopee │ ④ 账号管理 │ ⑤ 设置
|
||
```
|
||
|
||
| Tab | 职责 | 风险 |
|
||
| --- | --- | --- |
|
||
| ① 导入采集 | 导入多个 Excel；任务列表；**采集**商品当前的旧标题/旧封面（只读），封面图下载本地；回写 Excel 旧字段 | 只读，低 |
|
||
| ② AI生成 | 左侧标题/封面**提示词**；右侧按批次/店铺筛选任务列表；AI 生成新标题/新封面；双击看新旧封面 | 不触线上，中 |
|
||
| ③ 更新shopee | 对**已生成**任务点击「开始更新」后弹窗确认；确认后打开编辑页换标题+封面并逐条点「更新」提交；结果回写 Excel | **写线上，高** |
|
||
| ④ 账号管理 | Shopee 账号（账号名/别名/数据目录/端口/密码本地明文仅参考/登录状态）；启动登录、检测登录、生成快捷方式 | 中 |
|
||
| ⑤ 设置 | AI 模型/API Key、本地图片目录、Chrome 路径、默认端口、Shopee 更新安全开关等 | — |
|
||
|
||
任务的**阶段状态**贯穿各 Tab：`imported → collected → generated → applied`（或 `failed/skipped`）。② 不设逐条人工确认阶段；③ 无常驻提交开关，但点击「开始更新」后必须先通过 ⑤ 的 Shopee 更新安全开关，再弹窗确认当前筛选范围和任务数量。各 Tab 聚焦各自阶段的列与按钮，但操作同一批任务（同一 batch）。
|
||
|
||
## 全局 Tab 栏可用性
|
||
|
||
5 个主 Tab 是高频导航入口，不能使用 Qt 默认的紧凑宽度。`MainWindow` 必须为 `QTabWidget/QTabBar` 设置基础样式：
|
||
|
||
- 每个 Tab 设置稳定最小宽度和足够左右 padding，避免文字贴边或窄到误点。
|
||
- Tab 之间保留明显间距，当前 Tab 有清晰背景/边框高亮。
|
||
- 样式只影响顶层主 Tab，不改变各业务表格、弹窗和后续 Tab 内部布局。
|
||
- 新增业务 Tab 内容时不得缩小主 Tab 栏点击区域。
|
||
|
||
## 首次使用引导保护
|
||
|
||
- ① 导入采集 与 ③ 更新shopee 都依赖**账号已配置且已登录**（在 ④ 账号管理）。
|
||
- 当无账号 / 对应账号 Chrome 未启动 / 账号未登录时：相关执行按钮**禁用或在执行前汇总拦截**，并提示「请先到『账号管理』配置账号并登录」。
|
||
- 可以提供「打开账号管理」或「启动登录」入口辅助用户处理当前账号；不要无提示批量启动所有账号 Chrome，避免开错账号或启动过多浏览器进程。
|
||
- 老用户账号已就绪则无感。
|
||
|
||
## ① 导入采集
|
||
|
||
```
|
||
┌ 导入采集 ─────────────────────────────────────────────────────┐
|
||
│ [导入 Excel…] [移除] [清空] │
|
||
│ ▸ 3 文件 · 128 行 · 有效125/无效3 · 匹配123 · 未匹配5⚠ │ ← 导入汇总栏
|
||
│ 匹配明细：女装店60 · my主店40 · 饰品店23 │
|
||
│ ┌───────────────────────────────────────────────────────────┐ │
|
||
│ │ 账号名 别名 商品ID 阶段 旧标题 旧封面 │ │
|
||
│ │ 主店A 女装店 51100639510 待采集 — — │ │
|
||
│ └───────────────────────────────────────────────────────────┘ │
|
||
│ [▶ 采集旧标题/旧封面] [■停止] [回写旧数据到 Excel] │
|
||
│ 日志：逐条 文件→匹配账号、采集结果 │
|
||
└───────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
- 导入：openpyxl 解析**输入列**（账号名/别名/商品id）入 SQLite。
|
||
- **导入汇总栏**（导入后即时刷新，跑采集前的校验关口）：显示 文件数、解析行数（原始数据量）、有效/无效行、匹配账号行数（按账号细分）、未匹配行数。未匹配/无效数字标红可点，点击在列表筛出便于定位纠错。
|
||
- 采集：用该账号已启动并登录的 Chrome 只读打开商品页，读旧标题、下载旧封面到本地图片目录，写 `old_title/old_cover_path`，stage=collected。若程序为采集自动新建商品页 tab，采集结束后自动关闭；若复用用户原本打开的 tab，则不关闭。
|
||
- 回写：采集完成后自动把旧标题/旧封面路径批量回写原 Excel；保留「回写旧数据到 Excel」作为手动重试入口（原文件被锁→提示关闭后重试/另存）。
|
||
- 别名未匹配账号 / 账号未登录 → 该行 skipped 并记原因。
|
||
|
||
## ② AI生成
|
||
|
||
左右布局：左侧约 1/4 放提示词，右侧放筛选 + 任务列表。
|
||
|
||
```
|
||
┌ AI生成 ───────────────────────────────────────────────────────┐
|
||
│ ┌─左 ~1/4─┐ ┌──────────────── 右 3/4 ──────────────────────┐ │
|
||
│ │标题提示词│ │ 批次[本次▼] 店铺[全部▼] 状态[全部▼] [筛选] │ │
|
||
│ │[ ]│ │ ┌──────────────────────────────────────────┐ │ │
|
||
│ │[ ]│ │ │ 店铺名 商品id 旧标题 新标题 状态 │ │ │
|
||
│ │ │ │ │ 女装店 511..639 …T恤 …百搭 已生成 │ │ │
|
||
│ │封面提示词│ │ │ 女装店 511..640 … — 待生成 │ │ │
|
||
│ │[ ]│ │ └──────────────────────────────────────────┘ │ │
|
||
│ │[ ]│ │ （双击某行 → 弹窗看 旧封面 | 新封面） │ │
|
||
│ └──────────┘ └───────────────────────────────────────────────┘ │
|
||
│ 进度：标题30/30 · 封面12/30 · 失败1 [▶ 开始生成] [■停止] │
|
||
└───────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
- 左侧（提示词管理，上下两块）：
|
||
- **标题提示词**：多行输入 + 「保存」（写 `title_prompt.txt`）；启动时自动加载回显。
|
||
- **封面提示词**：模板下拉（读 `prompts/cover/*.txt`）+ 图标工具栏（新建/保存/另存为/重命名/删除）+ 多行输入 + 「插入标题」（插 `{新标题}`）/「预览」（变量替换后查看）。
|
||
- 变量：`{旧标题}`/`{新标题}`/`{商品id}`/`{店铺}`，生成前按任务替换。
|
||
- 右上：按导入批次 / 店铺 / 状态筛选任务。
|
||
- 右下：任务列表（店铺名、商品id、旧标题、新标题、状态）；**双击某条 → 弹窗展示旧封面 | 新封面**（纯查看）。
|
||
- 底部**单个「开始生成」+「停止」**：开始生成 = **先按 `title_concurrency` 并发生成标题，接着按 `image_concurrency` 并发生成封面**；进度实时显示 标题/封面/失败 计数。
|
||
- 生成参数（标题/图片并发数、失败重试、分辨率、jpg 质量、模型/Key）在 **⑤ 设置**，不在本 Tab 重复。
|
||
- 每条/每张完成即写库；「停止」取消未开始项，可再次「开始生成」对剩余继续。
|
||
- **无逐条人工审核环节**；新标题直接用 AI 输出（不可编辑）；可选对单行 `重生成`。生成完即可进入 ③，③ 开始更新前会做批量确认。
|
||
|
||
## ③ 更新shopee
|
||
|
||
```
|
||
┌ 更新shopee ───────────────────────────────────────────────────┐
|
||
│ 批次[本次▼] 店铺[全部▼] 状态[已生成▼] [筛选] │
|
||
│ ⚠ 点击「开始更新」后先过安全开关，再确认【当前筛选结果】并提交 │
|
||
│ ┌───────────────────────────────────────────────────────────┐ │
|
||
│ │ 店铺 商品ID 新标题 新封面 阶段 结果 │ │
|
||
│ └───────────────────────────────────────────────────────────┘ │
|
||
│ [▶ 开始更新] [■停止] [回写结果到 Excel] │
|
||
└───────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
- 顶部**按批次 / 店铺 / 状态筛选**（与 ①②一致）；「开始更新」作用于**当前筛选结果**，是一道范围控制。
|
||
- 店铺筛选：建议**逐店铺更新**（每店铺需先启动其 Chrome 并登录）。
|
||
- 状态筛选：`已生成` 只跑未更新的；`失败` 用于**失败重试**；`已更新成功/略过` 仅查看。
|
||
- 点击「开始更新」先读取 ⑤ `shopee_update` 安全设置：未允许真实提交、超过单次最大条数、包含非测试商品 ID、或包含新封面但未允许封面更新时，直接弹警告并阻断。
|
||
- 安全开关通过后，弹窗展示本次筛选条件、任务数量、安全设置和“将提交线上”的风险提示；用户点「是/确认」才开始，点「否/取消」不执行。
|
||
- 对确认后的**已生成（generated）任务**执行：打开编辑页换标题+换封面 → 点「更新」提交。
|
||
- 满 9 张封面时，删除第一张前必须已有该任务的本地旧封面备份（①采集得到的 `old_cover_path` 且文件存在）；备份缺失时阻断该条更新并提示先采集/修复备份，不盲删线上图片。
|
||
- 串行、单条失败继续；每条立即写回 SQLite（committed/状态/error），失败不阻塞后续任务。
|
||
- 更新前做账号就绪预检：无账号、对应账号 Chrome 未启动或未登录时整体阻断并引导去④账号管理，不进入逐条提交。
|
||
- 若 ⑤ 开启“成功后关闭本次新开编辑页”，则仅关闭本轮程序自动新开且成功提交的商品页；失败任务和用户原本打开的 tab 不关闭。
|
||
- 更新完成后自动回写原 Excel：写入新标题、新封面图片路径、更新状态；原文件被锁时提示关闭后点击「回写结果到 Excel」手动重试。
|
||
- 自动回写完成后弹窗汇总成功/失败/略过数量与 Excel 回写文件/行数。
|
||
|
||
## ④ 账号管理
|
||
|
||
```
|
||
┌ 账号管理 ─────────────────────────────────────────────────────┐
|
||
│ 账号名 别名 地区 端口 登录状态 备注 │
|
||
│ 主店A 女装店 seller.shopee.tw 9222 ●已登录 │
|
||
│ [＋新增][✎编辑][🗑删除] [▶启动并登录][🔄检测登录][⧉快捷方式] │
|
||
└───────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
账号弹窗字段：账号名、别名（唯一，Excel 用它匹配）、地区域名、调试端口、密码（本地明文仅参考，保存/变更时提示，UI 打码，不自动登录）、备注；配置目录按别名生成 slug 只读显示。
|
||
|
||
## ⑤ 设置
|
||
|
||
- AI 模型管理（T-501 已接入）：左侧模型下拉 + 新增/删除，右侧详情编辑。
|
||
- 字段：启用、服务商名、类别（文本/图像）、api_type、模型ID、网址、密钥、连接超时。
|
||
- 密钥存在 `config/ai_models.json`，本地明文保存；保存/变更时提示；UI 使用密码框打码显示，不进入日志/导出。
|
||
- 保存复用 `appconfig` 模型清单后端，保持 name 唯一、至少 text/image 各一个模型。
|
||
- 「测试连接」通过后台 worker 调 `appconfig.test_ai_model()`，不阻塞主线程。
|
||
- AI 生成参数（T-501b 已接入）：标题/图片模型角色下拉、标题并发数、图片并发数、失败重试次数、分辨率、jpg 质量。
|
||
- 标题模型下拉只列 text 类模型；图片模型下拉只列 image 类模型。
|
||
- 分辨率为 `512 / 1k / 2k / 4k`；返回超时只读展示 `resolution_timeouts[resolution]`，不单独编辑。
|
||
- 保存写入 `config.json` 的 `ai` 段，供 ② AI生成复用。
|
||
- 路径与端口（T-501b 已接入）：本地图片目录、Chrome 路径、账号数据根目录、DB 路径、默认调试端口、端口范围、CDP 就绪超时。
|
||
- Shopee 更新安全（T-501c 已接入）：测试商品 ID、允许真实提交、允许更新封面、单次最大更新条数、成功后关闭本次新开编辑页。
|
||
- 默认关闭真实提交和封面更新，单次最大更新条数默认 1。
|
||
- ③ 点击「开始更新」会读取这些设置，先拦截不符合条件的更新，再弹确认框。
|
||
|
||
## 流程导航
|
||
|
||
```text
|
||
④ 账号管理：配账号 + 启动登录（首次必做）
|
||
│
|
||
① 导入采集：导入 Excel → 采集旧标题/旧封面 → 自动回写旧字段（失败可手动重试）
|
||
│
|
||
② AI生成：提示词 → 生成新标题/新封面（无逐条审核）
|
||
│
|
||
⑤ 设置：开启测试商品范围内的 Shopee 更新安全开关
|
||
│
|
||
③ 更新shopee：对已生成任务点击开始更新 → 安全开关检查 → 弹窗确认 → 换标题/允许时换封面 → 点「更新」提交 → 回写结果 → 弹窗汇总
|
||
```
|
||
|
||
- 未配账号 / Chrome 未启动 / 未登录：① ③ 的执行按钮禁用或执行前提示去 ④。
|
||
- 已生成的任务即可进 ③；③ 通过 ⑤ 安全开关并经用户确认批量弹窗后提交线上，无常驻提交开关。
|
||
- 任意步骤失败：记入该任务、日志标明，不影响其他任务。
|
||
|
||
## 组件建议（PySide6）
|
||
|
||
| 组件 | 归属 | 说明 |
|
||
| --- | --- | --- |
|
||
| `MainWindow(QMainWindow)` | 根窗口 | 持有 `QTabWidget`、状态栏、全局消息 |
|
||
| `CollectTab(QWidget)` | ① | 导入、任务表、采集、回写 |
|
||
| `GenerateTab(QWidget)` | ② | 左提示词管理 + 右筛选/任务列表；双击看新旧封面；开始生成/停止/进度已接入 `GenerateWorker` |
|
||
| `ApplyTab(QWidget)` | ③ | 已生成任务筛选 + Shopee 更新安全拦截 + 开始更新确认 + 确认后串行更新 + 结果回写与结束汇总 |
|
||
| `AccountsTab(QWidget)` | ④ | 账号增删改、启动登录、检测登录、生成快捷方式 |
|
||
| `SettingsTab(QWidget)` | ⑤ | AI 模型 master-detail 管理 + 角色/生成参数/路径/端口配置 + Shopee 更新安全 |
|
||
| `TaskTableModel(QAbstractTableModel)` | ①②③ | 任务表格数据模型，供 `QTableView` 使用 |
|
||
| `BaseWorker(QObject)` | 后台 | 定义 `progress/log/row_updated/failed/finished/cancelled` signals |
|
||
| `ApplyWorker(BaseWorker)` | ③ | 账号就绪预检、串行调用 `editor.apply_task(..., close_success_tab=...)`、逐条 `set_applied()`，失败继续 |
|
||
| `AIModelTestWorker(BaseWorker)` | ⑤ | 后台调用 `appconfig.test_ai_model()` 测试模型连接 |
|
||
| `WriteBackWorker(BaseWorker)` | ①③ | ①回写旧字段；③回写新标题/新封面/更新状态 |
|
||
|
||
> 采集、生成、更新都是耗时操作，使用 `QObject` worker + `QThread`。Worker 不直接操作 QWidget，只通过 signal 通知主线程刷新 UI。
|