hi-server/.trae/documents/APP_PC 报错日志收集接口与表设计.md

背景与现状

• 技术栈：Go + gin 路由（internal/handler/routes.go）、GORM + MySQL（internal/svc/serviceContext.go）。
• 现有日志：系统统一写入 system_logs（internal/model/log/log.go），并通过 LogModel.FilterSystemLog 提供查询（internal/model/log/model.go）。管理端已存在日志查询路由（internal/handler/routes.go:188-236）。
• 新需求：新增专用表 log_message，用于 APP/PC/Web 客户端错误日志采集，避免与原有“消息发送/业务日志”混用（降低查询噪声、明确字段）。

SQL 表设计（MySQL）

• 表名：log_message
• 目的：采集终端错误与异常信息，便于筛选、定位、汇总。
• 字段：
  • id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY
  • platform VARCHAR(32) NOT NULL（如 android/ios/windows/mac/web）
  • app_version VARCHAR(32) NULL
  • os_name VARCHAR(32) NULL（如 Android、iOS、Windows、macOS）
  • os_version VARCHAR(32) NULL
  • device_id VARCHAR(64) NULL（设备唯一标识，便于去重/定位）
  • user_id BIGINT NULL DEFAULT NULL（关联已登录用户；匿名为空）
  • session_id VARCHAR(64) NULL（会话标识，便于定位）
  • level TINYINT UNSIGNED NOT NULL DEFAULT 3（1=fatal 2=error 3=warn 4=info）
  • error_code VARCHAR(64) NULL（业务/系统错误码）
  • message TEXT NOT NULL（错误简述）
  • stack MEDIUMTEXT NULL（堆栈）
  • context JSON NULL（扩展上下文，如接口路径、参数、网络状态等）
  • client_ip VARCHAR(45) NULL（由服务端按请求解析填充）
  • user_agent VARCHAR(255) NULL（Web/PC 端可用）
  • locale VARCHAR(16) NULL（如 zh-CN、en-US）
  • digest VARCHAR(64) NULL（去重指纹：message+stack+error_code+app_version+platform 的哈希）
  • occurred_at DATETIME NULL（客户端发生时间）
  • created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP（服务端入库时间）
• 索引：
  • idx_platform_time(platform, created_at)
  • idx_user_time(user_id, created_at)
  • idx_device_time(device_id, created_at)
  • idx_error_code(error_code)
  • uniq_digest(digest)（可选唯一，避免大量重复日志）
• 迁移：
  • 新增：initialize/migrate/database/02105_log_message.up.sql
  • 回滚：initialize/migrate/database/02105_log_message.down.sql
• DDL 示例：

