docs: refine gui color optimization plan

2026-07-01 17:19:35 +08:00
parent f80f00b5a2
commit ca41ed2874
4 changed files with 205 additions and 0 deletions
@@ -94,6 +94,13 @@
 | T-508 | ③ 更新shopee生产化操作区 | T-401, T-404a, T-506 | 「开始更新」作为主操作视觉强化；「重置更新状态」从底部按钮移到任务表右键菜单/高级入口，与批量更新物理分离，运行中禁用；更新安全拦截弹窗写明具体开关并提供「前往设置」深链到⑤，不改 Shopee/CDP 更新流程 | DONE |
 | T-509 | ② 新标题人工微调 | T-303, T-401 | ②任务表「新标题」列可编辑；仅允许已生成、未提交线上、非运行中任务；编辑写回 `tasks.new_title`，保留 `stage=generated`，清空 `last_error`，状态回到可更新；不触碰 Shopee/CDP/Excel，③ 使用修改后的标题 | DONE |
 | T-510 | ③ 检查本轮更新文案统一 | T-506, T-508 | 将用户可见「预览本轮更新」统一改为「检查本轮更新」，按钮、确认框、状态栏、完成弹窗、运行日志和文档一致；保留内部 `dry_run` 字段与执行语义，不改 Shopee/CDP 更新流程 | DONE |
 | T-511 | 语义色板 + ①②③任务状态列上色 | T-202, T-303, T-401 | 依据 `docs/ui-color-design.md`。在 `app/gui.py` 顶部定义统一语义色板常量（success `#1a7f37`/danger `#cf222e`/info `#0969da`/pending `#9a6700`/muted `#6e7781`/warning `#bc4c00`），全局引用不散落硬编码。①②③ 三个 TableModel 在 `Qt.ForegroundRole` 按内部 `stage/status` 返回 `QColor`，不要按中文显示文案硬匹配：完成态=success、失败=danger、略过/取消=muted、待处理=pending、进行中=info；不给普通行刷底色（失败行浅底 `#ffebe9` 可选、仅此一种）。保持文字+颜色双编码，不只靠颜色。跑 `test_gui.py` 无回归 | TODO |
 | T-512 | ③高风险按钮上色 + ①导入校验数字标红 | T-511, T-508, T-202b | ③「开始更新」（写线上）改用 warning `#bc4c00` 系强调（描边或填充；第一版不强制图标，避免 Windows/Qt 字体渲染不稳），与②安全流程 info 蓝主操作区分；「停止」保持中性。①导入汇总栏：未匹配数 >0 时用 danger 且保持现有按钮可点击筛出，=0 保持中性；无效行数 >0 时只标红提示，不承诺在任务表筛出，因为脏行未入库，后续若要点击查看需另做「导入错误明细」。颜色取自 T-511 色板常量 | TODO |
 | T-513 | 登录点 / ③Tab危险标识 / 破坏性按钮上色 | T-511, T-105, T-206 | ④登录状态 `●` 已登录=success、未登录/未检测=danger 或 muted（保留文字）；③ 更新shopee Tab 若做危险标识，不依赖 QSS 硬选第 3 个 Tab，优先用 `QTabWidget.setTabIcon(2, ...)` 设置克制 warning 小圆点图标，或第一版先跳过 Tab 标识；不整条刷红。破坏性按钮「删除批次」「删除账号」文字/描边用 danger，与普通灰按钮区分（二次确认弹窗仍是主防线）。颜色取自 T-511 色板常量 | TODO |
 | T-514 | ①②③ 首次空状态引导卡片 | T-205 | 依据 `docs/ux-review.md` P1。①②③ 在「无账号/未登录」时用显式空状态引导卡片替代灰按钮，例如「第一步：前往『④账号管理』配置并登录账号 →」并带跳转按钮；账号就绪后卡片消失，老用户无感。仅 UI 引导，不改采集/生成/更新流程与既有预检拦截逻辑 | TODO |
 | T-515 | 批次阶段进度总览 | T-206, T-401 | 依据 `docs/ux-review.md` P1。加轻量批次进度总览：按选中批次聚合各阶段计数（导入/已采集/已生成/已更新/失败/略过），落点可选①顶部进度条或独立概览区。数据由现有 `db.list_tasks(batch_id=...)` 按 `stage/status` 聚合，不新增表；已软删除批次不计入 | TODO |
 | T-516 | ①筛选对齐②③ | T-202, T-303b | 依据 `docs/ux-review.md` P2。① 导入采集补齐与②③一致的店铺/商品ID/状态筛选（至少店铺），保持三个列表页筛选心智一致；不改导入汇总栏与未匹配筛出逻辑，只扩展筛选维度 | TODO |
 | T-517 | ⑤设置分区 + 清理兼容字段 | T-506, T-507 | 依据 `docs/ux-review.md` P2。⑤ 视觉分区：高频「Shopee 更新安全/执行模式」与低频「基础设施（Chrome路径/端口/DB路径）」分块；彻底隐藏或清理残留的 `test_item_id`、`dry_run` 用户入口（保留内部兼容字段与语义），减少设置页过载与 UI 技术债 | TODO |
 ## 里程碑
