# Shudao Go Backend - Postman 接口测试指南

## 📋 目录

1. [项目概述](#项目概述)
2. [环境配置](#环境配置)
3. [认证机制](#认证机制)
4. [接口分类](#接口分类)
5. [详细接口文档](#详细接口文档)
6. [测试流程](#测试流程)
7. [常见问题](#常见问题)

---

## 项目概述

**项目名称**: 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 获取与使用

1. **登录获取 Token**
   - 接口: `POST /apiv1/auth/local_login`
   - 登录成功后，从响应中提取 `token` 字段
   - 将 Token 保存到环境变量 `{{token}}`

2. **请求头配置**
   ```
   Authorization: Bearer {{token}}
   ```

3. **Token 自动更新**（Postman Tests 脚本）：
   ```javascript
   // 在登录接口的 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
```

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

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

**错误响应**:
```json
{
    "statusCode": 401,
    "msg": "用户名或密码错误"
}
```

**Postman Tests 脚本**:
```javascript
// 保存 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}}
```

**请求体**:
```json
{
    "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 |

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

**Postman Tests 脚本**:
```javascript
// 保存对话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
```

**响应示例**:
```json
{
    "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}}
```

**请求体**:
```json
{
    "conversation_id": 123
}
```

**响应示例**:
```json
{
    "statusCode": 200,
    "msg": "删除成功"
}
```

---

### 💰 3. 积分系统

#### 3.1 获取积分余额

**接口**: `GET /apiv1/points/balance`

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

**请求头**:
```
Authorization: Bearer {{token}}
```

**响应示例**:
```json
{
    "statusCode": 200,
    "msg": "success",
    "data": {
        "points": 20
    }
}
```

**Postman Tests 脚本**:
```javascript
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}}
```

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

**响应示例**:
```json
{
    "statusCode": 200,
    "msg": "success",
    "data": {
        "new_balance": 10,
        "points_consumed": 10
    }
}
```

**错误响应**（积分不足）:
```json
{
    "statusCode": 400,
    "msg": "积分不足，下载需要10积分",
    "data": {
        "current_points": 5,
        "required_points": 10
    }
}
```

**Postman Tests 脚本**:
```javascript
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
```

**响应示例**:
```json
{
    "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}}
```

**请求体**:
```json
{
    "image_url": "https://oss.example.com/images/construction_site.jpg",
    "second_scene_ids": [1, 2, 3]
}
```

**响应示例**:
```json
{
    "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}}
```

**响应示例**:
```json
{
    "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
```

**响应示例**:
```json
{
    "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}}
```

**请求体**:
```json
{
    "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-不满意）

**响应示例**:
```json
{
    "statusCode": 200,
    "msg": "success"
}
```

#### 4.5 获取三级场景示例图

**接口**: `GET /apiv1/get_third_scene_example_image`

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

**请求头**:
```
Authorization: Bearer {{token}}
```

**查询参数**:
```
third_scene_name=未系安全带
```

**响应示例**:
```json
{
    "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}}
```

**请求体**:
```json
{
    "exam_name": "施工安全员考试",
    "question_count": 10,
    "difficulty": "中等"
}
```

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

#### 5.2 单题生成提示词

**接口**: `POST /apiv1/exam/build_single_prompt`

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

**请求头**:
```
Content-Type: application/json
Authorization: Bearer {{token}}
```

**请求体**:
```json
{
    "question_type": "单选题",
    "topic": "高处作业安全"
}
```

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

#### 5.3 修改考试题目

**接口**: `POST /apiv1/re_modify_question`

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

**请求头**:
```
Content-Type: application/json
Authorization: Bearer {{token}}
```

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

**响应示例**:
```json
{
    "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: [选择图片文件]
```

**响应示例**:
```json
{
    "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}}
```

**请求体**:
```json
{
    "content": {
        "title": "安全培训PPT",
        "slides": [...]
    }
}
```

**响应示例**:
```json
{
    "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=安全
```

**响应示例**:
```json
{
    "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
```

**响应示例**:
```json
{
    "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}}
```

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

#### 7.2 热点问题

**接口**: `GET /apiv1/get_hot_question`

**说明**: 获取热点问题列表

**请求头**:
```
Authorization: Bearer {{token}}
```

**响应示例**:
```json
{
    "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}}
```

**响应示例**:
```json
{
    "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}}
```

**请求体**:
```json
{
    "feedback_type": "功能建议",
    "content": "建议增加语音输入功能",
    "contact": "user@example.com"
}
```

**响应示例**:
```json
{
    "statusCode": 200,
    "msg": "感谢您的反馈！"
}
```

#### 7.5 点赞/踩

**接口**: `POST /apiv1/like_and_dislike`

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

**请求头**:
```
Content-Type: application/json
Authorization: Bearer {{token}}
```

**请求体**:
```json
{
    "ai_message_id": 456,
    "action": "like"
}
```

**参数说明**:
- `action`: `like` 或 `dislike`

**响应示例**:
```json
{
    "statusCode": 200,
    "msg": "success"
}
```

#### 7.6 埋点记录

**接口**: `POST /apiv1/tracking/record`

**说明**: 记录用户行为埋点

**请求头**:
```
Content-Type: application/json
Authorization: Bearer {{token}}
```

**请求体**:
```json
{
    "api_path": "/apiv1/send_deepseek_message",
    "request_method": "POST",
    "user_agent": "Mozilla/5.0...",
    "ip_address": "192.168.1.100"
}
```

**响应示例**:
```json
{
    "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
```

**响应示例**:
```json
{
    "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：

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

### 2. Collection 级别的 Tests Script

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

```javascript
// 统一错误处理
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。

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

### Q2: 积分不足如何处理？

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

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

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

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

**A**: 检查以下几点：
1. 图片格式是否支持（JPG、PNG、GIF）
2. 图片大小是否超过限制（通常 10MB）
3. Token 是否有效
4. OSS 配置是否正确

### Q4: OSS 代理 URL 无法访问？

**A**: OSS 代理 URL 格式为：
```
/apiv1/oss/parse/?url=https://oss.example.com/images/example.jpg
```

确保：
1. URL 参数正确编码
2. 原始 OSS URL 有效
3. 服务器可以访问 OSS

### Q5: 如何测试流式响应？

**A**: 流式响应接口：
- `/apiv1/stream/chat`
- `/apiv1/stream/chat-with-db`

在 Postman 中无法很好地展示流式响应，建议：
1. 使用浏览器测试页面：`/stream-test`、`/simple-stream-test`
2. 使用 curl 命令测试：
   ```bash
   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: 如何查看请求日志？

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

### Q8: 如何处理并发请求？

**A**: 使用 Postman Collection Runner：
1. 选择 Collection
2. 点击 "Run" 按钮
3. 设置并发数量（Iterations）
4. 设置请求间隔（Delay）
5. 点击 "Run" 开始测试

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

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

### Q10: 如何模拟不同用户？

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

---

## Postman Collection 导入模板

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

```json
{
    "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开发团队

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