---
doc_id: API-202606-002
feature_id: FEAT-202606-001-unified-entry-client
type: api
title: 医梦 AI 中台对外接口设计文档 v1.2
status: approved
owner: 医梦研发团队
created_at: 2026-06-03
updated_at: 2026-06-03
reviewers: []
related_docs:
  - PRD-202605-001
  - ODS-202606-001
related_modules:
  - emoon-openplatform
  - emoon-ai-agent
  - emoon-ai-card
  - emoon-ai-mcp
  - emoon-ai-device
tags:
  - 对外接口
  - 联调基准
  - OpenAPI
---

# 医梦 AI 中台对外接口设计文档 v1.2｜正式联调基准版

> 文档定位：厂商对接接口全貌 + MVP 可落地接口契约说明  
> 适用对象：HIS/EMR/LIS/PACS/叫号/支付厂商、机器人厂商、自助机/导诊屏/诊室屏/大屏厂商、四诊仪厂商、迪耐克/鸿蒙病房互通方、医院信息科、医梦内部研发与测试  
> OpenAPI 文件：`docs/api/openapi/医梦AI中台开放平台接口-v1.2.openapi.yaml`（文件名沿用 v1.2，`info.version` 为 1.2.3）
> 版本：v1.2.3
> 生成时间：2026-06-03 18:00

---

## 0. 本版结论

本版不是把接口无限做大，而是把接口分成三层：

| 优先级 | 定位 | 研发策略 | 是否建议春节前稳定 |
|---|---|---|---|
| **P0** | 厂商联调前必须稳定的最小闭环 | 必须进入 OpenAPI；请求/响应 schema 要相对完整 | 是 |
| **P1** | 第一轮试点上线增强能力 | 先进入接口规划和 OpenAPI，占位或局部实现 | 视项目节奏 |
| **P2** | 生产运营、商业闭环、区域化能力 | 规划全貌，避免未来重构；不承诺春节前完成 | 否 |

本版在 v1.1 基础上采纳本轮审查中合理的问题，形成正式联调基准版：补充文件删除幂等、文件上传幂等语义、`clientFileId`、`sha256`、`retentionPolicy`、住院设备映射边界、工具风险等级、`/meter/events` 查询范围收敛，并将 FHIR 可选映射从主 OpenAPI YAML 移出，避免厂商误解为当前交付承诺。

2026-05-31 补充统一入口客户端口径：本次不新增 P0 URL，而是收敛终端调用白名单、AgentRouter/TaskState 内部职责和前后端工程边界。OpenAPI YAML 文件名沿用 v1.2，`info.version` 当时升级为 1.2.1，并将 `AgentChatRequest.agentId` 改为可选以支持后端路由。

2026-06-03 根据空海医院会议补充“动线 + 感知”口径：本次仍不新增 P0 URL，只在现有场景、设备事件和对话接口中增加可选 `perceptionContext`、服务端返回 `journeyState`、`perceptionCapabilities`、`journeyPolicy`，用于支撑“同一设备、不同用户、不同动线阶段展示不同智能体服务”。P0 只做扫码/NFC/刷卡/人工确认和服务区域级事件，不承诺全院无感定位、连续轨迹、自动签到、自动缴费。

2026-06-03 交叉 review 后修正：`journeyState` 只允许服务端返回，客户端请求不得传入；`journey_updated` 作为 P0 SSE 事件，避免前端从 `task_updated/card_created` 反推动线阶段。



### v1.2 相比 v1.1 的关键修正

| 修正项 | 处理方式 | 影响 |
|---|---|---|
| 文件删除幂等 | `DELETE /files/{fileId}` 增加 `X-Emoon-Idempotency-Key`，重复删除返回首次结果或已删除状态 | 防止敏感文件删除操作重试时审计不一致 |
| 文件上传幂等 | `FileUploadRequest` 增加 `clientFileId`、`sha256`、`source`、`retentionPolicy` | 支撑舌诊、面诊、报告、音频等文件的安全上传与重复上传识别 |
| 住院设备边界 | `DeviceContext` 增加 `managementMode`、`externalSystem`、`externalDeviceId` | 区分医梦直管门诊设备与迪耐克/鸿蒙病房映射设备 |
| 动线与感知 | `AgentChatRequest` 增加可选 `perceptionContext`，响应和 SSE 返回 `journeyState`，`DeviceSceneData` 增加 `perceptionCapabilities/journeyPolicy` | 支撑服务找人和同设备差异化能力，但不扩大 P0 URL 面 |
| 工具风险等级 | `ToolInvokeRequest` / `ToolCatalogItem` 增加 `riskLevel` | 明确查询、敏感查询、业务写入、财务动作、医疗正式写入的不同控制要求 |
| 计量查询收敛 | `/meter/events` P0 只支持 `billingEpisodeId` / `traceId` 精确查询 | 防止普通厂商误以为可查询完整项目账单或全量成本明细 |
| FHIR 降噪 | `/fhir/{resourceType}/$translate` 从主 YAML 移除，仅保留为远期可选规划 | 避免 HIS 厂商误解医梦当前要提供完整 FHIR 网关 |

关键取舍：

1. **不直接暴露 Dify Key**：所有 AI 调用统一走 OpenPlatform。
2. **普通设备厂商不得直接调用 `/tools/{toolName}/invoke`**：设备只能走设备接口、智能体接口、卡片动作接口。
3. **写操作必须幂等**：挂号、签到、缴费、卡片动作、HIS 写接口必须带 `X-Emoon-Idempotency-Key`。
4. **文件先上传后引用**：舌诊、面诊、报告解读等多模态场景先调用 `/files/upload` 获得 `fileId`，再传入 `/agent/chat`。
5. **设备上下文进入每次关键调用**：`deviceContext` 进入 chat、card action、device event、meter event。
6. **P0 能真实联调，P1/P2 先给全貌**：防止接口规划缺口导致未来返工。

