# shudao-go-backend 接口测试指南

> 基础地址：`http://localhost:22001`（开发环境）  
> 所有 API 路径前缀：`/apiv1`  
> 认证方式：`Authorization: Bearer <token>`

---

## 一、环境准备

### Postman 环境变量

| 变量名 | 示例值 | 说明 |
|--------|--------|------|
| `base_url` | `http://localhost:22001` | 服务基础地址 |
| `token` | `eyJhbGc...` | 登录后自动保存 |
| `user_id` | `1` | 登录后自动保存 |
| `conversation_id` | `0` | 对话ID，动态更新 |
| `ai_message_id` | `0` | AI消息ID，动态更新 |
| `recognition_record_id` | `0` | 识别记录ID，动态更新 |

### Collection 级别 Pre-request Script（自动注入 Token）

```javascript
const url = pm.request.url.toString();
if (!url.includes('/auth/local_login')) {
    const token = pm.environment.get("token");
    if (token) {
        pm.request.headers.add({ key: 'Authorization', value: 'Bearer ' + token });
    }
}
```

### Collection 级别 Tests Script（统一断言）

```javascript
pm.test("HTTP 200", () => pm.response.to.have.status(200));
pm.test("响应有 statusCode", () => {
    pm.expect(pm.response.json()).to.have.property('statusCode');
});
if (pm.response.json().statusCode === 401) {
    pm.environment.unset("token");
    console.warn("Token 已过期，请重新登录");
}
```

---

## 二、接口测试详情

### 🔐 模块 1：认证

#### 1.1 本地登录
- **路径**：`POST /apiv1/auth/local_login`
- **认证**：不需要

**请求体**：
```json
{
    "username": "admin",
    "password": "password123"
}
```

**Tests 脚本**：
```javascript
const data = pm.response.json();
if (data.statusCode === 200 && data.token) {
    pm.environment.set("token", data.token);
    pm.environment.set("user_id", data.userInfo.id);
}
pm.test("登录成功并获取Token", () => {
    pm.expect(data.statusCode).to.eql(200);
    pm.expect(data.token).to.be.a('string').and.not.empty;
});
```

**预期响应**：
```json
{
    "statusCode": 200,
    "msg": "登录成功",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userInfo": { "id": 1, "username": "admin", "role": "admin" }
}
```

---

### 💬 模块 2：AI 对话

#### 2.1 发送 DeepSeek 消息
- **路径**：`POST /apiv1/send_deepseek_message`

**请求体**：
```json
{
    "message": "如何做好施工现场安全管理？",
    "ai_conversation_id": 0,
    "business_type": 0,
    "exam_name": "",
    "ai_message_id": 0
}
```

**business_type 说明**：

| 值 | 含义 |
|----|------|
| 0 | 通用对话 |
| 1 | 安全培训 |
| 2 | AI 写作 |
| 3 | 考试工坊 |

**Tests 脚本**：
```javascript
const data = pm.response.json();
if (data.data && data.data.ai_conversation_id) {
    pm.environment.set("conversation_id", data.data.ai_conversation_id);
    pm.environment.set("ai_message_id", data.data.ai_message_id);
}
pm.test("消息发送成功", () => pm.expect(data.statusCode).to.eql(200));
```

#### 2.2 获取历史记录
- **路径**：`GET /apiv1/get_history_record`
- **Query 参数**：`ai_conversation_id=0&business_type=0`
- **说明**：`ai_conversation_id=0` 返回对话列表；传具体 ID 返回该对话的消息详情

#### 2.3 删除对话（单轮消息对）
- **路径**：`POST /apiv1/delete_conversation`
- **说明**：传入 AI 回复消息的 ID，会同时软删除该 AI 消息及对应的用户消息

**请求体**：
```json
{
    "ai_conversation_id": 456
}
```

#### 2.4 删除历史记录（整个对话）
- **路径**：`POST /apiv1/delete_history_record`

**请求体**：
```json
{
    "ai_conversation_id": 123
}
```

#### 2.5 删除隐患识别历史记录
- **路径**：`POST /apiv1/delete_recognition_record`

**请求体**：
```json
{
    "recognition_id": 123
}
```

#### 2.6 猜你想问
- **路径**：`POST /apiv1/guess_you_want`

