Shudao Go Backend - Postman 接口测试指南

📋 目录

项目概述
环境配置
认证机制
接口分类
详细接口文档
测试流程
常见问题

项目概述

项目名称: Shudao Chat Go Backend
框架: Beego v2
主要功能:

AI 对话系统（基于阿里通义千问、DeepSeek 等模型）
用户认证（本地登录 + 4A 集成）
积分系统
隐患识别
考试工坊
AI 写作
知识库管理
OSS 文件管理

项目结构:

shudao-go-backend/
├── controllers/     # 控制器层
├── models/         # 数据模型层
├── routers/        # 路由定义
├── utils/          # 工具函数
└── conf/           # 配置文件

环境配置

1. Postman 环境变量

在 Postman 中创建环境并配置以下变量：

变量名	示例值	说明
`base_url`	`http://localhost:8080`	API 基础地址
`token`	`eyJhbGc...`	登录后获取的 JWT Token
`user_id`	`1`	当前用户 ID
`ai_conversation_id`	`123`	对话 ID（动态更新）

2. 服务器地址

开发环境: http://localhost:8080
测试环境: http://test-server:8080
生产环境: https://api.shudao.com

认证机制

Token 获取与使用

登录获取 Token
- 接口: POST /apiv1/auth/local_login
- 登录成功后，从响应中提取 token 字段
- 将 Token 保存到环境变量 {{token}}
请求头配置
```
Authorization: Bearer {{token}}
```

Token 自动更新（Postman Tests 脚本）：

// 在登录接口的 Tests 标签页添加
if (pm.response.code === 200) {
   const jsonData = pm.response.json();
   if (jsonData.token) {
       pm.environment.set("token", jsonData.token);
       pm.environment.set("user_id", jsonData.userInfo.id);
   }
}

接口分类

1. 认证相关

本地登录

2. AI 对话相关

发送 DeepSeek 消息
获取历史记录
猜你想问
意图识别
ChromaDB 文档检索

3. 积分系统

获取积分余额
消费积分
消费记录查询

4. 隐患识别

图片识别
识别历史记录
识别详情查询
用户点评

5. 考试工坊

生成考试提示词
单题生成
修改题目

6. 文件管理

OSS 上传
OSS 代理下载
政策文件查询

7. 其他功能

推荐问题
热点问题
功能卡片
意见反馈
埋点统计

详细接口文档

🔐 1. 认证相关

1.1 本地登录

接口: POST /apiv1/auth/local_login

说明: 使用用户名和密码进行本地登录，获取 JWT Token

请求头:

Content-Type: application/json

请求体:

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

响应示例:

{
    "statusCode": 200,
    "msg": "登录成功",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userInfo": {
        "id": 1,
        "username": "admin",
        "nickname": "管理员",
        "role": "admin",
        "email": "admin@example.com"
    }
}

错误响应:

{
    "statusCode": 401,
    "msg": "用户名或密码错误"
}

Postman Tests 脚本:

// 保存 Token 到环境变量
if (pm.response.code === 200) {
    const jsonData = pm.response.json();
    if (jsonData.statusCode === 200 && jsonData.token) {
        pm.environment.set("token", jsonData.token);
        pm.environment.set("user_id", jsonData.userInfo.id);
        console.log("Token 已保存:", jsonData.token);
    }
}

// 断言测试
pm.test("登录成功", function() {
    pm.response.to.have.status(200);
    const jsonData = pm.response.json();
    pm.expect(jsonData.statusCode).to.eql(200);
    pm.expect(jsonData.token).to.be.a('string');
});

💬 2. AI 对话相关

2.1 发送 DeepSeek 消息

接口: POST /apiv1/send_deepseek_message

说明: 发送消息到 AI 模型，支持多种业务类型（安全培训、AI写作、考试工坊等）

请求头:

Content-Type: application/json
Authorization: Bearer {{token}}

请求体:

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

参数说明: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | message | string | ✅ | 用户消息内容 | | ai_conversation_id | uint64 | ✅ | 对话ID，新对话传0 | | business_type | int | ✅ | 业务类型：0-通用对话，1-安全培训，2-AI写作，3-考试工坊 | | exam_name | string | ❌ | 考试名称（business_type=3时使用） | | ai_message_id | uint64 | ❌ | 消息ID |