### 0.1 v1.2.3 统一入口客户端补充口径

| 主题 | 接口口径 | 原因 |
|---|---|---|
| 终端调用白名单 | 机器人、自助机、导诊屏、诊室屏等统一入口客户端只允许调用 Device、`/agent/chat/stream`、Conversation、File、Card、Device Event、Device Command 相关接口 | 保持终端轻量，避免终端绕过中台审计和计量 |
| `/agent/chat` | 保留为同步对话、服务端联调和不支持 SSE 的受控调用；统一入口客户端默认使用 `/agent/chat/stream` | 医院终端需要流式反馈和卡片事件，SSE 更适合 P0 体验 |
| TaskStateService | 不新增公共 `/tasks` P0 接口；`taskId`、`taskType`、`taskStatus` 通过 SSE 事件、会话查询和卡片实例返回 | 减少接口面，避免第一期多维护一组状态查询 API |
| AgentRouter | 作为 `emoon-ai-agent` 内部能力，不对外暴露路由接口 | 外部厂商只关心结果，不应依赖医梦内部路由规则 |
| 舌诊底层接口 | 终端只能走 `/files/upload` + `/agent/chat/stream` + `/cards/{id}/actions/{name}`，不得直连舌诊 SDK/API | 舌象图片属于敏感医疗数据，必须统一文件审计和工具审计 |
| HIS Mock/Real Adapter | Mock 阶段和真实阶段对终端接口不变，差异只在后端 `HospitalAdapter` 配置 | 便于 MVP 先联调，后续替换真实 HIS 不改终端 |
| 前后端工程边界 | 后端能力仍在 AI 中台统一工程；前端/移动端另起 `emoon-terminal-client` | 符合团队资源现状，避免一个仓库混合终端构建、后端模块和 Demo 服务 |
| 动线/感知字段 | `perceptionContext` 是终端上报的最近一次感知事实，`journeyState` 只由后端结合 HIS/叫号/任务状态推导后返回 | 前端不得传入或自行判断已签到、可缴费、可挂号成功 |
| 设备能力差异 | `/devices/{deviceId}/scene` 返回 `allowedAgents/allowedCards/perceptionCapabilities/journeyPolicy` | 同一设备面向患者、医护、访客和不同动线阶段时能力不同 |

### 0.2 本接口边界的行业依据

| 依据 | 对接口设计的约束 |
|---|---|
| 东软 5G 智慧医院公开方案强调统一信息平台集成各子系统 | 医梦接口只做 AI 入口、设备场景和受控工具，不把自己设计成完整 HIS/EMR 替代品 |
| 华为智慧病房/医疗物联网公开方案强调物联网平台和多协议设备接入 | 住院 IoMT、床头屏、护理白板优先通过外部病房/物联平台事件接入，不让医梦接口承担原始设备接入责任 |
| 科大讯飞智慧医疗公开资料强调 AI 嵌入医生现有流程和辅助决策 | 高风险医疗动作必须通过 Card Action 和人工确认，不开放“自动诊断/自动处方”接口 |
| Dify 官方已有 Workflow 版本控制能力 | 接口层不暴露 Dify 内部发布 API，医梦只维护 Agent 配置、版本映射和输出归一 |
| 《个人信息保护法》对医疗健康、行踪轨迹等敏感个人信息有严格要求 | 文件、位置、设备事件和服务找人接口必须最小化采集、可审计、可降级 |

---

## 1. 接口设计边界

### 1.1 医梦中台对外开放的不是“数据库接口”

对外接口只开放业务能力和设备能力，不开放内部表结构。厂商不应关心医梦内部使用 Dify、MCP、Card Runtime、Metering 还是其他实现。

```text
外部厂商 -> OpenPlatform API -> 鉴权/限流/幂等/审计 -> Agent/Card/Device/Tool -> 医院系统或设备
```

### 1.2 三类厂商的接入边界

| 厂商类型 | 推荐接入方式 | 禁止事项 |
|---|---|---|
| 机器人/自助机/屏幕厂商 | Device API + Agent API + Card Action API | 不直接调用 HIS Tool，不直接持有 Dify Key |
| HIS/EMR/LIS/PACS/叫号/支付厂商 | Tool API + Webhook/Event API | 不直接参与 AI 会话编排，不绕过医梦审计链路 |
| 四诊仪/专用设备厂商 | Device API + File API + Agent/Card API | 不把原始敏感图像暴露给非授权系统 |

---

## 2. 全量接口规划：按优先级分类

### P0 接口清单

