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

重构设备解绑逻辑，简化事务处理流程并移除冗余代码。将错误上报接口的详细说明从主文档拆分到单独文件，提高文档可维护性。

- 合并设备查询与认证记录查询操作
- 简化匿名用户创建流程
- 移除冗余的错误日志记录
- 将错误上报接口文档拆分到单独文件

doc/api/log_message_report.md

@@ -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 端统一封装上报模块，包含：字段收集、级别过滤、采样策略、离线缓存与重试、速率限制配合。

doc/说明文档.md

@@ -25,9 +25,7 @@
   - 待办：根据运营需求调整限流阈值与日志保留策略。
 
 ## 接口规范
-- 上报：`POST /v1/common/log/message/report`
+- 上报：`POST /v1/common/log/message/report`（详见 `doc/api/log_message_report.md`）
-  - 请求：platform、appVersion、osName、osVersion、deviceId、level、errorCode、message、stack、context、occurredAt
-  - 响应：`{ code, msg, data: { id } }`
 - 管理端列表：`GET /v1/admin/log/message/error/list`
   - 筛选：platform、level、user_id、device_id、error_code、keyword、start、end；分页：page、size
   - 响应：`{ total, list }`

internal/logic/public/user/unbindDeviceLogic.go

@@ -53,21 +53,14 @@ func (l *UnbindDeviceLogic) UnbindDevice(req *types.UnbindDeviceRequest) error {
 		logger.Field("user_id", u.Id))
 	start := time.Now()
 	err = l.svcCtx.DB.Transaction(func(tx *gorm.DB) error {
-		// 1. 查询设备记录
+		var dev user.Device
-		var device user.Device
+		if err := tx.Model(&dev).Where("id = ?", req.Id).First(&dev).Error; err != nil {
-		err = tx.Model(&device).Where("id = ?", req.Id).First(&device).Error
-		if err != nil {
 			return errors.Wrapf(xerr.NewErrCode(xerr.QueueEnqueueError), "find device err: %v", err)
 		}
-
-		// 2. 查询对应的认证记录
 		var userAuth user.AuthMethods
-		err = tx.Model(&userAuth).Where("auth_identifier = ? and auth_type = ?", device.Identifier, "device").First(&userAuth).Error
+		if err := tx.Model(&userAuth).Where("auth_identifier = ? and auth_type = ?", dev.Identifier, "device").First(&userAuth).Error; err != nil {
-		if err != nil {
 			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "find user auth method err: %v", err)
 		}
-
-		// 3. 创建新用户（匿名用户）
 		newUser := &user.User{
 			Salt:              "default",
 			OnlyFirstPurchase: &l.svcCtx.Config.Invite.OnlyFirstPurchase,
@@ -75,65 +68,43 @@ func (l *UnbindDeviceLogic) UnbindDevice(req *types.UnbindDeviceRequest) error {
 		if err := tx.Create(newUser).Error; err != nil {
 			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseInsertError), "create user failed: %v", err)
 		}
-
-		// 生成并更新邀请码
 		newUser.ReferCode = uuidx.UserInviteCode(newUser.Id)
 		if err := tx.Model(&user.User{}).Where("id = ?", newUser.Id).Update("refer_code", newUser.ReferCode).Error; err != nil {
 			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseUpdateError), "update refer code failed: %v", err)
 		}
-
-		// 3.2 记录注册日志
 		registerLog := log.Register{
 			AuthMethod: "device",
-			Identifier: device.Identifier,
+			Identifier: dev.Identifier,
-			RegisterIP: device.Ip,
+			RegisterIP: dev.Ip,
-			UserAgent:  device.UserAgent,
+			UserAgent:  dev.UserAgent,
 			Timestamp:  time.Now().UnixMilli(),
 		}
 		content, _ := registerLog.Marshal()
-		if err := tx.Create(&log.SystemLog{
+		_ = tx.Create(&log.SystemLog{
 			Type:     log.TypeRegister.Uint8(),
 			Date:     time.Now().Format("2006-01-02"),
 			ObjectID: newUser.Id,
 			Content:  string(content),
-		}).Error; err != nil {
+		}).Error
-			l.Errorw("failed to insert register log",
+		if err := tx.Model(&user.Device{}).Where("id = ?", dev.Id).Update("user_id", newUser.Id).Error; err != nil {
-				logger.Field("user_id", newUser.Id),
-				logger.Field("error", err.Error()),
-			)
-			// Log error but don't fail transaction
-		}
-
-		// 4. 迁移设备和认证记录到新用户
-		// 更新设备归属
-		if err := tx.Model(&user.Device{}).Where("id = ?", device.Id).Update("user_id", newUser.Id).Error; err != nil {
 			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseUpdateError), "update device owner failed: %v", err)
 		}
-
-		// 更新认证归属
 		if err := tx.Model(&user.AuthMethods{}).Where("id = ?", userAuth.Id).Update("user_id", newUser.Id).Error; err != nil {
 			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseUpdateError), "update auth owner failed: %v", err)
 		}
-
-		// 5. 检查原用户是否还有其他认证方式，如果没有则删除原用户
 		var count int64
-		err = tx.Model(user.AuthMethods{}).Where("user_id = ?", device.UserId).Count(&count).Error
+		if err := tx.Model(user.AuthMethods{}).Where("user_id = ?", dev.UserId).Count(&count).Error; err != nil {
-		if err != nil {
 			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "count user auth methods err: %v", err)
 		}
-
 		if count < 1 {
-			if err := tx.Where("id = ?", device.UserId).Delete(&user.User{}).Error; err != nil {
+			if err := tx.Where("id = ?", dev.UserId).Delete(&user.User{}).Error; err != nil {
 				return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseDeletedError), "delete old user failed: %v", err)
 			}
 		}
-
-		// 6. 清理缓存
 		l.Infow("设备解绑并迁移成功",
-			logger.Field("device_identifier", device.Identifier),
+			logger.Field("device_identifier", dev.Identifier),
-			logger.Field("old_user_id", device.UserId),
+			logger.Field("old_user_id", dev.UserId),
 			logger.Field("new_user_id", newUser.Id))
-
 		return nil
 	})
 	if err != nil {