xkyy/xk-hy-transit-go
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bf816536be86e03c5658c98cddf9ce2adce8d3e3
xk-hy-transit-go/docs/COMMANDS.md

240 lines
10 KiB
Markdown
Raw Normal View History

初始化
2026-05-22 08:06:07 +08:00
# xk-hy-transit-go 运行命令说明
## 前置
接口加密
2026-05-27 08:18:07 +08:00
1. 复制环境配置：`cp .env.example .env`，填写 `XK_API_TOKEN`、`HY_*`、`FORWARD_BASE_URL`、`MYSQL_DSN`。云端 `HY_TRANSIT_API_TOKEN` 须与 `XK_API_TOKEN` 一致；默认开启 `/api/hy/*` 响应 `result` 传输加密（`HY_TRANSIT_PAYLOAD_ENCRYPT`），Go 客户端自动解密。
更新html
2026-05-22 09:17:39 +08:00
2. 本机 MySQL 已执行 [`sql/hy_transit_schema.sql`](../../sql/hy_transit_schema.sql)。若库已存在且 Web 需展示**推送明文**，另执行 [`sql/hy_push_log_plain_migration.sql`](../../sql/hy_push_log_plain_migration.sql)。
初始化
2026-05-22 08:06:07 +08:00
3. 内网已启动 **xk-hy-forward-go**（`forward.exe` 或 `go run .`）。
4. 云端已部署 `xk_hy_transit_cloud.sql` 与 `routes/hy.php`。
---
## 运营推荐：直接运行（交互菜单）
无参数启动程序，按中文提示选择，无需记忆子命令：
```bat
transit.exe
```
或开发环境：
```bash
go run ./cmd/transit
```
菜单示例：
```
======== 互联网医院监管中转 ========
1) 单次执行（跑一轮后退出）
2) 定时执行（常驻，按 .env 中 CRON 每天跑）
更新html
2026-05-22 09:17:39 +08:00
3) 查看日志（Web 控制台，不跑定时）
初始化
2026-05-22 08:06:07 +08:00
0) 退出
更新启动逻辑
2026-05-22 10:20:13 +08:00
10s 内未选择将自动启动「2) 定时执行（常驻）」
更新html
2026-05-22 09:17:39 +08:00
请选择 [0-3]:
初始化
2026-05-22 08:06:07 +08:00
```
更新启动逻辑
2026-05-22 10:20:13 +08:00
- **10 秒无输入**：自动选择 **2** 并进入确认步骤；确认步骤同样 **10 秒无输入** 则自动启动常驻（适合双击 `transit.exe` 无人值守）。超时秒数可用环境变量 `MENU_AUTO_SERVE_TIMEOUT_SEC`（正整数，默认 10）调整。
- 选 **1**：再输入 `step`（默认 all）、`date`（回车=按 ANCHOR_OFFSET_DAYS 推算，默认昨日）；该路径仍须手动输入，无自动超时。
更新html
2026-05-22 09:17:39 +08:00
- 选 **2**：显示当前 cron 配置，确认后进程常驻，到点自动 `step=all`，并启动 Web 控制台（默认 `http://127.0.0.1:8765/`）。
- 选 **3**：仅启动 Web，可浏览文件日志与本机同步流水（测试同步需选 2 用 serve）。
初始化
2026-05-22 08:06:07 +08:00
- 选 **0**：退出。
更新html
2026-05-22 09:17:39 +08:00
### Web 控制台（serve 自动启动）
| 页面 | 路径 | 说明 |
|------|------|------|
| 首页 | `/` | 导航 |
| 文件日志 | `/logs` | app / pull / push |
接口加密
2026-05-27 08:18:07 +08:00
| 同步流水 | `/runs` | 三表关联 + JSON 详情；可一键清空本机三表 |
更新html
2026-05-22 09:17:39 +08:00
| 测试执行 | `/test` | POST 触发一次 sync |
接口加密
2026-05-27 08:18:07 +08:00
API：`POST /api/runs/truncate` — 清空本机 `hy_push_log` / `hy_push_record` / `hy_sync_job`（需 MySQL 已连接；sync 运行中返回 409）。仅影响本机 `xk_hy_transit` 审计库。
环境变量：`LOG_WEB_ADDR`（默认 `127.0.0.1:8765`）、`LOG_WEB_ALLOW_TEST`（默认 `true`）。Cron 与 Web 测试共用互斥锁，不会并行执行两次 sync；截断与 sync 亦互斥。
更新html
2026-05-22 09:17:39 +08:00
初始化
2026-05-22 08:06:07 +08:00
---
## 单次执行（跑完即退出）
适用于：补跑某天数据、联调、Windows 计划任务每日调一次。
| 场景 | 命令 |
|------|------|
| 全量四步（推荐） | `go run ./cmd/transit sync --step=all` |
| 指定锚定日 | `go run ./cmd/transit sync --step=all --date=2026-05-18` |
| 只跑咨询 | `go run ./cmd/transit sync --step=consult` |
| 只跑处方 | `go run ./cmd/transit sync --step=recipe` |
| 编译后 exe | `transit.exe sync --step=all` |
| 兼容旧写法 | `go run ./cmd/transit --step=all --date=2026-05-18` |
`--step` 可选：`consult` | `referral` | `recipe` | `verification` | `all`。
未传 `--date` 时，锚定日 = 今天减去 `.env` 中 `ANCHOR_OFFSET_DAYS`（默认 1，即昨日）。
### Windows 计划任务（每日单次，不常驻）
```bat
schtasks /Create /TN "HyTransitSync" /TR "D:\path\to\transit.exe sync --step=all" /SC DAILY /ST 22:00
```
---
## 定时任务执行（进程常驻）
适用于：外网机 7×24 保活，由内置 Cron 到点执行。
| 场景 | 命令 / 配置 |
|------|-------------|
| 默认每天 22:00 | `go run ./cmd/transit serve` 或 `transit.exe serve` |
| 自定义 cron | `.env` 设置 `CRON_EXPR=0 30 22 * * *`（分 时 日 月 周） |
| 简写时间 | `SCHEDULE_TIME=22:30`（仅当未设置 `CRON_EXPR` 时生效） |
说明：`serve` 启动后阻塞不退出；到点执行 `step=all` + 默认锚定日。修改 cron 需重启进程。
优先级：`CRON_EXPR` 环境变量存在 > `SCHEDULE_TIME` > 默认 `0 22 * * *`。
---
## 与 xk-hy-forward-go 配合（双通道）
外网 **transit-go** 只访问内网 **forward-go**，由 forward 转发至政务云 `59.202.52.129`：
| 通道 | transit 请求路径 | forward 转发目标 |
|------|------------------|------------------|
| 监管业务 JSON | `POST {FORWARD_BASE_URL}/province/supervise/data` | `28212` `/province/supervise/data` |
| 处方 PDF 上传 | `POST {FORWARD_BASE_URL}/mng/file/auth/upload` | `28211` `/mng/file/auth/upload` |
内网机先启动转发服务：
```bash
cd xk-hy-forward-go
go run .
```
或 `forward.exe`。详见 [forward-go README](../xk-hy-forward-go/README.md)。
`.env` 建议：
```env
FORWARD_BASE_URL=http://192.168.1.10:8080
FILE_UPLOAD_VIA_FORWARD=true
```
`FILE_UPLOAD_VIA_FORWARD=true`（默认）时 PDF **不直连**政务云，避免外网机访问 `59.202.52.129:28211` 失败。
---
## 处方 PDF 本地落盘
生成处方 PDF 并上传监管前，会同步写入本地文件（失败仅告警，不阻断上传）：
```text
{程序目录}/pdf/{YYYY-MM-DD}/{患者姓名}{诊所名} {处方号} {YYYY-MM-DD HH-mm-ss}.pdf
```
| 场景 | 程序目录 |
|------|----------|
| 打包运行 `transit.exe` | exe 所在目录 |
| 开发 `go run ./cmd/transit` | 当前工作目录（建议在 `xk-hy-transit-go` 下执行） |
| 配置 | 说明 |
|------|------|
| `CHROME_PATH` | 可选：Chrome/Edge 路径；未设则自动探测 |
| xk-api | 打印 HTML 由 `GET /api/hy/transit/prescription/detail` 生成（与 PC 处方详情版式一致） |
示例：`D:\deploy\pdf\2026-05-19\张三萧康中医馆 ZY8181791680594661 2026-05-19 14-30-05.pdf`（exe 同级 `pdf` 目录）
流程：**拉取 HTML → chromedp 转 PDF → 落盘 `pdf/` → 上传监管**。
### 单独测 PDF（不走上报）
```bash
go run ./cmd/transit pdf-test --prescription-id=12345
# 或本地 HTML
go run ./cmd/transit pdf-test --html-file=./test.html --patient=张三 --store=测试诊所 --prescription-no=ZY123
```
成功时应看到 `saved local pdf: ...\pdf\2026-05-19\...pdf`。
### 单独测监管文件上传
测试
2026-05-28 16:39:51 +08:00
需 xk-api 配置 `HY_APP_KEY`、`HY_APP_SECRET`、`HY_FILE_BUCKET`（transit 按 FileAuth 算法本地生成 `uploadToken`，每次上传前自动刷新）。算法说明见 [`docs/FILEAUTH.md`](FILEAUTH.md)。
初始化
2026-05-22 08:06:07 +08:00
```bash
go run ./cmd/transit upload-test --pdf=./test.pdf
```
成功输出 `upload ok fileId=...`。
---
## 应用日志
默认写入项目内 `{程序目录}/log/transit/`（可用 `LOG_DIR` 覆盖根路径，实际为 `{LOG_DIR}/transit/`）：
```text
xk-hy-transit-go\log\transit\
pull-YYYY-MM-DD.log # 批次、拉取、校验跳过
push-YYYY-MM-DD.log # 每条上报、PDF 上传、code/msgCode
app-YYYY-MM-DD.log # 启动、cron、同步摘要
```
每次 `sync` / 定时 cron 执行会在三个日文件中写入 `======== BEGIN ... ========` 与 `======== END ... ========` 分隔行。
与 MySQL `hy_push_log` 互补。**控制台**仅输出开始、结束、失败摘要（`[同步]` / `[定时]`）；详情见上述日志文件。
定时常驻启动时会打印 `日志目录=...`，请以此路径为准，勿与空的 `xk-hy-transit-go\log\` 下未使用目录混淆。
内网 forward 日志仍在同级 `log/forward/`（forward-go 进程）。
监管业务上报成功条件（Ver2.0）：
- 有 `body.msgCode`（或 `body.body.msgCode`）：HTTP 200 且 JSON `code=200` 且 `msgCode=200`
- **无** `msgCode` 字段：HTTP 200 且 JSON `code=200` 即可
---
## 排错
| 现象 | 处理 |
|------|------|
| `chromedp: context canceled` | 已修复：勿在浏览器初始化后立即 cancel allocator；请拉最新代码后重试 |
| `缺少环境变量 XK_API_TOKEN` | 检查 `.env` 与云端 `HY_TRANSIT_API_TOKEN` 一致 |
| `batch_id required` | 云端拉取接口需先 `batch/create`；请用新版 sync 流程 |
| `pull consult http 401` | Token 错误或过期 |
| 转发超时 | 检查 forward-go 是否启动、`ALLOW_IPS` 是否拦了中转机 IP |
| 交互菜单不出现 | 非 TTY 环境（CI/重定向）会只打印用法；请用 `sync`/`serve` 子命令 |
| PDF 未生成 / chromedp 报错 | 安装 Chrome 或设置 `CHROME_PATH`；首次需 `go mod tidy` 拉取 chromedp 依赖 |
| 样式与 PC 不一致 | 对比 `GET /api/hy/transit/prescription/detail` 的 `recipe_file_html` 与后台处方打印预览 |
测试
2026-05-28 16:39:51 +08:00
| `upload token empty` / `appKey/appSecret/fileBucket 未配置` | xk-api 或 transit `.env` 配置 `HY_APP_KEY` / `HY_APP_SECRET` / `HY_FILE_BUCKET`；`/config` 点「重新拉取」 |
初始化
2026-05-22 08:06:07 +08:00
| PDF 上传连接超时 | 确认 `FILE_UPLOAD_VIA_FORWARD=true` 且 forward 已监听 `/mng/file/auth/upload`；检查 forward `.env` 中 `FILE_TARGET_URL` |
| 推送显示 success 但监管未入库 | 若响应含 `msgCode` 须为 200；无 `msgCode` 时看 `code` 与 HTTP |
测试
2026-05-28 16:39:51 +08:00
| 文件上传 HTTP 403 body=`forbidden` | **forward-go 本地拒绝**：检查 `ALLOW_IPS`、`FORWARD_SHARED_SECRET` 与 transit `X-Forward-Token` |
| 文件上传 HTTP 403 含 JSON `message` | **政务云拒绝 token**：核对 `HY_FILE_BUCKET` scope、密钥；`/config` 重新拉取；Web `/upload` 查看完整 `detail` |
| xk-api 改了 HY_APP_* 但 transit 仍是旧值 | transit `serve` 长进程需 Web「重新拉取」或重启；云端凭证优先于本地 `.env`；uploadToken 每次上传前自动重生 |
### Web 控制台页面（`transit serve`）
| 路径 | 说明 |
|------|------|
| `/config` | 查看云端 / 本地 / 生效互医配置；对比云端预生成 token 与 Runner 本地 FileAuth token |
| `/upload` | 测试 PDF 上传（失败时展示完整 upstream 错误，Toast 提示） |
| `/runs` | 同步流水；失败记录可「整条重试」 |
改 xk-api `.env` 后：`php artisan config:clear` + 重启 PHP/Laravel-S，再在 transit `/config` 点重新拉取。
初始化
2026-05-22 08:06:07 +08:00
---
## 子命令速查
```text
transit # 无参数 → 交互菜单（运营）
transit sync ... # 单次同步
transit serve # 定时常驻
transit upload-test --pdf=... # 单独测文件上传
transit --step=all # 兼容旧单次参数
```
接口说明见云端 [hy-transit-api.md](../../xk-api/docs/hy-transit-api.md)（路径以实际部署为准）。
Reference in New Issue Copy Permalink