新增钱包、换卡、标签系统的数据模型和规范
本次提交完成 add-wallet-transfer-tag-models 提案的实施和归档: ## 新增功能模块 - 钱包系统:用户/代理钱包管理,支持充值、扣款、退款、乐观锁防并发 - 换卡记录:物联卡更换历史追溯,包含套餐快照(JSONB) - 标签系统:设备/IoT卡/号卡的统一标签管理 - 运营商渠道:四大运营商(CMCC/CUCC/CTCC/CBN)的渠道管理 ## 数据库变更 - 新增 6 张表:tb_wallet, tb_wallet_transaction, tb_recharge_record, tb_card_replacement_record, tb_tag, tb_resource_tag - 修改 2 张表:tb_carrier(新增渠道字段), tb_order(新增混合支付字段) - 迁移版本:v6 → v7(执行时间 282.5ms) ## 代码变更 - 新增 8 个 Go 模型(符合统一规范:gorm.Model + BaseModel) - 新增 40+ 个常量定义(含完整中文注释) - 新增 7 个 Redis Key 生成函数 - 修复模型规范:移除重复字段,统一使用 gorm.Model 嵌入 ## 文档变更 - 新增 3 个业务文档:数据模型设计、字段说明、迁移验证报告 - 更新 AGENTS.md:新增 Model 模型规范和常量注释规范 - 新增 4 个 OpenSpec 规范:wallet, carrier, card-replacement, tag - 更新 1 个 OpenSpec 规范:iot-order(支持混合支付) ## 验证通过 - ✅ LSP 诊断:所有模型和常量文件无错误 - ✅ OpenSpec 验证:openspec validate --strict 通过 - ✅ 迁移执行:表结构创建成功,索引正确 - ✅ 提案归档:2026-01-13-add-wallet-transfer-tag-models 变更文件统计:29 个文件,新增 3682 行
This commit is contained in:
35
AGENTS.md
35
AGENTS.md
@@ -82,6 +82,9 @@ Handler → Service → Store → Model
|
||||
- Redis key 使用函数生成: `Redis{Module}{Purpose}Key(params...)`
|
||||
- 格式: `{module}:{purpose}:{identifier}`
|
||||
- 禁止硬编码字符串和 magic numbers
|
||||
- **必须为所有常量添加中文注释**,参考 `pkg/constants/iot.go` 的注释风格
|
||||
- 常量分组使用 `// ========` 分隔线和标题注释
|
||||
- 每个常量值后必须添加行内注释说明含义
|
||||
|
||||
### Go 代码风格
|
||||
- 使用 `gofmt` 格式化
|
||||
@@ -90,6 +93,38 @@ Handler → Service → Store → Model
|
||||
- 接口命名: 使用 `-er` 后缀(Reader、Writer、Logger)
|
||||
- 缩写词: 全大写或全小写(URL、ID、HTTP 或 url、id、http)
|
||||
|
||||
## Model 模型规范
|
||||
|
||||
**必须遵守的模型结构:**
|
||||
|
||||
```go
|
||||
// ModelName 模型名称模型
|
||||
// 详细的业务说明(2-3行)
|
||||
// 特殊说明(如果有)
|
||||
type ModelName struct {
|
||||
gorm.Model // 包含 ID、CreatedAt、UpdatedAt、DeletedAt
|
||||
BaseModel `gorm:"embedded"` // 包含 Creator、Updater
|
||||
Field1 string `gorm:"column:field1;type:varchar(50);not null;comment:字段1说明" json:"field1"`
|
||||
// ... 其他字段
|
||||
}
|
||||
|
||||
// TableName 指定表名
|
||||
func (ModelName) TableName() string {
|
||||
return "tb_model_name"
|
||||
}
|
||||
```
|
||||
|
||||
**关键要点:**
|
||||
- ✅ **必须**嵌入 `gorm.Model` 和 `BaseModel`,不要手动定义 ID、CreatedAt、UpdatedAt、DeletedAt、Creator、Updater
|
||||
- ✅ **必须**为模型添加中文注释,说明业务用途(参考 `internal/model/iot_card.go`)
|
||||
- ✅ **必须**在每个字段的 `comment` 标签中添加中文说明
|
||||
- ✅ **必须**为导出的类型编写 godoc 格式的文档注释
|
||||
- ✅ **必须**实现 `TableName()` 方法,表名使用 `tb_` 前缀
|
||||
- ✅ 所有字段必须显式指定 `gorm:"column:field_name"` 标签
|
||||
- ✅ 金额字段使用 `int64` 类型,单位为分
|
||||
- ✅ 时间字段使用 `*time.Time`(可空)或 `time.Time`(必填)
|
||||
- ✅ JSONB 字段需要实现 `driver.Valuer` 和 `sql.Scanner` 接口
|
||||
|
||||
## 数据库设计
|
||||
|
||||
**核心规则:**
|
||||
|
||||
Reference in New Issue
Block a user