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. 建议目录结构

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. 验证目标

每个阶段至少运行：

npm test
npm run build

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