# UI 公共组件登记表

> 记录 BossAi 前端可复用组件,避免重复造轮子。新增、重命名、废弃或职责变化时同步更新。
> 技术栈:React 18 + Vite + TypeScript + Tailwind + shadcn/ui(详见 ADR-001)

## 基础组件(shadcn/ui,复制即用)

| 组件 | 类型 | 适用场景 | 输入状态 | 输出事件 | 使用页面 | 状态 |
|---|---|---|---|---|---|---|
| `Button` | 基础组件 | 按钮交互 | `variant` / `size` / `disabled` / `asChild` | `onClick` | 全部页面 | 稳定 |
| `Card` | 基础组件 | 内容卡片容器 | `className` | - | 全部页面 | 稳定 |
| `Input` | 基础组件 | 单行输入 | `value` / `placeholder` / `disabled` | `onChange` | 设置(待实现) | 稳定 |
| `Textarea` | 基础组件 | 多行输入 | `value` / `placeholder` | `onChange` | 法务参谋 | 稳定 |
| `Badge` | 基础组件 | 状态标签 | `variant` | - | 全部页面 | 稳定 |
| `Label` | 基础组件 | 表单标签 | `htmlFor` | - | 法务参谋 | 稳定 |
| `Separator` | 基础组件 | 分隔线 | `orientation` | - | 通用 | 稳定 |
| `ScrollArea` | 基础组件 | 滚动区域 | `className` | - | 通用 | 稳定 |
| `Select` | 基础组件 | 下拉选择 | `value` / `onValueChange` | `onValueChange` | 预留 | 稳定 |
| `Dialog` | 基础组件 | 弹窗/二次确认 | `open` / `onOpenChange` | `onOpenChange` | 法务参谋(销毁确认) | 稳定 |
| `Toaster`(sonner) | 基础组件 | 全局 toast 反馈 | `position` | - | 全局(AppLayout) | 稳定 |

## 布局组件

| 组件 | 类型 | 适用场景 | 输入状态 | 输出事件 | 使用页面 | 状态 |
|---|---|---|---|---|---|---|
| `AppLayout` | 布局组件 | 应用主框架(Sidebar+Header+内容) | - | - | 全部页面(路由出口) | 稳定 |
| `Sidebar` | 布局组件 | 左侧导航(w-60 sticky) | - | `NavLink` 跳转 | 全部页面 | 稳定 |
| `Header` | 布局组件 | 顶部栏(h-14 sticky,移动端含抽屉) | `nav`(移动端导航内容) | - | 全部页面 | 稳定 |
| `MobileNav` | 布局组件 | 移动端抽屉导航 | - | `NavLink` 跳转 | Header 抽屉 | 稳定 |
| `PageLayout` | 布局组件 | 页面骨架(标题+描述+操作区+内容) | `title` / `description` / `actions` / `children` | - | 全部页面 | 稳定 |

## 领域/组合组件

| 组件 | 类型 | 适用场景 | 输入状态 | 输出事件 | 使用页面 | 状态 |
|---|---|---|---|---|---|---|
| `StatusBadge` | 组合组件 | 风险等级徽章 | `level`(green/amber/orange/red) | - | 驾驶舱、法务参谋 | 稳定 |
| `RiskCardView` | 领域组件 | 风险卡片(等级+结论+行动+证据+升级) | `card`(RiskCard) / `answer` / `model` / `onEscalate` | `onEscalate` | 法务参谋 | 稳定 |
| `EmptyState` | 组合组件 | 空数据状态 | `title` / `description` / `icon` / `action` | - | 法务参谋、占位页 | 稳定 |
| `LoadingState` | 组合组件 | 加载状态 | `label` | - | 通用(预留) | 稳定 |
| `ErrorState` | 组合组件 | 错误状态(带重试) | `message` / `onRetry` | `onRetry` | 驾驶舱 | 稳定 |
| `ChatPanel` | 领域组件 | 通用对话面板(会话/提问/风险卡/上传/急停/工单升级) | `scene` / `samples` / `modes` / `defaultMode` / `emotionMode` / `modeSelector` / `showRiskCard` / `enableUpload` | 内部状态 + 工单创建 | 法务参谋、经营决策、生活助理、情绪中心 | 稳定 |
| `OfflineIndicator` | 基础组件 | 全局离线提示条(网络断开时显示) | - | - | 全局(AppLayout) | 稳定 |
| `Markdown` | 基础组件 | AI 回复 Markdown 渲染(GFM+代码高亮+流式光标) | `content` / `streaming` / `className` | - | ChatPanel、RiskCardView | 稳定 |
| `TicketDetail` | 领域组件 | 工单详情弹窗(状态/分配/处理结果) | `ticket` / `onClose` / `onUpdate` | `onUpdate` | 复核工单 | 稳定 |

