133 lines
5.3 KiB
Markdown
133 lines
5.3 KiB
Markdown
# 前端设计系统
|
||
|
||
## 1. 设计原则
|
||
|
||
- 使用 shadcn/ui 基础组件和项目自有 App 组件构建业务页面。
|
||
- 运营页面保持紧凑、克制，优先服务高频重复操作。
|
||
- 工单状态、优先级、审计、AI 和系统反馈使用统一语义色。
|
||
- 用户可见文案以中文为主；TypeScript 标识符和 API 字段可保持英文。
|
||
- 列表、筛选、详情、状态和优先级不得创建一次性样式。
|
||
- 管理端强调清晰层级、有限表面和紧凑操作，不使用营销页式装饰布局。
|
||
- 亮色和暗色主题必须同时可用，业务页面不自行硬编码主题颜色。
|
||
|
||
## 2. 设计令牌
|
||
|
||
主题令牌位于 `frontend/src/styles/globals.css`，通过
|
||
`frontend/tailwind.config.ts` 暴露给 Tailwind。
|
||
|
||
核心令牌：
|
||
|
||
- `background`、`foreground`、`surface`、`border`
|
||
- `muted`、`muted-foreground`
|
||
- `primary`、`success`、`warning`、`danger`、`info`、`ai`
|
||
- `sidebar`、`sidebar-foreground`、`sidebar-primary`、`sidebar-accent`、
|
||
`sidebar-border`
|
||
|
||
主题行为：
|
||
|
||
- `AppThemeProvider` 使用 `next-themes`，支持亮色、暗色和跟随系统。
|
||
- `AppThemeToggle` 位于顶部栏，用户选项统一为“亮色”“暗色”“跟随系统”。
|
||
- 亮色和暗色值都在全局样式中定义，业务页面不要新增零散的 `dark:` 颜色覆盖。
|
||
- 侧边栏必须使用 `sidebar*` 令牌，保证主题切换一致。
|
||
|
||
## 3. 组件层级
|
||
|
||
### shadcn/ui 基础组件
|
||
|
||
位于 `frontend/src/components/ui`，尽量保持生成组件的标准 API：
|
||
|
||
- `Button`、`Badge`
|
||
- `Card`、`CardHeader`、`CardContent`、`CardTitle`、`CardDescription`
|
||
- `Input`、`Textarea`、`Select`
|
||
- `Table`
|
||
- `Dialog`、`Sheet`、`DropdownMenu`、`Tabs`
|
||
- `Tooltip`、`Skeleton`、`Sonner`
|
||
|
||
业务页面不要直接修改基础组件实现来满足单页需求，应通过属性、组合或 App 组件扩展。
|
||
|
||
### 项目级 App 组件
|
||
|
||
位于 `frontend/src/components/app`，是业务页面优先使用的页面 API：
|
||
|
||
- `AppSidebar`、`AppTopbar`
|
||
- `AppThemeProvider`、`AppThemeToggle`
|
||
- `AppPage`、`AppPageHeader`
|
||
- `AppDataTable`、`AppFilterBar`
|
||
- `AppDetailLayout`、`AppSection`
|
||
- `AppEmptyState`
|
||
- `AppStatusBadge`、`AppPriorityBadge`
|
||
- `AppField`
|
||
|
||
使用约定：
|
||
|
||
- 列表和表格使用 `AppDataTable`。
|
||
- 搜索和筛选使用 `AppFilterBar`。
|
||
- 主内容加侧栏的详情页使用 `AppDetailLayout`。
|
||
- 状态和优先级使用语义 Badge 组件。
|
||
- 表单标签、必填态和说明使用 `AppField`，避免页面直接使用裸 `Label`。
|
||
- Select 统一采用 `SelectContent > SelectGroup > SelectItem`。
|
||
|
||
## 4. 页面与交互规则
|
||
|
||
### 工单
|
||
|
||
- 工单中心第一列组合工单号、标题、提出人和描述，状态与优先级作为独立运营信息。
|
||
- 工单详情使用总览、事件时间线和侧栏区域，不在多个面板重复同一字段。
|
||
- 状态流转统一使用 `TicketTransitionDialog`；需要备注或解决结果时由领域规则决定。
|
||
- 工单编辑只提交变化字段，避免把未修改的 Agent 字段误标为人工保护字段。
|
||
- `pending_info` 工单必须展示待补全字段、来源证据、原始材料和受理运行。
|
||
- 智能受理 SSE 断线后显示重连状态，终态查询失败时保留人工表单。
|
||
|
||
### 知识与解决方案
|
||
|
||
- 知识、方案和治理页面沿用同一页面、表格和表单组件。
|
||
- 检索结果必须展示来源类型、标题、综合分数和可引用片段。
|
||
- 版本状态、审核人、发布时间和变更摘要应清晰可见。
|
||
- 发布、下线、回滚和高风险确认使用明确的确认对话框。
|
||
|
||
### Agent、Tool、渠道与系统治理
|
||
|
||
- 配置页先展示当前状态，再提供编辑或新建动作。
|
||
- 凭据只显示“已配置”或脱敏尾号，不回填明文。
|
||
- Agent 运行详情展示步骤、事件、调用尝试和冻结配置，但不在普通列表泄露敏感正文。
|
||
- 高风险 Tool 必须显示申请人、审核人、风险级别和当前确认状态。
|
||
- 渠道回复必须展示冻结回复版本及目标会话，不能允许任意自由文本绕过回复任务。
|
||
|
||
## 5. 状态与反馈
|
||
|
||
- 加载：使用 Skeleton 或页面级加载态，避免布局跳动。
|
||
- 空状态：使用 `AppEmptyState`，说明下一步可执行动作。
|
||
- 成功：使用简短 Toast，不重复页面已经明确显示的结果。
|
||
- 失败：错误消息保留在相关区域，并提供重试或人工降级动作。
|
||
- 权限不足：隐藏不可用主操作或明确禁用原因，不伪装成数据为空。
|
||
- 长任务：展示进度阶段、最近事件和连接状态，终态后刷新权威业务数据。
|
||
|
||
## 6. 可访问性与响应式
|
||
|
||
- 表单控件必须有可关联标签。
|
||
- 仅图标按钮必须提供 `sr-only` 文本或 `aria-label`。
|
||
- 状态不能只依赖颜色，应同时显示文本或图标。
|
||
- 焦点顺序与视觉顺序一致，Dialog 和 Sheet 使用标准焦点管理。
|
||
- 桌面优先的治理页面在移动端应明确限制，不压缩成不可操作布局。
|
||
- 时间使用 `<time>` 和 ISO `dateTime`，展示文本按用户时区格式化。
|
||
|
||
## 7. 开发检查
|
||
|
||
新增或修改页面后运行：
|
||
|
||
```powershell
|
||
cd frontend
|
||
pnpm test:run
|
||
pnpm typecheck
|
||
pnpm lint
|
||
pnpm build
|
||
```
|
||
|
||
预览入口：
|
||
|
||
```text
|
||
frontend/src/features/design-system/DesignSystemPreview.tsx
|
||
```
|
||
|
||
业务代码结构、注释和提交规则见[开发指南](../development/development-guide.md)。
|