响应示例:

{
    "statusCode": 200,
    "msg": "success",
    "data": {
        "ai_conversation_id": 123,
        "ai_message_id": 456,
        "reply": "施工现场安全管理的关键要点包括...",
        "intent": "complex_question",
        "sources": [
            "《建筑施工安全检查标准》",
            "《施工现场临时用电安全技术规范》"
        ]
    }
}

Postman Tests 脚本:

// 保存对话ID
if (pm.response.code === 200) {
    const jsonData = pm.response.json();
    if (jsonData.data && jsonData.data.ai_conversation_id) {
        pm.environment.set("ai_conversation_id", jsonData.data.ai_conversation_id);
    }
}

pm.test("消息发送成功", function() {
    pm.response.to.have.status(200);
    const jsonData = pm.response.json();
    pm.expect(jsonData.statusCode).to.eql(200);
    pm.expect(jsonData.data.reply).to.be.a('string');
});

2.2 获取历史记录

接口: GET /apiv1/get_history_record

说明: 获取用户的对话历史记录

请求头:

Authorization: Bearer {{token}}

查询参数:

page=1
pageSize=20
business_type=0

响应示例:

{
    "statusCode": 200,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": 123,
                "user_id": 1,
                "content": "如何做好施工现场安全管理？",
                "business_type": 0,
                "created_at": "2026-04-03T09:00:00Z",
                "message_count": 5
            }
        ],
        "total": 100,
        "page": 1,
        "pageSize": 20
    }
}

2.3 删除对话

接口: POST /apiv1/delete_conversation

说明: 删除指定对话（软删除）

请求头:

Content-Type: application/json
Authorization: Bearer {{token}}

请求体:

{
    "conversation_id": 123
}

响应示例:

{
    "statusCode": 200,
    "msg": "删除成功"
}

💰 3. 积分系统

3.1 获取积分余额

接口: GET /apiv1/points/balance

说明: 查询当前用户的积分余额

请求头:

Authorization: Bearer {{token}}

响应示例:

{
    "statusCode": 200,
    "msg": "success",
    "data": {
        "points": 20
    }
}

Postman Tests 脚本:

pm.test("积分余额查询成功", function() {
    pm.response.to.have.status(200);
    const jsonData = pm.response.json();
    pm.expect(jsonData.statusCode).to.eql(200);
    pm.expect(jsonData.data.points).to.be.a('number');
    pm.expect(jsonData.data.points).to.be.at.least(0);
});

3.2 消费积分

接口: POST /apiv1/points/consume

说明: 消费积分下载文件（每次消费 10 积分）

请求头:

Content-Type: application/json
Authorization: Bearer {{token}}

请求体:

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

响应示例:

{
    "statusCode": 200,
    "msg": "success",
    "data": {
        "new_balance": 10,
        "points_consumed": 10
    }
}

错误响应（积分不足）:

{
    "statusCode": 400,
    "msg": "积分不足，下载需要10积分",
    "data": {
        "current_points": 5,
        "required_points": 10
    }
}

Postman Tests 脚本:

pm.test("积分消费成功", function() {
    const jsonData = pm.response.json();
    if (jsonData.statusCode === 200) {
        pm.expect(jsonData.data.points_consumed).to.eql(10);
        pm.expect(jsonData.data.new_balance).to.be.a('number');
    } else if (jsonData.statusCode === 400) {
        pm.expect(jsonData.msg).to.include("积分不足");
    }
});

3.3 消费记录查询

接口: GET /apiv1/points/history

说明: 查询用户的积分消费历史记录

请求头:

Authorization: Bearer {{token}}

查询参数:

page=1
pageSize=10

响应示例:

{
    "statusCode": 200,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": 1,
                "user_id": 1,
                "file_name": "建筑施工安全检查标准.pdf",
                "file_url": "https://oss.example.com/files/standard.pdf",
                "points_consumed": 10,
                "balance_after": 10,
                "created_at": "2026-04-03T09:00:00Z"
            }
        ],
        "total": 5,
        "page": 1,
        "pageSize": 10
    }
}

