# AI 审批编排 — UI 交互规范

> **版本**: v1.0-draft
> **最后更新**: 2026-05-19
> **维护者**: 前端团队
> **关联**: [01-prd.md](./01-prd.md) §5.5 / [07-api.md](./07-api.md) §14

---

## 📋 概述

本模块对外的 UI 界面集中在 **校准 Dashboard**（`/ai-orchestration/calibration`）。

跨模块的 UI 表现：
- **L1 AI 侧栏**（详 [approval-center/05-ui-interaction-spec.md](../approval-center/05-ui-interaction-spec.md) 扩展段）—— 在 approval-center 详情抽屉 480px 内
- **form_template 详情卡片**（详 [form-management/05-ui-interaction-spec.md](../form-management/05-ui-interaction-spec.md) 扩展段）—— 在 form-management 详情页内嵌

本规范仅覆盖**校准 Dashboard 独立页面**。

---

## 🎨 设计原则

- 遵循 Lark 设计系统（详 `.agents/skills/frontend-main/references/frontend-standards.md`）
- 数据密集型页面优先图表 + 表格组合
- 时间轴默认 7d，可切 1h / 24h / 7d / 30d
- 权限分支：`view_all`（IT 管理员 / AI Ops）vs `view_own`（表单管理员）UI 自动切换

---

## 📐 页面布局 — `/ai-orchestration/calibration`

```
+----------------------------------------------------------+
|  AI 编排 / 校准 Dashboard                                  |
|                                                          |
|  [时间窗: 1h | 24h | 7d ★ | 30d]                          |
|  [筛选: 模板▼ 组织▼ 风险等级▼]   [刷新⟳]  [导出 CSV]      |
+----------------------------------------------------------+
|                                                          |
|  +-------------+ +-------------+ +-------------+         |
|  | 修改率       | | 平均决策时间  | | AI 不可用    |        |
|  | 14.2%        | | 8.2s         | | 3 次/小时    |        |
|  | ▼ vs last 7d | | ▲ vs last 7d | | ⚠ > 阈值     |        |
|  | -2.1%        | | +0.5s        | |              |        |
|  +-------------+ +-------------+ +-------------+         |
|                                                          |
|  +-------------+ +-----------------------------+         |
|  | 月度成本     | | 置信度分布                   |        |
|  | $38.45       | | [饼图：低 2 / 中低 8 / ...]  |        |
|  | / $1000      | |                              |        |
|  | 3.8% 已用    | |                              |        |
|  +-------------+ +-----------------------------+         |
|                                                          |
|  时间趋势 (按 form_template 拆分)                          |
|  +------------------------------------------------------+ |
|  | [多线图：modification_rate × 时间 × 模板]              | |
|  | 0.30 ---  alert threshold  -------------               | |
|  | 0.20  ░░░░░░░░░░░░░                                    | |
|  | 0.10  ▓▓▓▓▓▓▓▓▓▓▓▓▓ (expense)                          | |
|  |       █████████████ (business-trip)                    | |
|  |   T-7d                                       Now       | |
|  +------------------------------------------------------+ |
|                                                          |
|  推荐明细列表（钻取入口）                                    |
|  +-------+------+------+--------+----------+------------+ |
|  | 时间   | 模板 | 状态 | 置信度  | 修改？   | 操作       | |
|  +-------+------+------+--------+----------+------------+ |
|  | 8:35  | exp  | ✓采纳 | 0.87   | 否       | 详情 →    | |
|  | 8:32  | trip | ✗推翻 | 0.92   | 是       | 详情 → 修改diff |
|  | ...                                                  | |
|  +-------+------+------+--------+----------+------------+ |
|                                                          |
+----------------------------------------------------------+
```

### 5 核心 metric 卡片

| 卡片 | 数据源 | 格式 | 告警 trigger（卡片描红） |
|---|---|---|---|
| 修改率 | `summary.modificationRate` | `XX.X%` + 趋势箭头（vs 上一时间窗）+ delta | > 0.30 红框 |
| 平均决策时间 | `summary.timeToDecisionP50Ms` | `X.Xs` + 趋势 | 无强制阈值；趋势上升 > 50% 黄框 |
| AI 不可用 | `summary.aiUnavailableCount` / time_window | `N 次/h` | > 10/h 红框 |
| 月度成本 | `summary.totalCostUsd / monthlyBudgetUsd` | `$XX.XX / $YYYY` + progress bar + `Z.Z%` | > 90% 红框 |
| 置信度分布 | `summary.confidenceBuckets` | 饼图 4 桶 | < 0.7 占比 > 40% 红框 |

