issue-hub-ai/docs/design/implementation-blueprint.md

# Issue Hub AI 一比一复刻实现蓝图

本文档承接 `docs/design/images2/` 下的高保真设计图清单，用于约束后续前端复刻和功能实现的代码结构。

初始代码现状：

- `src/App.tsx` 同时承载启动、状态、数据操作、页面、组件、工具函数，后续必须拆分。
- `src/styles.css` 为单一全局样式文件，后续需要按设计系统、布局、页面拆分。
- 现有业务能力以个人问题中枢为主，中心调度、部门队列、升级、知识复盘等功能需要扩展数据模型。

当前实现状态：

- 应用入口已拆到 `src/app/App.tsx`、`src/app/appState.ts`、`src/app/appWorkflows.ts` 和 `src/app/routes.ts`。
- 领域逻辑已进入 `src/domain/`，本地仓储、同步、设置和密钥边界进入 `src/data/`。
- 调度端和客户端页面已进入 `src/features/dispatcher/`、`src/features/client/`，页面专属组件与 CSS 按业务面拆分。
- 共享样式已收口到 `src/shared/styles/`，原未引用的 `src/styles.css` 已删除，避免保留单一大样式文件误导后续维护。

## 1. 复刻目标

先完成设计图定稿，再按设计图一比一复刻以下页面：

### 调度中心

- 中心调度台。
- 问题池。
- 部门队列。
- 提醒升级。
- 知识复盘。
- 规则配置。
- 管理看板。

### 客户端

- 客户端首页 / 我的待办。
- 提交问题。
- 处理人问题详情。
- 提交人进度追踪。
- 移动端提交 / 补充。

## 2. 建议目录结构

```text
src/
  app/
    App.tsx
    AppShell.tsx
    routes.ts
    useAppBootstrap.ts
  domain/
    issues/
      issueTypes.ts
      issueStatus.ts
      issueSelectors.ts
      issueActions.ts
    dispatch/
      dispatchTypes.ts
      dispatchRules.ts
      dispatchSelectors.ts
    departments/
      departmentTypes.ts
      workload.ts
    ai/
      aiTypes.ts
      aiTriage.ts
      aiRecommendations.ts
    notifications/
      escalationTypes.ts
      escalationRules.ts
  data/
    repository.ts
    seedData.ts
    sync/
      syncClient.ts
      syncTypes.ts
  features/
    dispatcher/
      CenterDashboardPage.tsx
      IssuePoolPage.tsx
      DepartmentQueuePage.tsx
      EscalationCenterPage.tsx
      KnowledgeReviewPage.tsx
      RuleConfigPage.tsx
      AnalyticsBoardPage.tsx
      components/
        DepartmentWorkloadPanel.tsx
        center/
          DispatchQueueTable.tsx
          AiDispatchInspector.tsx
          centerDashboard.css
        escalation/
          escalationCenter.css
        knowledge/
          KnowledgeMetricsStrip.tsx
          KnowledgeReviewTable.tsx
          KnowledgeSummaryPanel.tsx
          knowledgeReview.css
        rules/
          RuleBuilder.tsx
          RuleTypeNav.tsx
          AiStrategyPanel.tsx
          RuleAuditPreview.tsx
          ruleConfig.css
        analytics/
          AnalyticsMetricCard.tsx
          AnalyticsTrendChart.tsx
          StatusDistributionDonut.tsx
          RankingPanel.tsx
          EfficiencyPanel.tsx
          SlaRiskTable.tsx
          AnalyticsSidePanel.tsx
          analyticsBoard.css
    client/
      ClientWorkbenchPage.tsx
      SubmitIssuePage.tsx
      HandlerIssueDetailPage.tsx
      SubmitterTrackingPage.tsx
      MobileSubmitPreview.tsx
      components/
        workbench/
        submit/
          SubmitIssueForm.tsx
          SubmitAiPrecheckPanel.tsx
          SubmitRichTextEditor.tsx
          ImpactScopePicker.tsx
          SeverityPicker.tsx
          AttachmentDropzone.tsx
          submitIssue.css
        handler/
        tracking/
        mobile/
    settings/
      SettingsPage.tsx
  shared/
    components/
      Button.tsx
      IconButton.tsx
      Badge.tsx
      MetricTile.tsx
      DataTable.tsx
      Timeline.tsx
      SegmentedControl.tsx
      EmptyState.tsx
    layout/
      Sidebar.tsx
      TopBar.tsx
      SplitPane.tsx
      InspectorPanel.tsx
    hooks/
      useDisclosure.ts
      usePersistedState.ts
    styles/
      tokens.css
      base.css
      layout.css
      components.css
```

## 3. 状态与数据分层

### 3.1 领域数据

需要从现有 `Issue` 扩展为中心调度模型：

