llm-survey/doc/api.md

在线调查问卷系统 API 文档

1. 数据结构

1.1 用户信息 (User)

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

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

{
    "id": "Long",
    "questionId": "Long",       // 关联的问题ID
    "optionCode": "String",     // 选项代码（如A、B、C）
    "content": "String",        // 选项内容
    "requiresText": "Boolean",  // 是否需要填写文本
    "createdAt": "DateTime"     // 创建时间
}

1.4 问卷答案 (SurveyResponse)

{
    "id": "Long",
    "userId": "Long",           // 用户ID
    "questionId": "Long",       // 问题ID
    "selectedOptions": "List<String>", // 选中的选项代码列表
    "textAnswer": "String",     // 文本答案
    "createdAt": "DateTime"     // 创建时间
}

1.5 错误信息 (ErrorInfo)

{
    "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: 服务器内部错误