leaudit-platform-frontend/auth_doc/API接口详细文档(1).md

# 版本管理V3 - API接口详细文档

## 📋 概述

版本管理V3提供了完整的文档版本管理功能，支持版本列表查询、版本对比、评查统计等核心能力。

**基础URL**: `/admin/versions`

**设计理念**:
- ✅ RESTful规范
- ✅ 统一响应格式
- ✅ LLM可选（默认关闭，按需启用）
- ✅ 权限验证（JWT Token）
- ✅ 文档类型无关（通过table_name参数支持不同实体）

---

## 🔐 认证方式

所有接口均需要在请求头中携带JWT Token：

```http
Authorization: Bearer <your-jwt-token>
```

**Token要求**:
- 必须包含`user_id`字段
- 必须包含`username`字段
- Token未过期

---

## 📊 接口列表

### 1. 获取文档列表（融合版本信息）⭐ 核心接口

获取当前用户的文档列表，每个文档包含其当前版本的详细评查统计。

#### 基本信息

- **接口路径**: `GET /admin/versions/documents-list`
- **接口描述**: 文档管理页面主列表，展示每个文档的评查情况
- **权限要求**: 已登录用户
- **数据隔离**: 只返回当前用户的文档

#### 请求参数

**分页参数**:

| 参数名 | 类型 | 必填 | 默认值 | 取值范围 | 说明 |
|--------|------|------|--------|----------|------|
| page | integer | 否 | 1 | ≥1 | 页码（从1开始） |
| page_size | integer | 否 | 20 | 1-100 | 每页数量 |
| table_name | string | 否 | documents | - | 实体表名 |

**过滤参数**:

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| name | string | 否 | 文档名称模糊搜索 | "采购合同" |
| document_number | string | 否 | 文档编号精确匹配 | "DOC20250119001" |
| type_id | integer | 否 | 文档类型ID | 1 |
| status | string | 否 | 文件处理状态 | "Processed" |
| audit_status | integer | 否 | 审核状态 | 1 |
| start_time | string | 否 | 上传开始时间 | "2025-01-01" |
| end_time | string | 否 | 上传结束时间 | "2025-01-31" |

**status取值说明**:
- `Waiting`: 等待处理
- `Cutting`: 切分中
- `Extractioning`: 提取中
- `Evaluationing`: 评查中
- `Failed`: 处理失败
- `Processed`: 处理完成

**audit_status取值说明**:
- `-2`: 警告
- `-1`: 不通过
- `0`: 待审核
- `1`: 通过
- `2`: 审核中

#### 请求示例

**基础请求（默认参数）**
```bash
curl -X GET "http://localhost:8073/admin/versions/documents-list" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

**带分页和过滤**
```bash
curl -X GET "http://localhost:8073/admin/versions/documents-list?page=1&page_size=20&status=Processed&audit_status=1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

**文档名称搜索**
```bash
curl -X GET "http://localhost:8073/admin/versions/documents-list?name=采购合同" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

**时间范围查询**
```bash
curl -X GET "http://localhost:8073/admin/versions/documents-list?start_time=2025-01-01&end_time=2025-01-31" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

**Python示例**
```python
import requests

url = "http://localhost:8073/admin/versions/documents-list"
headers = {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "Content-Type": "application/json"
}
params = {
    "page": 1,
    "page_size": 20,
    "status": "Processed",
    "audit_status": 1,
    "name": "采购"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())
```

#### 响应格式

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

