初始化

2026-05-22 08:06:07 +08:00
commit f3e6917421
37 changed files with 3219 additions and 0 deletions
--- a/docs/COMMANDS.md
+++ b/docs/COMMANDS.md
@@ -0,0 +1,210 @@
+# xk-hy-transit-go 运行命令说明
+
+## 前置
+
+1. 复制环境配置：`cp .env.example .env`，填写 `XK_API_TOKEN`、`HY_*`、`FORWARD_BASE_URL`、`MYSQL_DSN`。
+2. 本机 MySQL 已执行 [`sql/hy_transit_schema.sql`](../../sql/hy_transit_schema.sql)。
+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 每天跑）
+  0) 退出
+请选择 [0-2]:
+```
+
+- 选 **1**：再输入 `step`（默认 all）、`date`（回车=按 ANCHOR_OFFSET_DAYS 推算，默认昨日）。
+- 选 **2**：显示当前 cron 配置，确认后进程常驻，到点自动 `step=all`。
+- 选 **0**：退出。
+
+---
+
+## 单次执行（跑完即退出）
+
+适用于：补跑某天数据、联调、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`。
+
+### 单独测监管文件上传
+
+需 xk-api 配置 `HY_APP_KEY`、`HY_APP_SECRET`、`HY_FILE_BUCKET`（否则 `uploadToken` 为空）：
+
+```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` 与后台处方打印预览 |
+| `upload token empty` | xk-api `.env` 配置 `HY_APP_KEY` / `HY_APP_SECRET` / `HY_FILE_BUCKET` |
+| PDF 上传连接超时 | 确认 `FILE_UPLOAD_VIA_FORWARD=true` 且 forward 已监听 `/mng/file/auth/upload`；检查 forward `.env` 中 `FILE_TARGET_URL` |
+| 推送显示 success 但监管未入库 | 若响应含 `msgCode` 须为 200；无 `msgCode` 时看 `code` 与 HTTP |
+| `上传凭证无效或过期` | 文件上传 HTTP 403，重新拉取 config 或检查 token |
+
+---
+
+## 子命令速查
+
+```text
+transit              # 无参数 → 交互菜单（运营）
+transit sync ...     # 单次同步
+transit serve        # 定时常驻
+transit upload-test --pdf=...  # 单独测文件上传
+transit --step=all   # 兼容旧单次参数
+```
+
+接口说明见云端 [hy-transit-api.md](../../xk-api/docs/hy-transit-api.md)（路径以实际部署为准）。