**请求体**：
```json
{
    "message": "安全帽",
    "ai_message_id": 456,
    "business_type": 0
}
```

#### 2.7 用户输入推荐问题
- **路径**：`GET /apiv1/get_user_recommend_question`
- **Query 参数**：`user_message=安全帽`

#### 2.8 根据文件名获取链接
- **路径**：`GET /apiv1/get_file_link`
- **Query 参数**：`fileName=建筑施工安全检查标准.pdf`（注意大写 N）

#### 2.9 保存 PPT 大纲
- **路径**：`POST /apiv1/save_ppt_outline`

**请求体**：
```json
{
    "ai_conversation_id": 123,
    "ppt_outline": "{\"title\":\"安全培训PPT\",\"slides\":[]}",
    "ppt_content": "<完整PPT内容字符串>"
}
```

#### 2.10 AI 写作保存编辑文档
- **路径**：`POST /apiv1/save_edit_document`

**请求体**：
```json
{
    "ai_conversation_id": 123,
    "content": "编辑后的文档内容..."
}
```

#### 2.11 联网搜索
- **路径**：`GET /apiv1/online_search`
- **Query 参数**：`keywords=建筑施工安全规范 2026`（注意是 keywords 复数）

#### 2.12 保存联网搜索结果
- **路径**：`POST /apiv1/save_online_search_result`
- **说明**：`id` 为 AI 消息 ID，`search_source` 为联网搜索结果内容

**请求体**：
```json
{
    "id": 456,
    "ai_conversation_id": 123,
    "search_source": "[{\"title\":\"...\",\"url\":\"...\",\"content\":\"...\"}]"
}
```

#### 2.13 意图识别
- **路径**：`POST /apiv1/intent_recognition`

**请求体**：
```json
{
    "message": "帮我写一份安全生产月活动方案",
    "ai_conversation_id": 0,
    "business_type": 0
}
```

**预期响应**（非知识库查询，直接返回答案）：
```json
{
    "statusCode": 200,
    "data": {
        "intent_result": { "intent": "faq", "confidence": 0.9 },
        "direct_answer": "安全生产月活动方案包括...",
        "ai_conversation_id": 123,
        "ai_message_id": 456,
        "is_online_search": 0
    }
}
```

**预期响应**（知识库查询，需前端继续调用 RAG）：
```json
{
    "statusCode": 200,
    "data": {
        "intent_result": { "intent": "query_knowledge_base", "search_queries": ["高处作业安全规范"] },
        "is_online_search": 1
    }
}
```

#### 2.14 获取 ChromaDB 文档
- **路径**：`GET /apiv1/get_chromadb_document`
- **Query 参数**：`message=高处作业安全规范`

#### 2.15 重新生成单题
- **路径**：`POST /apiv1/re_produce_single_question`

**请求体**：
```json
{
    "message": "请重新生成一道关于高处作业安全的单选题"
}
```

---

### 🌐 模块 3：流式接口

> ⚠️ Postman 对 SSE 流式响应支持有限，推荐使用 curl 或浏览器测试页面。

#### 3.1 流式聊天
- **路径**：`POST /apiv1/stream/chat`
- **浏览器测试页面**：`http://localhost:22001/stream-test`

**curl 测试命令**：
```bash
curl -X POST "http://localhost:22001/apiv1/stream/chat" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"如何做好施工现场安全管理？","ai_conversation_id":0,"business_type":0}' \
  --no-buffer
```

**响应格式**（SSE）：
```
data: {"content":"施工现场"}
data: {"content":"安全管理"}
data: [DONE]
```

#### 3.2 流式聊天（数据库集成）
- **路径**：`POST /apiv1/stream/chat-with-db`
- **浏览器测试页面**：`http://localhost:22001/stream-chat-with-db-test`

**curl 测试命令**：
```bash
curl -X POST "http://localhost:22001/apiv1/stream/chat-with-db" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"施工安全要点","ai_conversation_id":0,"business_type":0}' \
  --no-buffer
```

---

### 📋 模块 4：通用功能

#### 4.1 获取推荐问题
- **路径**：`GET /apiv1/recommend_question`
- **Query 参数**：`limit=5`（可选，默认 5）

