shudao-main/shudao-go-backend/接口测试指南.md

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）

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（统一断言）

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
• 认证：不需要

请求体：

{
    "username": "admin",
    "password": "password123"
}

Tests 脚本：

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;
});

预期响应：

{
    "statusCode": 200,
    "msg": "登录成功",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userInfo": { "id": 1, "username": "admin", "role": "admin" }
}

---

💬 模块 2：AI 对话

2.1 发送 DeepSeek 消息

• 路径：POST /apiv1/send_deepseek_message

请求体：

{
    "message": "如何做好施工现场安全管理？",
    "ai_conversation_id": 0,
    "business_type": 0,
    "exam_name": "",
    "ai_message_id": 0
}

business_type 说明：

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

Tests 脚本：

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 消息及对应的用户消息

请求体：

{
    "ai_conversation_id": 456
}

2.4 删除历史记录（整个对话）

• 路径：POST /apiv1/delete_history_record

请求体：

{
    "ai_conversation_id": 123
}

2.5 删除隐患识别历史记录

• 路径：POST /apiv1/delete_recognition_record

请求体：

{
    "recognition_id": 123
}

2.6 猜你想问

• 路径：POST /apiv1/guess_you_want

请求体：

{
    "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

请求体：

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

2.10 AI 写作保存编辑文档

• 路径：POST /apiv1/save_edit_document

请求体：

{
    "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 为联网搜索结果内容

请求体：

{
    "id": 456,
    "ai_conversation_id": 123,
    "search_source": "[{\"title\":\"...\",\"url\":\"...\",\"content\":\"...\"}]"
}

2.13 意图识别

• 路径：POST /apiv1/intent_recognition

请求体：

{
    "message": "帮我写一份安全生产月活动方案",
    "ai_conversation_id": 0,
    "business_type": 0
}

预期响应（非知识库查询，直接返回答案）：

{
    "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）：

{
    "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

请求体：

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

---

🌐 模块 3：流式接口

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

3.1 流式聊天

• 路径：POST /apiv1/stream/chat
• 浏览器测试页面：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

响应格式（SSE）：

data: {"content":"施工现场"}
data: {"content":"安全管理"}
data: [DONE]

3.2 流式聊天（数据库集成）

• 路径：POST /apiv1/stream/chat-with-db
• 浏览器测试页面：http://localhost:22001/stream-chat-with-db-test

curl 测试命令：

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

请求体：

{
    "content": "建议增加语音输入功能"
}

4.5 点赞/踩

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

请求体：

{
    "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=下载

请求体：

{
    "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

请求体：

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

5.2 单题生成提示词

• 路径：POST /apiv1/exam/build_single_prompt

请求体：

{
    "client": "pc",
    "sectionType": "single",
    "questionIndex": 0,
    "projectType": "工程",
    "questionType": "单选题",
    "scorePerQuestion": 2,
    "currentQuestion": {}
}

5.3 修改考试题目

• 路径：POST /apiv1/re_modify_question

请求体：

{
    "ai_conversation_id": 123,
    "content": "修改后的题目内容..."
}

---

🔍 模块 6：隐患识别

6.1 隐患识别

• 路径：POST /apiv1/hazard

请求体：

{
    "scene_name": "隧道",
    "image": "https://oss.example.com/images/site.jpg",
    "date": "2026-04-07"
}

Tests 脚本：

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

请求体：

{
    "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

请求体：

{
    "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 脚本：

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

请求体：

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

7.3 生成 S3 预签名上传凭证

• 路径：POST /apiv1/oss/upload

请求体：

{
    "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

请求体：

{
    "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

请求体：

{
    "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 脚本：

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

请求体：

{
    "file_name": "建筑施工安全检查标准.pdf",
    "file_url": "https://oss.example.com/files/standard.pdf"
}

Tests 脚本：

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：流式聊天测试

# 浏览器打开 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 过期响应示例：

{ "statusCode": 401, "msg": "获取用户信息失败: token已过期" }

积分不足响应示例：

{
    "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