# 跨平台商品聚合与 AI 分析 UI 设计文档

- 文档状态：Draft
- 版本：v0.2
- 更新时间：2026-04-02
- 依据文档：
  - `docs/PRD.md`
  - `docs/FeatureSummary.md`
  - `docs/DevelopmentPlan.md`

## 1. 文档目标

本文件用于把 `PRD`、`FeatureSummary` 和 `DevelopmentPlan` 中已经明确的产品边界、状态模型和研发形态，收敛为可执行的 Web 前端 UI 设计基线。

### 1.1 本文回答什么

| 主题 | 需要回答的问题 | 输出形式 |
| --- | --- | --- |
| 信息架构 | MVP 工作台如何承载完整任务闭环 | 页面结构、导航、流程图 |
| 状态表达 | 各类任务状态、平台状态、报告状态如何区分 | 状态表、状态流图 |
| 视觉风格 | 如何避免落成普通后台表格页 | 视觉原则、Token、线框 |
| 前端落地 | 页面模块、共享组件、接口契约如何协同 | 模块表、组件表、验收表 |

### 1.2 文档速览

| 项目 | 结论 |
| --- | --- |
| 产品形态 | 统一 Web 工作台，不做本机采集分支 |
| 核心闭环 | 新建任务 -> 候选确认 -> 任务执行 -> 报告阅读 -> 历史回看 |
| 关键设计目标 | 可发起、可判断、可恢复、可追溯 |
| UI 基调 | 研究台、证据板、暖色工作台、克制但有判断力 |
| P0 关键页面 | 新建、确认、执行、报告、历史、会话准备/恢复 |
| 关键风险处理 | 平台阻塞不等于整单失败，优先支持部分成功产出 |

### 1.3 任务闭环总览

```mermaid
flowchart LR
    A[新建任务] --> B[多平台搜索]
    B --> C[候选确认]
    C -->|有确认链接| D[抓取与分析]
    C -->|零确认收口| X[NoSelection 终态]
    D --> E[报告发布]
    D --> F[阻塞恢复]
    F --> D
    E --> G[报告阅读与证据下钻]
    G --> H[历史回看 / 版本切换 / 平台级重试]
```

对应 ASCII 视图：

```text
+------------+     +------------+     +------------+     +------------+
| 新建任务   | --> | 候选确认   | --> | 任务执行   | --> | 报告阅读   |
+------------+     +------------+     +------------+     +------------+
                         |                   |
                         |                   v
                         |              +------------+
                         +------------> | 阻塞恢复   |
                                        +------------+
                         |
                         v
                    +------------+
                    | NoSelection|
                    +------------+
```

## 2. 设计输入与前置假设

### 2.1 业务基线

产品本质不是“抓取工具集合”，而是一个围绕商品分析任务组织输入、确认、执行和报告输出的工作台。

MVP 的核心目标与 `PRD` 保持一致：

| 目标 | 说明 |
| --- | --- |
| 一次任务发起 | 替代多平台反复手工搜索 |
| 系统召回 + 人工确认 | 保证分析对象正确性 |
| 标准化数据 + 结构化 AI 报告 | 降低整理与判断成本 |
| 部分成功可产出 | 不把所有异常都视为整单失败 |

### 2.2 交付形态对齐

当前上游文档已统一为“Web 工作台 + 后端统一采集执行 + 服务端远程受控浏览器处理会话”的形态。

| 项目 | 基线 |
| --- | --- |
| 执行位置 | 服务端统一执行 |
| 用户入口 | 统一 Web 工作台 |
| 会话处理 | 服务端远程受控浏览器 |
| 页面文案口径 | 使用“系统”“工作台”“当前任务”等中性表达 |
| 会话页面复用 | 任务前准备与任务中恢复共用一套页面模式 |

### 2.3 设计范围

#### P0 范围

| 范围 | 内容 |
| --- | --- |
| 页面 | 新建任务、候选确认、任务执行、报告、历史任务、会话准备/恢复 |
| 系统能力 | 视觉系统、状态系统、共享组件、响应式、可访问性 |
| 协同要求 | 与任务状态、平台状态、报告快照、会话恢复流程对齐 |

#### 非本文件范围

| 非范围项 | 说明 |
| --- | --- |
| 品牌官网式首页 | 不在 MVP 范围 |
| PDF/Markdown 导出视觉稿 | 本文不展开 |
| 多租户权限中心 | 不纳入 P0 |
| 高级 BI 大屏 | 不纳入 P0 |

## 3. 总体体验目标

### 3.1 四个体验问题

| 问题 | UI 需要解决什么 |
| --- | --- |
| 发起问题 | 用户能否快速开始，而不是被表单噪音淹没 |
| 判断问题 | 用户能否确认目标商品，而不是机械点按钮 |
| 过程问题 | 用户能否知道系统现在在做什么、卡在哪、下一步怎么做 |
| 结果问题 | 用户能否先得到结论，再下钻到证据 |