#### 4.2 获取热点问题
- **路径**：`GET /apiv1/get_hot_question`
- **Query 参数**：`question_type=0`（0=AI问答，1=安全培训）

#### 4.3 获取功能卡片
- **路径**：`GET /apiv1/get_function_card`
- **Query 参数**：`function_type=0`（0=AI问答，1=安全培训）

#### 4.4 提交意见反馈
- **路径**：`POST /apiv1/submit_feedback`

**请求体**：
```json
{
    "content": "建议增加语音输入功能"
}
```

#### 4.5 点赞/踩
- **路径**：`POST /apiv1/like_and_dislike`
- **说明**：`user_feedback` 为整数，1=点赞，-1=踩，0=取消

**请求体**：
```json
{
    "id": 456,
    "user_feedback": 1
}
```

#### 4.6 获取政策文件
- **路径**：`GET /apiv1/get_policy_file`
- **Query 参数**：`page=1&pageSize=10&search=安全&policy_type=0`
- **说明**：`policy_type=0` 表示全部类型

#### 4.7 文件下载
- **路径**：`GET /apiv1/download_file`
- **Query 参数**：`pdf_oss_download_link=<OSS文件URL>&file_name=建筑施工安全检查标准.pdf`
- **说明**：直接流式返回文件内容，非 JSON 响应

#### 4.8 政策文件查看/下载统计
- **路径**：`POST /apiv1/policy_file_count`
- **说明**：`action_type` 为整数，1=查看，2=下载

**请求体**：
```json
{
    "policy_file_id": 1,
    "action_type": 1
}
```

#### 4.9 获取用户数据 ID
- **路径**：`GET /apiv1/get_user_data_id`
- **说明**：无需参数，从 Token 中自动获取 `account_id` 查询

---

### 📝 模块 5：考试工坊

> ⚠️ 考试工坊接口的具体请求体字段需以实际 controllers/exam.go 为准，以下为参考示例。

#### 5.1 生成考试提示词
- **路径**：`POST /apiv1/exam/build_prompt`

**请求体**：
```json
{
    "mode": "ai",
    "client": "pc",
    "projectType": "工程",
    "examTitle": "施工安全员考试",
    "totalScore": 100,
    "questionTypes": [
        {
            "name": "单选题",
            "romanNumeral": "一",
            "questionCount": 10,
            "scorePerQuestion": 2
        }
    ],
    "pptContent": ""
}
```

#### 5.2 单题生成提示词
- **路径**：`POST /apiv1/exam/build_single_prompt`

**请求体**：
```json
{
    "client": "pc",
    "sectionType": "single",
    "questionIndex": 0,
    "projectType": "工程",
    "questionType": "单选题",
    "scorePerQuestion": 2,
    "currentQuestion": {}
}
```

#### 5.3 修改考试题目
- **路径**：`POST /apiv1/re_modify_question`

**请求体**：
```json
{
    "ai_conversation_id": 123,
    "content": "修改后的题目内容..."
}
```

---

### 🔍 模块 6：隐患识别

#### 6.1 隐患识别
- **路径**：`POST /apiv1/hazard`

**请求体**：
```json
{
    "scene_name": "隧道",
    "image": "https://oss.example.com/images/site.jpg",
    "date": "2026-04-07"
}
```

**Tests 脚本**：
```javascript
const data = pm.response.json();
if (data.data && data.data.recognition_record_id) {
    pm.environment.set("recognition_record_id", data.data.recognition_record_id);
}
pm.test("识别成功", () => pm.expect(data.statusCode).to.eql(200));
```

#### 6.2 保存流程步骤（如 PPT 生成）
- **路径**：`POST /apiv1/save_step`

**请求体**：
```json
{
    "ai_conversation_id": 123,
    "step": 2,
    "ppt_json_url": "https://oss.example.com/ppt.json",
    "cover_image": "https://oss.example.com/cover.jpg",
    "ppt_json_content": "{...}"
}
```

#### 6.3 获取历史识别记录
- **路径**：`GET /apiv1/get_history_recognition_record`

#### 6.4 获取识别记录详情
- **路径**：`GET /apiv1/get_recognition_record_detail`
- **Query 参数**：`recognition_record_id=123`

