优康云外部接口说明

本页说明优康云体检智能体面向官网、CLI、MCP Server 和第三方 AI 工具的外部接口设计。当前可先作为接口约定和安全边界文档，后端能力将按阶段开放。

设计原则：接口必须清晰返回状态、错误码和原因。机构开户注册必须进入待审核或验证码确认流程，不得默认放行。

接口清单

接口	用途	当前状态
`GET /manifest/ukang-agent-manifest.json`	机器可读安装清单，供 AI 判断组件、版本、下载地址、校验位和能力状态。	第一阶段开放
`POST /api/agent/register-org`	申请优康云账号，提交机构名称、联系人、手机号和资质资料引用。	接口设计，待后端开放
`POST /api/agent/install-report`	上传安装结果、组件版本、端口、异常项和实施报告摘要。	接口设计，待后端开放
`GET /api/agent/download-token`	获取受控下载授权，用于限制安装包下载、记录审计和回溯来源。	接口设计，待后端开放
`GET /api/agent/version`	供 AI 判断当前最新版本、可用通道和升级策略。	接口设计，待后端开放

GET /manifest/ukang-agent-manifest.json

返回优康云体检智能体安装清单。下载包应保留 SHA256 校验位，AI 应在执行安装前校验清单中的 sha256。

{
  "schemaVersion": "1.0",
  "implementationPhase": "phase-1",
  "components": []
}

POST /api/agent/register-org

register-org 用于申请优康云账号。提交后只产生申请单，不直接开通正式机构。

{
  "name": "某某体检中心",
  "phone": "13800000000",
  "contactName": "张三",
  "socialCreditCode": "91110000000000000X",
  "licenseFileId": "FILE-20260524-000001"
}

成功响应应包含申请编号和审核状态，例如 pending_review 或 sms_verify_required。

POST /api/agent/install-report

install-report 用于上传安装结果。报告应记录安装时间、版本号、开放端口、配置项、异常项，不应上传明文数据库密码或云端密钥。

{
  "requestId": "REQ-20260524-000001",
  "machineCode": "HOST-XXXX",
  "components": [
    {"id": "mysql84-runtime", "version": "8.4.6", "status": "installed"}
  ],
  "issues": []
}

GET /api/agent/download-token

download-token 用于获取受控下载授权。下载授权应有过期时间、组件范围和审计记录。

GET /api/agent/download-token?component=ukang-health-exam&channel=stable

GET /api/agent/version

version 用于 AI 判断当前最新版本、通道和可升级组件。

{
  "product": "ukang-health-exam-agent",
  "channel": "stable",
  "latestVersion": "10.1.125-beta",
  "manifestUrl": "https://www.ukang.cc/manifest/ukang-agent-manifest.json"
}

安全要求

要求	说明
开户注册审核	机构开户注册必须进入待审核或验证码确认流程，不得默认放行。
下载校验	下载包应保留 SHA256 校验位，CLI/MCP 安装前必须校验。
审计日志	所有云端配置必须记录审计日志，包括操作者、时间、机构、配置项和结果。
敏感信息	不得在前端写死 MySQL 密码、云端密钥、机构密钥。
失败返回	失败必须返回明确错误码和原因，不允许静默吞错或返回假成功。

返回 AI 安装页面