127 lines
6.7 KiB
Markdown
127 lines
6.7 KiB
Markdown
# 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`。首次配置：
|
||
|
||
```powershell
|
||
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 和识别文字
|
||
不写入数据库、日志或浏览器。
|
||
|
||
## 命令
|
||
|
||
```powershell
|
||
$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`](../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`。
|