# main 分支独有功能与端点说明

> 本文档记录 `main` 分支（本地最新版本）相对于 `server-release`（生产服务器版本）的**独有功能和端点差异**。
>
> 更新日期：2026-06-10 | 对比基准：`origin/server-release` (commit `15c0aec`) vs `main` (commit `edaef7a`)

---

## 一、新增端点（仅 main 可用）

### 1. 异步任务查询系统

main 分支引入了完整的异步任务注册表（`core/task_registry.py`），将上传、同步、出题等长耗时操作改为后台线程执行，接口立即返回 `task_id`。

| 端点 | 方法 | 说明 |
|------|------|------|
| `/tasks` | GET | 获取任务列表（支持 status/type/limit 过滤） |
| `/tasks/<task_id>` | GET | 获取单个任务状态（JSON 轮询，后端组推荐） |
| `/tasks/<task_id>/progress` | GET | SSE 流式任务进度推送（dev-ui 前端推荐） |
| `/tasks/stats` | GET | 获取任务统计信息 |

**GET /tasks 请求参数**：

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `status` | string | ❌ | 过滤状态：`pending` / `running` / `completed` / `failed` |
| `type` | string | ❌ | 过滤类型：`sync` / `reindex` / `upload` / `batch_upload` / `exam_generate` / `exam_grade` |
| `limit` | int | ❌ | 返回数量限制（默认 50） |

**GET /tasks 响应示例**：
```json
{
  "success": true,
  "status": "success",
  "status_code": 2000,
  "message": "查询成功",
  "data": {
    "tasks": [
      {
        "task_id": "a1b2c3d4e5f6",
        "type": "sync",
        "description": "文档同步",
        "status": "running",
        "progress": 45.0,
        "current": 9,
        "total": 20,
        "stage": "处理文件",
        "message": "已处理: 产品手册.pdf",
        "created_at": "2026-06-05T10:30:00",
        "started_at": "2026-06-05T10:30:01"
      }
    ],
    "total": 1
  }
}
```

**GET /tasks/\<task_id\>/progress SSE 事件序列**：
```
data: {"type": "start", "data": {"stage": "扫描文档"}}
data: {"type": "progress", "data": {"progress": 10.0, "current": 2, "total": 20, "stage": "处理文件", "message": "已处理: file1.pdf"}}
data: {"type": "progress", "data": {"progress": 25.0, "current": 5, "total": 20, "stage": "处理文件", "message": "已处理: file2.docx"}}
data: {"type": "complete", "data": {"task_id": "a1b2c3d4e5f6", "status": "completed", "result": {...}}}
```

> 心跳保活：每 1 秒发送 `: heartbeat`，防止连接超时。

**任务状态流转**：
```
pending → running → completed
                  → failed
```

---

### 2. 缓存管理接口

用于调试和监控 LRU 缓存与语义缓存的运行状态。

| 端点 | 方法 | 说明 |
|------|------|------|
| `/cache/stats` | GET | 获取所有缓存的命中统计 |
| `/cache/clear` | POST | 清空所有缓存 |

**GET /cache/stats 响应示例**：
```json
{
  "embedding_cache": {
    "total_entries": 128,
    "hits": 45,
    "misses": 83,
    "hit_rate": "35.16%",
    "evictions": 0
  },
  "semantic_cache": {
    "total_entries": 50,
    "hits": 12,
    "misses": 38,
    "hit_rate": "24.00%"
  },
  "semantic_cache_intent": {
    "total_entries": 30,
    "hits": 8,
    "misses": 22,
    "hit_rate": "26.67%"
  }
}
```

**POST /cache/clear 响应示例**：
```json
{
  "status": "ok",
  "cleared": {
    "lru_cache": "cleared",
    "semantic_cache": "cleared"
  }
}
```

---

### 3. 会话管理接口

需要 `ENABLE_SESSION=true` 配置项启用，使用 SQLite 存储会话历史。

| 端点 | 方法 | 说明 |
|------|------|------|
| `/sessions` | GET | 获取当前用户的会话列表 |
| `/history/<session_id>` | GET | 获取指定会话的聊天历史 |
| `/session/<session_id>` | DELETE | 删除指定会话 |
| `/clear/<session_id>` | POST | 清空指定会话的历史（保留会话） |

> **注意**：这些端点在 `ENABLE_SESSION=false`（生产模式默认值）时不注册，返回 404。

**GET /sessions 响应示例**：
```json
{
  "success": true,
  "status": "success",
  "status_code": 2000,
  "data": {
    "sessions": [
      {
        "session_id": "abc-123-def",
        "created_at": "2026-06-05T10:30:00",
        "last_active": "2026-06-05T11:00:00",
        "preview": "用户最后一条消息的前50字..."
      }
    ]
  }
}
```

