carlostousferragut/rentacaar-scanner-agent
GitHub: carlostousferragut/rentacaar-scanner-agent
运行于Windows的文档扫描代理服务，通过HTTP API提供西班牙身份证及护照的自动化扫描与识别能力。
Stars: 0 | Forks: 0
# RentaCaaR Scanner Agent
Windows 服务，在端口 7823 上提供本地 HTTP API，用于通过 WIA 连接的平板扫描仪扫描文档（通过 PDF417 条形码扫描西班牙 DNI/NIE，通过 MRZ OCR 扫描护照）。
## 环境要求
- Windows 10/11 x64
- .NET 8 SDK（用于开发）
- WIA 兼容的平板扫描仪
- Inno Setup 6（用于构建安装程序）
- Tesseract tessdata 文件（用于 MRZ/护照 OCR）
## Tessdata 设置
从 [tessdata_fast](https://github.com/tesseract-ocr/tessdata_fast) 仓库下载训练数据文件，并将其放入：
```
RentaCaaR.ScannerAgent/tessdata/
mrz.traineddata ← specialized MRZ model (preferred)
spa.traineddata ← Spanish language (fallback)
eng.traineddata ← English language (fallback)
```
`mrz.traineddata` 文件可以在 [tessdata](https://github.com/tesseract-ocr/tessdata) 仓库中找到（这是用于机读区的专用模型）。
## 构建
```
# 还原包
dotnet restore RentaCaaR.ScannerAgent/RentaCaaR.ScannerAgent.csproj
# 发布自包含单文件可执行文件
dotnet publish RentaCaaR.ScannerAgent/RentaCaaR.ScannerAgent.csproj -c Release
```
输出：`RentaCaaR.ScannerAgent/bin/Release/net8.0-windows/win-x64/publish/RentaCaaR.ScannerAgent.exe`
## 构建安装程序
1. 安装 [Inno Setup 6](https://jrsoftware.org/isinfo.php)
2. 首先运行构建（见上文），以便生成发布输出
3. 编译安装脚本：
```
iscc installer/setup.iss
```
输出：`installer/Output/RentaCaaR-Scanner-Setup-1.0.6.exe`
## 自动发布 (GitHub Actions)
此仓库包含位于 `.github/workflows/release.yml` 的工作流，它会：
1. 从 `installer/setup.iss` 读取 `MyAppVersion`
2. 验证其与 `RentaCaaR.ScannerAgent.csproj` 中的 `` 匹配
3. 在 `Release` 模式下还原并发布 Agent
4. 在 Runner 上安装 Inno Setup
5. 根据 `installer/setup.iss` 构建安装程序
6. 创建/发布包含安装程序资产的 GitHub Release `v{MyAppVersion}`
它在推送到 `main` 分支时自动运行（无需手动标记 Tag）。
如果 Release `v{MyAppVersion}` 已存在，则跳过发布。
典型流程：
```
# 1) 将两个文件中的版本号提升至相同的值（例如 1.0.5）
# - RentaCaaR.ScannerAgent/RentaCaaR.ScannerAgent.csproj
# - installer/setup.iss
# 2) 提交并推送到 main
git add .
git commit -m "Release 1.0.5"
git push origin main
```
重要提示：保持 `RentaCaaR.ScannerAgent.csproj` 与 `installer/setup.iss` 的版本一致，否则工作流将按设计执行失败。
## 开发（作为控制台应用运行）
```
dotnet run --project RentaCaaR.ScannerAgent/RentaCaaR.ScannerAgent.csproj
```
服务将在 `http://127.0.0.1:7823` 上启动。作为控制台应用（而非 Windows 服务）运行时，其行为完全相同 —— WIA 和 OCR 的工作方式一致。
## API 端点
| Method | Path | 描述 |
|--------|-------------|--------------------------------------------------|
| GET | /health | 服务状态、版本、注册状态 |
| GET | /scanners | 列出已连接的 WIA 扫描仪 |
| POST | /scan | 扫描文档并返回字段 + base64 图像 |
| POST | /register | 使用 Token 将 Agent 注册到后端 |
| POST | /settings | 设置默认扫描仪 ID |
### POST /scan 请求体
```
{
"scannerId": "optional-wia-device-id",
"dpi": 300
}
```
### POST /register 请求体
```
{
"token": "one-time-registration-token",
"backendUrl": "https://your-rentacaar-instance.com",
"name": "optional-agent-name"
}
```
## Windows 注册表
配置存储在：
```
HKEY_LOCAL_MACHINE\SOFTWARE\RentaCaaR\ScannerAgent
AgentId (string)
Secret (string)
BackendUrl (string)
OrgName (string)
OfficeName (string)
DefaultScannerId (string, optional)
```
## 自动更新
服务每小时轮询一次 `{backendUrl}/api/agent/updates?version=X&agentId=Y`。如果有新版本可用，它会下载并静默运行 Inno Setup 安装程序（`/VERYSILENT /NORESTART /SUPPRESSMSGBOXES`），该程序会停止服务、替换二进制文件并自动重启服务。
## 心跳
每 5 分钟，服务会向 `{backendUrl}/api/agent/heartbeat` 发送当前版本。认证使用 `X-Agent-Auth: {agentId}:{secret}` 标头。
标签：GitHub Actions, HTTP API, HTTP工具, Inno Setup, MRZ, .NET 8, OCR, PDF417条码, Python脚本, RentaCaaR, Tesseract, WIA, Windows服务, WinForms/WPF相关, 命令控制, 图像处理, 平板扫描仪, 护照识别, 数据采集, 文档扫描, 本地服务, 机器视觉, 自动笔记, 西班牙DNI/NIE, 身份证识别