API 接口文档

接口文档

v1 · contract 1.0.0

本服务把体检报告转换成结构化的健康管理方案。

接口只返回 JSON，不返回渲染结果 —— 报告页面由接入方自行渲染。

所有字段以契约为准：稳定 id（如 cardiovascular）用于程序判断，中文标签仅供展示。

快速开始 · 三步

提交 → 轮询 → 取方案

1 · 提交

受理即返回 jobId（毫秒级），生成在后台进行。

curl -X POST "$BASE/v1/api/healthPlan/submit" \
  -H "authorization: Bearer $API_KEY" \
  -H "content-type: application/json" \
  -d '{"idempotencyKey":"<UUID>","reportJson":{...},"customerRef":"crm-42"}'

返回 { "error_code": 0, "data": { "jobId": "qjg-..." }, "trace_id": "..." }

2 · 轮询

建议 2 秒一次；失败会带 failureCode。

curl -X POST "$BASE/v1/api/healthPlan/status" \
  -H "authorization: Bearer $API_KEY" \
  -H "content-type: application/json" \
  -d '{"jobId":"qjg-..."}'

返回 { "error_code": 0, "data": { "state": "succeeded" } }

3 · 取方案

返回 PlanResult v1；未完成 409，失败 502。

curl "$BASE/v1/api/healthPlan/result?jobId=qjg-..." \
  -H "authorization: Bearer $API_KEY"

返回 { "schemaVersion": "1.0.0", "dimensions": [ … 7 项 … ] }

端点 · 对外接口

全部对外接口

正式路径位于 /v1 之下；不带前缀的旧路径仍可用，但响应头会带 Deprecation。机器可读文档见 /openapi.json。

POST/v1/api/healthPlan/submit需要 API key

把体检报告原始 JSON 交给服务，受理后异步生成方案。

超时重试请用**同一个 idempotencyKey**，不会产生两份方案。

请求字段

idempotencyKeystring · 必填幂等键（规范 UUID）。同一键重复提交不会重复生成
reportJsonobject · 必填体检报告原始 JSON（客户系统导出格式）
customerRefstring客户侧不透明引用；**跨次积累（状态与记忆）依赖它**，不传则不做累积
sourcestring调用来源标识（只留档）

200 已受理401 缺少或错误的 API key429 超出配额

POST/v1/api/healthPlan/status需要 API key

轮询任务状态：running / succeeded / failed。

建议 2 秒一次；失败时 failureCode 会说明原因。

请求字段

jobIdstring · 必填

200 状态（running / succeeded / failed）401 未授权

GET/v1/api/healthPlan/result需要 API key

取结构化方案（PlanResult v1）。这是正式交付物，客户自行渲染。

任务未完成返回 409，退避重试（2s → 4s → 8s）。

200 方案契约400 jobId 不合法401 未授权404 任务不存在409 任务尚未完成（job-not-ready）502 任务失败（返回失败码与原因）

GET/v1/api/healthState需要 API key

读某客户跨次累积的健康状态：版本、最近观察、注意力提示。

需要两个凭据：租户 API key + 状态读取 token。

200 状态投影（版本、最近观察、注意力提示）401 未授权404 该主体暂无状态记录

POST/v1/api/healthPlan/revision-decision需要 API key

医生审批 Agent 提交的方案修订提案（人工动作，不是 agent 工具）。

驳回必须写理由；批准不自动应用，需要最终文案并重渲染。

请求字段

jobIdstring · 必填
revisionIdstring · 必填
decisionstring · 必填
decidedBystring · 必填审批人标识（必填，可追溯）
reasonstring驳回时必填（至少 5 字）
finalTextstring批准时可选：医生给出的最终文案

200 已记录审批（applied=false）400 缺 decidedBy / 驳回缺理由 / 参数不合法401 审批 token 不匹配404 任务或提案不存在409 提案已审批过（不可改写历史）503 审批 token 未配置，拒绝一切审批

字段语义 · 容易踩的点

dimensions[].id 才能当键

id 是稳定英文标识（七维固定）；label 是中文展示名，可能随文案调整。程序判断一律用 id。

timing: null 表示"还没有明确时机"

占位文案（如「待医生确认」）不会输出到契约里；null 不等于"随时"。

serviceItems 为空是正常状态

表示本次资料未形成可展示的服务建议，原因在 notices 字段；不会出现占位假条目。

幂等由 idempotencyKey 决定

超时重试用同一个键，不会重复生成；不同键会各自生成一份。

七个维度 id

程序判断请用 id，不要用中文标签（标签可能随文案调整）。

id	label
cardiovascular	心血管系统
neurological	神经系统
endocrine_metabolic	内分泌与代谢
hepato_digestive	肝胆与消化
respiratory	呼吸系统
urologic_reproductive	泌尿与生殖
immune_inflammation	免疫与炎症

