# 表单引擎 API

> API 接口文档 - 定义所有表单引擎接口的请求和响应格式

---

## 📋 概述

| 属性 | 值 |
|------|-----|
| Base URL | `/api/v1` |
| 认证方式 | JWT Bearer Token |
| 接口数量 | 50 个 |
| 版本 | v2.0 |

---

## 🔐 权限要求

| 功能模块 | 需要权限 | 说明 |
|---------|---------|------|
| 查看表单列表 | `form:read` | 普通用户可查看已发布表单 |
| 创建表单定义 | `form:create` | 设计者权限 |
| 更新表单定义 | `form:update` | 设计者权限 |
| 删除表单定义 | `form:delete` | 设计者权限 |
| 提交版本审核 | `form:design` | 设计者权限 |
| 审核版本 | `form:admin` | 管理员权限 |
| 发布/归档表单 | `form:admin` | 管理员权限 |
| 管理表单版本 | `form:version:manage` | 版本管理权限 |
| 提交表单实例 | `form:instance:create` | 普通用户权限 |
| 管理翻译 | `form:translation:manage` | 翻译管理权限 |
| 管理模板 | `form:template:manage` | 模板管理权限 |

---

## 📚 接口列表

### 1. 表单定义管理 (12 个)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/forms` | 获取表单列表 |
| GET | `/forms/:formIdentifier` | 获取表单详情 |
| POST | `/forms` | 创建表单 |
| PATCH | `/forms/:formIdentifier` | 更新表单 |
| DELETE | `/forms/:formIdentifier` | 删除表单 |
| POST | `/forms/:formIdentifier/publish` | 发布表单 |
| POST | `/forms/:formIdentifier/archive` | 归档表单 |
| PATCH | `/forms/:formIdentifier/slug` | 更新 Slug |
| POST | `/forms/:formIdentifier/aliases` | 添加别名 |
| DELETE | `/forms/:formIdentifier/aliases/:alias` | 删除别名 |
| POST | `/forms/:formIdentifier/duplicate` | 复制表单 |
| GET | `/forms/:formIdentifier/stats` | 获取统计 |

### 2. 表单版本管理 (10 个)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/forms/:formIdentifier/versions` | 获取版本列表 |
| GET | `/forms/:formIdentifier/versions/:version` | 获取版本详情 |
| POST | `/forms/:formIdentifier/versions` | 创建版本 |
| PATCH | `/forms/:formIdentifier/versions/:version` | 更新版本 |
| POST | `/forms/:formIdentifier/versions/:version/submit-review` | 🆕 提交审核 |
| POST | `/forms/:formIdentifier/versions/:version/review` | 🆕 审核版本 |
| POST | `/forms/:formIdentifier/versions/:version/publish` | 发布版本 |
| POST | `/forms/:formIdentifier/versions/_actions/set-default` | 设为默认（version 在 body 传入）|
| POST | `/forms/:formIdentifier/versions/:version/deprecate` | 废弃版本 |
| GET | `/forms/:formIdentifier/versions/compare` | 版本对比 |

### 3. 表单实例管理 (12 个)

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/form-instances` | 创建实例 |
| GET | `/form-instances/my` | 我的实例列表 |
| GET | `/form-instances/:instanceIdentifier` | 获取实例详情 |
| PATCH | `/form-instances/:instanceIdentifier` | 更新实例 |
| DELETE | `/form-instances/:instanceIdentifier` | 删除实例 |
| POST | `/form-instances/:instanceIdentifier/submit` | 提交实例 |
| POST | `/form-instances/:instanceIdentifier/cancel` | 取消实例 |
| POST | `/form-instances/:instanceIdentifier/restore` | 恢复实例 |
| GET | `/form-instances` | 🔒 获取所有实例 (Admin) |
| POST | `/form-instances/batch-update-status` | 🔒 批量更新状态 (Admin) |
| GET | `/form-instances/export` | 🔒 导出数据 (Admin) |
| GET | `/form-instances/stats` | 🔒 实例统计 (Admin) |

### 4. 表单翻译管理 (6 个)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/forms/:formIdentifier/versions/:version/translations` | 获取翻译列表 |
| GET | `/forms/:formIdentifier/versions/:version/translations/:locale` | 获取指定语言 |
| PUT | `/forms/:formIdentifier/versions/:version/translations/:locale` | 创建/更新翻译 |
| DELETE | `/forms/:formIdentifier/versions/:version/translations/:locale` | 删除翻译 |
| GET | `/forms/:formIdentifier/versions/:version/translations/:locale/check` | 检查翻译完整性 |
| POST | `/forms/:formIdentifier/versions/:version/translations/import` | 批量导入翻译 |

