cmroubao/backend-api/README.md

cmroubao backend API

Go 1.23.0、Gin 1.11.0 和 SQLite 构成的单进程采购任务服务。当前提供参考图上传与 规范化、任务创建/列表/详情/取消 API、服务端渲染管理页面、健康检查和显式数据库 迁移，并使用 ADMIN 服务端会话和 BUYER + 预授权设备联合身份隔离管理与执行接口。 App 设备接口已支持 readiness heartbeat、原子领取、安全幂等重放、参考图授权、 start/运行续租/release 和取消安全确认。

环境

• Go 1.23.0
• CGO_ENABLED=1
• PATH 中可用的 GCC

可选环境变量：

变量	默认值	说明
CMROUBAO_HTTP_ADDR	127.0.0.1:8080	监听地址；无 TLS 时只允许 loopback
CMROUBAO_DATABASE_PATH	var/cmroubao.db	SQLite 文件路径
CMROUBAO_ASSET_DIR	var/assets	规范化参考图片的受控本地目录
CMROUBAO_TLS_CERT_FILE	无	TLS certificate；必须和 private key 同时设置
CMROUBAO_TLS_KEY_FILE	无	TLS private key；非 loopback 监听必须设置
CMROUBAO_CLAIM_LEASE	10m	CLAIMED 租约；允许 1m 至 30m
CMROUBAO_RUNNING_LEASE	30m	RUNNING/等待确认的离线执行授权；允许 5m 至 120m
CMROUBAO_READINESS_TTL	2m	设备就绪 heartbeat 新鲜度；允许 30s 至 10m
CMROUBAO_SHUNYUNBAO_URL	https://www.shunyunbaoerp.com	顺运宝 HTTPS origin
CMROUBAO_SHUNYUNBAO_USERNAME	无	顺运宝账号；必须与密码同时设置
CMROUBAO_SHUNYUNBAO_PASSWORD	无	顺运宝密码；必须与账号同时设置
CMROUBAO_OCR_API_URL	无	OCR POST endpoint；HTTP 只允许本机 loopback

本地 ERP .env

API 启动时只从当前目录读取 .env，标准启动脚本会先进入 backend-api/，因此文件位置 固定为 backend-api/.env。首次配置：

Set-Location backend-api
Copy-Item .env.example .env
# 编辑 .env，填入顺运宝账号和密码

该文件只允许上述 CMROUBAO_SHUNYUNBAO_* 值和 CMROUBAO_OCR_API_URL，进程环境变量 优先于同名 .env 值。 它不配置数据库、监听/TLS、authctl 密码或其他应用选项，也不会修改全局进程环境。缺失 .env 时 ERP/OCR 保持未配置，其他本地功能仍可启动。仅支持空行、整行 # 注释和 KEY=VALUE （需要保留空格或 # 的值可使用成对单/双引号）；不支持变量展开、命令或行内注释。

.env 已被 Git 忽略，应只保存在本机受限目录；.env.example 不得填入真实凭证。var/ 运行数据同样不得提交。

按单号导入货运时，API 在创建同步前使用该 OCR endpoint 读取 ERP 验证码并建立进程内会话。 OCR 不可用时导入页显示 OCR 服务无效，不会创建同步记录；验证码、图片、Cookie 和识别文字 不写入数据库、日志或浏览器。

命令

$env:GOTOOLCHAIN = "local"
go test ./...
go vet ./...
go build -o bin/cmroubao-api.exe ./cmd/api
go build -o bin/cmroubao-migrate.exe ./cmd/migrate
go build -o bin/cmroubao-authctl.exe ./cmd/authctl
go run ./cmd/migrate up
go run ./cmd/migrate status

$env:CMROUBAO_AUTH_PASSWORD = "至少 5 个 UTF-8 字节"
go run ./cmd/authctl create-user ADMIN admin
Remove-Item Env:CMROUBAO_AUTH_PASSWORD

$env:CMROUBAO_AUTH_PASSWORD = "采购员独立强密码，至少 5 个 UTF-8 字节"
go run ./cmd/authctl create-user BUYER buyer01
Remove-Item Env:CMROUBAO_AUTH_PASSWORD
$env:CMROUBAO_AUTH_PASSWORD = "账号新密码，至少 5 个 UTF-8 字节"
go run ./cmd/authctl reset-password admin
Remove-Item Env:CMROUBAO_AUTH_PASSWORD
go run ./cmd/authctl create-device buyer-phone-01
# 发生人员离岗或设备风险时，现有凭证会随禁用立即失效
go run ./cmd/authctl disable-user buyer01
go run ./cmd/authctl disable-device <device-id>
# 恢复时使用对应的 enable-user / enable-device
go run ./cmd/api

API 启动前会检查全部 migration 已应用；发现 pending migration 会拒绝启动并提示先 执行 go run ./cmd/migrate up，不会在服务进程内自动改表。

authctl create-user 和 authctl reset-password 的密码只从 CMROUBAO_AUTH_PASSWORD 进程环境变量读取，不接受命令行密码或 ERP .env。 create-device 只在成功时输出一次设备 ID 和 256 bit 设备 token；原值应立即放入 设备安全配置，不得写入 Git、普通日志或共享文档。enable-user、disable-user、 enable-device、disable-device 是受支持的本地停用/恢复入口；禁用会让该主体的 现有 session/access token 在下一次请求时失效。

服务启动后，GET /healthz 在数据库可用时返回 200 和 {"status":"ok"}，不可用时返回 503 和 {"status":"unavailable"}。管理页面：

• GET /tasks：任务列表、搜索和状态筛选。
• GET /tasks/new：上传参考图并创建任务。
• GET /tasks/{id}：查看原始约束和任务状态；未执行任务立即取消，执行中请求安全停止。
• GET/POST /login、POST /logout：建立或撤销 8 小时 ADMIN 会话。

未登录管理页面会跳转 /login，未授权管理 API 返回 401。Cookie 认证的管理 API 写请求还需要 X-CSRF-Token。采购 App 使用 POST /api/v1/auth/token，ADMIN Cookie 与 BUYER Bearer token 不能互换。两类登录在凭证校验前按来源地址独立限流： 5 分钟最多 10 次，超限返回 429 和 Retry-After，成功后清零。

设备任务路由为 /api/v1/devices/heartbeat、/api/v1/tasks/claim-next 及 task-scoped reference-image/start/heartbeat/release/cancel-ack。除设备 heartbeat 外，任务读取 和迁移都受当前用户、设备、claim generation、X-Claim-Token 与服务端租约约束； 原 claim token 只由 App 生成和保存，服务端数据库只存 SHA-256。

start 和任务 heartbeat 显式返回 execution_expires_at。默认运行授权为 30 分钟， App 可每 30 秒 best-effort 滑动续期；过期后原设备 heartbeat 只同步状态且不延长 旧授权，并只接受 SAFE_STOPPED step；RUNNING/WAITING_CONFIRMATION 不自动 回队列。匹配原 execution/claim 的设备仍可确认已存在的管理取消请求。

默认 loopback 可使用 HTTP 开发。局域网监听必须同时设置 certificate/private key， 服务直接使用 TLS 启动，不会降级为明文。完整 API 合约见 ../docs/api.md。

仓库根目录的 generate-local-tls.ps1 -IPAddress <LAN-IP> 可为 Debug 联调生成 .local/cmroubao-tls/ 下的本地 CA 和带 IP SAN 的服务端证书；生成后 start-backend.bat 自动使用证书监听 0.0.0.0:8080。手机只安装 ca.crt，绝不 复制 ca.key 或 server.key。