feat: 实现邮箱验证码登录功能，支持新用户自动注册并记录登录日志
Build docker and publish / build (20.15.1) (push) Successful in 5m40s
Build docker and publish / build (20.15.1) (push) Successful in 5m40s
This commit is contained in:
@@ -1,151 +1,112 @@
|
||||
## 背景与现状
|
||||
- 技术栈：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`。
|
||||
* 仅实现 Go 后端 API；客户端（iOS/StoreKit 2）按说明调用。
|
||||
|
||||
## 接口设计（管理端查询）
|
||||
- 列表：`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`），保证代码一致性。
|
||||
* 非续期订阅：固定时长通行证（如 30/90/365 天），产品ID：`com.airport.vpn.pass.30d|90d|365d`。
|
||||
|
||||
## 防护与合规
|
||||
- 限流：按 `device_id`、`client_ip` 维度做分钟/小时限流（重用 Redis，internal/svc/serviceContext.go 已初始化）。
|
||||
- 安全：
|
||||
- 敏感信息剔除（避免在 `context`/`stack` 中泄露密钥/密码）
|
||||
- 大字段截断与压缩策略（超限截断，或服务端配置开关）
|
||||
- 隐私：遵循最小化原则，不采集不必要的 PII；`user_id` 仅在登录上下文中由服务端注入。
|
||||
* 非消耗型（可选）：一次性解锁某附加功能，产品ID：`com.airport.vpn.addon.xyz`。
|
||||
|
||||
## 客户端上报示例
|
||||
- 示例请求：
|
||||
```
|
||||
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
|
||||
}
|
||||
```
|
||||
* 服务器以 `productId→权益/时长` 进行配置映射。
|
||||
|
||||
## 迁移与回滚
|
||||
- 新增 `02105_log_message.up.sql`：创建表与索引。
|
||||
- 回滚 `02105_log_message.down.sql`：`DROP TABLE IF EXISTS log_message;`
|
||||
## 后端API设计（Go/Gin）
|
||||
|
||||
## 与现有日志体系的关系
|
||||
- 管理端查询保持独立路由，避免与现有 `message/list`（邮件/短信发送日志）混淆（internal/handler/routes.go:207-213）。
|
||||
- 可选加写 `system_logs` 一条摘要（`Type` 新增 `TypeClientError`），用于仪表盘总览；但核心数据以 `log_message` 为准。
|
||||
* 路由注册：`internal/handler/routes.go`
|
||||
|
||||
* `GET /api/iap/apple/products`：返回前端展示的产品清单（含总价/描述/时长映射）
|
||||
|
||||
* `POST /api/iap/apple/transactions/attach`：绑定一次购买到用户账户（需登录）。入参：`signedTransactionJWS`
|
||||
|
||||
* `POST /api/iap/apple/restore`：恢复购买（批量接收 JWS 列表并绑定）
|
||||
|
||||
* `GET /api/iap/apple/status`：返回用户当前权益与到期时间（统一来源聚合）
|
||||
|
||||
* 逻辑目录：`internal/logic/iap/apple/*`
|
||||
|
||||
* `AttachTransactionLogic`：解析 JWS→校验 `bundleId/productId/purchaseDate`→根据 `productId` 映射权益与时长→更新订阅统一表
|
||||
|
||||
* `RestoreLogic`：对所有已购记录执行绑定去重（基于 `original_transaction_id`）
|
||||
|
||||
* `QueryStatusLogic`：聚合各来源订阅，返回有效权益（取最近到期/最高等级）
|
||||
|
||||
* 工具包：`pkg/iap/apple`
|
||||
|
||||
* `ParseTransactionJWS`：解析 JWS，提取 `transactionId/originalTransactionId/productId/purchaseDate/revocationDate`
|
||||
|
||||
* `VerifyBasic`：基础校验（`bundleId`、签名头部与证书链存在性）；如客户端已 `transaction.verify()`，可采用“信任+服务器最小校验”的模式快速落地
|
||||
|
||||
* 配置：`doc/config-zh.md`
|
||||
|
||||
* `IAP_PRODUCT_MAP`：`productId → tier/duration`（例如：`30d→+30天`、`addon→解锁功能X`）
|
||||
|
||||
* `APPLE_IAP_BUNDLE_ID`：用于 JWS 内部校验
|
||||
|
||||
## 数据模型
|
||||
|
||||
* 新表：`apple_iap_transactions`
|
||||
|
||||
* `id`、`user_id`、`original_transaction_id`（唯一）、`transaction_id`、`product_id`、`purchase_at`、`revocation_at`、`jws_hash`
|
||||
|
||||
* 统一订阅表增强（现有 `SubscribeModel`）
|
||||
|
||||
* 新增来源：`source=apple_iap`、`external_id=original_transaction_id`、`tier`、`expires_at`
|
||||
|
||||
* 索引：`original_transaction_id` 唯一、`user_id+source`、`expires_at`
|
||||
|
||||
## 与现有系统融合
|
||||
|
||||
* `internal/svc/serviceContext.go`：初始化 IAP 模块与模型
|
||||
|
||||
* `QueryPurchaseOrderLogic/SubscribeModel`：聚合苹果IAP来源；冲突策略：按最高权益与最晚到期。
|
||||
|
||||
* 不产生命令行支付订单，仅记录订阅流水与审计（避免与 Stripe 等混淆）。
|
||||
|
||||
## 安全与合规
|
||||
|
||||
* 仅显示商店在可支付时；价格、描述清晰；使用系统确认表单。
|
||||
|
||||
* 服务器进行最小校验：`bundleId`、`productId`白名单、`purchaseDate`有效性；保存 `jws_hash` 做去重。
|
||||
|
||||
* 退款：在 App 内提供“请求退款”的帮助页并使用系统接口触发；后端无需额外API。
|
||||
|
||||
## 客户端使用说明（StoreKit 2）
|
||||
|
||||
* 产品拉取与展示：
|
||||
|
||||
* 通过已知 `productId` 列表调用 `Product.products(for:)`；展示总价与描述，检查 `canMakePayments`
|
||||
|
||||
* 购买：
|
||||
|
||||
* 调用 `purchase()`，系统确认表单弹出→返回 `Transaction`；执行 `await transaction.verify()`
|
||||
|
||||
* 成功后将 `transaction.signedData` POST 到 `/api/iap/apple/transactions/attach`
|
||||
|
||||
* 恢复：
|
||||
|
||||
* 调用 `Transaction.currentEntitlements`，遍历并验证每条 `Transaction`，将其 `signedData` 批量 POST 到 `/api/iap/apple/restore`
|
||||
|
||||
* 状态显示：
|
||||
|
||||
* 访问 `GET /api/iap/apple/status` 获取到期时间与权益用于 UI 展示
|
||||
|
||||
* 退款入口：
|
||||
|
||||
* 在购买帮助页直接使用 `beginRefundRequest(for:in:)`；文案简洁，按钮直达
|
||||
|
||||
## 测试与验收
|
||||
|
||||
* 单元测试：JWS 解析、`productId→权益/时长` 映射、去重策略。
|
||||
|
||||
* 集成测试：绑定/恢复接口鉴权与幂等、统一订阅查询结果。
|
||||
|
||||
* 沙盒：使用 iOS 沙盒购买与恢复；记录审计与日志。
|
||||
|
||||
## 里程碑
|
||||
|
||||
1. 基础能力：`products/status` 与 `transactions/attach` 落地
|
||||
2. 恢复与融合：`restore` + 统一订阅聚合
|
||||
3. 上线前验证：沙盒测试与文案、监控
|
||||
|
||||
## 后续实现要点
|
||||
- 路由注册：`/v1/common/log/message/report` 与 `/v1/admin/log/message/error/*`。
|
||||
- 校验与限流中间件：复用现有 `DeviceMiddleware` 与 Redis。
|
||||
- 单元测试：
|
||||
- 入库成功/去重冲突/字段截断
|
||||
- 多维筛选与分页
|
||||
- 文档：在项目说明文档补充采集字段、接口规范与数据保留策略。
|
||||
Reference in New Issue
Block a user