### 时间趋势图

- **多线图**：每个 form_template 一条线（`time × modification_rate`）
- **阈值参考线**：`0.30` 红色虚线 + 文字 "告警阈值"
- 颜色按 tier：Tier 1 绿 / Tier 2 黄 / Tier 3 红
- 鼠标 hover → tooltip 显示该 (template, time_bucket) 完整数字
- 点击线段 → 钻取到推荐明细列表（过滤到该 template + time window）

### 推荐明细列表

- 表头：时间 / 模板 / 状态（ADOPTED ✓ / OVERRIDDEN ✗ / IGNORED ◌ / FAILED ⚠）/ 置信度 / 修改？/ 操作
- 分页 20/页
- 点击"详情 →" → 抽屉打开（右侧 480px）显示 AiRecommendationLog 完整数据（reasoning_chain / risk_indicators / modification_diff）
- **OVERRIDDEN 行特殊**：展开行显示 `modificationDiff.from → to` summary 一行

---

## 🔒 权限分支

| 角色 | 默认 URL | UI 切换 |
|---|---|---|
| IT 管理员 / AI Ops（`view_all`） | `/ai-orchestration/calibration` | 全量；筛选可选 organization；模板筛选不限 |
| 表单管理员（`view_own`） | 同 URL | 自动注入 `organizationId IN (用户管的 orgs)` + `formTemplateKey IN (SELECT key FROM FormTemplate WHERE createdById = userId)`；筛选下拉只显示自己模板 |
| 其他角色 | 不可访问 | `/403` 跳转 |

权限点：
- `calibration_dashboard:view_all`
- `calibration_dashboard:view_own`

---

## 🔧 关键交互

### 1. 切时间窗

点击 `1h / 24h / 7d / 30d` Tab → 立即重查 + 所有图表重渲染 + URL `?timeWindow=7d` 更新（可分享）。

### 2. 筛选下拉

- 模板：从 `GET /form-templates` 拉列表
- 组织：仅 `view_all` 可见；从 `GET /organizations` 拉
- 风险等级：3 固定选项（1/2/3）
- 多选支持；筛选变化 → 实时重查

### 3. 卡片告警态

阈值命中 → 卡片：
- 红框（border-error-500）
- 右上角 ⚠ 图标
- hover tooltip："已触发告警阈值；详情：..."（链接到 AI Ops oncall 频道）

### 4. 趋势图钻取

点击时间趋势图上某线段 → 推荐明细列表自动过滤到该 template + 时间窗内 → 滚动到列表锚点。

### 5. 推荐详情抽屉

点击推荐明细行"详情 →" → 右侧抽屉 480px 滑入：

```
+--------------------+
| 推荐详情            |
+--------------------+
| 时间: 2026-05-19   |
| 模板: expense      |
| 风险等级: Tier 1   |
+--------------------+
| recommended_action |
|   APPROVE          |
| 置信度: 0.87       |
| 模型: claude-opus  |
+--------------------+
| 推理链              |
| [reasoning_chain   |
|  TEXT 最多 4KB]    |
+--------------------+
| 风险点              |
| ✓ 金额合理 (low)   |
| ✓ 历史一致 (low)   |
+--------------------+
| 历史相似 Top 3      |
| → task-uuid-1 链接 |
| → task-uuid-2 链接 |
| → task-uuid-3 链接 |
+--------------------+
| 审批人决策          |
| 状态: ADOPTED      |
| 时间: 8:35:23     |
| 推理链阅读: 8.5s   |
| 滚动距离: 320px    |
+--------------------+
| 成本: $0.0234      |
| 耗时: 1.45s        |
+--------------------+
| [查看审批 task →]   |
+--------------------+
```

OVERRIDDEN 状态额外显示：
- `modification_diff.from / to`（结构化 diff 渲染）
- `modification_reason`（文本）

### 6. 导出 CSV

`[导出 CSV]` 按钮 → 当前筛选条件 + 时间窗 → 下载推荐明细 CSV（所有字段；reasoning_chain 截断 200 字）。

权限：所有可见角色均可导出（导出范围 = UI 可见范围）；写 audit `action='EXPORT_CALIBRATION_CSV'`。

---