### 3.2 设计原则

| 原则 | 解释 |
| --- | --- |
| 任务优先于页面 | 页面只是同一任务在不同阶段的视图 |
| 证据优先于修辞 | 结论、建议、风险都要能回到证据索引 |
| 正确性优先于自动化感 | 确认页帮助判断，不制造“系统全懂了”的错觉 |
| 部分成功优先于全局失败 | 单个平台失败时，其余平台结果仍可阅读 |
| 状态必须可解释 | `Blocked`、`NoResult`、`NoSelection` 等必须明确区分 |
| 复杂信息分层展开 | 顶层摘要，细节通过抽屉、折叠、版本切换进入 |

### 3.3 视觉关键词

| 关键词 | 含义 |
| --- | --- |
| `研究台` | 像分析师的工作台，而不是通用 SaaS 后台 |
| `证据板` | 结论旁边始终有证据入口 |
| `暖色工作台` | 避免大面积冷白，增强阅读与停留感 |
| `克制但有判断力` | 状态色明确，但不过度装饰 |

## 4. 信息架构与导航

### 4.1 页面结构总表

| 页面 | 建议路由 | 核心问题 | 主操作 |
| --- | --- | --- | --- |
| 新建任务页 | `/tasks/new` | 我要分析什么，采样如何设置，哪些平台当前可能受限 | 创建任务 |
| 会话准备页 | `/sessions/:platform/prepare` | 在创建任务前如何完成某个平台的登录或会话预热 | 接管远程会话、返回原页面 |
| 候选确认页 | `/tasks/:taskId/confirm` | 哪些候选才是我要分析的对象 | 选择、跳过、提交确认 |
| 任务执行页 | `/tasks/:taskId/run` | 系统做到哪一步了，哪里被阻塞，是否需要我介入 | 查看进度、处理阻塞、重试平台 |
| 报告页 | `/tasks/:taskId/report` | 最终得出了什么结论，证据是什么 | 阅读、对比、切换版本、下钻证据 |
| 历史任务页 | `/history` | 过去做过哪些任务，哪些值得回看或继续处理 | 搜索、筛选、回看、删除、重试 |
| 阻塞恢复页 | `/tasks/:taskId/recovery/:platform` | 如何完成登录、验证码或风控处理并恢复任务 | 接管远程会话、完成恢复 |

### 4.2 全局工作台结构

MVP 采用“轻左侧导航 + 任务上下文头部 + 页面主体”的结构。

```text
+----------------------------------------------------------------------------------+
| 左侧导航                                                                         |
|  - 新建任务                                                                      |
|  - 历史任务                                                                      |
+----------------------+-----------------------------------------------------------+
| Task Context Header  | 任务名 / task_status / 更新时间 / 平台概览 / 主操作       |
+----------------------+-----------------------------------------------------------+
| Task Spine           | 输入 -> 确认 -> 执行 -> 报告                              |
+----------------------+-----------------------------------------------------------+
| 页面主体                                                                           |
|  - 新建页 / 确认页 / 执行页 / 报告页 / 历史页 / 会话页                           |
+----------------------------------------------------------------------------------+
```

### 4.3 导航原则

| 原则 | 说明 |
| --- | --- |
| 单任务主线 | 任务创建后，后续页面围绕同一个 `task_id` 组织 |
| 历史页即首页 | 不额外引入空洞 Dashboard |
| 执行与报告互通 | 两者是同一任务的不同视图，不应割裂 |
| 会话页为旁路流程 | 只被拉起，不进入主导航 |

### 4.4 导航流转图

```mermaid
flowchart TD
    A[/history 历史任务/] --> B[/tasks/:id/report 报告/]
    A --> C[/tasks/:id/run 执行/]
    D[/tasks/new 新建任务/] --> E[/tasks/:id/confirm 确认/]
    E --> C
    C --> B
    D --> F[/sessions/:platform/prepare 会话准备/]
    C --> G[/tasks/:id/recovery/:platform 阻塞恢复/]
    F --> D
    G --> C
```

## 5. 视觉系统

### 5.1 视觉基调

| 层次 | 设计要求 |
| --- | --- |
| 背景 | 有轻微纸面与桌面感，不是纯白办公后台 |
| 标题 | 有明显层级，突出任务对象与结果判断 |
| 状态 | 语义清晰，颜色服务于解释，不服务于装饰 |
| 报告 | 更像研究报告，不像长表格或运营后台 |

### 5.2 色彩系统

建议采用“暖底色 + 深墨文字 + 青铜系状态强调”的基线，并通过 CSS Variables 覆盖组件库 Token。

