# Stack Research

**Domain:** IoT 卡管理平台 — SIM 卡全生命周期 + 代理分销 + 分佣结算
**Researched:** 2026-03-27
**Confidence:** MEDIUM-HIGH（核心技术栈 HIGH，外围选项 MEDIUM）

---

## 结论先行：当前技术栈评估

**整体结论：当前技术选型对于该领域是合理的，无需大规模替换。**
存在 3 个明确的技术债和 1 个值得关注的升级时机。

| 组件 | 当前版本 | 最新版本 | 状态 | 建议 |
|------|---------|---------|------|------|
| Fiber | v2.52.9 | **v3.1.0** | ⚠️ 大版本落后 | 保持 v2，不升级（见分析） |
| GORM | v1.31.1 | v1.31.x | ✅ 最新 | 继续使用 |
| Asynq | v0.25.1 | **v0.26.0** | ⚠️ 落后一个版本 | 可选升级（安全依赖升级） |
| go-redis | v9.7.0 | v9.18.0 | ⚠️ 落后较多 | 建议升级（无 API 破坏性变更） |
| sonic | v1.14.2 | v1.14.x | ✅ 近期版本 | 继续使用 |
| PowerWeChat | v3.4.38 | v3.4.38 | ✅ 最新 | 继续使用 |
| Go runtime | 1.25.x | 1.25.x | ✅ 最新 | 继续使用 |

---

## 核心技术栈

### 一、HTTP 框架 — Fiber v2（**继续坚守**）

| 项目 | 内容 |
|------|------|
| 当前版本 | v2.52.9（已是 v2.x 最新） |
| 最新大版本 | v3.1.0（2026-02-02 正式发布） |
| **不升级的原因** | v3 有重大破坏性变更，迁移成本高，且本项目有大量存量代码 |

**v3 核心破坏性变更（对本项目影响分析）：**

1. **`c.UserContext()` 被移除** → `Ctx` 本身现在实现 `context.Context`，直接传 `c` 即可。
   - **影响：**本项目全代码库大量使用 `c.UserContext()` 传递用户 Context 到 Service/Store 层，这是最大的迁移成本。
   - **估算：**全局搜索 `UserContext()` 调用点，预估 100+ 处改动。

2. **`c.BodyParser()` 移除** → 改用 `c.Bind().Body()`
   - **影响：**所有 Handler 层的请求解析代码需要改写。

3. **路由注册 `Add` 方法签名变更** → 影响 `internal/routes/registry.go` 的统一注册逻辑。

4. **`app.Mount()` 移除** → 使用 `app.Use()`。

**置信度：HIGH**（官方文档 https://docs.gofiber.io/whats_new/ 已确认）

**建议：** 保持 v2.52.x，待 v2 EOL 公告或下一个重大重构机会再考虑升级。v2 安全维护至少到 2026 年底，风险可控。

---

### 二、ORM — GORM v2（**继续使用，无更好替代方案**）

**2026 年 Go ORM 格局：**

| ORM | 定位 | 适合本项目 |
|-----|------|-----------|
| **GORM** | 全功能 ORM，code-first，ActiveRecord 风格 | ✅ **最适合** |
| sqlc | 编译时类型安全，从 SQL 生成 Go 代码 | ❌ 需要从头重写所有查询 |
| sqlx | SQL 轻量封装，接近原生 database/sql | ❌ 需要全部改写，收益有限 |
| ent | 图模型 ORM，compile-time type safety | ❌ 学习成本高，编译慢，不适合现有代码库 |

**为什么 GORM 对本项目是正确选择：**
- CRUD 密集型应用（卡管理、套餐管理、订单、佣金），GORM 的约定优于配置大幅减少样板代码
- 软删除、钩子（Hooks）、事务等特性本项目大量依赖
- 当前 v1.31.x 已是最新，无需升级

**GORM 的已知性能问题（针对本项目的建议）：**
- 多级代理佣金树查询（最深 7 层）不应使用 GORM `Preload`，而应使用原生 `WITH RECURSIVE` CTE
- 批量导入（ICCID Excel）应使用 `db.CreateInBatches()` 而非逐行 `Create()`

**置信度：HIGH**（多个 2026 年对比文章，主流观点一致）

---

### 三、任务队列 — Asynq（**继续使用，考虑升级到 v0.26.0**）