错误处理

状态码与建议动作

状态码	含义	建议
400	请求不合法（如 jobId 格式错）	修参数，不要重试
401	API key 缺失或错误	检查密钥
404	任务或资源不存在	核对 jobId
409	任务尚未完成（job-not-ready）	退避重试 2s → 4s → 8s
429	超出配额（默认 60 次/分钟/租户）	退避
502	任务失败（返回 failureCode）	记录失败码并对账
503	端点未配置（如审批 token 缺失）	联系服务方

数据与合规

服务端不保存体检报告原文：只保留归一后的事实，身份证号、手机号、住址、姓名不落盘。
customerRef 是识别同一客户的唯一依据；同一客户多次体检请传相同 customerRef，否则跨次累积不生效。
数据默认保留 90 天（可配置），到期自动清理；支持按客户删除。

配额：每租户 60 次/分钟 · 数据保留 90 天

全链路 · 从数据到生成物

一张图看懂谁在什么时候做什么

从报告进入网关，到多域审核、系统签发、补渲染 PDF，最后交给客户自有系统取件与触达。关键边界只有一条：Agent 不接触客户，也不替人作出医疗决定。

01
Agent 网关
打分 · 生成 · 渲染
机构提交体检报告后进入网关：证据标准化 → HRA-5 风险项 → 医生确认，再输出结构化结论与行动清单。每个结论保留证据、规则版本与确认记录。
02
多域独立审核
营养 · 运动 · 医学 · 更多
营养师、运动指导、全科医生等角色各自审本域内容，可乱序、可驳回；域可随业务扩展。审核方拿到的是域视图 JSON（只含本域），不是整份 PDF。
03
多域都通过？
状态机
各域齐后自动进入签发；任一域驳回则回到重做，不通过就不生成 PDF。
驳回 1–2 次
重做该域（domain_rework_required）→ 回到 01
同一域驳回 3 次
人工接手（manual_takeover）→ 改稿回传
04
系统签发
自动签发
多域全部通过后由系统自动签发，不需要任何人再点一次；签发是状态机完成的，不是人工动作。
05
补渲染 PDF
签发后才有
签发后自动补渲染个人版与团队版 PDF，与 HTML 同源、内容一致。撤签时 PDF 删除，回到两件 HTML。
06
客户自有系统取件
只读凭证
客户自有系统（CRM、会员系统等）用只读凭证拉取交付清单与单份产物：两件 HTML、两件 PDF，以及每日执行卡、计划节点与日历任务。
07
客户触达
由机构完成
微信、短信或 App 由机构自己选择。Agent 只负责把内容做出来、把数据准备好，不直接接触客户。

演示 · 编排形态

Agent 编排怎么推进节点

接入后，机构通过接口提交数据、取回评估结果；Agent 在中间推进工作流节点，把需要人决定的部分整理好交回。下面是节点、角色与「需要拍板」的形态示意。

Agent 编排 · 已完成当前已可交付

Agent 编排工作流节点，按规则推进服务

Agent 编排 · 形态示意

当前能力

节点编排 · 形态示意

节点分派评估结果进入随访节点按风险分层与职责条件分派，写清责任与时限待接手
状态推进近 7 天记录尚未补齐资料缺口挂在节点上，而不是留在某人的记忆里等待资料
升级转人工达到复核条件，提交医生团队附完整证据链与规则版本；规则未覆盖时不强行推进待复核

Agent 编排节点，人作出决定

同一份评估依据同一张节点清单同一条状态记录同一套度量口径

当前已支持

事件识别

评估结果、复查到期、用户反馈进入工作流。

节点分派

按职责与风险条件映射到角色，写清责任与时限。

状态推进

跟进停滞节点、补齐缺失资料，保留状态变化。

升级与转人工

达到复核条件交给医生团队；规则未覆盖时不强行推进。

结果回流

实际结果回写，更新服务理解并触发下一轮。

Agent 编排层已完成，可用于工作流节点编排、角色分派、状态推进与结果回流；具体接入范围与角色权限在实施阶段按机构流程确认。

以上为界面示意，实际节点与角色按机构流程配置。

先聊接入接入由双方在实施阶段确认范围

接口文档

提交 → 轮询 → 取方案

全部对外接口

dimensions[].id 才能当键

timing: null 表示"还没有明确时机"

serviceItems 为空是正常状态

幂等由 idempotencyKey 决定

七个维度 id

状态码与建议动作

一张图看懂谁在什么时候做什么

Agent 网关

多域独立审核

多域都通过？

系统签发

补渲染 PDF

客户自有系统取件

客户触达

Agent 编排怎么推进节点

Agent 编排工作流节点，按规则推进服务