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

12 KiB

Raw Blame History

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

项目信息

项目名称: IoT SIM 管理系统 - 数据模型层
实施日期: 2026-01-12
实施人员: Claude Sonnet 4.5
OpenSpec 变更 ID: iot-sim-management

实施范围

本次实施严格按照 OpenSpec 规范,仅完成数据模型层的实现,包括:

✅ 已完成

数据库迁移脚本
- UP 迁移脚本 (000005_create_iot_sim_management_tables.up.sql)
- DOWN 迁移脚本 (000005_create_iot_sim_management_tables.down.sql)
- 26 张数据库表
- 完整的索引定义
- 中文注释
- 三大运营商初始数据
GORM 模型定义
- 11 个模型文件
- 26 个模型结构体
- 遵循项目规范的字段定义
- 无外键约束,无 ORM 关联
业务常量定义
- 100+ 业务常量
- 5 大分类
- 统一常量管理
代码质量保证
- go fmt 格式化
- goimports 导入整理
- golangci-lint 质量检查(0 issues)
- go build 编译通过
数据库迁移测试
- UP 迁移成功 (616ms)
- DOWN 迁移成功 (602ms)
- 版本切换正确
完整文档
- 数据模型总结.md
- 表结构详细说明.md
- 轮询机制说明.md
- 分佣系统说明.md
- 实施总结.md (本文档)

❌ 不在本阶段范围

根据 OpenSpec 规范,以下工作不在本阶段实施范围:

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

数据库表清单

核心业务表 (4张)

表名	说明	记录数
carriers	运营商	3 (预置)
iot_cards	IoT 卡	0
devices	设备	0
number_cards	号卡	0

套餐与流量管理表 (7张)

表名	说明	记录数
package_series	套餐系列	0
packages	套餐	0
agent_package_allocations	代理套餐分配	0
device_sim_bindings	设备-IoT卡绑定	0
package_usages	套餐使用情况	0
polling_configs	轮询配置	0
data_usage_records	流量使用记录	0

订单管理表 (1张)

表名	说明	记录数
orders	订单	0

分佣系统表 (8张)

表名	说明	记录数
agent_hierarchies	代理层级关系	0
commission_rules	分佣规则	0
commission_ladder	分佣阶梯	0
commission_combined_conditions	组合分佣条件	0
commission_records	分佣记录	0
commission_approvals	分佣审批	0
commission_templates	分佣模板	0
carrier_settlements	运营商结算	0

财务管理表 (3张)

表名	说明	记录数
commission_withdrawal_requests	提现申请	0
commission_withdrawal_settings	提现设置	0
payment_merchant_settings	收款商户设置	0

系统管理表 (2张)

表名	说明	记录数
dev_capability_configs	开发能力配置	0
card_replacement_requests	换卡申请	0

总计: 26 张表

文件清单

数据库迁移脚本

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

GORM 模型文件

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

总计: 11 个文件, 594 行代码

常量定义文件

pkg/constants/
└── iot.go (164 行)

文档文件

docs/iot-sim-management/
├── 数据模型总结.md
├── 表结构详细说明.md
├── 轮询机制说明.md
├── 分佣系统说明.md
└── 实施总结.md (本文档)

核心技术特性

1. 无外键约束设计

数据库表之间没有外键约束
关联关系通过存储关联 ID 字段手动维护
提高灵活性和性能
便于分布式扩展

2. GORM 模型规范

所有字段显式指定 column: 标签
禁止使用 ORM 关联关系
所有字段添加中文注释
字符串字段明确长度
数值字段明确精度

3. 多所有者模式

owner_type + owner_id 实现多态所有权
支持 platform/agent/user/device 四种所有者类型
灵活管理资源所有权

4. 三层轮询机制

实名检查进程
卡流量检查进程
套餐流量检查进程
支持梯度轮询策略
独立的轮询配置

5. 三种分佣模式

一次性分佣 (立即发放)
长期分佣 (冻结后发放)
组合分佣 (部分立即,部分冻结)
OR 条件解冻 (时间 OR 流量)
阶梯奖励机制

