docs: complete Chinese project documentation

2026-07-27 19:08:08 +08:00
parent b02d18d3b9
commit 78a70ee7c2
20 changed files with 3441 additions and 654 deletions
--- a/docs/frontend/design-system.md
+++ b/docs/frontend/design-system.md
@@ -1,80 +1,132 @@
-# Frontend Design System
+# 前端设计系统

-## Principles
+## 1. 设计原则

- Build product screens from shadcn/ui primitives and project-owned App components.
- Keep operational pages dense, quiet, and optimized for repeated use.
- Use semantic status colors for ticket state, priority, audit, AI, and system feedback.
- User-facing frontend text must be Chinese-first. Internal TypeScript names and API field names may stay English.
- Business pages must not create one-off table, filter, detail, status, or priority patterns.
- Admin UI should feel calm and enterprise-grade: clear hierarchy, restrained surfaces, compact actions, and no decorative marketing-style layout.
+- 使用 shadcn/ui 基础组件和项目自有 App 组件构建业务页面。
+- 运营页面保持紧凑、克制，优先服务高频重复操作。
+- 工单状态、优先级、审计、AI 和系统反馈使用统一语义色。
+- 用户可见文案以中文为主；TypeScript 标识符和 API 字段可保持英文。
+- 列表、筛选、详情、状态和优先级不得创建一次性样式。
+- 管理端强调清晰层级、有限表面和紧凑操作，不使用营销页式装饰布局。
+- 亮色和暗色主题必须同时可用，业务页面不自行硬编码主题颜色。

-## Tokens
+## 2. 设计令牌

-Theme tokens live in `frontend/src/styles/globals.css` and are exposed through Tailwind in
-`frontend/tailwind.config.ts`.
+主题令牌位于 `frontend/src/styles/globals.css`，通过
+`frontend/tailwind.config.ts` 暴露给 Tailwind。

-Core tokens:
+核心令牌：

- `background`, `foreground`, `surface`, `border`
- `muted`, `muted-foreground`
- `primary`, `success`, `warning`, `danger`, `info`, `ai`
- `sidebar`, `sidebar-foreground`, `sidebar-primary`, `sidebar-accent`, `sidebar-border`
+- `background`、`foreground`、`surface`、`border`
+- `muted`、`muted-foreground`
+- `primary`、`success`、`warning`、`danger`、`info`、`ai`
+- `sidebar`、`sidebar-foreground`、`sidebar-primary`、`sidebar-accent`、
+  `sidebar-border`

-Theme behavior:
+主题行为：

- `AppThemeProvider` uses `next-themes` with `light`, `dark`, and `system`.
- `AppThemeToggle` is rendered in `AppTopbar` and exposes Chinese options: `亮色`, `暗色`, `跟随系统`.
- Light and dark mode values must both be defined in `frontend/src/styles/globals.css`; do not add one-off `dark:` color overrides in business pages.
- Sidebar colors must come from `sidebar*` tokens so the sidebar follows theme switching.
+- `AppThemeProvider` 使用 `next-themes`，支持亮色、暗色和跟随系统。
+- `AppThemeToggle` 位于顶部栏，用户选项统一为“亮色”“暗色”“跟随系统”。
+- 亮色和暗色值都在全局样式中定义，业务页面不要新增零散的 `dark:` 颜色覆盖。
+- 侧边栏必须使用 `sidebar*` 令牌，保证主题切换一致。

-## Components
+## 3. 组件层级

-shadcn/ui primitives live in `frontend/src/components/ui` and should remain close to generated shadcn APIs:
+### shadcn/ui 基础组件

- `Button`
- `Badge`
- `Card`, `CardHeader`, `CardContent`, `CardTitle`, `CardDescription`
- `Input`, `Textarea`, `Select`
+位于 `frontend/src/components/ui`，尽量保持生成组件的标准 API：
+
+- `Button`、`Badge`
+- `Card`、`CardHeader`、`CardContent`、`CardTitle`、`CardDescription`
+- `Input`、`Textarea`、`Select`
 - `Table`
- `Dialog`, `Sheet`, `DropdownMenu`, `Tabs`, `Tooltip`, `Skeleton`, `Sonner`
+- `Dialog`、`Sheet`、`DropdownMenu`、`Tabs`
+- `Tooltip`、`Skeleton`、`Sonner`

