面向后端研发 / 前端研发 / 测试 / 联调对接的接口契约文档。定义用户端、运营后台、医生后台三端全部数据交互接口，含免登录激活、报告上传、状态机流转、AI 解读、审核审批、建议书、咨询与随访、客户 360、工单、穿戴数据等 12 大分类共 36 个 REST 端点与 1 组 WebSocket 事件。
https://api.you-thealth.cn/apiAuthorization: Bearer {token}X-App-Ver 客户端版本X-Biz-Line 业务线标识X-Request-Id 幂等/追踪可用（建议）code 业务码（0 为成功）msg 提示信息data 业务数据（可空）traceId 链路追踪链接激活 · 身份识别
S1–S4拍照 / PDF / 多张
U1–U54 节点 · 解析
P1–P4材料 / 医助 / 医生 / 主任
R1–R8生成 / 编辑 / 下载
G1–G4跳题 · 72 小时会话
Q1–Q3计划 · 补录 · 聚合
F1–F3指标 · 通用存储
W1–W2| 端点 | method | 请求参数 | 响应格式 | 鉴权 | 错误码 |
|---|---|---|---|---|---|
| /auth/activate （链接激活） | POST | ticket（激活票据）、bizLine（业务线）、channel（渠道）、openId（可选，微信） |
{code,msg,data:{userId,token,expiresIn,isNew,serviceId}} |
免登录票据 | 20101 票据失效 / 20102 已过期 |
| 无需账号密码打开链接即激活；服务闭环第一步，防重放（单次票据、有效期）。 | |||||
| /auth/identity | GET | ticket / userKey |
{data:{customerId,name,gender,age,services:[{serviceId,status}]}} |
免登录 | 20103 身份不可识别 |
| /auth/refresh | POST | refreshToken |
{data:{token,expiresIn}} |
RefreshToken | 20104 Refresh 失效 |
| /auth/session | GET | — | {data:{valid,serviceId,progress,contactPhone}} |
需 Token | 401 / 20101 |
| 端点 | method | 请求参数 | 响应格式 | 鉴权 | 错误码 |
|---|---|---|---|---|---|
| /report/upload/image | POST | image（multipart）、serviceId、type（体检/影像）、可多页 |
{data:{fileId,url,thumbUrl,ocrStatus,exifAware}} |
需 Token | 20201 文件过大 / 20204 非图片 |
| /report/upload/pdf | POST | pdf（单 PDF ≤20MB）、serviceId、页范围 |
{data:{fileId,pageCount,size,ocrStatus}} |
需 Token | 20202 PDF 解析失败 |
| /report/upload/multi | POST | files[]（≤20 张/次）、逐张 image 或 pdf、次序 |
{data:{items:[{fileId,ok,err}],overall:"partial"/"all"}} |
需 Token | 20205 批量超限 / 20203 单张失败 |
| /report/upload/{id} | DELETE | — | {code,msg} |
需 Token | 404 / 20206 已提交不可删 |
| /report/upload/task | GET | taskId / serviceId |
{data:{progress,stage,fileCount,totalBytes,status}} |
需 Token | 404 |
| 端点 | method | 请求参数 | 响应格式 | 鉴权 | 错误码 |
|---|---|---|---|---|---|
| /report/status | GET | serviceId |
{data:{nodes:[{key,label,time,operator}],current,overall:"pending/processing/done"}} |
需 Token | 404 |
| /report/detail | GET | serviceId |
{data:{images[],metrics[],abnormal[],aiSummary}} |
需 Token | 404 |
| /ai/parse | POST | reportId、files[]、options（OCR+指标提取+初步结论） |
{data:{taskId,status,progress}} |
需 Token | 20301 解析排队 / 20302 模型异常 |
| /ai/parse/{reportId} | GET | — | {data:{ocrText,metrics[],abnormalFlags[],conclusion,tos,suggestion}} 挂起/就绪/失败 |
需权限 | 20303 未就绪 |
| 端点 | method | 请求参数 | 响应格式 | 鉴权 | 错误码 |
|---|---|---|---|---|---|
| /review/material/list | GET | 分页 / status / bizLine | {data:{list,total,page}} | 运营 | 401 / 403 |
| /review/material/{id}/approve | POST | remark（可选） | {data:{nextNode:"ai_parse"}} | 运营 | 20401 材料不完整 |
| /review/material/{id}/reject | POST | reason必填、退回节点 | {code,msg} | 运营 | 20402 退回原因必填 |
| /review/assistant/list | GET | 分页 / 业务线 | {data:{list,total}} | 运营 | 401 / 403 |
| /review/assistant/{id} | GET | — | 内含 aiReference（富文本+AI 参考） | 运营 | 404 |
| /review/assistant/{id}/submit | POST | draft富文本、aiRefResult核对结论、riskLevel | {data:{nextNode:"doctor"}} | 运营 | 20403 核对项缺失 |
| /review/doctor/list | GET | 分页 / 医生维度 | {data:{list,total}} | 医生 | 401 / 403 |
| /review/doctor/{id}/apply-code | POST | assessBody富文本、signPhone | {data:{sent:true,expiresIn}} 发送短信签名验证码 | 医生 | 20501 验证码限频 / 20502 手机号不匹配 |
| /review/doctor/{id}/assess | POST | assessBody、smsCode、recommendation | {data:{nextNode:"chief"}} 携带短信号签提交 | 医生 | 20503 签名验证码错误 / 20504 评估未填写必填项 |
| /review/chief/{id} | GET | — | 含 doctorAssess 预览 | 主任 | 404 |
| /review/chief/{id}/finalize | POST | comment、决定通过 | {data:{nextNode:"suggestion"}} | 主任 | 20601 二次签名缺失 |
| /review/chief/{id}/revert | POST | reason必填、目标节点 | {code,msg} 专家撤回 | 主任 | 20602 撤回原因必填 |
材料审核 → AI 解析 → 医助评估 → 医生初审 → 主任确认 → 建议书 → 完成。除主任可"专家撤回"外，运营/医助/医生在同节点内可退回材料端；任一环节携带签名与操作溯源日志。| 端点 | method | 请求参数 | 响应格式 | 鉴权 | 错误码 |
|---|---|---|---|---|---|
| /suggestion/generate | POST | serviceId、合并主任结论与医生评估 | {data:{suggestionId,status,pdfReady}} | 医生/主任 | 20701 缺少评审结论 |
| /suggestion/{id} | GET | — | {data:{content,version,status}} | 需 Token | 404 |
| /suggestion/{id}/edit | PUT | content富文本、version乐观锁 | {data:{version:v+1}} 仅待确认态可编辑 | 医生 | 20702 版本冲突 / 20703 非可编辑状态 |
| /suggestion/{id}/confirm | POST | signInfo确认签名 | {data:{status:"confirmed"}} | 医生 | 20704 未签名不可确认 |
| /suggestion/{id}/pdf | GET | — | application/pdf 流式下载（可加水印） | 需 Token | 20705 PDF 未就绪 |
| 端点 | method | 请求参数 | 响应格式 | 鉴权 | 错误码 |
|---|---|---|---|---|---|
| /questionnaire/template | GET | bizLine、version | {data:{items:[{id,type,branchRules}]}} 含条件跳题规则 | 需 Token | 401 |
| /questionnaire/submit | POST | answers[]、按跳题逻辑强校验 | {data:{score?,riskFlag,nextValid}} | 需 Token | 20801 必答遗漏 / 20802 跳题非法 |
| /consult/create | POST | serviceId、topic、需在服务内 | {data:{sessionId,expiryAt(now+72h)}} | 需 Token | 20901 会话已存在 |
| /consult/list | GET | 分页 / 状态 | {data:{sessions[],unread}} | 需 Token | 401 |
| /consult/{id}/message | POST | content、type(text/image)、客户端 msgId | {data:{serverMsgId,ts}} | 需 Token | 20902 会话已过期(72h) |
| 端点 | method | 请求参数 | 响应格式 | 鉴权 | 错误码 |
|---|---|---|---|---|---|
| /followup/plan | GET | serviceId | {data:{cycles:[{seq:1/2/3,dueAt,status}]}} | 运营 | 401 |
| /followup/{id}/phone-record | POST | cycle、callAt、outcome、note补录 | {data:{recordId}} | 运营 | 21001 呼叫状态异常 |
| /followup/{id}/task | POST | dateRange、assignee | {data:{taskId,plan}} | 运营 | 21002 计划冲突 |
| /customer/{id}/360 | GET | — | {data:{profile,reports[],services[],consults[],followups[],orders[],risk}} | /运营 / 医生 | 21101 无查看权限 |
| /ticket/create | POST | type(体检预约/线下就诊)、slot、prefer | {data:{ticketId,status,dispatch}} | 需 Token | 21201 槽位已满 |
| /ticket/{id} | GET | — | {data:{status,history[]}} | 需 Token | 404 |
| /wearable/metric | GET | from/to、bindDeviceId | {data:{series[],interval}} | 需 Token | 21301 绑定失效 |
| /file/upload | POST | file(≤50MB)、scope | {data:{fileId,url}} 内容安全未过则 21402 | 需 Token | 21401 类型受限 / 21402 安全审核不通过 |
| /file/{id} | GET | — | application/octet-stream | 需 Token | 404 |
连接端点：wss://api.you-thealth.cn:8443/ws?token={jwt}。消息为 JSON 文本，携带 traceId 与递增序列 seq。
| 事件类型 | 方向 | 字段 | 说明 |
|---|---|---|---|
| message.new | 服务端→客户端 | sessionId,msgId,from,content,type,sentAt | 对外发消息的实时送达（72 小时会话内） |
| message.send | 客户端→服务端 | sessionId,clientMsgId,content,type | 客户端发起消息；服务端回 ack |
| ack | 服务端→客户端 | clientMsgId,serverMsgId | 消息落库回执，用于 UI 状态从"发送中→已发送" |
| message.delivered | 服务端→客户端 | msgId,to | 对方已接收（可达但未读） |
| message.read | 两端双向 | msgId,reader,timestamp | 对方已读，UI 更新"已读"标识与气泡角标 |
| typing | 两端双向 | sessionId,state:"on/off" | 正在输入提示 |
| presence.online | 服务端→客户端 | userId,activeAt | 会话对象上线（在线状态） |
| presence.offline | 服务端→客户端 | userId,leaveAt | 会话对象离线 |
| session.expired | 服务端→客户端 | sessionId,expiredAt | 72 小时会话过期通知，清理 UI、禁止发送 |
lastSeq 做增量补齐，防丢消息。| code | HTTP | 含义 | 处理建议 |
|---|---|---|---|
| 0 | 200 | 成功 | — |
| -1 | 500 | 系统内部错误 | 展示兜底提示并上报 traceId |
| 401 | 401 | Token 缺失/失效/过期 | 跳登录/重新激活 |
| 403 | 403 | 无权限（角色/业务线不符） | 提示无权访问 |
| 404 | 404 | 资源不存在 | 提示已删除或链接失效 |
| 429 | 429 | 触发限频（发送/提交） | 引导稍后再试 |
| 20101 | 400 | 激活票据无效/失效 | 引导重新获取链接 |
| 20102 | 400 | 激活票据过期 | 引导重新获取链接 |
| 20103 | 404 | 身份不可识别 | 工单或人工核验 |
| 20201 | 400 | 文件超过上传大小上限 | 压缩后重传 |
| 20202 | 400 | PDF 解析失败/损坏 | 换格式或重新上传 |
| 20401 | 422 | 材料不完整无法通过审核 | 补齐材料 |
| 20503 | 400 | 医生短信签名验证码错误 | 重新获取/校验 |
| 20602 | 422 | 主任撤回原因未填写 | 补充撤回原因 |
| 20702 | 409 | 建议书版本冲突 | 刷新后重试 |
| 20902 | 400 | 咨询会话已超 72 小时过期 | 新建服务重新发起 |
| 21201 | 400 | 体检预约/就诊槽位已满 | 改期选择 |
| 21402 | 400 | 上传内容未通过安全审核 | 移除违规内容后重传 |
code==0 判成功；HTTP 状态仅做传输层粗分类，业务判断一律以 code 为准。所有业务码在本表基础上追加，新码须同步登记本清单并评审。