# 审批中心 - 状态机文档

> **版本**: v1.0  
> **最后更新**: 2026-01-21  
> **维护者**: FFOA 开发团队

---

## ✅ 机器读取区（必填）

### 核心对象

| 字段 | 内容 |
|------|------|
| 对象类型 | 审批实例 |
| 状态字段 | `status` |
| 数据表 | `approval_instances` |

### 状态列表

| 状态代码 | 说明 | 终态 |
|---------|------|------|
| RUNNING | 流程运行中 | ❌ |
| SUSPENDED | 流程暂停 | ❌ |
| APPROVED | 已通过 | ✅ |
| REJECTED | 已拒绝 | ✅ |
| WITHDRAWN | 已撤回 | ✅ |
| TERMINATED | 已终止 | ✅ |
| FAILED | 失败 | ✅ |

### 合法流转

| 当前状态 | 可流转到 | 触发动作 | 执行者 | 前置条件 |
|---------|---------|---------|--------|---------|
| RUNNING | APPROVED | 审批通过 | 审批人 | 流程到达终态 |
| RUNNING | REJECTED | 审批拒绝 | 审批人 | 任一节点拒绝 |
| RUNNING | WITHDRAWN | 撤回 | 申请人 | 流程未结束 |
| RUNNING | TERMINATED | 管理员终止 | 管理员 | 异常/强制终止 |
| RUNNING | FAILED | 系统失败 | 系统 | 异常导致失败 |
| RUNNING | SUSPENDED | 暂停 | 管理员/系统 | 触发暂停条件 |
| SUSPENDED | RUNNING | 恢复 | 管理员/系统 | 解除暂停 |

### terminateType 字段

| 值 | 设置来源 | 说明 |
|---|---------|------|
| `WITHDRAWN` | withdrawSignal | 发起人撤回 |
| `ADMIN_TERMINATE` | adminTerminateSignal | 管理员终止 |
| `null` | 默认 | 超时、错误等归为 TERMINATED |

- 类型定义：`terminateType: 'WITHDRAWN' | 'ADMIN_TERMINATE' | null`
- 向后兼容：旧实例无 terminateType 字段时，fallback 到 terminateReason 字符串匹配
- 设计决策：用 TypeScript union type 替代字符串匹配，分离终止类型和终止原因

---

## 🧭 人类阅读区（可选）

### 状态流转图（如需）

```mermaid
stateDiagram-v2
    [*] --> RUNNING: 启动
    RUNNING --> SUSPENDED: 暂停
    SUSPENDED --> RUNNING: 恢复
    RUNNING --> APPROVED: 通过
    RUNNING --> REJECTED: 拒绝
    RUNNING --> WITHDRAWN: 撤回
    RUNNING --> TERMINATED: 终止
    RUNNING --> FAILED: 失败
```