🔍 4. 隐患识别

4.1 隐患识别

接口: POST /apiv1/hazard

说明: 上传图片进行隐患识别（需要先上传图片到 OSS）

请求头:

Content-Type: application/json
Authorization: Bearer {{token}}

请求体:

{
    "image_url": "https://oss.example.com/images/construction_site.jpg",
    "second_scene_ids": [1, 2, 3]
}

响应示例:

{
    "statusCode": 200,
    "msg": "识别成功",
    "data": {
        "recognition_record_id": 123,
        "original_image_url": "https://oss.example.com/images/construction_site.jpg",
        "recognition_image_url": "https://oss.example.com/images/recognized_123.jpg",
        "labels": ["高处作业", "临边防护"],
        "third_scenes": ["未系安全带", "防护栏杆缺失"],
        "description": "未系安全带 防护栏杆缺失"
    }
}

4.2 获取识别历史记录

接口: GET /apiv1/get_history_recognition_record

说明: 获取用户的隐患识别历史记录

请求头:

Authorization: Bearer {{token}}

响应示例:

{
    "statusCode": 200,
    "msg": "success",
    "data": [
        {
            "id": 123,
            "user_id": 1,
            "title": "施工现场隐患识别",
            "original_image_url": "/apiv1/oss/parse/?url=https://oss.example.com/images/...",
            "recognition_image_url": "/apiv1/oss/parse/?url=https://oss.example.com/images/...",
            "description": "未系安全带 防护栏杆缺失",
            "created_at": "2026-04-03T09:00:00Z"
        }
    ],
    "total": 10
}

4.3 获取识别详情

接口: GET /apiv1/get_recognition_record_detail

说明: 获取指定识别记录的详细信息

请求头:

Authorization: Bearer {{token}}

查询参数:

recognition_record_id=123

响应示例:

{
    "statusCode": 200,
    "msg": "success",
    "data": {
        "id": 123,
        "original_image_url": "/apiv1/oss/parse/?url=...",
        "recognition_image_url": "/apiv1/oss/parse/?url=...",
        "labels": ["高处作业", "临边防护"],
        "third_scenes": ["未系安全带", "防护栏杆缺失"],
        "scene_match": 0,
        "tip_accuracy": 0,
        "effect_evaluation": 0,
        "user_remark": ""
    }
}

4.4 提交用户点评

接口: POST /apiv1/submit_evaluation

说明: 用户对识别结果进行点评

请求头:

Content-Type: application/json
Authorization: Bearer {{token}}

请求体:

{
    "id": 123,
    "scene_match": 1,
    "tip_accuracy": 1,
    "effect_evaluation": 1,
    "user_remark": "识别准确"
}

参数说明:

scene_match: 场景匹配度（0-未评价，1-匹配，2-不匹配）
tip_accuracy: 提示准确度（0-未评价，1-准确，2-不准确）
effect_evaluation: 效果评价（0-未评价，1-满意，2-不满意）

响应示例:

{
    "statusCode": 200,
    "msg": "success"
}

4.5 获取三级场景示例图

接口: GET /apiv1/get_third_scene_example_image

说明: 获取三级场景的正确和错误示例图（带水印）

请求头:

Authorization: Bearer {{token}}

查询参数:

third_scene_name=未系安全带

响应示例:

{
    "statusCode": 200,
    "msg": "success",
    "data": {
        "id": 1,
        "third_scene_name": "未系安全带",
        "correct_example_image": "/apiv1/oss/parse/?url=...",
        "wrong_example_image": "/apiv1/oss/parse/?url=..."
    }
}

📝 5. 考试工坊

5.1 生成考试提示词

接口: POST /apiv1/exam/build_prompt

说明: 根据考试要求生成提示词

请求头:

Content-Type: application/json
Authorization: Bearer {{token}}

请求体:

{
    "exam_name": "施工安全员考试",
    "question_count": 10,
    "difficulty": "中等"
}

