leaudit-platform-frontend/auth_doc/评查审核接口对接文档.md

# 评查审核接口对接文档

> 版本：v1.0
> 更新时间：2024-12-10
> 模块：评查审核（Evaluation Audit）

---

## 一、接口总览

| 序号 | 接口名称     | 方法      | 路径                                            | 功能说明                     |
| ---- | ------------ | --------- | ----------------------------------------------- | ---------------------------- |
| 1    | 更新评查结果 | `PATCH` | `/admin/v2/evaluation/results/{result_id}`    | 修改评查结果的通过状态和说明 |
| 2    | 创建审核状态 | `POST`  | `/admin/v2/evaluation/audit-status`           | 记录人工审核操作             |
| 3    | 更新审核状态 | `PATCH` | `/admin/v2/evaluation/audit-status/{id}`      | 更新已有的审核状态记录       |
| 4    | 确认文档审核 | `PATCH` | `/admin/v2/evaluation/documents/{id}/confirm` | 确认文档整体审核完成         |

---

## 二、通用说明

### 2.1 请求头

所有接口都需要携带 JWT Token：

```http
Authorization: Bearer <your_jwt_token>
Content-Type: application/json
```

### 2.2 基础路径

```
开发环境: http://localhost:8000
生产环境: https://your-domain.com
```

### 2.3 通用响应格式

**成功响应**：

```json
{
    "success": true,
    "message": "操作成功",
    "data": { ... }
}
```

**错误响应**：

```json
{
    "detail": "错误信息"
}
```

### 2.4 HTTP 状态码

| 状态码 | 说明           |
| ------ | -------------- |
| 200    | 请求成功       |
| 400    | 请求参数错误   |
| 403    | 无权限访问     |
| 404    | 资源不存在     |
| 500    | 服务器内部错误 |

---

## 三、接口详细说明

---

### 3.1 更新评查结果

**功能说明**：人工审核时，修改某个评查点的评查结果（通过/不通过）和说明信息。

#### 请求信息

| 项目     | 说明                                          |
| -------- | --------------------------------------------- |
| 请求路径 | `/admin/v2/evaluations/results/{result_id}` |
| 请求方法 | `PATCH`                                     |
| 权限要求 | 用户必须对该文档有访问权限                    |

#### 路径参数

| 参数名    | 类型    | 必填 | 说明                                      |
| --------- | ------- | ---- | ----------------------------------------- |
| result_id | integer | 是   | 评查结果ID（evaluation_results 表的主键） |

#### 请求体参数

| 参数名      | 类型   | 必填 | 说明                                      |
| ----------- | ------ | ---- | ----------------------------------------- |
| result      | string | 否   | 评查结果，可选值：`"pass"` / `"fail"` |
| message     | string | 否   | 评查结果说明（人工审核备注）              |
| final_score | float  | 否   | 最终分数（人工修正后的分数）              |

#### 请求示例

```http
PATCH /admin/v2/evaluation/results/123
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
    "result": "pass",
    "message": "经人工审核，该评查点符合要求",
    "final_score": 100.0
}
```

#### 响应示例

**成功响应** (200)：

```json
{
    "success": true,
    "message": "评查结果更新成功",
    "data": {
        "result_id": 123,
        "updated_fields": ["evaluated_results", "final_score"]
    }
}
```

**错误响应** (404)：

```json
{
    "detail": "评查结果 123 不存在"
}
```

**错误响应** (403)：

```json
{
    "detail": "无权修改此评查结果"
}
```

#### 业务逻辑

```
1. 接收请求，验证 JWT Token
2. 根据 result_id 查询 evaluation_results 表
3. 获取该评查结果关联的 document_id
4. 验证当前用户是否有权限访问该文档：
   - 是文档上传者
   - 或是交叉评查任务的参与者
5. 更新 evaluation_results 表：
   - evaluated_results.result = 请求的 result
   - evaluated_results.message = 请求的 message
   - final_score = 请求的 final_score
6. 返回更新结果
```

#### 数据库变更

更新 `evaluation_results` 表：

- `evaluated_results` (JSONB): 更新其中的 `result` 和 `message` 字段
- `final_score` (float): 更新最终分数

---

### 3.2 创建审核状态

**功能说明**：记录用户对某个评查点的人工审核操作，用于追踪审核历史。

#### 请求信息

| 项目     | 说明                                   |
| -------- | -------------------------------------- |
| 请求路径 | `/admin/v2/evaluations/audit-status` |
| 请求方法 | `POST`                               |
| 权限要求 | 用户必须对该文档有访问权限             |

#### 请求体参数