```json
{
  "total": 156,
  "page": 1,
  "page_size": 20,
  "total_pages": 8,
  "documents": [
    {
      "id": 1963,
      "name": "采购合同_V4.pdf",
      "original_name": "采购合同.pdf",
      "document_number": "DOC20250119001",
      "type_id": 1,
      "type_name": "合同类",
      "version_number": 4,
      "status": "Processed",
      "audit_status": 1,
      "file_size": 1024000,
      "created_at": "2025-01-19 10:30:00",
      "updated_at": "2025-01-19 11:45:00",
      "total_evaluation_points": 56,
      "pass_count": 49,
      "warning_count": 1,
      "fail_count": 6,
      "manual_count": 0,
      "failed_evaluation_points": 7,
      "has_previous_version": true,
      "total_versions": 4,
      "previous_version_id": 1960,
      "file_path": "/uploads/2025/01/19/doc1963.pdf",
      "thumbnail_url": "/thumbnails/doc1963_thumb.jpg"
    },
    {
      "id": 1962,
      "name": "服务协议_V2.pdf",
      "original_name": "服务协议.pdf",
      "document_number": "DOC20250119002",
      "type_id": 2,
      "type_name": "协议类",
      "version_number": 2,
      "status": "Processed",
      "audit_status": 1,
      "file_size": 512000,
      "created_at": "2025-01-19 09:15:00",
      "updated_at": "2025-01-19 09:45:00",
      "total_evaluation_points": 45,
      "pass_count": 43,
      "warning_count": 0,
      "fail_count": 2,
      "manual_count": 0,
      "failed_evaluation_points": 2,
      "has_previous_version": true,
      "total_versions": 2,
      "previous_version_id": 1958,
      "file_path": "/uploads/2025/01/19/doc1962.pdf",
      "thumbnail_url": "/thumbnails/doc1962_thumb.jpg"
    }
  ]
}
```

**字段说明**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| total | integer | 符合条件的文档总数 |
| page | integer | 当前页码 |
| page_size | integer | 每页数量 |
| total_pages | integer | 总页数 |
| documents | array | 文档列表 |

**单个文档对象字段**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | integer | 文档ID |
| name | string | 文档名称（含版本号） |
| original_name | string | 原始文档名称 |
| document_number | string | 文档编号 |
| type_id | integer | 文档类型ID |
| type_name | string | 文档类型名称 |
| version_number | integer | 当前版本号 |
| status | string | 处理状态 |
| audit_status | integer | 审核状态 |
| file_size | integer | 文件大小（字节） |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |
| total_evaluation_points | integer | 总评查点数 |
| pass_count | integer | 通过数量 |
| warning_count | integer | 警告数量 |
| fail_count | integer | 失败数量 |
| manual_count | integer | 待人工审核数量 |
| failed_evaluation_points | integer | 失败的评查点总数（warning + fail） |
| has_previous_version | boolean | 是否有历史版本 |
| total_versions | integer | 总版本数 |
| previous_version_id | integer | 上一个版本的ID（null表示无上版本） |
| file_path | string | 文件路径 |
| thumbnail_url | string | 缩略图URL |

#### 错误响应

**未授权 (401 Unauthorized)**
```json
{
  "code": 401,
  "msg": "缺少认证Token，请先登录",
  "data": []
}
```

**参数错误 (422 Unprocessable Entity)**
```json
{
  "code": 422,
  "msg": "参数验证错误",
  "data": [
    {
      "loc": ["query", "page_size"],
      "msg": "ensure this value is less than or equal to 100",
      "type": "value_error.number.not_le"
    }
  ]
}
```

**服务器错误 (500 Internal Server Error)**
```json
{
  "detail": "查询失败: Database connection error"
}
```

---

### 2. 获取实体的版本列表

获取指定实体的所有历史版本信息。

#### 基本信息

- **接口路径**: `GET /admin/versions/{entity_id}`
- **接口描述**: 查看文档/卷宗的历史版本列表
- **权限要求**: 已登录用户，且实体属于当前用户
- **数据隔离**: 只返回当前用户的实体版本

#### 路径参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| entity_id | integer | 是 | 实体ID（文档ID或卷宗ID） |

#### 查询参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| table_name | string | 否 | documents | 实体表名（documents, dossiers等） |

#### 请求示例

**获取文档的版本列表**
```bash
curl -X GET "http://localhost:8073/admin/versions/1963?table_name=documents" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

**Python示例**
```python
import requests

