# 审批引擎（Approval Engine）

> **负责人**: FFOA 开发团队  
> **状态**: 🟢 Active  
> **最后更新**: 2026-01-06

---

## 📋 文档导航

| 文档 | 状态 | 最后更新 |
|------|------|---------|
| [产品需求文档](./01-prd.md) | ✅ | 2026-01-06 |
| [用户场景](./02-user-journey.md) | ✅ | 2026-01-06 |
| [架构设计](./03-architecture.md) | ✅ | 2026-01-06 |
| [状态机](./04-state-machine.md) | ✅ | 2026-01-06 |
| [UI 交互规范](./05-ui-interaction-spec.md) | ✅ | 2026-01-06 |
| [数据模型](./06-data-model.md) | ✅ | 2026-01-06 |
| [API 文档](./07-api.md) | ✅ | 2026-01-06 |
| [错误码](./08-error-codes.md) | ✅ | 2026-01-06 |
| [测试场景](./09-test-scenarios.md) | ✅ | 2026-01-06 |
| [开发路线图](./10-roadmap.md) | ✅ | 2026-01-06 |
| [变更日志](./99-changelog.md) | ✅ | 2026-01-06 |

**状态说明**:
- ✅ Completed/Approved - 已完成并通过评审
- 🚧 In Progress/Draft - 编写中
- ❌ Not Started - 未开始
- 📝 Need Update - 需要更新

---

## 📌 概述

审批引擎是 FFOA 平台的核心工作流引擎，提供通用的审批流程管理能力。支持流程定义、版本管理、多种审批模式（串行/并行/会签/或签）以及与 Temporal.io 的深度集成，为企业各类审批业务提供稳定可靠的工作流编排服务。

### 核心功能

1. **流程定义管理** - 支持通过表单管理页面可视化配置审批流程，支持多版本共存
2. **审批操作** - 提供通过/驳回/退回/转发/撤回/加签等完整的审批操作
3. **任务管理** - 待办/已处理/我发起的全流程任务追踪
4. **流程可视化** - 实时流程图展示，审批历史完整追溯
5. **Temporal 集成** - 基于 Temporal.io 的可靠工作流引擎，保证流程执行的稳定性

### 业务价值

- 统一企业审批流程，规范审批管理
- 支持复杂审批场景（条件分支、会签或签等）
- 提供完整的审批追溯和历史记录
- 可视化配置，降低流程维护成本

---

## 🏗️ 技术信息

### 代码位置

- **前端**:
  - `frontend/src/app/(modules)/approval-center/page.tsx` - 审批中心（列表）
  - `frontend/src/app/(modules)/approval-center/submit/[formKey]/page.tsx` - 发起审批
  - `frontend/src/app/(engines)/approval/[businessType]/[instanceId]/page.tsx` - 审批详情
  - `frontend/src/app/(engines)/approvals/page.tsx` - `/approvals` 路由重定向
  - `frontend/src/features/approval/` - 审批组件与流程设计器
- **后端**: `backend/src/engines/approval/`
- **数据库**: `corp_approval.approval_*`（Schema: corp_approval）

### API 端点

- **Base URL**: `/api/v1/approval`
- **主要接口组**:
  - 流程启动（1个接口）
  - 审批操作（10个接口）
  - 任务查询（7个接口）
  - 流程查询（5个接口）
  - 流程图数据（2个接口）
  - 催办与提醒（3个接口）
  - 流程定义管理（6个接口）
  - 管理员操作（20个接口，含 admin analytics / instances / tasks / settings 等）
- **总计**: **54 个接口**（以代码 `backend/src/engines/approval/` 中 `@Get/@Post/@Put/@Patch/@Delete` 实测为准；详细分组见 `07-api.md`）

### 技术栈

- **前端**: Next.js 14 + TypeScript + Tailwind CSS + shadcn/ui
- **后端**: NestJS + Prisma + PostgreSQL
- **工作流引擎**: Temporal.io 1.x
- **其他**: Redis（缓存）、Winston（日志）

---

## 🔗 相关模块

### 依赖的模块

| 模块 | 依赖关系 | 说明 |
|------|---------|------|
| [表单管理](../form-management/) | 强依赖 | 流程定义与表单定义绑定 |
| [组织架构](../organization/) | 强依赖 | 审批人配置依赖用户和部门信息 |
| [通知引擎](../notification-engine/) | 弱依赖 | 审批通知推送 |

### 被依赖的模块