#### 6.5 获取三级场景示例图
- **路径**：`GET /apiv1/get_third_scene_example_image`
- **Query 参数**：`third_scene_name=未系安全带`

#### 6.6 提交点评
- **路径**：`POST /apiv1/submit_evaluation`

**请求体**：
```json
{
    "id": 123,
    "scene_match": 1,
    "tip_accuracy": 1,
    "effect_evaluation": 1,
    "user_remark": "识别准确"
}
```

**评分字段说明**：

| 字段 | 0 | 1 | 2 |
|------|---|---|---|
| scene_match | 未评价 | 匹配 | 不匹配 |
| tip_accuracy | 未评价 | 准确 | 不准确 |
| effect_evaluation | 未评价 | 满意 | 不满意 |

#### 6.7 查询最新识别记录是否已点评
- **路径**：`GET /apiv1/get_latest_recognition_record`

---

### 📁 模块 7：OSS 文件存储

#### 7.1 上传图片
- **路径**：`POST /apiv1/oss/shudao/upload_image`
- **Content-Type**：`multipart/form-data`

**Postman Body 设置**：
- 选择 `form-data`
- Key: `file`，Type: `File`，Value: 选择本地图片

**Tests 脚本**：
```javascript
const data = pm.response.json();
if (data.data && data.data.url) {
    pm.environment.set("image_url", data.data.url);
}
pm.test("图片上传成功", () => pm.expect(data.statusCode).to.eql(200));
```

#### 7.2 上传 PPT JSON 文件
- **路径**：`POST /apiv1/oss/shudao/upload_json`

**请求体**：
```json
{
    "content": {
        "title": "安全培训PPT",
        "slides": [
            { "title": "第一章：安全生产基础", "content": "..." }
        ]
    }
}
```

#### 7.3 生成 S3 预签名上传凭证
- **路径**：`POST /apiv1/oss/upload`

**请求体**：
```json
{
    "file_name": "example.jpg",
    "file_type": "image/jpeg"
}
```

#### 7.4 OSS 代理解析
- **路径**：`GET /apiv1/oss/parse`
- **认证**：不需要
- **Query 参数**：`url=https://oss.example.com/images/example.jpg`

> 直接返回文件内容（图片/PDF），用于解决跨域访问问题。

---

### 🔎 模块 8：知识库检索

#### 8.1 知识库文件高级搜索
- **路径**：`GET /apiv1/knowledge/files/advanced-search`
- **Query 参数**：`query=高处作业安全规范&top_k=5`

---

### 📊 模块 9：埋点跟踪

#### 9.1 记录埋点
- **路径**：`POST /apiv1/tracking/record`

**请求体**：
```json
{
    "api_path": "/apiv1/send_deepseek_message",
    "method": "POST",
    "extra_data": "附加数据"
}
```

#### 9.2 获取埋点记录列表
- **路径**：`GET /apiv1/tracking/records`
- **Query 参数**：`page=1&pageSize=20&start_date=2026-04-01&end_date=2026-04-07`

#### 9.3 添加接口路径映射
- **路径**：`POST /apiv1/tracking/api_mapping`

**请求体**：
```json
{
    "api_path": "/apiv1/send_deepseek_message",
    "api_name": "发送AI消息",
    "api_desc": "用于发送 AI 会话的消息"
}
```

#### 9.4 获取接口路径映射列表
- **路径**：`GET /apiv1/tracking/api_mappings`

---

### 💰 模块 10：积分系统

#### 10.1 获取积分余额
- **路径**：`GET /apiv1/points/balance`

**Tests 脚本**：
```javascript
const data = pm.response.json();
pm.test("积分余额查询成功", () => {
    pm.expect(data.statusCode).to.eql(200);
    pm.expect(data.data.points).to.be.a('number').and.at.least(0);
});
pm.environment.set("current_points", data.data.points);
```

#### 10.2 消费积分下载文件
- **路径**：`POST /apiv1/points/consume`

**请求体**：
```json
{
    "file_name": "建筑施工安全检查标准.pdf",
    "file_url": "https://oss.example.com/files/standard.pdf"
}
```