|模块|主要厂商/对象|方法|路径|接口|说明|
|---|---|---|---|---|---|
|通用平台|全部厂商|POST|`/auth/token`|获取短期访问 Token|厂商使用 client_credentials 获取 accessToken；也可用于服务端系统对接。|
|通用平台|全部厂商|GET|`/health`|平台健康检查|用于联调前探活，不返回敏感配置。|
|通用平台|全部厂商|GET|`/capabilities`|查询项目已开通能力|让厂商知道当前项目可调用哪些 Agent、工具、设备能力和计费策略。|
|智能体与会话|受控服务端/不支持 SSE 的终端|POST|`/agent/chat`|智能体同步对话|首轮 conversationId 可为空，平台自动创建会话并返回；统一入口客户端默认不使用该接口。|
|智能体与会话|机器人/自助机/导诊屏/诊室屏|POST|`/agent/chat/stream`|智能体流式对话 SSE|POST + SSE；必须支持断线后按 conversationId 查询最终消息、任务状态和卡片。|
|智能体与会话|终端厂商/患者端/医生端|POST|`/conversations`|创建会话|可选预创建；chat 不传 conversationId 时自动创建。|
|智能体与会话|终端厂商/患者端/医生端|GET|`/conversations/{conversationId}`|查询会话详情|用于断线恢复、历史状态恢复。|
|智能体与会话|终端厂商/患者端/医生端|GET|`/conversations/{conversationId}/messages`|查询会话消息|用于 SSE 断线后的最终文本和卡片恢复。|
|文件与多模态|四诊仪/自助机/患者端/医生端|POST|`/files/upload`|上传图片/音频/文档|舌诊、面诊、报告解读等场景先上传文件，chat 只传 fileId。|
|文件与多模态|四诊仪/自助机/患者端/医生端|GET|`/files/{fileId}`|查询文件元数据|只返回元数据和受控访问状态，不默认返回公开 URL。|
|设备接入|机器人/自助机/大屏/诊室屏|POST|`/devices/register`|设备注册或激活|设备拿到 deviceId、deviceSecret、准入等级、默认场景。|
|设备接入|机器人/自助机/大屏/诊室屏|POST|`/devices/{deviceId}/heartbeat`|设备心跳|上报在线状态、版本、当前场景、错误摘要。|
|设备接入|机器人/自助机/大屏/诊室屏|GET|`/devices/{deviceId}/scene`|获取设备场景配置|返回 UI 模板、Agent 绑定、工具权限、设备能力开关。|
|设备接入|机器人/自助机/大屏/诊室屏|POST|`/devices/{deviceId}/events`|上报设备事件|扫码、打印、读卡、靠近、导航完成、异常等事件。|
|设备接入|机器人/自助机/大屏/诊室屏|GET|`/devices/{deviceId}/commands/poll`|轮询待执行命令|MVP 采用轮询，避免设备厂商必须开放公网回调。|
|设备接入|机器人/自助机/大屏/诊室屏|POST|`/devices/{deviceId}/commands/{commandId}/ack`|设备命令回执|设备执行命令后回报 success/failed。|
|卡片动作|终端厂商/HIS适配方|GET|`/cards/{cardInstanceId}`|查询卡片实例|用于卡片恢复、状态查询、历史审计。|
|卡片动作|终端厂商/HIS适配方|POST|`/cards/{cardInstanceId}/actions/{actionName}`|执行卡片动作|挂号、签到、建档、确认病历等确定性动作统一走卡片动作。|
|受控工具|HIS/EMR/LIS/PACS/叫号/支付适配方|POST|`/tools/{toolName}/invoke`|调用院内系统工具|仅开放给受控系统适配方；普通设备厂商不得直接调用。|
|计量与运营|医院信息科/医梦运营|GET|`/usage/summary`|查询基础用量汇总|春节前先做项目/设备/智能体/场景维度基础统计。|
|计量与运营|医院信息科/医梦运营|GET|`/meter/events`|查询计量事件|用于排障、能力值流水追踪，P0 只读。|
### P1 接口清单

|模块|主要厂商/对象|方法|路径|接口|说明|
|---|---|---|---|---|---|
|智能体与会话|终端厂商/患者端/医生端|GET|`/conversations`|查询会话列表|患者端历史咨询、医生端历史 AI 交互。|
|智能体目录|终端厂商/运营后台|GET|`/agents`|查询可用智能体列表|让终端动态展示可用能力。|
|智能体目录|终端厂商/运营后台|GET|`/agents/{agentId}`|查询智能体详情|返回 Agent 名称、场景、输入能力、输出卡片类型。|
|设备治理|设备厂商/医梦运营|GET|`/devices`|查询设备列表|设备运维、授权、在线率统计。|
|设备治理|设备厂商/医梦运营|GET|`/devices/{deviceId}`|查询设备详情|设备能力、版本、位置、场景绑定。|
|设备治理|医梦运营/设备厂商|PATCH|`/devices/{deviceId}/scene`|更新设备场景绑定|灰度切换 UI 模板和 Agent 绑定。|
|设备治理|医梦运营/设备厂商|GET|`/devices/{deviceId}/events`|查询设备事件|定位设备问题和事件回放。|
|Webhook|HIS/叫号/机器人/设备厂商|POST|`/webhooks`|注册 Webhook|第三方系统回调事件订阅。|
|Webhook|HIS/叫号/机器人/设备厂商|GET|`/webhooks`|查询 Webhook 列表|运营和联调管理。|
|Webhook|HIS/叫号/机器人/设备厂商|DELETE|`/webhooks/{webhookId}`|删除 Webhook|关闭事件订阅。|
|事件接入|HIS/叫号/迪耐克/病房系统|POST|`/events/ingest`|接收外部系统业务事件|挂号成功、叫号变更、护理预警等外部事件接入。|
|受控工具|HIS/EMR/LIS/PACS/叫号/支付适配方|GET|`/tools/catalog`|查询授权工具目录|让受控适配方知道当前项目可调用工具和 schema。|
|设备授权|医院信息科/医梦运营|GET|`/licenses/devices`|查询设备授权状态|设备授权、入口客户端授权和运维服务统计。|
### P2 接口清单

> P2 是远期规划能力，不进入春节前门诊主交付。FHIR 可选映射已从主 OpenAPI YAML 移除，仅在医院已有 FHIR 网关且项目合同明确要求时，另行提供独立 `emoon-ai-fhir-future.openapi.yaml`。