| 参数名               | 类型    | 必填 | 说明                                 |
| -------------------- | ------- | ---- | ------------------------------------ |
| document_id          | integer | 是   | 文档ID                               |
| evaluation_point_id  | integer | 是   | 评查点ID                             |
| evaluation_result_id | integer | 是   | 评查结果ID                           |
| edit_audit_status    | integer | 是   | 审核状态：`0`=未审核，`1`=已审核 |
| message              | string  | 否   | 操作记录文本（最大255字符）          |

#### 请求示例

```http
POST /admin/v2/evaluation/audit-status
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
    "document_id": 456,
    "evaluation_point_id": 789,
    "evaluation_result_id": 123,
    "edit_audit_status": 1,
    "message": "已完成人工审核，确认通过"
}
```

#### 响应示例

**成功响应** (200)：

```json
{
    "id": 1,
    "user_id": 10,
    "document_id": 456,
    "evaluation_point_id": 789,
    "evaluation_result_id": 123,
    "edit_audit_status": 1,
    "message": "已完成人工审核，确认通过",
    "created_at": "2024-12-10T10:30:00+08:00",
    "updated_at": "2024-12-10T10:30:00+08:00"
}
```

**错误响应** (403)：

```json
{
    "detail": "无权操作此文档的审核状态"
}
```

#### 业务逻辑

```
1. 接收请求，验证 JWT Token
2. 验证当前用户是否有权限访问 document_id 对应的文档
3. 在 audit_status 表中插入新记录：
   - user_id = 当前登录用户ID（自动填充）
   - document_id = 请求的 document_id
   - evaluation_point_id = 请求的 evaluation_point_id
   - evaluation_result_id = 请求的 evaluation_result_id
   - edit_audit_status = 请求的 edit_audit_status
   - message = 请求的 message
4. 返回创建的记录
```

#### 数据库变更

在 `audit_status` 表中插入新记录

#### 前端使用场景

当用户点击"通过"或"不通过"按钮时：

1. 先调用 **3.1 更新评查结果** 更新结果
2. 再调用 **3.2 创建审核状态** 记录操作

---

### 3.3 更新审核状态

**功能说明**：更新已有的审核状态记录，用于"重新审核"等场景。

#### 请求信息

| 项目     | 说明                                                     |
| -------- | -------------------------------------------------------- |
| 请求路径 | `/admin/v2/evaluations/audit-status/{audit_status_id}` |
| 请求方法 | `PATCH`                                                |
| 权限要求 | 用户必须是该记录的创建者，或对关联文档有访问权限         |

#### 路径参数

| 参数名          | 类型    | 必填 | 说明                                |
| --------------- | ------- | ---- | ----------------------------------- |
| audit_status_id | integer | 是   | 审核状态ID（audit_status 表的主键） |

#### 请求体参数

| 参数名            | 类型    | 必填 | 说明                                 |
| ----------------- | ------- | ---- | ------------------------------------ |
| edit_audit_status | integer | 否   | 审核状态：`0`=未审核，`1`=已审核 |
| message           | string  | 否   | 操作记录文本（最大255字符）          |

#### 请求示例

```http
PATCH /admin/v2/evaluation/audit-status/1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
    "edit_audit_status": 1,
    "message": "重新审核后确认通过"
}
```

#### 响应示例

**成功响应** (200)：

```json
{
    "success": true,
    "message": "审核状态更新成功",
    "data": {
        "audit_status_id": 1,
        "updated_fields": ["edit_audit_status", "message"]
    }
}
```

**错误响应** (404)：

```json
{
    "detail": "审核状态记录 1 不存在"
}
```

#### 业务逻辑

```
1. 接收请求，验证 JWT Token
2. 根据 audit_status_id 查询 audit_status 表
3. 验证权限：
   - 如果是自己创建的记录，允许更新
   - 如果不是自己的记录，检查是否有关联文档的访问权限
4. 更新 audit_status 表对应记录
5. 返回更新结果
```

#### 数据库变更

更新 `audit_status` 表：

- `edit_audit_status`: 审核状态
- `message`: 操作记录
- `updated_at`: 自动更新（数据库触发器）

---

### 3.4 确认文档审核完成

**功能说明**：确认整个文档的审核完成，更新文档的审核状态字段。

#### 请求信息

| 项目     | 说明                                                      |
| -------- | --------------------------------------------------------- |
| 请求路径 | `/admin/v2/evaluations/documents/{document_id}/confirm` |
| 请求方法 | `PATCH`                                                 |
| 权限要求 | 用户必须对该文档有访问权限                                |

#### 路径参数

| 参数名      | 类型    | 必填 | 说明   |
| ----------- | ------- | ---- | ------ |
| document_id | integer | 是   | 文档ID |

#### 请求体参数

| 参数名       | 类型    | 必填 | 默认值 | 说明                     |
| ------------ | ------- | ---- | ------ | ------------------------ |
| audit_status | integer | 否   | 1      | 审核状态：`1`=审核完成 |

#### 请求示例

