all in

2025-12-05 00:09:32 +08:00
parent bb3d22eabf
commit 3d1dbb3f97
214 changed files with 113060 additions and 1232 deletions
@@ -0,0 +1,383 @@
+# 版本管理 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