## 背景与现状
- 技术栈：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。
- 单元测试：
  - 入库成功/去重冲突/字段截断
  - 多维筛选与分页
- 文档：在项目说明文档补充采集字段、接口规范与数据保留策略。