# 版本管理 v3 快速参考

> 5 分钟快速上手指南

---

## 🚀 快速开始

### 1. API 端点

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

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

### 2. 通用查询参数

所有端点都支持 `table_name` 参数：

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

---

## 📝 常用示例

### 获取版本列表

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

**响应：**

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

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

```bash
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
  }'
```

**关键字段：**

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

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

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

**额外返回：**

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

---

## 💻 Python 使用

### 基础用法

```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
)
```

### 扩展到新类型

```python
# 支持卷宗
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

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

```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": "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         | 服务器内部错误               | 查看日志                   |

### 示例

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

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

---

## 🧪 测试

### 单元测试

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

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

### 集成测试

```bash
# 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
```

---

## 📌 关键要点

### ✅ 必须记住

1. **change_from_previous 是带符号的**
   - 负数 = 改进
   - 正数 = 退步
   - 零 = 持平

2. **LLM 默认关闭**
   - `enable_llm=False` 是默认值
   - 需要智能分析时显式设置为 `true`

3. **table_name 参数支持扩展**
   - `documents` - 文档
   - `dossiers` - 卷宗
   - 未来任意表

4. **权限自动验证**
   - 所有查询自动检查 user_id
   - 无权限访问返回 404

### ⚠️ 注意事项

1. **LLM 模式成本**
   - 每次调用约 ¥0.002
   - 高频使用需考虑成本

2. **LLM 可能失败**
   - 系统会自动降级到统计模式
   - 不影响核心功能

3. **版本号动态计算**
   - 最新版本号最大
   - 删除旧版本会影响版本号

---

## 🔗 相关资源

- [完整实现文档](./version_management_v3_implementation_summary.md)
- [开发计划](./version_management_optimization_plan.md)
- [API 测试脚本](../test_version_api_v3.py)
- [单元测试](../tests/test_version_management_v3.py)

---

## 💡 最佳实践

### 1. 前端展示

```javascript
// 展示变化趋势
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

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

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

### 3. 缓存策略

```python
# 版本列表缓存 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