feat: add device registration observation

docs/api.md

@@ -18,6 +18,7 @@
 - T-608 起新用户注册成功一次性赠送 **10 点**试用点数；赠点必须经计费层写入钱包和 `PointsLedger(change_type=signup_bonus)`，不得直接改余额字段。历史用户是否补发不属于默认注册流程。
 - API Key 库内只存 `key_hash`（SHA-256）与 `key_prefix`，明文只在创建时返回一次，不在 admin、日志或调用记录中回显。
 - 每次生成调用写 `CallRecord`；只允许保存 `result_ref` / `result_summary` 这类引用或摘要，不保存 provider `raw`、base64 图片或敏感上游字段。
+- T-624 起，蝦皮圈客户端可先用 API Key 登记设备并取得短期 `X-Device-Session`；设备会话仅用于设备心跳，尚**不**参与现有生成/余额接口鉴权、计费或授权拦截。设备标识、公钥和会话令牌不写入调用日志或响应中的设备对象。
 
 T-301 已实现对外 API 鉴权基线：`apps.api.authentication.ApiKeyAuthentication` 只解析 `Authorization: Bearer <API_KEY>`；生成、余额等外部 API 视图应继承 `apps.api.views.ExternalApiView`，不接受 Web session。
 
@@ -88,6 +89,9 @@ T-607/T-609/T-617 已实现 `GET /api/v1/client/releases/latest?platform=windows
 | `payment_order_create_failed` | 支付平台下单失败 | 502 |
 | `order_not_found` | 充值订单不存在或不属于当前用户 | 404 |
 | `rate_limited` | 请求过于频繁，请稍后再试 | 429 |
+| `device_session_invalid` | 缺失、无效或过期设备会话 | 401 |
+| `device_revoked` | 客户端设备已被吊销 | 403 |
+| `device_identity_mismatch` | 同一设备标识对应的安装公钥不一致 | 403 |
 
 `upstream_timeout` 与 `upstream_error` 都表示本次生成失败且已退点，客户端可按失败 / 重试处理。`upstream_timeout` 通常来自 T-612 的生图上游硬截止或底层 HTTP 超时。`upstream_error` 需要按错误消息继续区分：如果 `/api/v1/balance` 成功、`/api/v1/models` 中目标别名存在且 `pricing_status="priced"`，但生成接口返回 `502 upstream_error` 且消息为「上游模型配置不可用」，优先判定为**服务端上游模型运行配置问题**，不是客户端 payload 问题。常见原因是 `AI_KEY_ENCRYPTION_KEY` 与入库时不一致、`AiModel.api_key_encrypted` 无法解密、别名指向的 `AiModel` 缺 `url` / `model` / `api_type` / API Key，或 `api_type` 无可用 Provider。该错误路径不应最终扣点；修复按 [`deployment.md`](deployment.md) 的 AI 模型配置排查步骤执行。
 
@@ -144,6 +148,52 @@ GET /api/v1/client/releases/latest?platform=windows
 
 要点：接口只查 `DownloadRelease(platform, is_current=True)`；`download_url` 优先使用 `external_url`，否则用 `file.url` 生成绝对 HTTPS URL；`published_at` MVP 可使用 `DownloadRelease.updated_at`；`force_update` 使用后台发布版本上的布尔配置，默认 `false`；`size_bytes` 使用后台填写的安装包字节数，可为空以兼容历史记录。响应不得包含本地 `MEDIA_ROOT`、文件系统路径、后台 ID、`is_current`、用户信息、API Key、模型配置或任何密钥字段。成功和“暂未发布”均返回 HTTP 200，方便桌面端静默检查；非法平台返回 `400 bad_request`。无当前版本或当前版本没有下载地址时返回 `release:null`，不返回独立的 `force_update` / `size_bytes` 顶层字段。
 
+### `POST /api/v1/client/devices/register`
+
+蝦皮圈客户端登记当前安装实例并获取短期设备会话。该接口使用既有 API Key 鉴权，不接受 Web session；第一阶段只登记和观测，不影响已有生成接口。
+
+请求：
+
+```json
+{
+  "product_code": "cmshopee",
+  "device_id": "v1:client-generated-installation-id",
+  "device_id_version": "v1",
+  "installation_public_key": "client-installation-public-key",
+  "platform": "windows",
+  "client_version": "0.1.0"
+}
+```
+
+成功响应：
+
+```json
+{
+  "device": {
+    "product_code": "cmshopee",
+    "platform": "windows",
+    "client_version": "0.1.0",
+    "status": "active",
+    "first_seen_at": "2026-07-21T10:00:00+08:00",
+    "last_seen_at": "2026-07-21T10:00:00+08:00"
+  },
+  "device_session_token": "dvs_cmhub_<only-returned-on-this-registration>",
+  "expires_at": "2026-07-21T11:00:00+08:00"
+}
+```
+
+首次登记返回 `201`；同一用户、产品和设备重复登记保持同一设备记录、轮换会话令牌并返回 `200`。服务端对 `device_id_version + device_id` 加私有 pepper 后只保存 HMAC 摘要，对安装公钥只保存 SHA-256 摘要；不得上传 MachineGuid、MAC、硬盘序列号或私钥。`device_session_token` 只在本次响应返回，数据库只存 hash，客户端应使用 Windows DPAPI 等本地安全存储保护它。
+
+### `POST /api/v1/client/devices/heartbeat`
+
+刷新已登记设备的活跃观测。请求头：
+
+```http
+X-Device-Session: dvs_cmhub_<device_session_token>
+```
+
+成功响应返回当前设备公开摘要、会话到期时间和 `activity_updated`。默认同一设备至少间隔 24 小时才写入一次 `last_seen_at`，因此频繁心跳可能返回 `activity_updated=false`，这是正常行为。缺失、无效或过期会话返回 `401 device_session_invalid`；已吊销设备返回 `403 device_revoked`。该接口不扣点、不创建调用记录，也不刷新过期会话；客户端应重新调用登记接口获取新令牌。
+
 ### `POST /api/v1/generate/title`
 
 生成标题。请求：