### 5. 表单模板管理 (6 个)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/form-templates` | 获取模板列表 |
| GET | `/form-templates/:templateIdentifier` | 获取模板详情 |
| POST | `/form-templates` | 创建模板 |
| PATCH | `/form-templates/:templateIdentifier` | 更新模板 |
| DELETE | `/form-templates/:templateIdentifier` | 删除模板 |
| POST | `/form-templates/:templateIdentifier/create-form` | 从模板创建 |

### 6. 版本审核管理 (4 个) 🆕

| 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|
| GET | `/form-versions/pending-review` | 获取待审核列表 | `form:admin` |
| GET | `/form-versions/:versionId/preview` | 预览待审核表单 | `form:admin` |
| GET | `/form-versions/:versionId/review-history` | 获取审核历史 | `form:read` |
| GET | `/form-versions/my-submissions` | 我提交的审核 | `form:design` |

---

## 🏷️ 路径参数命名规范

本 API 遵循统一的路径参数命名规范：

- **`:formIdentifier`** - 表单标识符（支持 UUID/key/slug/alias）
- **`:instanceIdentifier`** - 实例标识符（UUID）
- **`:templateIdentifier`** - 模板标识符（UUID/key）
- **`:version`** - 版本号（数字，从 1 开始）
- **`:locale`** - 语言代码（zh-CN, en-US）
- **`:alias`** - 别名（字符串）

**formIdentifier 解析优先级**（按顺序尝试）:
1. UUID (id)
2. Key (不可变标识符)
3. Slug (URL 友好标识)
4. Alias (业务别名)

---

## 📊 数据模型

### FormDefinition（表单定义）

```typescript
interface FormDefinition {
  id: string;                    // UUID
  key: string;                   // 唯一标识（不可变）
  slug: string;                  // URL 友好标识（可变）
  slugHistory: string[];         // Slug 历史记录
  aliases: string[];             // 业务别名
  name: string;                  // 表单名称
  category: string;              // 分类
  description?: string;
  icon?: string;
  color?: string;
  defaultLocale: string;         // 默认语言
  supportedLocales: string[];    // 支持的语言
  latestVersion: number;         // 最新版本号
  status: FormStatus;            // DRAFT | PUBLISHED | ARCHIVED
  requiresApproval: boolean;     // 是否需要审批
  approvalProcessKey?: string;   // 审批流程 Key
  
  // 🆕 区域配置（规划中）
  regionScope?: 'ALL' | 'SPECIFIC';
  allowedRegions?: string[];
  regionApprovalConfig?: Record<string, { approvalProcessKey: string }>;
  
  createdBy: string;
  createdAt: string;
  updatedAt: string;
}

enum FormStatus {
  DRAFT = 'DRAFT',           // 草稿 - 开发中，业务不可见
  PUBLISHED = 'PUBLISHED',   // 已发布 - 业务可用
  ARCHIVED = 'ARCHIVED',     // 已归档 - 停用，保留历史
}
```

### FormVersion（表单版本）

```typescript
interface FormVersion {
  id: string;
  definitionId: string;
  version: number;               // 版本号（从 1 开始）
  nameI18n: Record<string, string>;
  descriptionI18n?: Record<string, string>;
  schema: FormSchema;            // JSON Schema
  uiSchema?: UISchema;           // UI 配置
  viewSchema?: ViewSchema;       // 🆕 详情视图配置
  validation?: object;
  changelog?: string;
  isDefault: boolean;
  status: VersionStatus;
  
  // 🆕 审核相关
  reviewedBy?: string;           // 审核人
  reviewedAt?: string;           // 审核时间
  reviewComment?: string;        // 审核意见
  
  createdBy: string;
  createdAt: string;
  publishedAt?: string;
}

enum VersionStatus {
  DRAFT = 'DRAFT',                   // 草稿 - 设计中
  PENDING_REVIEW = 'PENDING_REVIEW', // 🆕 待审核
  PUBLISHED = 'PUBLISHED',           // 已发布
  REJECTED = 'REJECTED',             // 🆕 已驳回
  DEPRECATED = 'DEPRECATED',         // 已废弃
}
```

