# shudao-chat-py 与 shudao-go-backend 接口对齐报告

## 一、路由前缀差异

| 版本 | 路由前缀 | 说明 |
|------|---------|------|
| Go版本 | `/apiv1` | 统一前缀 |
| Python版本 | `/api/{module}` | 模块化前缀（auth/chat/scene等） |

---

## 二、已对齐接口（核心业务）

### 2.1 聊天相关（11个已对齐）

| Go接口 | Python接口 | 状态 |
|--------|-----------|------|
| POST /apiv1/send_deepseek_message | POST /api/chat/send_deepseek_message | ✅ 已对齐 |
| GET /apiv1/get_history_record | GET /api/chat/get_history_record | ✅ 已对齐 |
| POST /apiv1/delete_conversation | POST /api/chat/delete_conversation | ✅ 已对齐 |
| POST /apiv1/delete_history_record | POST /api/chat/delete_history_record | ✅ 已对齐 |
| POST /apiv1/stream/chat | POST /api/chat/stream/chat | ✅ 已对齐 |
| POST /apiv1/stream/chat-with-db | POST /api/chat/stream/chat-with-db | ✅ 已对齐 |
| POST /apiv1/guess_you_want | POST /api/chat/guess_you_want | ✅ 已对齐 |
| GET /apiv1/online_search | GET /api/chat/online_search | ✅ 已对齐 |
| POST /apiv1/save_online_search_result | POST /api/chat/save_online_search_result | ✅ 已对齐 |
| POST /apiv1/intent_recognition | POST /api/chat/intent_recognition | ✅ 已对齐 |
| POST /apiv1/save_ppt_outline | POST /api/chat/save_ppt_outline | ✅ 已对齐 |
| POST /apiv1/save_edit_document | POST /api/chat/save_edit_document | ✅ 已对齐 |
| GET /apiv1/get_user_recommend_question | GET /api/chat/get_user_recommend_question | ✅ 已对齐 |

### 2.2 考试相关（4个已对齐）

| Go接口 | Python接口 | 状态 |
|--------|-----------|------|
| POST /apiv1/exam/build_prompt | POST /api/exam/build_prompt | ✅ 已对齐 |
| POST /apiv1/exam/build_single_prompt | POST /api/exam/build_single_prompt | ✅ 已对齐 |
| POST /apiv1/re_modify_question | POST /api/exam/re_modify_question | ✅ 已对齐 |
| POST /apiv1/re_produce_single_question | POST /api/exam/re_produce_single_question | ✅ 已对齐 |

### 2.3 隐患识别相关（2个已对齐）

| Go接口 | Python接口 | 状态 |
|--------|-----------|------|
| POST /apiv1/hazard | POST /api/hazard/hazard | ✅ 已对齐 |
| POST /apiv1/save_step | POST /api/hazard/save_step | ✅ 已对齐 |

### 2.4 场景相关（4个已对齐）

| Go接口 | Python接口 | 状态 |
|--------|-----------|------|
| GET /apiv1/get_history_recognition_record | GET /api/scene/get_history_recognition_record | ✅ 已对齐 |
| GET /apiv1/get_recognition_record_detail | GET /api/scene/get_recognition_record_detail | ✅ 已对齐 |
| GET /apiv1/get_third_scene_example_image | GET /api/scene/get_third_scene_example_image | ✅ 已对齐 |
| GET /apiv1/get_latest_recognition_record | GET /api/scene/get_latest_recognition_record | ✅ 已对齐 |
| POST /apiv1/submit_evaluation | POST /api/scene/submit_evaluation | ✅ 已对齐 |

### 2.5 埋点相关（4个已对齐）

| Go接口 | Python接口 | 状态 |
|--------|-----------|------|
| POST /apiv1/tracking/record | POST /api/tracking/record | ✅ 已对齐 |
| GET /apiv1/tracking/records | GET /api/tracking/records | ✅ 已对齐 |
| POST /apiv1/tracking/api_mapping | POST /api/tracking/api_mapping | ✅ 已对齐 |
| GET /apiv1/tracking/api_mappings | GET /api/tracking/api_mappings | ✅ 已对齐 |

### 2.6 通用数据相关（3个已对齐）

| Go接口 | Python接口 | 状态 |
|--------|-----------|------|
| GET /apiv1/get_hot_question | GET /api/total/get_hot_question | ✅ 已对齐 |
| GET /apiv1/recommend_question | GET /api/total/get_recommend_question | ✅ 已对齐 |
| GET /apiv1/get_user_data_id | GET /api/total/get_user_data_id | ✅ 已对齐 |

### 2.7 积分相关（1个已对齐）

