shudao-main/shudao-chat-py/接口对齐报告.md

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层面做路由转发，兼容两种前缀

  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个