**Tests 脚本**：
```javascript
const data = pm.response.json();
if (data.statusCode === 200) {
    pm.test("积分消费成功", () => {
        pm.expect(data.data.points_consumed).to.eql(10);
        const before = parseInt(pm.environment.get("current_points"));
        pm.expect(data.data.new_balance).to.eql(before - 10);
    });
} else if (data.statusCode === 400) {
    pm.test("积分不足提示正确", () => pm.expect(data.msg).to.include("积分不足"));
}
```

#### 10.3 获取消费记录
- **路径**：`GET /apiv1/points/history`
- **Query 参数**：`page=1&pageSize=10`

---

## 三、完整测试流程

### 流程 A：基础对话测试

```
1. POST /apiv1/auth/local_login          → 获取 Token
2. GET  /apiv1/recommend_question        → 查看推荐问题（limit=5）
3. GET  /apiv1/get_hot_question          → 查看热点问题（question_type=0）
4. GET  /apiv1/get_function_card         → 查看功能卡片（function_type=0）
5. POST /apiv1/send_deepseek_message     → 发送消息（保存 conversation_id, ai_message_id）
6. POST /apiv1/like_and_dislike          → 对回复点赞（id=ai_message_id, user_feedback=1）
7. GET  /apiv1/get_history_record        → 查看历史记录（business_type=0）
8. POST /apiv1/delete_history_record     → 删除整个对话（ai_conversation_id=xxx）
```

### 流程 B：隐患识别测试

```
1. POST /apiv1/auth/local_login                    → 获取 Token
2. POST /apiv1/oss/shudao/upload_image             → 上传图片（保存 image_url）
3. POST /apiv1/hazard                              → 提交识别（保存 recognition_record_id）
4. GET  /apiv1/get_history_recognition_record      → 查看历史
5. GET  /apiv1/get_recognition_record_detail       → 查看详情
6. GET  /apiv1/get_third_scene_example_image       → 查看示例图
7. GET  /apiv1/get_latest_recognition_record       → 检查是否已点评
8. POST /apiv1/submit_evaluation                   → 提交点评
9. POST /apiv1/delete_recognition_record           → 删除记录
```

### 流程 C：积分消费测试

```
1. POST /apiv1/auth/local_login      → 获取 Token
2. GET  /apiv1/points/balance        → 记录初始积分（需 ≥ 10）
3. GET  /apiv1/get_policy_file       → 查看政策文件列表
4. POST /apiv1/points/consume        → 消费积分下载
5. GET  /apiv1/points/balance        → 验证积分已扣减 10
6. GET  /apiv1/points/history        → 查看消费记录
```

### 流程 D：流式聊天测试

```bash
# 浏览器打开 http://localhost:22001/stream-test

# 或使用 curl：
curl -X POST "http://localhost:22001/apiv1/stream/chat" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"施工安全要点","ai_conversation_id":0,"business_type":0}' \
  --no-buffer
```

---

## 四、常见错误处理

| 状态码 | 含义 | 处理方式 |
|--------|------|---------|
| 200 | 成功 | 正常处理 |
| 400 | 参数错误 / 积分不足 | 检查请求参数 |
| 401 | Token 无效或过期 | 重新调用登录接口 |
| 403 | 权限不足 | 检查用户角色 |
| 500 | 服务器内部错误 | 查看服务器日志 |

**Token 过期响应示例**：
```json
{ "statusCode": 401, "msg": "获取用户信息失败: token已过期" }
```

**积分不足响应示例**：
```json
{
    "statusCode": 400,
    "msg": "积分不足，下载需要10积分",
    "data": { "current_points": 5, "required_points": 10 }
}
```

---

## 五、接口速查表