**最新版本：** v0.26.0（2026-02-03 发布）

| 版本 | 关键变更 |
|------|---------|
| v0.25.1（当前） | 安全依赖升级 + 增加 `RedisUniversalClient` 支持 |
| **v0.26.0** | 增加 Task Headers 支持（PR #1070）+ TLS 选项 + 最低 Go 版本升至 1.24 |

**为什么不替换 Asynq：**
在 IoT 卡管理场景中，Asynq 的优势：
- 基于 Redis（与现有基础设施共享，无额外运维成本）
- 内置定时任务调度（Scheduler）适合轮询任务场景
- 任务可视化（Asynqmon Web UI）在生产调试中有价值
- 竞品（Machinery、Watermill）依赖更重，对单节点场景没有额外收益

**建议：** 升级到 v0.26.0（`go get github.com/hibiken/asynq@v0.26.0`），主要收益是上游安全依赖修复，API 完全兼容。

**置信度：HIGH**（GitHub Releases 直接验证）

---

### 四、Redis 客户端 — go-redis v9（**建议升级**）

**当前版本：** v9.7.0
**最新版本：** v9.18.0（2026-02-16）

v9.7.0 → v9.18.0 跨越 11 个 patch 版本，均为向后兼容。建议升级原因：
- 包含若干 bug 修复和性能改进
- 升级命令：`go get github.com/redis/go-redis/v9@v9.18.0`

**置信度：MEDIUM**（pkg.go.dev 直接确认版本）

---

### 五、JSON 序列化 — sonic（**继续使用**）

**sonic（bytedance/sonic）** 在 2025 年基准测试中仍是 Go 生态最快的 JSON 库：

| 库 | 相对速度 | 适用场景 |
|----|---------|---------|
| **sonic** | ~3-4x 快于 std | 高并发 API，大 payload（如 Excel 导入响应） |
| encoding/json v2（Go 1.25 内置） | ~1.8x 快于 std | 标准库，无需引入依赖 |
| encoding/json（std） | 1x 基线 | 无额外依赖场景 |

**注意：** Go 1.25 引入了 `encoding/json/v2`，性能约为 sonic 的 50%，但消除了历史行为不一致问题。对于本项目，sonic 仍是正确选择：本项目已集成且使用 Fiber 的 sonic 替换，迁移收益不大。

**置信度：HIGH**（2025-09 Reddit benchmark + Trendyol 生产迁移案例）

---

## 领域特有技术栈缺口分析

### 缺口 1：金融精度问题 ⚠️（**重大技术债**）

**问题描述：**
IoT 卡管理平台涉及两类精度敏感计算：
1. **货币金额**：钱包余额、佣金金额（差价佣金、一次性佣金）、套餐价格
2. **流量计费**：MB/GB 流量用量计算、按比例退款

**当前实现风险：**
- 余额字段使用 `int64`（存储"分"）—— **钱包余额做法正确**
- 但佣金链计算（差价 = 上层价格 - 下层成本）中，如果涉及百分比分佣（如"提成 15%"），用 `float64` 计算后再转 `int64` 会有精度损失

**标准做法（2025 年行业共识）：**

```
选项 A：纯整数（分/厘）存储，避免所有浮点运算
  - 适合固定金额计算
  - 本项目钱包余额已是此做法 ✅
  
选项 B：shopspring/decimal（用于百分比/比例计算）
  - 适合佣金比例计算、退款按比例扣减
  - 7000+ GitHub stars，已是 Go 社区财务计算标准库
  
选项 C：go-money（Rhymond/go-money）
  - 适合多币种场景，本项目不需要
```

**建议：**
引入 `github.com/shopspring/decimal` v1.4.0，**仅用于**：
- 佣金比例计算（如方案 I-3：退款按比例扣减代理佣金）
- 流量按比例计费（方案 E 的流量体系改革）

不需要全局替换 int64 余额字段，仅在需要乘除法的计算环节使用 decimal，最终结果转 int64 存储。

**置信度：HIGH**（Modern Treasury 官方博客 2025-08 + shopspring/decimal 7286 stars）

---

### 缺口 2：多级代理查询性能 ⚠️（**架构风险**）

**问题描述：**
本项目代理层级最多 7 层，`GetSubordinateShopIDs()` 使用 PostgreSQL `WITH RECURSIVE` CTE 查询，结果缓存 30 分钟。这个架构是正确的。