-Product App components live in `frontend/src/components/app` and are the preferred page-level API:
+业务页面不要直接修改基础组件实现来满足单页需求，应通过属性、组合或 App 组件扩展。

- `AppSidebar`
- `AppTopbar`
- `AppThemeProvider`
- `AppThemeToggle`
- `AppPage`
- `AppPageHeader`
- `AppDataTable`
- `AppFilterBar`
- `AppDetailLayout`
- `AppSection`
+### 项目级 App 组件
+
+位于 `frontend/src/components/app`，是业务页面优先使用的页面 API：
+
+- `AppSidebar`、`AppTopbar`
+- `AppThemeProvider`、`AppThemeToggle`
+- `AppPage`、`AppPageHeader`
+- `AppDataTable`、`AppFilterBar`
+- `AppDetailLayout`、`AppSection`
 - `AppEmptyState`
- `AppStatusBadge`
- `AppPriorityBadge`
+- `AppStatusBadge`、`AppPriorityBadge`
+- `AppField`

-Business pages should use:
+使用约定：

- `AppDataTable` for repeated table/list surfaces.
- `AppFilterBar` for search and filter controls.
- `AppDetailLayout` for detail pages with main content and side panels.
- `AppStatusBadge` and `AppPriorityBadge` for ticket lifecycle and priority presentation.
- `AppField` for form labels and required state; direct page-level `Label` usage should be avoided.
- `SelectContent > SelectGroup > SelectItem` for every select menu.
+- 列表和表格使用 `AppDataTable`。
+- 搜索和筛选使用 `AppFilterBar`。
+- 主内容加侧栏的详情页使用 `AppDetailLayout`。
+- 状态和优先级使用语义 Badge 组件。
+- 表单标签、必填态和说明使用 `AppField`，避免页面直接使用裸 `Label`。
+- Select 统一采用 `SelectContent > SelectGroup > SelectItem`。

-## Current Core Screens
+## 4. 页面与交互规则

- Ticket center uses an operations-table layout: the first column combines ticket number, title, requester, and description; workflow state and priority are grouped together.
- Ticket detail uses `AppDetailLayout`, a ticket overview card, a real event timeline, and a side column for handling context, linked solutions, and AI analysis placeholder. Avoid repeating overview-card fields in the side column.
- Ticket status transitions use `TicketTransitionDialog`. Resolution and closure actions can carry a solution summary; non-resolution workflow actions still require a handling note.
- Ticket workflows are category-driven: business and operation issues support short closure paths, data issues use a medium path, and technical issues keep the standard support workflow.
- Linked solutions support search, recommendation-only linking, adoption with automatic ticket closure, and prefilled resolution text during later resolve/close actions.
- Knowledge pages use the same `AppPage`, `AppSection`, `AppDataTable`, `AppField`, and shadcn form primitives as ticket and system pages.
- Knowledge search results must show source type, title, score, and citable content snippets.
- System governance quick-create forms use `AppSection`, `FieldGroup`, and `AppField`.
+### 工单

-Preview page:
+- 工单中心第一列组合工单号、标题、提出人和描述，状态与优先级作为独立运营信息。
+- 工单详情使用总览、事件时间线和侧栏区域，不在多个面板重复同一字段。
+- 状态流转统一使用 `TicketTransitionDialog`；需要备注或解决结果时由领域规则决定。
+- 工单编辑只提交变化字段，避免把未修改的 Agent 字段误标为人工保护字段。
+- `pending_info` 工单必须展示待补全字段、来源证据、原始材料和受理运行。
+- 智能受理 SSE 断线后显示重连状态，终态查询失败时保留人工表单。

- `frontend/src/features/design-system/DesignSystemPreview.tsx`
+### 知识与解决方案
+
+- 知识、方案和治理页面沿用同一页面、表格和表单组件。
+- 检索结果必须展示来源类型、标题、综合分数和可引用片段。
+- 版本状态、审核人、发布时间和变更摘要应清晰可见。
+- 发布、下线、回滚和高风险确认使用明确的确认对话框。
+
+### 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)。