| 模块 | 方法 | 路径 | 关键参数说明 |
|------|------|------|------|
| 认证 | POST | `/apiv1/auth/local_login` | username, password |
| 对话 | POST | `/apiv1/send_deepseek_message` | message, ai_conversation_id, business_type |
| 对话 | GET | `/apiv1/get_history_record` | ai_conversation_id, business_type |
| 对话 | POST | `/apiv1/delete_conversation` | ai_message_id（AI回复消息ID） |
| 对话 | POST | `/apiv1/delete_history_record` | ai_conversation_id |
| 对话 | POST | `/apiv1/guess_you_want` | message, ai_message_id, business_type |
| 对话 | GET | `/apiv1/get_user_recommend_question` | user_message |
| 对话 | GET | `/apiv1/get_file_link` | fileName（大写N） |
| 对话 | POST | `/apiv1/save_ppt_outline` | ai_conversation_id, ppt_outline, ppt_content |
| 对话 | POST | `/apiv1/save_edit_document` | ai_conversation_id, content |
| 对话 | GET | `/apiv1/online_search` | keywords（复数） |
| 对话 | POST | `/apiv1/save_online_search_result` | id(ai_message_id), ai_conversation_id, search_source |
| 对话 | POST | `/apiv1/intent_recognition` | message, ai_conversation_id, business_type |
| 对话 | GET | `/apiv1/get_chromadb_document` | message |
| 对话 | POST | `/apiv1/re_produce_single_question` | message |
| 流式 | POST | `/apiv1/stream/chat` | message, ai_conversation_id, business_type |
| 流式 | POST | `/apiv1/stream/chat-with-db` | message, ai_conversation_id, business_type |
| 通用 | GET | `/apiv1/recommend_question` | limit（默认5） |
| 通用 | GET | `/apiv1/get_hot_question` | question_type（0/1） |
| 通用 | GET | `/apiv1/get_function_card` | function_type（0/1） |
| 通用 | POST | `/apiv1/submit_feedback` | content |
| 通用 | POST | `/apiv1/like_and_dislike` | id, user_feedback（整数1/-1/0） |
| 通用 | GET | `/apiv1/get_policy_file` | page, pageSize, search, policy_type |
| 通用 | GET | `/apiv1/download_file` | pdf_oss_download_link, file_name |
| 通用 | POST | `/apiv1/policy_file_count` | policy_file_id, action_type（1=查看/2=下载） |
| 通用 | GET | `/apiv1/get_user_data_id` | 无参数，从Token获取 |
| 考试 | POST | `/apiv1/exam/build_prompt` | mode, client, projectType, examTitle, totalScore, questionTypes |
| 考试 | POST | `/apiv1/exam/build_single_prompt` | client, sectionType, questionIndex, projectType, questionType, scorePerQuestion, currentQuestion |
| 考试 | POST | `/apiv1/re_modify_question` | ai_conversation_id, content |
| 隐患 | POST | `/apiv1/hazard` | scene_name, image, date |
| 隐患 | POST | `/apiv1/save_step` | ai_conversation_id, step, ppt_json_url, cover_image, ppt_json_content |
| 隐患 | GET | `/apiv1/get_history_recognition_record` | 无参数 |
| 隐患 | GET | `/apiv1/get_recognition_record_detail` | recognition_record_id |
| 隐患 | GET | `/apiv1/get_third_scene_example_image` | third_scene_name |
| 隐患 | POST | `/apiv1/submit_evaluation` | id, scene_match, tip_accuracy, effect_evaluation |
| 隐患 | GET | `/apiv1/get_latest_recognition_record` | 无参数 |
| 隐患 | POST | `/apiv1/delete_recognition_record` | recognition_record_id |
| OSS | POST | `/apiv1/oss/upload` | file_name, file_type |
| OSS | POST | `/apiv1/oss/shudao/upload_image` | multipart file |
| OSS | POST | `/apiv1/oss/shudao/upload_json` | content |
| OSS | GET | `/apiv1/oss/parse` | url（无需认证） |
| 知识库 | GET | `/apiv1/knowledge/files/advanced-search` | query, top_k |
| 埋点 | POST | `/apiv1/tracking/record` | api_path, method, extra_data |
| 埋点 | GET | `/apiv1/tracking/records` | page, pageSize, start_date, end_date |
| 埋点 | POST | `/apiv1/tracking/api_mapping` | api_path, api_name, api_desc |
| 埋点 | GET | `/apiv1/tracking/api_mappings` | 无参数 |
| 积分 | GET | `/apiv1/points/balance` | 无参数，从Token获取 |
| 积分 | POST | `/apiv1/points/consume` | file_name, file_url |
| 积分 | GET | `/apiv1/points/history` | page, pageSize |

---

> 文档版本：v1.1 | 最后更新：2026-04-07 | 服务端口：22001