响应示例:

{
    "statusCode": 200,
    "msg": "success",
    "data": {
        "prompt": "请生成10道中等难度的施工安全员考试题目..."
    }
}

5.2 单题生成提示词

接口: POST /apiv1/exam/build_single_prompt

说明: 生成单个题目的提示词

请求头:

Content-Type: application/json
Authorization: Bearer {{token}}

请求体:

{
    "question_type": "单选题",
    "topic": "高处作业安全"
}

响应示例:

{
    "statusCode": 200,
    "msg": "success",
    "data": {
        "prompt": "请生成一道关于高处作业安全的单选题..."
    }
}

5.3 修改考试题目

接口: POST /apiv1/re_modify_question

说明: 修改已生成的考试题目

请求头:

Content-Type: application/json
Authorization: Bearer {{token}}

请求体:

{
    "question_id": 123,
    "new_content": "修改后的题目内容..."
}

响应示例:

{
    "statusCode": 200,
    "msg": "修改成功"
}

📁 6. 文件管理

6.1 上传图片到 OSS

接口: POST /apiv1/oss/shudao/upload_image

说明: 上传图片文件到阿里云 OSS

请求头:

Content-Type: multipart/form-data
Authorization: Bearer {{token}}

请求体:

form-data:
- file: [选择图片文件]

响应示例:

{
    "statusCode": 200,
    "msg": "上传成功",
    "data": {
        "url": "https://oss.example.com/images/2026/0403/image_123.jpg"
    }
}

6.2 上传 JSON 文件

接口: POST /apiv1/oss/shudao/upload_json

说明: 上传 JSON 文件（用于 PPT 大纲等）

请求头:

Content-Type: application/json
Authorization: Bearer {{token}}

请求体:

{
    "content": {
        "title": "安全培训PPT",
        "slides": [...]
    }
}

响应示例:

{
    "statusCode": 200,
    "msg": "上传成功",
    "data": {
        "url": "https://oss.example.com/json/ppt_123.json"
    }
}

6.3 OSS 代理解析

接口: GET /apiv1/oss/parse

说明: 代理访问 OSS 资源（解决跨域问题）

请求头:

无需认证

查询参数:

url=https://oss.example.com/images/example.jpg

响应: 直接返回文件内容（图片、PDF 等）

6.4 获取政策文件

接口: GET /apiv1/get_policy_file

说明: 获取政策文件列表

请求头:

Authorization: Bearer {{token}}

查询参数:

page=1
pageSize=10
keyword=安全

响应示例:

{
    "statusCode": 200,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": 1,
                "title": "建筑施工安全检查标准",
                "file_url": "https://oss.example.com/files/standard.pdf",
                "file_size": "2.5MB",
                "created_at": "2026-04-01T00:00:00Z"
            }
        ],
        "total": 100
    }
}

6.5 获取文件下载链接

接口: GET /apiv1/download_file

说明: 获取文件的 OSS 下载链接

请求头:

Authorization: Bearer {{token}}

查询参数:

file_name=建筑施工安全检查标准.pdf

响应示例:

{
    "statusCode": 200,
    "msg": "success",
    "data": {
        "download_url": "https://oss.example.com/files/standard.pdf?expires=..."
    }
}

🎯 7. 其他功能

7.1 推荐问题

接口: GET /apiv1/recommend_question

说明: 获取系统推荐问题

请求头:

Authorization: Bearer {{token}}

响应示例:

{
    "statusCode": 200,
    "msg": "success",
    "data": [
        "如何做好施工现场安全管理？",
        "高处作业需要注意哪些事项？",
        "临时用电有哪些安全要求？"
    ]
}

7.2 热点问题

接口: GET /apiv1/get_hot_question

说明: 获取热点问题列表

请求头:

Authorization: Bearer {{token}}

响应示例:

{
    "statusCode": 200,
    "msg": "success",
    "data": [
        {
            "id": 1,
            "question": "施工现场消防安全管理要点",
            "click_count": 1523
        },
        {
            "id": 2,
            "question": "脚手架搭设安全规范",
            "click_count": 1342
        },
        {
            "id": 3,
            "question": "基坑支护安全监测方法",
            "click_count": 1156
        }
    ]
}