|模块|主要厂商/对象|方法|路径|接口|说明|
|---|---|---|---|---|---|
|伙伴与准入|医梦运营/合作厂商|POST|`/partners`|创建合作方接入档案|正式厂商准入、scope、密钥、设备类型绑定。|
|伙伴与准入|医梦运营/合作厂商|GET|`/partners/{partnerId}`|查询合作方档案|合规、联调、授权审计。|
|合同与套餐|医院/医梦商务运营|GET|`/contracts`|查询合同与套餐|对接合同、套餐、能力值包。|
|账户与额度|医院/医梦商务运营|GET|`/credit/accounts`|查询能力值账户|主账户、科室账户、区域账户。|
|账户与额度|医梦内部系统|POST|`/credit/accounts/{accountId}/freeze`|冻结能力值|高成本任务预冻结，通常不对外开放。|
|账户与额度|医梦内部系统|POST|`/credit/accounts/{accountId}/settle`|结算能力值|由计量账本驱动，通常不对外开放。|
|账单结算|医院/医梦商务运营|GET|`/billing/invoices`|查询账单|月账单、超量账单、科室分摊。|
|运营报表|医院/医梦运营|GET|`/operation/reports`|查询运营报告|用量、设备、智能体、科室、成本和质量指标。|
|审计合规|信息科/医梦运维|GET|`/audit/logs`|查询审计日志|敏感操作、工具调用、卡片动作、设备事件。|

---

## 3. 全量接口规划：按厂商分类

### 全部厂商

|建议接入接口|
|---|
|`POST /auth/token`|
|`GET /health`|
|`GET /capabilities`|
### 机器人厂商

|建议接入接口|
|---|
|`POST /devices/register`|
|`POST /devices/{deviceId}/heartbeat`|
|`GET /devices/{deviceId}/scene`|
|`POST /devices/{deviceId}/events`|
|`GET /devices/{deviceId}/commands/poll`|
|`POST /devices/{deviceId}/commands/{commandId}/ack`|
|`POST /agent/chat/stream`|
### 自助机/导诊屏/大屏/诊室屏厂商

|建议接入接口|
|---|
|`POST /devices/register`|
|`POST /devices/{deviceId}/heartbeat`|
|`GET /devices/{deviceId}/scene`|
|`POST /devices/{deviceId}/events`|
|`GET /cards/{cardInstanceId}`|
|`POST /cards/{cardInstanceId}/actions/{actionName}`|
|`POST /agent/chat/stream`|
### HIS/EMR/LIS/PACS/叫号/支付厂商

|建议接入接口|
|---|
|`POST /tools/{toolName}/invoke`|
|`GET /tools/catalog`|
|`POST /webhooks`|
|`POST /events/ingest`|
|`GET /meter/events`|
### 四诊仪厂商

|建议接入接口|
|---|
|`POST /devices/register`|
|`POST /devices/{deviceId}/heartbeat`|
|`POST /files/upload`|
|`POST /agent/chat/stream`|
|`GET /cards/{cardInstanceId}`|
|`POST /cards/{cardInstanceId}/actions/{actionName}`|
### 迪耐克/鸿蒙病房/住院互通方

|建议接入接口|
|---|
|`POST /events/ingest`|
|`POST /devices/register（仅映射终端）`|
|`POST /devices/{deviceId}/events（仅标准业务事件，不做硬件心跳主责）`|
|`POST /agent/chat/stream（仅明确需要 AI 嵌入时使用）`|
|`GET /tools/catalog`|
### 医院信息科/运营方

|建议接入接口|
|---|
|`GET /usage/summary`|
|`GET /meter/events`|
|`GET /licenses/devices`|
|`GET /operation/reports`|
|`GET /audit/logs`|

---

## 4. 通用规范

### 4.1 Base URL 与版本

| 环境 | Base URL |
|---|---|
| 沙箱 | `https://sandbox-api.emoon-ai.com/api/v1` |
| 医院私有化 | `https://api.{hospital}.emoon.local/api/v1` |

版本策略：

| 规则 | 说明 |
|---|---|
| URL 版本 | 破坏性变更升级 `/api/v2` |
| 非破坏性变更 | 新增可选字段、返回新增字段，不升级 URL |
| 枚举扩展 | 厂商必须能忽略未知枚举或降级处理 |
| 废弃策略 | 生产接口废弃前至少提前通知，具体周期写入合同或联调协议 |

### 4.2 鉴权方式

本版保留两种鉴权。MVP 阶段可以先稳定 Bearer Token，P0 高风险写操作逐步增加 HMAC。

| 鉴权 | 适用对象 | Header |
|---|---|---|
| Bearer Token | HIS 厂商、后台系统、受控服务器端 | `Authorization: Bearer <access_token>` |
| HMAC 签名 | 自助机、机器人、设备侧高风险调用 | `Authorization: EMOON-HMAC <access_key>` + 签名头 |

HMAC 必要请求头：

| Header | 必填 | 说明 |
|---|---:|---|
| `X-Emoon-Project-Id` | 是 | 项目/医院标识 |
| `X-Emoon-Partner-Id` | 是 | 合作方标识 |
| `X-Emoon-Timestamp` | 是 | Unix 毫秒时间戳，默认允许 ±300 秒 |
| `X-Emoon-Nonce` | 是 | 随机串，防重放 |
| `X-Emoon-Signature` | HMAC 模式必填 | HMAC-SHA256 签名 |
| `X-Emoon-Trace-Id` | 建议 | 链路排障 ID |
| `X-Emoon-Idempotency-Key` | 写接口必填 | 幂等键 |
| `X-Emoon-Device-Id` | 设备调用建议 | 设备上下文兜底 |

推荐签名串：

```text
HTTP_METHOD + "
" +
PATH_WITH_QUERY + "
" +
X-Emoon-Timestamp + "
" +
X-Emoon-Nonce + "
" +
SHA256_HEX(request_body)
```

### 4.3 Scope 与高风险接口

