xk-hy-transit-go/docs/COMMANDS.md

# 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)。若库已存在且 Web 需展示**推送明文**，另执行 [`sql/hy_push_log_plain_migration.sql`](../../sql/hy_push_log_plain_migration.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 每天跑）
  3) 查看日志（Web 控制台，不跑定时）
  0) 退出
请选择 [0-3]:
```

- 选 **1**：再输入 `step`（默认 all）、`date`（回车=按 ANCHOR_OFFSET_DAYS 推算，默认昨日）。
- 选 **2**：显示当前 cron 配置，确认后进程常驻，到点自动 `step=all`，并启动 Web 控制台（默认 `http://127.0.0.1:8765/`）。
- 选 **3**：仅启动 Web，可浏览文件日志与本机同步流水（测试同步需选 2 用 serve）。
- 选 **0**：退出。

### Web 控制台（serve 自动启动）

| 页面 | 路径 | 说明 |
|------|------|------|
| 首页 | `/` | 导航 |
| 文件日志 | `/logs` | app / pull / push |
| 同步流水 | `/runs` | 三表关联 + JSON 详情 |
| 测试执行 | `/test` | POST 触发一次 sync |

环境变量：`LOG_WEB_ADDR`（默认 `127.0.0.1:8765`）、`LOG_WEB_ALLOW_TEST`（默认 `true`）。Cron 与 Web 测试共用互斥锁，不会并行执行两次 sync。

---

## 单次执行（跑完即退出）

适用于：补跑某天数据、联调、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)（路径以实际部署为准）。