**潜在风险：**
- 佣金链计算时，N 层递归分佣可能退化为 N 次单独 DB 查询（N+1 问题）
- 7 层 × 每层查询 = 最坏 7 次 DB 往返，而 DB 查询要求 < 50ms

**2025 年标准方案：**
对于多级分佣树计算，行业标准是一次性将整条链路数据加载到内存，而非逐层查询：

```sql
-- 一次性获取完整佣金链（从叶子节点到根节点）
WITH RECURSIVE commission_chain AS (
  SELECT shop_id, parent_id, level, 0 AS depth
  FROM tb_shop WHERE id = $1
  UNION ALL
  SELECT s.shop_id, s.parent_id, s.level, cc.depth + 1
  FROM tb_shop s
  INNER JOIN commission_chain cc ON s.id = cc.parent_id
)
SELECT * FROM commission_chain ORDER BY depth;
```

当前代码已经有 `WITH RECURSIVE` 基础，但需要确认佣金计算是否利用了这个能力。

**置信度：MEDIUM**（基于代码库 PROJECT.md 分析 + PostgreSQL 官方文档）

---

### 缺口 3：可观测性 ⚠️（**生产上线前需解决**）

**问题描述：**
当前技术栈的可观测性仅有：
- 应用日志（Zap）
- 访问日志
- Asynq 任务状态（via Asynqmon 可选）
- 健康检查 `GET /health`

**缺失：**
- 没有指标（Metrics）收集
- 没有链路追踪（Tracing）
- 没有告警（Alerting）

**对于当前阶段（MVP 修复上线）：** 可以暂时接受，PROJECT.md 的 Out of Scope 已明确 "P2-6 告警通知渠道 — 无关紧要，暂不做"。

**但如果平台上线后扩展：**
- 轻量级方案：Prometheus + Grafana（已是 Go 社区标准）
- 零侵入方案：OpenTelemetry Go SDK（标准化，支持后续接入任意后端）

**置信度：MEDIUM**（基于 Go 社区 2025 年可观测性实践）

---

### 缺口 4（IoT 领域特有）：运营商网关客户端 — 无通用标准库

**问题描述：**
本项目有 `internal/gateway/client.go`（外部 Gateway 服务 HTTP 客户端）。IoT SIM 卡管理平台通常需要对接：
- GSMA M2M 标准（SM-DP+/SM-DS for eSIM）
- 运营商私有 API（中国联通、移动、电信）

**2025 年实际情况：**
国内运营商 IoT 平台（移动 OneNET、电信 CTWing、联通 Open）均为私有 REST/SOAP API，**没有标准化的 Go SDK**。

当前项目自研 `internal/gateway/client.go` 是唯一可行路径，符合行业惯例。

**置信度：HIGH**（行业调研确认，无通用 Go SDK 存在）

---

## 当前栈中已弃用/有问题的依赖

| 依赖 | 问题 | 建议 |
|------|------|------|
| `aws/aws-sdk-go` (v1) | AWS SDK Go v1 已于 2025-07-31 进入 Maintenance Mode，不再接收功能更新 | 低优先级，当前对接联通云 OSS，可继续使用；如有大范围重构可迁移到 `aws/aws-sdk-go-v2` |
| `excelize/v2` | 无严重问题，版本跟进即可 | — |

**AWS SDK v1 注意：** 仅 Maintenance Mode，不是 End of Life，安全补丁仍会发布。迁移到 v2 需要较大代码改动，不建议在当前 MVP 阶段操作。

**置信度：MEDIUM**（AWS 官方公告，2025-07-31）

---

## 可选补充库

以下库不在当前技术栈中，但对特定需求有价值：

| 库 | 版本 | 用途 | 引入时机 |
|----|------|------|---------|
| `shopspring/decimal` | v1.4.0 | 佣金比例计算、退款按比例计算 | **方案 I（退款）实现时** |
| `golang-migrate/migrate` | v4.18.x | 数据库迁移（已在项目使用） | — 已用 |
| `hibiken/asynqmon` | latest | Asynq 任务可视化 Web UI | 生产环境调试时 |

---

## 替代方案对比