7.3 功能卡片

接口: GET /apiv1/get_function_card

说明: 获取首页功能卡片

请求头:

Authorization: Bearer {{token}}

响应示例:

{
    "statusCode": 200,
    "msg": "success",
    "data": [
        {
            "id": 1,
            "title": "安全培训",
            "icon": "https://oss.example.com/icons/training.png",
            "description": "智能安全培训助手",
            "business_type": 1
        },
        {
            "id": 2,
            "title": "AI写作",
            "icon": "https://oss.example.com/icons/writing.png",
            "description": "AI辅助公文写作",
            "business_type": 2
        },
        {
            "id": 3,
            "title": "考试工坊",
            "icon": "https://oss.example.com/icons/exam.png",
            "description": "智能生成考试题目",
            "business_type": 3
        },
        {
            "id": 4,
            "title": "隐患识别",
            "icon": "https://oss.example.com/icons/hazard.png",
            "description": "AI图像识别隐患",
            "business_type": 4
        }
    ]
}

7.4 提交意见反馈

接口: POST /apiv1/submit_feedback

说明: 用户提交意见反馈

请求头:

Content-Type: application/json
Authorization: Bearer {{token}}

请求体:

{
    "feedback_type": "功能建议",
    "content": "建议增加语音输入功能",
    "contact": "user@example.com"
}

响应示例:

{
    "statusCode": 200,
    "msg": "感谢您的反馈！"
}

7.5 点赞/踩

接口: POST /apiv1/like_and_dislike

说明: 对 AI 回复进行点赞或踩

请求头:

Content-Type: application/json
Authorization: Bearer {{token}}

请求体:

{
    "ai_message_id": 456,
    "action": "like"
}

参数说明:

action: like 或 dislike

响应示例:

{
    "statusCode": 200,
    "msg": "success"
}

7.6 埋点记录

接口: POST /apiv1/tracking/record

说明: 记录用户行为埋点

请求头:

Content-Type: application/json
Authorization: Bearer {{token}}

请求体:

{
    "api_path": "/apiv1/send_deepseek_message",
    "request_method": "POST",
    "user_agent": "Mozilla/5.0...",
    "ip_address": "192.168.1.100"
}

响应示例:

{
    "statusCode": 200,
    "msg": "记录成功"
}

7.7 获取埋点记录

接口: GET /apiv1/tracking/records

说明: 查询埋点记录（管理员）

请求头:

Authorization: Bearer {{token}}

查询参数:

page=1
pageSize=20
start_date=2026-04-01
end_date=2026-04-03

响应示例:

{
    "statusCode": 200,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": 1,
                "user_id": 1,
                "api_path": "/apiv1/send_deepseek_message",
                "request_method": "POST",
                "created_at": "2026-04-03T09:00:00Z"
            }
        ],
        "total": 5000,
        "page": 1,
        "pageSize": 20
    }
}

测试流程

完整测试流程示例

1. 基础流程测试

1. 登录获取Token
   POST /apiv1/auth/local_login
   
2. 查询积分余额
   GET /apiv1/points/balance
   
3. 发送AI消息
   POST /apiv1/send_deepseek_message
   
4. 查看对话历史
   GET /apiv1/get_history_record
   
5. 查询消费记录
   GET /apiv1/points/history

2. 隐患识别流程测试

1. 登录获取Token
   POST /apiv1/auth/local_login
   
2. 上传图片
   POST /apiv1/oss/shudao/upload_image
   
3. 提交隐患识别
   POST /apiv1/hazard
   
4. 查看识别历史
   GET /apiv1/get_history_recognition_record
   
5. 查看识别详情
   GET /apiv1/get_recognition_record_detail?recognition_record_id=123
   
6. 提交点评
   POST /apiv1/submit_evaluation
   
7. 查看示例图
   GET /apiv1/get_third_scene_example_image?third_scene_name=未系安全带

3. 积分消费流程测试

1. 登录获取Token
   POST /apiv1/auth/local_login
   