**GET /history/\<session_id\> 响应示例**：
```json
{
  "success": true,
  "status": "success",
  "status_code": 2000,
  "data": {
    "history": [
      {"role": "user", "content": "你好", "created_at": "2026-06-05T10:30:00"},
      {"role": "assistant", "content": "你好！有什么可以帮你的？", "created_at": "2026-06-05T10:30:01"}
    ]
  }
}
```

---

### 4. 审计日志接口

需要 `ENABLE_SESSION=true` 配置项启用，查询用户操作审计记录。

| 端点 | 方法 | 说明 |
|------|------|------|
| `/audit/logs` | GET | 查询审计日志（管理员） |

**GET /audit/logs 请求参数**：

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `limit` | int | ❌ | 返回条数（默认 50） |
| `days` | int | ❌ | 查询天数范围（默认 7） |
| `action` | string | ❌ | 按操作类型过滤 |

**响应示例**：
```json
{
  "success": true,
  "status": "success",
  "status_code": 2000,
  "data": {
    "logs": [
      {
        "id": 1,
        "user_id": "admin001",
        "username": "admin",
        "action": "rag_query",
        "query": "三峡工程",
        "result_summary": "...",
        "role": "admin",
        "department": "管理部",
        "ip_address": "127.0.0.1",
        "duration_ms": 1234,
        "timestamp": "2026-06-05T12:00:00"
      }
    ],
    "total": 100
  }
}
```

---

### 5. 系统统计接口

| 端点 | 方法 | 说明 |
|------|------|------|
| `/stats` | GET | 获取系统综合统计 |

> **server-release 上此端点返回 500**（`KeyError: 'SESSION_MANAGER'`），因为会话管理器未初始化。main 分支在 `ENABLE_SESSION=true` 时正常工作。

---

## 二、已有端点的行为与内部逻辑差异

以下端点在 main 和 server-release 上 URL 相同，但**行为或内部逻辑有显著差异**。

### 1. 全面异步化

server-release 上为同步阻塞的操作，在 main 分支改为异步执行并返回 `task_id`：

| 端点 | server-release 行为 | main 行为 |
|------|---------------------|-----------|
| `POST /documents/upload` | 同步保存+向量化，直接返回结果 | 同步保存，异步向量化，返回 `task_id` |
| `POST /documents/batch-upload` | 同步保存+向量化，直接返回结果 | 同步保存，异步向量化，返回 `task_id` |
| `POST /sync` | 同步阻塞直到完成 | 异步执行，立即返回 `task_id` |
| `POST /collections/<kb>/reindex` | 同步阻塞直到完成 | 异步执行，立即返回 `task_id` |
| `POST /exam/generate` | 同步阻塞（30-60s） | 异步执行，立即返回 `task_id` |
| `POST /exam/generate-smart` | 同步阻塞（30-60s） | 异步执行，立即返回 `task_id` |
| `POST /exam/grade` | 同步阻塞 | 异步执行，立即返回 `task_id` |

**main 分支上传响应示例**（对比 server-release）：
```json
{
  "success": true,
  "status": "success",
  "status_code": 2002,
  "message": "文件上传成功，已保存，向量化任务已启动",
  "data": {
    "file": {
      "filename": "test.txt",
      "collection": "public_kb",
      "path": "public_kb/test.txt",
      "size": 18,
      "replaced": false
    },
    "sync_status": "已保存，向量化任务已启动",
    "task_id": "a1b2c3d4e5f6"
  }
}
```

> **新增字段**：`task_id`（用于轮询进度）、`replaced`（是否为覆盖旧文件）。
> server-release 上这两个字段不存在。

**后端调用流程变更**：
```
server-release: POST /upload → 等待 → 200 OK（文件已处理）
main:           POST /upload → 立即 200 OK（task_id）→ GET /tasks/<id> 轮询直到 completed
```

### 2. RAG 问答增强（不涉及端口变化）

`POST /rag` 端点在两个分支上 URL 和响应格式一致，但**内部管道逻辑**有差异。

**两个分支共有的能力（engine.py 层，已同步）**：

| 能力 | 说明 |
|------|------|
| Embedding 缓存 | `_encode_cached()` LRU 缓存，减少重复编码 |
| 表格邻居上下文扩展 | 表格切片自动扩展相邻文本上下文 |
| MMR 去重 | 文本相似度去重，减少冗余切片 |
| 子查询分解 | 复杂查询拆分为子查询提升召回 |
| 图片 P0 独立召回 | 图片切片独立通道检索 |
| 引用去重 | chunk_id 保序去重 |

**main 独有的增强（chat_routes.py 层）**：