url = "http://localhost:8073/admin/versions/1963"
headers = {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
params = {
    "table_name": "documents"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())
```

#### 响应格式

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

```json
{
  "current_version": {
    "version_number": 4,
    "entity_id": 1963,
    "entity_name": "采购合同.pdf",
    "created_at": "2025-01-19 11:45:00",
    "file_size": 1024000,
    "status": "Processed",
    "audit_status": 1,
    "total_evaluation_points": 56,
    "pass_count": 49,
    "warning_count": 1,
    "fail_count": 6,
    "manual_count": 0,
    "failed_evaluation_points": 7,
    "is_current": true
  },
  "entity_name": "采购合同.pdf",
  "total_versions": 4,
  "versions": [
    {
      "version_number": 4,
      "entity_id": 1963,
      "entity_name": "采购合同_V4.pdf",
      "created_at": "2025-01-19 11:45:00",
      "file_size": 1024000,
      "status": "Processed",
      "audit_status": 1,
      "total_evaluation_points": 56,
      "pass_count": 49,
      "warning_count": 1,
      "fail_count": 6,
      "manual_count": 0,
      "failed_evaluation_points": 7,
      "is_current": true,
      "file_path": "/uploads/2025/01/19/doc1963.pdf",
      "thumbnail_url": "/thumbnails/doc1963_thumb.jpg"
    },
    {
      "version_number": 3,
      "entity_id": 1961,
      "entity_name": "采购合同_V3.pdf",
      "created_at": "2025-01-18 15:30:00",
      "file_size": 1020000,
      "status": "Processed",
      "audit_status": 1,
      "total_evaluation_points": 56,
      "pass_count": 46,
      "warning_count": 2,
      "fail_count": 8,
      "manual_count": 0,
      "failed_evaluation_points": 10,
      "is_current": false,
      "file_path": "/uploads/2025/01/18/doc1961.pdf",
      "thumbnail_url": "/thumbnails/doc1961_thumb.jpg"
    },
    {
      "version_number": 2,
      "entity_id": 1960,
      "entity_name": "采购合同_V2.pdf",
      "created_at": "2025-01-17 10:15:00",
      "file_size": 1015000,
      "status": "Processed",
      "audit_status": -1,
      "total_evaluation_points": 56,
      "pass_count": 41,
      "warning_count": 3,
      "fail_count": 12,
      "manual_count": 0,
      "failed_evaluation_points": 15,
      "is_current": false,
      "file_path": "/uploads/2025/01/17/doc1960.pdf",
      "thumbnail_url": "/thumbnails/doc1960_thumb.jpg"
    },
    {
      "version_number": 1,
      "entity_id": 1959,
      "entity_name": "采购合同_V1.pdf",
      "created_at": "2025-01-16 14:00:00",
      "file_size": 1010000,
      "status": "Processed",
      "audit_status": -1,
      "total_evaluation_points": 56,
      "pass_count": 38,
      "warning_count": 5,
      "fail_count": 13,
      "manual_count": 0,
      "failed_evaluation_points": 18,
      "is_current": false,
      "file_path": "/uploads/2025/01/16/doc1959.pdf",
      "thumbnail_url": "/thumbnails/doc1959_thumb.jpg"
    }
  ]
}
```

**字段说明**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| current_version | object | 当前版本信息 |
| entity_name | string | 实体原始名称（不含版本号） |
| total_versions | integer | 总版本数 |
| versions | array | 完整版本列表（按版本号降序） |

**版本对象字段**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| version_number | integer | 版本号 |
| entity_id | integer | 实体ID |
| entity_name | string | 实体名称（含版本号） |
| created_at | string | 创建时间 |
| file_size | integer | 文件大小（字节） |
| status | string | 处理状态 |
| audit_status | integer | 审核状态 |
| total_evaluation_points | integer | 总评查点数 |
| pass_count | integer | 通过数量 |
| warning_count | integer | 警告数量 |
| fail_count | integer | 失败数量 |
| manual_count | integer | 待人工审核数量 |
| failed_evaluation_points | integer | 失败评查点总数 |
| is_current | boolean | 是否当前版本 |
| file_path | string | 文件路径 |
| thumbnail_url | string | 缩略图URL |

#### 错误响应

**未找到 (404 Not Found)**
```json
{
  "detail": "实体不存在或无权访问"
}
```

**无权限 (404 Not Found)**
```json
{
  "detail": "无权访问此实体"
}
```

---

### 3. 对比两个版本的评查结果

对比两个版本的评查结果，支持统计分析和LLM深度分析。

#### 基本信息

- **接口路径**: `POST /admin/versions/compare`
- **接口描述**: 查看版本改进情况，追踪问题解决进度
- **权限要求**: 已登录用户，且两个版本都属于当前用户
- **性能参数**:
  - 统计模式: 50-100ms, ¥0
  - LLM模式: 2-5s, ¥0.002

#### 查询参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| table_name | string | 否 | documents | 实体表名 |

#### 请求体

```json
{
  "old_version_id": 1960,
  "new_version_id": 1963,
  "enable_llm": false
}
```

**请求体字段**:

| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| old_version_id | integer | 是 | - | 旧版本ID |
| new_version_id | integer | 是 | - | 新版本ID |
| enable_llm | boolean | 否 | false | 是否启用LLM深度分析 |

#### 请求示例

**统计模式（默认，快速）**
```bash
curl -X POST "http://localhost:8073/admin/versions/compare" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "old_version_id": 1960,
    "new_version_id": 1963,
    "enable_llm": false
  }'