| Scope | 能力 |
|---|---|
| `agent:invoke` | 调用智能体 |
| `device:write` | 设备注册、心跳、事件上报 |
| `card:action` | 执行卡片动作 |
| `file:write` | 文件上传 |
| `tool:read` | 调用查询类院内工具 |
| `tool:write` | 调用写类院内工具，高风险，仅受控适配方 |
| `usage:read` | 查询用量和计量事件 |
| `webhook:manage` | 管理 Webhook |

`/tools/{toolName}/invoke` 必须有 `tool:read` 或 `tool:write`，并且只允许受控系统适配方调用。普通设备厂商不得直接调用。

### 4.4 幂等

所有产生业务事实的接口必须支持 `X-Emoon-Idempotency-Key`。

| 接口类型 | 幂等键建议 |
|---|---|
| 对话请求 | `projectId + resolvedAgentId/routeKey + clientMessageId`；统一入口客户端未传 `agentId` 时由后端路由结果补齐 |
| 设备事件 | `projectId + deviceId + eventType + eventId` |
| 卡片动作 | `projectId + cardInstanceId + actionName + clientActionId` |
| Tool 写操作 | `projectId + toolName + businessKey` |
| 文件上传 | `projectId + sha256 + clientFileId` |

重复请求规则：

1. 同幂等键、同请求摘要、首次成功：返回第一次结果。
2. 同幂等键、不同请求摘要：返回 `IDEMPOTENCY_CONFLICT`。
3. 首次处理中：返回处理中状态或让客户端稍后查询。
4. HIS 写操作状态不明：先查询最终状态，禁止直接重复写。

### 4.5 统一响应

成功响应：

```json
{
  "code": "OK",
  "message": "success",
  "traceId": "trace_001",
  "requestId": "req_001",
  "data": {}
}
```

错误响应：

```json
{
  "code": "INVALID_PARAM",
  "message": "参数错误",
  "details": {
    "field": "deviceContext.deviceId",
    "reason": "deviceId is required"
  },
  "traceId": "trace_001",
  "requestId": "req_001"
}
```

常见错误码：

| 错误码 | 含义 |
|---|---|
| `AUTH_INVALID_TOKEN` | Token 无效或过期 |
| `AUTH_SIGNATURE_INVALID` | HMAC 签名错误 |
| `AUTH_TIMESTAMP_EXPIRED` | 时间戳过期 |
| `PERMISSION_DENIED` | Scope 或项目授权不足 |
| `RATE_LIMIT_EXCEEDED` | 触发限流 |
| `IDEMPOTENCY_CONFLICT` | 同一幂等键请求内容不一致 |
| `DEVICE_NOT_REGISTERED` | 设备未注册或未激活 |
| `CARD_EXPIRED` | 卡片已过期 |
| `TOOL_FORBIDDEN` | 工具未授权或调用方无权限 |
| `HIS_TIMEOUT` | 院内系统超时 |
| `BILLING_QUOTA_EXCEEDED` | 额度不足或超限 |

---

## 5. P0 接口详细设计

### 5.1 智能体对话接口

`POST /agent/chat`

请求要点：

| 字段 | 说明 |
|---|---|
| `agentId` | 对外智能体 ID；统一入口客户端可为空，由后端 `AgentRouter` 根据设备、场景、任务状态和输入内容决定 |
| `conversationId` | 可为空；为空时平台自动创建并返回 |
| `user` | 用户上下文，预留 `patientId/visitId/encounterId/authorizationId` |
| `deviceContext` | 设备上下文，设备调用必须传 |
| `perceptionContext` | 可选。终端最近一次感知事实，如扫码、NFC、刷卡、服务区域事件；服务端仍以授权和院内系统状态为准 |
| `message` | 文本、图片、音频、文件引用；多模态内容使用 `fileId` |
| `billingContext` | 场景和计量上下文 |

`journeyState` 只存在于响应、SSE 和查询结果中。客户端请求不得传入该对象；即使通过 `inputs` 扩展字段伪造，P0 服务端也必须完全忽略，并以服务端事实重新推导。

### 5.2 文件上传接口

`POST /files/upload`

MVP 只处理：

- 舌象/面象图片；
- 报告图片或 PDF；
- 诊间音频片段可后置。

要求：

1. 文件必须鉴权上传。
2. 平台返回 `fileId`，后续 Agent 调用只传 `fileId`。
3. 不默认返回可公开访问 URL。
4. 原图、报告、面部图片按敏感数据处理。


文件上传幂等规则：

| 字段 / Header | 说明 |
|---|---|
| `X-Emoon-Idempotency-Key` | 正式联调建议必传。推荐值：`projectId + partnerId + clientFileId`。 |
| `clientFileId` | 厂商侧文件唯一 ID；同一文件重试上传时保持不变。 |
| `sha256` | 文件摘要，用于完整性校验和重复文件识别。 |
| `source` | 文件来源：患者端、自助机、机器人、四诊仪、医生站、病区终端、第三方系统等。 |
| `retentionPolicy` | 文件保存策略：`transient`、`episode`、`medical_record`、`audit_only`。 |

文件上传降级幂等规则：如果 `clientFileId` 缺失，平台可降级使用 `projectId + partnerId + sha256 + purpose + user.visitId` 识别重复上传；但正式厂商接入仍应提供 `clientFileId`。

`DELETE /files/{fileId}` 删除或作废文件时也应传 `X-Emoon-Idempotency-Key`。同一文件重复删除返回首次删除结果或当前已删除状态，不重复产生业务副作用。

### 5.3 设备接入三步握手

```text
设备启动 -> /devices/register -> /devices/{deviceId}/scene -> /agent/chat/stream 或 /cards/actions
                    -> 定时 /devices/{deviceId}/heartbeat
                    -> 有事件时 /devices/{deviceId}/events
```