- `Issue`：问题主数据。
- `IssueTimelineEvent`：状态、派单、评论、提醒、验收时间线。
- `Assignment`：派单和转派记录。
- `Department`：部门与负责人。
- `User`：用户、角色、技能标签、部门归属。
- `AiTriageResult`：AI 摘要、分类、优先级、派单建议、置信度。
- `EscalationEvent`：提醒、催办、升级记录。
- `KnowledgeItem`：沉淀后的知识条目。
- `DispatchRule`：分类、SLA、派单、自动执行规则。

### 3.2 UI 状态

页面级 UI 状态放在页面组件内：

- 当前选中问题。
- 当前筛选条件。
- 当前 tab。
- 弹窗或抽屉开关。
- 临时表单草稿。

跨页面状态通过轻量应用状态提供：

- 当前角色视角：中心调度员、部门负责人、处理人、提交人。
- 当前登录用户。
- 通知数量。
- 同步状态。

## 4. 页面功能矩阵

| 页面 | 必备功能 | 主要组件 |
| --- | --- | --- |
| 中心调度台 | 查看待派发、采纳 AI、退回补充、批量派发 | `DispatchQueueTable`, `AiDispatchInspector`, `MetricTile` |
| 问题池 | 全局筛选、批量处理、合并相似问题 | `DataTable`, `IssueFilterBar`, `AiInsightPanel` |
| 部门队列 | 查看部门负载、分派处理人、跨部门转派 | `DepartmentWorkloadPanel`, `DispatchQueueTable` |
| 提醒升级 | 查看超时、催办、升级负责人 | `Timeline`, `MetricTile`, `escalationCenter.css` |
| 知识复盘 | 查看已关闭问题、生成知识条目 | `KnowledgeReviewTable`, `KnowledgeSummaryPanel`, `KnowledgeMetricsStrip` |
| 规则配置 | 配置 SLA、派单、提醒、AI 自动执行 | `RuleBuilder`, `RuleTypeNav`, `AiStrategyPanel`, `RuleAuditPreview` |
| 管理看板 | 查看指标、趋势、部门效率 | `AnalyticsMetricCard`, `AnalyticsTrendChart`, `StatusDistributionDonut`, `AnalyticsSidePanel` |
| 客户端首页 | 我的待办、待补充、协作请求 | `WorkbenchMetrics`, `WorkbenchIssueTable`, `WorkbenchDetailPanel` |
| 提交问题 | 表单提交、AI 预检查、附件上传 | `SubmitIssueForm`, `SubmitAiPrecheckPanel` |
| 处理人详情 | 接单、协作、转派、完成处理 | `HandlerIssueSummaryAside`, `HandlerTimelineWorkspace`, `HandlerActionAside` |
| 提交人追踪 | 查看进度、补充、催办、验收 | `SubmittedIssueList`, `SubmitterProgressMain`, `SubmitterIssueAside` |
| 移动端提交 | 移动表单、补充信息、附件 | `MobileSubmitPhone`, `MobileSupplementPhone`, `MobileFeatureRail` |

## 5. 交互状态要求

每个核心操作至少要有以下状态：

- 默认。
- hover。
- focus。
- disabled。
- loading。
- 成功反馈。
- 失败反馈。

关键业务操作必须写入时间线：

- AI 分析完成。
- 中心派发。
- 部门分派。
- 接单。
- 转派。
- 请求协作。
- 催办。
- 升级。
- 完成处理。
- 验收通过或返工。

## 6. 样式拆分原则

- `tokens.css`：颜色、间距、圆角、阴影、字体尺度。
- `base.css`：全局 reset、正文、滚动条、输入基础样式。
- `layout.css`：应用外壳、侧边栏、主工作区、右侧检查器。
- `components.css`：按钮、徽标、表格、时间线、指标块等通用组件。
- 页面特殊样式只放在对应 feature 的局部 CSS 或模块文件中。

## 7. MVP 功能落地顺序

1. 先搭建新的 `AppShell`、路由、设计 token 和共享组件。
2. 复刻中心调度台，打通问题选择、AI 推荐、采纳派发、退回补充。
3. 复刻客户端首页和处理人详情，打通接单、转派、请求协作、完成处理。
4. 复刻提交问题和提交人追踪，打通提交、补充、验收。
5. 复刻部门队列和提醒升级，打通部门分派和 SLA 升级。
6. 复刻知识复盘、规则配置和管理看板。
7. 把 mock 数据替换为仓储层可持久化数据。
8. 增加 focused tests：状态流转、派单规则、SLA 提醒、AI 建议采纳。

## 8. 验证目标

每个阶段至少运行：

```pwsh
npm test
npm run build
```

界面复刻阶段需要额外保存截图，用于和 images2 设计图进行人工对比。