feat: add image route usage telemetry

docs/api.md

@@ -25,6 +25,8 @@ T-302 已实现生成接口基线：`POST /api/v1/generate/title` 与 `POST /api
 
 T-614 已实现生图异步任务化：`POST /api/v1/generate/image/tasks` 返回 `202` 与公开 UUID `task_id`，`GET /api/v1/generate/image/tasks/{task_id}` 轮询任务状态和结果。任务表 `ImageGenerationTask` 关联 `user`、`api_key` 与已预扣 `CallRecord`，支持 `Idempotency-Key` 去重、payload 冲突 `409 idempotency_conflict`、租约 / 心跳 / reaper 处理僵尸 running 任务并幂等退点。异步结果 URL 由 `MEDIA_PUBLIC_BASE_URL` 或 `PUBLIC_BASE_URL` 生成，不透传上游临时链接。
 
+T-615 已实现生图接口用量遥测：旧同步 `POST /api/v1/generate/image` 与新异步提交 `POST /api/v1/generate/image/tasks` 都会写 `cmhub.api.generation_usage` 结构化日志，事件名 `generation_route_usage`。调用方可选带 `X-Client-Version` 请求头，便于按客户端版本观察旧同步路迁移进度；该请求头不参与鉴权、计费或幂等判断。日志只记录 route/user/key 前缀/客户端版本/别名/状态/耗时/错误码等白名单字段，不记录 API Key 明文、prompt、图片 base64 或 provider raw。
+
 T-303 已实现余额查询基线：`GET /api/v1/balance` 已接入 API Key 鉴权，返回当前 `UserWallet.points_balance`，并保留旧字段同时新增不含邮箱的 `account` 账号展示对象；测试覆盖响应余额与 `PointsLedger.points_delta` 累加值一致的账务场景，并确认 Web session 不能调用该外部接口。
 
 T-601 已实现可用别名发现：`GET /api/v1/models` 已接入 API Key 鉴权，只返回当前 active 且具备对应能力的公开别名、能力、是否需要原图和点数单价；接口不调用 `AiModel.to_resolved_model()`，不解密 provider key，不返回底层 SKU、模型 URL、`api_key_encrypted`、`extra_body` 等内部配置，且成功请求不占用生成接口限流额度。
@@ -172,6 +174,14 @@ GET /api/v1/client/releases/latest?platform=windows
 
 生成图片（同步等待）。请求：
 
+可选请求头：
+
+```http
+X-Client-Version: 0.1.1
+```
+
+该字段仅用于 T-615 的用量遥测，帮助服务端区分旧同步接口由哪些客户端版本调用；不影响响应结构。
+
 ```json
 {
   "prompt": "把这件衣服换成模特上身的穿搭图",
@@ -208,6 +218,7 @@ GET /api/v1/client/releases/latest?platform=windows
 POST /api/v1/generate/image/tasks
 Authorization: Bearer sk_cmhub_xxx
 Idempotency-Key: desktop-job-20260708-0001
+X-Client-Version: 0.1.1
 Content-Type: application/json
 ```