## 待沉淀组件(后续迭代)

| 组件 | 类型 | 适用场景 | 触发条件 | 状态 |
|---|---|---|---|---|
| `DataTable` | 基础组件 | 列表/表格 | 待办台账、合同列表页实现时 | 待开发 |
| `Pagination` | 基础组件 | 分页 | 列表数据超过单页时 | 待开发 |
| `FilterBar` | 组合组件 | 筛选栏 | 风险台账、合同管理页实现时 | 待开发 |
| `TimeRangePicker` | 组合组件 | 时间范围筛选 | 数据看板、历史查询实现时 | 待开发 |
| `ConfirmDialog` | 组合组件 | 通用二次确认 | 当前法务参谋用内联 Dialog,出现 2+ 处时抽取 | 待观察 |
| `SessionModePicker` | 领域组件 | 隐私会话模式选择 | 已内联于 ChatPanel,情绪中心实现时抽取 | 已内联 | 待观察 |
| `ToggleRow` | 组合组件 | 设置开关行 | `icon` / `title` / `desc` / `defaultOn` / `danger` | `onClick` | 设置 | 稳定 |

## 设计 Token 约定

- 主色:`--primary` (gray-900 系),通过 CSS 变量,禁硬编码 hex
- 风险色:`risk-green/amber/orange/red`(Tailwind 语义类)
- 状态色三件套:`emerald(success) / amber(warning) / rose(destructive)`
- 圆角:`--radius: 0.625rem`
- 字体:Geist → system-ui 回退
- 容器:`container mx-auto max-w-7xl px-4`

## 2.0 新增组件(web2/src)

> v2.0 在 `web2/` 新目录开发,保留 `web/` v1.0 不动。详见 ADR-002。

| 组件 | 类型 | 适用场景 | 输入状态 | 输出事件 | 使用页面 | 状态 |
|---|---|---|---|---|---|---|
| `NavConfig` | 基础模块 | 共享导航配置(USER_NAV/EXPERT_NAV/ADMIN_NAV/MOBILE_TABS) | - | - | Sidebar/BottomTab/Header | 稳定 |
| `BottomTab` | 布局组件 | 移动端底部 4 Tab(仅 md 以下) | - | `NavLink` 跳转 | AppLayout | 稳定 |
| `Fab` | 布局组件 | 浮动新建按钮(移动端) | - | `onClick` → 跳转 | AppLayout | 稳定 |
| `MatterCard` | 领域组件 | 案卡卡片(图标+标题+状态+时间) | `matter` / `onClick` / `onArchive` | `onClick` / `onArchive` | 事项看板 | 稳定 |
| `ChatPanel`(2.0) | 领域组件 | 通用对话面板(案卡接入+风险卡置顶+起诉状向导+URL预填+专家上下文) | `scene` / `samples` / `modes` / `defaultMode` / `showRiskCard` / `enableUpload` / `matterId` | 内部状态 + 案卡流转 | 法务/决策/生活/情绪 | 稳定 |
| `QuickCommandPanel` | 领域组件 | 快捷指令底部抽屉(画像驱动+语音输入) | `open` / `onClose` | `onClose` | FAB | 稳定 |
| `ExpertAvatar` | 基础组件 | 专家头像(带 fallback 首字母) | `name` / `avatarUrl` / `size` | - | 我的团队 | 稳定 |
| `EmptyState`(2.0) | 组合组件 | 空状态引导 | `title` / `description` / `icon` / `action` | - | 全部页面 | 稳定 |
| `LoadingState`(2.0) | 组合组件 | 加载状态 | `label` | - | 全部页面 | 稳定 |
| `ErrorState`(2.0) | 组合组件 | 错误状态+重试 | `message` / `onRetry` | `onRetry` | 全部页面 | 稳定 |
| `PageLayout`(2.0) | 布局组件 | 页面骨架(标题+描述+操作区+内容) | `title` / `description` / `actions` / `children` | - | 全部页面 | 稳定 |

## 2.0 设计 Token 变更

- 主色:`--primary` 从 gray-900 系改为 **indigo-600** (`hsl(243 75% 59%)`),C 端温暖专业
- 新增案卡状态色:`matter-new/asking/confirm/analyzing/expert/closed`
- 新增动画:`slide-up`(300ms) / `slide-down`(200ms) / `fade-in`(200ms)
- 移动端底部 Tab:`h-16`,主内容区 `padding-bottom: 4rem`
- FAB:`bottom-20 right-4`,圆形 56px,仅移动端