实现 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
parent 743db126f7
commit 034f00e2e7
48 changed files with 11675 additions and 1 deletions
--- a/docs/iot-sim-management/实施总结.md
+++ b/docs/iot-sim-management/实施总结.md
@@ -0,0 +1,491 @@
+# IoT SIM 管理系统 - 数据模型层实施总结
+
+## 项目信息
+
+- **项目名称**: IoT SIM 管理系统 - 数据模型层
+- **实施日期**: 2026-01-12
+- **实施人员**: Claude Sonnet 4.5
+- **OpenSpec 变更 ID**: iot-sim-management
+
+---
+
+## 实施范围
+
+本次实施严格按照 OpenSpec 规范,仅完成数据模型层的实现,包括:
+
+### ✅ 已完成
+
+1. **数据库迁移脚本**
+   - UP 迁移脚本 (000005_create_iot_sim_management_tables.up.sql)
+   - DOWN 迁移脚本 (000005_create_iot_sim_management_tables.down.sql)
+   - 26 张数据库表
+   - 完整的索引定义
+   - 中文注释
+   - 三大运营商初始数据
+
+2. **GORM 模型定义**
+   - 11 个模型文件
+   - 26 个模型结构体
+   - 遵循项目规范的字段定义
+   - 无外键约束,无 ORM 关联
+
+3. **业务常量定义**
+   - 100+ 业务常量
+   - 5 大分类
+   - 统一常量管理
+
+4. **代码质量保证**
+   - `go fmt` 格式化
+   - `goimports` 导入整理
+   - `golangci-lint` 质量检查(0 issues)
+   - `go build` 编译通过
+
+5. **数据库迁移测试**
+   - UP 迁移成功 (616ms)
+   - DOWN 迁移成功 (602ms)
+   - 版本切换正确
+
+6. **完整文档**
+   - 数据模型总结.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 流量两种解冻条件
+
+**理由**:
+- 提高解冻灵活性
+- 代理满足任一条件即可获得佣金
+- 提高代理积极性和用户留存率
+
+---
+
+## 性能考虑
+
+### 索引设计
+
+1. **主键索引**: 所有表的 `id` 字段
+2. **唯一索引**:
+   - `iccid` (IoT 卡唯一标识)
+   - `order_no` (订单号)
+   - `carrier_code` (运营商编码)
+   等唯一字段
+3. **组合索引**:
+   - `(carrier_id, status)` - IoT 卡查询优化
+   - `(owner_type, owner_id)` - 所有权查询优化
+   - `(status, created_at)` - 订单列表查询优化
+4. **单列索引**:
+   - 外键字段
+   - 常用查询字段
+
+### 查询优化建议
+
+1. **避免 N+1 查询**: 在业务层使用批量查询
+2. **分页查询**: 列表查询必须分页,避免一次性加载大量数据
+3. **异步任务**: 使用 Asynq 处理轮询任务,避免阻塞主线程
+4. **缓存策略**: 运营商信息、套餐信息等静态数据可以缓存
+
+---
+
+## 安全考虑
+
+### 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 个文档)
+
+### 技术亮点
+
+1. **无外键约束设计**: 提高灵活性和性能
+2. **三层轮询机制**: 实名检查、卡流量检查、套餐流量检查相互独立
+3. **三种分佣模式**: 一次性、长期、组合分佣,支持 OR 条件解冻
+4. **多所有者模式**: 统一管理资源所有权
+5. **真流量/虚流量共存**: 灵活的流量管理机制
+6. **行业卡支持**: 区分行业卡和普通卡的不同业务流程
+
+### 遵循的规范
+
+- ✅ Go 代码风格规范 (Effective Go)
+- ✅ GORM 模型规范 (显式 column 标签, 无 ORM 关联)
+- ✅ 数据库设计规范 (无外键约束, 完整索引)
+- ✅ 常量管理规范 (统一定义, 分类管理)
+- ✅ 文档规范 (中文编写, 结构清晰)
+- ✅ OpenSpec 流程规范 (只实现数据模型层)
+
+---
+
+**实施完成时间**: 2026-01-12
+**实施人员**: Claude Sonnet 4.5
+**文档版本**: v1.0