### FormInstance（表单实例）

```typescript
interface FormInstance {
  id: string;
  formDefinitionId: string;
  formVersionId: string;         // ⚠️ 不可变
  formKey: string;               // 快照
  formVersion: number;           // 快照
  businessKey: string;           // 🆕 业务单号（唯一）
  regionId?: string;             // 🆕 区域 ID（规划中）
  data: Record<string, any>;     // 表单数据
  status: InstanceStatus;
  createdBy: string;
  submittedBy?: string;
  submittedAt?: string;
  approvalInstanceId?: string;
  approvalStatus?: string;
  createdAt: string;
  updatedAt: string;
  deletedAt?: string;            // 软删除
}

enum InstanceStatus {
  DRAFT = 'DRAFT',
  SUBMITTED = 'SUBMITTED',
  PENDING_APPROVAL = 'PENDING_APPROVAL',
  APPROVED = 'APPROVED',
  REJECTED = 'REJECTED',
  CANCELLED = 'CANCELLED',
}
```

### ViewSchema（详情视图配置）🆕

```typescript
interface ViewSchema {
  hiddenFields?: string[];       // 隐藏的字段
  groups?: {
    title: string;
    fields: string[];
    collapsed?: boolean;
  }[];
  layout?: {
    columns?: 1 | 2 | 3;
    labelPosition?: 'top' | 'left';
  };
  fieldOverrides?: {
    [fieldName: string]: {
      label?: string;
      format?: string;
      hidden?: boolean;
    };
  };
}
```

---

## 📖 接口详情

### 1. 表单定义管理

#### 1.1 获取表单列表

```
GET /api/v1/forms
```

**权限**: `form:read`

**Query 参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| category | string | 否 | 分类筛选 |
| status | FormStatus | 否 | 状态筛选 |
| search | string | 否 | 搜索关键词 |
| regionId | string | 否 | 🆕 区域筛选 |
| page | number | 否 | 页码，默认 1 |
| limit | number | 否 | 每页数量，默认 20 |

