csxj2026/junhong_cmp_fiber

Files

huang 034f00e2e7 实现 IoT SIM 管理模块数据模型和数据库结构

- 添加 IoT 核心业务表：运营商、IoT 卡、设备、号卡、套餐、订单等
- 添加分佣系统表：分佣规则、分佣记录、运营商结算等
- 添加轮询和流量管理表：轮询配置、流量使用记录等
- 添加财务和系统管理表：佣金提现、换卡申请等
- 实现完整的 GORM 模型和常量定义
- 添加数据库迁移脚本和详细文档
- 集成 OpenSpec 工作流工具（opsx 命令和 skills）

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-01-12 15:44:23 +08:00

18 KiB

Raw Blame History

IoT SIM 管理系统 - 数据模型总结

概述

本文档总结了 IoT SIM 管理系统的数据模型层实现,包括 26 张数据库表和对应的 GORM 模型定义。

实现范围

✅ 数据库迁<E5BA93><E8BF81><EFBFBD>脚本 (migrations/000005_create_iot_sim_management_tables.up/down.sql)
✅ GORM 模型定义 (internal/iot/model/*.go)
✅ 业务常量定义 (pkg/constants/iot.go)
❌ API Handler 层 (不在本阶段范围)
❌ Service 业务逻辑层 (不在本阶段范围)
❌ Store 数据访问层 (不在本阶段范围)

核心业务实体

1. 运营商管理 (Carrier)

表名: carriers

核心字段:

carrier_code: 运营商编码 (CMCC/CUCC/CTCC)
carrier_name: 运营商名称 (中国移动/中国联通/中国电信)
api_endpoint: API 接口地址
api_credentials: API 凭证 (JSONB)

预置数据: 初始化三大运营商数据

文件位置: internal/iot/model/carrier.go:5

2. IoT 卡管理 (IotCard)

表名: iot_cards

核心字段:

iccid: IoT 卡唯一标识 (20 位数字)
card_category: 卡业务类型 (normal-普通卡, industry-行业卡)
carrier_id: 所属运营商 ID
owner_type: 所有者类型 (platform/agent/user/device)
owner_id: 所有者 ID
activation_status: 激活状态 (0-未激活, 1-已激活)
real_name_status: 实名状态 (0-未实名, 1-已实名)
network_status: 网络状态 (0-停机, 1-开机)
enable_polling: 是否参与轮询

特殊机制:

支持行业卡(无需实名)和普通卡(需实名)
多所有者模式 (owner_type + owner_id)
轮询开关控制 (enable_polling)
流量使用累计 (data_usage_mb)
Gateway 同步时间戳 (last_sync_time)

文件位置: internal/iot/model/iot_card.go:8

3. 设备管理 (Device)

表名: devices

核心字段:

device_code: 设备唯一编码
device_name: 设备名称
device_type: 设备类型
sim_slots: SIM 卡槽数量 (1-4)
owner_type: 所有者类型 (platform/agent/user)
owner_id: 所有者 ID

关联关系:

通过 device_sim_bindings 表关联 1-4 张 IoT 卡

文件位置: internal/iot/model/device.go:5

4. 号卡管理 (NumberCard)

表名: number_cards

核心字段:

virtual_product_code: 虚拟商品编码 (用于对应运营商订单)
card_name: 号卡名称
carrier: 运营商
data_amount_mb: 流量额度 (MB)
price: 价格 (元)

业务说明: 号卡是完全独立的业务线,从上游平台下单,使用虚拟商品编码映射运营商订单。

文件位置: internal/iot/model/number_card.go:8

套餐与流量管理

5. 套餐系列 (PackageSeries)

表名: package_series

核心字段:

series_code: 系列编码
series_name: 系列名称
description: 描述

用途: 套餐分组,用于一次性分佣规则配置。

文件位置: internal/iot/model/package.go:7

6. 套餐 (Package)

表名: packages

核心字段:

package_code: 套餐编码
package_name: 套餐名称
series_id: 所属套餐系列 ID
package_type: 套餐类型 (formal-正式套餐, addon-附加套餐)
duration_months: 套餐时长 (月数)
data_type: 流量类型 (real-真流量, virtual-虚流量)
real_data_mb: 真流量额度 (MB)
virtual_data_mb: 虚流量额度 (MB)
data_amount_mb: 总流量额度 (MB)
price: 套餐价格 (元)

特殊机制:

支持真流量/虚流量共存
停机判断基于虚流量
支持正式套餐和附加套餐

文件位置: internal/iot/model/package.go:23

7. 代理套餐分配 (AgentPackageAllocation)

表名: agent_package_allocations

核心字段:

agent_id: 代理用户 ID
package_id: 套餐 ID
cost_price: 成本价 (元)
retail_price: 零售价 (元)

用途: 为直属下级代理分配套餐,设置佣金模式。

文件位置: internal/iot/model/package.go:48

8. 设备-IoT 卡绑定 (DeviceSimBinding)

表名: device_sim_bindings

核心字段:

device_id: 设备 ID
iot_card_id: IoT 卡 ID
slot_position: 插槽位置 (1, 2, 3, 4)
bind_status: 绑定状态 (1-已绑定, 2-已解绑)
bind_time: 绑定时间
unbind_time: 解绑时间

用途: 管理设备与 IoT 卡的多对多绑定关系 (1 设备绑定 1-4 张 IoT 卡)。

文件位置: internal/iot/model/package.go:66

9. 套餐使用情况 (PackageUsage)

表名: package_usages

核心字段:

order_id: 订单 ID
package_id: 套餐 ID
usage_type: 使用类型 (single_card-单卡套餐, device-设备级套餐)
iot_card_id: IoT 卡 ID (单卡套餐时有值)
device_id: 设备 ID (设备级套餐时有值)
data_limit_mb: 流量限额 (MB)
data_usage_mb: 已使用流量 (MB)
real_data_usage_mb: 真流量使用 (MB)
virtual_data_usage_mb: 虚流量使用 (MB)
activated_at: 套餐生效时间
expires_at: 套餐过期时间
status: 状态 (1-生效中, 2-已用完, 3-已过期)
last_package_check_at: 最后一次套餐流量检查时间

用途: 跟踪单卡套餐和设备级套餐的流量使用。

文件位置: internal/iot/model/package.go:85

10. 轮询配置 (PollingConfig)

表名: polling_configs

核心字段:

config_name: 配置名称 (如未实名卡、实名卡)
card_condition: 卡状态条件 (not_real_name/real_name/activated/suspended)
carrier_id: 运营商 ID (NULL 表示所有运营商)
real_name_check_enabled: 是否启用实名检查
real_name_check_interval: 实名检查间隔 (秒)
card_data_check_enabled: 是否启用卡流量检查
card_data_check_interval: 卡流量检查间隔 (秒)
package_check_enabled: 是否启用套餐流量检查
package_check_interval: 套餐流量检查间隔 (秒)
priority: 优先级 (数字越小优先级越高)

特殊机制: 支持梯度轮询策略 (实名检查、卡流量检查、套餐流量检查)。

文件位置: internal/iot/model/polling.go:7

11. 流量使用记录 (DataUsageRecord)

表名: data_usage_records

核心字段:

iot_card_id: IoT 卡 ID
usage_date: 使用日期
data_usage_mb: 流量使用 (MB)
carrier_sync_data: 运营商同步数据 (JSONB)
synced_at: 同步时间

用途: 记录 IoT 卡每日流量使用情况 (历史数据)。

文件位置: internal/iot/model/data_usage.go:5

订单管理

12. 订单 (Order)

表名: orders

核心字段:

order_no: 订单号 (唯一标识)
order_type: 订单类型 (1-套餐订单, 2-号卡订单)
iot_card_id: IoT 卡 ID (单卡套餐订单时有值)
device_id: 设备 ID (设备级套餐订单时有值)
number_card_id: 号卡 ID (号卡订单时有值)
package_id: 套餐 ID (套餐订单时有值)
user_id: 用户 ID
agent_id: 代理用户 ID
amount: 订单金额 (元)
payment_method: 支付方式 (wallet/online/carrier)
status: 状态 (1-待支付, 2-已支付, 3-已完成, 4-已取消, 5-已退款)
carrier_order_id: 运营商订单 ID
carrier_order_data: 运营商订单原始数据 (JSONB)

支持场景:

套餐订单 (单卡套餐 / 设备级套餐)
号卡订单

文件位置: internal/iot/model/order.go:11

分佣系统

13. 代理层级关系 (AgentHierarchy)

表名: agent_hierarchies

核心字段:

agent_id: 代理用户 ID
parent_agent_id: 上级代理用户 ID
agent_level: 代理层级 (1-一级代理, 2-二级代理, ...)
agent_path: 代理路径 (如 /1/2/3/)

用途: 管理代理的树形层级关系。

文件位置: internal/iot/model/commission.go:8

14. 分佣规则 (CommissionRule)

表名: commission_rules

核心字段:

rule_name: 规则名称
rule_type: 规则类型 (one_time-一次性分佣, long_term-长期分佣, combined-组合分佣)
package_series_id: 套餐系列 ID
commission_type: 分佣方式 (fixed-固定金额, percentage-百分比)
commission_value: 分佣值
target_level: 目标层级 (NULL 表示所有层级)
enable_ladder: 是否启用阶梯
freeze_days: 冻结天数 (长期分佣)
freeze_data_mb: 冻结流量 (MB, 长期分佣)
unfreeze_mode: 解冻模式 (auto-自动, manual-手动)

分佣类型说明:

一次性分佣: 订单完成后立即发放
长期分佣: 订单完成后冻结,满足解冻条件后发放
组合分佣: 同时包含一次性和长期分佣

文件位置: internal/iot/model/commission.go:24

15. 分佣阶梯 (CommissionLadder)

表名: commission_ladder

核心字段:

rule_id: 分佣规则 ID
min_quantity: 最小数量
max_quantity: 最大数量
commission_type: 分佣方式 (fixed/percentage)
commission_value: 分佣值

用途: 为分佣规则配置阶梯奖励 (订单数量越多,分佣越高)。

文件位置: internal/iot/model/commission.go:47

16. 组合分佣条件 (CommissionCombinedCondition)

表名: commission_combined_conditions

核心字段:

rule_id: 分佣规则 ID
condition_type: 条件类型 (one_time-一次性, long_term-长期)
commission_type: 分佣方式 (fixed/percentage)
commission_value: 分佣值
freeze_days: 冻结天数 (长期分佣)
freeze_data_mb: 冻结流量 (MB, 长期分佣)

用途: 定义组合分佣规则的具体条件 (一次性部分 + 长期部分)。

文件位置: internal/iot/model/commission.go:68

17. 分佣记录 (CommissionRecord)

表名: commission_records

核心字段:

order_id: 订单 ID
agent_id: 代理用户 ID
rule_id: 分佣规则 ID
commission_type: 分佣类型 (one_time/long_term/combined)
commission_amount: 分佣金额 (元)
status: 状态 (1-待发放, 2-已发放, 3-已冻结, 4-已取消)
freeze_days: 冻结天数
freeze_data_mb: 冻结流量 (MB)
unfreeze_conditions: 解冻条件 (JSONB)
unfrozen_at: 解冻时间
distributed_at: 发放时间

特殊机制: 支持 OR 条件解冻 (时间到期 OR 流量达标,满足其一即可解冻)。

文件位置: internal/iot/model/commission.go:88

18. 分佣审批 (CommissionApproval)

表名: commission_approvals

核心字段:

commission_record_id: 分佣记录 ID
agent_id: 代理用户 ID
approval_status: 审批状态 (1-待审批, 2-已通过, 3-已拒绝)
approver_id: 审批人 ID
approval_reason: 审批原因
approved_at: 审批时间

用途: 管理需要手动审批的分佣记录。

文件位置: internal/iot/model/commission.go:116

19. 分佣模板 (CommissionTemplate)

表名: commission_templates

核心字段:

template_name: 模板名称
template_data: 模板数据 (JSONB)
description: 描述

用途: 快速创建分佣规则的预设模板。

文件位置: internal/iot/model/commission.go:137

20. 运营商结算 (CarrierSettlement)

表名: carrier_settlements

核心字段:

carrier_id: 运营商 ID
settlement_month: 结算月份 (YYYY-MM)
total_orders: 总订单数
total_amount: 总金额 (元)
settlement_status: 结算状态 (1-待结算, 2-已结算, 3-已支付)
settled_at: 结算时间
paid_at: 支付时间

用途: 记录与运营商的月度结算情况。

文件位置: internal/iot/model/commission.go:155

财务管理

21. 提现申请 (CommissionWithdrawalRequest)

表名: commission_withdrawal_requests

核心字段:

agent_id: 代理用户 ID
withdrawal_amount: 提现金额 (元)
withdrawal_method: 提现方式 (bank_card/alipay/wechat)
account_info: 账户信息 (JSONB)
status: 状态 (1-待审核, 2-已通过, 3-已拒绝, 4-已打款, 5-已取消)
reviewer_id: 审核人 ID
review_reason: 审核原因
reviewed_at: 审核时间
paid_at: 打款时间

用途: 管理代理用户的佣金提现申请。

文件位置: internal/iot/model/financial.go:8

22. 提现设置 (CommissionWithdrawalSetting)

表名: commission_withdrawal_settings

核心字段:

agent_id: 代理用户 ID
min_withdrawal_amount: 最小提现金额 (元)
max_withdrawal_amount: 最大提现金额 (元)
withdrawal_fee_rate: 提现手续费率 (小数)
auto_approval_enabled: 是否启用自动审批

用途: 配置代理用户的提现规则。

文件位置: internal/iot/model/financial.go:31

23. 收款商户设置 (PaymentMerchantSetting)

表名: payment_merchant_settings

核心字段:

merchant_name: 商户名称
merchant_type: 商户类型 (alipay/wechat/bank)
merchant_config: 商户配置 (JSONB)
is_default: 是否默认商户

用途: 配置收款商户信息 (支付宝、微信、银行)。

文件位置: internal/iot/model/financial.go:51

系统管理

24. 开发能力配置 (DevCapabilityConfig)

表名: dev_capability_configs

核心字段:

capability_name: 能力名称
capability_code: 能力编码
capability_config: 能力配置 (JSONB)
description: 描述

用途: 管理系统开发能力配置 (如 API 开关、功能权限等)。

文件位置: internal/iot/model/system.go:5

25. 换卡申请 (CardReplacementRequest)

表名: card_replacement_requests

核心字段:

old_iot_card_id: 旧卡 ID
new_iot_card_id: 新卡 ID
user_id: 用户 ID
replacement_reason: 换卡原因
status: 状态 (1-待审核, 2-已通过, 3-已拒绝, 4-已完成)
reviewer_id: 审核人 ID
reviewed_at: 审核时间
completed_at: 完成时间

用途: 管理 IoT 卡的换卡申请流程。

文件位置: internal/iot/model/system.go:25

数据库设计原则

1. 无外键约束

数据库表之间禁止建立外键约束 (Foreign Key Constraints)
关联关系通过存储关联 ID 字段手动维护
关联数据查询在代码层面显式执行

设计理由:

灵活性：业务逻辑完全在代码中控制
性能：无数据库层面的引用完整性检查开销
可控性：开发者完全掌控何时查询关联数据
分布式友好：在微服务场景下更容易扩展

2. GORM 模型规范

所有字段必须显式指定 column: 标签
禁止使用 ORM 关联关系 (foreignKey, references, hasMany, belongsTo)
所有字段必须添加中文注释
字符串字段长度必须明确定义 (VARCHAR(100)/VARCHAR(255)/TEXT)
数值字段精度必须明确定义 (DECIMAL(10,2)/BIGINT)
时间字段使用 GORM 自动管理 (autoCreateTime, autoUpdateTime)

3. 命名规范

数据库字段名：下划线命名法 (snake_case)，如 user_id, created_at
Go 结构体字段名：驼峰命名法 (PascalCase)，如 UserID, CreatedAt
表名：复数形式，如 iot_cards, orders, commission_rules
常量名：大写驼峰 + 前缀，如 IotOrderStatusPending, CarrierCodeCMCC

常量定义

所有业务常量统一定义在 pkg/constants/iot.go 文件中,包括:

卡类型、卡业务类型、激活状态、实名状态、网络状态
所有者类型、卡状态、设备状态
套餐类型、流量类型、套餐使用状态
订单类型、订单状态、支付方式
轮询卡状态条件
分佣规则类型、分佣方式、分佣状态、解冻模式
提现状态、提现方式、商户类型
换卡申请状态、审批状态

文件位置: pkg/constants/iot.go:1

数据库迁移

迁移脚本

UP 脚本: migrations/000005_create_iot_sim_management_tables.up.sql
- 创建 26 张表
- 创建所有必需的索引
- 添加完整的中文注释
- 初始化三大运营商数据
DOWN 脚本: migrations/000005_create_iot_sim_management_tables.down.sql
- 按反向依赖顺序删除所有表

迁移测试

# 应用迁移
source .env && migrate -database "postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}?sslmode=${DB_SSLMODE}" -path migrations up

# 回滚迁移
source .env && migrate -database "postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}?sslmode=${DB_SSLMODE}" -path migrations down 1

# 查看版本
source .env && migrate -database "postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}?sslmode=${DB_SSLMODE}" -path migrations version

测试结果

✅ UP 迁移成功 (耗时 616ms)
✅ DOWN 迁移成功 (耗时 602ms)
✅ 数据库版本正确切换 (4 → 5 → 4 → 5)

文件清单

数据库迁移脚本

migrations/000005_create_iot_sim_management_tables.up.sql (1102 行)
migrations/000005_create_iot_sim_management_tables.down.sql (27 行)

GORM 模型定义

internal/iot/model/carrier.go (17 行)
internal/iot/model/iot_card.go (40 行)
internal/iot/model/device.go (27 行)
internal/iot/model/number_card.go (26 行)
internal/iot/model/package.go (108 行)
internal/iot/model/order.go (36 行)
internal/iot/model/polling.go (29 行)
internal/iot/model/data_usage.go (20 行)
internal/iot/model/commission.go (175 行)
internal/iot/model/financial.go (70 行)
internal/iot/model/system.go (46 行)

常量定义

pkg/constants/iot.go (164 行)

代码质量

✅ go fmt 格式化通过
✅ goimports 导入整理通过
✅ golangci-lint 质量检查通过 (0 issues)
✅ go build 编译通过
✅ go mod tidy 依赖管理通过

下一步工作

根据 OpenSpec 规范,本阶段只实现数据模型层,以下工作不在本阶段范围:

❌ API Handler 层
❌ Service 业务逻辑层
❌ Store 数据访问层
❌ 单元测试
❌ 集成测试
❌ API 文档生成

这些工作将在后续阶段按照 OpenSpec 流程逐步实现。

参考文档

文档版本: v1.0 最后更新: 2026-01-12 维护人员: Claude Sonnet 4.5

18 KiB Raw Blame History Unescape Escape

IoT SIM 管理系统 - 数据模型总结

概述

实现范围

核心业务实体

1. 运营商管理 (Carrier)

2. IoT 卡管理 (IotCard)

3. 设备管理 (Device)

4. 号卡管理 (NumberCard)

套餐与流量管理

5. 套餐系列 (PackageSeries)

6. 套餐 (Package)

7. 代理套餐分配 (AgentPackageAllocation)

8. 设备-IoT 卡绑定 (DeviceSimBinding)

9. 套餐使用情况 (PackageUsage)

10. 轮询配置 (PollingConfig)

11. 流量使用记录 (DataUsageRecord)

订单管理

12. 订单 (Order)

分佣系统

13. 代理层级关系 (AgentHierarchy)

14. 分佣规则 (CommissionRule)

15. 分佣阶梯 (CommissionLadder)

16. 组合分佣条件 (CommissionCombinedCondition)

17. 分佣记录 (CommissionRecord)

18. 分佣审批 (CommissionApproval)

19. 分佣模板 (CommissionTemplate)

20. 运营商结算 (CarrierSettlement)

财务管理

21. 提现申请 (CommissionWithdrawalRequest)

22. 提现设置 (CommissionWithdrawalSetting)

23. 收款商户设置 (PaymentMerchantSetting)

系统管理

24. 开发能力配置 (DevCapabilityConfig)

25. 换卡申请 (CardReplacementRequest)

数据库设计原则

1. 无外键约束

2. GORM 模型规范

3. 命名规范

常量定义

数据库迁移

迁移脚本

迁移测试

测试结果

文件清单

数据库迁移脚本

GORM 模型定义

常量定义

代码质量

下一步工作

参考文档

18 KiB

Raw Blame History