CREATE TABLE `log_message` (
  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  `platform` VARCHAR(32) NOT NULL,
  `app_version` VARCHAR(32) NULL,
  `os_name` VARCHAR(32) NULL,
  `os_version` VARCHAR(32) NULL,
  `device_id` VARCHAR(64) NULL,
  `user_id` BIGINT NULL DEFAULT NULL,
  `session_id` VARCHAR(64) NULL,
  `level` TINYINT UNSIGNED NOT NULL DEFAULT 3,
  `error_code` VARCHAR(64) NULL,
  `message` TEXT NOT NULL,
  `stack` MEDIUMTEXT NULL,
  `context` JSON NULL,
  `client_ip` VARCHAR(45) NULL,
  `user_agent` VARCHAR(255) NULL,
  `locale` VARCHAR(16) NULL,
  `digest` VARCHAR(64) NULL,
  `occurred_at` DATETIME NULL,
  `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uniq_digest` (`digest`),
  KEY `idx_platform_time` (`platform`, `created_at`),
  KEY `idx_user_time` (`user_id`, `created_at`),
  KEY `idx_device_time` (`device_id`, `created_at`),
  KEY `idx_error_code` (`error_code`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

接口设计（采集）

• 路径：POST /v1/common/log/message/report
• 路由分组：/v1/common（复用 DeviceMiddleware，见 internal/handler/routes.go:625-655）
• 鉴权：可匿名；若已登录从上下文解析 user_id 注入。启用 IP/设备维度的限流（Redis），避免刷量。
• 请求体（JSON）：
  • platform string 必填
  • appVersion string 可选
  • osName string 可选
  • osVersion string 可选
  • deviceId string 可选
  • userId number 可选（客户端不可信，以服务端解析为准）
  • sessionId string 可选
  • level number 可选（默认 3）
  • errorCode string 可选
  • message string 必填
  • stack string 可选
  • context object 可选
  • occurredAt number 可选（毫秒时间戳）
• 返回（统一封装）：{ "code": 0, "msg": "OK", "data": { "id": 123 } }（参考 pkg/result/httpResult.go）
• 处理逻辑：
  • 从请求头解析 UA 与 IP 注入 client_ip、user_agent；校验字段长度与大小（如 stack 限制 1MB）。
  • 计算 digest（如 sha256(message|stack|errorCode|appVersion|platform)），若唯一索引冲突则返回已存在的 ID 或静默忽略（防重复）。
  • 使用 GORM 入库至 log_message。

接口设计（管理端查询）

• 列表：GET /v1/admin/log/message/error/list
  • 筛选：platform、level、userId、deviceId、errorCode、keyword（匹配 message/stack/context）、start/end（时间范围）
  • 分页：page、size
• 详情：GET /v1/admin/log/message/error/detail?id=...
• 路由分组：/v1/admin/log（与现有日志保持一致，见 internal/handler/routes.go:188-236）
• 返回：列表返回 total 与 list（含核心字段），详情返回全部字段。

数据模型与方法（GORM 设计）

• 目录：internal/model/logmessage/
• 结构：
  • type LogMessage struct { ... }（字段与上表对应，TableName() string { return "log_message" }）
• 接口：
  • Insert(ctx context.Context, data *LogMessage) error
  • Filter(ctx context.Context, params *FilterParams) ([]*LogMessage, int64, error)（支持多维筛选、分页、关键字模糊）
  • FindOne(ctx context.Context, id int64) (*LogMessage, error)
• 逻辑：仿照现有 internal/model/log/default.go 与 model.go 的模式（组合 defaultModel + customModel），保证代码一致性。

防护与合规

• 限流：按 device_id、client_ip 维度做分钟/小时限流（重用 Redis，internal/svc/serviceContext.go 已初始化）。
• 安全：
  • 敏感信息剔除（避免在 context/stack 中泄露密钥/密码）
  • 大字段截断与压缩策略（超限截断，或服务端配置开关）
• 隐私：遵循最小化原则，不采集不必要的 PII；user_id 仅在登录上下文中由服务端注入。

客户端上报示例

• 示例请求：

POST /v1/common/log/message/report
{
  "platform": "android",
  "appVersion": "1.2.3",
  "osName": "Android",
  "osVersion": "14",
  "deviceId": "a1b2c3",
  "level": 2,
  "errorCode": "NETWORK_TIMEOUT",
  "message": "请求超时：/api/order/list",
  "stack": "TimeoutException at...",
  "context": { "api": "/api/order/list", "retry": 1 },
  "occurredAt": 1733145600000
}

迁移与回滚

• 新增 02105_log_message.up.sql：创建表与索引。
• 回滚 02105_log_message.down.sql：DROP TABLE IF EXISTS log_message;

与现有日志体系的关系

• 管理端查询保持独立路由，避免与现有 message/list（邮件/短信发送日志）混淆（internal/handler/routes.go:207-213）。
• 可选加写 system_logs 一条摘要（Type 新增 TypeClientError），用于仪表盘总览；但核心数据以 log_message 为准。

后续实现要点

• 路由注册：/v1/common/log/message/report 与 /v1/admin/log/message/error/*。
• 校验与限流中间件：复用现有 DeviceMiddleware 与 Redis。
• 单元测试：
  • 入库成功/去重冲突/字段截断
  • 多维筛选与分页
• 文档：在项目说明文档补充采集字段、接口规范与数据保留策略。