temp

2025-07-20 20:53:26 +08:00
parent 83bf9aea7d
commit 8ad1d7288e
158 changed files with 18156 additions and 13188 deletions
--- a/docs/认证流程API说明.md
+++ b/docs/认证流程API说明.md
@@ -0,0 +1,276 @@
+# 认证流程API说明
+
+## 概述
+
+认证流程已简化为6个主要状态，系统会自动处理认证申请的创建和完成，用户无需手动调用相关接口。
+
+## 认证状态
+
+1. **待认证** (`pending`) - 用户尚未开始认证流程
+2. **已提交企业信息** (`info_submitted`) - 用户已提交企业信息
+3. **已企业认证** (`enterprise_verified`) - 企业信息已通过认证
+4. **已申请合同** (`contract_applied`) - 已申请e签宝生成合同
+5. **已签署合同** (`contract_signed`) - 合同已签署完成
+6. **认证完成** (`completed`) - 认证流程全部完成
+
+## API接口
+
+### 1. 获取认证状态
+```
+GET /api/certification/status
+```
+获取当前用户的认证状态信息。
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "获取认证状态成功",
+  "data": {
+    "id": "cert_123",
+    "user_id": "user_456",
+    "status": "info_submitted",
+    "status_name": "已提交企业信息",
+    "progress": 33,
+    "is_user_action_required": false,
+    "info_submitted_at": "2024-01-01T10:00:00Z",
+    "enterprise_verified_at": null,
+    "contract_applied_at": null,
+    "contract_signed_at": null,
+    "completed_at": null,
+    "contract_url": "",
+    "created_at": "2024-01-01T09:00:00Z",
+    "updated_at": "2024-01-01T10:00:00Z"
+  }
+}
+```
+
+### 2. 获取认证详情
+```
+GET /api/certification/details
+```
+获取当前用户的详细认证信息，包括企业信息。
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "获取认证详情成功",
+  "data": {
+    "id": "cert_123",
+    "user_id": "user_456",
+    "status": "enterprise_verified",
+    "status_name": "已企业认证",
+    "progress": 66,
+    "is_user_action_required": true,
+    "info_submitted_at": "2024-01-01T10:00:00Z",
+    "enterprise_verified_at": "2024-01-01T11:00:00Z",
+    "contract_applied_at": null,
+    "contract_signed_at": null,
+    "completed_at": null,
+    "contract_url": "",
+    "created_at": "2024-01-01T09:00:00Z",
+    "updated_at": "2024-01-01T11:00:00Z",
+    "enterprise": {
+      "id": "ent_789",
+      "company_name": "示例企业有限公司",
+      "unified_social_code": "91110000123456789X",
+      "legal_person_name": "张三",
+      "legal_person_id": "110101199001011234",
+      "is_ocr_verified": true,
+      "is_face_verified": true,
+      "created_at": "2024-01-01T10:00:00Z",
+      "updated_at": "2024-01-01T10:00:00Z"
+    }
+  }
+}
+```
+
+### 3. 获取认证进度
+```
+GET /api/certification/progress
+```
+获取当前用户的认证进度信息。
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "获取认证进度成功",
+  "data": {
+    "certification_id": "cert_123",
+    "user_id": "user_456",
+    "current_status": "contract_signed",
+    "status_name": "已签署合同",
+    "progress_percentage": 100,
+    "is_user_action_required": false,
+    "next_valid_statuses": ["completed"],
+    "message": "合同签署完成，认证流程结束",
+    "created_at": "2024-01-01T09:00:00Z",
+    "updated_at": "2024-01-01T12:00:00Z"
+  }
+}
+```
+
+### 4. 提交企业信息
+```
+POST /api/certification/submit-enterprise-info
+```
+提交企业信息。如果用户没有认证申请，系统会自动创建。
+
+**请求参数：**
+```json
+{
+  "company_name": "示例企业有限公司",
+  "unified_social_code": "91110000123456789X",
+  "legal_person_name": "张三",
+  "legal_person_id": "110101199001011234"
+}
+```
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "企业信息提交成功",
+  "data": {
+    "id": "ent_789",
+    "company_name": "示例企业有限公司",
+    "unified_social_code": "91110000123456789X",
+    "legal_person_name": "张三",
+    "legal_person_id": "110101199001011234",
+    "is_ocr_verified": false,
+    "is_face_verified": false,
+    "created_at": "2024-01-01T10:00:00Z",
+    "updated_at": "2024-01-01T10:00:00Z"
+  }
+}
+```
+
+### 5. 企业认证
+```
+POST /api/certification/enterprise-verify
+```
+执行企业认证流程。
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "企业认证成功",
+  "data": {
+    "id": "cert_123",
+    "user_id": "user_456",
+    "status": "enterprise_verified",
+    "status_name": "已企业认证",
+    "progress": 66,
+    "is_user_action_required": true,
+    "info_submitted_at": "2024-01-01T10:00:00Z",
+    "enterprise_verified_at": "2024-01-01T11:00:00Z",
+    "contract_applied_at": null,
+    "contract_signed_at": null,
+    "completed_at": null,
+    "contract_url": "",
+    "created_at": "2024-01-01T09:00:00Z",
+    "updated_at": "2024-01-01T11:00:00Z"
+  }
+}
+```
+
+### 6. 申请合同
+```
+POST /api/certification/apply-contract
+```
+申请e签宝生成合同文件。
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "合同申请成功",
+  "data": {
+    "id": "cert_123",
+    "user_id": "user_456",
+    "status": "contract_applied",
+    "status_name": "已申请合同",
+    "progress": 83,
+    "is_user_action_required": true,
+    "info_submitted_at": "2024-01-01T10:00:00Z",
+    "enterprise_verified_at": "2024-01-01T11:00:00Z",
+    "contract_applied_at": "2024-01-01T12:00:00Z",
+    "contract_signed_at": null,
+    "completed_at": null,
+    "contract_url": "",
+    "created_at": "2024-01-01T09:00:00Z",
+    "updated_at": "2024-01-01T12:00:00Z"
+  }
+}
+```
+
+### 7. 完成合同签署
+```
+POST /api/certification/complete-contract-sign
+```
+完成合同签署。系统会自动判断是否完成认证。
+
+**请求参数：**
+```json
+{
+  "contract_url": "https://esign.example.com/contract/123"
+}
+```
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "合同签署完成",
+  "data": null
+}
+```
+
+## 流程说明
+
+### 自动处理逻辑
+
+1. **自动创建认证申请**：当用户首次提交企业信息时，如果用户没有认证申请，系统会自动创建一个认证申请。
+
+2. **自动完成认证**：当合同签署完成后，系统会自动将认证状态更新为"认证完成"。
+
+3. **企业信息创建**：企业信息在企业认证成功时自动创建，用户无需手动创建。
+
+### 状态转换规则
+
+- **待认证** → **已提交企业信息**：提交企业信息
+- **已提交企业信息** → **已企业认证**：企业认证成功
+- **已企业认证** → **已申请合同**：申请合同
+- **已申请合同** → **已签署合同**：合同签署完成
+- **已签署合同** → **认证完成**：自动完成
+
+### 进度百分比
+
+- 待认证：0%
+- 已提交企业信息：33%
+- 已企业认证：66%
+- 已申请合同：83%
+- 已签署合同：100%
+- 认证完成：100%
+
+## 错误处理
+
+所有接口都会返回统一的错误格式：
+
+```json
+{
+  "code": 400,
+  "message": "错误描述信息",
+  "data": null
+}
+```
+
+常见错误：
+- `用户未登录`：JWT token无效或过期
+- `用户已有企业信息`：用户已存在企业信息
+- `统一社会信用代码已存在`：该企业已被其他用户认证
+- `当前状态不允许企业认证`：状态转换不合法
+- `用户尚未创建认证申请`：用户没有认证申请（通常不会出现，因为会自动创建）