hn-readcard-go/README.md

# readcard-go

## GUI 读卡界面

双击打包后的 `readcard-go.exe` 会启动桌面读卡界面和后台 HTTP 服务。点击“读卡”后，成功时显示二维码，内容格式为：

```text
encodeURIComponent(Name)|IDNum|CardNum|CardIDCode
```

失败时错误原因显示在二维码下方。GUI 默认使用杭州免 PIN 读卡器类型，可在 `config.json` 中修改：

```json
"gui_reader_type": "ZJ_HZ_310000"
```

Windows Common Controls v6 清单已通过 `rsrc_windows_386.syso` 嵌入 EXE，用于避免 GUI 启动时出现 `TTM_ADDTOOL failed`。`readcard-go.exe.manifest` 是资源的源文件；如修改该文件，需要重新生成对应的 `.syso` 资源。

`card-read-service` 的 Go 版本，保持原有 HTTP 接口和响应格式，并增加业务失败、panic、DLL 崩溃与异常退出日志。

## 构建和运行

### 打包环境要求

执行打包操作的电脑必须已经安装 Go 开发环境，并且 `go` 命令已加入系统 `PATH`。可以在命令行中执行以下命令检查：

```powershell
go version
```

能够正常输出 Go 版本信息即可，例如：

```text
go version go1.26.5 windows/amd64
```

不需要另外安装 32 位 Go。厂商 `CardReaderDLL.dll` 是 32 位 DLL，打包脚本会自动设置 `GOOS=windows`、`GOARCH=386` 和 `CGO_ENABLED=0`，使用常规的 64 位 Go 环境即可生成 32 位程序。

最终使用 `dist/readcard-go.exe` 的电脑不需要安装 Go 环境，但必须复制完整的 `dist` 目录，不能只复制 exe 文件。

### 执行打包

在 PowerShell 中执行：

```powershell
.\build.ps1 -Version "1.0.0"
.\dist\readcard-go.exe
```

也可以直接双击项目根目录下的 `一键打包.bat`。脚本会自动调用 PowerShell 完成测试、构建和厂商依赖复制，成功后自动打开 `dist` 发布目录；打包版本可修改批处理文件顶部的 `BUILD_VERSION`。

在 macOS 中可使用 `一键打包.sh` 交叉编译 Windows 32 位产物：

```bash
chmod +x ./一键打包.sh
./一键打包.sh
```

只检查打包环境、不执行构建：

```bash
./一键打包.sh --check
```

macOS 脚本会检查 Go 版本和 `windows/386` 目标，编译 Windows 测试程序（不在 macOS 上运行），生成 `dist/readcard-go.exe`，并复制 `config.json` 和完整的厂商 DLL 目录。最终产物仍需在 Windows 真机上验证。

构建脚本会运行测试、生成 `dist/readcard-go.exe`，并把原项目的 `package/DWCardReaderDLL` 复制到发布目录。开发运行可执行：

```powershell
.\run.ps1
```

启动后：

- 健康检查：`GET http://127.0.0.1:17880/health`
- 免 PIN 读卡：`POST http://127.0.0.1:17880/api/card/read-nopin`
- 嘉兴带 PIN 读卡：`POST http://127.0.0.1:17880/api/card/read`
- HMAC-SM3：`POST http://127.0.0.1:17880/api/hmac-sm3`

免 PIN 读卡示例：

```powershell
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:17880/api/card/read-nopin `
  -ContentType "application/json" `
  -Body '{"reader_type":"ZJ_HZ_310000"}'
```

## 日志

日志默认写入程序目录下的 `logs`：

- `service-组件-YYYY-MM-DD.log`：启动、配置、DLL 加载、HTTP 失败、读卡失败、panic 堆栈和自动重启记录。
- `crash-YYYY-MM-DD.log`：工作进程写到标准错误的 Go runtime/native crash 信息。

日志达到 `log_max_file_mb` 后自动生成 `-001`、`-002` 分卷；日志目录超过 `log_max_total_mb` 时优先删除最旧分卷，同时仍按 `log_retention_days` 清理过期日志。默认单文件最大 20MB、目录总量最大 200MB、保留 30 天。

程序默认由守护进程启动工作进程。若 DLL 导致工作进程直接崩溃，守护进程会记录 PID、退出码、运行时长并自动重启；30 秒内连续崩溃达到 `max_rapid_restarts` 后停止，避免无限重启。日志不会记录身份证号、卡号、密钥或请求正文。

## 配置

`config.json`：

```json
{
  "host": "127.0.0.1",
  "port": 17880,
  "dll_dir": "package/DWCardReaderDLL",
  "cors_origin": "*",
  "log_dir": "logs",
  "log_retention_days": 30,
  "log_max_file_mb": 20,
  "log_max_total_mb": 200,
  "restart_delay_ms": 1500,
  "max_rapid_restarts": 5
}
```

支持环境变量：`CARD_HOST`、`CARD_PORT`、`CARD_DLL_DIR`、`CARD_CORS_ORIGIN`、`CARD_LOG_DIR`、`CARD_LOG_MAX_FILE_MB`、`CARD_LOG_MAX_TOTAL_MB`。调试时设置 `CARD_NO_SUPERVISOR=1` 可直接运行工作进程。

接口行为和 `reader_type` 列表请参照原项目 `card-read-service/README.md`。