@@ -109,3 +116,5 @@
 - 上传弹裁剪框商品的自动裁剪。
 - 账号登录态健康巡检。
 - AI 生成图的合规/质量自检。
 - ② 左栏提示词区组件密度优化：封面模板低频动作（另存为/重命名/删除）折叠进图标菜单或评估移入⑤（`docs/ux-review.md` P2）。
 - 界面深色主题：为 `docs/ui-color-design.md` 语义色板另出深色等义映射（当前只服务浅色）。
@@ -22,6 +22,8 @@ cmshopee 是一个给**电商运营**使用的 Windows PySide6 桌面自动化
 - [界面与流程结构](routes.md)：GUI 窗口、操作流程、按钮职责（无前端路由，用 GUI 流程替代）。
 - [当前实现状态](current-state.md)：当前代码现实、可运行命令、下一步可做任务。
 - [常见问题排查](troubleshooting.md)：本地配置、启动报错、敏感文件修复等排障记录。
 - [产品与 UI 评估](ux-review.md)：以 PM + UI 设计视角评估 5 Tab 模块 / 组件合理性，含优化方案与优先级清单。
 - [界面配色设计](ui-color-design.md)：语义色板与组件配色映射规范，指导给状态 / 按钮 / 校验 / 登录状态上色。
 ## 任务 / 进度 / 当前状态
