junhong_cmp_fiber/.planning/research/ARCHITECTURE.md

Architecture Research

Domain: IoT 卡管理 + 多级分销 + 分佣结算平台（Brownfield 单体） Researched: 2026-03-27 Confidence: HIGH（基于当前代码库深度分析 + 该领域已知模式验证）

---

当前架构概述

系统总览

┌──────────────────────────────────────────────────────────────────────┐
│                          API 进程（cmd/api）                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐             │
│  │ /auth    │  │ /admin   │  │ /c/v1    │  │ /callback│             │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘             │
│       │             │             │              │                   │
│       └─────────────┴──── Handler 层 ────────────┘                   │
│                           │                                          │
│                     Service 层（~55 个服务包）                         │
│                           │                                          │
│                     Store 层（54 个 Store 文件）                       │
│                           │                                          │
│                     PostgreSQL + Redis                               │
└──────────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────────┐
│                        Worker 进程（cmd/worker）                      │
│  ┌────────────────┐  ┌──────────────────┐  ┌─────────────────────┐  │
│  │ Asynq Worker   │  │ 轮询调度器        │  │ Asynq Scheduler     │  │
│  │ (任务消费)      │  │ (Redis SortedSet)│  │ (定时任务)           │  │
│  └────────┬───────┘  └────────┬─────────┘  └──────────┬──────────┘  │
│           └──────────────────┴────────────────────────┘             │
│                               │                                      │
│                         Task Handler 层（16 个任务）                   │
│                               │                                      │
│                     Service / Store 层（复用 API 侧）                  │
└──────────────────────────────────────────────────────────────────────┘

外部集成：
  Gateway（运营商接口） ← HTTP Client → IoT 卡/设备状态同步
  微信支付（JSAPI/H5）  ← PowerWeChat SDK
  富友支付             ← 自研 SDK（pkg/fuiou）
  联通云 OSS           ← S3 兼容（批量导入/导出）

组件职责