```http
PATCH /admin/v2/evaluation/documents/456/confirm
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
    "audit_status": 1
}
```

或者使用默认值（不传请求体）：

```http
PATCH /admin/v2/evaluation/documents/456/confirm
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{}
```

#### 响应示例

**成功响应** (200)：

```json
{
    "success": true,
    "message": "文档审核确认成功",
    "data": {
        "document_id": 456,
        "audit_status": 1
    }
}
```

**错误响应** (403)：

```json
{
    "detail": "无权确认此文档的审核状态"
}
```

#### 业务逻辑

```
1. 接收请求，验证 JWT Token
2. 验证当前用户是否有权限访问 document_id 对应的文档
3. 更新 documents 表的 audit_status 字段
4. 返回更新结果
```

#### 数据库变更

更新 `documents` 表：

- `audit_status`: 设置为 1（审核完成）

---

## 四、完整业务流程

### 4.1 人工审核单个评查点

```mermaid
sequenceDiagram
    participant 前端
    participant 后端
    participant 数据库

    前端->>后端: PATCH /results/{id} (修改评查结果)
    后端->>数据库: 验证权限
    后端->>数据库: 更新 evaluation_results
    后端-->>前端: 返回成功

    前端->>后端: POST /audit-status (记录审核操作)
    后端->>数据库: 插入 audit_status
    后端-->>前端: 返回创建的记录
```

### 4.2 确认文档整体审核完成

```mermaid
sequenceDiagram
    participant 前端
    participant 后端
    participant 数据库

    Note over 前端: 用户完成所有评查点审核后
    前端->>后端: PATCH /documents/{id}/confirm
    后端->>数据库: 验证权限
    后端->>数据库: 更新 documents.audit_status = 1
    后端-->>前端: 返回成功
```

### 4.3 前端调用示例（TypeScript/Axios）

```typescript
import axios from 'axios';

const API_BASE = '/admin/v2/evaluation';

// 获取 JWT Token
const getToken = () => localStorage.getItem('token');

// 创建 axios 实例
const api = axios.create({
    headers: {
        'Content-Type': 'application/json',
    },
});

// 添加请求拦截器
api.interceptors.request.use((config) => {
    const token = getToken();
    if (token) {
        config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
});

/**
 * 更新评查结果
 * @param resultId 评查结果ID
 * @param data 更新数据
 */
export async function updateEvaluationResult(
    resultId: number,
    data: {
        result?: 'pass' | 'fail';
        message?: string;
        final_score?: number;
    }
) {
    const response = await api.patch(`${API_BASE}/results/${resultId}`, data);
    return response.data;
}

/**
 * 创建审核状态记录
 * @param data 审核状态数据
 */
export async function createAuditStatus(data: {
    document_id: number;
    evaluation_point_id: number;
    evaluation_result_id: number;
    edit_audit_status: 0 | 1;
    message?: string;
}) {
    const response = await api.post(`${API_BASE}/audit-status`, data);
    return response.data;
}

/**
 * 更新审核状态记录
 * @param auditStatusId 审核状态ID
 * @param data 更新数据
 */
export async function updateAuditStatus(
    auditStatusId: number,
    data: {
        edit_audit_status?: 0 | 1;
        message?: string;
    }
) {
    const response = await api.patch(`${API_BASE}/audit-status/${auditStatusId}`, data);
    return response.data;
}

/**
 * 确认文档审核完成
 * @param documentId 文档ID
 */
export async function confirmDocumentReview(documentId: number) {
    const response = await api.patch(`${API_BASE}/documents/${documentId}/confirm`, {
        audit_status: 1,
    });
    return response.data;
}

// ============================================
// 业务场景示例
// ============================================

/**
 * 场景1：用户点击"通过"按钮
 */
async function handlePassClick(
    documentId: number,
    evaluationPointId: number,
    evaluationResultId: number
) {
    try {
        // 1. 更新评查结果为"通过"
        await updateEvaluationResult(evaluationResultId, {
            result: 'pass',
            message: '人工审核通过',
            final_score: 100,
        });

        // 2. 记录审核操作
        await createAuditStatus({
            document_id: documentId,
            evaluation_point_id: evaluationPointId,
            evaluation_result_id: evaluationResultId,
            edit_audit_status: 1,
            message: '用户确认通过',
        });

        console.log('审核成功');
    } catch (error) {
        console.error('审核失败:', error);
    }
}

/**
 * 场景2：用户点击"不通过"按钮
 */
async function handleFailClick(
    documentId: number,
    evaluationPointId: number,
    evaluationResultId: number,
    reason: string
) {
    try {
        // 1. 更新评查结果为"不通过"
        await updateEvaluationResult(evaluationResultId, {
            result: 'fail',
            message: reason,
            final_score: 0,
        });

        // 2. 记录审核操作
        await createAuditStatus({
            document_id: documentId,
            evaluation_point_id: evaluationPointId,
            evaluation_result_id: evaluationResultId,
            edit_audit_status: 1,
            message: `用户确认不通过: ${reason}`,
        });

        console.log('审核成功');
    } catch (error) {
        console.error('审核失败:', error);
    }
}

/**
 * 场景3：用户完成所有评查点审核，点击"确认完成"
 */
async function handleConfirmAllClick(documentId: number) {
    try {
        await confirmDocumentReview(documentId);
        console.log('文档审核确认成功');
    } catch (error) {
        console.error('确认失败:', error);
    }
}
```

