openapi: 3.0.3 info: title: EMOON AI OpenPlatform External API version: 1.2.3 description: 医梦 AI 中台对外接口契约 v1.2.3，正式联调基准版。P0/P1 为厂商联调主基线；P2 为受控规划接口。FHIR 映射从主 YAML 移出，避免误解为当前交付承诺。统一入口客户端调用 Agent 时可不传 agentId，由后端 AgentRouter 结合设备、场景、感知上下文和服务端推导的动线阶段决定最终智能体。 servers: - url: https://api.{hospital}.emoon.local/api/v1 variables: hospital: default: demo - url: https://sandbox-api.emoon-ai.com/api/v1 security: - BearerAuth: [] - HmacAuth: [] tags: - name: Auth - name: Platform - name: Agent - name: Conversation - name: File - name: Device - name: Card - name: MCP Tool - name: Webhook - name: Event - name: Usage - name: License - name: Partner - name: Contract - name: Credit - name: Billing - name: Operation - name: Audit paths: /auth/token: post: summary: 获取短期访问 Token tags: - Auth x-emoon-priority: P0 description: client_credentials 模式。 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TokenRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseToken' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /health: get: summary: 平台健康检查 tags: - Platform x-emoon-priority: P0 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseHealth' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /capabilities: get: summary: 查询项目已开通能力 tags: - Platform x-emoon-priority: P0 parameters: &id005 - &id001 $ref: '#/components/parameters/ProjectId' - &id002 $ref: '#/components/parameters/PartnerId' - &id003 $ref: '#/components/parameters/TraceId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseCapabilities' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /agent/chat: post: summary: 智能体同步对话 tags: - Agent x-emoon-priority: P0 description: 首轮 conversationId 可为空，平台自动创建会话并返回。支持 Bearer Token；HMAC 模式需携带 X-Emoon-Timestamp、X-Emoon-Nonce、X-Emoon-Signature。 parameters: &id004 - *id001 - *id002 - *id003 - &id006 $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentChatRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseAgentChat' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /agent/chat/stream: post: summary: 智能体流式对话 SSE tags: - Agent x-emoon-priority: P0 description: POST + text/event-stream。断线后使用 conversationId 查询最终消息。 parameters: *id004 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentChatRequest' responses: '200': description: SSE stream content: text/event-stream: schema: type: string '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /conversations: post: summary: 创建会话 tags: - Conversation x-emoon-priority: P0 parameters: *id005 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConversationCreateRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseConversation' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: summary: 查询会话列表 tags: - Conversation x-emoon-priority: P1 parameters: - *id001 - *id002 - *id003 - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PageSize' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseConversationList' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /conversations/{conversationId}: get: summary: 查询会话详情 tags: - Conversation x-emoon-priority: P0 parameters: - $ref: '#/components/parameters/ConversationIdPath' - *id001 - *id002 - *id003 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseConversation' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /conversations/{conversationId}/messages: get: summary: 查询会话消息 tags: - Conversation x-emoon-priority: P0 parameters: - $ref: '#/components/parameters/ConversationIdPath' - *id001 - *id002 - *id003 - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PageSize' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseMessageList' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /files/upload: post: summary: 上传图片/音频/文档 tags: - File x-emoon-priority: P0 description: multipart/form-data 上传，返回 fileId；后续 Agent 调用只传 fileId。 parameters: *id004 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseFileUpload' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/FileUploadRequest' /files/{fileId}: get: summary: 查询文件元数据 tags: - File x-emoon-priority: P0 parameters: - $ref: '#/components/parameters/FileIdPath' - *id001 - *id002 - *id003 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseFileMeta' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: summary: 删除或作废文件 tags: - File x-emoon-priority: P1 description: 删除或作废授权范围内未被锁定的文件。DELETE 本身应保持幂等；正式厂商联调要求传 X-Emoon-Idempotency-Key。同一文件重复删除返回首次处理结果或当前已删除状态。 parameters: - $ref: '#/components/parameters/FileIdPath' - *id001 - *id002 - *id003 - $ref: '#/components/parameters/IdempotencyKey' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /devices/register: post: summary: 设备注册或激活 tags: - Device x-emoon-priority: P0 parameters: *id005 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeviceRegisterRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseDeviceRegister' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /devices/{deviceId}/heartbeat: post: summary: 设备心跳 tags: - Device x-emoon-priority: P0 parameters: - $ref: '#/components/parameters/DeviceIdPath' - *id001 - *id002 - *id003 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeviceHeartbeatRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseDeviceHeartbeat' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /devices/{deviceId}/scene: get: summary: 获取设备当前场景配置 tags: - Device x-emoon-priority: P0 parameters: - $ref: '#/components/parameters/DeviceIdPath' - *id001 - *id002 - *id003 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseDeviceScene' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: summary: 更新设备场景绑定 tags: - Device x-emoon-priority: P1 parameters: - $ref: '#/components/parameters/DeviceIdPath' - *id001 - *id002 - *id003 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeviceSceneUpdateRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseDeviceScene' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /devices/{deviceId}/events: post: summary: 上报设备事件 tags: - Device x-emoon-priority: P0 description: 异步事件，正常返回 202 Accepted。 parameters: - $ref: '#/components/parameters/DeviceIdPath' - *id001 - *id002 - *id003 - *id006 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeviceEventRequest' responses: '202': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseAccepted' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: summary: 查询设备事件 tags: - Device x-emoon-priority: P1 parameters: - $ref: '#/components/parameters/DeviceIdPath' - *id001 - *id002 - *id003 - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PageSize' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseDeviceEventList' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /devices/{deviceId}/commands/poll: get: summary: 设备轮询待执行命令 tags: - Device x-emoon-priority: P0 parameters: - $ref: '#/components/parameters/DeviceIdPath' - *id001 - *id002 - *id003 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseDeviceCommands' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /devices/{deviceId}/commands/{commandId}/ack: post: summary: 设备命令执行回执 tags: - Device x-emoon-priority: P0 parameters: - $ref: '#/components/parameters/DeviceIdPath' - $ref: '#/components/parameters/CommandIdPath' - *id001 - *id002 - *id003 - *id006 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeviceCommandAckRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /cards/{cardInstanceId}: get: summary: 查询卡片实例 tags: - Card x-emoon-priority: P0 parameters: - $ref: '#/components/parameters/CardInstanceIdPath' - *id001 - *id002 - *id003 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseCardInstance' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /cards/{cardInstanceId}/actions/{actionName}: post: summary: 执行卡片动作 tags: - Card x-emoon-priority: P0 description: 所有产生业务后果的卡片动作必须幂等，且必须携带 operator 与 deviceContext。 parameters: - $ref: '#/components/parameters/CardInstanceIdPath' - $ref: '#/components/parameters/ActionNamePath' - *id001 - *id002 - *id003 - *id006 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CardActionRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseCardAction' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /tools/{toolName}/invoke: post: summary: 调用院内系统工具，面向受控适配方 tags: - MCP Tool x-emoon-priority: P0 description: 需要 tool:read 或 tool:write scope。普通设备厂商默认不开放。 parameters: - $ref: '#/components/parameters/ToolNamePath' - *id001 - *id002 - *id003 - *id006 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ToolInvokeRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseToolInvoke' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-emoon-required-scopes: - tool:read - tool:write x-emoon-partner-level: - trusted_system_adapter - his_vendor - emoon_internal /usage/summary: get: summary: 查询用量汇总 tags: - Usage x-emoon-priority: P0 parameters: - *id001 - *id002 - *id003 - $ref: '#/components/parameters/FromDate' - $ref: '#/components/parameters/ToDate' - $ref: '#/components/parameters/GroupBy' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseUsageSummary' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /meter/events: get: summary: 查询计量事件 tags: - Usage x-emoon-priority: P0 parameters: - *id001 - *id002 - *id003 - $ref: '#/components/parameters/BillingEpisodeId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/QueryTraceId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseMeterEvents' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: 查询计量事件。P0 阶段仅支持按 billingEpisodeId 或 traceId 做精确查询，用于联调排障和计量核验；不作为正式账单查询接口，不开放项目级、设备级、时间范围复杂过滤给普通厂商。 /agents: get: summary: 查询可用智能体列表 tags: - Agent x-emoon-priority: P1 parameters: - *id001 - *id002 - *id003 - $ref: '#/components/parameters/ScenarioCode' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseAgentList' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /agents/{agentId}: get: summary: 查询智能体详情 tags: - Agent x-emoon-priority: P1 parameters: - $ref: '#/components/parameters/AgentIdPath' - *id001 - *id002 - *id003 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseAgentDetail' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /devices: get: summary: 查询设备列表 tags: - Device x-emoon-priority: P1 parameters: - *id001 - *id002 - *id003 - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PageSize' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseDeviceList' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /devices/{deviceId}: get: summary: 查询设备详情 tags: - Device x-emoon-priority: P1 parameters: - $ref: '#/components/parameters/DeviceIdPath' - *id001 - *id002 - *id003 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseDeviceDetail' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /webhooks: post: summary: 注册 Webhook tags: - Webhook x-emoon-priority: P1 parameters: *id005 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookRegisterRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseWebhook' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: summary: 查询 Webhook 列表 tags: - Webhook x-emoon-priority: P1 parameters: - *id001 - *id002 - *id003 - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PageSize' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseWebhookList' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /webhooks/{webhookId}: delete: summary: 删除 Webhook tags: - Webhook x-emoon-priority: P1 parameters: - $ref: '#/components/parameters/WebhookIdPath' - *id001 - *id002 - *id003 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /events/ingest: post: summary: 接收外部系统业务事件 tags: - Event x-emoon-priority: P1 description: 用于 HIS、叫号、迪耐克/病房系统向医梦上报事件。 parameters: *id004 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExternalEventRequest' responses: '202': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseAccepted' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /tools/catalog: get: summary: 查询授权工具目录 tags: - MCP Tool x-emoon-priority: P1 parameters: *id005 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseToolCatalog' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-emoon-required-scopes: - tool:read /licenses/devices: get: summary: 查询设备授权状态 tags: - License x-emoon-priority: P1 parameters: - *id001 - *id002 - *id003 - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PageSize' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseDeviceLicenses' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /partners: post: summary: 创建合作方接入档案 tags: - Partner x-emoon-priority: P2 description: P2 规划接口，不建议进入春节前 MVP。 parameters: *id005 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PartnerCreateRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /contracts: get: summary: 查询合同与套餐 tags: - Contract x-emoon-priority: P2 description: P2 规划接口，不建议进入春节前 MVP。 parameters: *id005 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /credit/accounts: get: summary: 查询能力值账户 tags: - Credit x-emoon-priority: P2 description: P2 规划接口，不建议进入春节前 MVP。 parameters: *id005 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /billing/invoices: get: summary: 查询账单 tags: - Billing x-emoon-priority: P2 description: P2 规划接口，不建议进入春节前 MVP。 parameters: *id005 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /operation/reports: get: summary: 查询运营报告 tags: - Operation x-emoon-priority: P2 description: P2 规划接口，不建议进入春节前 MVP。 parameters: *id005 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /audit/logs: get: summary: 查询审计日志 tags: - Audit x-emoon-priority: P2 description: P2 规划接口，不建议进入春节前 MVP。 parameters: *id005 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /partners/{partnerId}: get: summary: 查询合作方档案 tags: - Partner x-emoon-priority: P2 parameters: - $ref: '#/components/parameters/PartnerIdPath' - *id001 - *id002 - *id003 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /credit/accounts/{accountId}/freeze: post: summary: 冻结能力值 tags: - Credit x-emoon-priority: P2 description: 内部高风险接口，通常不对外开放。 parameters: - $ref: '#/components/parameters/AccountIdPath' - *id001 - *id002 - *id003 - *id006 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreditFreezeRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /credit/accounts/{accountId}/settle: post: summary: 结算能力值 tags: - Credit x-emoon-priority: P2 description: 内部高风险接口，通常不对外开放。 parameters: - $ref: '#/components/parameters/AccountIdPath' - *id001 - *id002 - *id003 - *id006 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreditSettleRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT HmacAuth: type: apiKey in: header name: X-Emoon-Access-Key description: 项目 Access Key。同时必须携带 X-Emoon-Timestamp（Unix 毫秒）、X-Emoon-Nonce（随机 UUID）、X-Emoon-Signature（Base64(HMAC-SHA256)）。 parameters: ProjectId: name: X-Emoon-Project-Id in: header required: true schema: type: string description: 项目/医院标识。 PartnerId: name: X-Emoon-Partner-Id in: header required: true schema: type: string description: 合作厂商标识。 TraceId: name: X-Emoon-Trace-Id in: header required: false schema: type: string description: 链路追踪 ID；不传则平台生成。 IdempotencyKey: name: X-Emoon-Idempotency-Key in: header required: false schema: type: string description: 写操作和产生业务事实的请求必须传。 Timestamp: name: X-Emoon-Timestamp in: header required: false schema: type: string description: HMAC 模式必填，Unix 毫秒时间戳。 Nonce: name: X-Emoon-Nonce in: header required: false schema: type: string description: HMAC 模式必填，防重放随机串。 Signature: name: X-Emoon-Signature in: header required: false schema: type: string description: HMAC 模式必填，HMAC-SHA256 签名。 DeviceIdHeader: name: X-Emoon-Device-Id in: header required: false schema: type: string description: 设备调用建议传，作为 deviceContext 兜底。 DeviceIdPath: name: deviceId in: path required: true schema: type: string ConversationIdPath: name: conversationId in: path required: true schema: type: string FileIdPath: name: fileId in: path required: true schema: type: string CardInstanceIdPath: name: cardInstanceId in: path required: true schema: type: string ActionNamePath: name: actionName in: path required: true schema: type: string CommandIdPath: name: commandId in: path required: true schema: type: string ToolNamePath: name: toolName in: path required: true schema: type: string WebhookIdPath: name: webhookId in: path required: true schema: type: string PartnerIdPath: name: partnerId in: path required: true schema: type: string AccountIdPath: name: accountId in: path required: true schema: type: string AgentIdPath: name: agentId in: path required: true schema: type: string Page: name: page in: query required: false schema: type: integer default: 1 PageSize: name: pageSize in: query required: false schema: type: integer default: 20 maximum: 200 FromDate: name: from in: query required: true schema: type: string format: date ToDate: name: to in: query required: true schema: type: string format: date GroupBy: name: groupBy in: query required: false schema: type: string enum: - project - partner - agent - device - scenario - department - day BillingEpisodeId: name: billingEpisodeId in: query required: false schema: type: string description: 按 billingEpisodeId 查询同一业务 episode 下的计量事件。P0 阶段 /meter/events 仅支持 billingEpisodeId 或 traceId 这类精确查询，不开放项目级、设备级、时间范围复杂过滤。 ScenarioCode: name: scenarioCode in: query required: false schema: type: string QueryTraceId: name: traceId in: query required: false schema: type: string description: 按 traceId 查询联调排障相关计量事件。P0 仅用于联调排障，不代表完整账单查询。 schemas: ApiResponse: type: object properties: code: type: string example: OK message: type: string example: success traceId: type: string requestId: type: string details: type: object additionalProperties: true data: type: object additionalProperties: true ErrorResponse: type: object properties: code: type: string example: INVALID_PARAM message: type: string details: type: object additionalProperties: true traceId: type: string requestId: type: string required: - code - message - traceId ApiResponseAccepted: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/AcceptedData' AcceptedData: type: object properties: accepted: type: boolean eventId: type: string status: type: string enum: - accepted - duplicate - ignored TokenRequest: type: object required: - grantType - clientId - clientSecret - projectId properties: grantType: type: string enum: - client_credentials clientId: type: string clientSecret: type: string projectId: type: string scopes: type: array items: type: string TokenData: type: object properties: accessToken: type: string tokenType: type: string example: Bearer expiresIn: type: integer example: 7200 scopes: type: array items: type: string ApiResponseToken: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/TokenData' HealthData: type: object properties: status: type: string enum: - UP - DOWN - DEGRADED timestamp: type: string format: date-time version: type: string ApiResponseHealth: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/HealthData' CapabilitiesData: type: object properties: projectId: type: string agents: type: array items: $ref: '#/components/schemas/AgentSummary' enabledFeatures: type: array items: type: string toolScopes: type: array items: type: string rateLimit: $ref: '#/components/schemas/RateLimitPolicy' ApiResponseCapabilities: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/CapabilitiesData' RateLimitPolicy: type: object properties: windowSeconds: type: integer limit: type: integer UserContext: type: object required: - externalUserId - role properties: externalUserId: type: string role: type: string enum: - patient - doctor - nurse - admin - system - anonymous patientId: type: string description: HIS 患者 ID，第一期可选。 visitId: type: string description: 门诊/住院就诊 ID，第一期可选。 encounterId: type: string authorizationId: type: string description: 患者授权记录 ID。 DeviceContext: type: object properties: deviceId: type: string deviceType: type: string enum: - mobile_app - guide_screen - self_service_kiosk - robot - waiting_screen - clinic_door_screen - clinic_desktop_screen - doctor_station - four_diagnosis_device - nurse_pda - nursing_whiteboard - bedside_screen - ward_robot - unknown description: 设备类型。门诊类型可进入医梦统一入口直接管理；住院侧类型仅表示 AI 能力映射对象，不代表医梦接管住院硬件。 locationCode: type: string sceneCode: type: string clientVersion: type: string managementMode: type: string enum: - emoon_managed - partner_managed - mapped_external description: 设备管理模式。emoon_managed=医梦统一入口客户端和 Device Registry 管理；partner_managed=合作设备厂商管理，医梦通过标准接口接入；mapped_external=迪耐克/鸿蒙病房等外部体系管理，医梦只做映射和事件互通。 externalSystem: type: string description: 外部系统标识，例如 dinaike_ward、harmony_ward、his_queue。管理模式为 mapped_external 或 partner_managed 时建议填写。 externalDeviceId: type: string description: 外部系统中的设备或终端 ID，用于住院互通和第三方设备映射。 required: - deviceId description: 设备上下文。门诊设备原则上由医梦 Device Registry 管理；住院侧类型（nurse_pda / nursing_whiteboard / bedside_screen / ward_robot）通常通过迪耐克/鸿蒙病房体系映射接入，医梦只负责 AI 能力、事件互通和审计，不承担住院硬件基础管理责任。 PerceptionContext: type: object description: 感知上下文。用于统一入口客户端上报最近一次身份、空间、业务、设备或风险感知事实；服务端仍以授权、HIS/叫号/任务状态为最终依据。P0 不允许上传连续轨迹。 properties: identityBindingId: type: string description: 患者身份与终端/设备/会话绑定记录 ID。 locationLevel: type: string enum: - L0 - L1 - L2 - L3 description: 感知级别。L0=扫码/人工；L1=NFC/刷卡；L2=BLE/Wi-Fi 区域；L3=星闪/鸿蒙/UWB 等高精度。 zoneCode: type: string description: 服务区域编码，如 clinic_room_301_door、outpatient_hall_kiosk。 source: type: string enum: - QR_SCANNED - NFC_TOUCH - CARD_READ - BLE_ZONE_DETECT - WIFI_ZONE_DETECT - MANUAL_CONFIRM - BUSINESS_STATE - DEVICE_EVENT - CUSTOM occurredAt: type: string format: date-time confidence: type: number format: double minimum: 0 maximum: 1 JourneyState: type: object readOnly: true description: 患者当前动线阶段。由服务端根据 VisitTimeline、TaskState、DeviceContext、DeviceEvent、CardAction 和院内系统状态推导；P0 仅用于服务端返回给客户端展示，客户端请求不得传入该对象，也不得据此自行放开高风险能力。 properties: stageCode: type: string description: 动线阶段编码，如 WAITING_CHECKIN、WAITING_CALL、WAITING_PAYMENT、WAITING_EXAM、REPORT_READY、FOLLOW_UP。 stageName: type: string description: 动线阶段中文名。 nextAction: type: string description: 推荐下一步动作，如 CHECK_IN、PAYMENT_GUIDE、NAVIGATE_TO_EXAM、REPORT_EXPLAIN。 source: type: string enum: - SERVER_DERIVED - HIS_STATE - CARD_ACTION - DEVICE_EVENT confidence: type: number format: double minimum: 0 maximum: 1 requiresConfirm: type: boolean description: 是否必须患者或医护确认后才能执行。 BillingContext: type: object properties: scenarioCode: type: string billingEpisodeId: type: string chargePolicy: type: string enum: - customer_charge - license_covered - bundle_included - internal_cost - no_charge ChatMessage: type: object required: - type - text properties: type: type: string enum: - text - image - audio - file text: type: string description: 文本内容（type=text 时必填）。 fileId: type: string description: 多模态文件推荐传 fileId（type=image/audio/file 时使用）。 clientMessageId: type: string description: 客户端消息幂等 ID。 AgentChatRequest: type: object required: - message properties: agentId: type: string nullable: true description: 对外智能体 ID。统一入口客户端可为空，由后端 AgentRouter 根据设备、场景、任务状态和输入内容决定。 conversationId: type: string description: 首轮可为空，平台自动创建。 user: $ref: '#/components/schemas/UserContext' deviceContext: $ref: '#/components/schemas/DeviceContext' perceptionContext: $ref: '#/components/schemas/PerceptionContext' message: $ref: '#/components/schemas/ChatMessage' inputs: type: object additionalProperties: true billingContext: $ref: '#/components/schemas/BillingContext' AgentChatData: type: object properties: conversationId: type: string messageId: type: string answer: type: string cards: type: array items: $ref: '#/components/schemas/CardRef' journeyState: $ref: '#/components/schemas/JourneyState' riskLevel: type: string enum: - low - medium - high - critical - unknown usage: $ref: '#/components/schemas/UsageBrief' CardRef: type: object properties: cardInstanceId: type: string cardKey: type: string status: type: string UsageBrief: type: object properties: meterEventId: type: string billingEpisodeId: type: string chargePolicy: type: string credits: type: number ApiResponseAgentChat: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/AgentChatData' ConversationCreateRequest: type: object properties: agentId: type: string user: $ref: '#/components/schemas/UserContext' deviceContext: $ref: '#/components/schemas/DeviceContext' title: type: string metadata: type: object additionalProperties: true Conversation: type: object properties: conversationId: type: string agentId: type: string title: type: string status: type: string enum: - active - closed - archived createdAt: type: string format: date-time updatedAt: type: string format: date-time ApiResponseConversation: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/Conversation' ApiResponseConversationList: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: type: object properties: items: type: array items: $ref: '#/components/schemas/Conversation' page: $ref: '#/components/schemas/PageInfo' ConversationMessage: type: object properties: messageId: type: string role: type: string enum: - user - assistant - system - tool content: type: string cards: type: array items: $ref: '#/components/schemas/CardRef' createdAt: type: string format: date-time ApiResponseMessageList: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: type: object properties: items: type: array items: $ref: '#/components/schemas/ConversationMessage' page: $ref: '#/components/schemas/PageInfo' FileUploadRequest: type: object required: - file properties: file: type: string format: binary purpose: type: string enum: - tongue_diagnosis - face_diagnosis - report_interpretation - medical_record - audio_transcription - other user: $ref: '#/components/schemas/UserContext' deviceContext: $ref: '#/components/schemas/DeviceContext' metadata: type: object additionalProperties: true clientFileId: type: string description: 厂商侧文件唯一 ID。同一文件重试上传时必须保持不变，推荐用于文件上传幂等。 sha256: type: string description: 文件 SHA-256 摘要。用于完整性校验、重复文件识别和审计。 source: type: string enum: - patient_app - self_service_kiosk - robot - four_diagnosis_device - doctor_station - ward_terminal - third_party_system description: 文件来源终端或系统。 retentionPolicy: type: string enum: - transient - episode - medical_record - audit_only description: 文件保存策略。transient=临时分析；episode=本次就诊 episode 内保存；medical_record=进入病历或正式医疗材料；audit_only=只保留审计摘要。 description: 文件上传请求。正式联调推荐幂等键 projectId + partnerId + clientFileId；clientFileId 缺失时可降级使用 projectId + partnerId + sha256 + purpose + user.visitId。 FileMeta: type: object properties: fileId: type: string fileType: type: string enum: - image - audio - document - other mimeType: type: string sizeBytes: type: integer sha256: type: string status: type: string enum: - uploaded - scanning - available - blocked - deleted uploadedAt: type: string format: date-time clientFileId: type: string purpose: type: string retentionPolicy: type: string enum: - transient - episode - medical_record - audit_only source: type: string ApiResponseFileUpload: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/FileMeta' ApiResponseFileMeta: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/FileMeta' DeviceRegisterRequest: type: object required: - deviceCode - deviceType - vendor - model - os - clientVersion properties: deviceCode: type: string deviceType: type: string vendor: type: string model: type: string os: type: string enum: - android - harmony - windows - linux - web - unknown clientVersion: type: string capabilities: $ref: '#/components/schemas/DeviceCapabilities' location: $ref: '#/components/schemas/DeviceLocation' DeviceCapabilities: type: object properties: touch: type: boolean screen: type: boolean voiceInput: type: boolean voiceOutput: type: boolean camera: type: boolean qrScan: type: boolean idCardReader: type: boolean medicalCardReader: type: boolean printer: type: boolean navigation: type: boolean nearbyDetect: type: boolean DeviceLocation: type: object properties: building: type: string floor: type: string area: type: string room: type: string bed: type: string locationCode: type: string DeviceRegisterData: type: object properties: deviceId: type: string deviceSecret: type: string activateStatus: type: string description: 设备准入状态。activated 可进入核心业务，pending 待人工审批，rejected 已拒绝。 enum: - activated - pending - rejected admissionLevel: type: string description: 设备等级 A/B/C/D。 enum: - A - B - C - D reason: type: string description: 当 activateStatus 为 pending 或 rejected 时，说明原因。 ApiResponseDeviceRegister: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/DeviceRegisterData' DeviceHeartbeatRequest: type: object required: - status - clientVersion properties: status: type: string enum: - online - offline - error - maintenance clientVersion: type: string ip: type: string currentSceneCode: type: string metrics: type: object additionalProperties: true errors: type: array items: $ref: '#/components/schemas/DeviceError' DeviceError: type: object properties: code: type: string message: type: string occurredAt: type: string format: date-time DeviceHeartbeatData: type: object properties: accepted: type: boolean serverTime: type: string format: date-time nextHeartbeatSeconds: type: integer ApiResponseDeviceHeartbeat: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/DeviceHeartbeatData' DeviceSceneData: type: object properties: deviceId: type: string deviceType: type: string description: 设备类型 robot/self_service_kiosk/guide_screen 等。 sceneCode: type: string homeTemplate: type: string description: 首页 UI 模板标识。 defaultAgent: type: string description: 默认智能体代码。 allowedAgents: type: array items: type: string description: 该设备在当前场景下允许调用的智能体列表。 blockedIntents: type: array items: type: string description: 该设备在当前场景下被阻止的意图列表。 capabilities: type: array items: type: string description: 设备硬件能力列表（如 touch/camera/id_card_ocr/file_upload）。 perceptionCapabilities: type: array items: type: string enum: - QR_IDENTITY_BINDING - NFC_TOUCH - CARD_READ - BLE_ZONE_DETECT - WIFI_ZONE_DETECT - HARMONY_NEARBY - MANUAL_CONFIRM description: 该设备支持的感知能力。P0 推荐 QR/NFC/刷卡/人工确认，BLE/鸿蒙近场仅作为可选试点。 journeyPolicy: type: object description: 动线服务策略。用于终端决定是否展示动线区和服务找人入口，不能用于绕过后端权限。 properties: mode: type: string enum: - DISABLED - MVP_STATIC - SERVER_DERIVED serviceFindPatientEnabled: type: boolean requiresPatientConfirm: type: boolean allowedCards: type: array items: type: string description: 该设备在当前场景下允许渲染的卡片类型列表。 ApiResponseDeviceScene: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/DeviceSceneData' DeviceSceneUpdateRequest: type: object properties: sceneCode: type: string homeTemplate: type: string description: 首页 UI 模板标识。 allowedAgents: type: array items: type: string description: 允许调用的智能体列表。 allowedCards: type: array items: type: string description: 允许渲染的卡片类型列表。 blockedIntents: type: array items: type: string description: 阻止的意图列表。 effectiveAt: type: string format: date-time DeviceEventRequest: type: object required: - eventId - eventType - occurredAt properties: eventId: type: string description: 设备端生成的唯一事件 ID。 eventType: type: string description: 设备事件类型。 enum: - QR_SCANNED - CARD_READ - PRINT_COMPLETED - PRINT_FAILED - NEARBY_DETECTED - NAVIGATION_STARTED - NAVIGATION_COMPLETED - DEVICE_ERROR - TOUCH_INTERACTION - CUSTOM eventPayload: type: object additionalProperties: true description: 事件附加数据。按 eventType 校验必要字段：QR_SCANNED 建议 qrType/visitId；CARD_READ 建议 cardType；NEARBY_DETECTED 建议 zoneCode/level；TOUCH_INTERACTION 建议 screen/action。未识别扩展字段只作为审计摘要，不直接触发高风险业务。 occurredAt: type: string format: date-time traceId: type: string description: 可选链路追踪 ID。 DeviceCommand: type: object properties: commandId: type: string commandType: type: string enum: - show_page - render_card - play_tts - start_navigation - stop_navigation - return_dock - print_receipt - refresh_scene - upgrade_client - custom payload: type: object additionalProperties: true expiresAt: type: string format: date-time ApiResponseDeviceCommands: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: type: object properties: commands: type: array items: $ref: '#/components/schemas/DeviceCommand' DeviceCommandAckRequest: type: object required: - status properties: status: type: string enum: - success - failed - processing - rejected message: type: string result: type: object additionalProperties: true CardInstance: type: object properties: cardInstanceId: type: string cardKey: type: string status: type: string enum: - active - submitted - processing - completed - failed - expired - cancelled renderPayload: type: object additionalProperties: true actions: type: array items: type: string expiresAt: type: string format: date-time ApiResponseCardInstance: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/CardInstance' OperatorContext: type: object required: - role - externalUserId properties: role: type: string enum: - patient - doctor - nurse - admin - system externalUserId: type: string patientId: type: string doctorId: type: string nurseId: type: string CardActionRequest: type: object required: - clientActionId - operator - deviceContext - payload properties: clientActionId: type: string operator: $ref: '#/components/schemas/OperatorContext' deviceContext: $ref: '#/components/schemas/DeviceContext' payload: type: object additionalProperties: true confirm: type: boolean billingContext: $ref: '#/components/schemas/BillingContext' CardActionData: type: object properties: cardInstanceId: type: string actionName: type: string status: type: string enum: - accepted - processing - completed - failed - duplicate result: type: object additionalProperties: true nextCard: $ref: '#/components/schemas/CardRef' ApiResponseCardAction: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/CardActionData' ToolInvokeRequest: type: object required: - toolCallId - context - input properties: toolCallId: type: string context: $ref: '#/components/schemas/ToolContext' input: type: object additionalProperties: true billingContext: $ref: '#/components/schemas/BillingContext' riskLevel: $ref: '#/components/schemas/ToolRiskLevel' description: 受控工具调用请求。仅开放给医梦 MCP Tool Server、HIS/EMR/LIS/PACS/叫号/支付等受控适配方；普通设备厂商不得直接调用。写操作必须幂等，并按 riskLevel 执行确认、权限和审计策略。 ToolContext: type: object properties: projectId: type: string user: $ref: '#/components/schemas/UserContext' deviceContext: $ref: '#/components/schemas/DeviceContext' cardInstanceId: type: string traceId: type: string ToolInvokeData: type: object properties: toolCallId: type: string toolName: type: string status: type: string enum: - success - failed - timeout - forbidden result: type: object additionalProperties: true error: $ref: '#/components/schemas/ErrorResponse' ApiResponseToolInvoke: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/ToolInvokeData' WebhookRegisterRequest: type: object required: - url - eventTypes properties: url: type: string format: uri eventTypes: type: array items: type: string secret: type: string description: type: string WebhookData: type: object properties: webhookId: type: string url: type: string eventTypes: type: array items: type: string status: type: string enum: - active - disabled ApiResponseWebhook: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/WebhookData' ApiResponseWebhookList: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: type: object properties: items: type: array items: $ref: '#/components/schemas/WebhookData' page: $ref: '#/components/schemas/PageInfo' ExternalEventRequest: type: object required: - eventId - eventType - occurredAt - sourceSystem properties: eventId: type: string eventType: type: string sourceSystem: type: string occurredAt: type: string format: date-time user: $ref: '#/components/schemas/UserContext' deviceContext: $ref: '#/components/schemas/DeviceContext' payload: type: object additionalProperties: true ToolCatalogItem: type: object properties: toolName: type: string toolType: type: string enum: - read - write description: type: string inputSchema: type: object additionalProperties: true outputSchema: type: object additionalProperties: true riskLevel: $ref: '#/components/schemas/ToolRiskLevel' ApiResponseToolCatalog: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: type: object properties: tools: type: array items: $ref: '#/components/schemas/ToolCatalogItem' UsageSummaryData: type: object properties: from: type: string format: date to: type: string format: date groupBy: type: string items: type: array items: type: object additionalProperties: true ApiResponseUsageSummary: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/UsageSummaryData' MeterEvent: type: object properties: meterEventId: type: string billingEpisodeId: type: string projectId: type: string partnerId: type: string agentId: type: string deviceId: type: string scenarioCode: type: string sourceType: type: string enum: - openplatform - dify - mcp - card - device - file - webhook sourceId: type: string meterItem: type: string rawQuantity: type: number credits: type: number chargePolicy: type: string enum: - customer_charge - license_covered - bundle_included - internal_cost - no_charge status: type: string enum: - pending - settled - reversed - failed occurredAt: type: string format: date-time ApiResponseMeterEvents: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: type: object properties: items: type: array items: $ref: '#/components/schemas/MeterEvent' page: $ref: '#/components/schemas/PageInfo' DeviceLicense: type: object properties: deviceId: type: string licenseStatus: type: string enum: - active - expired - suspended - not_bound licenseType: type: string validTo: type: string format: date ApiResponseDeviceLicenses: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: type: object properties: items: type: array items: $ref: '#/components/schemas/DeviceLicense' page: $ref: '#/components/schemas/PageInfo' AgentSummary: type: object properties: agentId: type: string name: type: string scenarioCode: type: string status: type: string ApiResponseAgentList: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: type: object properties: items: type: array items: $ref: '#/components/schemas/AgentSummary' AgentDetail: allOf: - $ref: '#/components/schemas/AgentSummary' properties: description: type: string supportedMessageTypes: type: array items: type: string supportedCards: type: array items: type: string ApiResponseAgentDetail: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/AgentDetail' DeviceDetail: type: object properties: deviceId: type: string deviceCode: type: string deviceType: type: string vendor: type: string model: type: string location: $ref: '#/components/schemas/DeviceLocation' capabilities: $ref: '#/components/schemas/DeviceCapabilities' status: type: string clientVersion: type: string lastHeartbeat: type: string format: date-time ApiResponseDeviceDetail: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: $ref: '#/components/schemas/DeviceDetail' ApiResponseDeviceList: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: type: object properties: items: type: array items: $ref: '#/components/schemas/DeviceDetail' page: $ref: '#/components/schemas/PageInfo' ApiResponseDeviceEventList: allOf: - $ref: '#/components/schemas/ApiResponse' properties: data: type: object properties: items: type: array items: $ref: '#/components/schemas/DeviceEventRequest' page: $ref: '#/components/schemas/PageInfo' PageInfo: type: object properties: page: type: integer pageSize: type: integer total: type: integer PartnerCreateRequest: type: object properties: partnerName: type: string partnerType: type: string scopes: type: array items: type: string CreditFreezeRequest: type: object properties: sourceEventId: type: string credits: type: number reason: type: string CreditSettleRequest: type: object properties: freezeId: type: string meterEventId: type: string actualCredits: type: number ToolRiskLevel: type: string enum: - L1_QUERY - L2_SENSITIVE_READ - L3_BUSINESS_WRITE - L4_FINANCIAL_ACTION - L5_MEDICAL_WRITE description: 工具风险等级。L1 查询、L2 敏感查询、L3 业务写入、L4 财务动作、L5 医疗正式写入。 x-emoon-api-version: 2026-05-29-v1.2 x-emoon-document-status: 正式联调基准版