# shudao-chat-py 接口列表

## 1. 认证模块 (routers/auth.py)

| 序号 | 方法 | 路径 | 说明 | 认证要求 |
|------|------|------|------|----------|
| 1.1 | POST | /login | 用户登录 | 否 |
| 1.2 | POST | /register | 用户注册 | 否 |
| 1.3 | POST | /refresh | 刷新token | 否 |
| 1.4 | POST | /logout | 用户登出 | 是 |
| 1.5 | GET | /profile | 获取用户信息 | 是 |
| 1.6 | PUT | /profile | 更新用户信息 | 是 |
| 1.7 | POST | /reset_password | 重置密码 | 是 |

## 2. 聊天模块 (routers/chat.py)

| 序号 | 方法 | 路径 | 说明 | 认证要求 |
|------|------|------|------|----------|
| 2.1 | POST | /chat | AI对话（SSE流式） | 是 |
| 2.2 | GET | /get_conversation | 获取对话记录 | 是 |
| 2.3 | DELETE | /delete_conversation | 删除对话 | 是 |
| 2.4 | POST | /clear_conversation | 清空对话 | 是 |
| 2.5 | POST | /guess_question | 猜你想问 | 是 |
| 2.6 | POST | /image_to_text | 图片识别 | 是 |
| 2.7 | POST | /image_to_text_stream | 图片识别（流式） | 是 |
| 2.8 | POST | /generate_ppt_outline | 生成PPT大纲 | 是 |
| 2.9 | POST | /generate_document | 生成公文 | 是 |
| 2.10 | POST | /save_ppt_outline | 保存PPT大纲 | 是 |
| 2.11 | POST | /save_edit_document | 保存编辑公文 | 是 |
| 2.12 | POST | /advanced_search | 高级搜索 | 是 |

## 3. 考试模块 (routers/exam.py)

| 序号 | 方法 | 路径 | 说明 | 认证要求 |
|------|------|------|------|----------|
| 3.1 | POST | /exam/build_prompt | 生成考试提示词 | 是 |
| 3.2 | POST | /exam/build_single_prompt | 生成单题提示词 | 是 |
| 3.3 | POST | /re_modify_question | 修改考试题目 | 是 |
| 3.4 | POST | /re_produce_single_question | 重新生成单题 | 是 |

## 4. 文件模块 (routers/file.py)

| 序号 | 方法 | 路径 | 说明 | 认证要求 |
|------|------|------|------|----------|
| 4.1 | POST | /oss/upload | OSS上传 | 是 |
| 4.2 | POST | /oss/shudao/upload_image | 上传图片 | 是 |
| 4.3 | POST | /oss/shudao/upload_json | 上传JSON文件 | 是 |
| 4.4 | GET | /oss/parse | OSS解析 | 是 |
| 4.5 | GET | /get_file_link | 获取文件链接 | 是 |

## 5. 隐患识别模块 (routers/hazard.py)

| 序号 | 方法 | 路径 | 说明 | 认证要求 |
|------|------|------|------|----------|
| 5.1 | POST | /hazard | 隐患识别 | 是 |
| 5.2 | POST | /save_step | 保存识别步骤 | 是 |

## 6. 知识库模块 (routers/knowledge.py)

| 序号 | 方法 | 路径 | 说明 | 认证要求 |
|------|------|------|------|----------|
| 6.1 | GET | /get_chromadb_document | 获取ChromaDB文档 | 否 |
| 6.2 | GET | /knowledge/files/advanced-search | 知识库高级搜索 | 否 |

## 7. 积分模块 (routers/points.py)

| 序号 | 方法 | 路径 | 说明 | 认证要求 |
|------|------|------|------|----------|
| 7.1 | GET | /points/balance | 获取积分余额 | 是 |
| 7.2 | POST | /points/consume | 消费积分 | 是 |
| 7.3 | POST | /points/add | 增加积分（管理员） | 是（管理员） |
| 7.4 | GET | /points/logs | 获取积分消费记录 | 是 |
| 7.5 | GET | /points/history | 获取积分消费记录（同logs） | 是 |

## 8. 场景模块 (routers/scene.py)

| 序号 | 方法 | 路径 | 说明 | 认证要求 |
|------|------|------|------|----------|
| 8.1 | GET | /get_scene_list | 获取场景列表 | 否 |
| 8.2 | GET | /get_first_scene_list | 获取一级场景列表 | 否 |
| 8.3 | GET | /get_second_scene_list | 获取二级场景列表 | 否 |
| 8.4 | GET | /get_third_scene_list | 获取三级场景列表 | 否 |
| 8.5 | GET | /get_third_scene_example_image | 获取三级场景示例图 | 否 |
| 8.6 | GET | /get_history_recognition_record | 获取隐患识别历史记录 | 是 |
| 8.7 | GET | /get_recognition_record_detail | 获取识别记录详情 | 否 |
| 8.8 | POST | /delete_recognition_record | 删除识别记录 | 是 |
| 8.9 | POST | /submit_evaluation | 提交点评 | 否 |
| 8.10 | GET | /get_latest_recognition_record | 获取最新识别记录 | 是 |
| 8.11 | POST | /scene_template | 创建场景模板 | 否 |
| 8.12 | GET | /scene_templates | 获取场景模板列表 | 否 |
| 8.13 | GET | /recognition_records | 获取识别记录列表（分页+筛选） | 是 |

## 9. 通用模块 (routers/total.py)

| 序号 | 方法 | 路径 | 说明 | 认证要求 |
|------|------|------|------|----------|
| 9.1 | GET | /recommend_question | 获取推荐问题 | 否 |
| 9.2 | GET | /get_policy_file | 获取策略文件列表 | 否 |
| 9.3 | GET | /get_function_card | 获取功能卡片 | 否 |
| 9.4 | GET | /get_hot_question | 获取热点问题 | 否 |
| 9.5 | POST | /submit_feedback | 提交意见反馈 | 否 |
| 9.6 | POST | /like_and_dislike | 点赞/踩 | 否 |
| 9.7 | GET | /get_user_data_id | 获取用户数据ID | 是 |
| 9.8 | POST | /get_policy_file_view_and_download_count | 更新政策文件查看计数 | 否 |
| 9.9 | GET | /pdf_oss_download | 流式代理下载OSS文件 | 否 |

## 10. 埋点模块 (routers/tracking.py)

| 序号 | 方法 | 路径 | 说明 | 认证要求 |
|------|------|------|------|----------|
| 10.1 | POST | /tracking/record | 记录埋点 | 是 |
| 10.2 | GET | /tracking/records | 获取埋点记录 | 是 |
| 10.3 | POST | /tracking/api_mapping | 添加API映射 | 是 |
| 10.4 | GET | /tracking/api_mappings | 获取API映射 | 是 |

## 统计信息

- **总接口数**: 60个
- **需要认证**: 32个
- **无需认证**: 28个
- **路由模块**: 10个

## 接口前缀说明

所有接口默认前缀为 `/api/v1`（根据 main.py 配置）

## 认证说明

- 需要认证的接口需要在请求头中携带 `Authorization: Bearer {token}`
- Token 通过 `/login` 接口获取
- Token 过期后可通过 `/refresh` 接口刷新

## 响应格式

所有接口统一返回格式：

```json
{
  "statusCode": 200,
  "msg": "success",
  "data": {}
}
```

## 更新日期

2026年4月3日