| 类别 | 当前选择 | 备选 | 不替换的理由 |
|------|---------|------|------------|
| HTTP 框架 | Fiber v2 | Gin, Echo, Chi, Fiber v3 | 大量存量代码；v3 破坏性变更成本高 |
| ORM | GORM | sqlc, sqlx, ent | 项目已深度集成，CRUD 场景 GORM 是最优解 |
| 任务队列 | Asynq | Machinery, Watermill, Temporal | Redis 复用优势；Temporal 对单节点过重 |
| 消息队列 | 无（Asynq 兼任） | NATS, Kafka | 当前规模不需要独立 MQ |
| 缓存 | Redis | Memcached | Redis 功能更丰富，已是基础设施 |
| 数据库 | PostgreSQL | MySQL, CockroachDB | PostgreSQL 的递归 CTE 对层级数据有优势 |
| JSON | sonic | encoding/json, json/v2 | sonic 性能优势在高并发场景显著 |

---

## 版本兼容性注意事项

| 依赖组合 | 状态 | 注意 |
|---------|------|------|
| Fiber v2 + Go 1.25 | ✅ 兼容 | Fiber v2.52.9 已适配 Go 1.25 |
| Fiber v3 + Go 1.25 | ⚠️ 要求 Go 1.25+ | v3 以 Go 1.25 为最低版本 |
| Asynq v0.26.0 + Go 1.25 | ✅ 兼容 | v0.26.0 要求 Go 1.24+，1.25 满足 |
| GORM v1.31.1 + PostgreSQL 14+ | ✅ 兼容 | — |
| PowerWeChat v3.4.38 + Go 1.25 | ✅ 兼容 | 官方声明 Go 1.23+ |

---

## 关键技术债总结（优先级排序）

### P0：必须在上线前解决

**金融精度风险**（佣金计算）
- 检查所有涉及百分比/比例的佣金计算代码，确认没有 `float64` 中间步骤
- 方案 I（退款按比例扣减佣金）实现时必须引入 `shopspring/decimal`

### P1：上线后尽快处理

**go-redis 版本落后**
- 从 v9.7.0 升级到 v9.18.0，无 API 破坏性变更，安全隐患修复

**Asynq 版本落后**
- 从 v0.25.1 升级到 v0.26.0，获得安全修复

### P2：中期规划

**AWS SDK v1 → v2 迁移**（对象存储）
- 不紧急，v1 仍有安全支持，规划下一个重大重构时处理

**Fiber v2 → v3 迁移评估**
- v2 仍在维护，不需要立即升级
- 建议在明年底（2027）重新评估是否升级

---

## 安装/升级命令参考

```bash
# 升级 Asynq（推荐）
go get github.com/hibiken/asynq@v0.26.0

# 升级 go-redis（推荐）
go get github.com/redis/go-redis/v9@v9.18.0

# 引入 decimal（P0 佣金精度修复时）
go get github.com/shopspring/decimal@v1.4.0

# 升级所有兼容依赖（谨慎，逐一验证）
go get -u ./...
```

---

## Sources

| 来源 | 内容 | 置信度 |
|------|------|--------|
| https://docs.gofiber.io/whats_new/ | Fiber v3 破坏性变更完整列表 | HIGH |
| https://newreleases.io/project/github/hibiken/asynq/release/v0.26.0 | Asynq v0.26.0 发布说明 | HIGH |
| https://pkg.go.dev/github.com/redis/go-redis/v9 | go-redis 最新版本 v9.18.0 | HIGH |
| https://reintech.io/blog/sqlc-vs-gorm-vs-sqlx-go-database-libraries-compared-2026 | GORM vs sqlc vs sqlx 2026 深度对比 | MEDIUM |
| https://encore.cloud/resources/go-orms | Go ORM 2026 对比（GORM/sqlc/ent）| MEDIUM |
| https://pkg.go.dev/github.com/shopspring/decimal@v1.4.0 | shopspring/decimal v1.4.0 | HIGH |
| https://www.moderntreasury.com/journal/floats-dont-work-for-storing-cents | 金融精度使用整数的行业实践 | HIGH |
| Reddit r/golang 2025-09 JSON benchmark | sonic vs std vs json/v2 基准 | MEDIUM |
| https://pkg.go.dev/github.com/ArtisanCloud/PowerWeChat/v3@v3.4.38 | PowerWeChat 最新版本确认 | HIGH |

---

*Stack research for: IoT SIM 卡管理平台（Go + Fiber + GORM + Asynq + PostgreSQL + Redis）*
*Researched: 2026-03-27*