| Go接口 | Python接口 | 状态 |
|--------|-----------|------|
| GET /apiv1/points/balance | GET /api/points/balance | ✅ 已对齐 |

---

## 三、Python版本缺失的Go接口（需补充）

### 3.1 认证相关（1个缺失）

| Go接口 | 说明 | 优先级 |
|--------|------|--------|
| POST /apiv1/auth/local_login | 本地登录接口 | 🔴 高（Python用的是/login） |

### 3.2 聊天相关（2个缺失）

| Go接口 | 说明 | 优先级 |
|--------|------|--------|
| GET /apiv1/get_file_link | 根据文件名获取链接 | 🟡 中 |
| GET /apiv1/get_chromadb_document | 获取ChromaDB文档并生成回答 | 🟡 中 |

### 3.3 OSS相关（3个缺失）

| Go接口 | 说明 | 优先级 |
|--------|------|--------|
| POST /apiv1/oss/shudao/upload_image | 上传图片专用接口 | 🟢 低（有通用upload） |
| POST /apiv1/oss/shudao/upload_json | 上传JSON文件专用接口 | 🟢 低（有通用upload） |
| GET /apiv1/oss/parse | OSS代理解析接口 | 🟡 中（Python有oss_proxy） |

### 3.4 功能推荐相关（1个缺失）

| Go接口 | 说明 | 优先级 |
|--------|------|--------|
| GET /apiv1/get_function_card | 返回四条功能卡片 | 🟡 中 |

### 3.5 反馈评价相关（2个缺失）

| Go接口 | 说明 | 优先级 |
|--------|------|--------|
| POST /apiv1/submit_feedback | 提交意见反馈 | 🔴 高 |
| POST /apiv1/like_and_dislike | 点赞和踩功能 | 🔴 高 |

### 3.6 政策文件相关（3个全部缺失）

| Go接口 | 说明 | 优先级 |
|--------|------|--------|
| GET /apiv1/get_policy_file | 返回政策文件 | 🔴 高 |
| GET /apiv1/download_file | 文件下载接口 | 🔴 高 |
| POST /apiv1/policy_file_count | 政策文件查看和下载次数统计 | 🟡 中 |

### 3.7 知识库相关（1个缺失）

| Go接口 | 说明 | 优先级 |
|--------|------|--------|
| GET /apiv1/knowledge/files/advanced-search | 知识库文件高级搜索 | 🟡 中 |

### 3.8 积分系统相关（2个缺失）

| Go接口 | 说明 | 优先级 |
|--------|------|--------|
| POST /apiv1/points/consume | 消费积分 | 🔴 高（Python用deduct） |
| GET /apiv1/points/history | 获取消费历史 | 🟡 中（Python用records） |

---

## 四、Python版本新增接口（Go版本没有）

### 4.1 认证增强（4个新增）

| Python接口 | 说明 | 备注 |
|-----------|------|------|
| POST /api/auth/register | 用户注册 | ✨ 功能增强 |
| GET /api/auth/user_info | 获取用户信息 | ✨ 功能增强 |
| POST /api/auth/change_password | 修改密码 | ✨ 功能增强 |
| POST /api/auth/update_user_info | 更新用户信息 | ✨ 功能增强 |

### 4.2 场景管理增强（9个新增）

| Python接口 | 说明 | 备注 |
|-----------|------|------|
| GET /api/scene/get_scene_list | 获取场景列表 | ✨ 新增场景树 |
| GET /api/scene/get_first_scene_list | 获取一级场景列表 | ✨ 新增场景树 |
| GET /api/scene/get_second_scene_list | 获取二级场景列表 | ✨ 新增场景树 |
| GET /api/scene/get_third_scene_list | 获取三级场景列表 | ✨ 新增场景树 |
| POST /api/scene/delete_recognition_record | 删除识别记录 | ✨ 功能增强 |
| POST /api/scene/scene_template | 创建场景模板 | ✨ 模板管理 |
| GET /api/scene/scene_templates | 获取场景模板列表 | ✨ 模板管理 |
| GET /api/scene/recognition_records | 获取识别记录列表（REST风格） | ✨ 功能增强 |

### 4.3 积分系统增强（2个新增）

| Python接口 | 说明 | 备注 |
|-----------|------|------|
| POST /api/points/add | 添加积分（管理员） | ✨ 管理功能 |
| POST /api/points/deduct | 扣除积分 | ✨ 替代consume |

### 4.4 通用数据增强（1个新增）

| Python接口 | 说明 | 备注 |
|-----------|------|------|
| POST /api/total/click_hot_question | 记录热门问题点击 | ✨ 统计功能 |