**响应**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "key": "expense_form",
        "slug": "expense-form",
        "name": "报销申请",
        "category": "FINANCE",
        "status": "PUBLISHED",
        "latestVersion": 2,
        "requiresApproval": true,
        "createdAt": "2025-01-01T00:00:00Z",
        "updatedAt": "2025-01-01T00:00:00Z"
      }
    ],
    "total": 100,
    "page": 1,
    "limit": 20,
    "totalPages": 5
  }
}
```

---

#### 1.2 获取表单详情

```
GET /api/v1/forms/:formIdentifier
```

**权限**: `form:read`

**Query 参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| locale | string | 否 | 语言代码（默认 zh-CN） |
| includeVersions | boolean | 否 | 是否包含版本列表 |

**响应**

```json
{
  "success": true,
  "data": {
    "id": "uuid",
    "key": "form_expense_001",
    "slug": "expense-reimbursement",
    "slugHistory": ["expense-form"],
    "aliases": ["报销"],
    "name": "报销申请",
    "category": "expense",
    "status": "PUBLISHED",
    "latestVersion": 3,
    "versions": [
      {
        "id": "version-id",
        "version": 3,
        "status": "PUBLISHED",
        "isDefault": true
      }
    ]
  }
}
```

---

#### 1.3 创建表单

```
POST /api/v1/forms
```

**权限**: `form:create`

**请求体**

```json
{
  "slug": "expense-form",
  "name": "报销申请",
  "category": "FINANCE",
  "description": "员工报销费用申请表",
  "icon": "💰",
  "requiresApproval": true,
  "approvalProcessKey": "expense_approval",
  "initialVersion": {
    "nameI18n": {
      "zh-CN": "报销申请",
      "en-US": "Expense Request"
    },
    "schema": {
      "type": "object",
      "properties": {
        "amount": { "type": "number", "title": "金额" },
        "reason": { "type": "string", "title": "事由" }
      },
      "required": ["amount", "reason"]
    },
    "uiSchema": {
      "reason": { "ui:widget": "textarea" }
    }
  }
}
```

**响应**

```json
{
  "success": true,
  "data": {
    "definition": {
      "id": "uuid",
      "key": "form_V1StGXR8",
      "slug": "expense-form",
      "status": "DRAFT"
    },
    "version": {
      "id": "version-uuid",
      "version": 1,
      "status": "DRAFT"
    }
  },
  "message": "表单创建成功"
}
```

---

#### 1.10 发布表单

⚠️ **重要**: 发布表单前必须有至少一个 `PUBLISHED` 且 `isDefault = true` 的版本。

```
POST /api/v1/forms/:formIdentifier/publish
```

**权限**: `form:admin`

**响应**

```json
{
  "success": true,
  "data": {
    "id": "uuid",
    "status": "PUBLISHED"
  },
  "message": "表单已发布"
}
```

**错误响应**

```json
{
  "success": false,
  "error": {
    "code": "FORM_NO_PUBLISHED_DEFAULT_VERSION",
    "message": "表单没有已发布的默认版本，请先发布至少一个版本并设为默认"
  },
  "statusCode": 400
}
```

---

### 2. 表单版本管理

#### 2.1 获取版本列表

```
GET /api/v1/forms/:formIdentifier/versions
```

**权限**: `form:read`

**Query 参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | VersionStatus | 否 | 状态筛选 |

**响应**

```json
{
  "success": true,
  "data": [
    {
      "id": "version-id",
      "version": 3,
      "nameI18n": { "zh-CN": "报销申请 V3" },
      "status": "PUBLISHED",
      "isDefault": true,
      "reviewedBy": "admin-id",
      "reviewedAt": "2025-01-01T00:00:00Z",
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ]
}
```

---

#### 2.2 获取版本详情

```
GET /api/v1/forms/:formIdentifier/versions/:version
```

**权限**: `form:read`

**Query 参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| locale | string | 否 | 语言代码 |
| includeTranslations | boolean | 否 | 是否包含翻译 |
| mode | string | 否 | 🆕 获取模式：`edit` | `readonly` | `view` |

**响应**

```json
{
  "success": true,
  "data": {
    "id": "version-id",
    "version": 3,
    "schema": {...},
    "uiSchema": {...},
    "viewSchema": {...},
    "status": "PUBLISHED",
    "reviewedBy": "admin-id",
    "reviewComment": "符合规范，审核通过"
  }
}
```

---

#### 2.5 提交审核 🆕

设计者将草稿版本提交给管理员审核。

```
POST /api/v1/forms/:formIdentifier/versions/:version/submit-review
```

**权限**: `form:design`

**请求体**

```json
{
  "comment": "请审核此版本，新增了发票上传功能"
}
```

**响应**

```json
{
  "success": true,
  "data": {
    "id": "version-id",
    "version": 2,
    "status": "PENDING_REVIEW",
    "submittedAt": "2025-01-01T00:00:00Z"
  },
  "message": "已提交审核"
}
```

**错误响应**

```json
{
  "success": false,
  "error": {
    "code": "VERSION_NOT_DRAFT",
    "message": "只有草稿状态的版本可以提交审核"
  },
  "statusCode": 400
}
```

---

#### 2.6 审核版本 🆕

管理员审核版本，可通过或驳回。

```
POST /api/v1/forms/:formIdentifier/versions/:version/review
```

**权限**: `form:admin`

**请求体 - 通过**

```json
{
  "action": "approve",
  "comment": "符合规范，审核通过",
  "setAsDefault": true
}
```

**请求体 - 驳回**

```json
{
  "action": "reject",
  "comment": "字段缺少必填验证，请补充"
}
```

**响应 - 通过**

```json
{
  "success": true,
  "data": {
    "id": "version-id",
    "version": 2,
    "status": "PUBLISHED",
    "isDefault": true,
    "reviewedBy": "admin-id",
    "reviewedAt": "2025-01-01T00:00:00Z",
    "reviewComment": "符合规范，审核通过"
  },
  "message": "版本审核通过"
}
```

**响应 - 驳回**

```json
{
  "success": true,
  "data": {
    "id": "version-id",
    "version": 2,
    "status": "REJECTED",
    "reviewedBy": "admin-id",
    "reviewedAt": "2025-01-01T00:00:00Z",
    "reviewComment": "字段缺少必填验证，请补充"
  },
  "message": "版本已驳回"
}
```

---

#### 2.7 发布版本

⚠️ **注意**: 如果版本状态为 `PENDING_REVIEW`，需要先通过审核才能发布。

```
POST /api/v1/forms/:formIdentifier/versions/:version/publish
```

**权限**: `form:version:manage` 或 `form:admin`

**请求体**

```json
{
  "setAsDefault": true
}
```

**响应**

```json
{
  "success": true,
  "data": {
    "id": "version-id",
    "version": 2,
    "status": "PUBLISHED",
    "isDefault": true,
    "publishedAt": "2025-01-01T00:00:00Z"
  },
  "message": "版本发布成功"
}
```

---

### 3. 表单实例管理

#### 3.1 创建表单实例

```
POST /api/v1/form-instances
```

**权限**: `form:instance:create`

**请求体**

```json
{
  "formIdentifier": "expense-form",
  "version": 2,
  "data": {
    "amount": 1000,
    "reason": "差旅费"
  }
}
```

**响应**

```json
{
  "success": true,
  "data": {
    "id": "instance-uuid",
    "formKey": "expense_form",
    "formVersion": 2,
    "formVersionId": "version-uuid",
    "businessKey": "expense_form_2025_0001",
    "status": "DRAFT",
    "data": {
      "amount": 1000,
      "reason": "差旅费"
    },
    "createdAt": "2025-01-01T00:00:00Z"
  },
  "message": "草稿创建成功"
}
```

---

#### 3.5 获取实例详情

```
GET /api/v1/form-instances/:instanceIdentifier
```

**权限**: `form:instance:read`

**Query 参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| locale | string | 否 | 语言代码 |
| includeForm | boolean | 否 | 是否包含表单定义 |
| mode | string | 否 | 🆕 渲染模式：`edit` | `readonly` | `view` |

**响应**

```json
{
  "success": true,
  "data": {
    "id": "instance-uuid",
    "formKey": "expense_form",
    "formVersion": 2,
    "formVersionId": "version-uuid",
    "businessKey": "expense_form_2025_0001",
    "regionId": "region-beijing",
    "data": {
      "amount": 1000,
      "reason": "差旅费"
    },
    "status": "SUBMITTED",
    "form": {
      "name": "报销申请",
      "schema": {...},
      "viewSchema": {...}
    }
  }
}
```

---

#### 3.6 提交表单实例

```
POST /api/v1/form-instances/:instanceIdentifier/submit
```

**权限**: `form:instance:create`

**请求体**

```json
{
  "data": {
    "amount": 1000,
    "reason": "差旅费",
    "date": "2025-01-01"
  },
  "comment": "请尽快审批"
}
```

**响应**

```json
{
  "success": true,
  "data": {
    "id": "instance-uuid",
    "businessKey": "expense_form_2025_0001",
    "status": "PENDING_APPROVAL",
    "submittedAt": "2025-01-01T00:00:00Z",
    "approvalInstanceId": "approval-uuid"
  },
  "message": "提交成功，已进入审批流程"
}
```

---

### 6. 版本审核管理 🆕

#### 6.1 获取待审核列表

获取所有待审核的表单版本（管理员视角）。

```
GET /api/v1/form-versions/pending-review
```

**权限**: `form:admin`

**Query 参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| category | string | 否 | 按表单分类筛选 |
| submittedBy | string | 否 | 按提交人筛选 |
| page | number | 否 | 页码 |
| limit | number | 否 | 每页数量 |

**响应**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "version-uuid",
        "version": 2,
        "status": "PENDING_REVIEW",
        "submittedAt": "2025-01-01T00:00:00Z",
        "submittedBy": {
          "id": "user-uuid",
          "name": "张三"
        },
        "form": {
          "id": "form-uuid",
          "key": "expense_form",
          "name": "报销申请",
          "category": "FINANCE"
        },
        "changelog": "新增发票上传功能"
      }
    ],
    "total": 5,
    "page": 1,
    "limit": 20
  }
}
```

---

#### 6.2 预览待审核表单

预览待审核版本的表单效果。

```
GET /api/v1/form-versions/:versionId/preview
```

**权限**: `form:admin`

**响应**

```json
{
  "success": true,
  "data": {
    "version": {
      "id": "version-uuid",
      "version": 2,
      "schema": {...},
      "uiSchema": {...},
      "changelog": "新增发票上传功能"
    },
    "form": {
      "id": "form-uuid",
      "name": "报销申请"
    },
    "translations": {
      "zh-CN": {...},
      "en-US": {...}
    },
    "previousVersion": {
      "version": 1,
      "schema": {...}
    },
    "diff": {
      "fieldsAdded": ["invoice"],
      "fieldsRemoved": [],
      "fieldsModified": []
    }
  }
}
```

---

#### 6.3 获取审核历史

获取某个表单版本的审核历史记录。

```
GET /api/v1/form-versions/:versionId/review-history
```

**权限**: `form:read`

**响应**

```json
{
  "success": true,
  "data": [
    {
      "action": "submit",
      "operator": { "id": "user-id", "name": "张三" },
      "comment": "请审核此版本",
      "timestamp": "2025-01-01T10:00:00Z"
    },
    {
      "action": "reject",
      "operator": { "id": "admin-id", "name": "管理员" },
      "comment": "字段缺少必填验证",
      "timestamp": "2025-01-01T11:00:00Z"
    },
    {
      "action": "submit",
      "operator": { "id": "user-id", "name": "张三" },
      "comment": "已补充验证规则",
      "timestamp": "2025-01-01T14:00:00Z"
    },
    {
      "action": "approve",
      "operator": { "id": "admin-id", "name": "管理员" },
      "comment": "审核通过",
      "timestamp": "2025-01-01T15:00:00Z"
    }
  ]
}
```

---

#### 6.4 我提交的审核

获取当前用户提交审核的版本列表。

```
GET /api/v1/form-versions/my-submissions
```

**权限**: `form:design`

**Query 参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | string | 否 | 筛选状态：`pending` | `approved` | `rejected` |
| page | number | 否 | 页码 |
| limit | number | 否 | 每页数量 |

**响应**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "version-uuid",
        "version": 2,
        "status": "REJECTED",
        "form": {
          "id": "form-uuid",
          "name": "报销申请"
        },
        "submittedAt": "2025-01-01T10:00:00Z",
        "reviewedAt": "2025-01-01T11:00:00Z",
        "reviewedBy": { "id": "admin-id", "name": "管理员" },
        "reviewComment": "字段缺少必填验证"
      }
    ],
    "total": 3,
    "page": 1,
    "limit": 20
  }
}
```

---

## ❌ 错误码

### 通用错误码

| 错误码 | HTTP 状态码 | 说明 |
|--------|------------|------|
| `VALIDATION_ERROR` | 400 | 请求参数验证失败 |
| `UNAUTHORIZED` | 401 | 未授权访问 |
| `FORBIDDEN` | 403 | 无权限执行操作 |
| `NOT_FOUND` | 404 | 资源不存在 |

### 表单定义相关

| 错误码 | HTTP 状态码 | 说明 |
|--------|------------|------|
| `FORM_NOT_FOUND` | 404 | 表单不存在 |
| `FORM_KEY_EXISTS` | 409 | 表单 Key 已存在 |
| `FORM_SLUG_EXISTS` | 409 | 表单 Slug 已存在 |
| `FORM_HAS_INSTANCES` | 409 | 表单已有实例，无法删除 |
| `FORM_NOT_PUBLISHED` | 400 | 表单未发布 |
| `FORM_NO_PUBLISHED_DEFAULT_VERSION` | 400 | 表单没有已发布的默认版本 |
| `FORM_NOT_AVAILABLE_IN_REGION` | 403 | 🆕 表单在当前区域不可用 |

### 表单版本相关

| 错误码 | HTTP 状态码 | 说明 |
|--------|------------|------|
| `VERSION_NOT_FOUND` | 404 | 版本不存在 |
| `VERSION_NOT_EDITABLE` | 400 | 版本不可编辑（非草稿状态） |
| `VERSION_NOT_DRAFT` | 400 | 🆕 只有草稿状态可提交审核 |
| `VERSION_NOT_PENDING_REVIEW` | 400 | 🆕 只有待审核状态可审核 |
| `VERSION_ALREADY_PUBLISHED` | 400 | 版本已发布 |

### 表单实例相关

| 错误码 | HTTP 状态码 | 说明 |
|--------|------------|------|
| `INSTANCE_NOT_FOUND` | 404 | 实例不存在 |
| `INSTANCE_NOT_EDITABLE` | 400 | 实例不可编辑 |
| `INSTANCE_VERSION_MISMATCH` | 400 | 🆕 版本不匹配 |
| `FORM_DATA_VALIDATION_FAILED` | 400 | 表单数据验证失败 |
| `DUPLICATE_BUSINESS_KEY` | 409 | 🆕 业务单号重复 |

---

## 🔄 业务规则

### 版本状态流转

```
DRAFT ──提交审核──> PENDING_REVIEW ──审核通过──> PUBLISHED
                         │
                         └──审核驳回──> REJECTED ──修改后重新提交──> PENDING_REVIEW
