# 审批引擎 - 数据模型文档

> **版本**: v0.2  
> **最后更新**: 2026-01-20  
> **维护者**: 后端团队

---

## 📋 概述

### Schema 信息

- **Schema 名称**: `corp_approval`
- **业务域**: 审批流程与任务
- **核心表数量**: 11 个

### 设计原则

- 流程定义、实例与任务分层  
- 关键操作可审计、可追溯  
- 支持多版本流程并存

### 命名说明

- 数据库模型使用 `Approval*` 命名（如 `ApprovalDefinition`）  
- 对外 API DTO 中沿用 `Process*` 命名（如 `ProcessDefinition`）

---

## 🗄️ 表结构设计

### 表清单

| 表名 | 说明 |
|------|------|
| `approval_definitions` | 流程定义 |
| `approval_versions` | 流程版本 |
| `approval_instances` | 流程实例 |
| `approval_node_instances` | 节点实例 |
| `approval_tasks` | 审批任务 |
| `approval_task_logs` | 操作日志 |
| `callback_retry_queue` | 回调重试队列 |
| `reminder_queue` | 催办队列 |
| `user_delegation_settings` | 用户委托设置 |
| `approval_admin_configs` | 管理员数据中心配置 |
| `approval_admin_exports` | 管理员导出任务 |

### 表 1: approval_definitions（主表）

#### 基本信息

- **表名**: `corp_approval.approval_definitions`
- **说明**: 流程定义元数据
- **主键**: `id`
- **唯一约束**: `key`

#### 关键字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `key` | String | 流程定义唯一键 |
| `name` | String | 流程名称 |
| `category` | String | 分类 |
| `status` | ProcessStatus | 定义状态 |
| `organization_id` | UUID? | 归属组织 |
| `latest_version` | Int | 最新版本号 |

#### 关联与索引

- 关联：`Organization`（可选）
- 索引：`key`、`category`、`status`、`name`、`organization_id`

---

### 表 2: approval_versions

#### 基本信息

- **表名**: `corp_approval.approval_versions`
- **说明**: 流程版本与模型快照
- **唯一约束**: `(definition_id, version)`

#### 关键字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `definition_id` | UUID | 关联流程定义 |
| `version` | Int | 版本号 |
| `process_model` | Json | 流程模型 |
| `settings` | Json | 全局配置 |
| `status` | VersionStatus | 版本状态 |
| `is_default` | Boolean | 是否默认版本 |
| `deployed_at` | Timestamptz? | 发布时间 |

#### 关联与索引

- 关联：`ApprovalDefinition`、`ApprovalInstance`
- 索引：`definition_id`、`status`、`is_default`

---

### 表 3: approval_instances

#### 基本信息

- **表名**: `corp_approval.approval_instances`
- **说明**: 流程实例（与业务单据关联）
- **唯一约束**: `(business_type, business_id)`、`workflow_id`

#### 关键字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `version_id` | UUID | 关联流程版本 |
| `business_type` | String | 业务类型 |
| `business_id` | String | 业务单据 ID |
| `business_key` | String | 可读业务编号 |
| `workflow_id` | String | Temporal Workflow ID |
| `workflow_run_id` | String | Temporal Run ID |
| `initiator_id` | UUID | 发起人 |
| `region_id` | String? | 发起人区域 |
| `status` | InstanceStatus | 实例状态 |
| `current_node_id` | String? | 当前节点 |
| `variables` | Json | 流程变量 |
| `total_node_executions` | Int | 节点执行统计 |
| `end_reason` | String? | 结束原因 |
| `priority` | Int | 优先级 |
| `due_date` | Timestamptz? | 截止时间 |
| `start_time` | Timestamptz | 启动时间 |
| `end_time` | Timestamptz? | 结束时间 |

#### 关联与索引

- 关联：`ApprovalVersion`、`ApprovalNodeInstance`、`ApprovalTask`
- 索引：`business_key`、`business_type`+`business_id`、`initiator_id`、`region_id`、`status`、`workflow_id`、`version_id`

---

### 表 4: approval_node_instances

#### 基本信息

- **表名**: `corp_approval.approval_node_instances`
- **说明**: 节点实例快照

