# 组件索引（给 Agent 定位用）

改 UI 前先查本表。新组件必须补一行。完整方案：`docs/SAAS-UPGRADE-PLAN.md`。

## 怎么找

| 你要做的事 | 先打开 |
| --- | --- |
| 改颜色/圆角/阴影 | `src/modules/shared/styles/_tokens.scss` |
| 卡片/按钮/空态 mixin | `src/modules/shared/styles/_card.scss` `_button.scss` `_state.scss` |
| 顶栏 / 侧栏 / 主区 | `header/` `navigation/` `src/app/app.component.ts` |
| 页头、返回、面包屑 | `page-header/` `page-breadcrumb/` |
| 周期/比较/命令按钮 | `page-toolbar/` `filter-bar/` |
| 指标卡 / 迷你趋势 | `summary-metric-card/` `sparkline/` `metric-card/`（旧，优先 summary） |
| 表格壳 | `data-table-shell/` `crud-table-workbench/` |
| 实体右侧属性 | `entity-property-list/` |
| 模块平级 Tab | `board-tabs/` |
| VOC 页内子导航 | `src/modules/voc-insight/shared/components/voc-insight-rail/` |
| 空/错/加载 | `empty-state/` `error-state/` `loading-spinner/` |
| 按钮 | `neu-button/`（改皮不改名） |
| 评论/行动 | `review-card/` `action-create-panel/` |
| 路由 | `src/app/app.routes.ts` |
| 导航项 | `navigation/navigation.component.ts` 的 `navItems` |

基础路径：`src/modules/shared/components/<name>/`

---

## 壳层

| 选择器 | 目录 | 何时用 | 不要用它做 |
| --- | --- | --- | --- |
| `app-header` | `header/` | 全局顶栏、搜索 | 页内标题 |
| `app-navigation` | `navigation/` | 左导航 | 页内 Tab |
| `app-global-context-bar` | `global-context-bar/` | 工作空间/商品上下文 | 替代页头 |
| `app-page-header` | `page-header/` | 任何页标题；已有 `crumbs` `backLabel` `backRoute` `meta` `lastUpdated` `sampleSize` `confidence` | 再写一套 h1 |
| `app-page-breadcrumb` | `page-breadcrumb/` | 可独立；通常由 page-header 带 | 侧栏路径 |
| `app-page-toolbar` | `page-toolbar/` | Hub 周期/比较/主操作 | 筛选全集（用 filter-bar） |
| `app-page-section` | `page-section/` | 简单分段 | 卡片 |

## 数据展示

| 选择器 | 目录 | 何时用 | 关键输入 |
| --- | --- | --- | --- |
| `app-summary-metric-card` | `summary-metric-card/` | Hub 指标，**优先这个** | label/value/trend*/clickable/emphasis/confidence/sampleSize |
| `app-sparkline` | `sparkline/` | 指标或行内迷你趋势 | points, tone, height |
| `app-metric-card` | `metric-card/` | 遗留页 | 新页不要新增依赖 |
| `app-content-card` | `content-card/` | 图/表外框 | title/subtitle/tone |
| `app-data-table-shell` | `data-table-shell/` | 硬表：加载/空/错/计数 | title/count/empty* |
| `app-entity-property-list` | `entity-property-list/` | Entity 右侧：必填+预留 | items[{label,value,hint,reserved}] |
| `app-entry-card` | `entry-card/` | 入口卡 | — |
| `app-alert-card` | `alert-card/` | 警告条 | 不要当详情页 |
| `app-review-card` | `review-card/` | 单条评论 | — |
| `app-product-identity` | `product-identity/` | 商品身份 | — |
| `app-board-tabs` | `board-tabs/` | Workspace 平级 | tabs/route |
| `app-priority-accordion` | `priority-accordion/` | 优先级折叠 | — |
| `app-split-panel` | `split-panel/` | 左右分栏 | — |

## 筛选与输入

| 选择器 | 目录 | 何时用 |
| --- | --- | --- |
| `app-filter-bar` | `filter-bar/` | 站点/时间/店铺/品类等业务筛选 |
| `app-filter-panel` | `filter-panel/` | 侧滤 |
| `app-date-range-picker` | `date-range-picker/` | 自定义日期 |
| `app-date-picker` | `date-picker/` | 单日 |
| `msq-dropdown` | `msq-dropdown/` | 下拉 |
| `msq-search-box` | `msq-search-box/` | 搜索框 |
| `app-neu-button` | `neu-button/` | 主/次按钮（视觉已去拟态） |

## 状态与全局浮层