| Token | 建议值 | 用途 |
| --- | --- | --- |
| `--bg-canvas` | `#F2EEE6` | 全局背景，营造研究台底色 |
| `--bg-surface` | `#FBF8F2` | 普通卡片背景 |
| `--bg-elevated` | `#FFFFFF` | 浮层、抽屉、重要卡片 |
| `--text-primary` | `#1F2A30` | 主文字 |
| `--text-secondary` | `#5B6971` | 次级说明 |
| `--line-subtle` | `#D7D0C4` | 分隔线 |
| `--brand-primary` | `#146C6E` | 主按钮、焦点、关键链接 |
| `--brand-primary-soft` | `#D9EFEB` | 主品牌浅底 |
| `--accent-amber` | `#8C5A16` | 版本、限制、提醒 |
| `--success` | `#2E7D5B` | 成功态 |
| `--warning` | `#9A4B24` | 警示态 |
| `--blocked` | `#9E3F22` | 阻塞态 |
| `--danger` | `#B63E2F` | 失败态 |
| `--info` | `#2F6D8A` | 搜索中、待确认等信息态 |

### 5.3 色彩使用规则

| 规则 | 说明 |
| --- | --- |
| 平台身份不靠颜色区分 | 平台识别优先用名称、图标和标签 |
| 状态色只表达状态 | 不承担品牌装饰功能 |
| 报告图表控色 | 1 组品牌色 + 语义色，禁止彩虹配色 |
| 对比度合规 | 所有文本与状态标签需满足 `WCAG AA` |

### 5.4 字体系统

| 字体角色 | 建议字体 |
| --- | --- |
| 标题字体 | `Alibaba PuHuiTi 3.0` 或 `Source Han Sans SC` |
| 正文字体 | `Noto Sans SC` |
| 数字/技术字段 | `IBM Plex Mono` |

### 5.5 栅格、圆角、阴影

| 项目 | 建议 |
| --- | --- |
| 最大内容宽度 | `1440px` |
| 主栅格 | `12` 列 |
| 列间距 | `24px` |
| 卡片圆角 | `16px` |
| 大容器圆角 | `20px` |
| 主区块垂直间距 | 不低于 `24px` |
| 阴影策略 | 普通卡片以浅边框为主，阴影克制 |

### 5.6 动效原则

| 场景 | 规则 |
| --- | --- |
| 页面进入 | 轻微上浮 + 淡入，`160ms-240ms` |
| 执行中状态 | 低频呼吸光或进度线，不做大面积闪烁 |
| 抽屉/折叠/版本切换 | 用滑入强化层级关系 |
| 可访问性 | 支持 `prefers-reduced-motion` |

### 5.7 图表与对比呈现

| 推荐形式 | 不推荐形式 |
| --- | --- |
| 对比矩阵 | 饼图 |
| 区间条 | 雷达图 |
| 指标卡 | 词云 |
| 主题标签组 | 三维图形 |
| 证据抽屉 | 复杂 BI 大屏表达 |

## 6. 状态系统与交互规则

### 6.1 状态语义映射

| 语义层 | 适用状态 | 视觉表达 | 备注 |
| --- | --- | --- | --- |
| `neutral` | `Draft`、`Pending`、`Skipped` | 灰底或描边标签 | 中性过程态 |
| `info` | `Searching`、`AwaitingConfirmation`、`AwaitingSelection` | 蓝青色标签或提示条 | 说明系统正在组织信息 |
| `progress` | `Running`、`session_check`、`crawl`、`analyze` | 动态进度样式 | 强调过程，不代表结果 |
| `success` | `Completed` | 绿色确认样式 | 完整成功 |
| `warning` | `PartialCompleted`、样本不足、限制说明 | 琥珀色提醒 | 有产出但覆盖不完整 |
| `blocked` | `SearchBlocked`、`Blocked` | 橙红色阻塞样式 | 必须带恢复动作 |
| `danger` | `Failed` | 红色失败样式 | 明确失败 |
| `empty` | `NoResult`、`NoSelection` | 中性空状态 | 不等于失败 |

### 6.2 三层状态不可混用

| 层级 | 字段 | 放在哪里 | 回答什么问题 |
| --- | --- | --- | --- |
| 任务层 | `task_status` | 任务页顶部 | 整个任务当前是否可用 |
| 阶段层 | `task_stage` | 执行页阶段轴 | 系统现在正在做哪一步 |
| 平台层 | `platform_status` | 候选页与执行页的平台卡片 | 哪个平台现在发生了什么 |
| 报告层 | `execution_status` | 报告页平台 Section | 最终发布报告如何描述该平台结果 |

### 6.3 状态流图

```mermaid
flowchart TD
    A[Draft] --> B[AwaitingConfirmation]
    B -->|零确认收口| C[NoSelection]
    B -->|至少一个确认| D[Running]
    D --> E[Completed]
    D --> F[PartialCompleted]
    D --> G[Blocked]
    D --> H[Failed]
    G -->|恢复后继续| D
    F -->|平台级重试| D
```

### 6.4 关键状态文案模板