| 模块 | 依赖关系 | 说明 |
|------|---------|------|
| 所有业务模块 | 强依赖 | 报销、采购、请假等业务都使用审批引擎 |
| [表单引擎](../form-engine/) | 弱依赖 | 表单提交后触发审批流程 |

---

## 🎯 功能完成度

| 功能 | 状态 |
|------|------|
| 流程定义管理 | ✅ |
| 版本管理（多版本共存） | ✅ |
| 串行/并行审批 | ✅ |
| 会签（AND）/或签（OR） | ✅ |
| 条件分支路由 | ✅ |
| 审批操作（通过/驳回/退回/转发/撤回/加签） | ✅ |
| 任务管理（待办/已处理/我发起的） | ✅ |
| 流程图可视化 | ✅ |
| 审批历史追踪 | ✅ |
| Temporal 工作流集成 | ✅ |
| 表单管理页面配置流程 | ✅ |
| 抄送功能 | ✅ |
| 批量审批 | 📋 规划中 |

**整体完成度**: ~85%

---

## 🚀 快速开始

### 1. 发起审批流程

```typescript
const result = await approvalService.startApproval({
  processDefinitionKey: 'OVERTIME_APPROVAL',
  businessType: 'OVERTIME',
  businessId: overtime.id,
  variables: {
    title: '张三的加班申请',
    applicantId: currentUser.id,
    hours: 8,
  },
});
```

### 2. 审批操作

```typescript
// 通过
await approvalService.approve({
  instanceId: approval.instanceId,
  taskId: 'task-xxx',
  operatorId: currentUser.id,
  comment: '同意',
});

// 驳回
await approvalService.reject({
  instanceId: approval.instanceId,
  taskId: 'task-xxx',
  operatorId: currentUser.id,
  comment: '材料不完整',
  reason: 'INCOMPLETE_MATERIALS',
});
```

### 3. 配置新流程

通过**表单管理页面**可视化配置审批流程：

1. 访问 `表单管理 > 表单定义 > 创建表单`
2. 在设计器中配置表单字段
3. 切换到「流程设计」标签，启用审批流程
4. 添加审批节点、设置审批人
5. 保存并提交审核

> 💡 流程配置已从 YAML 文件迁移至可视化页面，无需手动编辑配置文件。

---

## 📊 数据库表

| 表名 | 说明 |
|------|------|
| `approval_definitions` | 流程定义 |
| `approval_versions` | 流程版本 |
| `approval_instances` | 流程实例 |
| `approval_node_instances` | 节点实例 |
| `approval_tasks` | 审批任务 |
| `approval_task_logs` | 操作日志 |

**Schema**: `corp_approval`

---

## 🧪 测试

### 单元测试

```bash
# 后端
cd testing && npm run test:backend:approval

# 前端
cd testing && npm run test:frontend -- frontend/modules/approval
```

### E2E 测试

按 `docs/modules/approval-engine/10-e2e-test-spec.md` 执行（Agent + Playwright MCP）

### 测试覆盖率

- **后端**: ~70%
- **前端**: 待补充
- **目标**: 80%+

---

## 待实现功能

- 条件节点支持复杂表达式
- 子流程支持
- 流程监控和性能分析

---

## 📚 参考资料

### 内部文档

- [PRD 文档](./01-prd.md) - 完整的产品需求和验收标准
- [架构设计](./03-architecture.md) - 详细的技术架构和配置指南
- [UI 交互规范](./05-ui-interaction-spec.md) - 前端开发的交互规范
- [API 文档](./07-api.md) - 54 个接口的详细说明
- [测试场景](./09-test-scenarios.md) - 测试用例和验收标准

### 外部资源

- [Temporal.io 官方文档](https://docs.temporal.io)
- [Prisma ORM 文档](https://www.prisma.io/docs)
- [NestJS 官方文档](https://docs.nestjs.com)

### 项目内相关

- [表单管理模块](../form-management/) - 表单与审批流集成
- [数据库规范入口](../../../.agents/skills/database-main/references/database-standards.md) - Schema 设计规范
- [后端规范入口](../../../.agents/skills/backend-main/references/backend-standards.md) - API 开发规范

---

## 📝 变更记录

查看 [变更日志](./99-changelog.md)

---

## 👥 贡献者

| 角色 | 说明 |
|------|------|
| 后端开发 | 审批引擎核心逻辑、Temporal 工作流集成 |
| 前端开发 | 审批列表、详情页、流程图可视化 |
| 测试工程师 | E2E 测试、流程测试 |

---

**最后更新**: 2025-12-25  
**维护者**: FFOA 开发团队  
**文档版本**: v2.0（已迁移到新文档结构）