| 选择器 | 目录 | 何时用 |
| --- | --- | --- |
| `app-empty-state` | `empty-state/` | 无数据 |
| `app-error-state` | `error-state/` | 失败+重试 |
| `app-loading-spinner` | `loading-spinner/` | 加载 |
| `app-data-source-alert` | `data-source-alert/` | 数据源提示 |
| `app-todo-banner` | `todo-banner/` | 待办条 |
| `app-toast-container` | `toast-container/` | 全局 toast |
| `app-dialog-container` | `dialog-container/` | 全局对话框 |
| `app-action-create-panel` | `action-create-panel/` | **创建行动用抽屉/面板** |
| `app-review-detail-modal` | `review-detail-modal/` | 评论预览，不是主题页 |
| `app-all-reviews-modal` | `all-reviews-modal/` | 评论列表弹层 |

## VOC 专用

| 选择器 | 路径 | 何时用 |
| --- | --- | --- |
| `app-voc-insight-rail` | `src/modules/voc-insight/shared/components/voc-insight-rail/` | 商品 VOC 子分页 |
| `app-voc-product-picker` | `.../voc-product-picker/` | 切换分析商品 |
| `app-ai-analysis-panel` | `shared/components/ai-analysis-panel/` | AI 分析侧栏 |
| `app-ai-visual-report` | `ai-visual-report/` | 报告 HTML；**不要改 styles.scss 里 .ai-visual-report-html** |

## 页面 → 组件（改页先对这张表）

| 路由 | 页面文件 | 应该用 |
| --- | --- | --- |
| `/domestic/overview` | `src/modules/domestic-voc/operating-overview.component.ts` | page-header + page-toolbar + 自研 kpi-cell + sparkline；信号整行走 go* |
| `/feedback-inbox`、`/feedback-inbox/:reviewId` | `src/modules/feedback-inbox/` | 队列+详情；path 深链选中；`page-header` + `page-toolbar`；详情侧 `entity-property-list`（负责人/已读空则 —）；创建行动用 `ActionCreatePanel` |
| `/voc-insight/topics/:id` | `voc-insight/topic-explorer/topic-detail.component.ts` | page-header + property-list |
| `/voc-insight/detail` | `voc-insight/voc-insight-detail/domestic-voc-detail.component.ts` | rail + page-header |
| `/voc-insight/runs` | `ai-voc-insight/analysis-runs/analysis-run-list.component.ts` | 表；点行进 `runs/:id` |
| `/voc-insight/runs/:id` | `ai-voc-insight/analysis-runs/analysis-run-page.component.ts` | page-header + entity-property-list + analysis-run-detail variant=page |
| `/validation` | `validation-center/validation-center.component.ts` | 列表 |
| `/validation/:id` | `validation-center/validation-page.component.ts` | page-header + entity-property-list + validation-detail variant=page |
| `/domestic/competitors/:productId` | `domestic-voc/competitor-detail.component.ts` | page-header + entity-property-list（负责人/验证窗口空则 —） |
| `/action-suggestion/kanban/:id` | `action-suggestion/action-page.component.ts` | page-header + entity-property-list + 状态/负责人/期限更新；创建仍用 `ActionCreatePanel` |
| `/voc-insight/topics` | `voc-insight/topic-explorer/topic-explorer.component.ts` | page-header + page-toolbar；点行进 `/voc-insight/topics/:id` |
| `/knowledge-center` | `knowledge-center/knowledge-center.component.ts` | page-header + page-toolbar；整行进商品/竞品详情 |
| `/system/api` | `system/pages/api-management/` | page-header + page-toolbar |
| `/system/ai-prompts` | `system/pages/ai-prompt-management/` | page-header + page-toolbar |
| `/data-center` | `data-center/data-center.component.ts` | page-header + page-toolbar |
| `/validation` | `validation-center/validation-center.component.ts` | page-header + page-toolbar；点行进 `/validation/:id` |
| `/voc-insight/ai` | `ai-voc-insight/ai-voc-insight.component.ts` | page-header + page-toolbar |
| `/action-suggestion/kanban` | `domestic-voc/framework/domestic-action-workbench.component.ts` | page-header + page-toolbar；点行进 `kanban/:id` |

## 样式 token

| 文件 | 作用 |
| --- | --- |
| `src/modules/shared/styles/_tokens.scss` | 唯一色板。primary=`#171717` |
| `_layout.scss` `_card.scss` `_button.scss` `_table.scss` `_badge.scss` | mixin |
| `src/styles.scss` | 全局；955 行后的 AI report **禁止改** |
| `src/app/app.component.scss` | 主区画布 |

## 新增组件检查表

1. standalone + OnPush  
2. 空值显示 `—`，不编数据  
3. 在本文件补一行  
4. 选择器 `app-*`  
5. 不引入新 UI 库