2. 查询当前积分
   GET /apiv1/points/balance
   
3. 查询政策文件
   GET /apiv1/get_policy_file
   
4. 消费积分下载
   POST /apiv1/points/consume
   
5. 再次查询积分（验证扣减）
   GET /apiv1/points/balance
   
6. 查看消费记录
   GET /apiv1/points/history

Postman Collection 设置

1. Collection 级别的 Pre-request Script

在 Collection 设置中添加以下脚本，自动为所有需要认证的请求添加 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
        });
    }
}

2. Collection 级别的 Tests Script

在 Collection 设置中添加以下脚本，统一处理错误：

// 统一错误处理
if (pm.response.code !== 200) {
    console.error("请求失败:", pm.response.json());
}

// 如果是401错误，提示重新登录
const jsonData = pm.response.json();
if (jsonData.statusCode === 401) {
    console.warn("Token已过期，请重新登录");
    pm.environment.unset("token");
}

// 通用断言
pm.test("HTTP状态码为200", function() {
    pm.response.to.have.status(200);
});

pm.test("响应格式正确", function() {
    const jsonData = pm.response.json();
    pm.expect(jsonData).to.have.property('statusCode');
    pm.expect(jsonData).to.have.property('msg');
});

常见问题

Q1: Token 过期怎么办？

A: Token 过期后会收到 401 状态码，需要重新调用登录接口获取新的 Token。

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

Q2: 积分不足如何处理？

A: 积分不足时会收到 400 状态码，响应中会包含当前积分和所需积分：

{
    "statusCode": 400,
    "msg": "积分不足，下载需要10积分",
    "data": {
        "current_points": 5,
        "required_points": 10
    }
}

需要联系管理员充值积分。

Q3: 图片上传失败怎么办？

A: 检查以下几点：

图片格式是否支持（JPG、PNG、GIF）
图片大小是否超过限制（通常 10MB）
Token 是否有效
OSS 配置是否正确

Q4: OSS 代理 URL 无法访问？

A: OSS 代理 URL 格式为：

/apiv1/oss/parse/?url=https://oss.example.com/images/example.jpg

确保：

URL 参数正确编码
原始 OSS URL 有效
服务器可以访问 OSS

Q5: 如何测试流式响应？

A: 流式响应接口：

/apiv1/stream/chat
/apiv1/stream/chat-with-db

在 Postman 中无法很好地展示流式响应，建议：

使用浏览器测试页面：/stream-test、/simple-stream-test

使用 curl 命令测试：

curl -X POST "http://localhost:8080/apiv1/stream/chat" \
 -H "Authorization: Bearer YOUR_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"message":"测试消息"}' \
 --no-buffer

Q6: business_type 参数说明

A: business_type 用于区分不同的业务场景：

值	业务类型	说明
0	通用对话	普通AI对话，支持RAG检索
1	安全培训	使用安全培训知识库
2	AI写作	公文写作辅助
3	考试工坊	生成考试题目

Q7: 如何查看请求日志？

在 Postman Console 中查看（View -> Show Postman Console）
服务器日志文件位置：logs/app_YYYYMMDD.log
使用埋点接口查询历史请求

Q8: 如何处理并发请求？

A: 使用 Postman Collection Runner：

选择 Collection
点击 "Run" 按钮
设置并发数量（Iterations）
设置请求间隔（Delay）
点击 "Run" 开始测试

Q9: 环境变量丢失怎么办？

导出当前环境配置：右键环境 -> Export
定期备份环境变量
使用 Collection 级别的变量作为默认值

Q10: 如何模拟不同用户？

创建多个环境（用户A、用户B等）
每个环境配置不同的用户名和密码
切换环境进行测试

Postman Collection 导入模板

将以下 JSON 保存为 .json 文件，导入到 Postman 中：

