# 企业认证接口文档

## 概述

企业认证模块支持企业提交认证材料，管理员审核通过或拒绝。认证状态包括 PENDING、APPROVED、REJECTED、RESUBMITTED。

## 认证状态枚举

| 状态 | 说明 |
|------|------|
| PENDING | 待审核 |
| APPROVED | 已通过（终态） |
| REJECTED | 已拒绝 |
| RESUBMITTED | 重新提交（待审核） |

## 状态流转规则

```
PENDING ──> APPROVED (终态)
PENDING ──> REJECTED
REJECTED ──> RESUBMITTED ──> PENDING（重新进入审核）
```

APPROVED 为终态，不可再流转。

---

## 接口列表

### 1. 企业提交认证

**请求方法**: `POST /companies/me/verification`

**请求头**:
```
Authorization: Bearer {jwt}
Content-Type: application/json
```

**请求体**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| materialsJson | String | 是 | 认证材料 JSON（营业执照URL等） |

**成功响应** (200):
```json
{
  "code": 1000,
  "message": "success",
  "data": {
    "id": 1,
    "companyId": 10,
    "status": "PENDING",
    "submittedBy": 1,
    "materialsJson": "{\"license\":\"url\"}",
    "submittedAt": "2026-08-13T10:00:00",
    "version": 0
  }
}
```

**错误响应**:
| 状态码 | 错误码 | 说明 |
|--------|--------|------|
| 400 | 1001 | 缺少 materialsJson |
| 403 | 2002 | 非 COMPANY 角色 |
| 409 | 8502 | 已有待审核的认证申请 |
| 409 | 8503 | 已通过认证，不可重复提交 |

**权限规则**: 仅 COMPANY 角色可调用，企业身份从 JWT 获取。

---

### 2. 企业查询认证状态

**请求方法**: `GET /companies/me/verification`

**请求头**:
```
Authorization: Bearer {jwt}
```

**成功响应** (200):
```json
{
  "code": 1000,
  "message": "success",
  "data": {
    "id": 1,
    "companyId": 10,
    "status": "APPROVED",
    "submittedBy": 1,
    "reviewerId": 100,
    "decisionReason": "材料齐全",
    "submittedAt": "2026-08-13T10:00:00",
    "decidedAt": "2026-08-13T11:00:00",
    "version": 1
  }
}
```

**错误响应**:
| 状态码 | 错误码 | 说明 |
|--------|--------|------|
| 403 | 2002 | 非 COMPANY 角色 |
| 404 | 8501 | 未提交过认证 |

**权限规则**: 仅 COMPANY 角色可调用，只能查看自己的认证。

---

### 3. 管理员查询认证列表

**请求方法**: `GET /admin/companies/verifications`

**请求头**:
```
Authorization: Bearer {jwt}
```

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | String | 否 | 按状态筛选 (PENDING/APPROVED/REJECTED/RESUBMITTED) |
| from | ISO DateTime | 否 | 提交时间起始 |
| to | ISO DateTime | 否 | 提交时间截止 |
| page | int | 否 | 页码（默认 0） |
| size | int | 否 | 每页条数（默认 20，最大 100） |

**成功响应** (200):
```json
{
  "code": 1000,
  "message": "success",
  "data": {
    "items": [],
    "total": 0,
    "page": 0,
    "size": 20,
    "totalPages": 0
  }
}
```

**错误响应**:
| 状态码 | 错误码 | 说明 |
|--------|--------|------|
| 403 | 2002 | 非 ADMIN 角色 |

**权限规则**: 仅 ADMIN 角色可调用。

---

### 4. 管理员查看认证详情

**请求方法**: `GET /admin/companies/verifications/{id}`

**请求头**:
```
Authorization: Bearer {jwt}
```

**成功响应** (200):
```json
{
  "code": 1000,
  "message": "success",
  "data": {
    "id": 1,
    "companyId": 10,
    "status": "PENDING",
    "submittedBy": 1,
    "materialsJson": "{\"license\":\"url\"}",
    "submittedAt": "2026-08-13T10:00:00"
  }
}
```

**错误响应**:
| 状态码 | 错误码 | 说明 |
|--------|--------|------|
| 403 | 2002 | 非 ADMIN 角色 |
| 404 | 8501 | 认证记录不存在 |

**权限规则**: 仅 ADMIN 角色可调用。

---

### 5. 管理员审核决定

**请求方法**: `POST /admin/companies/verifications/{id}/decision`

**请求头**:
```
Authorization: Bearer {jwt}
Content-Type: application/json
```

**请求体**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| decision | String | 是 | APPROVED 或 REJECTED |
| reason | String | 条件必填 | REJECTED 时必须填写原因 |

**成功响应** (200):
```json
{
  "code": 1000,
  "message": "success",
  "data": {
    "id": 1,
    "companyId": 10,
    "status": "APPROVED",
    "reviewerId": 100,
    "decisionReason": "材料齐全",
    "decidedAt": "2026-08-13T11:00:00",
    "version": 1
  }
}
```

**错误响应**:
| 状态码 | 错误码 | 说明 |
|--------|--------|------|
| 400 | 1001 | decision 无效（非 APPROVED/REJECTED） |
| 400 | 8505 | REJECTED 时缺少原因 |
| 403 | 2002 | 非 ADMIN 角色 |
| 404 | 8501 | 认证记录不存在 |
| 409 | 8503 | 已通过，不可重复审核 |
| 409 | 8504 | 非法状态流转 |

**权限规则**: 仅 ADMIN 角色可调用。审查结果发送通知给企业。

**幂等规则**: 相同状态重复调用返回 200（幂等返回），但已 APPROVED 状态不可重复审核（返回 409）。

---

### 6. 审核历史

**请求方法**: `GET /admin/companies/verifications/history`

**请求头**:
```
Authorization: Bearer {jwt}
```

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| verificationId | Long | 是 | 认证记录 ID |

**成功响应** (200):
```json
{
  "code": 1000,
  "message": "success",
  "data": [
    {
      "id": 1,
      "fromStatus": null,
      "toStatus": "PENDING",
      "actorUserId": 1,
      "reason": "企业提交认证材料",
      "createdAt": "2026-08-13T10:00:00"
    }
  ]
}
```

**错误响应**:
| 状态码 | 错误码 | 说明 |
|--------|--------|------|
| 403 | 2002 | 非 ADMIN 角色 |

**权限规则**: 仅 ADMIN 角色可调用。

---

## 权限规则总结

| 角色 | 接口 | 权限 |
|------|------|------|
| COMPANY | `/companies/me/verification` (POST/GET) | 允许 |
| STUDENT | `/companies/me/verification` (POST/GET) | 403 |
| ADMIN | `/admin/companies/verifications/**` | 允许 |
| COMPANY | `/admin/companies/verifications/**` | 403 |
| STUDENT | `/admin/companies/verifications/**` | 403 |

## 时间字段和时区

所有时间字段使用 ISO 8601 格式，时区为系统默认（Asia/Shanghai）。

## 审计日志

所有操作（提交、审核决定）均写入审计日志，包含操作用户、操作类型、IP 地址、User-Agent 等上下文信息。