feat: 轮询系统重构(分片队列 + 停复机统一 + Handler 拆分)
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m46s
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m46s
【核心变更】
1. 停复机逻辑统一(StopResumeService)
- 新增 EvaluateAndAct 统一入口,封装三条件停复机判断
- 停机条件:无套餐(no_package) / 流量耗尽(traffic_exhausted) / 未实名(not_realname)
- 复机条件:stop_reason 合规 + 有套餐且未耗尽 + 已实名或行业卡
- 修复设备套餐 Bug:hasValidPackage 按 device_id 查套餐,而非仅 iot_card_id
- 设备维度停复机加幂等锁(Redis SetNX,TTL 30s),防止多卡并发重复调 Gateway
2. Redis 分片队列(PollingQueueManager)
- 新建 queue_manager.go,封装所有轮询 Redis 操作
- 16 分片 Sorted Set,Key 格式:polling:shard:{shardID}:queue:{taskType}
- Lua 脚本原子出队(ZRANGEBYSCORE + 分批 ZREM),消除竞态窗口
- 新增背压检测:队列深度超 50 万时 Scheduler 跳过该分片
- RemoveFromAllQueues 覆盖 4 种任务类型(含 protect)
3. Handler 拆分(polling_handler.go 1360行 → 5个专注文件)
- polling_base.go:共享基类(并发控制/卡缓存/重入队)
- polling_realname_handler.go:实名采集,实名 0→1 时立即触发复机
- polling_carddata_handler.go:流量采集,保留跨月边界检测逻辑
- polling_package_handler.go:套餐采集,委托 EvaluateAndAct 决策
- polling_protect_handler.go:保护期一致性检查,保护期内强制修正
4. 配置管理(PollingConfigManager)
- 新建 config_manager.go,从 scheduler.go 提取配置职责
- 内存缓存 + 5 分钟定时刷新,刷新失败保留原缓存
- 修复 getCardCondition:停机卡返回 suspended,不再错配 activated 配置
5. 渐进式初始化(CardInitializer)
- 新建 initializer.go,分批加载(每批 10 万),批次间 sleep 500ms
- 过滤 enable_polling=false 的卡,初始化完成前 Scheduler 不出队
6. 卡生命周期服务(PollingLifecycleService)
- 新建 lifecycle_service.go,替代已删除的 callbacks.go 和 api_callback.go
- OnCardCreated/OnCardEnabled/OnCardStatusChanged 入队前检查 enable_polling
7. Scheduler 精简(1000+行 → 227行)
- 保留纯调度循环:scheduleLoop + processShardSchedule + enqueueBatch
- 保留每 10 秒触发套餐过期检测和流量重置
- 移除所有 DB 操作、配置加载、卡初始化逻辑
8. 轮询管控 API(enable_polling)
- 新增 PUT /api/admin/assets/:id/polling-status 接口
- 支持对设备/卡维度开关轮询,关闭后从所有分片队列移除
9. 数据库迁移
- 000103:tb_device 新增 enable_polling 字段(boolean, NOT NULL, DEFAULT true)
- 000104:新增 suspended 轮询配置,为 activated 配置补全 protect_check_interval
【文件统计】
- 新增:19 个文件(handler × 5、polling 组件 × 4、迁移 × 3 等)
- 修改:20 个文件(bootstrap 注入、store 接口、monitoring 适配分片等)
- 删除:3 个文件(polling_handler.go、callbacks.go、api_callback.go)
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
436
AGENTS.md
436
AGENTS.md
@@ -18,36 +18,8 @@
|
||||
| 数据库迁移 | `db-migration` | 迁移命令、文件规范、执行流程、失败处理 |
|
||||
| 维护规范文档 | `doc-management` | 规范文档流程和维护规则 |
|
||||
| 调试 bug / 排查异常 | `systematic-debugging` | 四阶段根因分析流程、逐层诊断、场景速查表 |
|
||||
| 涉及业务逻辑的开发/修改 | `kb-sync` | 开发前查阅知识库、开发后更新知识库、业务决策记录 |
|
||||
| 编写接口测试 / Hurl 测试 | `hurl-test` | 四阶段交互式生成 .hurl 测试文件(探索→确认→生成→验证),DTO 驱动的字段完整性断言 |
|
||||
|
||||
---
|
||||
|
||||
## 知识库规范(强制执行)
|
||||
|
||||
本项目的业务知识库在 Obsidian vault **「长沙鑫精」** 中,通过 `obsidian` CLI 访问。
|
||||
|
||||
**必须遵守:**
|
||||
|
||||
- 任何涉及业务逻辑的开发前,必须通过 `obsidian vault="长沙鑫精" search/read` 查阅知识库对应模块
|
||||
- 业务逻辑变更完成后,必须更新知识库中受影响的模块文档
|
||||
- 涉及业务决策变更时(为什么从 A 改成 B),必须在对应模块追加决策记录
|
||||
- 新增业务模块时,必须在知识库中创建对应文档
|
||||
|
||||
**禁止:**
|
||||
|
||||
- ❌ 不查阅知识库就开始开发业务功能
|
||||
- ❌ 改了业务逻辑但不更新知识库
|
||||
- ❌ 涉及业务决策变更但不记录原因
|
||||
|
||||
**知识库结构:**
|
||||
|
||||
| 文件夹 | 内容 |
|
||||
|--------|------|
|
||||
| `卡管业务整理/` | 正确的业务流程文档(流程图 + 接口字段速查 + 决策记录) |
|
||||
| `修正业务/` | 已知问题和修复方案 |
|
||||
|
||||
**详细操作规范**:加载 `kb-sync` Skill
|
||||
| 编写 Go 代码注释/文档注释 | `comment-standards` | 包/结构体/接口/函数/内联注释完整规范与示例 |
|
||||
| 创建涉及接口的 OpenSpec 提案 | `openspec-api-contract` | 探索阶段引导清单、提案必填章节与完成标准 |
|
||||
|
||||
---
|
||||
|
||||
@@ -143,150 +115,13 @@ Handler → Service → Store → Model
|
||||
|
||||
### 注释规范
|
||||
|
||||
#### 基本原则
|
||||
- **所有注释使用中文**,导出符号必须有文档注释(包、函数、类型、接口、常量)
|
||||
- 复杂逻辑解释"为什么"而非"做了什么",禁止废话注释(复述代码本身)
|
||||
- Handler 方法注释必须包含 HTTP 方法和路径(`// Create 创建账号` + `// POST /api/admin/accounts`)
|
||||
- 未导出函数:< 15 行可省略,≥ 15 行或非显而易见算法必须注释
|
||||
- 修改代码时必须同步更新注释,过时注释比没有注释更有害
|
||||
|
||||
- **所有注释使用中文**(与语言要求一致)
|
||||
- **导出符号必须有文档注释**(包、函数、方法、类型、接口、常量、变量)
|
||||
- **复杂逻辑必须有实现注释**(解释"为什么",而不是"做了什么")
|
||||
- **禁止废话注释**(不要用注释复述代码本身)
|
||||
- **修改代码时必须同步更新注释**(过时的注释比没有注释更有害)
|
||||
|
||||
#### 包注释
|
||||
|
||||
每个包的入口文件(通常是主文件或 `doc.go`)必须有包注释:
|
||||
|
||||
```go
|
||||
// Package account 提供账号管理的业务逻辑服务
|
||||
// 包含账号创建、修改、删除、权限分配等功能
|
||||
package account
|
||||
```
|
||||
|
||||
#### 结构体注释
|
||||
|
||||
所有导出结构体必须有文档注释,说明该结构体代表什么:
|
||||
|
||||
```go
|
||||
// Service 账号业务服务
|
||||
// 负责账号的 CRUD、角色分配、密码管理等业务逻辑
|
||||
type Service struct {
|
||||
store *Store
|
||||
auditService AuditServiceInterface
|
||||
}
|
||||
```
|
||||
|
||||
#### 接口注释
|
||||
|
||||
导出接口必须注释接口用途,每个方法必须说明契约:
|
||||
|
||||
```go
|
||||
// PermissionChecker 权限检查器接口
|
||||
// 用于查询用户的权限列表
|
||||
type PermissionChecker interface {
|
||||
// CheckPermission 检查用户是否拥有指定权限
|
||||
// userID: 用户ID
|
||||
// permCode: 权限编码(格式: module:action)
|
||||
// platform: 端口类型 (all/web/h5)
|
||||
CheckPermission(ctx context.Context, userID uint, permCode string, platform string) (bool, error)
|
||||
}
|
||||
```
|
||||
|
||||
#### 函数和方法注释
|
||||
|
||||
导出函数/方法必须以函数名开头,说明功能:
|
||||
|
||||
```go
|
||||
// Create 创建账号
|
||||
// POST /api/admin/accounts
|
||||
func (h *AccountHandler) Create(c *fiber.Ctx) error {
|
||||
```
|
||||
|
||||
**复杂方法**(超过 30 行或包含复杂业务逻辑)必须额外说明实现思路:
|
||||
|
||||
```go
|
||||
// ActivateByRealname 首次实名激活套餐
|
||||
// 当用户完成实名认证后,自动激活处于"囤货待实名"状态的套餐:
|
||||
// 1. 查找该卡所有 status=3(待实名激活)的套餐
|
||||
// 2. 按创建时间排序,第一个主套餐立即激活(status=1)
|
||||
// 3. 其余主套餐进入排队状态(status=4)
|
||||
// 4. 加油包如果绑定了已激活的主套餐则一并激活
|
||||
func (s *UsageService) ActivateByRealname(ctx context.Context, cardID uint) error {
|
||||
```
|
||||
|
||||
#### 未导出符号的注释
|
||||
|
||||
未导出(小写)的函数/方法:
|
||||
|
||||
- **简单逻辑**(< 15 行):可以不加注释
|
||||
- **复杂逻辑**(≥ 15 行)或 **非显而易见的算法**:必须加注释
|
||||
|
||||
```go
|
||||
// buildPermissionTree 递归构建权限树
|
||||
// 采用 map 索引 + 单次遍历算法,时间复杂度 O(n)
|
||||
func (s *Service) buildPermissionTree(permissions []*model.Permission) []*dto.PermissionTreeNode {
|
||||
```
|
||||
|
||||
#### 内联注释(实现逻辑注释)
|
||||
|
||||
以下场景**必须**添加内联注释:
|
||||
|
||||
| 场景 | 要求 |
|
||||
|------|------|
|
||||
| 复杂条件判断 | 解释判断的业务含义 |
|
||||
| 多步骤业务流程 | 用编号注释标明每一步 |
|
||||
| 非显而易见的设计决策 | 解释"为什么这样做"而不是"做了什么" |
|
||||
| 缓存/事务/并发处理 | 说明策略和原因 |
|
||||
| 临时方案/兼容逻辑 | 标注 TODO 或说明背景 |
|
||||
|
||||
**✅ 好的内联注释(解释为什么)**:
|
||||
|
||||
```go
|
||||
// 使用 Redis 分布式锁防止并发重复创建,锁超时 10 秒
|
||||
if !s.acquireLock(ctx, lockKey, 10*time.Second) {
|
||||
return errors.New(errors.CodeTooManyRequests, "操作过于频繁,请稍后重试")
|
||||
}
|
||||
|
||||
// 先冻结佣金再扣款,保证资金安全(失败时佣金自动解冻)
|
||||
if err := s.freezeCommission(ctx, tx, orderID); err != nil {
|
||||
return err
|
||||
}
|
||||
```
|
||||
|
||||
**❌ 废话注释(禁止)**:
|
||||
|
||||
```go
|
||||
// 获取用户ID ← 禁止:代码本身已经很清楚
|
||||
userID := middleware.GetUserIDFromContext(ctx)
|
||||
|
||||
// 创建账号 ← 禁止:变量名已说明意图
|
||||
account := &model.Account{}
|
||||
|
||||
// 返回错误 ← 禁止:return err 不需要注释
|
||||
return err
|
||||
```
|
||||
|
||||
#### 常量和枚举注释
|
||||
|
||||
分组常量必须有组注释,每个值必须有行内注释:
|
||||
|
||||
```go
|
||||
// 用户类型常量
|
||||
const (
|
||||
UserTypeSuperAdmin = 1 // 超级管理员
|
||||
UserTypePlatform = 2 // 平台用户
|
||||
UserTypeAgent = 3 // 代理账号
|
||||
UserTypeEnterprise = 4 // 企业账号
|
||||
)
|
||||
```
|
||||
|
||||
#### Handler 层特殊要求
|
||||
|
||||
Handler 方法的注释必须包含 HTTP 方法和路径:
|
||||
|
||||
```go
|
||||
// Create 创建账号
|
||||
// POST /api/admin/accounts
|
||||
func (h *AccountHandler) Create(c *fiber.Ctx) error {
|
||||
```
|
||||
**详细规范与示例**:见 `comment-standards` skill
|
||||
|
||||
### Go 代码风格
|
||||
|
||||
@@ -324,35 +159,9 @@ func (h *AccountHandler) Create(c *fiber.Ctx) error {
|
||||
|
||||
## ⚠️ 测试禁令(强制执行)
|
||||
|
||||
**本项目不使用任何形式的自动化测试代码。**
|
||||
|
||||
**绝对禁止:**
|
||||
|
||||
- ❌ **禁止编写单元测试** - 无论任何场景
|
||||
- ❌ **禁止编写集成测试** - 无论任何场景
|
||||
- ❌ **禁止编写验收测试** - 无论任何场景
|
||||
- ❌ **禁止编写流程测试** - 无论任何场景
|
||||
- ❌ **禁止编写 E2E 测试** - 无论任何场景
|
||||
- ❌ **禁止创建 `*_test.go` 文件** - 除非用户明确要求
|
||||
- ❌ **禁止在任务中包含测试相关工作** - 规划和实现均不涉及测试
|
||||
- ❌ **禁止在文档中提及测试要求** - 规范、设计文档均不讨论测试
|
||||
|
||||
**唯一例外:**
|
||||
|
||||
- ✅ **仅当用户明确要求**时才编写测试代码
|
||||
- ✅ 用户必须主动说明"请写测试"或"需要测试"
|
||||
|
||||
**原因说明:**
|
||||
|
||||
- 业务系统的正确性通过人工验证和生产环境监控保证
|
||||
- 测试代码的维护成本高于价值
|
||||
- 快速迭代优先于测试覆盖率
|
||||
|
||||
**替代方案:**
|
||||
|
||||
- 使用 PostgreSQL MCP 工具手动验证数据
|
||||
- 使用 Postman/curl 手动测试 API
|
||||
- 依赖生产环境日志和监控发现问题
|
||||
**本项目禁止任何形式的自动化测试**(单元/集成/E2E/`*_test.go` 文件),规划和文档中也不讨论测试。
|
||||
**唯一例外**:用户明确说"请写测试"时。
|
||||
**替代验证**:PostgreSQL MCP 手动验证数据、Postman/curl 手动测试 API。
|
||||
|
||||
## 性能要求
|
||||
|
||||
@@ -427,148 +236,30 @@ func (h *AccountHandler) Create(c *fiber.Ctx) error {
|
||||
|
||||
### 越权防护规范
|
||||
|
||||
**适用场景**:任何涉及跨用户、跨店铺、跨企业的资源访问
|
||||
**三层防护机制**(基础设施已就绪,无需自建):
|
||||
1. **路由层中间件**:粗粒度拦截(如企业账号禁止访问账号管理)
|
||||
2. **Service 层业务检查**:`middleware.CanManageShop()` / `middleware.CanManageEnterprise()` 细粒度验证;示例见 `internal/service/account/service.go`
|
||||
3. **GORM Callback 自动过滤**:代理按店铺层级、企业按企业ID,已自动应用无需手动调用
|
||||
|
||||
**三层防护机制**:
|
||||
|
||||
1. **路由层中间件**(粗粒度拦截)
|
||||
- 用于明显的权限限制(如企业账号禁止访问账号管理)
|
||||
- 示例:
|
||||
|
||||
```go
|
||||
group.Use(func(c *fiber.Ctx) error {
|
||||
userType := middleware.GetUserTypeFromContext(c.UserContext())
|
||||
if userType == constants.UserTypeEnterprise {
|
||||
return errors.New(errors.CodeForbidden, "无权限访问账号管理功能")
|
||||
}
|
||||
return c.Next()
|
||||
})
|
||||
```
|
||||
|
||||
2. **Service 层业务检查**(细粒度验证)
|
||||
- 使用 `middleware.CanManageShop(ctx, targetShopID, shopStore)` 验证店铺权限
|
||||
- 使用 `middleware.CanManageEnterprise(ctx, targetEnterpriseID, enterpriseStore, shopStore)` 验证企业权限
|
||||
- 类型级权限检查(如代理不能创建平台账号)
|
||||
- 示例见 `internal/service/account/service.go`
|
||||
|
||||
3. **GORM Callback 自动过滤**(兜底)
|
||||
- 已有实现,自动应用到所有查询
|
||||
- 代理用户:`WHERE shop_id IN (自己店铺+下级店铺)`
|
||||
- 企业用户:`WHERE enterprise_id = 当前企业ID`
|
||||
- 无需手动调用
|
||||
|
||||
**统一错误返回**:
|
||||
|
||||
- 越权访问统一返回:`errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")`
|
||||
- 不区分"不存在"和"无权限",防止信息泄露
|
||||
统一错误返回:`errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")`(不区分"不存在"与"无权限",防止信息泄露)
|
||||
|
||||
### 幂等性规范
|
||||
|
||||
**适用场景**:任何可能被重复触发的写操作
|
||||
|
||||
#### 必须实现幂等性的场景
|
||||
|
||||
| 场景 | 原因 | 实现策略 |
|
||||
|------|------|----------|
|
||||
| 订单创建 | 用户双击、网络重试 | Redis 业务键防重 + 分布式锁 |
|
||||
| 支付回调 | 第三方平台重复通知 | 状态条件更新(`WHERE status = pending`) |
|
||||
| 钱包扣款/充值 | 并发请求、消息重投 | 乐观锁(version 字段)+ 状态条件更新 |
|
||||
| 套餐激活 | 异步任务重试 | Redis 分布式锁 + 已存在记录检查 |
|
||||
| 异步任务处理 | Asynq 自动重试 | Redis 任务锁(`RedisTaskLockKey`) |
|
||||
| 佣金计算 | 支付成功后触发 | 幂等任务入队 + 状态检查 |
|
||||
|
||||
#### 不需要幂等性的场景
|
||||
|
||||
- 纯查询接口(GET 请求天然幂等)
|
||||
- 管理后台的配置修改(低频操作,人为确认)
|
||||
- 日志记录、审计记录(允许重复写入)
|
||||
|
||||
#### 实现策略选择
|
||||
|
||||
根据场景特征选择合适的策略:
|
||||
|
||||
**策略 1:状态条件更新(首选,适用于有明确状态流转的操作)**
|
||||
写操作按场景选择策略:
|
||||
- **状态流转操作** → 状态条件更新(首选)
|
||||
- **创建类操作(无状态可依赖)** → Redis 业务键防重 + 分布式锁(三层检测)
|
||||
- **余额/库存数值更新** → 乐观锁(`version` 字段)
|
||||
|
||||
```go
|
||||
// 通过 WHERE 条件确保只有预期状态才能更新,RowsAffected == 0 说明已被处理
|
||||
// 策略1示例(首选):通过 WHERE 条件确保幂等,RowsAffected=0 说明已被处理
|
||||
result := tx.Model(&model.Order{}).
|
||||
Where("id = ? AND payment_status = ?", orderID, model.PaymentStatusPending).
|
||||
Updates(map[string]any{"payment_status": model.PaymentStatusPaid})
|
||||
|
||||
if result.RowsAffected == 0 {
|
||||
// 已被处理,检查当前状态决定返回成功还是错误
|
||||
}
|
||||
if result.RowsAffected == 0 { /* 已处理,检查当前状态 */ }
|
||||
```
|
||||
|
||||
**策略 2:Redis 业务键防重 + 分布式锁(适用于创建类操作,无状态可依赖)**
|
||||
|
||||
```go
|
||||
// 业务键 = 唯一标识请求意图的组合字段
|
||||
// 示例:order:create:{buyer_type}:{buyer_id}:{carrier_type}:{carrier_id}:{sorted_package_ids}
|
||||
idempotencyKey := buildBusinessKey(...)
|
||||
redisKey := constants.RedisXxxIdempotencyKey(idempotencyKey)
|
||||
|
||||
// 第 1 层:Redis GET 快速检测
|
||||
val, err := s.redis.Get(ctx, redisKey).Result()
|
||||
if err == nil && val != "" {
|
||||
return existingResult // 已创建,直接返回
|
||||
}
|
||||
|
||||
// 第 2 层:分布式锁防止并发
|
||||
lockKey := constants.RedisXxxLockKey(resourceType, resourceID)
|
||||
locked, _ := s.redis.SetNX(ctx, lockKey, time.Now().String(), lockTTL).Result()
|
||||
if !locked {
|
||||
return errors.New(errors.CodeTooManyRequests, "操作进行中,请勿重复提交")
|
||||
}
|
||||
defer s.redis.Del(ctx, lockKey)
|
||||
|
||||
// 第 3 层:加锁后二次检测
|
||||
val, err = s.redis.Get(ctx, redisKey).Result()
|
||||
if err == nil && val != "" {
|
||||
return existingResult
|
||||
}
|
||||
|
||||
// 执行业务逻辑...
|
||||
|
||||
// 成功后标记
|
||||
s.redis.Set(ctx, redisKey, resultID, idempotencyTTL)
|
||||
```
|
||||
|
||||
**策略 3:乐观锁(适用于余额、库存等数值更新)**
|
||||
|
||||
```go
|
||||
result := tx.Model(&model.Wallet{}).
|
||||
Where("id = ? AND balance >= ? AND version = ?", walletID, amount, currentVersion).
|
||||
Updates(map[string]any{
|
||||
"balance": gorm.Expr("balance - ?", amount),
|
||||
"version": gorm.Expr("version + 1"),
|
||||
})
|
||||
if result.RowsAffected == 0 {
|
||||
return errors.New(errors.CodeInsufficientBalance, "余额不足或并发冲突")
|
||||
}
|
||||
```
|
||||
|
||||
#### Redis Key 命名规范
|
||||
|
||||
幂等性相关的 Redis Key 统一在 `pkg/constants/redis.go` 定义:
|
||||
|
||||
```go
|
||||
// 幂等性检测键:Redis{Module}IdempotencyKey — TTL 通常 3~5 分钟
|
||||
func RedisOrderIdempotencyKey(businessKey string) string
|
||||
|
||||
// 分布式锁键:Redis{Module}{Action}LockKey — TTL 通常 10~30 秒
|
||||
func RedisOrderCreateLockKey(carrierType string, carrierID uint) string
|
||||
```
|
||||
|
||||
#### 现有幂等性实现参考
|
||||
|
||||
| 模块 | 文件 | 策略 |
|
||||
|------|------|------|
|
||||
| 订单创建 | `internal/service/order/service.go` → `Create()` | 策略 2:Redis 业务键 + 分布式锁 |
|
||||
| 钱包支付 | `internal/service/order/service.go` → `WalletPay()` | 策略 1:状态条件更新 |
|
||||
| 支付回调 | `internal/service/order/service.go` → `HandlePaymentCallback()` | 策略 1:状态条件更新 |
|
||||
| 套餐激活 | `internal/service/package/activation_service.go` → `ActivateQueuedPackage()` | 策略 2(简化版):Redis 分布式锁 |
|
||||
| 钱包扣款 | `internal/service/order/service.go` → `WalletPay()` | 策略 3:乐观锁(version 字段) |
|
||||
- Redis Key 定义在 `pkg/constants/redis.go`,分布式锁必须用 `defer` 释放
|
||||
- 参考实现:`internal/service/order/service.go`
|
||||
|
||||
### 异步任务载荷规范(Asynq)
|
||||
|
||||
@@ -581,24 +272,12 @@ func RedisOrderCreateLockKey(carrierType string, carrierID uint) string
|
||||
// ✅ 正确:传 struct
|
||||
queueClient.EnqueueTask(ctx, constants.TaskTypeXxx, MyPayload{OrderID: id})
|
||||
|
||||
// ✅ 正确:传 map
|
||||
queueClient.EnqueueTask(ctx, constants.TaskTypeXxx, map[string]any{"order_id": id})
|
||||
|
||||
// ❌ 错误:预先序列化后传 []byte(二次 Marshal → base64 编码)
|
||||
payloadBytes, _ := sonic.Marshal(MyPayload{OrderID: id})
|
||||
queueClient.EnqueueTask(ctx, constants.TaskTypeXxx, payloadBytes)
|
||||
```
|
||||
|
||||
**直接用 `asynq.NewTask` 入队时**(绕过 `EnqueueTask`)才需要自己 Marshal:
|
||||
|
||||
```go
|
||||
// 直接构造 asynq.Task 时,需自行序列化
|
||||
payloadBytes, _ := sonic.Marshal(MyPayload{OrderID: id})
|
||||
task := asynq.NewTask(constants.TaskTypeXxx, payloadBytes, asynq.Queue(...))
|
||||
client.EnqueueContext(ctx, task)
|
||||
```
|
||||
|
||||
**原因**:`pkg/queue/client.go` 的 `EnqueueTask` 在内部已封装了 `sonic.Marshal`,统一处理序列化,调用方不应关心底层字节格式。
|
||||
直接用 `asynq.NewTask` 入队时(绕过 `EnqueueTask`)才需要自己 Marshal。
|
||||
|
||||
---
|
||||
|
||||
@@ -606,51 +285,9 @@ client.EnqueueContext(ctx, task)
|
||||
|
||||
**适用场景**:任何敏感操作(账号管理、权限变更、数据删除等)
|
||||
|
||||
**使用方式**:
|
||||
|
||||
1. **Service 层集成审计日志**:
|
||||
|
||||
```go
|
||||
type Service struct {
|
||||
store *Store
|
||||
auditService AuditServiceInterface
|
||||
}
|
||||
|
||||
func (s *Service) SensitiveOperation(ctx context.Context, ...) error {
|
||||
// 1. 执行业务操作
|
||||
err := s.store.DoSomething(ctx, ...)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// 2. 记录审计日志(异步)
|
||||
s.auditService.LogOperation(ctx, &model.OperationLog{
|
||||
OperatorID: middleware.GetUserIDFromContext(ctx),
|
||||
OperationType: "operation_type",
|
||||
OperationDesc: "操作描述",
|
||||
BeforeData: beforeData, // 变更前数据
|
||||
AfterData: afterData, // 变更后数据
|
||||
RequestID: middleware.GetRequestIDFromContext(ctx),
|
||||
IPAddress: middleware.GetIPFromContext(ctx),
|
||||
UserAgent: middleware.GetUserAgentFromContext(ctx),
|
||||
})
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
2. **审计日志字段说明**:
|
||||
- `operator_id`, `operator_type`, `operator_name`: 操作人信息(必填)
|
||||
- `target_*`: 目标资源信息(可选)
|
||||
- `operation_type`: 操作类型(create/update/delete/assign_roles等)
|
||||
- `operation_desc`: 操作描述(中文,便于查看)
|
||||
- `before_data`, `after_data`: 变更数据(JSON 格式)
|
||||
- `request_id`, `ip_address`, `user_agent`: 请求上下文
|
||||
|
||||
3. **异步写入**:
|
||||
- 审计日志使用 Goroutine 异步写入
|
||||
- 写入失败不影响业务操作
|
||||
- 失败时记录 Error 日志,包含完整审计信息
|
||||
- Service 层注入 `auditService AuditServiceInterface`,操作成功后调用 `LogOperation()`
|
||||
- 必填字段:`OperatorID`、`OperationType`、`OperationDesc`、`BeforeData`、`AfterData`
|
||||
- 异步写入(Goroutine),写入失败不影响业务,失败时记录 Error 日志
|
||||
|
||||
**示例参考**:`internal/service/account/service.go`
|
||||
|
||||
@@ -672,19 +309,4 @@ client.EnqueueContext(ctx, task)
|
||||
> "我注意到任务 2.1 和 2.2 可以合并为一步完成,是否可以这样优化?"
|
||||
> "任务 3.1 在当前实现中可能不需要,是否可以跳过?"
|
||||
|
||||
**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md`
|
||||
|
||||
# English Learning Mode
|
||||
|
||||
The user is learning English through practical use. Apply these rules in every conversation:
|
||||
|
||||
1. **Always respond in Chinese** — regardless of whether the user writes in English or Chinese.
|
||||
|
||||
2. **When the user writes in English**, append a one-line correction at the end of your response in this format:
|
||||
→ `[natural version of what they wrote]`
|
||||
No explanation needed — just the corrected phrase.
|
||||
|
||||
3. **When the user mixes Chinese into English** (e.g., "I want to 实现 dark mode"), translate the Chinese word/phrase inline and continue naturally. Do not make a
|
||||
big deal of it.
|
||||
|
||||
4. **Never interrupt the flow** to give grammar lessons. Corrections are silent and brief — the user's focus is on the task, not the language.
|
||||
**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md`
|
||||
Reference in New Issue
Block a user