docs: add research findings
This commit is contained in:
121
.planning/research/SUMMARY.md
Normal file
121
.planning/research/SUMMARY.md
Normal file
@@ -0,0 +1,121 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user