初始化

2026-07-08 15:04:42 +08:00
commit 70264153e5
129 changed files with 13797 additions and 0 deletions
--- a/docs/projects/xk-api/modules/hy-supervise.md
+++ b/docs/projects/xk-api/modules/hy-supervise.md
@@ -0,0 +1,180 @@
+# 监管上报模块
+
+## 概述
+
+监管上报模块负责与浙江省互联网医院监管平台对接，实现咨询、转诊、处方、核销等数据的上报和回调。
+
+---
+
+## 监管批次管理
+
+### 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| 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 | 具体失败原因 |