163 lines
4.2 KiB
Markdown
163 lines
4.2 KiB
Markdown
# 在线调查问卷系统 API 文档
|
||
|
||
## 1. 数据结构
|
||
|
||
### 1.1 用户信息 (User)
|
||
```json
|
||
{
|
||
"id": "Long",
|
||
"name": "String", // 姓名
|
||
"phone": "String", // 手机号码
|
||
"workArea": "String", // 工作领域: RD/PROJECT/INSURANCE/FINANCE/OPERATION/CUSTOMER_SERVICE/ADMIN
|
||
"positionType": "String", // 岗位性质: MANAGEMENT/TECHNICAL/BUSINESS/SUPPORT
|
||
"createdAt": "DateTime" // 创建时间
|
||
}
|
||
```
|
||
|
||
### 1.2 问题 (Question)
|
||
```json
|
||
{
|
||
"id": "Long",
|
||
"questionNumber": "Integer", // 问题序号
|
||
"content": "String", // 问题内容
|
||
"questionType": "String", // 问题类型: SINGLE_CHOICE/MULTIPLE_CHOICE/TEXT
|
||
"workArea": "String", // 针对的工作领域（null表示通用问题）
|
||
"isRequired": "Boolean", // 是否必答
|
||
"nextQuestionLogic": "JSON", // 跳转逻辑
|
||
"createdAt": "DateTime" // 创建时间
|
||
}
|
||
```
|
||
|
||
### 1.3 选项 (Option)
|
||
```json
|
||
{
|
||
"id": "Long",
|
||
"questionId": "Long", // 关联的问题ID
|
||
"optionCode": "String", // 选项代码（如A、B、C）
|
||
"content": "String", // 选项内容
|
||
"requiresText": "Boolean", // 是否需要填写文本
|
||
"createdAt": "DateTime" // 创建时间
|
||
}
|
||
```
|
||
|
||
### 1.4 问卷答案 (SurveyResponse)
|
||
```json
|
||
{
|
||
"id": "Long",
|
||
"userId": "Long", // 用户ID
|
||
"questionId": "Long", // 问题ID
|
||
"selectedOptions": "List<String>", // 选中的选项代码列表
|
||
"textAnswer": "String", // 文本答案
|
||
"createdAt": "DateTime" // 创建时间
|
||
}
|
||
```
|
||
|
||
### 1.5 错误信息 (ErrorInfo)
|
||
```json
|
||
{
|
||
"code": "String", // 错误代码
|
||
"message": "String", // 错误消息
|
||
"detail": "String", // 错误详情
|
||
"timestamp": "Long", // 时间戳
|
||
"path": "String" // 请求路径
|
||
}
|
||
```
|
||
|
||
## 2. API 接口
|
||
|
||
### 2.1 用户相关接口
|
||
|
||
#### 2.1.1 用户注册
|
||
- **URL**: `/user/register`
|
||
- **Method**: POST
|
||
- **请求体**: User对象（不需要id和createdAt）
|
||
- **响应**: User对象
|
||
- **错误码**:
|
||
- `INVALID_ARGUMENT`: 参数校验失败
|
||
- `BAD_REQUEST`: 手机号已被注册
|
||
|
||
#### 2.1.2 查询用户信息
|
||
- **URL**: `/user/{id}`
|
||
- **Method**: GET
|
||
- **参数**:
|
||
- `id`: 用户ID
|
||
- **响应**: User对象
|
||
- **错误码**:
|
||
- `BAD_REQUEST`: 用户不存在
|
||
|
||
#### 2.1.3 检查手机号是否已注册
|
||
- **URL**: `/user/check/{phone}`
|
||
- **Method**: GET
|
||
- **参数**:
|
||
- `phone`: 手机号
|
||
- **响应**: Boolean（true表示已注册）
|
||
|
||
### 2.2 问题相关接口
|
||
|
||
#### 2.2.1 获取用户的问题列表
|
||
- **URL**: `/question/user/{userId}`
|
||
- **Method**: GET
|
||
- **参数**:
|
||
- `userId`: 用户ID
|
||
- **响应**: Question对象列表
|
||
- **错误码**:
|
||
- `BAD_REQUEST`: 用户不存在
|
||
|
||
#### 2.2.2 获取问题的选项列表
|
||
- **URL**: `/question/{questionId}/option`
|
||
- **Method**: GET
|
||
- **参数**:
|
||
- `questionId`: 问题ID
|
||
- **响应**: Option对象列表
|
||
|
||
#### 2.2.3 获取下一个问题
|
||
- **URL**: `/question/next`
|
||
- **Method**: GET
|
||
- **参数**:
|
||
- `userId`: 用户ID
|
||
- `currentQuestionNumber`: 当前问题序号
|
||
- `selectedOptions`: 选中的选项代码列表
|
||
- **响应**: Question对象
|
||
- **错误码**:
|
||
- `BAD_REQUEST`: 没有更多问题了
|
||
|
||
### 2.3 问卷答案相关接口
|
||
|
||
#### 2.3.1 提交问卷答案
|
||
- **URL**: `/survey/submit/{userId}`
|
||
- **Method**: POST
|
||
- **参数**:
|
||
- `userId`: 用户ID
|
||
- **请求体**: SurveyResponse对象列表
|
||
- **响应**: SurveyResponse对象列表
|
||
- **错误码**:
|
||
- `BAD_REQUEST`: 必答题未回答
|
||
|
||
#### 2.3.2 获取用户的问卷答案
|
||
- **URL**: `/survey/user/{userId}`
|
||
- **Method**: GET
|
||
- **参数**:
|
||
- `userId`: 用户ID
|
||
- **响应**: SurveyResponse对象列表
|
||
|
||
#### 2.3.3 获取问题的所有答案
|
||
- **URL**: `/survey/question/{questionId}`
|
||
- **Method**: GET
|
||
- **参数**:
|
||
- `questionId`: 问题ID
|
||
- **响应**: SurveyResponse对象列表
|
||
|
||
## 3. 错误处理
|
||
|
||
所有接口在发生错误时都会返回统一格式的错误信息（ErrorInfo对象）：
|
||
|
||
### 3.1 通用错误码
|
||
- `INVALID_ARGUMENT`: 参数校验失败
|
||
- `BAD_REQUEST`: 业务逻辑错误
|
||
- `DATABASE_ERROR`: 数据库访问错误
|
||
- `SYSTEM_ERROR`: 系统错误
|
||
|
||
### 3.2 HTTP状态码
|
||
- 200: 请求成功
|
||
- 400: 请求参数错误或业务逻辑错误
|
||
- 500: 服务器内部错误 |