@@ -0,0 +1,92 @@
 # 界面配色设计（语义色规范）
 > 立场：以 UI 设计师视角，为当前灰白 GUI 定义一套**语义色**规范。核心原则是"颜色编码含义、加速判断、降低误操作"，不是装饰。
 > 基线：`app/gui.py` 现状——除顶部 Tab 栏（`TAB_STYLE`，GitHub 风浅灰/悬停浅蓝）外，任务状态、校验数字、登录状态、动作按钮均为 Qt 默认灰白。
 > 性质：设计规范，不改代码。落地时按文末"实现映射"接入，遵守 `docs/05-coding-rules.md` 验证清单。
 ## 为什么上色（用户视角）
 本工具是**带风险分级的流水线**（①②只读/安全 → ③写 Shopee 线上，高风险）。纯灰白本身不是缺点：中性界面对长时间操作不易疲劳、显得专业。所以目标不是"变好看"，而是让**承载判断的关键信息**用颜色加速识别、并对高风险动作形成潜意识提醒。
 **反面**：给大面积表格/面板刷底色、堆品牌色、加渐变，会让密集工具界面变吵、变"玩具感"，是负分。因此本规范只给"承载含义的元素"上色。
 ## 三条纪律（决定成败）
 1. **背景保持中性**：只给状态文字、关键按钮、指示点上色；不给表格行/面板大面积刷底色（失败行可用极浅底色，见下）。
 2. **不能只靠颜色**：色盲用户约 8%。状态必须"颜色 + 文字/图标"双编码——现有状态已有中文文字（达标）；③ 高风险按钮第一版不强制图标，避免 Windows/Qt 字体渲染不稳。
 3. **一套色板全局复用 + 对比度达标**：绿/红/琥珀/蓝各定唯一值，禁止每处手写不同的红；文字色对白底满足 WCAG AA（对比度 ≥ 4.5）。
 ## 语义色板（浅色主题）
 | 语义 | 名称 | 十六进制 | 用途 | 白底对比 |
 | --- | --- | --- | --- | --- |
 | 成功 | success | `#1a7f37` | 已更新成功、已登录 | AA ✓ |
 | 失败 | danger | `#cf222e` | 失败状态、校验错误数、破坏性按钮文字 | AA ✓ |
 | 进行中 | info | `#0969da` | 采集中/生成中/更新中、安全主操作按钮 | AA ✓ |
 | 待处理 | pending | `#9a6700` | 待采集/待生成/待更新 | AA ✓ |
 | 略过/禁用 | muted | `#6e7781` | 略过、禁用态、次级文字 | AA ✓ |
 | 危险动作强调 | warning | `#bc4c00` | ③ 写线上的高风险按钮 | AA ✓ |
 | 极浅失败底 | danger-bg | `#ffebe9` | 失败行可选浅底（谨慎用） | 底色 |
 > 若将来做深色主题，另出一套等义映射；本规范先服务当前浅色。
 ## 组件配色映射（按价值排序）
 ### 1）任务状态列（①②③表格核心）— 最高 ROI
 `TaskTableModel` / `GenerateTaskTableModel` / `ApplyTaskTableModel` 的状态/阶段列，按值上前景色：
 | 显示 | 语义色 |
 | --- | --- |
 | 已采集 / 已生成 / 已更新成功 | success `#1a7f37` |
 | 失败 | danger `#cf222e` |
 | 略过 | muted `#6e7781` |
 | 待采集 / 待生成 | pending `#9a6700` |
 | 采集中 / 生成中 / 更新中（如有进行态） | info `#0969da` |
 - 收益：扫上百行时一眼分辨成功/失败/待办，是全项目颜色投入产出比最高处。
 - 可选：失败行整行加 `danger-bg #ffebe9` 极浅底，但仅失败一种、不叠加其他行底色，避免花。
 ### 2）③ 高风险动作按钮
 - `开始更新`（写 Shopee 线上，`objectName=startUpdateButton`，现仅粗体）：改用 **warning `#bc4c00`** 系（暖色描边或填充；图标可后置评估），与②安全流程的 info 蓝主操作明确区分。目的是每次点它都有"这一步动线上"的潜意识提醒。
 - `停止`：保持中性或 muted，不与主操作抢视觉。
 ### 3）校验数字（①导入汇总栏）
 - 未匹配数 **> 0** 时用 danger `#cf222e`，并保持当前「未匹配(n)」按钮可点击筛出；= 0 时保持中性。
 - 无效行数 **> 0** 时同样用 danger 标红提示，但第一版不承诺在任务表筛出，因为脏行不会入库；若要点击查看，需要后续新增「导入错误明细」。匹配数可用 success 或保持中性。
 ### 4）登录状态点（④账号管理）
 - `● 已登录` = success `#1a7f37`；`● 未登录 / 未检测` = muted `#6e7781` 或 danger（未登录用 danger 更醒目）。文字保留，圆点只是加速扫读。
 ### 5）③ Tab 危险区标识（克制）
 - 给 ③ 更新shopee 加一个**克制**的暖色标识时，不依赖 QSS 硬选第 3 个 Tab。普通 `QTabBar` stylesheet 没有稳定的 nth-tab 选择器；优先用 `QTabWidget.setTabIcon(2, ...)` 设置 warning 小圆点图标，或第一版先跳过 Tab 标识。目的：让用户始终知道自己在"碰线上"的那个 Tab。切忌整条 Tab 刷红。
 ### 6）破坏性按钮（低优先）
 - `删除批次`（①）、`删除账号`（④）等不可逆动作：按钮文字或描边用 danger `#cf222e`，与普通灰按钮区分。二次确认弹窗仍是主防线，颜色只是二级提示。
 ## 实现映射（PySide6，落地时参考）
 - **状态色**：在各 TableModel 的 `data()` 里响应 `Qt.ForegroundRole`（必要时 `Qt.BackgroundRole`）按内部 `stage/status` 返回 `QColor`；不要按中文显示文案硬匹配，不要在 QSS 里做，表格单元格上色走 model role 最稳。
 - **按钮/汇总数字**：用 `objectName` + 集中 QSS。建议把语义色板定义为 `app/gui.py` 顶部的一组常量（如 `COLOR_SUCCESS = "#1a7f37"`），QSS 与 `QColor` 都引用同一常量，杜绝散落硬编码。③ Tab 单独标识如需落地，用 `setTabIcon(2, ...)`，不要试图用 QSS nth 选择器。
 - **登录点**：文字前缀 `●` 用 `QColor`，或状态列走 ForegroundRole。
 - **复用**：所有红/绿/蓝/琥珀只从色板常量取值，新增组件一律引用，不新造颜色。
 ## 非目标（明确不做）
 - 不做整体换肤 / 品牌主题 / 渐变 / 大面积彩色背景。
 - 不给普通只读表格行刷底色（失败行浅底是唯一例外且可选）。
 - 不改变顶部 Tab 栏既有的防误点尺寸与灰白基调；③ 风险标识必须克制，且可在第一版跳过。
 - 不引入第三方 QSS 主题库；用现有 `TAB_STYLE` + objectName + model role 即可。
 ## 落地建议顺序
 1. 状态列上色（映射 1）——收益最高、风险最低，建议先做。
 2. ③ 高风险按钮 + 校验数字标红（映射 2、3）——直接服务防误操作与导入纠错；无效行第一版只标红，不做筛表。
 3. 登录点、③ Tab 标识、破坏性按钮（映射 4、5、6）——体验打磨。
 > 每步落任务时补现状/方案/验收，并跑 `python -m unittest discover -s tests`（GUI 逻辑测试）确认无回归。