| 能力 | 说明 | 涉及函数 |
|------|------|----------|
| 语义缓存闭环 | 相似问题命中缓存直接返回，跳过检索和生成 | 集成在 RAG 管道主流程中 |
| 表格救援 | 被预算截断的表格切片补回上下文 | `_rescue_table_chunks()` |
| 语义前缀精简 | 精简表格切片冗余语义前缀，保留章节标识 | `_strip_semantic_prefix()` |
| 层级章节相似度 | 数值精确匹配 + Jaccard 层级系数，用于图片/表格章节过滤 | `_section_similarity()` |
| 图片后置过滤 | 基于 LLM 回答关键词反向筛选图片 | `_filter_images_by_answer()` |

**server-release 独有的增强（agentic*.py 模块化层）**：

| 能力 | 说明 | 所在模块 |
|------|------|----------|
| 查询改写 | 口语→专业术语映射、实体补全、LLM 深度重写、图片指代识别 | `agentic_query.py` QueryRewriteMixin |
| 上下文压缩 | rerank 过滤、token 截断、去重 | `agentic_context.py` ContextMixin |
| 质量评估 | 置信度门控、答案反思 | `agentic_quality.py` QualityMixin |
| 受限文档检查 | 权限级别感知的文档过滤 | `engine.py` check_restricted_documents() |

> **总结**：两个分支在引擎层（engine.py）的检索能力基本一致。差异在于上层管道编排——main 在 chat_routes.py 中增加了表格救援、语义缓存等管道函数；server-release 则通过 AgenticRAG 模块化系统实现了查询改写、上下文压缩等能力。这些差异不影响 API 端口定义。

### 3. 认证增强

| 端点 | 变更说明 |
|------|----------|
| `POST /auth/login` | 新增 IP 速率限制（频繁登录返回 HTTP 429） |
| `POST /auth/change-password` | 新增旧密码验证（server-release 不验证旧密码） |

---

## 三、全局响应格式变更

main 分支将所有端点的响应统一为 `success_response()` / `error_response()` 封装格式。

**server-release 响应格式**（部分端点使用原始 jsonify）：
```json
{
  "contexts": ["..."],
  "metadatas": [...],
  "scores": [0.99]
}
```

**main 分支响应格式**（统一封装）：
```json
{
  "success": true,
  "status": "success",
  "status_code": 2000,
  "message": "查询成功",
  "data": {
    "contexts": ["..."],
    "metadatas": [...],
    "scores": [0.99]
  }
}
```

> **⚠️ Breaking Change**：如果后端直接读取响应顶层字段（如 `response.contexts`），迁移到 main 后需要改为 `response.data.contexts`。建议后端统一使用 `response.data` 访问实际数据。

---

## 四、新增状态码

| 状态码 | 常量名 | 说明 |
|--------|--------|------|
| 4014 | `TASK_NOT_FOUND` | 任务不存在 |
| 4015 | `TASK_CONFLICT` | 任务冲突（如重复触发同步） |
| 5040 | `REINDEX_ERROR` | 重建索引失败 |

---

## 五、架构差异总结

| 维度 | server-release | main |
|------|----------------|------|
| 长操作模式 | 同步阻塞 | 异步任务 + task_id 轮询 |
| 响应格式 | 混合（jsonify + success_response） | 统一 success_response 封装 |
| RAG 引擎层 | 相同（engine.py 已同步） | 相同 |
| RAG 管道层 | AgenticRAG 模块化编排（查询改写/上下文压缩/质量评估） | chat_routes.py 单体管道（语义缓存/表格救援/图片过滤） |
| 会话管理 | 无状态 | SQLite 会话存储（可选） |
| 审计日志 | 无 | 操作审计记录 |
| 缓存系统 | LRU（语义缓存已初始化但未接入流程） | LRU + 语义缓存（完整闭环） |
| 认证安全 | 基础 | IP 速率限制 + 旧密码验证 |
| 核心架构 | AgenticRAG 多模块 + engine.py | 统一 engine.py + chat_routes.py 管道 |

---

## 六、迁移注意事项

如果后续需要将 main 分支部署到服务器，需要注意：

1. **后端适配**：后端组需要修改调用方式，从同步等待结果改为轮询 `GET /tasks/<task_id>`。建议轮询间隔 1-2 秒。

2. **响应格式**：所有接口响应统一为 `{success, status, status_code, message, data}` 格式，前端/后端需要从 `data` 字段读取实际数据。

3. **配置项**：新增 `ENABLE_SESSION`、`ENABLE_FEEDBACK` 等开关，需要确认生产环境配置。

4. **RAG 管道差异**：main 和 server-release 的 RAG 增强方向不同（main 侧重语义缓存/表格救援，server-release 侧重模块化查询改写/上下文压缩），但不影响 API 端口兼容性。迁移时两者的检索效果可能略有差异，需要做效果对比测试。

5. **兼容性**：如果暂不迁移后端，可以只在 main 分支上保持同步模式（通过环境变量开关），避免 breaking change。