新增钱包、换卡、标签系统的数据模型和规范

本次提交完成 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:
2026-01-13 15:47:32 +08:00
parent 2150fb6ab9
commit 6e2dc325d7
29 changed files with 3682 additions and 87 deletions

View File

@@ -0,0 +1,80 @@
# carrier Specification
## Purpose
TBD - created by archiving change add-wallet-transfer-tag-models. Update Purpose after archive.
## Requirements
### Requirement: 运营商实体定义
系统 SHALL 定义运营商(Carrier)实体,管理四大固定运营商(中国移动、中国联通、中国电信、广电)的渠道信息
**四大运营商固定枚举**
- **CMCC**:中国移动
- **CUCC**:中国联通
- **CTCC**:中国电信
- **CBN**:广电
**实体字段**
- `id`:运营商 ID主键BIGINT
- `carrier_type`运营商类型VARCHAR(20),枚举值:"CMCC" | "CUCC" | "CTCC" | "CBN"**【新增】**
- `carrier_name`运营商名称VARCHAR(100),如"中国移动"
- `carrier_code`运营商编码VARCHAR(50),保留字段,建议填充与 carrier_type 相同)
- `channel_name`渠道名称VARCHAR(100),可自定义,如"北京渠道1"**【新增】**
- `channel_code`渠道编码VARCHAR(50),可自定义,如"BJ001"**【新增】**
- `status`状态INT1-启用 2-禁用)
- `creator`:创建人 IDBIGINT
- `updater`:更新人 IDBIGINT
- `created_at`创建时间TIMESTAMP自动填充
- `updated_at`更新时间TIMESTAMP自动填充
- `deleted_at`删除时间TIMESTAMP可空软删除
**唯一约束**`(carrier_type, channel_code)``deleted_at IS NULL` 条件下唯一
#### Scenario: 创建中国移动的渠道
- **WHEN** 平台创建中国移动的北京渠道,`carrier_type` 为 "CMCC"`carrier_name` 为 "中国移动"`channel_name` 为 "北京渠道1"`channel_code` 为 "BJ001"
- **THEN** 系统创建运营商记录,`carrier_type` 为 "CMCC"`channel_name` 为 "北京渠道1"`channel_code` 为 "BJ001"
#### Scenario: 同一运营商创建多个渠道
- **WHEN** 平台为中国移动创建两个渠道北京渠道BJ001和上海渠道SH001
- **THEN** 系统创建两条运营商记录,`carrier_type` 都为 "CMCC",但 `channel_code` 不同
#### Scenario: 渠道编码重复
- **WHEN** 平台创建中国移动的渠道,`carrier_type` 为 "CMCC"`channel_code` 为已存在的 "BJ001"
- **THEN** 系统拒绝创建,返回错误信息"该运营商的渠道编码已存在"
#### Scenario: 不同运营商可以使用相同渠道编码
- **WHEN** 平台为中国移动创建渠道carrier_type=CMCC, channel_code=BJ001然后为中国联通创建渠道carrier_type=CUCC, channel_code=BJ001
- **THEN** 系统允许创建,因为 `carrier_type` 不同
#### Scenario: 运营商类型枚举限制
- **WHEN** 平台创建运营商,`carrier_type` 为 "OTHER"(不在枚举中)
- **THEN** 系统拒绝创建,返回错误信息"运营商类型必须是 CMCC/CUCC/CTCC/CBN 之一"
---
### Requirement: 运营商数据校验
系统 SHALL 对运营商数据进行校验,确保数据完整性和一致性。
**校验规则**
- `carrier_type`:必填,枚举值 "CMCC" | "CUCC" | "CTCC" | "CBN"
- `carrier_name`:必填,长度 1-100 字符
- `carrier_code`:必填,长度 1-50 字符
- `channel_name`:可选,长度 1-100 字符
- `channel_code`:可选,长度 1-50 字符
- `status`:必填,枚举值 1-2
#### Scenario: 创建运营商时 carrier_type 无效
- **WHEN** 创建运营商,`carrier_type` 为 "INVALID"
- **THEN** 系统拒绝创建,返回错误信息"运营商类型无效"
#### Scenario: 创建运营商时 carrier_name 为空
- **WHEN** 创建运营商,`carrier_name` 为空
- **THEN** 系统拒绝创建,返回错误信息"运营商名称不能为空"