| 状态 | 推荐文案结构 | 示例 |
| --- | --- | --- |
| `Blocked` | 结论 + 原因 + 下一步 | `需登录后才能继续抓取，请处理会话后重试` |
| `PartialCompleted` | 结论 + 缺口 + 可用性 | `报告已生成，但 1 个已确认平台未完成` |
| `NoResult` | 结论 + 归因 + 口径 | `该平台未找到候选结果，不计入失败` |
| `sample_flag=insufficient` | 结论 + 范围限制 | `样本不足，当前结论仅基于 24 条评论` |
| `NoSelection` | 结论 + 原因 + 后续动作 | `本次未确认任何链接，任务已结束；你可以处理会话后重新搜索` |

### 6.5 禁止做法

| 禁止项 | 原因 |
| --- | --- |
| 用单个总进度条替代全部状态 | 会丢失任务层、阶段层、平台层差异 |
| 把平台异常只写进日志 | 用户无法快速定位问题 |
| 用“处理中”“异常”覆盖多个状态 | 信息含糊，不利于恢复 |
| 在报告页直接复用运行态 `platform_status` | 会破坏报告快照口径 |

## 7. 页面级设计

### 7.1 新建任务页

#### 7.1.1 页面概要

| 项目 | 说明 |
| --- | --- |
| 页面目标 | 让用户快速输入目标商品并理解任务边界 |
| 建议路由 | `/tasks/new` |
| 主按钮 | `创建任务` |
| 主要风险 | 平台可用性、样本规则、输入过载 |

#### 7.1.2 布局与模块

| 区块 | 内容 |
| --- | --- |
| 左侧主栏 `7` | 任务输入、评论样本配置、示例输入、规则说明 |
| 右侧侧栏 `5` | 平台可用性提示、最近会话状态、最近任务快捷入口 |

| 模块 | 作用 | 关键字段 |
| --- | --- | --- |
| `Hero Composer` | 输入查询词与商品描述 | `query`、`description` |
| `Sampling Config` | 配置评论样本策略 | `per_link_limit`、`task_total_limit` |
| `Platform Readiness Panel` | 展示平台会话与搜索要求 | `search_requirement`、最近会话状态 |
| `Scope Reminder` | 明确 P0 范围和限制 | 平台范围、样本说明 |
| `Recent Tasks Mini List` | 提供回看捷径 | 最近 3 到 5 条任务 |

#### 7.1.3 关键交互

| 交互 | 规则 |
| --- | --- |
| 输入校验 | 前置在字段下方，不使用提交后大弹窗 |
| 平台状态提示 | 只作预告，文案需说明“实际执行时将再次检查” |
| 去处理登录 | 从状态卡直接跳到 `/sessions/:platform/prepare` |
| 完成会话准备后 | 返回原页并刷新该平台会话状态 |
| 创建任务后 | 直接进入候选确认页 |

#### 7.1.4 ASCII 线框

```text
+----------------------------------------------------------------------------------+
| 新建任务                                                                         |
| 查询词 [______________________________]   [创建任务]                             |
| 商品补充描述 [_______________________________________________]                   |
|                                                                                  |
| 左侧主栏                                          | 右侧侧栏                     |
| +----------------------------------------------+  | +--------------------------+ |
| | Sampling Config                              |  | | 平台就绪状态             | |
| | - 单链接评论上限 N                           |  | | 天猫   需登录 / 去准备   | |
| | - 任务总上限 500                             |  | | 京东   可用               | |
| +----------------------------------------------+  | | 淘宝   后续扩展          | |
| +----------------------------------------------+  | +--------------------------+ |
| | Scope Reminder                               |  | +--------------------------+ |
| | - 仅天猫、京东                               |  | | 最近任务                 | |
| | - 淘宝为下一优先平台                         |  | |                          | |
| | - 不保证评论全量                             |  | +--------------------------+ |
| +----------------------------------------------+  |                              |
+----------------------------------------------------------------------------------+
```

### 7.2 候选确认页

#### 7.2.1 页面概要

| 项目 | 说明 |
| --- | --- |
| 页面目标 | 帮助用户在最短时间内确认正确商品链接 |
| 建议路由 | `/tasks/:taskId/confirm` |
| 主按钮 | `开始抓取与分析` |
| 次级动作 | `结束本次确认`、`跳过平台` |

#### 7.2.2 布局与模块

| 区块 | 内容 |
| --- | --- |
| 顶部 `Task Summary Strip` | 查询词、样本设置、平台返回概览 |
| 中部 `Candidate Board` | 按平台分区展示候选 |
| 右侧 `Selection Basket` | 汇总已确认链接、估算样本数、展示主动作 |

| 候选卡字段 | 必须包含 |
| --- | --- |
| 身份信息 | 平台标识、商品主图、商品标题 |
| 商业信息 | 价格、店铺名称、销量/热度/评分 |
| 判断辅助 | 规格差异标签、疑似重复、价格异常、信息不完整 |
| 行为控件 | 源链接入口、勾选控件 |

#### 7.2.3 关键交互

