# 审批引擎 - 错误码文档

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

---

## 📋 概述

本文档定义审批引擎模块的错误码。当前为草稿，需与 API 契约与实现对齐。

### 错误码规范

- **来源**: 以 `docs/modules/approval-engine/07-api.md` 为准  
- **命名**: 当前为英文大写短码（未统一前缀）  
- **HTTP 状态码**: 遵循 RESTful 标准

---

## 🎯 错误码分类

| 分类 | HTTP 状态码 | 说明 |
|------|-----------|------|
| **验证错误** | 400 | 请求参数验证失败 |
| **权限错误** | 403 | 无权限执行操作 |
| **资源错误** | 404 | 资源不存在 |
| **冲突错误** | 409 | 资源冲突 |
| **业务错误** | 422 | 业务逻辑错误 |
| **服务器错误** | 500 | 服务器内部错误 |

---

## ❌ 错误码清单

### 通用错误

| 错误码 | HTTP 状态码 | 场景 | 前端处理 |
|--------|------------|------|---------|
| `UNAUTHORIZED` | 401 | 未认证 | 跳转登录或刷新 Token |
| `FORBIDDEN` | 403 | 无权限 | 隐藏/禁用操作按钮 |
| `NOT_FOUND` | 404 | 资源不存在 | 提示资源不存在 |
| `VALIDATION_ERROR` | 400 | 参数验证失败 | 高亮错误字段 |
| `INTERNAL_ERROR` | 500 | 服务器内部错误 | 提示稍后再试 |

### 流程相关错误

| 错误码 | HTTP 状态码 | 场景 | 前端处理 |
|--------|------------|------|---------|
| `PROCESS_DEFINITION_NOT_FOUND` | 404 | 流程定义不存在 | 提示联系管理员 |
| `PROCESS_VERSION_NOT_FOUND` | 404 | 流程版本不存在 | 提示联系管理员 |
| `PROCESS_INSTANCE_NOT_FOUND` | 404 | 流程实例不存在 | 刷新或返回列表 |
| `PROCESS_ALREADY_EXISTS` | 409 | 业务单据已有运行流程 | 提示并跳转已有流程 |
| `PROCESS_NOT_RUNNING` | 400 | 流程已结束 | 禁止操作并刷新 |
| `PROCESS_SUSPENDED` | 400 | 流程已暂停 | 提示等待恢复 |

### 任务相关错误

| 错误码 | HTTP 状态码 | 场景 | 前端处理 |
|--------|------------|------|---------|
| `TASK_NOT_FOUND` | 404 | 任务不存在 | 返回列表并刷新 |
| `TASK_ALREADY_COMPLETED` | 400 | 任务已完成 | 禁止重复提交 |
| `TASK_ALREADY_CLAIMED` | 400 | 任务被他人认领 | 刷新任务状态 |
| `NOT_TASK_ASSIGNEE` | 403 | 非处理人 | 提示无权限 |
| `NOT_CANDIDATE` | 403 | 非候选人 | 提示无权限 |
| `CONCURRENT_MODIFICATION` | 409 | 并发冲突 | 提示刷新后重试 |

### 操作相关错误

| 错误码 | HTTP 状态码 | 场景 | 前端处理 |
|--------|------------|------|---------|
| `WITHDRAW_NOT_ALLOWED` | 400 | 当前节点不允许撤回 | 提示撤回限制 |
| `NOT_INITIATOR` | 403 | 非发起人撤回 | 提示权限不足 |
| `NEXT_NODE_ALREADY_PROCESSED` | 400 | 下一级已处理 | 禁止撤回 |
| `WITHDRAW_TIME_EXCEEDED` | 400 | 超过撤回时限 | 提示超时 |
| `APPROVER_WITHDRAW_DISABLED` | 400 | 审批人撤回禁用 | 隐藏撤回入口 |
| `INVALID_TARGET_NODE` | 400 | 目标节点无效 | 提示选择有效节点 |
| `RETURN_NOT_ALLOWED` | 400 | 不允许退回 | 提示退回限制 |
| `REMIND_LIMIT_EXCEEDED` | 400 | 催办次数超限 | 禁止继续催办 |
| `REMIND_INTERVAL_TOO_SHORT` | 400 | 催办间隔过短 | 提示稍后重试 |

### 验证相关错误

| 错误码 | HTTP 状态码 | 场景 | 前端处理 |
|--------|------------|------|---------|
| `VALIDATION_FAILED` | 400 | 节点验证失败 | 显示校验原因 |
| `FIELD_REQUIRED` | 400 | 必填字段未填 | 高亮必填字段 |
| `FIELD_NOT_MODIFIED` | 400 | 必须修改的字段未修改 | 提示修改要求 |
| `COMMENT_REQUIRED` | 400 | 必须填写审批意见 | 提示填写意见 |
| `ATTACHMENT_REQUIRED` | 400 | 必须上传附件 | 提示上传附件 |

### 工作流相关错误

| 错误码 | HTTP 状态码 | 场景 | 前端处理 |
|--------|------------|------|---------|
| `WORKFLOW_ERROR` | 500 | Temporal 执行错误 | 提示稍后重试 |
| `WORKFLOW_NOT_FOUND` | 404 | 工作流不存在 | 提示联系管理员 |
| `WORKFLOW_TIMEOUT` | 504 | 工作流超时 | 提示稍后再试 |
| `MAX_NODE_EXECUTIONS_EXCEEDED` | 400 | 节点执行次数超限 | 提示联系管理员 |
| `MAX_RETURN_COUNT_EXCEEDED` | 400 | 退回次数超限 | 提示退回限制 |

---

## ❗️待确认项

- 错误码是否需要统一前缀规范  
- 错误码与 UI 交互提示的映射策略  
- 各接口的错误码覆盖是否完整