接口需求清单 - 新华保险肿瘤风险评估

1 接口总览

模块	接口数	GET	POST	PUT
用户与认证	4	2	1	1
问卷与评估	8	4	3	1
线上咨询	5	3	2	0
线下就医	2	1	1	0
健康档案	3	3	0	0
文件与通知	2	1	1	0

2 用户与认证

编号	接口名称	方法	路径	说明
API-001	获取用户信息	GET	/api/v1/user/profile	获取当前登录用户基本信息，返回姓名/手机号/身份证(脱敏)/投保信息
API-002	更新用户信息	PUT	/api/v1/user/profile	更新用户基本信息（地址/工作单位等非核心字段）
API-003	获取服务入口配置	GET	/api/v1/config/services	返回可用服务列表及开关状态（线上咨询/线下就医/健康档案）
API-004	用户同意记录	POST	/api/v1/user/consent	记录用户对隐私协议/数据使用的同意行为

3 问卷与评估

编号	接口名称	方法	路径	说明
API-005	获取问卷配置	GET	/api/v1/questionnaire/config	返回问卷题目列表、选项配置、步骤结构
API-006	保存问卷步骤数据	POST	/api/v1/questionnaire/step	保存单步问卷数据（基本信息/生活方式/HPV），支持断点续传
API-007	获取问卷草稿	GET	/api/v1/questionnaire/draft	获取用户未提交的问卷草稿数据
API-008	提交问卷	POST	/api/v1/questionnaire/submit	提交完整问卷，触发审核流程
API-009	上传检测报告	POST	/api/v1/questionnaire/upload	上传HPV检测报告文件，返回文件ID和预览URL
API-010	获取审核状态	GET	/api/v1/questionnaire/review-status	返回当前问卷审核状态（pending/approved/rejected）及失败原因
API-011	获取评估结果	GET	/api/v1/questionnaire/result	返回风险评估等级（high/medium/low）+器官风险分解+建议
API-012	修改上传结果	PUT	/api/v1/questionnaire/upload	审核失败后修改上传的检测报告

请求示例 - 提交问卷

POST /api/v1/questionnaire/submit
Content-Type: application/json
Authorization: Bearer {token}

{
  "basic_info": {
    "name": "张三",
    "birth_date": "1965-03-15",
    "age": 61,
    "height": 170,
    "weight": 75,
    "origin": "北京市",
    "id_number": "110***********1234",
    "phone": "138****5678",
    "address": "北京市朝阳区...",
    "workplace": "XX公司"
  },
  "lifestyle": {
    "smoking": "current",
    "drinking": {
      "drinks": true,
      "types": [
        {"type": "beer", "weekly_amount_ml": 1000, "duration_years": 20}
      ]
    },
    "occupation_exposure": "yes"
  },
  "hpv_test": {
    "result": "negative",
    "report_file_id": "file_xxx123"
  }
}

响应示例 - 评估结果

{
  "code": 0,
  "data": {
    "risk_level": "high",
    "risk_score": 78,
    "organ_risks": {
      "high": [
        {"organ": "lung", "name": "肺癌", "score": 85},
        {"organ": "liver", "name": "肝癌", "score": 72},
        {"organ": "stomach", "name": "胃癌", "score": 68},
        {"organ": "colorectal", "name": "结直肠癌", "score": 65}
      ],
      "medium": [
        {"organ": "ovary", "name": "卵巢", "score": 45},
        {"organ": "lymph", "name": "淋巴", "score": 42}
      ]
    },
    "suggestion": "建议进行肿瘤专项健康管理服务...",
    "disclaimer": "本评估结果仅供参考，不作为临床诊断依据"
  }
}

4 线上咨询

编号	接口名称	方法	路径	说明
API-013	获取医生列表	GET	/api/v1/doctors	返回医生列表，支持按科室筛选，含头像/姓名/职称/科室/医院
API-014	获取医生详情	GET	/api/v1/doctors/{id}	返回医生完整信息：擅长领域/个人简介/执业资质
API-015	发起咨询	POST	/api/v1/consultations	创建咨询会话，返回会话ID
API-016	获取消息列表	GET	/api/v1/consultations/{id}/messages	分页获取会话消息，支持游标分页
API-017	发送消息	POST	/api/v1/consultations/{id}/messages	发送文字消息，通过WebSocket实时推送

5 线下就医

编号	接口名称	方法	路径	说明
API-018	获取企微二维码	GET	/api/v1/medical-assistance/qrcode	返回动态企微二维码URL和过期时间
API-019	确认添加管家	POST	/api/v1/medical-assistance/confirm	用户确认已添加企微，记录状态

6 健康档案

编号	接口名称	方法	路径	说明
API-020	获取咨询记录列表	GET	/api/v1/health-records/consultations	返回历史咨询记录，按时间倒序
API-021	获取随访计划列表	GET	/api/v1/health-records/follow-up-plans	返回随访计划，含检查项目/时间/状态
API-022	获取咨询详情	GET	/api/v1/health-records/consultations/{id}	返回指定咨询的完整对话记录

7 文件与通知

编号	接口名称	方法	路径	说明
API-023	获取上传凭证	GET	/api/v1/upload/token	获取文件上传STS凭证（直传OSS）
API-024	发送通知	POST	/api/v1/notifications/send	系统通知发送（审核完成/随访提醒等）

8 WebSocket 实时通信

事件	方向	触发时机	数据结构
message_received	Server→Client	医生发送消息	{type:"message", consultation_id, message:{id, content, sender, timestamp}}
consultation_ended	Server→Client	医生结束/超时结束	{type:"consultation_ended", consultation_id, reason}
review_status_changed	Server→Client	审核状态变更	{type:"review_status", status:"approved"/"rejected", reason}
typing	双向	对方正在输入	{type:"typing", consultation_id, user_id}

9 通用约定

9.1 请求头

Content-Type: application/json
Authorization: Bearer {access_token}
X-Request-Id: {uuid}  // 请求追踪
X-App-Version: 1.0.0  // 客户端版本

9.2 统一响应格式

{
  "code": 0,        // 0=成功，非0=错误码
  "message": "success",
  "data": { ... },  // 业务数据
  "timestamp": 1695278400
}

9.3 错误码定义

错误码	含义	处理方式
0	成功	-
1001	参数校验失败	前端展示字段级错误
1002	数据不存在	前端展示空状态
2001	未登录/Token过期	跳转登录页
2002	无权限	展示无权限提示
3001	文件上传失败	展示重试按钮
3002	文件格式不支持	展示格式要求提示
5000	服务器内部错误	展示"系统繁忙"提示

9.4 分页约定

// 请求参数
?cursor={cursor}&limit=20

// 响应
{
  "list": [...],
  "next_cursor": "xxx",  // null表示无更多
  "has_more": true
}