### 4.5 文件管理增强（1个新增）

| Python接口 | 说明 | 备注 |
|-----------|------|------|
| GET /api/file/get_oss_proxy_url | 获取加密的OSS代理URL | ✨ 安全增强 |

### 4.6 知识库增强（2个新增）

| Python接口 | 说明 | 备注 |
|-----------|------|------|
| POST /api/knowledge/add_documents | 向知识库添加文档 | ✨ 管理功能 |
| POST /api/knowledge/delete_documents | 从知识库删除文档 | ✨ 管理功能 |

---

## 五、接口差异分析

### 5.1 命名差异

| 功能 | Go接口 | Python接口 | 差异说明 |
|------|--------|-----------|----------|
| 登录 | /apiv1/auth/local_login | /api/auth/login | 名称简化 |
| 积分扣除 | /apiv1/points/consume | /api/points/deduct | 语义更明确 |
| 积分历史 | /apiv1/points/history | /api/points/records | 名称统一 |
| 推荐问题 | /apiv1/recommend_question | /api/total/get_recommend_question | 加get前缀 |

### 5.2 功能差异

| 功能模块 | Go版本特点 | Python版本特点 |
|---------|-----------|---------------|
| 认证系统 | 仅登录 | 完整用户管理（注册、信息修改等） |
| 场景管理 | 基础识别记录 | 完整场景树（一/二/三级）+ 模板管理 |
| 积分系统 | 余额+消费+历史 | 余额+记录+增减（管理员） |
| 政策文件 | 完整功能 | ❌ 缺失 |
| 反馈评价 | 完整功能 | ❌ 缺失 |
| 知识库 | 高级搜索 | 基础检索+文档管理 |

---

## 六、优先级修复建议

### 🔴 高优先级（核心业务缺失）

1. **政策文件模块**（3个接口）
   - GET /api/total/get_policy_file
   - GET /api/total/download_file
   - POST /api/total/policy_file_count

2. **反馈评价模块**（2个接口）
   - POST /api/total/submit_feedback
   - POST /api/total/like_and_dislike

3. **删除识别记录**（Go版本在ChatController，Python在SceneController）
   - 需统一位置：建议保留在SceneController

### 🟡 中优先级（功能增强）

1. **功能卡片**
   - GET /api/total/get_function_card

2. **ChromaDB文档获取**
   - GET /api/chat/get_chromadb_document

3. **知识库高级搜索**
   - GET /api/knowledge/files/advanced-search

4. **文件链接获取**
   - GET /api/chat/get_file_link

### 🟢 低优先级（可选优化）

1. **OSS专用上传接口**（已有通用upload）
   - POST /api/file/oss/shudao/upload_image
   - POST /api/file/oss/shudao/upload_json

---

## 七、对齐统计

| 统计项 | Go版本 | Python版本 | 已对齐 | 差异 |
|-------|--------|-----------|--------|------|
| API接口总数 | 47个 | 55个 | 30个 | 25个 |
| Go缺失接口 | - | - | - | 19个 |
| Python缺失接口 | - | - | - | 17个 |
| 对齐率 | - | - | 63.8% | - |

---

## 八、下一步行动建议

### 阶段一：核心功能对齐（1-2周）

1. **补充政策文件模块**
   - 创建 routers/policy.py
   - 实现3个政策文件接口
   - 对接数据库表

2. **补充反馈评价模块**
   - 扩展 routers/total.py
   - 实现反馈和点赞接口
   - 对接数据库表

3. **统一删除识别记录接口位置**
   - 确认保留在 routers/scene.py
   - 更新文档说明

### 阶段二：功能增强对齐（2-3周）

1. **补充功能卡片接口**
2. **补充ChromaDB文档获取**
3. **补充知识库高级搜索**
4. **补充文件链接获取**

### 阶段三：优化与标准化（1周）

1. **统一路由命名规范**
2. **统一响应格式**
3. **完善接口文档**
4. **编写集成测试**

---

## 九、重要说明

### 9.1 路由前缀差异处理

- **建议**：在Nginx层面做路由转发，兼容两种前缀
  ```nginx
  location /apiv1/ {
      rewrite ^/apiv1/(.*)$ /api/$1 last;
  }
  ```

### 9.2 接口版本管理

- Go版本：`/apiv1`
- Python版本：`/api`（建议后续改为 `/api/v1`）

### 9.3 数据库兼容性

- Python版本需确保与Go版本共享同一数据库
- 关注数据表结构一致性
- 注意时间戳字段（Go可能用time.Time，Python用int）

---

**生成时间**: 2026/4/3
**版本**: v1.0
**对齐率**: 63.8%
**待补充接口**: 17个