huang
034f00e2e7
- 添加 IoT 核心业务表：运营商、IoT 卡、设备、号卡、套餐、订单等 - 添加分佣系统表：分佣规则、分佣记录、运营商结算等 - 添加轮询和流量管理表：轮询配置、流量使用记录等 - 添加财务和系统管理表：佣金提现、换卡申请等 - 实现完整的 GORM 模型和常量定义 - 添加数据库迁移脚本和详细文档 - 集成 OpenSpec 工作流工具（opsx 命令和 skills） Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
492 lines
12 KiB
Markdown
492 lines
12 KiB
Markdown
# 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
|