| 交互 | 规则 |
| --- | --- |
| 平台内多选 | 允许 |
| 平台跳过 | 每个平台都必须有显式入口 |
| 主按钮启用条件 | 至少确认一个链接 |
| 零确认收口 | 所有平台已无可继续选择时，允许提交为 `NoSelection` |
| 勾选反馈 | 除勾选状态外，还要提升卡片层级与边框对比 |
| 右侧篮子反馈 | 即时展示确认链接数、理论样本量、总上限提示 |

#### 7.2.4 异常状态

| 状态 | 页面表现 |
| --- | --- |
| `SearchBlocked` | 平台分区显示阻塞卡，不显示空白 |
| `NoResult` | 中性空状态，并标注“不计入失败” |
| 全部不可选 | 可提交进入 `NoSelection` 终态 |
| `NoSelection` 终态 | 给出原因摘要和两个动作：返回新建、处理会话后重搜 |

#### 7.2.5 ASCII 线框

```text
+------------------------------------------------------------------------------------------------+
| 候选确认                                                                                       |
| 查询词: 无线蓝牙耳机      样本: 每链接 100 / 总上限 500      平台返回: 天猫 4 京东 3           |
+-----------------------------------------------+----------------------------+-------------------+
| Candidate Board                               | Candidate Board            | Selection Basket  |
| 天猫                                          | 京东                       | 已确认 2 个链接   |
| +-------------------------------------------+ | +------------------------+ | 理论样本 200      |
| | [x] 主图 标题 价格 店铺 规格标签           | | | [ ] 主图 标题...      | | 预计收缩: 否     |
| | 疑似重复 / 信息不完整 / 查看原链接         | | | SearchBlocked         | | [开始抓取与分析] |
| +-------------------------------------------+ | | [去处理会话]          | | [结束本次确认]    |
|                                               | +------------------------+ |                   |
|                                               |                            |                   |
|                                               |                            |                   |
|                                               |                            |                   |
+------------------------------------------------------------------------------------------------+
```

### 7.3 任务执行页

#### 7.3.1 页面概要

| 项目 | 说明 |
| --- | --- |
| 页面目标 | 让长任务变成可理解、可恢复、可追踪的过程 |
| 建议路由 | `/tasks/:taskId/run` |
| 实时机制 | `SSE` |
| 核心动作 | 处理阻塞、重试平台、查看当前报告 |

#### 7.3.2 布局与模块

| 区块 | 内容 |
| --- | --- |
| 左侧主栏 `8` | `Task Hero Banner`、`Stage Rail`、`Platform Run Panels` |
| 右侧侧栏 `4` | `Live Event Feed`、执行摘要、阻塞恢复入口、可重试动作 |

| 模块 | 作用 |
| --- | --- |
| `Task Hero Banner` | 展示 `task_status`、`task_stage`、已用时、已确认链接数、已完成平台数 |
| `Stage Rail` | 显示 `precheck -> search -> confirmation -> session_check -> crawl -> normalize -> analyze -> publish` |
| `Platform Run Panels` | 每个平台单独展示状态、最近事件、错误原因、下一步动作 |
| `Live Event Feed` | 按时间线展示事件，支持按平台筛选 |
| `Action Panel` | 统一放置处理阻塞、重试、查看报告入口 |

#### 7.3.3 关键交互

| 交互 | 规则 |
| --- | --- |
| 实时刷新 | 使用 `SSE`，不使用高频轮询 |
| 新事件到达 | 不强制打断用户当前阅读位置 |
| `Blocked` 平台 | 在平台卡片内直接提供恢复按钮 |
| 重试动作 | 必须通过 `RetryablePlatformPicker`，只列出 `SearchBlocked`、`Blocked`、`Failed` |
| `PartialCompleted` | 主按钮切为“查看当前报告”，同时保留平台级重试入口 |
| 有部分产出时 | 至少一个平台完成后，允许提前查看报告 |

#### 7.3.4 三层信息并列规则

```text
+----------------------------------------------------------------------------------+
| Task Hero Banner                                                                 |
| task_status = PartialCompleted    task_stage = publish    已用时 07:42           |
+----------------------------------------------------------------------------------+
| Stage Rail                                                                       |
| precheck -> search -> confirmation -> session_check -> crawl -> normalize -> ... |
+------------------------------------------------------+---------------------------+
| Platform Run Panels                                  | Live Event Feed           |
| 天猫  Blocked   [去恢复]                              | 14:02 天猫需登录         |
| 京东  Running                                         | 14:03 京东抓取中         |
| 系统  模板刷新完成                                    | 14:04 请求模板已更新     |
+------------------------------------------------------+---------------------------+
```

三层分别回答：

| 信息层 | 回答的问题 |
| --- | --- |
| 顶部任务状态 | 整任务是否可用 |
| 阶段轴 | 系统正在做哪一步 |
| 平台运行卡 | 哪个平台发生了什么 |

### 7.4 报告页

#### 7.4.1 页面概要