设备管理边界：

| 管理模式 | 说明 | 典型设备 |
|---|---|---|
| `emoon_managed` | 由医梦统一入口客户端和 Device Registry 管理，包含注册、心跳、场景、事件、版本和基础状态。 | 导诊屏、自助机、门诊机器人、诊室屏、叫号/候诊屏 |
| `partner_managed` | 由合作设备厂商管理硬件与驱动，医梦通过标准 API/SDK 接入能力。 | 第三方机器人、四诊仪、专用采集设备 |
| `mapped_external` | 由外部体系管理，医梦仅记录映射关系和 AI 事件互通。 | 迪耐克/鸿蒙病房床头屏、护理白板、护士 PDA、病区机器人 |

门诊设备原则上进入医梦 Device Registry；住院侧设备类型仅表示 AI 能力映射对象，不代表医梦承担住院硬件注册、心跳、升级和故障主责。

设备事件 MVP 类型：

| eventType | 说明 |
|---|---|
| `QR_SCANNED` | 扫码完成 |
| `CARD_READ` | 身份证/医保卡读取 |
| `PRINT_COMPLETED` | 打印成功 |
| `PRINT_FAILED` | 打印失败 |
| `NEARBY_DETECTED` | 近场检测到患者或临时授权令牌 |
| `NAVIGATION_STARTED` | 机器人开始导航 |
| `NAVIGATION_COMPLETED` | 机器人导航完成 |
| `DEVICE_ERROR` | 设备异常 |
| `TOUCH_INTERACTION` | 触控、点击、语音交互摘要 |
| `CUSTOM` | 厂商扩展事件，P0 只能承载联调所需的非敏感摘要 |

`eventPayload` 按 `eventType` 校验必要字段，不强制所有事件使用同一个扁平结构：

| eventType | 必要 eventPayload | 说明 |
|---|---|---|
| `QR_SCANNED` | `qrType`、`visitId` 或临时授权 token | 身份/就诊绑定 |
| `CARD_READ` | `cardType` | 不允许上传完整身份证号、医保卡号 |
| `NEARBY_DETECTED` | `zoneCode`、`level` | 只表示进入服务区域，不表示已签到 |
| `TOUCH_INTERACTION` | `screen`、`action` | 用户主动触发摘要 |
| `CUSTOM` | 项目约定字段 | 仅用于联调扩展，正式上线前需进入白名单 |

`NEARBY_DETECTED` 推荐 `eventPayload`：

```json
{
  "eventType": "NEARBY_DETECTED",
  "eventId": "evt_001",
  "occurredAt": "2026-05-29T10:00:00+08:00",
  "eventPayload": {
    "subject": {
      "type": "temporary_token",
      "value": "tmp_nearby_token_xxx"
    },
    "signal": {
      "type": "ble",
      "rssi": -65,
      "confidence": 0.82
    },
    "areaCode": "OPD_2F_ROOM_201_DOOR"
  }
}
```

注意：不要让设备直接上报身份证号、手机号等敏感信息。服务找人只保存“到达诊室门口服务区域”的必要事件，不保存连续轨迹。设备事件只形成感知事实，不能自动触发签到、缴费、挂号等高风险业务动作，必须由后端结合身份授权、HIS/叫号状态和患者确认后生成卡片。

### 5.4 卡片动作接口

`POST /cards/{'{cardInstanceId}'}/actions/{'{actionName}'}`

卡片动作必须传：

| 字段 | 说明 |
|---|---|
| `clientActionId` | 客户端动作 ID，参与幂等 |
| `operator` | 操作者，患者/医生/护士/系统 |
| `deviceContext` | 动作发生在哪个设备、什么位置 |
| `payload` | 动作业务参数 |
| `confirm` | 是否已由用户或医护确认 |

卡片动作原则：

1. 前端不直接调用 HIS。
2. 卡片动作先校验卡片状态、权限、幂等和有效期。
3. 需要写 HIS 时由 `AgentActionOrchestrator` 承接业务编排，`CardActionService` 做状态校验和快照，再进入 MCP Tool Server。
4. 医疗高风险动作必须人工确认。

### 5.5 受控工具接口

`POST /tools/{'{toolName}'}/invoke`

工具接口只对以下对象开放：

- 医梦 MCP Tool Server；
- HIS/EMR/LIS/PACS/叫号/支付等系统适配方；
- 医梦内部可信服务。

普通设备厂商、机器人厂商、自助机厂商默认不开放。

工具命名建议：

| 工具域 | 示例 |
|---|---|
| HIS 基础 | `his.queryDepartments`、`his.queryDoctors` |
| 排班号源 | `his.querySchedules`、`his.lockSchedule`、`his.releaseSchedule` |
| 挂号 | `his.createRegistration`、`his.cancelRegistration` |
| 叫号签到 | `queue.checkIn`、`queue.queryStatus` |
| EMR | `emr.createDraft`、`emr.queryRecord` |
| LIS/PACS | `lis.queryReports`、`pacs.queryImages` |
| 支付 | `payment.createOrder`、`payment.queryStatus` |


工具风险等级：

| 风险等级 | 工具类型 | 控制要求 |
|---|---|---|
| `L1_QUERY` | 查询科室、医生、院区、FAQ | 可自动调用，记录审计。 |
| `L2_SENSITIVE_READ` | 查询患者、报告、费用、处方摘要 | 需要患者授权、医护身份或项目授权。 |
| `L3_BUSINESS_WRITE` | 锁号、签到、建档、挂号 | 必须幂等、用户确认、卡片动作审计。 |
| `L4_FINANCIAL_ACTION` | 支付、退费、补缴 | 强确认、支付系统回调、财务审计。 |
| `L5_MEDICAL_WRITE` | EMR 正式写回、医嘱、处方 | 医生确认、医院系统签名、全链路审计。 |