6. 真流量/虚流量共存

真流量额度 (real_data_mb)
虚流量额度 (virtual_data_mb)
总流量额度 (data_amount_mb)
停机判断基于虚流量

7. 行业卡 vs 普通卡

行业卡无需实名认证
普通卡必须实名才能激活
通过 card_category 字段区分

代码质量指标

编译和格式化

✅ go fmt 格式化通过
✅ goimports 导入整理通过
✅ go build 编译通过
✅ go mod tidy 依赖管理通过

静态分析

✅ golangci-lint run 质量检查通过
✅ 0 issues
✅ 无语法错误
✅ 无命名冲突

数据库迁移测试

✅ UP 迁移成功 (耗时 616ms)
✅ DOWN 迁移成功 (耗时 602ms)
✅ 版本切换正确 (4 → 5 → 4 → 5)
✅ 表结构验证通过

解决的问题

1. 常量命名冲突

问题: 发现订单状态常量在 constants.go 和 iot.go 中重复定义

解决方案:

将 IoT 模块的订单状态常量重命名为 IotOrderStatus*
避免与现有常量冲突
保持常量命名的一致性

2. 依赖管理

问题: github.com/lib/pq 应该作为直接依赖

解决方案:

运行 go mod tidy 添加直接依赖
确保所有依赖正确管理

关键决策记录

1. 字段命名规范

决策: 所有 GORM 模型字段必须显式指定 column: 标签

理由:

明确 Go 字段名和数据库字段名的映射关系
避免 GORM 自动转换可能带来的歧义
提高代码可读性和可维护性

2. 无外键约束

决策: 数据库表之间不建立外键约束

理由:

提高灵活性,业务逻辑完全在代码中控制
提高性能,无数据库层面的引用完整性检查开销
简化数据库 schema,迁移更容易
分布式友好,便于后续微服务拆分

3. 轮询机制设计

决策: 实现三层独立的轮询机制

理由:

实名检查、卡流量检查、套餐流量检查业务逻辑独立
可以针对不同场景设置不同的轮询间隔
提高系统可维护性和可扩展性

4. 分佣系统 OR 条件解冻

决策: 长期分佣支持时间 OR 流量两种解冻条件

理由:

提高解冻灵活性
代理满足任一条件即可获得佣金
提高代理积极性和用户留存率

性能考虑

索引设计

主键索引: 所有表的 id 字段
唯一索引:
- iccid (IoT 卡唯一标识)
- order_no (订单号)
- carrier_code (运营商编码) 等唯一字段
组合索引:
- (carrier_id, status) - IoT 卡查询优化
- (owner_type, owner_id) - 所有权查询优化
- (status, created_at) - 订单列表查询优化
单列索引:
- 外键字段
- 常用查询字段

查询优化建议

避免 N+1 查询: 在业务层使用批量查询
分页查询: 列表查询必须分页,避免一次性加载大量数据
异步任务: 使用 Asynq 处理轮询任务,避免阻塞主线程
缓存策略: 运营商信息、套餐信息等静态数据可以缓存

安全考虑

1. 数据脱敏

敏感信息(API 凭证、账户信息)使用 JSONB 存储
业务层需要实现加密/解密逻辑

2. 权限控制

数据权限通过 owner_type + owner_id 实现
业务层需要实现权限检查逻辑

3. 审计日志

所有表包含 created_at 和 updated_at 时间戳
关键操作(分佣审批、提现审批)记录审批人 ID

后续工作建议

根据 OpenSpec 规范,数据模型层完成后,建议按以下顺序进行后续开发:

1. Store 数据访问层

实现 GORM 数据访问接口
实现事务管理
实现查询优化

2. Service 业务逻辑层

实现核心业务逻辑
实现轮询调度器
实现分佣计算引擎
实现运营商 Gateway 对接

3. Handler API 层

实现 RESTful API 接口
实现参数验证
实现错误处理

4. 测试

单元测试
集成测试
性能测试

5. 文档

API 文档
部署文档
运维手册

团队协作建议

1. 代码审查要点