| 项目 | 说明 |
| --- | --- |
| 页面目标 | 让用户先获得结论，再快速验证结论 |
| 建议路由 | `/tasks/:taskId/report` |
| 核心能力 | 摘要、对比、洞察、证据下钻、版本切换 |
| 状态来源 | 只消费报告快照中的 `execution_status` |

#### 7.4.2 信息顺序

| 顺序 | 区块 | 作用 |
| --- | --- | --- |
| 1 | 报告头部摘要 | 给出对象、版本、结论、限制 |
| 2 | 商品快照 | 用指标卡建立全局认知 |
| 3 | 质量标记与限制 | 说明样本和覆盖范围 |
| 4 | 跨平台对比 | 给出平台级矩阵 |
| 5 | 平台级洞察 | 展开每个平台的结构化结论 |
| 6 | 建议区 | 按优先级组织动作建议 |
| 7 | 证据索引与抽屉 | 提供可回溯证据链 |

#### 7.4.3 头部与快照

| 区块 | 必须包含 |
| --- | --- |
| 头部 | 查询词、标准化商品名、`report_version`、默认/历史版本标识、生成时间、`task_status`、`headline`、限制摘要 |
| 商品快照 | 平台数、已确认链接数、评论样本数、抓取时间范围、报告版本、质量标记摘要 |

若为 `PartialCompleted`：

| 要求 | 说明 |
| --- | --- |
| 组合状态条 | 顶部必须显式显示 |
| 平台缺口说明 | 明确列出阻塞或失败平台 |
| 可读性说明 | 提示“报告可阅读，但覆盖范围有限” |

#### 7.4.4 跨平台对比区

| 对比行 | 内容 |
| --- | --- |
| 价格区间 | 平台价格带和主销规格 |
| 平台主卖点 | 平台商品页主叙事 |
| 主要好评主题 | 高频正向反馈 |
| 主要差评/风险主题 | 高频负向反馈 |
| 店铺或链接差异 | 店铺差异、规格差异、显著异动 |

展示规则：

| 规则 | 说明 |
| --- | --- |
| 默认只看平台级 | 不直接铺满链接级细节 |
| 异常平台保留列位 | `blocked`、`failed`、`no_result` 仍保留列位 |
| 主动下钻再展开细节 | 通过卡片或证据抽屉进入 |

#### 7.4.5 平台级洞察区

| Section 结构 | 内容 |
| --- | --- |
| 平台头部 | 平台名称、`execution_status`、已确认链接数、价格区间 |
| `selling_points` | 卖点卡组 |
| `positive_themes` | 好评主题卡组 |
| `negative_themes` | 差评主题卡组 |
| `store_diff_notes` | 店铺差异卡组 |

#### 7.4.6 InsightCard 结构

| 字段 | 必须 |
| --- | --- |
| 标题 | 是 |
| 结论说明 | 是 |
| 置信度 | 是 |
| 样本标记 | 是 |
| 来源范围摘要 | 是 |
| 证据数量或证据链接 | 是 |

交互规则：

| 交互 | 规则 |
| --- | --- |
| 点击卡片 | 打开 `EvidenceDrawer` |
| 样本不足 | 必须显式标识“样本不足” |
| 置信度表达 | 文字枚举 + 视觉样式，不能只靠颜色 |

#### 7.4.7 证据抽屉

| 内容 | 说明 |
| --- | --- |
| 证据摘要 | 当前结论对应的证据简介 |
| 来源平台 | 天猫 / 京东 |
| 来源类型 | `product` / `review` |
| 源链接 | 原始来源入口 |
| 评论引用标识 | 用于回溯 |
| 抓取时间 | 时间上下文 |
| 摘录或摘要 | 当前证据文本 |

#### 7.4.8 ASCII 线框

```text
+--------------------------------------------------------------------------------------------------+
| 报告页                                                                                            |
| 商品: XX 蓝牙耳机    report_version: v3    状态: PartialCompleted    [切换版本]                   |
| headline: 两平台价格接近，但京东差评集中在续航，天猫平台样本不足                                   |
+---------------------------------------------------------------+----------------------------------+
| 商品快照指标卡                                                | 质量标记 / 限制                |
| 平台数 2 | 已确认链接 3 | 评论样本 186 | 时间范围 7d          | 样本不足 / 覆盖有限            |
+---------------------------------------------------------------+----------------------------------+
| 跨平台对比矩阵                                                                                     |
| 价格区间 | 卖点 | 好评主题 | 风险主题 | 店铺差异                                                   |
+----------------------------------------------------------------------------------+---------------+
| 平台级洞察                                                                      | EvidenceDrawer |
| 天猫 Section                                                                    | 证据摘要       |
| 京东 Section                                                                    | 来源链接       |
| Cross-platform Summary                                                          | 评论摘录       |
+----------------------------------------------------------------------------------+---------------+
```

### 7.5 历史任务页

#### 7.5.1 页面概要

