# VOC SaaS 升级方案（落地版）

**状态**：已完全落地（A–H）  
**统筹结论**：不换产品骨架，不做成概念稿。在现有浅色运营壳上，补齐 **Stripe 式主次**、**可点进的硬表**、**实体独立子页**，并把可复用块抽成共享组件。  
**视觉**：shadcn Neutral（炭黑主按钮，蓝只做链接/信息）。规格细节见 `docs/SAAS-UI-UPGRADE.md`。  
**Agent 入口**：先读本文 + `docs/COMPONENT-INDEX.md` + `.cursor/rules/saas-ui-agent.mdc`。

---

## 0. 一句话

经营概览继续是 Hub；反馈/行动学 Linear 队列；分析页学 Amplitude「左条件右主图」；点主题/验证/运行必须进入 **自己的路由**，不是抽屉。

---

## 1. 三种页面（禁止混用）

| 类型 | 做什么 | 例子 | 组件 |
| --- | --- | --- | --- |
| Hub | 先回答「正不正常」，再下钻 | `/domestic/overview` | `page-header` + `page-toolbar` + `summary-metric-card` + 硬表 |
| Workspace | 模块内平级切换 | 退款三页、监测三页、VOC rail | `board-tabs` / `voc-insight-rail` |
| Entity | 整页属于这一条 | 主题、商品 VOC、验证、分析运行、单条反馈 | `page-header`（返回+面包屑）+ `entity-property-list` |

抽屉只留给：创建行动、筛选、评论预览。

---

## 2. 路由（只加子路由，不删旧 path）

| 现况 | 目标 | 行为 |
| --- | --- | --- |
| 已有 | `/voc-insight/topics/:id`、`/voc-insight/detail`、`/domestic/competitors/:productId` | 保持，补面包屑 |
| 抽屉 | `/validation` + **`/validation/:id`** | 列表点行进子页；侧栏仍高亮验证中心 |
| 抽屉 | `/voc-insight/runs` + **`/voc-insight/runs/:id`** | 同上 |
| query | `/feedback-inbox` + **`/feedback-inbox/:reviewId`** | 桌面可仍分栏，URL 必须表达选中；提供「仅此页」头 |
| 看板抽屉 | `/action-suggestion/kanban` + **`/action-suggestion/kanban/:id`** | 点行进独立页；创建仍用面板 |

返回必须带回列表 query。侧栏不挂实体。

---

## 3. 字段契约

**规则**

1. **必填有数就展示**；没有就走空态文案，不编数字、不编评论。
2. **预留字段**必须在模板里占位：值为空时显示 `—`，可用 `hint` 说明「有数据后再出现」。禁止用假数填满。
3. 指标必须能回答「比上一期好还是坏」：`value` + `trendValue` + `trendState`。
4. VOC 数字必须带 **样本 / 置信度 / 更新时间** 三者之一；缺哪项显示哪项为 `—`。
5. 可点击行必须有：`id`、标题、类型、严重度或状态、**去哪**（route）。

### 3.1 Hub · 经营概览 `/domestic/overview`

| 区块 | 必填字段 | 预留（空则 —） | 交互 |
| --- | --- | --- | --- |
| 页头 | 标题「经营概览」 | eyebrow=工作台 | 无 |
| 工具条 | `period.start/end`、`comparisonLabel` | 店铺、类目、负责人 | 数据口径 / 商品列表 / AI 洞察 |
| 结论条 | `primaryMetric`、`text`、`tone` | 下次复盘时间 | 不点出弹窗，点进对应 Workspace/Entity |
| 口径事实 | 明细行数、天数、商品数、VOC 本品/竞品条数、快照时间 | 数据新鲜度 SLA | — |
| 指标 5 宫格 | 成交金额、退款率、成交转化、负向证据、可行动主题；各含 label/value/trend*/spark | 置信度、样本（经营指标可 —） | 退款率异常时视觉上作为 **primary**（`emphasis=primary`），其余缩小一档 |
| 主图 | 7 日成交/转化/退款 | 对比期虚线（有上一窗才画） | 点系列不编新结论 |
| 硬表 | 异常与机会：severity、label、title、detail、metric、action | owner、到期 | **整行**进商品/退款/类目/VOC |

现有 `OverviewKpi` / `OverviewSignal` 继续用，只改展示层级，不改口径计算。

### 3.2 Hub · 反馈收件箱 `/feedback-inbox`

| 区块 | 必填 | 预留 | 交互 |
| --- | --- | --- | --- |
| 队列行 | id、dateLabel、sourceLabel、sentiment、topicLabel、product 标题、priorityLabel | 负责人、已读 | 选中改 URL `/:reviewId` |
| 详情 | 原文、商品、主题、sampleCount、confidence | 关联分析 run、已建行动 | 「展开为页面」；创建行动仍用面板 |

### 3.3 Entity · 验证 `/validation/:id`

