qingsongping-AIDevelop/docs/company-verification-api.md

企业认证接口文档

概述

企业认证模块支持企业提交认证材料，管理员审核通过或拒绝。认证状态包括 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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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 等上下文信息。