# 监管上报模块

## 概述

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

---

## 监管批次管理

### 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| 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` | 处方核销信息上报 |

### 监管数据流程

```mermaid
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 | 具体失败原因 |