junhong_cmp_fiber/openspec/changes/archive/2026-01-12-fix-iot-models-violations/proposal.md

## Why

在之前的 IoT SIM 管理系统提案（2026-01-12-iot-sim-management）中创建的所有数据模型存在严重的架构违规问题，完全没有遵循项目的核心开发规范。这些违规导致代码不一致、可维护性差、违背项目设计原则。

**核心问题：**

1. **未使用基础模型**：所有 IoT 模型都没有嵌入 `BaseModel`，缺少统一的 `creator` 和 `updater` 字段
2. **未使用 gorm.Model**：部分模型没有嵌入 `gorm.Model`，缺少标准的 `ID`、`CreatedAt`、`UpdatedAt`、`DeletedAt` 字段
3. **字段命名不规范**：未显式指定 `column` 标签，依赖 GORM 自动转换（违反规范）
4. **字段定义不完整**：缺少必要的数据库约束标签（`not null`、`uniqueIndex`、索引等）
5. **数据类型不一致**：
   - 货币字段使用 `float64` 而不是整数（分为单位）
   - ID 字段类型不一致（`uint` vs `bigint`）
   - 时间字段缺少 `autoCreateTime`/`autoUpdateTime` 标签
6. **表名不符合规范**：使用复数形式（`iot_cards`）而不是项目约定的 `tb_` 前缀单数形式
7. **缺少中文注释**：部分字段缺少清晰的中文注释说明业务含义
8. **软删除支持不一致**：某些应该支持软删除的模型缺少 `gorm.Model` 嵌入

**对比现有规范模型（Account、PersonalCustomer）：**

✅ **正确示例（Account 模型）：**
```go
type Account struct {
    gorm.Model                    // ✅ 嵌入标准模型（ID、CreatedAt、UpdatedAt、DeletedAt）
    BaseModel    `gorm:"embedded"` // ✅ 嵌入基础模型（Creator、Updater）
    Username     string `gorm:"column:username;type:varchar(50);uniqueIndex:idx_account_username,where:deleted_at IS NULL;not null;comment:用户名" json:"username"`
    // ✅ 显式 column 标签
    // ✅ 明确类型和长度
    // ✅ 唯一索引 + 软删除过滤
    // ✅ not null 约束
    // ✅ 中文注释
}

func (Account) TableName() string {
    return "tb_account" // ✅ tb_ 前缀 + 单数
}
```

❌ **错误示例（IotCard 模型）：**
```go
type IotCard struct {
    ID uint `gorm:"column:id;primaryKey;comment:IoT 卡 ID" json:"id"`
    // ❌ 没有 gorm.Model
    // ❌ 没有 BaseModel
    // ❌ 手动定义 ID（应该由 gorm.Model 提供）
    // ❌ 没有 DeletedAt（无法软删除）

    CostPrice float64 `gorm:"column:cost_price;type:decimal(10,2);default:0;comment:成本价(元)" json:"cost_price"`
    // ❌ 使用 float64 而不是整数（分为单位）

    CreatedAt time.Time `gorm:"column:created_at;autoCreateTime;comment:创建时间" json:"created_at"`
    UpdatedAt time.Time `gorm:"column:updated_at;autoUpdateTime;comment:更新时间" json:"updated_at"`
    // ❌ 手动定义（应该由 gorm.Model 提供）
}

func (IotCard) TableName() string {
    return "iot_cards" // ❌ 复数形式，没有 tb_ 前缀
}
```

**影响范围：**

需要修复以下所有 IoT 相关模型（约 25 个模型文件）：
- `internal/model/iot_card.go`（IotCard）
- `internal/model/device.go`（Device、DeviceSimBinding）
- `internal/model/number_card.go`（NumberCard）
- `internal/model/package.go`（PackageSeries、Package、AgentPackageAllocation、PackageUsage）
- `internal/model/order.go`（Order）
- `internal/model/commission.go`（AgentHierarchy、CommissionRule、CommissionLadder、CommissionCombinedCondition、CommissionRecord、CommissionApproval、CommissionTemplate、CarrierSettlement）
- `internal/model/financial.go`（CommissionWithdrawalRequest、CommissionWithdrawalSetting、PaymentMerchantSetting）
- `internal/model/system.go`（DevCapabilityConfig、CardReplacementRequest）
- `internal/model/carrier.go`（Carrier）
- `internal/model/data_usage.go`（DataUsageRecord）
- `internal/model/polling.go`（PollingConfig）

## What Changes

- 重构所有 IoT 相关数据模型，使其完全符合项目开发规范
- 统一所有模型的字段定义、类型、约束、注释格式
- 确保所有模型与现有用户体系模型（Account、PersonalCustomer）保持一致的架构风格
- 更新数据库迁移脚本以反映模型变更