| 项目 | 说明 |
| --- | --- |
| 页面目标 | 同时承担工作台首页与任务账本 |
| 建议路由 | `/history` |
| 核心动作 | 搜索、筛选、回看、删除、版本切换、平台级重试 |

#### 7.5.2 布局与字段

| 区块 | 内容 |
| --- | --- |
| 左侧筛选栏 | 状态、平台、时间、是否部分完成等筛选 |
| 中间任务列表 | 搜索、排序、主浏览 |
| 右侧预览面板 | 摘要、版本、失败平台、最近更新时间、快捷操作 |

| 列表字段 | 至少展示 |
| --- | --- |
| 查询词 | 任务识别主信息 |
| 最新 `task_status` | 结果口径 |
| 报告版本 | 无报告则显示 `No report` |
| 更新时间 | 倒序主排序字段 |
| 平台覆盖情况 | 概览 |
| 失败/阻塞平台数 | 风险提示 |
| 快捷入口 | 查看报告、继续执行、重试、删除 |

#### 7.5.3 关键交互

| 交互 | 规则 |
| --- | --- |
| 默认排序 | 最近更新时间倒序 |
| 快速筛选 | 支持 `Completed`、`PartialCompleted`、`Blocked`、`Failed`、`NoSelection` |
| 版本切换 | 可在预览面板完成 |
| 无报告任务 | 显示 `NoSelection` 或失败原因摘要，不渲染为空白 |
| 删除 | 必须二次确认，并说明会删除关联数据与报告 |

### 7.6 会话准备与阻塞恢复页

#### 7.6.1 页面概要

| 项目 | 说明 |
| --- | --- |
| 页面目标 | 为会话准备、登录恢复、验证码和风控处理提供最短闭环 |
| 模式 | `prepare`、`recovery` |
| 共同布局 | 左侧远程浏览器，右侧恢复侧栏 |

#### 7.6.2 页面结构

| 区块 | 内容 |
| --- | --- |
| `Remote Browser Viewport` | 远程浏览器画面 |
| `Recovery Sidebar` | 当前平台、阻塞原因、处理步骤、会话剩余时间、校验按钮、返回按钮 |

#### 7.6.3 状态流

| 状态 | 说明 |
| --- | --- |
| `allocating` | 分配会话资源 |
| `connecting` | 建立连接 |
| `live` | 用户可操作 |
| `verifying` | 系统校验恢复结果 |
| `recovered` | 已恢复成功 |
| `expired` | 会话过期 |

#### 7.6.4 恢复流程图

```mermaid
flowchart TD
    A[进入 prepare/recovery] --> B[allocating]
    B --> C[connecting]
    C --> D[live]
    D --> E[用户处理登录/验证码/风控]
    E --> F[verifying]
    F -->|成功| G[recovered]
    F -->|失败或过期| H[expired]
    H --> B
    G --> I[返回来源页并刷新状态]
```

#### 7.6.5 关键交互

| 交互 | 规则 |
| --- | --- |
| 从 `recovery` 进入 | 返回时保留执行页滚动位置和筛选上下文 |
| 从 `prepare` 进入 | 完成后返回来源页并刷新会话状态 |
| 恢复成功后 | 优先返回原来源页，不跳陌生页面 |
| 连接失败或过期 | 必须提供重新申请入口 |
| 移动端 | 降级为“请在桌面端继续处理”的受限视图 |

## 8. 共享组件与前端模块建议

### 8.1 共享组件总表

| 组件 | 用途 | 主要出现页面 |
| --- | --- | --- |
| `TaskContextHeader` | 任务头部上下文 | 确认、执行、报告 |
| `TaskSpine` | 任务主线阶段表达 | 确认、执行、报告 |
| `PlatformStatusTag` | 平台状态标签 | 确认、执行、报告 |
| `PlatformSummaryTile` | 平台摘要卡 | 新建、确认、报告 |
| `CandidateCard` | 候选商品卡片 | 确认 |
| `SelectionBasket` | 已确认集合与主动作 | 确认 |
| `PlatformRunPanel` | 平台运行卡 | 执行 |
| `InsightCard` | 洞察卡片 | 报告 |
| `EvidenceDrawer` | 证据抽屉 | 报告 |
| `QualityFlagPanel` | 质量与限制说明 | 报告 |
| `VersionSwitcher` | 版本切换 | 报告、历史预览 |
| `SessionLauncher` | 发起会话准备/恢复 | 新建、执行 |
| `RetryablePlatformPicker` | 平台级重试选择器 | 执行、历史 |

### 8.2 与组件库的关系

| 类型 | 策略 |
| --- | --- |
| 复用 Ant Design 的部分 | 表单、抽屉、弹层、表格、分段控件、消息提示 |
| 业务自定义组件 | 候选卡、平台运行卡、洞察卡、证据抽屉头部、状态条 |
| 样式控制 | 用全局 Token 和 CSS Variables 覆盖默认色彩、圆角、边框、排版 |

### 8.3 前端模块映射