#### 关键字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `instance_id` | UUID | 关联流程实例 |
| `node_id` | String | 节点 ID |
| `node_name` | String | 节点名称 |
| `node_type` | String | 节点类型 |
| `status` | NodeStatus | 节点状态 |
| `assignees` | String[] | 审批人列表 |
| `approval_mode` | String? | 审批模式 |
| `execution_count` | Int | 执行次数 |

#### 关联与索引

- 关联：`ApprovalInstance`、`ApprovalTask`
- 索引：`instance_id`、`node_id`、`status`

---

### 表 5: approval_tasks

#### 基本信息

- **表名**: `corp_approval.approval_tasks`
- **说明**: 审批任务

#### 关键字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `instance_id` | UUID | 关联流程实例 |
| `node_instance_id` | UUID | 关联节点实例 |
| `type` | ApprovalTaskType | 任务类型 |
| `assignee` | UUID? | 当前处理人 |
| `candidate_users` | String[] | 候选人 |
| `candidate_groups` | String[] | 候选组 |
| `owner` | UUID? | 原负责人 |
| `status` | ApprovalTaskStatus | 任务状态 |
| `version` | Int | 乐观锁版本 |
| `form_data` | Json? | 表单字段 |
| `priority` | Int | 优先级 |
| `due_date` | Timestamptz? | 截止时间 |
| `reminder_count` | Int | 催办次数 |
| `auto_approved` | Boolean | 自动通过标记 |
| `delegation_type` | DelegationType? | 委托类型 |
| `create_time` | Timestamptz | 创建时间 |
| `claim_time` | Timestamptz? | 认领时间 |
| `end_time` | Timestamptz? | 完成时间 |

#### 关联与索引

- 关联：`ApprovalInstance`、`ApprovalNodeInstance`、`ReminderQueue`
- 索引：`instance_id`、`node_instance_id`、`assignee`+`status`、`status`+`create_time`、`due_date`

---

### 表 6: approval_task_logs

#### 基本信息

- **表名**: `corp_approval.approval_task_logs`
- **说明**: 审批操作日志

#### 关键字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `task_id` | UUID | 关联任务 |
| `instance_id` | UUID | 冗余实例 ID |
| `action` | ApprovalTaskAction | 操作类型 |
| `operator_id` | UUID | 操作人 |
| `target_user_id` | UUID? | 目标用户 |
| `target_node_id` | String? | 目标节点 |
| `add_sign_users` | String[] | 加签用户 |
| `form_data_changes` | Json? | 表单变更 |
| `attachments` | Json? | 附件 |
| `request_id` | String? | 请求 ID |
| `risk_level` | RiskLevel? | 风险等级 |
| `admin_reason` | String? | 管理员原因 |
| `action_time` | Timestamptz | 操作时间 |

#### 关联与索引

- 关联：`ApprovalTask`、`User`
- 索引：`task_id`、`instance_id`、`operator_id`、`action`、`action_time`

---

### 表 7: callback_retry_queue

#### 基本信息

- **表名**: `corp_approval.callback_retry_queue`
- **说明**: 外部回调重试

#### 关键字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `instance_id` | UUID | 关联流程实例 |
| `callback_type` | String | 回调类型 |
| `callback_url` | String? | 回调地址 |
| `payload` | Json | 回调载荷 |
| `retry_count` | Int | 已重试次数 |
| `max_retries` | Int | 最大重试 |
| `next_retry_at` | Timestamptz | 下次重试时间 |
| `status` | CallbackStatus | 队列状态 |

---

### 表 8: reminder_queue

#### 基本信息

- **表名**: `corp_approval.reminder_queue`
- **说明**: 催办调度

#### 关键字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `task_id` | UUID | 关联任务 |
| `instance_id` | UUID | 关联流程实例 |
| `reminder_type` | ReminderType | 催办类型 |
| `channels` | String[] | 通知渠道 |
| `scheduled_at` | Timestamptz | 调度时间 |
| `executed_at` | Timestamptz? | 执行时间 |
| `status` | ReminderStatus | 状态 |

---

### 表 9: user_delegation_settings

#### 基本信息

- **表名**: `corp_approval.user_delegation_settings`
- **说明**: 用户委托配置

