csxj2026/junhong_cmp_fiber

Files

huang 2150fb6ab9 重构：完善 IoT 模型架构规范和数据库设计

- 完善 GORM 模型规范：货币字段使用 int64(分为单位)、JSONB 字段规范、模型结构规范
- 修复所有 IoT 模型的架构违规问题
- 更新 CLAUDE.md 开发指南，补充完整的数据库设计规范和模型示例
- 添加数据库迁移脚本(000006)用于架构重构
- 归档 OpenSpec 变更文档(2026-01-12-fix-iot-models-violations)

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

2026-01-12 17:43:12 +08:00

17 KiB

Raw Blame History

设计文档：修复 IoT 模型架构违规

1. 设计目标

将所有 IoT 相关数据模型重构为符合项目开发规范的标准模型，确保代码一致性、可维护性和长期可扩展性。

2. 核心设计原则

2.1 统一模型结构

所有数据模型必须遵循以下标准结构：

type ModelName struct {
    gorm.Model                    // 标准字段：ID, CreatedAt, UpdatedAt, DeletedAt
    BaseModel    `gorm:"embedded"` // 基础字段：Creator, Updater

    // 业务字段（按字母顺序排列）
    Field1 Type `gorm:"column:field1;..." json:"field1"`
    Field2 Type `gorm:"column:field2;..." json:"field2"`
}

func (ModelName) TableName() string {
    return "tb_model_name" // tb_ 前缀 + 单数
}

设计理由：

gorm.Model：提供标准的主键、时间戳、软删除支持
BaseModel：提供审计字段，记录创建人和更新人
显式 column 标签：明确 Go 字段和数据库列的映射关系，避免依赖 GORM 自动转换
tb_ 前缀单数表名：项目统一规范，便于识别业务表

2.2 字段定义规范

字符串字段：

Name string `gorm:"column:name;type:varchar(100);not null;comment:名称" json:"name"`

必须显式指定 column 标签
必须指定 type:varchar(N) 和长度
必须指定 not null（如果必填）
必须添加中文 comment

货币金额字段：

Amount int64 `gorm:"column:amount;type:bigint;default:0;not null;comment:金额（分）" json:"amount"`

使用 int64 类型（不是 float64）
单位为"分"（1元 = 100分）
必须指定 type:bigint
必须指定 default:0 和 not null
注释中明确标注"（分）"

设计理由：

整数存储避免浮点精度问题（金融领域最佳实践）
分为单位便于精确计算和货币转换

枚举字段：

Status int `gorm:"column:status;type:int;default:1;not null;comment:状态 1-启用 2-禁用" json:"status"`

使用 int 类型（不是 string）
必须在注释中列举所有枚举值
必须指定 default 和 not null

关联 ID 字段：

UserID uint `gorm:"column:user_id;type:bigint;not null;index;comment:用户ID" json:"user_id"`

使用 uint 类型（与 gorm.Model 的 ID 类型一致）
数据库类型使用 bigint（PostgreSQL）
必须添加 index 索引
禁止使用 GORM 关联标签（foreignKey、references）

可选关联 ID 字段：

ShopID *uint `gorm:"column:shop_id;type:bigint;index;comment:店铺ID（可选）" json:"shop_id,omitempty"`

使用指针类型 *uint（可为 NULL）
不指定 not null
仍需添加 index 索引
JSON 标签使用 omitempty

唯一索引字段：

ICCID string `gorm:"column:iccid;type:varchar(50);uniqueIndex:idx_iccid,where:deleted_at IS NULL;not null;comment:ICCID" json:"iccid"`

使用 uniqueIndex 标签
对于支持软删除的表，必须添加 where:deleted_at IS NULL 过滤条件
索引名命名规范：idx_{table}_{field} 或 idx_{field}

时间字段：

ActivatedAt *time.Time `gorm:"column:activated_at;comment:激活时间" json:"activated_at,omitempty"`

可选时间字段使用指针类型 *time.Time
不使用 autoCreateTime 或 autoUpdateTime（这些由 gorm.Model 提供）
JSON 标签使用 omitempty

JSONB 字段（PostgreSQL）：

Metadata datatypes.JSON `gorm:"column:metadata;type:jsonb;comment:元数据" json:"metadata,omitempty"`

使用 gorm.io/datatypes.JSON 类型
数据库类型使用 jsonb（PostgreSQL 优化存储）
使用 omitempty

2.3 表名和索引命名规范

表名：

格式：tb_{model_name}（单数）
示例：tb_iot_card、tb_device、tb_order

索引名：

普通索引：idx_{table}_{field}
唯一索引：idx_{table}_{field} 或 uniq_{table}_{field}
复合索引：idx_{table}_{field1}_{field2}

设计理由：

统一前缀便于识别业务表（与系统表区分）
单数形式符合 Go 惯用命名（类型名为单数）
索引名清晰表达用途和字段

2.4 软删除支持

所有业务数据表都应支持软删除：

type BusinessModel struct {
    gorm.Model // 包含 DeletedAt 字段
    // ...
}

不需要软删除的表：

纯配置表（如 PollingConfig、CommissionWithdrawalSetting）
日志表（如 DataUsageRecord）
中间表（如 DeviceSimBinding 可选支持）

对于不需要软删除的表，可以手动定义字段：

type ConfigModel struct {
    ID        uint      `gorm:"column:id;primaryKey;comment:ID" json:"id"`
    BaseModel `gorm:"embedded"`
    // ...
    CreatedAt time.Time `gorm:"column:created_at;autoCreateTime;comment:创建时间" json:"created_at"`
    UpdatedAt time.Time `gorm:"column:updated_at;autoUpdateTime;comment:更新时间" json:"updated_at"`
}