refactor(用户): 优化设备解绑逻辑并提取错误上报接口文档

重构设备解绑逻辑，简化事务处理流程并移除冗余代码。将错误上报接口的详细说明从主文档拆分到单独文件，提高文档可维护性。 - 合并设备查询与认证记录查询操作 - 简化匿名用户创建流程 - 移除冗余的错误日志记录 - 将错误上报接口文档拆分到单独文件
2025-12-03 01:45:06 -08:00
parent f0439f4f80
commit 4b6fcb338e
3 changed files with 115 additions and 45 deletions
@@ -0,0 +1,101 @@
+# 客户端错误上报接口文档
+
+## 接口概览
+- 路径：`POST /v1/common/log/message/report`
+- 说明：APP/PC/Web 客户端错误与异常信息上报，服务端入库 `log_message` 表，并提供管理端查询。
+- 认证：无需登录；若走设备安全通道需使用 `Login-Type: device` 与 AES 加密。
+- 中间件：`DeviceMiddleware`（当请求头 `Login-Type=device` 时启用加解密）。
+
+## 请求
+- Headers：
+  - `Content-Type: application/json`
+  - 可选：`Login-Type: device`（启用设备加密通道）
+- Body（JSON）：
+  - `platform` string 必填，客户端平台，如 `android`/`ios`/`windows`/`mac`/`web`
+  - `appVersion` string 可选，应用版本，如 `2.4.1`
+  - `osName` string 可选，系统名称，如 `Android`/`iOS`/`Windows`/`macOS`
+  - `osVersion` string 可选，系统版本，如 `14`
+  - `deviceId` string 可选，设备唯一标识
+  - `sessionId` string 可选，会话标识
+  - `level` uint8 可选，日志等级：`1=fatal`、`2=error`、`3=warn`、`4=info`（默认 `3`）
+  - `errorCode` string 可选，业务或系统错误码
+  - `message` string 必填，错误简述（服务器将超过约 64KB 的内容截断）
+  - `stack` string 可选，堆栈信息（服务器将超过约 1MB 的内容截断）
+  - `context` object 可选，扩展上下文（如接口路径、参数、网络状态等）
+  - `occurredAt` int64 可选，客户端发生时间，毫秒时间戳
+
+- 服务器侧自动填充：
+  - `client_ip`、`user_agent`、`locale` 由请求解析
+  - `user_id` 仅在鉴权后由服务端注入（本接口默认匿名）
+
+## 加密通道（设备）
+- 当使用设备安全通道时（`Login-Type: device`），请求体需要将原始 JSON 加密为：
+  - `data` string：AES 加密后的密文
+  - `time` string：IV/nonce（与密文配套）
+- 服务端会自动解密为明文 JSON，再进行字段校验与入库。
+
+## 响应
+- 成功：
+```
+{
+  "code": 0,
+  "msg": "OK",
+  "data": { "id": 123 }
+}
+```
+- 常见错误：
+  - `{"code":401,"msg":"TooManyRequests"}` 触发速率限制（设备ID或IP维度）
+  - `{"code":400,"msg":"InvalidParams"}` 参数校验失败（缺少必填或类型不符）
+  - `{"code":10001,"msg":"DatabaseQueryError"}` 数据库操作异常
+
+## 速率限制
+- 默认按 `deviceId` 或 `client_ip` 每分钟最多约 `120` 条，超限即返回 `TooManyRequests`。
+
+## 去重策略
+- 服务端计算 `digest = sha256(message|stack|errorCode|appVersion|platform)` 并尝试唯一入库，重复日志可能返回已存在记录的 `id`。
+
+## 示例
+- 明文上报（推荐测试使用）：
+```
+curl -X POST http://localhost:8080/v1/common/log/message/report \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "platform": "android",
+    "appVersion": "2.4.1",
+    "osName": "Android",
+    "osVersion": "14",
+    "deviceId": "and-9a7f3e2c-01",
+    "sessionId": "sess-73f8a2a4",
+    "level": 2,
+    "errorCode": "ORDER_RENEWAL_TIMEOUT",
+    "message": "订单续费接口超时：/v1/public/order/renewal",
+    "stack": "TimeoutException: request exceeded 8000ms\\n at HttpClient.post(HttpClient.kt:214)\\n at RenewalRepository.submit(RenewalRepository.kt:87)",
+    "context": {
+      "api": "/v1/public/order/renewal",
+      "method": "POST",
+      "endpoint": "https://api.example.com/v1/public/order/renewal",
+      "httpStatus": 504,
+      "responseTimeMs": 8123,
+      "retryCount": 2,
+      "network": { "type": "cellular", "carrier": "China Mobile" }
+    },
+    "occurredAt": 1733200005123
+  }'
+```
+
+- 设备加密上报（示意）：
+```
+# 将原始JSON通过AES加密得到密文data与随机IV time
+curl -X POST http://localhost:8080/v1/common/log/message/report \
+  -H 'Content-Type: application/json' \
+  -H 'Login-Type: device' \
+  -d '{"data":"<aes_cipher>","time":"<iv_nonce>"}'
+```
+
+## 管理端查询（用于联调验证）
+- 列表：`GET /v1/admin/log/message/error/list`（需 `Authorization`）
+- 详情：`GET /v1/admin/log/message/error/detail?id=...`
+
+## 备注
+- 字段尽量避免携带敏感信息（密码、密钥、完整令牌等）；如需调试请截断或脱敏后上报。
+- 建议在 APP/PC 端统一封装上报模块，包含：字段收集、级别过滤、采样策略、离线缓存与重试、速率限制配合。