MVP 阶段建议优先开放 `L1_QUERY` 和少量 `L3_BUSINESS_WRITE`。`L4_FINANCIAL_ACTION` 与 `L5_MEDICAL_WRITE` 不建议春节前作为通用厂商接口开放。

---

## 6. SSE 流式接口

`POST /agent/chat/stream`

Header：

```http
Accept: text/event-stream
Content-Type: application/json
```

事件类型：

| 事件 | 优先级 | 说明 |
|---|---|---|
| `message_delta` | P0 | 文本增量 |
| `message_completed` | P0 | 文本完成，返回 messageId/conversationId |
| `card_created` | P0 | 平台已创建卡片实例，前端可渲染 |
| `task_updated` | P0 | 任务状态变更，返回 taskId/taskType/currentStep/status |
| `journey_updated` | P0 | 动线阶段变更，返回 stageCode/nextAction/source；前端动线区必须以该事件或响应中的 `journeyState` 为准 |
| `error` | P0 | 流式错误 |
| `usage_reported` | P1 | 本次调用用量或能力值事件，仅展示用途，不作为账本唯一来源 |

断线恢复：

1. 客户端记录 `conversationId` 和最后收到的 `eventId`。
2. 断线后调用 `GET /conversations/{'{conversationId}'}/messages` 查询最终消息、任务状态、动线状态和卡片。
3. 卡片实例以 `GET /cards/{'{cardInstanceId}'}` 为准。

---

## 7. Webhook 与外部事件

### 7.1 Webhook 签名

第三方回调医梦或医梦回调第三方，都应使用签名头：

| Header | 说明 |
|---|---|
| `X-Emoon-Webhook-Event-Id` | 事件唯一 ID |
| `X-Emoon-Webhook-Timestamp` | Unix 毫秒时间戳 |
| `X-Emoon-Webhook-Nonce` | 随机串 |
| `X-Emoon-Webhook-Signature` | HMAC-SHA256 签名 |

重试策略建议：

| 项 | 建议 |
|---|---|
| 单次超时 | 5 秒 |
| 重试间隔 | 1min / 5min / 30min / 2h |
| 最大重试 | 5 次 |
| 成功条件 | HTTP 2xx |
| 幂等键 | `eventId` |

### 7.2 外部事件接入

`POST /events/ingest` 用于 HIS、叫号、迪耐克/病房系统等向医梦上报业务事件，例如：

| eventType | 来源 |
|---|---|
| `registration_created` | HIS |
| `registration_cancelled` | HIS |
| `queue_status_changed` | 叫号系统 |
| `checkin_completed` | 签到系统 |
| `report_available` | LIS/PACS |
| `ward_alert_created` | 迪耐克/病房系统 |
| `nursing_task_closed` | 护理系统 |

---

## 8. 限流、计量和计费

### 8.1 限流不是计费

限流用于保护系统，计费用于商业结算。限流命中不代表扣费，调用成功也不一定直接扣费，必须根据 `chargePolicy` 和计量账本判断。

限流响应头建议：

| Header | 说明 |
|---|---|
| `X-RateLimit-Limit` | 当前窗口额度 |
| `X-RateLimit-Remaining` | 剩余额度 |
| `X-RateLimit-Reset` | 重置时间 |
| `Retry-After` | 建议重试秒数 |

### 8.2 计量事件

标准计量事件包含：

- `projectId`
- `partnerId`
- `agentId`，Router 决定场景时由后端补齐最终命中的 Agent ID
- `deviceId`
- `scenarioCode`
- `billingEpisodeId`
- `sourceType`
- `sourceId`
- `meterItem`
- `rawQuantity`
- `credits`
- `chargePolicy`

`chargePolicy` 枚举：

| 值 | 说明 |
|---|---|
| `customer_charge` | 客户能力值扣费 |
| `license_covered` | 设备授权覆盖 |
| `bundle_included` | 服务包包含 |
| `internal_cost` | 只记内部成本 |
| `no_charge` | 不计费，仅审计 |


`/meter/events` 查询范围：

| 阶段 | 支持范围 | 不支持范围 |
|---|---|---|
| P0 | 按 `billingEpisodeId` 或 `traceId` 做精确查询，用于联调排障和计量核验 | 不开放项目级、设备级、时间范围、成本明细和完整账单查询给普通厂商 |
| P1 | 医院信息科和医梦运营可按项目、智能体、设备做基础汇总 | 不直接替代正式月账单 |
| P2 | 进入账单、分摊、运营报告和区域能力池 | 需合同、权限、审计体系同步成熟 |

正式账单查询不使用 `/meter/events`，后续由 `/billing/invoices` 或账单中心接口承接。

---

## 9. MVP 实施建议

### 9.1 P0 开发顺序

1. 通用鉴权、HMAC Header、错误响应、幂等键。
2. `/devices/register` + `/heartbeat` + `/scene`，让统一入口客户端能先启动和拿到场景。
3. `/agent/chat/stream` + `/conversations/{'{id}'}` + `/conversations/{'{id}'}/messages`，统一入口客户端默认走 SSE。
4. `AgentRouter` 和 `TaskStateService` 先作为 `emoon-ai-agent` 内部能力实现，不新增公共 `/tasks` P0 API。
5. `/files/upload` + `/files/{'{fileId}'}` + `DELETE /files/{'{fileId}'}` 幂等删除。
6. `/cards/{'{id}'}` + `/cards/{'{id}'}/actions/{'{actionName}'}`，卡片动作由 Agent 编排链路推进状态和工具调用。
7. `/tools/{'{toolName}'}/invoke` 只接查询类 HIS 工具和显式 Mock 写工具，普通终端不可直接调用。
8. `/devices/{'{deviceId}'}/events` + `/commands/poll` + `/commands/{'{commandId}'}/ack`，先支撑机器人导航、扫码、打印、异常事件。
9. `/meter/events` 只按 `billingEpisodeId` / `traceId` 精确查询 + 计量事件落库。