| 前端模块 | 对应页面 | 核心依赖 |
| --- | --- | --- |
| `task-composer` | 新建任务页 | 任务创建 API、平台可用性摘要、全局会话准备入口 |
| `candidate-board` | 候选确认页 | 平台候选列表、平台状态、用户选择提交 |
| `task-live-console` | 执行页 | 任务详情 API、SSE 事件流、阻塞恢复入口、可重试平台提交 |
| `report-viewer` | 报告页 | `report_snapshot`、版本列表、证据索引 |
| `history-browser` | 历史任务页 | 历史任务列表、筛选、删除、可重试平台提交 |
| `session-console` | 会话准备页 / 阻塞恢复页 | 远程会话分配、状态校验、恢复结果 |

## 9. 响应式与可访问性

### 9.1 响应式策略

| 断点 | 规则 |
| --- | --- |
| `>= 1280px` | 完整工作台布局 |
| `1024px - 1279px` | 侧栏下移，三列变双列或单列 |
| `768px - 1023px` | 候选分区改为折叠面板，报告矩阵改为堆叠卡片 |
| `< 768px` | 保留新建、历史、报告查看和执行状态查看；会话页降级为提示视图 |

### 9.2 可访问性要求

| 要求 | 说明 |
| --- | --- |
| 状态不可只靠颜色 | 必须同时提供图标和文字 |
| 键盘可达 | 主要交互可通过键盘完成 |
| 实时更新可读 | 执行页更新区域需支持 `aria-live` |
| 对比度合规 | 至少满足 `WCAG AA` |
| 动效可减弱 | 支持减少动态偏好 |

## 10. 前端实现约束

### 10.1 状态管理建议

| 技术 | 适用范围 |
| --- | --- |
| `TanStack Query` | 任务详情、历史列表、报告快照、版本列表、平台候选等服务端状态 |
| `Zustand` | 候选页勾选态、报告页证据抽屉开合、历史页筛选器、执行页局部 UI 状态 |
| `SSE` | 执行页实时任务事件 |

### 10.2 接口契约要求

| 契约 | 要求 |
| --- | --- |
| 任务状态字段 | `task_status`、`task_stage`、`platform_status` 必须原样返回枚举值 |
| `NoSelection` | 必须作为正式终态返回 |
| 报告结构 | 直接返回 `PRD` 定义的结构化 Schema |
| 状态映射 | `platform_status -> execution_status` 由后端在发布阶段完成 |
| 候选数据 | 必须包含足以判断的识别字段，不能只给标题和链接 |
| 会话恢复接口 | 必须返回会话模式、恢复状态和来源页信息 |
| 版本列表 | 必须明确“默认版本”和“最新版本”定义 |
| 历史任务无报告场景 | 必须显式返回“无报告”信息 |

### 10.3 文案与日志边界

| 项目 | 原则 |
| --- | --- |
| 用户可见文案 | 只展示用户可理解的状态描述 |
| 开发诊断信息 | 可作为独立字段，不直接暴露技术错误栈 |
| 平台失败原因 | 尽量转译为“登录已失效”“页面校验失败”“评论接口不可用”等可理解表述 |

## 11. 已收口决策

| 决策 | 说明 |
| --- | --- |
| 统一工作台形态 | 只保留“Web 工作台 + 后端统一执行 + 服务端受控会话中心” |
| `NoSelection` 正式化 | 允许确认页以零确认链接结束任务 |
| 报告状态隔离 | 报告页只消费 `execution_status`，运行页和确认页只消费 `platform_status` |
| 重试都是平台级 | 必须通过可重试平台选择器发起 |
| 默认版本策略 | P0 中默认版本等于最新成功版本 |
| 追溯策略 | 90 天追溯依赖证据索引与摘录快照，不依赖长期保留全部原始大对象 |

## 12. UI 验收清单

| 验收项 | 标准 |
| --- | --- |
| 新建任务页可理解 | 用户能看懂平台提示、样本规则和主操作 |
| 会话准备可回跳 | 拉起会话页后，返回能刷新平台状态 |
| 确认页能正确收口 | 支持多选、跳过平台和 `NoSelection` 终态 |
| 执行页三层状态清晰 | 同时表达任务状态、任务阶段、平台状态 |
| `Completed` 与 `PartialCompleted` 区分明显 | 视觉和文案均有明确差异 |
| 报告页先摘要后证据 | 能先读结论，再下钻验证 |
| 历史页不是空账本 | 支持筛选、回看、切换版本、删除和平台级重试 |
| 会话恢复流程闭环 | 入口、状态流、返回路径清晰 |
| 移动端不崩坏 | 至少能完成阅读、状态查看和基础导航 |

## 13. 一句话结论

MVP 的 UI 不应被做成普通后台管理页，而应被设计成一个“围绕任务与证据组织信息的分析工作台”：新建页负责发起，候选页负责判断，执行页负责解释过程，报告页负责支持决策，历史页负责沉淀与回看，会话页负责最短人工介入闭环。