实现 IoT SIM 管理模块数据模型和数据库结构
- 添加 IoT 核心业务表：运营商、IoT 卡、设备、号卡、套餐、订单等 - 添加分佣系统表：分佣规则、分佣记录、运营商结算等 - 添加轮询和流量管理表：轮询配置、流量使用记录等 - 添加财务和系统管理表：佣金提现、换卡申请等 - 实现完整的 GORM 模型和常量定义 - 添加数据库迁移脚本和详细文档 - 集成 OpenSpec 工作流工具（opsx 命令和 skills） Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,113 @@
|
||||
## Why
|
||||
|
||||
构建 IoT 卡管理系统来支持三大核心业务:IoT 卡(物联网卡/流量卡)、设备(Device)、号卡(NumberCard)的全生命周期管理。系统需要支持平台自营和多级代理商分销模式、套餐订购流程和运营商订单回传处理,实现从产品分销到分佣结算的完整业务闭环。
|
||||
|
||||
**核心概念澄清**:
|
||||
- **IoT 卡** = 物联网卡 = SIM 卡 = 网卡 = 流量卡(同一个东西,不同叫法)
|
||||
- **普通卡**: 需要实名认证才能激活使用,遵循运营商实名制要求
|
||||
- **行业卡**: 不需要实名认证,可以直接激活使用,适用于企业/行业客户批量采购场景
|
||||
- **设备**:用户的物联网设备(如 GPS 追踪器、智能传感器),可绑定 1-4 张 IoT 卡,主要用于批量管理和设备操作(重启、修改密码等),不在卡管系统中销售
|
||||
- **号卡**:完全独立的业务线,从上游平台下单,不走我们平台激活和充值,只接收订单状态更新
|
||||
|
||||
## What Changes
|
||||
|
||||
- 新增 IoT 卡(IotCard)业务模型:支持 IoT 卡库存管理、平台自营销售、代理分销(分配)、套餐购买订单生成、集成 Gateway 项目 HTTP 接口获取卡状态/实名状态/流量详情/停复机操作等能力
|
||||
- 新增设备(Device)业务模型:支持用户设备管理、与 IoT 卡的绑定关系(1设备绑定1-4张IoT卡)、设备批量分配、设备操作(重启、修改密码、重置等)
|
||||
- 新增号卡(NumberCard)业务模型:支持运营商订单回传、虚拟商品编码映射、号卡代理分销和分佣、运营商侧套餐管理
|
||||
- 新增套餐(Package)管理:支持 IoT 卡套餐定义、套餐系列、真流量/虚流量共存机制、套餐订购流程、设备级套餐(流量共享)
|
||||
- 新增订单(Order)管理:支持两种订单类型(套餐订单、号卡订单)、订单状态流转、设备级套餐订单
|
||||
- 新增多级代理商分佣体系:支持树形代理关系(每个代理只有一个上级)、三种分佣类型(一次性/长期/组合)、分佣计算逻辑、梯度佣金、分佣解冻和审批流程
|
||||
- 集成现有用户体系:复用已有的平台用户、代理用户、企业用户、个人用户模型
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
#### 核心数据模型
|
||||
- `iot-card`: IoT 卡业务模型 - 定义 IoT 卡实体(物联网卡/流量卡)、卡业务类型(普通卡/行业卡,card_category)、状态、库存管理、平台自营和代理分销规则、Gateway 项目集成(状态/实名/流量/停复机)、运营商关联(carrier_id)、轮询控制字段(enable_polling、last_data_check_at、last_real_name_check_at)、行业卡无需实名认证规则
|
||||
- `iot-device`: 设备业务模型 - 定义设备实体、用户设备管理、IoT 卡绑定关系(1设备绑定1-4张IoT卡)、设备操作接口(重启/修改密码/重置)、设备批量分配
|
||||
- `iot-number-card`: 号卡业务模型 - 定义号卡实体、虚拟商品编码、运营商订单映射、代理分销和分佣规则(下单即冻结、次月导入Excel解冻)
|
||||
- `iot-package`: 套餐管理 - 定义套餐实体(只适用于IoT卡)、套餐系列关联(series_id)、真流量/虚流量共存机制(real_data_mb+virtual_data_mb)、停机判断规则(基于虚流量)、设备级套餐(流量共享)
|
||||
- `iot-order`: 订单管理 - 定义订单实体、订单类型(1-套餐订单 2-号卡订单)、订单状态流转、设备级套餐订单支持
|
||||
- `iot-agent-commission`: 代理分佣 - 定义代理树形关系、分佣规则(一次性/长期/组合,series_id用于一次性分佣,package_id用于长期分佣)、分佣计算逻辑、梯度佣金(号卡:激活量;IoT卡:激活量+提货量)、分佣解冻条件(行业卡无需实名认证即可解冻),组合佣金:时间点 OR 套餐周期阈值、结算流程
|
||||
|
||||
#### 财务和账户管理
|
||||
- `iot-commission-withdrawal`: 佣金提现管理 - 代理佣金提现申请、审批流程、提现记录查询
|
||||
- `iot-commission-withdrawal-settings`: 佣金提现设置 - 提现参数配置(最低金额、手续费率、到账时间等)
|
||||
- `iot-financial-account`: 我的账户 - 查询当前登录账号的佣金数据(可提现余额、冻结金额、累计收入等)
|
||||
- `iot-payment-merchant-settings`: 收款商户设置 - 配置支付参数(支付宝、微信等收款账户)
|
||||
- `iot-dev-capability-management`: 开发能力管理 - 管理 API 对接参数(AppID、AppSecret、回调地址等)
|
||||
- `iot-commission-template-management`: 分佣模板管理 - 创建和管理分佣模板,快速为代理分配产品时设置佣金规则
|
||||
|
||||
#### 商品管理
|
||||
- `iot-number-card-management`: 号卡管理 - 新增和管理号卡商品基础信息(虚拟商品编码、运营商、套餐类型等)
|
||||
- `iot-number-card-allocation`: 号卡分配 - 为特定代理分配号卡商品,设置佣金模式(一次性/长期/组合)
|
||||
- `iot-package-series-management`: 套餐系列管理 - 新增和管理套餐系列(用于分组和佣金规则配置)
|
||||
- `iot-package-management`: 套餐管理 - 新增和管理套餐(只能看到自己的套餐;管理员可以看到全部)
|
||||
- `iot-package-allocation`: 套餐分配 - 为直属下级代理分配套餐,设置佣金模式
|
||||
|
||||
#### 资产管理
|
||||
- `iot-single-card-info`: 单卡信息查询 - 通过 ICCID 查询单卡详细信息,提供操作入口(套餐充值、停复机、流量详情、更改过期时间、转新卡、停复机记录、往期订单、增减流量、变更钱包余额、充值支付密码、续充、设备操作)
|
||||
- `iot-card-asset-management`: IoT 卡资产管理 - 查询 IoT 卡信息,提供批量操作入口(批量分配、批量激活、批量停复机等)
|
||||
- `iot-device-asset-management`: 设备资产管理 - 查看设备信息,提供操作入口,查看和修改设备绑定的 IoT 卡信息,执行设备相关操作(重启、修改密码、重置)
|
||||
- `iot-asset-allocation`: 资产分配 - 为特定代理批量分配 IoT 卡或设备(支持设备批量分配和 IoT 卡批量分配;设备分配时自动分配绑定的所有 IoT 卡)
|
||||
- `iot-card-replacement-request`: 换卡申请管理 - 客户提交的换卡申请管理,处理换卡申请,填充新的 ICCID
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
无 - 本次变更为新增能力,不修改现有能力的需求。已有的用户体系(`user-organization`, `auth`, `role-permission`)将被复用,但不修改其规范。
|
||||
|
||||
## Impact
|
||||
|
||||
**新增数据模型**:
|
||||
- 运营商(Carrier)表及 GORM 模型 - 运营商基础信息(中国移动、中国联通、中国电信)
|
||||
- IoT 卡(IotCard)表及 GORM 模型 - 物联网卡/流量卡的统一管理
|
||||
- 设备(Device)表及 GORM 模型 - 用户设备管理
|
||||
- 设备-IoT卡绑定关系(DeviceSimBinding)表及 GORM 模型
|
||||
- 号卡(NumberCard)表及 GORM 模型
|
||||
- 套餐系列(PackageSeries)表及 GORM 模型
|
||||
- 套餐(Package)表及 GORM 模型
|
||||
- 代理套餐分配(AgentPackageAllocation)表及 GORM 模型
|
||||
- 套餐使用情况(PackageUsage)表及 GORM 模型 - 跟踪单卡套餐和设备级套餐的流量使用
|
||||
- 轮询配置(PollingConfig)表及 GORM 模型 - 支持梯度轮询策略(实名检查、卡流量检查、套餐流量检查)
|
||||
- 流量使用记录(DataUsageRecord)表及 GORM 模型 - 记录卡的流量历史,支持流量查询和分析
|
||||
- 订单(Order)表及 GORM 模型
|
||||
- 代理层级关系(AgentHierarchy)表及 GORM 模型
|
||||
- 分佣规则(CommissionRule)表及 GORM 模型
|
||||
- 阶梯分佣配置(CommissionLadder)表及 GORM 模型
|
||||
- 组合分佣条件(CommissionCombinedCondition)表及 GORM 模型
|
||||
- 分佣记录(CommissionRecord)表及 GORM 模型
|
||||
- 分佣审批(CommissionApproval)表及 GORM 模型
|
||||
- 分佣模板(CommissionTemplate)表及 GORM 模型
|
||||
- 号卡运营商结算(CarrierSettlement)表及 GORM 模型
|
||||
- 佣金提现申请(CommissionWithdrawalRequest)表及 GORM 模型
|
||||
- 佣金提现设置(CommissionWithdrawalSetting)表及 GORM 模型
|
||||
- 收款商户设置(PaymentMerchantSetting)表及 GORM 模型
|
||||
- 开发能力配置(DevCapabilityConfig)表及 GORM 模型
|
||||
- 换卡申请(CardReplacementRequest)表及 GORM 模型
|
||||
|
||||
**系统集成**:
|
||||
- 依赖现有用户体系(`user_organizations`, `users`, `roles`, `permissions` 等表)
|
||||
- 需要支持三个前端入口:Web 后台(平台+代理)、H5代理/企业端、H5客户端
|
||||
- 集成 Gateway 项目 HTTP 接口:SIM 卡状态查询、实名状态查询、流量详情查询、停复机操作等
|
||||
|
||||
**业务流程**:
|
||||
- IoT 卡的平台自营销售流程和代理分销流程
|
||||
- 设备的用户管理流程(添加设备、绑定IoT卡、设备操作)
|
||||
- 设备的批量分配流程(运营人员分配设备给代理,自动分配绑定的所有IoT卡)
|
||||
- 套餐购买订单流程(单卡套餐订单、设备级套餐订单)
|
||||
- 设备级套餐流量共享机制(套餐分配到设备绑定的所有IoT卡,流量共享)
|
||||
- 号卡的虚拟商品编码映射和运营商订单回传
|
||||
- 多级代理分佣计算和结算流程:
|
||||
- IoT 卡分佣:一次性佣金(实名+充值+购买套餐)、长期佣金(购买套餐)、组合佣金(时间点 OR 套餐周期阈值)
|
||||
- 号卡分佣:下单即冻结,次月导入Excel解冻
|
||||
- 分佣解冻和审批流程
|
||||
|
||||
**明确排除的范围**(本阶段不涉及):
|
||||
- API 层(Handlers)
|
||||
- 业务逻辑层(Services)
|
||||
- 计费系统实现(Billing Engine)
|
||||
- 供应管理集成(Provisioning)
|
||||
- 事件系统集成(Events)
|
||||
- 单元测试和集成测试
|
||||
- API 文档生成
|
||||
Reference in New Issue
Block a user