`/agent/chat` 保留为同步接口和服务端联调工具，不作为统一入口客户端 P0 主链路。

### 9.2 不建议第一期实现的内容

- 完整 OAuth2/IAM；
- mTLS；
- 完整账单中心；
- 区域多院能力池；
- FHIR 网关 / FHIR Translate 主接口；
- 第三方卡片插件市场；
- 全院鸿蒙无感定位；
- 所有设备深度控制命令；
- 公共 `/tasks` 查询与任务编排 API；
- 终端直连 Dify、HIS Tool、舌诊底层接口或计量写接口。

### 9.3 统一入口客户端 P0 接口白名单

| 终端类型 | 默认允许接口 | 第一阶段不允许 |
|---|---|---|
| 机器人 | Device 注册/心跳/场景/事件/命令轮询、`/agent/chat/stream`、Conversation、Card | 直连 HIS Tool、直连 Dify、真实缴费、医保、退费 |
| 自助机 | Device、`/agent/chat/stream`、Conversation、File、Card | 前端写死号源、前端直接调用舌诊接口、自动完成高风险动作 |
| 导诊屏/大屏 | Device、`/agent/chat/stream`、Conversation、Card、轻量事件 | 舌象采集、实名挂号、支付、医保 |
| 诊室屏/医生站插件 | Device、`/agent/chat/stream`、Conversation、File、Card | 自动诊断、自动处方、绕过医生确认 |

---

## 10. v1.1 相比 v1.0 的变更

| 变更 | 说明 |
|---|---|
| 新增会话接口 | `/conversations`、`/conversations/{'{id}'}`、`/messages` |
| 新增文件接口 | `/files/upload`、`/files/{'{fileId}'}` |
| 卡片动作增加 `deviceContext` | 解决设备审计和设备计量归因 |
| 补 HMAC Headers | Timestamp、Nonce、Signature |
| 补核心上下文 schema | UserContext、DeviceContext、BillingContext |
| 补错误 details | 方便厂商联调排障 |
| 补设备事件和命令 schema | 支撑机器人、自助机、服务找人 |
| 补 Tool scope 说明 | 避免普通设备厂商误调 HIS 工具 |
| 补 Webhook 签名和重试 | 支撑外部事件接入 |
| 补 P0/P1/P2 全量接口目录 | 兼顾接口全貌和 MVP 落地 |

---

## 11. 对外发送建议

正式发给厂商时建议提供一个资料包：

```text
医梦AI中台厂商对接资料包/
├── 对外接口联调基准.md
├── 医梦AI中台开放平台接口-v1.2.openapi.yaml
├── Postman Collection
├── HMAC签名示例-Java
├── HMAC签名示例-TypeScript
├── HIS工具接口Mock说明
├── 机器人设备接入示例
└── 设备事件与命令测试用例
```

当前这版已经可以作为内部评审和厂商预沟通底稿。若要发正式联调版，应再补 Postman Collection、HMAC 示例和 HIS Mock Server。


## 12. v1.2.3 正式联调基准结论

v1.2.3 可以作为厂商正式联调基准。它不扩大主 OpenAPI YAML 的 P0 接口面，只补充统一入口客户端的调用边界、工程归属、动线阶段和感知上下文。仍需坚持以下边界：

1. **主 YAML 只代表当前联调基准**：P0/P1 是主要联调范围；P2 只做规划说明，不代表春节前承诺。
2. **FHIR 不在主基线内**：如医院已有 FHIR 网关，需要单独评估后另出 FHIR 映射文件。
3. **住院设备不按门诊总包处理**：护理白板、床头屏、护士 PDA 等住院终端默认通过迪耐克/鸿蒙病房体系映射接入。
4. **文件和工具接口是高风险区域**：文件必须有用途、来源、保存策略和幂等；工具必须有 riskLevel、scope、幂等和审计。
5. **计量查询不是账单接口**：`/meter/events` 只用于联调排障和计量核验，正式对账以后续账单中心为准。
6. **统一入口客户端不直连底层能力**：终端前端不得持有 Dify Key，不得调用 HIS Tool，不得直连舌诊底层接口，不得写计量账本。
7. **动线和感知不等于自动业务动作**：终端只能上报感知事实和展示后端返回的 `journeyState`，签到、缴费、挂号、报告解读等动作仍必须走卡片确认、审计和幂等链路。

对外发送建议：

| 对象 | 发送内容 | 备注 |
|---|---|---|
| HIS / EMR / LIS / PACS / 叫号 / 支付厂商 | Markdown + v1.2 YAML + Tool 接口章节 | 强调 tools 受控开放和风险等级 |
| 机器人 / 自助机 / 大屏 / 诊室屏厂商 | Markdown + v1.2 YAML + Device / Agent / Card 章节 | 强调不得直接调用 Tool |
| 四诊仪厂商 | Markdown + v1.2 YAML + File / Device / Agent 章节 | 强调文件上传幂等和敏感数据策略 |
| 迪耐克 / 鸿蒙病房互通方 | Markdown + v1.2 YAML + Device 管理边界 / Event 章节 | 强调 mapped_external，不承担住院硬件主责 |
| 医院信息科 | Markdown + v1.2 YAML + 鉴权 / 审计 / 计量章节 | 强调权限隔离、日志、计量不是账单 |