SAAS-UPGRADE-PLAN.md 8.5 KB
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. 字段契约
规则
- 必填有数就展示；没有就走空态文案，不编数字、不编评论。
- 预留字段必须在模板里占位：值为空时显示
—，可用hint说明「有数据后再出现」。禁止用假数填满。 - 指标必须能回答「比上一期好还是坏」：
value+trendValue+trendState。 - VOC 数字必须带 样本 / 置信度 / 更新时间 三者之一；缺哪项显示哪项为
—。 - 可点击行必须有：
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. 验收
- 经营概览能一眼看出「现在最该盯哪个数」（退款异常时 emphasis）
- 异常行进真实路由，不是 alert
- 验证/分析运行有独立 URL，浏览器后退回列表
- 预留字段为空是
—，没有假数 -
COMPONENT-INDEX.md能搜到新组件 -
npx ng build --configuration=development通过 - 反馈深链
/feedback-inbox/:reviewId - 行动详情独立 URL
/action-suggestion/kanban/:id，浏览器后退回工作台 - 主题列表点行进
/voc-insight/topics/:id - 其余 Hub 接
page-toolbar，预留店铺/类目/负责人为— - 知识库整行进已有商品/竞品详情
- 类目 VOC 诊断可进入商品洞察
- 行动详情不再用抽屉，创建仍用面板
- 退款/监测/新品/品类表格整行进入已有商品或类目详情
- 主题/AI 洞察证据使用
/feedback-inbox/:reviewId，不再只靠 query - 实体页返回与面包屑保留列表 query