TanWenyan/leaudit-platform-frontend

Fork 0

Files

T

LiangShiyong 3d1dbb3f97 all in

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

7.8 KiB

Raw Blame History

版本管理 v3 快速参考

5 分钟快速上手指南

🚀 快速开始

1. API 端点

基础路径: /admin/api/v3/versions

方法	端点	描述
GET	`/{entity_id}`	获取版本列表
POST	`/compare`	对比两个版本
GET	`/{entity_id}/failed-points`	获取失败评查点
GET	`/statistics`	获取统计信息

2. 通用查询参数

所有端点都支持 table_name 参数：

?table_name=documents  # 默认
?table_name=dossiers   # 卷宗
?table_name=xxx        # 未来扩展

📝 常用示例

获取版本列表

curl -X GET \
  "http://localhost:8000/admin/api/v3/versions/123" \
  -H "Authorization: Bearer YOUR_TOKEN"

响应：

{
  "current_version": {
    "version_number": 3,
    "failed_evaluation_points": 7
  },
  "total_versions": 3,
  "versions": [...]
}

版本对比（快速 - 统计模式）

curl -X POST \
  "http://localhost:8000/admin/api/v3/versions/compare" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "old_version_id": 122,
    "new_version_id": 123,
    "enable_llm": false
  }'

关键字段：

{
  "statistics": {
    "change_from_previous": -8,  // ✅ 负数=改进，正数=退步
    "improvement_rate": 53
  }
}

版本对比（智能 - LLM 模式）

# 只需将 enable_llm 改为 true
{
  "old_version_id": 122,
  "new_version_id": 123,
  "enable_llm": true  // ✅ 启用 LLM
}

额外返回：

{
  "analysis": {
    "type": "llm",
    "risk_assessment": {...},
    "priority_issues": [...]
  }
}

💻 Python 使用

基础用法

from services.documents.v3 import UniversalVersionService

# 初始化
service = UniversalVersionService()

# 获取版本列表
versions = await service.get_version_list(
    entity_id=123,
    user_id=1
)

# 快速对比（统计模式）
result = await service.compare_versions(
    old_version_id=122,
    new_version_id=123,
    user_id=1,
    enable_llm=False  # 默认即可
)

# 智能对比（LLM 模式）
result_llm = await service.compare_versions(
    old_version_id=122,
    new_version_id=123,
    user_id=1,
    enable_llm=True  # ✅ 启用 LLM
)

扩展到新类型

# 支持卷宗
service = UniversalVersionService(
    table_name="dossiers",
    evaluation_table="dossier_evaluations",
    evaluation_fk="dossier_id"
)

# API 使用相同
versions = await service.get_version_list(entity_id=456, user_id=1)

📊 响应格式速查

VersionListResponse

{
  "current_version": {
    "version_number": 3,
    "entity_id": 123,
    "entity_name": "采购合同.pdf",
    "failed_evaluation_points": 7,
    "is_current": true
  },
  "entity_name": "采购合同.pdf",
  "total_versions": 3,
  "versions": [...]
}

ComparisonResponse

{
  "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": "statistical" | "llm",
    "summary": "...",
    "conclusion": "positive" | "negative" | "neutral",
    "recommendations": [...]
  }
}

🔧 配置参数

UniversalVersionService 构造函数

参数	默认值	说明
`table_name`	`"documents"`	实体表名
`pk_field`	`"id"`	主键字段
`name_field`	`"name"`	名称字段（分组依据）
`timestamp_field`	`"created_at"`	时间戳字段（排序）
`user_field`	`"user_id"`	用户字段（权限）
`evaluation_table`	`"evaluation_results"`	评查结果表
`evaluation_fk`	`"document_id"`	评查表外键

⚡ 性能对比

模式	响应时间	成本	使用场景
统计模式	50-100ms	¥0	快速查看、API
LLM 模式	2-5s	¥0.002/次	详细报告

推荐：

列表查看 → 统计模式
详细分析 → LLM 模式
API 集成 → 统计模式
人工审查 → LLM 模式

🛡️ 错误处理

常见错误码

HTTP 状态码	错误原因	解决方案
401	Token 无效或过期	重新登录
404	实体不存在或无权限访问	检查 entity_id 和权限
500	服务器内部错误	查看日志

示例

// 404 错误
{
  "detail": "实体不存在或无权限访问: entity_id=999, user_id=1"
}

// 500 错误
{
  "detail": "对比失败: Connection timeout"
}

🧪 测试

单元测试

# 运行所有测试
pytest tests/test_version_management_v3.py -v

# 运行特定测试
pytest tests/test_version_management_v3.py::TestVersionComparisonEngine::test_calculate_statistics_decreased -v

集成测试

# 1. 启动应用
python run.py

# 2. 修改测试参数
# test_version_api_v3.py 底部
await tester.run_all_tests(entity_id=123)

# 3. 运行测试
python test_version_api_v3.py

📌 关键要点

✅ 必须记住

change_from_previous 是带符号的
- 负数 = 改进
- 正数 = 退步
- 零 = 持平
LLM 默认关闭
- enable_llm=False 是默认值
- 需要智能分析时显式设置为 true
table_name 参数支持扩展
- documents - 文档
- dossiers - 卷宗
- 未来任意表
权限自动验证
- 所有查询自动检查 user_id
- 无权限访问返回 404

⚠️ 注意事项

LLM 模式成本
- 每次调用约 ¥0.002
- 高频使用需考虑成本
LLM 可能失败
- 系统会自动降级到统计模式
- 不影响核心功能
版本号动态计算
- 最新版本号最大
- 删除旧版本会影响版本号

🔗 相关资源

💡 最佳实践

1. 前端展示

// 展示变化趋势
const change = statistics.change_from_previous;
const icon = change < 0 ? "⬇️" : change > 0 ? "⬆️" : "➡️";
const color = change < 0 ? "green" : change > 0 ? "red" : "gray";
const text = change < 0
  ? `减少 ${Math.abs(change)} 个问题`
  : change > 0
  ? `增加 ${change} 个问题`
  : `无变化`;

// 显示
<span style={{color}}>
  {icon} {text}
</span>

2. 何时使用 LLM

# ✅ 适合 LLM
- 用户主动请求详细报告
- 生成周报/月报
- 重要文档的深度分析

# ❌ 不适合 LLM
- 列表页快速预览
- 高频 API 调用
- 实时性要求高的场景

3. 缓存策略

# 版本列表缓存 5 分钟
@cache(ttl=300)
async def get_version_list(entity_id, user_id):
    ...

# LLM 结果缓存 1 小时（相同版本对比）
cache_key = f"llm:{old_id}:{new_id}"
redis.setex(cache_key, 3600, json.dumps(result))

最后更新: 2025-11-18 版本: v3.0.0 维护者: Claude Code

7.8 KiB Raw Blame History