# AI 审批编排（AI Approval Orchestration）

> **负责人**: FFOA 开发团队
> **状态**: 🚧 Draft（合并 PRD 阶段 0+1 草案）
> **最后更新**: 2026-05-19

---

## 📋 文档导航

| 文档 | 状态 | 最后更新 | 何时读取 |
|------|------|---------|---------|
| [产品需求文档](./01-prd.md) | 🚧 Draft | 2026-05-19 | 实施任何阶段 0/1 子项前必读 |
| [架构设计](./03-architecture.md) | ❌ | - | 实施前补 |
| [状态机](./04-state-machine.md) | 🚧 Draft | 2026-05-19 | 实施 AiRecommendation 状态流转前必读 |
| [UI 交互规范](./05-ui-interaction-spec.md) | 🚧 Draft | 2026-05-19 | 实施校准 Dashboard 前必读 |
| [数据模型](./06-data-model.md) | 🚧 Draft | 2026-05-19 | schema 变更前必读 |
| [API 文档](./07-api.md) | 🚧 Draft | 2026-05-19 | 后端 API 实现前必读 |
| [错误码](./08-error-codes.md) | ❌ | - | API 实现配套 |
| [测试场景](./09-test-scenarios.md) | ❌ | - | L1 集成测试前必读 |
| [变更日志](./99-changelog.md) | ❌ | - | - |

**状态说明**:
- ✅ Completed - 已完成并通过评审
- 🚧 Draft - 编写中
- ❌ Not Started - 未开始

---

## 📌 概述

**AI 审批编排**是 FFOA 在 AI-first 时代为审批 + 表单模块新增的**策略编排层**，承载 3 个核心能力：

1. **Policy-as-Code**：声明式策略表把"什么样的审批由 AI 介入到什么程度"从代码硬编码解放为可独立审阅的策略配置（EU AI Act Article 14 合规要求）
2. **Risk Tier Registry**：3 tier × 4 维评分（irreversibility / blast radius / compliance / confidence）的统一风险分级
3. **AI Form Spec 标准**：AI 生成表单产物的元数据规范（落 `FormVersion.schema._ai` 子节点）

**校准 Dashboard** 是本模块对外服务的可观测性入口（`/ai-orchestration/calibration`）。

### 跟其他模块的边界

| 模块 | 跟本模块的关系 |
|---|---|
| **approval-engine** | 本模块提供"哪个 task 该走 AI 推荐"的策略；approval-engine 本身不改契约面 |
| **approval-center** | 详情抽屉 480px 加 AI 侧栏区块（消费本模块的推荐数据） |
| **form-engine** | FormVersion.schema._ai 子节点跟本模块的 AI Form Spec 标准对齐；form-engine 持有数据，本模块定义规范 |
| **form-management** | designer 切只读 + FormTemplate.source/origin 字段；本模块不直接动 form-management 数据 |
| **audit-system** | 6 字段扩展 + AuditAction 4 新值由本模块在 audit-system 上声明扩展；audit-system 提供哈希链分段迁移 |
| **agent** | AI 推荐调用走 agent 模块的 ModelRouter；依赖 #410 PR-A 合入 |
| **knowledge-base** | "历史相似 Top 3"复用 knowledge-base 的 RAG 能力 |
| **ai-form-genesis** | 自然语言 → form spec 生成是平行子能力模块；产物落 form-engine，元数据遵循本模块的 AI Form Spec 标准 |

### 核心功能（阶段 0 + 1 合并交付）

**阶段 0 — 共用基建**：

1. **Policy-as-Code 表** —— `(form_template_key, organizationId) → tier + reviewer_set + ai_mode + confidence_threshold + monthly_ai_call_budget + cross_org_visibility`
2. **ApprovalPolicyHistory** —— 策略本身的版本审计 trail
3. **Risk Tier Registry** —— 3 tier × 4 维评分配置 + top 5 form_template 起步配置
4. **AI Form Spec 标准** —— JSON Schema 顶层 `_ai` 子节点规范 + 版本机制 + 冻结策略
5. **audit-system 扩 6 字段 + AuditAction 4 新值 + 哈希链分段迁移**
6. **校准 Dashboard** —— modification_rate / time_to_decision / ai_unavailable_count / confidence_distribution / ai_cost_usd 5 指标

**阶段 1 — L1 辅助审批**：

7. **AiRecommendationLog** —— 每个审批 task × AI 调用 → 推荐 + 置信度 + 推理链 + 修改 diff 全链路落库
8. **AI 推荐生成器** —— 调用 ModelRouter（按 tier 选模型）+ 复用 knowledge-base RAG 拿历史相似 Top 3 + 幂等 key 防重复扣 token
9. **反 rubber-stamp affordance** —— Tier 3 强制阅读倒计时 + "我已阅读"勾选 + 推翻 modification_diff 必填

### 不在本模块范围

| 项 | 归属 |
|---|---|
| AI Form Genesis 自然语言生成 UX + API | `ai-form-genesis` 模块 |
| approval-engine AI_STAGE 节点类型 | 阶段 2 — `approval-engine/04-state-machine` 留 out-of-scope 占位 |
| approval-center 详情抽屉 480px UI 实现 | `approval-center/05-ui-interaction-spec` |
| FormVersion.schema._ai 持久化 | `form-engine/06-data-model` |
| FormTemplate.source/origin | `form-management/06-data-model` |
| audit-system 哈希链分段迁移脚本 | `audit-system/06-data-model` + 迁移 PR |

---

## 🎯 实施阶段（出自 #409 阶段 0+1+1.5 合并 PRD）

| 阶段 | 子项 | 估时 | 依赖 |
|---|---|---|---|
| 阶段 0 | Policy-as-Code + History + Risk Tier Registry + AI Form Spec 标准 + audit 扩字段 + 校准 Dashboard | 3 周 | #410 PR-A（柔性卡口） |
| 阶段 1 | AiRecommendationLog + 推荐生成器 + 反 rubber-stamp affordance | 2 周 | 阶段 0 完成 + #410 PR-A 合入 |

EU AI Act 时间窗：2026-08-02。详见 [TASK.md](../../../TASK.md) § "EU AI Act 时间窗"。

---

## 🔗 关联

- Issue #409: http://43.130.59.228/FFAIWorkspace/workspace/issues/409
- 方向 review（11 项决策）: http://43.130.59.228/FFAIWorkspace/workspace/issues/410#issuecomment-4528
- 决策沉淀: `.learnings/2026-05-19-410-plan-review.md`（PR #448）
- Agent 接入规范: `docs/standards/21-agent-business-module-integration.md`（PR #449）
- 数据分层政策: `docs/standards/16-data-layering-and-metadata-policy.md`