tyapi-server/docs/认证流程API说明.md

# 认证流程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无效或过期
- `用户已有企业信息`：用户已存在企业信息
- `统一社会信用代码已存在`：该企业已被其他用户认证
- `当前状态不允许企业认证`：状态转换不合法
- `用户尚未创建认证申请`：用户没有认证申请（通常不会出现，因为会自动创建）