# Research Summary

**Domain:** 君鸿卡管系统 — IoT 卡/号卡/设备全生命周期管理平台
**Synthesized:** 2026-03-27
**Sources:** STACK.md · FEATURES.md · ARCHITECTURE.md · PITFALLS.md

---

## 技术栈评估

**结论：当前技术选型合理，无需大规模替换。**

| 组件 | 状态 | 行动建议 |
|------|------|---------|
| Fiber v2.52.9 | ✅ 继续使用 | 不升级 v3（破坏性变更 100+ 处，迁移成本过高） |
| GORM v1.31.x | ✅ 最新 | 继续使用；多级递归查询用原生 `WITH RECURSIVE` |
| Asynq v0.24.x | ⚠️ 落后 | 可选升级到 v0.26.0（无破坏性变更） |
| go-redis v9.7.0 | ⚠️ 落后 | 建议升级到 v9.18.x（无破坏性变更） |
| sonic / PowerWeChat | ✅ 正常 | 继续使用 |

**技术债**：佣金计算全程使用 `int64` 整数运算是正确的；退款比例计算（方案 I-3）禁止用 `float64`，应使用整数算术 `a * b / c`。

---

## 功能完整性分析

### 已覆盖的 Table Stakes ✅
- IoT 卡全生命周期（开卡/激活/停复机/销户）
- 套餐系统（主套餐/加油包/排队/囤货待实名/流量扣减）
- 五种订单购买场景 + 三种支付方式
- 代理商多级分销（7 级层级，差价佣金+一次性佣金）
- RBAC 权限系统 + 多租户数据隔离
- C 端微信认证 + 钱包充值购包

### 缺失的 Table Stakes ⚠️（修复阶段应关注）

| 功能 | 优先级 | 说明 |
|------|--------|------|
| 卡/资产批量操作（停/复/注销） | HIGH | 运营场景必须，单卡操作无法应对批量场景 |
| 卡/订单批量导出（Excel） | HIGH | 财务对账必须，已有导入但缺导出 |
| 退款完整流程 | HIGH | 方案 I 已规划，必须实现 |
| 卡状态变更历史记录 | MEDIUM | 出现纠纷时需要溯源 |
| 套餐到期提醒（微信模板消息） | MEDIUM | 用户断网会差评，竞品标配 |
| 代理商完整资金流水账单 | MEDIUM | 代理需要对账 |
| 富友支付 JSAPI/小程序接口补全 | HIGH | 方案 J-1，SDK 已实现但接口是留桩 |

### 竞品差异化（v2+ 方向）
- 智能套餐推荐（基于历史用量）
- 告警推送（流量耗尽前预警）
- 数据大屏（代理商业绩可视化）

---

## 架构风险

### 当前正确的设计决策 ✅
- 双进程隔离（API vs Worker）— 独立扩容
- 数据权限显式过滤（非 GORM Callback）— 可见性强
- Asynq 任务队列解耦同步/异步链路
- Bootstrap 集中依赖装配

### 需要立即处理的架构问题 🔴

**1. PollingHandler 缺少 asynqClient（方案 A-3）**
- 实名激活任务通过 RPush Redis List 降级，绕过 Asynq
- 修复后才能保证异步任务链路可靠性

**2. 多个 Service 实例依赖注入残缺（方案 F-6）**
- StopResumeCallback / ResumeCallback 未在 bootstrap 注入
- 停复机后套餐联动回调不触发

**3. Worker 注册遗漏（方案 A-4）**
- AutoPurchaseHandler 未在 handler.go 注册
- 充值回调后自动购包任务入队但永远不消费

### SaaS 化时的潜在瓶颈（供参考，v2+ 考量）
- 代理层级 7 级限制需松绑为配置化
- tb_shop/tb_enterprise 的 owner_shop_id 设计需调整为 tenant_id
- 套餐成本价体系（每个代理一套）将成为最大多租户难点

---

## 关键陷阱（超出修正方案范围）

### 🔴 高危

**1. sellerCostPrice 赋值错误可能不止 1 处（A-5 相关）**
- 修正方案只点名场景 5，但 order/service.go 中有 6 处 `sellerCostPrice = buyerCostPrice`
- 修复时必须逐一验证每个场景的语义正确性

**2. 退款佣金回扣禁用 float64（方案 I-3）**
- `ratio := float64(x) / float64(y)` 会引入精度误差
- 应使用：`deductAmount = commission.Amount * approvedAmount / actualAmount`（纯整数）

**3. 分佣树形遍历可能循环引用**
- `shop.ParentID` 向上遍历没有深度上限和循环检测
- 人工修改数据库可能导致 Worker 死循环

### 🟡 中危

**4. 店铺软删除没有级联检查**
- 删除有子代理的店铺后，子代理 parent_id 指向软删除记录
- 佣金计算时找不到父链接，上级代理静默丢失佣金

**5. 实名状态轮询无限重试设计**
- 卡在"未实名"状态的卡每次轮询都入队，没有最大重试次数限制
- 大量长期未实名的卡会持续占用轮询资源

---

## 构建优先级建议

```
立即（1-2 天）：方案 A（7 个 P0 Bug）
近期（3-5 天）：方案 B/C/G/H + J-4（企业权限/提现/实名重构/轮询小修）
中期（1-2 周）：方案 D/I/J-1/J-2/J-3/F（设备/退款/富友支付/代码清理）
长期（低峰期）：方案 E（流量体系改革，破坏性 DB 迁移）
```

---
*Research synthesized: 2026-03-27*