## ✨ 动效 / 微交互

- 卡片数字变化：tween 300ms（避免数字跳变）
- 趋势图加载：skeleton 200ms 后渐显
- 告警卡片：边框轻微 pulse 动效 + ⚠ 图标颜色 fade
- 抽屉滑入 / 滑出：240ms ease-out
- 切时间窗：所有图表 loading skeleton（150ms）后重绘

---

## 📱 响应式

- **桌面**（≥ 1280px）：5 卡片 + 时间趋势 + 列表并排（如布局所示）
- **平板**（768-1279px）：5 卡片堆叠 2 行（3+2） + 趋势图 + 列表纵向
- **移动**（< 768px）：5 卡片纵向单列 + 趋势图（横屏旋转提示） + 列表

校准 Dashboard 主要用例是桌面端 IT/AI Ops 使用；移动端兜底显示，不重点优化。

---

## 🌐 i18n

所有文案 i18n key：

```
ai_orchestration.calibration.title = 校准 Dashboard
ai_orchestration.calibration.metric.modification_rate = 修改率
ai_orchestration.calibration.metric.time_to_decision = 平均决策时间
ai_orchestration.calibration.metric.ai_unavailable = AI 不可用
ai_orchestration.calibration.metric.cost = 月度成本
ai_orchestration.calibration.metric.confidence_distribution = 置信度分布
ai_orchestration.calibration.alert.threshold_exceeded = 已触发告警阈值
ai_orchestration.calibration.drawer.reasoning_chain = 推理链
ai_orchestration.calibration.drawer.risk_indicators = 风险点
ai_orchestration.calibration.drawer.historical_similar = 历史相似 Top 3
ai_orchestration.calibration.drawer.modification_diff = 修改对比
ai_orchestration.calibration.action.export_csv = 导出 CSV
... (完整清单 v1.0 上线前补齐)
```

zh-CN + en-US 双语必须；切换 locale 整页文本 + 日期 / 数字格式实时切换。

---

## 🔗 跟其他模块的 UI 衔接

### approval-center 详情抽屉加 AI 侧栏（不在本规范）

详 [approval-center/05-ui-interaction-spec.md](../approval-center/05-ui-interaction-spec.md) 「§AI 侧栏」（待 approval-center 文档扩展）。

UX 要点（本模块只列约束，落地在 approval-center）：
- 480px 抽屉内增加 AI 侧栏区块（位于"表单数据"与"审批历史"之间）
- 显示：推荐 action / 置信度 / 推理链 / 历史相似 Top 3 / 风险点
- Tier 3 + HARD_GATE：倒计时按钮 + 必勾 checkbox
- AI 不可用状态：显示 "AI 暂不可用（[原因]）" + 不阻塞审批
- 审批人停留时长 + 滚动距离采集 → POST adopt/override/ignore 时回传

### form-management form_template 详情卡片（不在本规范）

详 [form-management/05-ui-interaction-spec.md](../form-management/05-ui-interaction-spec.md) 「§AI 校准卡片」（待 form-management 文档扩展）。

UX 要点：
- form_template 详情页右上角嵌入 mini 卡片
- 显示该模板的 7d modification_rate + time_to_decision + cost
- 点击 → 跳到 `/ai-orchestration/calibration?formTemplateKey=<key>`

---

## ❗️待确认项

- [ ] 时间趋势图工具库选型：Recharts vs ECharts vs Tremor（项目其他 dashboard 用什么？需对齐）
- [ ] 推荐明细列表是否支持服务端筛选 ai_mode = SUGGEST_ONLY 的"建议"记录（默认隐藏）
- [ ] 抽屉打开"查看审批 task →"链接行为：新标签页 / 跳转替换；推荐**新标签页**（dashboard 不丢上下文）

---

## 🔗 关联

- [01-prd.md](./01-prd.md) §5.5 校准 Dashboard
- [07-api.md](./07-api.md) §14 GET /calibration
- [06-data-model.md](./06-data-model.md) `calibration_metrics_snapshot` + `ai_recommendation_logs`
- approval-center [`05-ui-interaction-spec.md`](../approval-center/05-ui-interaction-spec.md) 待扩展 AI 侧栏
- form-management [`05-ui-interaction-spec.md`](../form-management/05-ui-interaction-spec.md) 待扩展 mini 卡片
- `.agents/skills/frontend-main/references/frontend-standards.md` Lark 设计系统