{
    "info": {
        "name": "Shudao Go Backend API",
        "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
    },
    "item": [
        {
            "name": "1. 认证",
            "item": [
                {
                    "name": "本地登录",
                    "event": [
                        {
                            "listen": "test",
                            "script": {
                                "exec": [
                                    "if (pm.response.code === 200) {",
                                    "    const jsonData = pm.response.json();",
                                    "    if (jsonData.statusCode === 200 && jsonData.token) {",
                                    "        pm.environment.set(\"token\", jsonData.token);",
                                    "        pm.environment.set(\"user_id\", jsonData.userInfo.id);",
                                    "    }",
                                    "}",
                                    "",
                                    "pm.test(\"登录成功\", function() {",
                                    "    pm.response.to.have.status(200);",
                                    "    const jsonData = pm.response.json();",
                                    "    pm.expect(jsonData.statusCode).to.eql(200);",
                                    "});"
                                ],
                                "type": "text/javascript"
                            }
                        }
                    ],
                    "request": {
                        "method": "POST",
                        "header": [
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            }
                        ],
                        "body": {
                            "mode": "raw",
                            "raw": "{\n    \"username\": \"admin\",\n    \"password\": \"password123\"\n}"
                        },
                        "url": {
                            "raw": "{{base_url}}/apiv1/auth/local_login",
                            "host": ["{{base_url}}"],
                            "path": ["apiv1", "auth", "local_login"]
                        }
                    }
                }
            ]
        },
        {
            "name": "2. AI对话",
            "item": [
                {
                    "name": "发送消息",
                    "event": [
                        {
                            "listen": "test",
                            "script": {
                                "exec": [
                                    "if (pm.response.code === 200) {",
                                    "    const jsonData = pm.response.json();",
                                    "    if (jsonData.data && jsonData.data.ai_conversation_id) {",
                                    "        pm.environment.set(\"ai_conversation_id\", jsonData.data.ai_conversation_id);",
                                    "    }",
                                    "}",
                                    "",
                                    "pm.test(\"消息发送成功\", function() {",
                                    "    pm.response.to.have.status(200);",
                                    "});"
                                ],
                                "type": "text/javascript"
                            }
                        }
                    ],
                    "request": {
                        "method": "POST",
                        "header": [
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            },
                            {
                                "key": "Authorization",
                                "value": "Bearer {{token}}"
                            }
                        ],
                        "body": {
                            "mode": "raw",
                            "raw": "{\n    \"message\": \"如何做好施工现场安全管理？\",\n    \"ai_conversation_id\": 0,\n    \"business_type\": 0\n}"
                        },
                        "url": {
                            "raw": "{{base_url}}/apiv1/send_deepseek_message",
                            "host": ["{{base_url}}"],
                            "path": ["apiv1", "send_deepseek_message"]
                        }
                    }
                }
            ]
        },
        {
            "name": "3. 积分系统",
            "item": [
                {
                    "name": "查询余额",
                    "request": {
                        "method": "GET",
                        "header": [
                            {
                                "key": "Authorization",
                                "value": "Bearer {{token}}"
                            }
                        ],
                        "url": {
                            "raw": "{{base_url}}/apiv1/points/balance",
                            "host": ["{{base_url}}"],
                            "path": ["apiv1", "points", "balance"]
                        }
                    }
                },
                {
                    "name": "消费积分",
                    "request": {
                        "method": "POST",
                        "header": [
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            },
                            {
                                "key": "Authorization",
                                "value": "Bearer {{token}}"
                            }
                        ],
                        "body": {
                            "mode": "raw",
                            "raw": "{\n    \"file_name\": \"测试文件.pdf\",\n    \"file_url\": \"https://example.com/test.pdf\"\n}"
                        },
                        "url": {
                            "raw": "{{base_url}}/apiv1/points/consume",
                            "host": ["{{base_url}}"],
                            "path": ["apiv1", "points", "consume"]
                        }
                    }
                },
                {
                    "name": "消费记录",
                    "request": {
                        "method": "GET",
                        "header": [
                            {
                                "key": "Authorization",
                                "value": "Bearer {{token}}"
                            }
                        ],
                        "url": {
                            "raw": "{{base_url}}/apiv1/points/history?page=1&pageSize=10",
                            "host": ["{{base_url}}"],
                            "path": ["apiv1", "points", "history"],
                            "query": [
                                {
                                    "key": "page",
                                    "value": "1"
                                },
                                {
                                    "key": "pageSize",
                                    "value": "10"
                                }
                            ]
                        }
                    }
                }
            ]
        }
    ],
    "variable": [
        {
            "key": "base_url",
            "value": "http://localhost:8080"
        }
    ]
}