```

### "发布版本" vs "发布表单"

| 操作 | API | 影响 | 说明 |
|------|-----|------|------|
| 发布版本 | `POST /versions/:v/publish` | `FormVersion.status` | 使版本可用 |
| 发布表单 | `POST /forms/:id/publish` | `FormDefinition.status` | 使表单对用户可见 |

**发布顺序**:
1. 版本审核通过 → `PUBLISHED`
2. 设为默认版本 → `isDefault = true`
3. 发布表单 → 用户可见

### FormInstance.formVersionId 不可变性

> ⚠️ **重要**: `FormInstance` 一旦创建，`formVersionId` 不可变。

- 历史数据永远按**当时所用的版本**渲染和校验
- 不随最新 Schema 变化
- 满足审计合规要求

### 业务单号（businessKey）

- 格式：`{formKey}_{year}_{sequence}`
- 示例：`expense_form_2025_0001`
- 后端自动生成，保证唯一性
- 用于审批系统关联、业务系统查询

---

## 🎯 常用场景

### 场景 1: 创建并发布表单（含审核）

```
1. POST /forms                                    # 创建表单 (DRAFT)
2. PATCH /forms/:id/versions/1                    # 设计表单
3. POST /forms/:id/versions/1/submit-review       # 提交审核
4. POST /forms/:id/versions/1/review              # 管理员审核通过
5. POST /forms/:id/publish                        # 发布表单
```

### 场景 2: 用户填写并提交表单

```
1. GET /forms/:identifier                         # 获取表单信息
2. GET /forms/:id/versions/:version               # 获取版本 Schema
3. POST /form-instances                           # 创建草稿
4. PATCH /form-instances/:id                      # 更新草稿
5. POST /form-instances/:id/submit                # 提交
```

### 场景 3: 查看历史记录（只读模式）

```
1. GET /form-instances/:id?mode=readonly          # 获取实例详情
   # 响应中包含 viewSchema，前端按只读模式渲染
```

### 场景 4: 管理员审核表单版本

```
1. GET /form-versions/pending-review              # 查看待审核列表
2. GET /form-versions/:id/preview                 # 预览表单
3. POST /forms/:formId/versions/:v/review         # 审核（通过/驳回）
```

---

## 📚 相关文档

- [PRD 需求文档](PRD.md)
- [架构设计文档](ARCHITECTURE.md)
- [开发待办](TODO.md)
- [变更记录](CHANGELOG.md)

---

**创建日期**: 2025-11-20  
**最后更新**: 2025-12-05  
**版本**: v2.0