# xk-hy-transit-go

外网 Windows 中转：从云端 xk-api 拉取监管组包 → 本机 MySQL 落库 → AES 签名 → 经内网 `xk-hy-forward-go` **双通道**上报政务云（28212 业务数据 + 28211 处方 PDF）→ 批量回调云端状态。

## 前置

1. 云端配置 `HY_TRANSIT_API_TOKEN`（与 Go `XK_API_TOKEN` 一致），可选 `HY_TRANSIT_PAYLOAD_ENCRYPT=true`（默认开启 result 传输加密），部署 `routes/hy.php` 与 `xk_hy_transit_cloud.sql`。
2. 本机执行 [`sql/hy_transit_schema.sql`](../sql/hy_transit_schema.sql)。
3. 内网部署 `xk-hy-forward-go`。

## 环境配置

```bash
cp .env.example .env
# 编辑 .env 填写 XK_API_TOKEN、HY_*、FORWARD_BASE_URL、FILE_UPLOAD_VIA_FORWARD、MYSQL_DSN
# XK_API_TOKEN 同时用于鉴权 Header 与解密云端 result（SHA256 派生 AES-128 密钥）
```

程序启动时自动 `godotenv.Load()` 读取 `.env`。

## 运行

**运营推荐**：直接双击或运行 `transit.exe`（无参数）。交互菜单 **10 秒内无操作** 将自动进入「定时执行（常驻）」；也可用菜单手动选「单次执行」或「定时执行」。超时秒数：`MENU_AUTO_SERVE_TIMEOUT_SEC`（默认 10）。

**完整命令说明**（单次 / 定时 / 计划任务 / 排错）：见 **[docs/COMMANDS.md](docs/COMMANDS.md)**。

```bash
# 交互菜单（无参数）
go run ./cmd/transit

# 单次同步
go run ./cmd/transit sync --step=all --date=2026-05-18

# 定时常驻（默认每天 22:00）
go run ./cmd/transit serve
```

步骤：`consult` | `referral` | `recipe` | `verification` | `all`

应用日志默认目录：`log/transit/`（`pull` / `push` / `app` 按日滚动；控制台仅开始/结束/错误），详见 [docs/COMMANDS.md](docs/COMMANDS.md)。

### Web 控制台

`transit serve` 启动后自动打开 **暗色 Web 控制台**（默认 `http://127.0.0.1:8765/`）：

- **文件日志**：app / pull / push 按日全文
- **同步流水**：本机三表关联，JSON 详情（拉取 payload → **推送明文** → 请求头/密文 → 政务云响应 → 推断回调）
- **测试执行**：页面触发一次 `sync`（与 CLI 相同，需 `LOG_WEB_ALLOW_TEST=true`）

无参数菜单选 **3) 查看日志** 可仅启动 Web（不跑 Cron）。环境变量：`LOG_WEB_ADDR`、`LOG_WEB_ALLOW_TEST`（见 `.env.example`）。

已有 MySQL 库需执行 [`sql/hy_push_log_plain_migration.sql`](../sql/hy_push_log_plain_migration.sql) 后，新同步记录才会落库推送明文。

## 接口文档

云端 API 说明：[`xk-api/docs/hy-transit-api.md`](../xk-api/docs/hy-transit-api.md)（WSL 路径以实际仓库为准）。

## Windows 部署

- 推荐：`transit.exe` 无参数 → 菜单选「定时执行」，或 `transit.exe serve` 注册为服务。
- 计划任务单次：见 `docs/COMMANDS.md` 中 `schtasks` 示例。