```

**LLM模式（智能分析）**
```bash
curl -X POST "http://localhost:8073/admin/versions/compare" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "old_version_id": 1960,
    "new_version_id": 1963,
    "enable_llm": true
  }'
```

**Python示例**
```python
import requests

url = "http://localhost:8073/admin/versions/compare"
headers = {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "Content-Type": "application/json"
}
data = {
    "old_version_id": 1960,
    "new_version_id": 1963,
    "enable_llm": False  # 设置为True启用LLM分析
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
```

#### 响应格式

**成功响应 - 统计模式 (200 OK)**

```json
{
  "statistics": {
    "old_total": 15,
    "new_total": 7,
    "change_from_previous": -8,
    "change_type": "decreased",
    "improvement_rate": 53
  },
  "resolved_issues": [
    {
      "evaluation_point_id": 116,
      "point_name": "当事人基本情况记载完整、准确",
      "old_result": "false",
      "new_result": "true",
      "risk_level": "high"
    },
    {
      "evaluation_point_id": 121,
      "point_name": "现场笔录时间地点完整性",
      "old_result": "false",
      "new_result": "true",
      "risk_level": "medium"
    }
  ],
  "remaining_issues": [
    {
      "evaluation_point_id": 103,
      "point_name": "案件来源有无一致性校验",
      "old_result": "false",
      "new_result": "false",
      "risk_level": "medium"
    }
  ],
  "new_issues": [],
  "analysis": {
    "type": "statistical",
    "summary": "版本改进：对比上个版本减少 8 个问题（改进率 53%）",
    "conclusion": "positive",
    "recommendations": [
      "已解决 8 个问题，进步显著",
      "仍有 7 个问题待解决",
      "建议重点关注剩余的中高风险问题"
    ]
  }
}
```

**成功响应 - LLM模式 (200 OK)**

```json
{
  "statistics": {
    "old_total": 15,
    "new_total": 7,
    "change_from_previous": -8,
    "change_type": "decreased",
    "improvement_rate": 53
  },
  "resolved_issues": [...],
  "remaining_issues": [...],
  "new_issues": [],
  "analysis": {
    "type": "llm",
    "summary": "版本V4相比V2有显著改进，成功解决了8个核心问题，改进率达53%。",
    "conclusion": "positive",
    "recommendations": [
      "优先处理'案件来源有无一致性校验'等高风险问题",
      "建议在下一版本中重点关注合规性检查项",
      "当前版本质量良好，可以考虑提交审核"
    ],
    "details": {
      "key_improvements": [
        "当事人基本情况记载完整性得到改善",
        "现场笔录时间地点信息补充完整"
      ],
      "remaining_risks": [
        "案件来源一致性需要进一步核对",
        "部分格式规范仍需完善"
      ]
    }
  }
}
```

**字段说明**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| statistics | object | 统计数据 |
| statistics.old_total | integer | 旧版本问题总数 |
| statistics.new_total | integer | 新版本问题总数 |
| statistics.change_from_previous | integer | 相比上版本的变化量 |
| statistics.change_type | string | 变化类型（decreased/increased/unchanged） |
| statistics.improvement_rate | integer | 改进率（百分比） |
| resolved_issues | array | 已解决的问题列表 |
| remaining_issues | array | 仍存在的问题列表 |
| new_issues | array | 新增的问题列表 |
| analysis | object | 分析结果 |
| analysis.type | string | 分析类型（statistical/llm） |
| analysis.summary | string | 分析摘要 |
| analysis.conclusion | string | 结论（positive/negative/neutral） |
| analysis.recommendations | array | 建议列表 |
| analysis.details | object | 详细分析（仅LLM模式） |

**问题对象字段**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| evaluation_point_id | integer | 评查点ID |
| point_name | string | 评查点名称 |
| old_result | string | 旧版本结果（true/false） |
| new_result | string | 新版本结果（true/false） |
| risk_level | string | 风险级别（high/medium/low） |

#### 错误响应

**版本不存在或无权限 (404 Not Found)**
```json
{
  "detail": "版本不存在或无权访问"
}
```

**LLM服务不可用 (500 Internal Server Error)**
```json
{
  "detail": "对比失败: LLM服务暂时不可用"
}
```

---

### 4. 获取版本统计信息

获取版本管理的统计数据（可选功能）。

#### 基本信息

- **接口路径**: `GET /admin/versions/statistics`
- **接口描述**: 查看版本管理的整体统计情况
- **权限要求**: 已登录用户
- **数据隔离**: 只统计当前用户的数据

#### 查询参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| table_name | string | 否 | documents | 实体表名 |
| date_from | string | 否 | null | 起始日期（YYYY-MM-DD） |
| date_to | string | 否 | null | 结束日期（YYYY-MM-DD） |

#### 请求示例

**基础请求**
```bash
curl -X GET "http://localhost:8073/admin/versions/statistics" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

**带时间范围**
```bash
curl -X GET "http://localhost:8073/admin/versions/statistics?date_from=2025-01-01&date_to=2025-01-31" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

#### 响应格式

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

```json
{
  "total_documents": 156,
  "total_versions": 423,
  "unique_documents": 89,
  "average_versions_per_document": 4.75,
  "version_distribution": {
    "采购合同.pdf": 4,
    "服务协议.pdf": 2,
    "租赁合同.pdf": 3,
    "保密协议.pdf": 5,
    "销售合同.pdf": 2
  }
}
```

**字段说明**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| total_documents | integer | 文档总数（包含所有版本） |
| total_versions | integer | 版本总数 |
| unique_documents | integer | 唯一文档数（按name去重） |
| average_versions_per_document | float | 平均版本数 |
| version_distribution | object | 版本分布（文档名 → 版本数） |

---

## 💻 前端集成示例

### Vue 3 + TypeScript

```typescript
// api/versions.ts
import axios from 'axios';

const API_BASE = '/admin/versions';

// 类型定义
export interface Document {
  id: number;
  name: string;
  version_number: number;
  status: string;
  audit_status: number;
  total_evaluation_points: number;
  pass_count: number;
  warning_count: number;
  fail_count: number;
  failed_evaluation_points: number;
  has_previous_version: boolean;
  total_versions: number;
}

export interface DocumentListParams {
  page?: number;
  page_size?: number;
  name?: string;
  status?: string;
  audit_status?: number;
  start_time?: string;
  end_time?: string;
}

export interface CompareRequest {
  old_version_id: number;
  new_version_id: number;
  enable_llm?: boolean;
}

// API函数
export const getDocumentsList = async (params?: DocumentListParams) => {
  const response = await axios.get(`${API_BASE}/documents-list`, { params });
  return response.data;
};

export const getVersionList = async (entityId: number, tableName = 'documents') => {
  const response = await axios.get(`${API_BASE}/${entityId}`, {
    params: { table_name: tableName }
  });
  return response.data;
};

export const compareVersions = async (data: CompareRequest, tableName = 'documents') => {
  const response = await axios.post(`${API_BASE}/compare`, data, {
    params: { table_name: tableName }
  });
  return response.data;
};

export const getStatistics = async (dateFrom?: string, dateTo?: string) => {
  const response = await axios.get(`${API_BASE}/statistics`, {
    params: { date_from: dateFrom, date_to: dateTo }
  });
  return response.data;
};
```

**组件使用**

```vue
<template>
  <div class="document-list">
    <el-table :data="documents" v-loading="loading">
      <el-table-column prop="name" label="文档名称" />
      <el-table-column prop="version_number" label="版本号" width="100" />
      <el-table-column label="评查情况" width="300">
        <template #default="{ row }">
          <el-tag type="success">通过: {{ row.pass_count }}</el-tag>
          <el-tag type="warning">警告: {{ row.warning_count }}</el-tag>
          <el-tag type="danger">失败: {{ row.fail_count }}</el-tag>
        </template>
      </el-table-column>
      <el-table-column label="操作" width="200">
        <template #default="{ row }">
          <el-button @click="viewVersions(row.id)" size="small">
            查看版本 ({{ row.total_versions }})
          </el-button>
          <el-button
            v-if="row.has_previous_version"
            @click="compareWithPrevious(row)"
            size="small"
            type="primary"
          >
            版本对比
          </el-button>
        </template>
      </el-table-column>
    </el-table>

    <el-pagination
      v-model:current-page="currentPage"
      v-model:page-size="pageSize"
      :total="total"
      @current-change="loadData"
      @size-change="loadData"
    />
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { getDocumentsList, compareVersions } from '@/api/versions';

const loading = ref(false);
const documents = ref([]);
const currentPage = ref(1);
const pageSize = ref(20);
const total = ref(0);

const loadData = async () => {
  loading.value = true;
  try {
    const result = await getDocumentsList({
      page: currentPage.value,
      page_size: pageSize.value,
      status: 'Processed'
    });
    documents.value = result.documents;
    total.value = result.total;
  } catch (error) {
    console.error('加载失败:', error);
  } finally {
    loading.value = false;
  }
};

const compareWithPrevious = async (row: any) => {
  if (!row.previous_version_id) return;

  loading.value = true;
  try {
    const result = await compareVersions({
      old_version_id: row.previous_version_id,
      new_version_id: row.id,
      enable_llm: false
    });

    // 显示对比结果
    console.log('对比结果:', result);
    // TODO: 打开对比结果对话框
  } catch (error) {
    console.error('对比失败:', error);
  } finally {
    loading.value = false;
  }
};

onMounted(() => {
  loadData();
});
</script>
```

---

## 📊 使用场景

### 场景1: 文档管理列表

**目标**: 展示所有文档及其评查状态

```javascript
// 获取处理完成的文档列表
const { documents, total } = await getDocumentsList({
  page: 1,
  page_size: 20,
  status: 'Processed'
});

// 筛选有问题的文档
const problemDocuments = documents.filter(
  doc => doc.failed_evaluation_points > 0
);
```

### 场景2: 版本历史追踪

**目标**: 查看文档的所有历史版本

```javascript
// 点击文档，查看其版本列表
const versionHistory = await getVersionList(documentId);

console.log(`文档名称: ${versionHistory.entity_name}`);
console.log(`总版本数: ${versionHistory.total_versions}`);
console.log(`当前版本: V${versionHistory.current_version.version_number}`);

// 展示版本时间线
versionHistory.versions.forEach(v => {
  console.log(`V${v.version_number}: ${v.failed_evaluation_points}个问题 (${v.created_at})`);
});
```

### 场景3: 版本改进对比

**目标**: 查看版本改进情况

```javascript
// 对比当前版本和上一版本
const comparison = await compareVersions({
  old_version_id: 1960,
  new_version_id: 1963,
  enable_llm: false  // 快速统计模式
});

console.log(`改进率: ${comparison.statistics.improvement_rate}%`);
console.log(`已解决: ${comparison.resolved_issues.length}个问题`);
console.log(`仍存在: ${comparison.remaining_issues.length}个问题`);

// 生成改进报告
const report = {
  summary: comparison.analysis.summary,
  improvement_rate: comparison.statistics.improvement_rate,
  resolved: comparison.resolved_issues.map(i => i.point_name),
  remaining: comparison.remaining_issues.map(i => i.point_name)
};
```

### 场景4: 智能改进建议

**目标**: 使用LLM获取智能建议

```javascript
// 启用LLM深度分析
const aiAnalysis = await compareVersions({
  old_version_id: 1960,
  new_version_id: 1963,
  enable_llm: true  // 启用LLM模式
});

// 显示AI建议
console.log('AI分析摘要:', aiAnalysis.analysis.summary);
console.log('改进建议:');
aiAnalysis.analysis.recommendations.forEach((rec, index) => {
  console.log(`${index + 1}. ${rec}`);
});

// 关键改进点
if (aiAnalysis.analysis.details) {
  console.log('关键改进:', aiAnalysis.analysis.details.key_improvements);
  console.log('剩余风险:', aiAnalysis.analysis.details.remaining_risks);
}
```

---

## ⚠️ 注意事项

### 1. 性能优化

- 文档列表查询建议使用合理的`page_size`（推荐20-50）
- 版本对比默认使用统计模式（快速）
- LLM模式会增加响应时间（2-5秒），按需启用

### 2. 权限控制

- 所有接口都需要JWT Token
- 用户只能查看自己的文档和版本
- 跨用户访问会返回404错误

### 3. 版本号规则

- 版本号由系统自动生成
- 同名文档的版本号递增（1, 2, 3...）
- 最新版本的版本号最大

### 4. LLM使用建议

- 日常查看建议关闭LLM（`enable_llm: false`）
- 需要深度分析时启用LLM（`enable_llm: true`）
- LLM分析有成本，避免频繁调用

### 5. 错误处理

```typescript
try {
  const data = await getDocumentsList({ page: 1, page_size: 20 });
  // 处理数据
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 401:
        // Token过期，跳转登录
        router.push('/login');
        break;
      case 404:
        // 资源不存在或无权限
        message.error('文档不存在或无权访问');
        break;
      case 422:
        // 参数错误
        message.error('请求参数错误');
        break;
      case 500:
        // 服务器错误
        message.error('服务器错误，请稍后重试');
        break;
    }
  }
}
```

---

## 📞 技术支持

### 相关文档

- [版本管理V3 README](./README.md)
- [功能需求分析与实现方案](./功能需求分析与实现方案.md)
- [文档列表融合版本管理接口说明](./文档列表融合版本管理接口说明.md)
- [文档列表与评查文件列表对比详解](./文档列表与评查文件列表对比详解.md)

### 常见问题

**Q: 为什么版本号不连续？**

A: 版本号是基于同名文档计算的，如果中间删除了某些版本，版本号会跳跃。

**Q: LLM分析需要多长时间？**

A: 通常2-5秒，取决于文档复杂度和LLM服务负载。

**Q: 如何判断文档是否有问题？**

A: 查看`failed_evaluation_points`字段，大于0表示有问题。

**Q: 版本对比是否支持跨文档？**

A: 不支持。只能对比同一个文档的不同版本。

---

**最后更新**: 2025-11-19
**版本**: v1.0
**维护者**: DocAuditAI Team

🤖 Generated with [Claude Code](https://claude.com/claude-code)