## Capabilities

### Modified Capabilities

#### 核心数据模型规范化

- `iot-card`: 修改 IoT 卡业务模型 - 统一字段定义，嵌入 BaseModel 和 gorm.Model，修正表名为 `tb_iot_card`，使用整数存储金额，完善索引和约束
- `iot-device`: 修改设备业务模型 - 统一字段定义，嵌入 BaseModel 和 gorm.Model，修正表名为 `tb_device`，规范化所有关联字段
- `iot-number-card`: 修改号卡业务模型 - 统一字段定义，嵌入 BaseModel 和 gorm.Model，修正表名为 `tb_number_card`，使用整数存储金额
- `iot-package`: 修改套餐管理模型 - 统一字段定义，嵌入 BaseModel 和 gorm.Model，修正表名（`tb_package_series`、`tb_package`、`tb_agent_package_allocation`、`tb_package_usage`），使用整数存储金额
- `iot-order`: 修改订单管理模型 - 统一字段定义，嵌入 BaseModel 和 gorm.Model，修正表名为 `tb_order`，使用整数存储金额，规范化 JSONB 字段
- `iot-agent-commission`: 修改代理分佣模型 - 统一所有分佣相关模型字段定义，嵌入 BaseModel 和 gorm.Model，修正表名（添加 `tb_` 前缀），使用整数存储金额

#### 财务和系统模型规范化

- 修改财务相关模型（CommissionWithdrawalRequest、CommissionWithdrawalSetting、PaymentMerchantSetting）- 统一字段定义，使用整数存储金额，完善索引和约束
- 修改系统配置模型（DevCapabilityConfig、CardReplacementRequest）- 统一字段定义，嵌入 BaseModel 和 gorm.Model
- 修改运营商模型（Carrier）- 统一字段定义，嵌入 BaseModel 和 gorm.Model，修正表名为 `tb_carrier`
- 修改流量记录模型（DataUsageRecord）- 统一字段定义，嵌入 gorm.Model，修正表名为 `tb_data_usage_record`
- 修改轮询配置模型（PollingConfig）- 统一字段定义，嵌入 BaseModel 和 gorm.Model，修正表名为 `tb_polling_config`

## Impact

**代码变更：**
- 重构约 25 个 GORM 模型文件（`internal/model/`）
- 所有模型的字段定义将发生变化（字段名、类型、标签）
- 所有表名将从复数变为 `tb_` 前缀单数形式

**数据库变更：**
- 需要生成新的数据库迁移脚本以反映模型变更
- 表名变更（如 `iot_cards` → `tb_iot_card`）
- 字段变更（如 `cost_price DECIMAL` → `cost_price BIGINT`，金额从元改为分）
- 新增字段（`creator`、`updater`、`deleted_at`）
- 新增索引和约束

**向后兼容性：**
- ❌ **不兼容变更**：此次修复涉及破坏性变更（表名、字段类型）
- 由于 IoT 模块尚未实际部署到生产环境，可以直接修改而无需数据迁移
- 如果已有测试数据，需要编写数据迁移脚本

**业务影响：**
- 不影响现有用户体系（Account、Role、Permission 等）
- 不影响个人客户模块（PersonalCustomer）
- IoT 模块的 Service 层和 Handler 层代码需要相应调整（字段类型变化）

**依赖关系：**
- 必须在实现 IoT 业务逻辑（Handlers、Services、Stores）之前修复
- 修复后才能生成正确的数据库迁移脚本
- 修复后才能生成准确的 API 文档

**文档变更：**
- 更新 `CLAUDE.md` 中的数据库设计原则和 GORM 模型字段规范
- 补充完整的字段定义规范（显式 column 标签、类型定义、注释要求）
- 添加金额字段整数存储的详细说明和示例
- 完善表名命名规范和 BaseModel 使用说明
- 确保全局规范文档与实际实现保持一致

**明确排除的范围**（本次不涉及）：
- Handler 层代码修改（将在后续任务中处理）
- Service 层代码修改（将在后续任务中处理）
- Store 层代码修改（将在后续任务中处理）
- DTO 模型调整（请求/响应结构体）
- 单元测试和集成测试
- API 文档更新

**风险和注意事项：**
- 所有金额字段从 `float64` 改为 `int64`（分为单位），需要在业务逻辑中进行单位转换
- 表名变更需要确保迁移脚本正确执行
- 新增的 `creator` 和 `updater` 字段需要在业务逻辑中正确赋值
- 软删除（`DeletedAt`）的引入可能需要调整查询逻辑（GORM 会自动处理）