#### 关键字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `user_id` | UUID | 被委托用户 |
| `delegate_user_id` | UUID | 委托人 |
| `enabled` | Boolean | 是否启用 |
| `start_time` | Timestamptz? | 生效开始 |
| `end_time` | Timestamptz? | 生效结束 |
| `scope` | DelegationScope | 委托范围 |
| `process_keys` | String[] | 流程范围 |

---

### 表 10: approval_admin_configs

#### 基本信息

- **表名**: `corp_approval.approval_admin_configs`
- **说明**: 管理员数据中心配置（导出保留期等）

#### 关键字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `key` | String | 配置键（唯一） |
| `value` | Json | 配置值 |
| `description` | String? | 配置说明 |
| `updated_by` | UUID? | 更新人 |
| `created_at` | Timestamptz | 创建时间 |
| `updated_at` | Timestamptz | 更新时间 |

---

### 表 11: approval_admin_exports

#### 基本信息

- **表名**: `corp_approval.approval_admin_exports`
- **说明**: 管理员数据中心导出任务

#### 关键字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `status` | ApprovalAdminExportStatus | 导出状态 |
| `format` | String | 导出格式（xlsx/csv） |
| `requested_by` | UUID | 发起人 |
| `filters` | Json | 导出筛选条件 |
| `file_key` | String? | 对象存储 Key |
| `file_name` | String? | 文件名 |
| `file_size` | BigInt? | 文件大小 |
| `content_type` | String? | 文件 MIME |
| `total_rows` | Int? | 导出行数 |
| `error_message` | String? | 失败原因 |
| `started_at` | Timestamptz? | 开始时间 |
| `completed_at` | Timestamptz? | 完成时间 |
| `expires_at` | Timestamptz? | 过期时间 |
| `created_at` | Timestamptz | 创建时间 |
| `updated_at` | Timestamptz | 更新时间 |

---

## 🔢 枚举定义（摘要）

| 枚举 | 值 |
|------|----|
| `ProcessStatus` | `ACTIVE` `SUSPENDED` `ARCHIVED` |
| `VersionStatus` | `DRAFT` `DEPLOYED` `SUPERSEDED` `ARCHIVED` |
| `InstanceStatus` | `RUNNING` `SUSPENDED` `APPROVED` `REJECTED` `WITHDRAWN` `TERMINATED` `FAILED` |
| `NodeStatus` | `PENDING` `ACTIVE` `COMPLETED` `CANCELLED` `FAILED` `SKIPPED` |
| `ApprovalTaskType` | `APPROVAL` `COUNTERSIGN` `OR_SIGN` `CC` `NOTIFICATION` `SERVICE_TASK` `SCRIPT_TASK` `USER_TASK` `RECEIVE_TASK` `SEQUENTIAL` |
| `ApprovalTaskStatus` | `CREATED` `PENDING` `CLAIMED` `RESERVED` `ASSIGNED` `IN_PROGRESS` `COMPLETED` `CANCELLED` `SUSPENDED` `WITHDRAWN` |
| `ApprovalTaskAction` | `SUBMIT` `APPROVE` `REJECT` `RETURN` `FORWARD` `WITHDRAW` `APPROVER_WITHDRAW` `ADD_SIGN` `REMOVE_SIGN` `CLAIM` `UNCLAIM` `DELEGATE` `AUTO_APPROVE` `AUTO_REJECT` `ESCALATE` `REMIND` `ADMIN_APPROVE` `ADMIN_REJECT` `ADMIN_TERMINATE` `ADMIN_REASSIGN` `COMPLETE` `CANCEL` `COMMENT` `EXECUTE` |
| `CallbackStatus` | `PENDING` `PROCESSING` `COMPLETED` `FAILED` |
| `ReminderType` | `TIMEOUT` `MANUAL` `BEFORE_TIMEOUT` |
| `ReminderStatus` | `SCHEDULED` `EXECUTED` `CANCELLED` |
| `DelegationType` | `MANUAL` `AUTO_ON_LEAVE` `AUTO_TIME_RANGE` `AUTO_TIMEOUT` |
| `DelegationScope` | `ALL` `SPECIFIC` |
| `ApprovalAdminExportStatus` | `PENDING` `PROCESSING` `SUCCESS` `FAILED` `EXPIRED` |

---

## ❗️待确认项

- 业务字段的必填与校验规则  
- 关联 `User`/`Organization` 的跨 schema 外键策略  
- 索引与查询模式的性能验证