csxj2026/junhong_cmp_fiber

Files

huang 3078bc71c8 docs: add research findings

2026-03-27 19:04:17 +08:00

4.6 KiB

Raw Permalink Blame History

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

4.6 KiB Raw Permalink Blame History Unescape Escape