检查是否遵循项目规范
检查是否有外键约束或 ORM 关联
检查字段命名是否符合规范
检查常量是否统一管理

2. 数据库变更流程

所有数据库变更必须通过迁移脚本
迁移脚本必须同时编写 UP 和 DOWN
迁移脚本必须在测试环境验证后才能上生产

3. 文档维护

数据模型变更时同步更新文档
文档使用中文编写,便于团队理解
文档放在 docs/ 目录统一管理

风险和挑战

1. 无外键约束的数据一致性

风险: 删除父记录时可能遗留子记录

应对措施:

在业务层实现级联删除逻辑
定期运行数据一致性检查脚本
使用软删除(status 字段)代替物理删除

2. 轮询任务性能

风险: 大量 IoT 卡可能导致轮询任务堆积

应对措施:

使用 Asynq 任务队列,支持横向扩展
实现限流保护,避免过度调用运营商 API
根据卡状态动态调整轮询间隔

3. 分佣计算复杂度

风险: 多级代理分佣计算可能影响性能

应对措施:

使用异步任务处理分佣计算
实现分佣计算缓存
定期优化分佣计算逻辑

总结

本次实施严格按照 OpenSpec 规范完成了 IoT SIM 管理系统的数据模型层实现,包括 26 张数据库表、11 个 GORM 模型文件、100+ 业务常量,以及完整的文档。

成果总结

✅ 数据库迁移脚本 (UP + DOWN)
✅ GORM 模型定义 (11 个文件, 594 行代码)
✅ 业务常量定义 (164 行代码)
✅ 代码质量保证 (0 issues)
✅ 数据库迁移测试通过
✅ 完整技术文档 (5 个文档)

技术亮点

无外键约束设计: 提高灵活性和性能
三层轮询机制: 实名检查、卡流量检查、套餐流量检查相互独立
三种分佣模式: 一次性、长期、组合分佣,支持 OR 条件解冻
多所有者模式: 统一管理资源所有权
真流量/虚流量共存: 灵活的流量管理机制
行业卡支持: 区分行业卡和普通卡的不同业务流程

遵循的规范

✅ Go 代码风格规范 (Effective Go)
✅ GORM 模型规范 (显式 column 标签, 无 ORM 关联)
✅ 数据库设计规范 (无外键约束, 完整索引)
✅ 常量管理规范 (统一定义, 分类管理)
✅ 文档规范 (中文编写, 结构清晰)
✅ OpenSpec 流程规范 (只实现数据模型层)

实施完成时间: 2026-01-12 实施人员: Claude Sonnet 4.5 文档版本: v1.0

12 KiB Raw Blame History

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

项目信息

实施范围

✅ 已完成

❌ 不在本阶段范围

数据库表清单

核心业务表 (4张)

套餐与流量管理表 (7张)

订单管理表 (1张)

分佣系统表 (8张)

财务管理表 (3张)

系统管理表 (2张)

文件清单

数据库迁移脚本

GORM 模型文件

常量定义文件

文档文件

核心技术特性

1. 无外键约束设计

2. GORM 模型规范

3. 多所有者模式

4. 三层轮询机制

5. 三种分佣模式

6. 真流量/虚流量共存

7. 行业卡 vs 普通卡

代码质量指标

编译和格式化

静态分析

数据库迁移测试

解决的问题

1. 常量命名冲突

2. 依赖管理

关键决策记录

1. 字段命名规范

2. 无外键约束

3. 轮询机制设计

4. 分佣系统 OR 条件解冻

性能考虑

索引设计

查询优化建议

安全考虑

1. 数据脱敏

2. 权限控制

3. 审计日志

后续工作建议

1. Store 数据访问层

2. Service 业务逻辑层

3. Handler API 层

4. 测试

5. 文档

团队协作建议

1. 代码审查要点

2. 数据库变更流程

3. 文档维护

风险和挑战

1. 无外键约束的数据一致性

2. 轮询任务性能

3. 分佣计算复杂度

总结

成果总结

技术亮点

遵循的规范

12 KiB

Raw Blame History