feat(auth): implement user and device authentication

backend-api/README.md

@@ -2,7 +2,7 @@
 
 Go 1.23.0、Gin 1.11.0 和 SQLite 构成的单进程采购任务服务。当前提供参考图上传与
 规范化、任务创建/列表/详情/取消 API、服务端渲染管理页面、健康检查和显式数据库
-迁移。T-204 正式管理登录完成前，除 `/healthz` 外的业务路由只接受 loopback 请求。
+迁移，并使用 ADMIN 服务端会话和 BUYER + 预授权设备联合身份隔离管理与执行接口。
 
 ## 环境
 
@@ -14,9 +14,11 @@ Go 1.23.0、Gin 1.11.0 和 SQLite 构成的单进程采购任务服务。当前
 
 | 变量 | 默认值 | 说明 |
 | --- | --- | --- |
-| `CMROUBAO_HTTP_ADDR` | `127.0.0.1:8080` | HTTP 监听地址；局域网监听必须显式配置 |
+| `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 监听必须设置 |
 
 不会自动读取 `.env`。本地配置和 `var/` 运行数据不得提交。
 
@@ -28,20 +30,44 @@ 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 = "至少 12 个 UTF-8 字节"
+go run ./cmd/authctl create-user ADMIN 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` 的密码只从 `CMROUBAO_AUTH_PASSWORD` 读取，不接受命令行密码。
+`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 会话。
 
-API 合约见 [`../docs/api.md`](../docs/api.md)。当前 loopback 门禁不是身份认证，不能
-通过修改监听地址把管理页面直接开放到局域网。
+未登录管理页面会跳转 `/login`，未授权管理 API 返回 `401`。Cookie 认证的管理 API
+写请求还需要 `X-CSRF-Token`。采购 App 使用 `POST /api/v1/auth/token`，ADMIN
+Cookie 与 BUYER Bearer token 不能互换。两类登录在凭证校验前按来源地址独立限流：
+5 分钟最多 10 次，超限返回 `429` 和 `Retry-After`，成功后清零。
+
+默认 loopback 可使用 HTTP 开发。局域网监听必须同时设置 certificate/private key，
+服务直接使用 TLS 启动，不会降级为明文。完整 API 合约见
+[`../docs/api.md`](../docs/api.md)。