附录

状态码说明

状态码	说明
200	请求成功
400	请求参数错误
401	未授权（Token无效或过期）
403	禁止访问（权限不足）
404	资源不存在
500	服务器内部错误

数据库表结构参考

users 表

id: 用户ID
username: 用户名
password: 密码（bcrypt加密）
nickname: 昵称
role: 角色（admin/user）
email: 邮箱
status: 状态（0-禁用，1-启用）

user_data 表

id: 主键
accountID: 4A账号ID
points: 积分余额
name: 姓名
contact_number: 联系电话

ai_conversation 表

id: 对话ID
user_id: 用户ID
content: 对话主题
business_type: 业务类型
exam_name: 考试名称

ai_message 表

id: 消息ID
user_id: 用户ID
ai_conversation_id: 对话ID
content: 消息内容
type: 消息类型（user/ai）

points_consumption_log 表

id: 记录ID
user_id: 用户ID
file_name: 文件名
file_url: 文件URL
points_consumed: 消费积分
balance_after: 消费后余额

recognition_record 表

id: 识别记录ID
user_id: 用户ID
original_image_url: 原始图片URL
recognition_image_url: 识别结果图片URL
labels: 二级场景标签
description: 三级场景描述
scene_match: 场景匹配度
tip_accuracy: 提示准确度
effect_evaluation: 效果评价

文档版本: v1.0
最后更新: 2026-04-03
维护人员: Shudao开发团队

如有问题，请联系技术支持。

POSTMAN_测试指南.md 35 KB Verlauf Originalformat

Shudao Go Backend - Postman 接口测试指南

📋 目录

项目概述

环境配置

1. Postman 环境变量

2. 服务器地址

认证机制

Token 获取与使用

接口分类

1. 认证相关

2. AI 对话相关

3. 积分系统

4. 隐患识别

5. 考试工坊

6. 文件管理

7. 其他功能

详细接口文档

🔐 1. 认证相关

1.1 本地登录

💬 2. AI 对话相关

2.1 发送 DeepSeek 消息

2.2 获取历史记录

2.3 删除对话

💰 3. 积分系统

3.1 获取积分余额

3.2 消费积分

3.3 消费记录查询

🔍 4. 隐患识别

4.1 隐患识别

4.2 获取识别历史记录

4.3 获取识别详情

4.4 提交用户点评

4.5 获取三级场景示例图

📝 5. 考试工坊

5.1 生成考试提示词

5.2 单题生成提示词

5.3 修改考试题目

📁 6. 文件管理

6.1 上传图片到 OSS

6.2 上传 JSON 文件

6.3 OSS 代理解析

6.4 获取政策文件

6.5 获取文件下载链接

🎯 7. 其他功能

7.1 推荐问题

7.2 热点问题

7.3 功能卡片

7.4 提交意见反馈

7.5 点赞/踩

7.6 埋点记录

7.7 获取埋点记录

测试流程

完整测试流程示例

1. 基础流程测试

2. 隐患识别流程测试

3. 积分消费流程测试

Postman Collection 设置

1. Collection 级别的 Pre-request Script

2. Collection 级别的 Tests Script

常见问题

Q1: Token 过期怎么办？

Q2: 积分不足如何处理？

Q3: 图片上传失败怎么办？

Q4: OSS 代理 URL 无法访问？

Q5: 如何测试流式响应？

Q6: business_type 参数说明

Q7: 如何查看请求日志？

Q8: 如何处理并发请求？

Q9: 环境变量丢失怎么办？

Q10: 如何模拟不同用户？

Postman Collection 导入模板

附录

状态码说明

数据库表结构参考

users 表

user_data 表

ai_conversation 表

ai_message 表

points_consumption_log 表

POSTMAN_测试指南.md 35 KB

Verlauf Originalformat