xk-docs/docs/projects/xk-api/modules/hy-supervise.md

监管上报模块

概述

监管上报模块负责与浙江省互联网医院监管平台对接，实现咨询、转诊、处方、核销等数据的上报和回调。

---

监管批次管理

接口

方法	路径	说明
POST	transit/batch/create	创建批次
POST	transit/batch/callback	批次回调
POST	transit/batch/finish	完成批次

关联类

类	文件	说明
HyTransitBatchController	app/Http/Controllers/hy/HyTransitBatchController.php	控制器
HyTransitRecordService	app/Service/admin/hy/HyTransitRecordService.php	业务服务

关联模型

模型	表名	说明
HyTransitBatchModel	xk_hy_transit_batch	监管同步批次
HyTransitRecordModel	xk_hy_transit_record	监管拉取/回调记录

批次状态

状态	值	说明
拉取中	pulling	正在拉取数据
拉取完成	done	数据拉取完成
拉取失败	failed	数据拉取失败

回调状态

状态	值	说明
待回调	pending	等待回调
回调完成	done	回调完成

---

监管数据拉取

接口

方法	路径	说明
GET	supervise/consult	拉取咨询数据
GET	supervise/referral	拉取转诊数据
GET	supervise/recipe	拉取处方数据
GET	supervise/verification	拉取核销数据
GET	supervise/config	获取机构配置

关联类

类	文件	说明
HySupervisePullController	app/Http/Controllers/hy/HySupervisePullController.php	控制器
HyApiService	app/Service/admin/hy/HyApiService.php	API 服务
HySupervisePayloadValidator	app/Service/admin/hy/HySupervisePayloadValidator.php	数据校验

监管步骤

步骤	值	说明
在线咨询	consult	咨询信息上报
在线复诊	referral	转诊/复诊信息上报
在线处方	recipe	处方信息上报
处方核销	verification	处方核销信息上报

监管数据类型

接口	说明
uploadConsultIndicators	咨询信息上报
uploadReferralIndicators	转诊/复诊信息上报
uploadRecipeIndicators	处方信息上报（含中药扩展）
uploadRecipeVerificationIndicators	处方核销信息上报

监管数据流程

sequenceDiagram
    participant API as xk-api
    participant GO as xk-hy-forward-go
    participant GOV as 浙江省政务云

    Note over API: 定时触发 / 手动拉取
    API->>API: 1. 创建批次 (batch/create)
    API->>API: 2. 拉取数据 (supervise/consult, /recipe, ...)
    API->>API: 3. 加密打包数据
    API->>GO: 4. 转发加密数据
    GO->>GOV: 5. 透传至政务云
    GOV-->>GO: 6. 返回处理结果
    GO-->>API: 7. 回调结果
    API->>API: 8. 更新批次状态

---

处方打印

关联类

类	文件	说明
PrescriptionPrintService	app/Service/admin/hy/PrescriptionPrintService.php	打印服务
HyRecipeHtmlRenderer	app/Service/admin/hy/HyRecipeHtmlRenderer.php	HTML 渲染

处方详情

方法	路径	说明
GET/POST	transit/prescription/detail	处方详情 + 打印 HTML
POST	transit/prescription/recipe-file	保存处方文件 ID

---

监管查询（管理后台）

接口

方法	路径	说明
GET	log/hy-transit-batch-list	批次列表
GET	log/hy-transit-record-list	记录列表
GET	log/hy-transit-record-detail	记录详情

---

加密规则

::: warning 安全信息

• 算法: AES-128-ECB + PKCS7 + Base64
• 密钥: substr(sha256(HY_TRANSIT_API_TOKEN), 0, 16)
• 默认启用加密（HY_TRANSIT_PAYLOAD_ENCRYPT=true） :::

签名规则

sign = HmacSHA256(requestBody + secret + header params sorted alphabetically)

---

政务云接口规范

HTTP 层返回码

代码	说明
200	成功
-1	系统繁忙
40001	参数错误
40002	appKey 未找到
40003	appKey 已冻结
40004	appKey/appSecret 不匹配
40006	无权限
40007	IP 未在白名单
40010	签名无效
40011	请求已过期
40012	其他服务错误

业务层 msgCode

代码	说明
200	成功
-99	参数字段为空
-98	数据为空
-1	具体失败原因