必填：`stageLabel`、行动标题、metric（`formattedValue` / `unavailableReason`）、checks、evidenceIds、analysisSummary。  
预留：`assignee`、`dueAt`、`slaHours`（模型没有就 `—`）。  
禁止把未测量写成「有效」。

### 3.4 Entity · 分析运行 `/voc-insight/runs/:id`

必填：status、headline/executiveSummary（空则空态）、sampleCount、evidenceCoverage、insights[]、timeline。  
预留：模型名、提示词版本、费用（没有就 `—`）。

### 3.5 Entity · 主题 / 商品 VOC

已有页补：面包屑、返回、证据条数、置信度、关联商品。  
预留：负责人、验证窗口。不重写分析逻辑。

### 3.6 通用空值

| 情况 | 展示 |
| --- | --- |
| 经营有、VOC 无 | 「部分数据 · 本品 0 / 竞品 N」 |
| 样本 < 门槛 | 置信度低 + 不生成行动 CTA |
| 预留未接 | `—` |
| 加载失败 | `error-state` + 重试 |

---

## 4. 本轮要抽出的复用组件

只新增，不改名已有组件。契约如下。

### 4.1 `app-sparkline`

路径：`src/modules/shared/components/sparkline/`  
输入：`points`（polyline 字符串或 number[]）、`tone: 'default'|'good'|'bad'`、`height`。  
用途：指标卡、表格行。经营概览已有 `sparkPoints`，改为喂这个组件。

### 4.2 `app-page-toolbar`

路径：`src/modules/shared/components/page-toolbar/`  
左：`fields: {label, value}[]`（周期、比较、店铺…）  
右：`ng-content select="[pageToolbarActions]"`  
预留字段走 `value: '—'`。

### 4.3 `app-entity-property-list`

路径：`src/modules/shared/components/entity-property-list/`  
`items: { label, value, hint?, reserved? }[]`  
`value` 空或 `reserved===true && !value` → 显示 `—`，hint 灰色。  
用在所有 Entity 右侧栏。

### 4.4 已有、必须复用（禁止再造一套）

`page-header`（已有 crumbs/back）、`page-breadcrumb`、`summary-metric-card`、`content-card`、`data-table-shell`、`board-tabs`、`empty-state`、`error-state`、`neu-button`、`alert-card`、`filter-bar`。

---

## 5. 波次与文件所有权（并行时不要互相改）

| 波次 | 谁改哪些 | 完成标准 |
| --- | --- | --- |
| A 组件 | 仅新增 4.1–4.3 目录；更新 `COMPONENT-INDEX.md` | **已完成** |
| B Hub | 仅 `operating-overview.component.ts/scss` | **已完成**（退款异常 emphasis；信号整行 +「进入」） |
| C 子页 | `app.routes.ts` + validation + analysis-runs | **已完成**（`/validation/:id`、`/voc-insight/runs/:id`） |
| D 反馈 URL | 仅 `feedback-inbox/*` | **已完成**（`/feedback-inbox/:reviewId`，旧 query 会升到 path） |
| E 收口 | 其它 Hub 接面包屑 | **已完成**（主题/商品 VOC/竞品详情 + 4 个 workbench） |
| F 行动子页与 Hub 工具条 | `action-page` + 各 Hub `page-toolbar` | **已完成** |
| G Wave 2/4 接线 | 反馈/知识库/验证/行动/类目 | **已完成**（队列工具条；知识库整行进详情；验证/行动空态；类目进商品洞察） |
| H 收口补漏 | 工作台行进详情 + 反馈 path 深链 | **已完成**（退款/监测/新品/品类整行进已有详情；证据进 `/feedback-inbox/:reviewId`；返回保留 query；行动抽屉死代码已清） |

禁止：新 UI 库、`npx shadcn@latest init`、改 Parse/后端契约、改 `.ai-visual-report-html`、编造评论。

---

## 6. 验收

- [x] 经营概览能一眼看出「现在最该盯哪个数」（退款异常时 emphasis）
- [x] 异常行进真实路由，不是 alert
- [x] 验证/分析运行有独立 URL，浏览器后退回列表
- [x] 预留字段为空是 `—`，没有假数
- [x] `COMPONENT-INDEX.md` 能搜到新组件
- [x] `npx ng build --configuration=development` 通过
- [x] 反馈深链 `/feedback-inbox/:reviewId`
- [x] 行动详情独立 URL `/action-suggestion/kanban/:id`，浏览器后退回工作台
- [x] 主题列表点行进 `/voc-insight/topics/:id`
- [x] 其余 Hub 接 `page-toolbar`，预留店铺/类目/负责人为 `—`
- [x] 知识库整行进已有商品/竞品详情
- [x] 类目 VOC 诊断可进入商品洞察
- [x] 行动详情不再用抽屉，创建仍用面板
- [x] 退款/监测/新品/品类表格整行进入已有商品或类目详情
- [x] 主题/AI 洞察证据使用 `/feedback-inbox/:reviewId`，不再只靠 query
- [x] 实体页返回与面包屑保留列表 query