TanWenyan/leaudit-platform-frontend

Fork 0

Files

T

LiangShiyong 3d1dbb3f97 all in

2025-12-05 00:09:32 +08:00

28 KiB

Raw Blame History

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

📋 概述

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

基础URL: /admin/versions

设计理念:

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

🔐 认证方式

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

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: 审核中

请求示例

基础请求（默认参数）

curl -X GET "http://localhost:8073/admin/versions/documents-list" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

带分页和过滤

curl -X GET "http://localhost:8073/admin/versions/documents-list?page=1&page_size=20&status=Processed&audit_status=1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

文档名称搜索

curl -X GET "http://localhost:8073/admin/versions/documents-list?name=采购合同" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

时间范围查询

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示例

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)

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

{
  "code": 401,
  "msg": "缺少认证Token，请先登录",
  "data": []
}

参数错误 (422 Unprocessable Entity)

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

{
  "detail": "查询失败: Database connection error"
}

2. 获取实体的版本列表

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

基本信息

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

路径参数

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

查询参数

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

请求示例

获取文档的版本列表

curl -X GET "http://localhost:8073/admin/versions/1963?table_name=documents" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

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)

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

{
  "detail": "实体不存在或无权访问"
}

无权限 (404 Not Found)

{
  "detail": "无权访问此实体"
}

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

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

基本信息

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

查询参数

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

请求体

{
  "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深度分析

请求示例

统计模式（默认，快速）

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模式（智能分析）

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示例

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)

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

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

{
  "detail": "版本不存在或无权访问"
}

LLM服务不可用 (500 Internal Server Error)

{
  "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）

请求示例

基础请求

curl -X GET "http://localhost:8073/admin/versions/statistics" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

带时间范围

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)

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

// 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;
};

组件使用

<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: 文档管理列表

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

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

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

场景2: 版本历史追踪

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

// 点击文档，查看其版本列表
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: 版本改进对比

目标: 查看版本改进情况

// 对比当前版本和上一版本
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获取智能建议

// 启用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. 错误处理

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;
    }
  }
}

📞 技术支持

常见问题

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

28 KiB Raw Blame History Unescape Escape

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

📋 概述

🔐 认证方式

📊 接口列表

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

基本信息

请求参数

请求示例

响应格式

错误响应

2. 获取实体的版本列表

基本信息

路径参数

查询参数

请求示例

响应格式

错误响应

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

基本信息

查询参数

请求体

请求示例

响应格式

错误响应

4. 获取版本统计信息

基本信息

查询参数

请求示例

响应格式

💻 前端集成示例

Vue 3 + TypeScript

📊 使用场景

场景1: 文档管理列表

场景2: 版本历史追踪

场景3: 版本改进对比

场景4: 智能改进建议

⚠️ 注意事项

1. 性能优化

2. 权限控制

3. 版本号规则

4. LLM使用建议

5. 错误处理

📞 技术支持

相关文档

常见问题

28 KiB

Raw Blame History