组件	职责	关键文件
Bootstrap	依赖装配，进程启动唯一入口	internal/bootstrap/*.go
RouteSpec + Register()	路由即文档，单次声明驱动 Fiber + OpenAPI	internal/routes/registry.go
Auth Middleware	JWT/Redis Token 解析，写入 UserContextInfo	pkg/middleware/auth.go
DataScope Filter	Store 层显式过滤，多租户数据隔离	pkg/middleware/data_scope.go
Service（业务核心）	幂等、事务编排、业务规则、任务提交	internal/service/**
Store（数据访问）	SQL、分页、显式权限过滤	internal/store/postgres/*.go
Task Handler	Asynq 任务处理（轮询/佣金/导入/过期）	internal/task/*.go
Polling Scheduler	Redis SortedSet 驱动卡片轮询队列	internal/polling/scheduler.go
Commission Calculation	多级分佣链计算（差价佣金 + 一次性佣金）	internal/service/commission_calculation/

---

组件边界分析

当前已正确划分的边界

① 双进程隔离（API vs Worker）

• API 进程：HTTP 快速响应，无阻塞 I/O
• Worker 进程：轮询、批量导入、佣金计算、定时任务
• 边界清晰，独立部署、独立扩容 ✅

② 数据权限隔离（Shop 层级过滤）

• 用户身份 → UserContextInfo → SubordinateShopIDs（Redis 缓存）
• Store 层显式调用 ApplyShopFilter / ApplyEnterpriseFilter
• 不依赖 GORM Callback，权限过滤显式可见 ✅

③ 任务队列解耦（Asynq）

• 同步调用路径：Handler → Service → 提交 Asynq 任务
• 异步执行路径：Worker → Task Handler → Service/Store
• 支付回调触发的佣金计算走异步路径，不阻塞回调响应 ✅

④ 外部服务封装（Gateway / 微信 / 富友）

• Gateway HTTP Client 封装在 internal/gateway/
• 微信 SDK 封装在 pkg/wechat/
• 富友 SDK 封装在 pkg/fuiou/
• 外部依赖注入，可以独立替换 ✅

当前边界薄弱点（需要关注）

⑤ Order Service 超大文件（Critical）

• internal/service/order/service.go = 2365 行
• 支付发起、支付回调、订单状态流转、幂等锁、钱包扣款全部耦合
• 任何一处改动都有全链路回归风险
• 建议： 按职责拆分为子文件：payment_service.go、callback_service.go、order_state.go、wallet_deduction.go

⑥ 轮询系统 asynqClient 依赖缺失（High）

• internal/task/polling_handler.go 中实名激活通过 Redis RPush 降级实现，而非 Asynq 任务
• 架构偏差：同一 Worker 进程内用两套机制投递任务（Asynq + RPush）
• 建议： 在 Worker Bootstrap 中注入 asynqClient，统一走 Asynq 路径

⑦ C 端 Handler 直接访问 DB（Medium）

• 方案 F-4：部分 C 端 Handler 绕过 Service 层直接访问 DB
• 破坏了分层边界，导致业务逻辑散落在 Handler 层
• 建议： 迁回 Service 层，Handler 只做 HTTP 入参解析和响应封装

---

数据流方向

关键流 1：订单创建 + 支付 + 佣金链

用户发起购买
    │
    ▼
Handler → 解析 DTO → 调用 OrderService.Create()
    │
    ▼
OrderService.Create()
├── Redis 幂等键检查（业务键防重）
├── 分布式锁（RedisOrderCreateLockKey）
├── 二次检查（加锁后再查 Redis）
├── DB 事务：创建订单 + 冻结钱包余额
└── 提交 Asynq 支付超时任务（30min）
    │
    ▼
支付回调（微信/富友）
    │
    ▼
CallbackHandler → PaymentService.HandleCallback()
├── WHERE status=pending 条件更新（防重）
├── 更新订单状态为已支付
├── 解冻钱包余额 / 扣款
└── 提交 CommissionCalculation Asynq 任务
    │
    ▼
Worker: CommissionCalculationTask
├── 查询代理层级路径（WITH RECURSIVE / parent_id 链）
├── 计算差价佣金链（每层代理差价 × 数量）
├── 计算一次性佣金（绑定规则）
├── DB 事务：写入 commission_record（幂等：unique(order_id, agent_id)）
└── 更新代理钱包余额

关键流 2：IoT 卡轮询 + 实名激活

Polling Scheduler（独立 Goroutine）
    │
    ├── 从 Redis Sorted Set 取到期卡片
    │       key: polling:realname:queue
    │
    ▼
投递 Asynq 任务 → Worker: PollingHandler
    │
    ├── 调用 Gateway HTTP 接口拉取实名状态
    ├── 更新 iot_card.realname_status
    │
    ▼
实名状态变为已认证 → 触发套餐激活
    │
    ▼ （当前路径：RPush，待修复为 Asynq）
激活任务 → PackageService.ActivateByRealname()
    ├── 查找 status=3（待实名激活）套餐
    ├── 第一个主套餐 → status=1（激活）
    ├── 其余主套餐 → status=4（排队）
    └── 加油包检查并激活

关键流 3：流量计费（当前方案 vs 改革方案）

当前（方案 E 改革前）：
  Gateway 上报流量 → 直接覆盖写 current_month_usage_mb
  问题：自然月由上游归零，历史数据被破坏

改革后（方案 E）：
  Gateway 上报流量增量
      │
      ▼
  Redis 增量累加（今日流量缓冲）
      │
  每日凌晨批任务 → 写入 tb_card_daily_usage（日粒度记录）
      │
  查询层：Redis 今日数据 + DB 历史数据 合并返回
  优点：历史数据不可变，查询范围可控

关键流 4：多租户数据权限

HTTP 请求 → Auth Middleware
    │
    ├── 解析 JWT/Redis Token
    ├── 查询用户 user_type, shop_id, enterprise_id
    ├── GetSubordinateShopIDs()（WITH RECURSIVE，Redis 缓存 30min）
    └── 写入 UserContextInfo 到 context.Context
    │
    ▼
Store 层查询
    ├── Agent 用户 → ApplyShopFilter(shopIDs)
    │       WHERE shop_id IN (当前+下级)
    ├── Enterprise 用户 → ApplyEnterpriseFilter(enterpriseID)
    │       WHERE enterprise_id = X
    └── SuperAdmin/Platform → 不过滤

---

架构模式

模式 1：两阶段幂等防重（订单创建）

What: Redis 业务键 + 分布式锁双重防护，防止并发创建重复订单 When: 任何创建类写操作（订单、提现、激活任务） Trade-offs: 增加 2~3 次 Redis 往返，换取金融级安全

// Step 1: Redis GET 快速检测
val, err := redis.Get(ctx, idempotencyKey).Result()
if err == nil && val != "" { return existingResult }

// Step 2: SetNX 分布式锁
locked, _ := redis.SetNX(ctx, lockKey, now, lockTTL).Result()
if !locked { return ErrTooManyRequests }
defer redis.Del(ctx, lockKey)

// Step 3: 加锁后二次检测（防止锁等待期间重复创建）
val, err = redis.Get(ctx, idempotencyKey).Result()
if err == nil && val != "" { return existingResult }

// Step 4: 执行业务逻辑...
// Step 5: 标记成功
redis.Set(ctx, idempotencyKey, resultID, ttl)

模式 2：条件更新防并发（状态流转）

What: WHERE status = expected_status 的条件 UPDATE，RowsAffected 判断 When: 支付回调、套餐激活、订单状态变更等有明确状态机的场景 Trade-offs: 需要数据库层有索引支持，效率高但依赖状态设计的正确性

result := tx.Model(&model.Order{}).
    Where("id = ? AND payment_status = ?", orderID, PaymentStatusPending).
    Updates(map[string]any{"payment_status": PaymentStatusPaid})
if result.RowsAffected == 0 {
    // 已被处理或并发冲突，根据当前状态决定返回
}

模式 3：Redis Sorted Set 驱动轮询调度

What: 以下次轮询时间为 Score，ICCID 为 Member，定时扫描到期项投递 Asynq 任务 When: 需要"不同间隔、海量卡片"的轮询调度场景 Trade-offs: 比 cron 更灵活，内存占用与卡片数量正相关；Redis 重启需重建队列

// 投入轮询队列（Score = 下次轮询 Unix 时间戳）
redis.ZAdd(ctx, "polling:realname:queue", redis.Z{
    Score: float64(nextPollAt.Unix()),
    Member: iccid,
})

// Scheduler 每秒扫描
members := redis.ZRangeByScore(ctx, key, &redis.ZRangeBy{
    Min: "-inf",
    Max: strconv.FormatInt(time.Now().Unix(), 10),
    Limit: &redis.Limit{Count: batchSize},
})
// 投递 Asynq 任务...

模式 4：多级佣金链计算（向上遍历）

What: 从发生订单的代理出发，沿 parent_id 向上遍历，逐级计算差价或固定佣金 When: 每笔订单支付成功后触发（异步任务） Trade-offs: 当前 parent_id 邻接表实现，层级 7 层时 WITH RECURSIVE 性能尚可；超 10 层或高并发时需物化路径优化

// 当前实现：DB 递归查询代理链（WITH RECURSIVE 或逐级查询）
// 建议：超 1000 TPS 时改为物化路径 + Redis 缓存代理链
func (s *Service) CalculateCommissionChain(ctx context.Context, orderID uint) error {
    order := fetchOrder(ctx, orderID)
    agentChain := fetchAncestorChain(ctx, order.SellerShopID) // 向上遍历
    for i, agent := range agentChain {
        diff := agent.SellPrice - agent.CostPrice
        writeCommissionRecord(ctx, tx, order.ID, agent.ShopID, diff)
    }
}

---

构建顺序建议

原则： 优先修复已存在但断裂的主链路，再扩展新功能，最后优化架构

阶段 0 — 主链路修复（P0，当前 MVP 阶段的首要目标）
│
├── 1. 实名常量统一（A-1）→ 解锁整个实名链路
├── 2. C 端实名校验（A-2）依赖 A-1
├── 3. 轮询 Handler 注入 asynqClient（A-3）→ 修复架构偏差
├── 4. 充值回调购包触发 + 佣金补全（A-4）→ 核心收入链路
├── 5. 代购订单金额修正（A-5）→ 佣金归零问题
└── 6. 并发校验修复（A-7, C-3）→ 提现/激活配置并发

阶段 1 — 功能补全（参考方案 B/C/D/H/J）
│
├── 企业端权限完善（B-1, B-2）
├── 提现/审批流程完善（C-1, C-2）
├── 设备体系完善（D-0 ~ D-3）
└── 轮询系统小修（H-1 ~ H-4）

阶段 2 — 流量计费改革（方案 E，独立窗口）
│
├── 新建 tb_card_daily_usage（迁移）
├── Redis 增量缓存层
└── 查询层适配（双段数据合并）

阶段 3 — 退款体系（方案 I）
│
├── 退款模型 + 7 个接口
└── 佣金钱包反向扣减

阶段 4 — Order Service 拆分（架构改善）
│
├── payment_service.go（支付发起）
├── callback_service.go（回调处理）
├── order_state.go（状态流转）
└── wallet_deduction.go（钱包操作）

组件依赖关系：

IoT卡状态 → 实名认证 → 套餐激活 → 流量计费 → 订单计算
     │              │          │
     ▼              ▼          ▼
  Gateway      数据轮询     Commission
  集成层       调度层       计算层

---

扩展挑战与 SaaS 化瓶颈

SaaS 化时会成为瓶颈的当前决策

当前决策	SaaS 化面临的问题	迁移路径
单一 PostgreSQL 数据库	所有"租户"（shop）共享同一 DB	添加 tenant_id 列 + RLS，或 Schema 隔离
GORM 数据过滤基于 shop_id	过滤逻辑散布于 54 个 Store 文件	统一 Tenant Context 注入层，确保覆盖率
Config 嵌入二进制	多租户需动态配置（微信AppID/支付商户号）	已有 tb_wechat_config，需完全消除环境变量硬依赖
单进程 Worker	一个 Worker 处理所有租户的轮询/佣金	按租户分队列；大租户独立 Worker
parent_id 邻接表代理层级	跨租户代理关系查询膨胀	加 tenant_id 隔离；超 5 万代理考虑物化路径
commission_calculation 单服务	高 TPS 下单文件 653 行线性计算	异步 + 批量写入；超 1000 TPS 考虑 Flink

各规模架构调整

规模	架构方案
当前（< 100 代理，< 1000 卡）	当前单体完全够用，重点是修复断链
成长期（1000+ 代理，10万+ 卡）	Worker 分队列 + 优化轮询 SortedSet 分片
SaaS 初期（多客户，共享平台）	添加 tenant_id 隔离层；动态支付配置；统一 OpenAPI 网关
SaaS 规模（每客户数万卡）	Schema 隔离 or DB 隔离；独立 Worker 进程 per 大客户
高并发计费（> 5000 TPS）	引入消息队列（Kafka）缓冲计费事件；离线批处理结算

第一个会触发的瓶颈：轮询调度

• 现状： Redis Sorted Set + Asynq 混合投递，Worker 单机并发
• 触发条件： 超过 5 万张活跃卡，每卡 5 分钟轮询一次 = ~167 TPS 持续 Gateway 请求
• 修复方向： Gateway 并发限速配置 + 批量 API 合并 + Sorted Set 分片（多个 queue key）

第二个会触发的瓶颈：佣金计算的 DB 递归查询

• 现状： WITH RECURSIVE 或逐级 parent_id 查询，最深 7 层
• 触发条件： 单日 > 1 万笔订单，并发处理时 DB CPU 飙升
• 修复方向： 代理链 Redis 缓存（shop_id → ancestor_chain）；写入时物化路径 path 字段

第三个会触发的瓶颈：Order Service 耦合带来的发布风险

• 现状： 2365 行，支付/回调/钱包全耦合
• 触发条件： 添加新支付方式（富友小程序）或退款逻辑时，改动影响范围不可控
• 修复方向： 拆分子文件（见构建顺序阶段 4），不需要跨进程拆分

---

反模式警告

反模式 1：在支付回调中同步计算佣金

What: 支付回调 Handler 直接在回调请求的生命周期内计算完整的多级佣金链 Why bad: 回调超时 → 第三方重推 → 佣金重复计算；而且 Gateway 通常要求快速响应（3s 内） Do this instead: 回调只更新订单状态，通过 Asynq 任务异步计算佣金（当前架构已正确实现）

反模式 2：代理层级递归查询不加缓存

What: 每次数据权限过滤都调用 WITH RECURSIVE 查下级 shop_id Why bad: 高并发下递归查询是 DB 杀手；7 层 × 每层 N 个子节点 = 指数级扫描 Do this instead: GetSubordinateShopIDs 结果 Redis 缓存 30 分钟（当前已实现），注意缓存失效策略

反模式 3：流量数据直接被上游覆盖写

What: Gateway 上报当月累计流量 → 直接 UPDATE current_month_usage_mb Why bad: 上游自然月归零时，历史用量记录丢失；无法回查历史；无法审计计费 Do this instead: 日粒度缓冲（方案 E）：增量写入 tb_card_daily_usage，查询层合并 Redis + DB

反模式 4：把租户隔离硬编码在每个 Store 文件

What: 54 个 Store 文件各自调用 ApplyShopFilter，过滤逻辑分散 Why bad: 新增 Store 文件时容易遗漏；SaaS 化时难以统一改造 Do this instead: MVP 阶段保持现状（显式>隐式）；SaaS 化时考虑统一 TenantContext 注入层 + 强制 lint 检测

反模式 5：Worker 内两套任务投递机制

What: 轮询实名激活通过 Redis RPush 投递，其他任务走 Asynq Why bad: 两套消费机制，Asynq 的可观测性/重试/超时管理对 RPush 任务无效 Do this instead: Worker Bootstrap 注入 asynq.Client，统一走 Asynq（方案 A-3）

---

集成点分析

外部服务

服务	集成模式	关键注意点
运营商 Gateway	同步 HTTP 调用（internal/gateway/）	Gateway 宕机时需降级；速率限制；超时设置
微信支付（JSAPI/H5）	PowerWeChat SDK	配置已迁移至 tb_wechat_config，但 OAuth 仍读环境变量（待修复）
富友支付	自研 SDK（pkg/fuiou/）	SDK 完整，主调接口仍留桩（方案 J-1）
联通云 OSS	S3 兼容 SDK	预签名 URL 上传，异步导入任务

内部模块边界

边界	通信方式	注意事项
API → Worker	Asynq 任务队列（Redis）	任务投递幂等；失败重试需要业务幂等保证
Order ↔ Commission	异步（支付回调完成后投递任务）	不能同步等待佣金计算完成
Package ↔ IoT Card	同步（Service 层直接调用）	套餐激活时需持有卡信息，单事务
Polling ↔ Gateway	同步 HTTP（Worker 内）	限速；超时；Gateway 不可用时不应导致整个轮询系统崩溃
Auth ↔ RBAC	同步 Redis + DB（中间件层）	SubordinateShopIDs 缓存是性能关键

---

架构变更的高风险区

基于当前代码分析，以下区域变更风险最高，需要在 roadmap 中单独规划：

区域	风险原因	建议处理方式
internal/service/order/service.go	2365 行，全链路耦合	先修复 Bug，再在低风险时拆分
流量计费体系（方案 E）	涉及 DB 迁移 + Redis 架构 + 查询兼容	单独发布窗口，充分测试迁移脚本
支付配置（微信/富友切换）	半迁移状态（环境变量 vs DB 配置同时存在）	明确单一配置源后再添加新支付方式
轮询系统（Polling Scheduler）	RPush 降级路径 + asynqClient 缺失	A-3 修复后，逐步迁移到统一 Asynq 路径
提现并发逻辑（A-7, C-3）	并发锁逻辑不完整，线上可能已有脏数据	修复时需同步修复历史数据

---

Sources

• 当前代码库深度分析（2026-03-27）：internal/service/, internal/store/postgres/, internal/task/, internal/routing/
• 多层级佣金系统架构设计（TechNova，2026-02-28）：物化路径 vs 邻接表 vs 闭包表对比，CAP 权衡，批流一体
• Multi-Tenant SaaS Isolation（AverageDevs，2026-01-25）：pooled tables vs schema per tenant，Row Level Security，noisy neighbor 防护
• Postgres Multitenancy 2025（DebuggAI）：RLS vs Schema vs 独立 DB 性能对比
• Go Worker Pool + Asynq 并发控制（BackendBytes，OneUptime，2026）：任务队列分区，并发控制

---

Architecture research for: IoT 卡管理平台（君鸿卡管系统） Researched: 2026-03-27