---

## 五、数据库表结构参考

### 5.1 evaluation_results 表

| 字段名                      | 类型            | 说明                                         |
| --------------------------- | --------------- | -------------------------------------------- |
| id                          | integer         | 主键                                         |
| document_id                 | integer         | 文档ID                                       |
| evaluation_point_id         | integer         | 评查点ID                                     |
| status                      | varchar(20)     | 状态                                         |
| extracted_results           | jsonb           | 抽取结果                                     |
| rules_results               | jsonb           | 规则判断结果                                 |
| **evaluated_results** | **jsonb** | **评查结果（包含 result 和 message）** |
| **final_score**       | **float** | **最终分数**                           |
| machine_score               | float           | 机器评查分数                                 |
| created_at                  | timestamp       | 创建时间                                     |
| updated_at                  | timestamp       | 更新时间                                     |

**evaluated_results 字段结构**：

```json
{
    "result": "pass",      // 评查结果：pass/fail
    "message": "说明信息"   // 评查结果说明
}
```

### 5.2 audit_status 表

| 字段名                      | 类型                   | 说明                               |
| --------------------------- | ---------------------- | ---------------------------------- |
| id                          | integer                | 主键                               |
| user_id                     | integer                | 操作用户ID                         |
| document_id                 | integer                | 文档ID                             |
| evaluation_point_id         | integer                | 评查点ID                           |
| evaluation_result_id        | integer                | 评查结果ID                         |
| **edit_audit_status** | **integer**      | **审核状态（0=未审核，1=已审核）** |
| **message**           | **varchar(255)** | **操作记录文本**             |
| created_at                  | timestamp              | 创建时间                           |
| updated_at                  | timestamp              | 更新时间                           |

### 5.3 documents 表（相关字段）

| 字段名                 | 类型              | 说明                               |
| ---------------------- | ----------------- | ---------------------------------- |
| id                     | integer           | 主键                               |
| **audit_status** | **integer** | **审核状态（0=待审核，1=已完成）** |
| ...                    | ...               | 其他字段省略                       |

---

## 六、错误处理

### 6.1 常见错误码

| HTTP 状态码 | detail 示例             | 原因               | 解决方案                                 |
| ----------- | ----------------------- | ------------------ | ---------------------------------------- |
| 403         | "无权修改此评查结果"    | 用户无权访问该文档 | 检查用户是否是文档上传者或交叉评查参与者 |
| 404         | "评查结果 123 不存在"   | 评查结果ID不存在   | 检查传入的 result_id 是否正确            |
| 404         | "审核状态记录 1 不存在" | 审核状态ID不存在   | 检查传入的 audit_status_id 是否正确      |
| 422         | "field required"        | 缺少必填字段       | 检查请求体是否包含所有必填字段           |
| 500         | "更新评查结果失败: ..." | 服务器内部错误     | 查看服务器日志排查问题                   |

### 6.2 前端错误处理示例

```typescript
try {
    await updateEvaluationResult(resultId, data);
} catch (error) {
    if (axios.isAxiosError(error)) {
        const status = error.response?.status;
        const detail = error.response?.data?.detail;

        switch (status) {
            case 403:
                alert('您没有权限执行此操作');
                break;
            case 404:
                alert('记录不存在，请刷新页面后重试');
                break;
            case 422:
                alert('请求参数错误，请检查输入');
                break;
            default:
                alert(`操作失败: ${detail || '未知错误'}`);
        }
    }
}
```

---

## 七、注意事项

1. **权限验证**：所有接口都会验证用户对文档的访问权限，前端无需额外处理权限逻辑
2. **字段更新**：PATCH 接口只更新传入的字段，未传入的字段保持不变
3. **操作顺序**：建议先调用"更新评查结果"，再调用"创建审核状态"
4. **审核状态值**：
   - `edit_audit_status = 0`：未审核（按钮显示"通过/不通过"）
   - `edit_audit_status = 1`：已审核（按钮显示"重新审核"）
5. **文档 audit_status**：
   - `audit_status = 0`：待人工确认
   - `audit_status = 1`：审核完成

---

## 八、联系方式

如有问题，请联系后端开发人员。