@@ -0,0 +1,102 @@
 # 产品与 UI 评估（模块 / 组件合理性）
 > 立场：以**产品经理（工作流 / 业务逻辑）+ UI 设计师（布局 / 组件 / 信息层级）**双视角，评估当前 5 Tab GUI 的所有模块与组件是否合理，并给出优化方案。
 > 基线：`docs/routes.md` 界面结构 + `docs/current-state.md` 当前实现快照（2026-07-01）。
 > 性质：评估与建议，不改代码。落地项见文末优先级清单，可转 `docs/06-tasks.md` 正式任务。
 ## 当前状态说明（2026-07-01）
 本文保留当时的产品/UI评估原文，但部分 P0 项已在后续任务中落地：T-509 已支持②「新标题」列本地微调；T-508 已把③「重置更新状态」移到任务表右键菜单，并强化「开始更新」主操作；T-510 已把用户可见「预览本轮更新」统一为「检查本轮更新」。继续落地时，不要把这些历史问题重复建任务；当前剩余可执行项以 `docs/06-tasks.md` 的 T-511 及之后任务为准。
 ## 总判断
 整体架构成熟、克制、内部一致：5 Tab 流水线映射 `imported → collected → generated → applied` 四阶段；worker/QThread、`run_logs` 运行日志、Excel 回写重试、安全二次确认在各 Tab 高度统一；安全红线（③二次确认、`committed` 提示、批次软删除）落得扎实。**定位是"给熟练运营重复使用"的桌面工具，作为日常工具是合理的。**
 问题不在 bug，而在设计取舍留下的**体验债**——集中在下面 4 个结构性问题与若干 Tab 级问题。
 ---
 ## 一、信息架构层（最高优先）
 ### 1. Tab 顺序与真实依赖顺序矛盾——首次用户逆流
 Tab 排列 `①采集 → ②生成 → ③更新 → ④账号 → ⑤设置`（工作流优先），但流程导航第一步是"④账号管理（首次必做）"，③之前还要"⑤设置配置安全开关"。**前置条件被放在最后两个 Tab。**
 - 熟练用户：账号早配好，高频①②③在前 → 正确。
 - 首次用户：①点采集被拦、③点更新被拦，需反向跳④⑤ → 逆流。
 取舍可接受，但代价是首次引导必须极强。现状是被动拦截（按钮禁用 + 执行前提示去④）。
 **优化方案**：①②③在"无账号 / 未登录"时，用**显式空状态引导卡片**替代灰按钮，例如「第一步：前往『④账号管理』配置并登录账号 →」并带跳转按钮；账号就绪后卡片消失，老用户无感。
 ### 2. ③ 的安全开关藏在 ⑤，是隐性耦合
 "允许真实提交""允许更新封面"是 ③ 能否工作的闸门，却住在 ⑤。为安全（不易误触）这样分是对的，但**发现性差**：首次真实更新被拦截时，用户未必知道去⑤开哪个开关。
 **优化方案**：③ 的安全拦截弹窗**写明被哪个具体开关拦下**（如"未允许真实提交"），并提供「前往设置」深链按钮直接跳到 ⑤ 对应分区。
 ### 3. 缺批次级总览——多批次场景盲区
 现在每个 Tab 各自按批次筛选看自己的列表，**没有任何地方一眼看到"批次X：导入5 / 已采集5 / 已生成3 / 已更新0"**。软删除上线后批次持续累积，运营管理多批次只能在①②③间来回数数。这是随规模暴露的缺口。
 **优化方案**：加一个轻量**批次进度总览**（各阶段计数）。落点可选：①顶部按选中批次显示阶段进度条，或独立"概览"区/弹窗。数据可由 `db.list_tasks(batch_id=...)` 按 `stage/status` 聚合，无需新表。
 ---
 ## 二、逐 Tab 评估
 ### ① 导入采集
 - **PM**：导入汇总栏（文件/行/有效/匹配/未匹配可点筛）是亮点，把校验关口前置，专业。
 - **UI**：筛选弱于②③——只有"批次 + 全部/未匹配"，缺"店铺/商品ID/状态"四联筛，量大时难定位单店铺，与②③不一致。
 - **优化**：① 对齐②③的店铺/商品ID/状态筛选（至少店铺筛选），保持三个列表页筛选心智一致。
 ### ② AI生成
 - **PM（历史问题，已由 T-509 解决）**：原评估时新标题不可编辑、只能重生成/重置；当前②已支持本地微调 `new_title`，继续保留该能力。
  - **当前处理**：该项已由 T-509 落地，后续不要重复建“标题编辑”任务；只在回归测试中确认编辑后进入③仍走同样确认。
 - **UI**：左侧 1/4 窄列塞了标题提示词 + 封面模板（下拉 + 新建/保存/另存为/重命名/删除 6 按钮）+ 插入/预览，密度过高。
  - **优化**：封面模板的低频管理动作（另存为/重命名/删除）收进图标菜单或右键；或评估把模板管理移入⑤，左栏只留"选模板 + 编辑 + 预览"。
 ### ③ 更新shopee
 - **PM**：逻辑最重也最严谨——预览→安全开关→确认→就绪预检→分批→回写→汇总，闭环完整，风险控制到位，保留。
 - **UI（历史问题，已由 T-508/T-510 解决）**：原评估时按钮行 `[预览][开始更新][停止][重置更新状态][回写Excel]` 5 连排；当前「检查本轮更新」文案已统一，`重置更新状态` 已移到任务表右键菜单，后续只需继续做语义色和风险视觉强化。
  - **当前处理**：重置入口与文案统一已由 T-508/T-510 落地；剩余只做 `开始更新` 的风险视觉强化、`回写Excel` 次级化等 T-512/T-513 范围内的颜色/层级调整。
 ### ④ 账号管理
 - **PM**：密码本地明文"仅参考"、不自动登录、人工登录 + 程序检测——安全取舍正确且清醒。
 - **UI**：表格 + 按钮组清晰，●登录状态指示好，`检测登录`手动触发（不擅自开浏览器）对。基本无异议。
 ### ⑤ 设置
 - **PM**：内容过载，AI模型 master-detail + 角色参数 + 路径端口 + Shopee安全 + 执行模式 5 类混在一页。几乎不改的基础设施（Chrome路径/端口/DB路径）和高频安全开关（允许提交）混排。
 - **UI**：已在做 3 列响应式优化，方向对；但残留 `test_item_id`、`dry_run` 兼容字段是 UI 技术债。
  - **优化**：视觉分区——"每次可能要动的"安全开关/执行模式一组，"装完不碰的"基础设施一组；清理或彻底隐藏 `test_item_id`/`dry_run` 兼容入口。
 ---
 ## 三、跨切面问题
 - **"重置"系列（②③）是开发联调工具（T-404a 明说"联调重试辅助"）泄漏进生产 UI**。对非技术运营，"退回 collected/generated"语义会困惑。
  - **优化**：先明确它服务谁。若面向运营，改文案为"退回重做"并收进右键/高级区；若纯开发用，考虑加开关默认隐藏。
 - **一致性做得好（保留）**：worker 模式、`run_logs` 全 Tab 统一、①③回写重试按钮对称、批次为统一枢轴。
 - **容器选型合理（保留）**：线性流水线用 Tab 而非 Wizard 是对的——熟练用户要能任意跳转、重跑单阶段，Tab 支持这点。
 ---
 ## 四、优先级清单（可转 `docs/06-tasks.md`）
 | 优先级 | 问题 | 建议动作 | 涉及 |
 | --- | --- | --- | --- |
 | **已落地** | ②新标题不可编辑直推线上 | T-509 已开放行内编辑 `new_title` | `app/gui.py` ②、`app/db.py` |
 | **已部分落地** | ③按钮行主次不分、重置误触 | T-508 已将单行"重置"移行右键菜单；视觉强化继续由 T-512/T-513 承接 | `app/gui.py` ③ |
 | **P1** | 首次用户逆流撞墙 | ①②③无账号时做显式空状态引导卡片，替代灰按钮 | `app/gui.py` ①②③ |
 | **P1** | ③安全开关藏⑤、发现性差 | ③拦截弹窗写明具体开关 + "去设置"深链 | `app/gui.py` ③⑤ |
 | **P1** | 缺批次级总览 | 加批次阶段计数总览（聚合现有 `list_tasks`） | `app/gui.py`、`app/db.py` |
 | **P2** | ⑤设置过载 + 兼容字段技术债 | 安全开关 vs 基础设施分区；清理隐藏兼容字段 | `app/gui.py` ⑤ |
 | **P2** | ①筛选弱于②③ | ①对齐"店铺/商品ID/状态"筛选 | `app/gui.py` ① |
 | **P2** | ②左栏组件密度过高 | 封面模板低频动作折叠 / 评估移⑤ | `app/gui.py` ② |
 > 落地顺序建议：P0 中已落地项只做回归；剩余事项以 `docs/06-tasks.md` 的 T-511 及之后任务为准，按防误操作/首次可用性/体验打磨的收益排序推进。每条落任务时补现状/方案/验收要点，并遵守 `docs/05-coding-rules.md` 验证清单。