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

本次提交完成 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 行

openspec/specs/card-replacement/spec.md

@@ -0,0 +1,187 @@
+# card-replacement Specification
+
+## Purpose
+TBD - created by archiving change add-wallet-transfer-tag-models. Update Purpose after archive.
+## Requirements
+### Requirement: 换卡记录实体定义
+
+系统 SHALL 定义换卡记录(CardReplacementRecord)实体，记录老卡到新卡的完整转移过程，包括套餐权益、代理关系、所有者信息等。
+
+**核心概念**：
+- **换卡场景**：老卡损坏、丢失或故障，需要更换新卡
+- **权益转移**：老卡的套餐（含剩余流量）、代理关系、所有者信息等全部转移到新卡
+- **套餐继续生效**：转移后套餐不作废，剩余流量继续可用
+
+**实体字段**：
+- `id`：换卡记录 ID（主键，BIGINT）
+- `replacement_no`：换卡单号（VARCHAR(50)，唯一）
+- `old_card_id`：老卡 ID（BIGINT，关联 tb_iot_card.id）
+- `old_iccid`：老卡 ICCID（VARCHAR(50)，冗余存储，防止老卡被删除后无法追踪）
+- `new_card_id`：新卡 ID（BIGINT，关联 tb_iot_card.id）
+- `new_iccid`：新卡 ICCID（VARCHAR(50)，冗余存储）
+- `old_owner_type`：老卡所有者类型（VARCHAR(20)）
+- `old_owner_id`：老卡所有者 ID（BIGINT）
+- `old_agent_id`：老卡代理 ID（BIGINT，可空）
+- `new_owner_type`：新卡所有者类型（VARCHAR(20)）
+- `new_owner_id`：新卡所有者 ID（BIGINT）
+- `new_agent_id`：新卡代理 ID（BIGINT，可空）
+- `package_snapshot`：套餐快照（JSONB，记录转移时的套餐详情）
+- `replacement_reason`：换卡原因（VARCHAR(20)，枚举值："damaged"-损坏 | "lost"-丢失 | "malfunction"-故障 | "upgrade"-升级 | "other"-其他）
+- `remark`：备注（TEXT）
+- `status`：换卡状态（INT，1-待审批 2-已通过 3-已拒绝 4-已完成）
+- `approved_by`：审批人 ID（BIGINT，可空）
+- `approved_at`：审批时间（TIMESTAMP，可空）
+- `completed_at`：完成时间（TIMESTAMP，可空）
+- `creator`：创建人 ID（BIGINT）
+- `updater`：更新人 ID（BIGINT）
+- `created_at`：创建时间（TIMESTAMP，自动填充）
+- `updated_at`：更新时间（TIMESTAMP，自动填充）
+- `deleted_at`：删除时间（TIMESTAMP，可空，软删除）
+
+**套餐快照 JSON 格式示例**：
+```json
+{
+  "package_id": 3001,
+  "package_name": "月套餐 10GB",
+  "package_code": "PKG-M-001",
+  "data_limit_mb": 10240,
+  "data_usage_mb": 5120,
+  "real_data_usage_mb": 4000,
+  "virtual_data_usage_mb": 1120,
+  "data_remaining_mb": 5120,
+  "activated_at": "2026-01-01T00:00:00Z",
+  "expires_at": "2026-02-01T00:00:00Z",
+  "remaining_days": 15,
+  "order_id": 10001
+}
+```
+
+#### Scenario: 创建换卡记录
+
+- **WHEN** 用户（ID 为 2001）的老卡（ICCID 为 "8986001"）损坏，需要换新卡（ICCID 为 "8986002"）
+- **THEN** 系统创建换卡记录，`old_card_id` 为老卡 ID，`new_card_id` 为新卡 ID，`replacement_reason` 为 "damaged"，`status` 为 1（待审批）
+
+#### Scenario: 审批通过换卡
+
+- **WHEN** 运营人员（ID 为 999）审批通过换卡记录（ID 为 5001）
+- **THEN** 系统将换卡记录状态从 1（待审批）变更为 2（已通过），记录 `approved_by` 为 999，`approved_at` 为当前时间
+
+#### Scenario: 完成换卡
+
+- **WHEN** 换卡记录（ID 为 5001）状态为 2（已通过），系统执行换卡操作
+- **THEN** 系统将：
+  1. 记录老卡和新卡的快照信息（所有者、代理、套餐）
+  2. 将老卡的套餐权益转移到新卡（套餐使用记录的 `iot_card_id` 更新为新卡 ID）
+  3. 将新卡的 `owner_type` 和 `owner_id` 更新为老卡的值
+  4. 将新卡的代理关系更新为老卡的值（如有）
+  5. 将换卡记录状态变更为 4（已完成），记录 `completed_at` 为当前时间
+
+#### Scenario: 拒绝换卡
+
+- **WHEN** 运营人员（ID 为 999）拒绝换卡记录（ID 为 5001），原因为"新卡不符合要求"
+- **THEN** 系统将换卡记录状态从 1（待审批）变更为 3（已拒绝），记录 `approved_by` 为 999，`approved_at` 为当前时间，`remark` 为拒绝原因
+
+---
+
+### Requirement: 套餐权益转移
+
+系统 SHALL 在换卡完成后，将老卡的套餐权益（包括剩余流量、过期时间等）转移到新卡，套餐继续生效。
+
+**转移内容**：
+- 套餐使用记录（`tb_package_usage`）
+- 剩余流量（`data_limit_mb - data_usage_mb`）
+- 套餐过期时间（`expires_at`）
+- 关联的订单信息
+
+**转移规则**：
+- 老卡的套餐使用记录的 `iot_card_id` 更新为新卡 ID
+- 剩余流量完整保留
+- 套餐过期时间不变
+- 如果老卡有多个套餐（正式套餐 + 加油包），全部转移
+
+#### Scenario: 套餐转移
+
+- **WHEN** 老卡有月套餐（剩余 5120 MB 流量，还有 15 天过期）
+- **THEN** 系统将套餐使用记录的 `iot_card_id` 从老卡 ID 更新为新卡 ID，流量和过期时间保持不变
+
+#### Scenario: 多套餐转移
+
+- **WHEN** 老卡有正式套餐和 2 个加油包
+- **THEN** 系统将所有套餐使用记录的 `iot_card_id` 更新为新卡 ID，所有套餐继续生效
+
+---
+
+### Requirement: 代理关系转移
+
+系统 SHALL 在换卡完成后，将老卡的代理关系转移到新卡。
+
+**转移内容**：
+- 新卡的 `owner_type` 更新为老卡的 `owner_type`
+- 新卡的 `owner_id` 更新为老卡的 `owner_id`
+- 如果老卡通过代理销售，新卡继承相同的代理关系
+
+#### Scenario: 代理关系转移
+
+- **WHEN** 老卡的 `owner_type` 为 "agent"，`owner_id` 为 123
+- **THEN** 系统将新卡的 `owner_type` 更新为 "agent"，`owner_id` 更新为 123
+
+---
+
+### Requirement: 换卡记录查询
+
+系统 SHALL 支持按老卡 ID、新卡 ID、用户 ID、换卡单号等条件查询换卡记录。
+
+**查询条件**：
+- 换卡单号（精确匹配）
+- 老卡 ID（精确匹配）
+- 新卡 ID（精确匹配）
+- 老卡 ICCID（精确匹配或模糊匹配）
+- 新卡 ICCID（精确匹配或模糊匹配）
+- 换卡状态（单选或多选）
+- 换卡原因（单选或多选）
+- 创建时间范围
+- 完成时间范围
+
+**分页**：
+- 默认每页 20 条，最大每页 100 条
+- 返回总记录数和总页数
+
+#### Scenario: 按老卡 ICCID 查询换卡记录
+
+- **WHEN** 查询老卡 ICCID 为 "8986001" 的换卡记录
+- **THEN** 系统返回所有 `old_iccid` 为 "8986001" 的换卡记录列表
+
+#### Scenario: 按状态查询换卡记录
+
+- **WHEN** 查询状态为 1（待审批）的换卡记录
+- **THEN** 系统返回所有 `status` 为 1 的换卡记录列表，按创建时间倒序排列
+
+---
+
+### Requirement: 换卡数据校验
+
+系统 SHALL 对换卡数据进行校验，确保数据完整性和一致性。
+
+**校验规则**：
+- `old_card_id`：必填，≥ 1，必须是有效的 IoT 卡 ID
+- `new_card_id`：必填，≥ 1，必须是有效的 IoT 卡 ID，不能与 `old_card_id` 相同
+- `old_iccid`：必填，长度 19-20 字符
+- `new_iccid`：必填，长度 19-20 字符，不能与 `old_iccid` 相同
+- `replacement_reason`：必填，枚举值 "damaged" | "lost" | "malfunction" | "upgrade" | "other"
+- `status`：必填，枚举值 1-4
+
+#### Scenario: 换卡时老卡和新卡相同
+
+- **WHEN** 创建换卡记录，`old_card_id` 和 `new_card_id` 都为 1001
+- **THEN** 系统拒绝创建，返回错误信息"新卡不能与老卡相同"
+
+#### Scenario: 换卡时新卡 ICCID 无效
+
+- **WHEN** 创建换卡记录，`new_iccid` 长度为 15（小于 19）
+- **THEN** 系统拒绝创建，返回错误信息"ICCID 长度必须为 19-20 字符"
+
+#### Scenario: 换卡时老卡不存在
+
+- **WHEN** 创建换卡记录，`old_card_id` 为 99999（不存在的 IoT 卡）
+- **THEN** 系统拒绝创建，返回错误信息"老卡不存在"
+

openspec/specs/carrier/spec.md

@@ -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`：状态（INT，1-启用 2-禁用）
+- `creator`：创建人 ID（BIGINT）
+- `updater`：更新人 ID（BIGINT）
+- `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** 系统拒绝创建，返回错误信息"运营商名称不能为空"
+

openspec/specs/iot-order/spec.md

@@ -11,56 +11,50 @@ This capability supports:
 - Commission triggering on order completion
 - Device-level order commission (counted once regardless of bound card count)
 - Multi-dimensional order querying and filtering
-
 ## Requirements
-
 ### Requirement: 订单实体定义
 
-系统 SHALL 定义订单(Order)实体,统一管理两种订单类型:套餐订单、号卡订单。
+系统 SHALL 定义订单(Order)实体，统一管理两种订单类型：套餐订单、号卡订单，并支持混合支付方式（钱包 + 在线支付）。
 
-**核心概念**:
-- **套餐订单**: 用户为 IoT 卡或设备购买套餐的订单,包括单卡套餐订单和设备级套餐订单
-- **号卡订单**: 运营商回传的号卡订单,用户直接在上游平台下单,系统只接收订单状态更新
+**修改说明**：
+- 增加 `wallet_payment_amount` 字段：钱包支付金额
+- 增加 `online_payment_amount` 字段：在线支付金额
+- 支持用户在购买套餐时选择支付方式（全部钱包支付、全部在线支付、混合支付）
 
-**实体字段**:
-- `id`: 订单 ID(主键,BIGINT)
-- `order_no`: 订单编号(VARCHAR(50),唯一)
-- `order_type`: 订单类型(INT,1-套餐订单 2-号卡订单)
-- `iot_card_id`: IoT 卡 ID(BIGINT,可空,单卡套餐订单时有值)
-- `device_id`: 设备 ID(BIGINT,可空,设备级套餐订单时有值)
-- `number_card_id`: 号卡 ID(BIGINT,可空,号卡订单时有值)
-- `package_id`: 套餐 ID(BIGINT,可空,仅当 order_type 为 1 时有值)
-- `user_id`: 用户 ID(BIGINT,购买用户)
-- `agent_id`: 代理 ID(BIGINT,可空,通过代理购买时有值)
-- `amount`: 订单金额(DECIMAL(10,2),元)
-- `payment_method`: 支付方式(VARCHAR(20),"wallet"-钱包 | "online"-在线支付 | "carrier"-运营商直付)
-- `status`: 订单状态(INT,1-待支付 2-已支付 3-已完成 4-已取消 5-已退款)
-- `carrier_order_id`: 运营商订单 ID(VARCHAR(255),可空,仅号卡订单有值)
-- `carrier_order_data`: 运营商订单原始数据(JSONB,可空)
-- `paid_at`: 支付时间(TIMESTAMP,可空)
-- `completed_at`: 完成时间(TIMESTAMP,可空)
-- `created_at`: 创建时间(TIMESTAMP,自动填充)
-- `updated_at`: 更新时间(TIMESTAMP,自动填充)
+**实体字段**（只列出新增字段）：
+- `wallet_payment_amount`：钱包支付金额（BIGINT，单位：分，默认 0）**【新增】**
+- `online_payment_amount`：在线支付金额（BIGINT，单位：分，默认 0）**【新增】**
 
-**订单类型说明**:
-- **单卡套餐订单**: `order_type` 为 1,`iot_card_id` 有值,`device_id` 为 NULL
-- **设备级套餐订单**: `order_type` 为 1,`device_id` 有值,`iot_card_id` 为 NULL
-- **号卡订单**: `order_type` 为 2,`number_card_id` 有值,`iot_card_id` 和 `device_id` 为 NULL
+**支付规则**：
+- `wallet_payment_amount` + `online_payment_amount` = `amount`（订单总金额）
+- 当 `payment_method` 为 "wallet" 时，`wallet_payment_amount` = `amount`，`online_payment_amount` = 0
+- 当 `payment_method` 为 "online" 时，`online_payment_amount` = `amount`，`wallet_payment_amount` = 0
+- 混合支付时，`payment_method` 为 "mixed"，两个字段都 > 0
 
-#### Scenario: 创建单卡套餐购买订单
+#### Scenario: 全额钱包支付
 
-- **WHEN** 用户(ID 为 2001)为 IoT 卡(ID 为 1001)购买套餐(ID 为 3001),金额为 30.00 元
-- **THEN** 系统创建订单记录,`order_type` 为 1,`iot_card_id` 为 1001,`device_id` 为 NULL,`package_id` 为 3001,`user_id` 为 2001,`amount` 为 30.00,状态为 1(待支付)
+- **WHEN** 用户购买套餐，订单金额为 30 00 分（30 元），选择钱包支付，钱包余额为 10000 分
+- **THEN** 系统创建订单，`amount` 为 3000，`payment_method` 为 "wallet"，`wallet_payment_amount` 为 3000，`online_payment_amount` 为 0
 
-#### Scenario: 创建设备级套餐购买订单
+#### Scenario: 全额在线支付
 
-- **WHEN** 用户(ID 为 2001)为设备(ID 为 5001,绑定 3 张 IoT 卡)购买套餐(ID 为 3002),金额为 399.00 元
-- **THEN** 系统创建订单记录,`order_type` 为 1,`device_id` 为 5001,`iot_card_id` 为 NULL,`package_id` 为 3002,`user_id` 为 2001,`amount` 为 399.00,状态为 1(待支付)
+- **WHEN** 用户购买套餐，订单金额为 3000 分（30 元），选择在线支付
+- **THEN** 系统创建订单，`amount` 为 3000，`payment_method` 为 "online"，`wallet_payment_amount` 为 0，`online_payment_amount` 为 3000
 
-#### Scenario: 创建号卡订单(运营商回传)
+#### Scenario: 混合支付
 
-- **WHEN** Gateway 回传运营商订单,虚拟商品编码对应号卡 ID 为 6001,代理 ID 为 123,订单金额为 30.00 元
-- **THEN** 系统创建订单记录,`order_type` 为 2,`number_card_id` 为 6001,`iot_card_id` 为 NULL,`device_id` 为 NULL,`agent_id` 为 123,`amount` 为 30.00,`payment_method` 为 "carrier",状态为 2(已支付)
+- **WHEN** 用户购买套餐，订单金额为 5000 分（50 元），钱包余额为 3000 分，用户选择钱包支付 3000 分 + 在线支付 2000 分
+- **THEN** 系统创建订单，`amount` 为 5000，`payment_method` 为 "mixed"，`wallet_payment_amount` 为 3000，`online_payment_amount` 为 2000
+
+#### Scenario: 钱包余额不足，部分钱包支付
+
+- **WHEN** 用户购买套餐，订单金额为 5000 分（50 元），钱包余额为 2000 分，用户选择钱包支付 2000 分 + 在线支付 3000 分
+- **THEN** 系统先冻结钱包余额 2000 分，创建订单，`wallet_payment_amount` 为 2000，`online_payment_amount` 为 3000，等待用户完成在线支付
+
+#### Scenario: 钱包余额不足，无法全额钱包支付
+
+- **WHEN** 用户购买套餐，订单金额为 5000 分（50 元），钱包余额为 3000 分，用户选择钱包支付
+- **THEN** 系统拒绝创建订单，返回错误信息"钱包余额不足"，建议用户选择混合支付或在线支付
 
 ---
 
@@ -207,41 +201,75 @@ This capability supports:
 
 ### Requirement: 订单数据校验
 
-系统 SHALL 对订单数据进行校验,确保数据完整性和一致性。
+系统 SHALL 对订单数据进行校验，确保数据完整性和一致性，特别是支付金额的一致性。
 
-**校验规则**:
-- 订单编号(order_no):必填,长度 1-50 字符,唯一
-- 订单类型(order_type):必填,枚举值 1(套餐订单) | 2(号卡订单)
-- IoT 卡 ID(iot_card_id):套餐订单时 iot_card_id 和 device_id 二选一
-- 设备 ID(device_id):套餐订单时 iot_card_id 和 device_id 二选一
-- 号卡 ID(number_card_id):号卡订单时必填
-- 套餐 ID(package_id):套餐订单时必填
-- 用户 ID(user_id):必填,≥ 1
-- 订单金额(amount):必填,≥ 0,最多 2 位小数
-- 支付方式(payment_method):必填,枚举值 "wallet" | "online" | "carrier"
-- 状态(status):必填,枚举值 1-5
+**新增校验规则**：
+- `wallet_payment_amount`：必填，≥ 0，最多精确到分
+- `online_payment_amount`：必填，≥ 0，最多精确到分
+- `wallet_payment_amount` + `online_payment_amount` = `amount`（订单总金额）
+- 当 `payment_method` 为 "wallet" 时，`wallet_payment_amount` 必须 = `amount`
+- 当 `payment_method` 为 "online" 时，`online_payment_amount` 必须 = `amount`
+- 当 `payment_method` 为 "mixed" 时，两个字段都必须 > 0
 
-#### Scenario: 创建订单时金额为负数
+#### Scenario: 支付金额不一致
 
-- **WHEN** 创建订单,金额为 -10.00
-- **THEN** 系统拒绝创建,返回错误信息"订单金额必须 ≥ 0"
+- **WHEN** 创建订单，`amount` 为 5000，`wallet_payment_amount` 为 2000，`online_payment_amount` 为 2000
+- **THEN** 系统拒绝创建，返回错误信息"支付金额总和与订单金额不一致"
 
-#### Scenario: 创建订单时订单编号重复
+#### Scenario: 钱包支付时在线支付金额不为 0
 
-- **WHEN** 创建订单,订单编号为已存在的 "ORD-2025-001"
-- **THEN** 系统拒绝创建,返回错误信息"订单编号已存在"
+- **WHEN** 创建订单，`payment_method` 为 "wallet"，`wallet_payment_amount` 为 3000，`online_payment_amount` 为 0（正确），但用户错误地设置 `online_payment_amount` 为 100
+- **THEN** 系统拒绝创建，返回错误信息"钱包支付时在线支付金额必须为 0"
 
-#### Scenario: 创建套餐订单时未关联 IoT 卡或设备
+#### Scenario: 混合支付时钱包支付金额为 0
 
-- **WHEN** 创建套餐订单,`iot_card_id` 和 `device_id` 都为 NULL
-- **THEN** 系统拒绝创建,返回错误信息"套餐订单必须关联 IoT 卡或设备"
+- **WHEN** 创建订单，`payment_method` 为 "mixed"，`wallet_payment_amount` 为 0，`online_payment_amount` 为 5000
+- **THEN** 系统拒绝创建，返回错误信息"混合支付时钱包支付金额和在线支付金额都必须大于 0"
 
-#### Scenario: 创建套餐订单时同时关联 IoT 卡和设备
+### Requirement: 订单支付处理
 
-- **WHEN** 创建套餐订单,`iot_card_id` 为 1001,`device_id` 为 5001
-- **THEN** 系统拒绝创建,返回错误信息"套餐订单不能同时关联 IoT 卡和设备"
+系统 SHALL 根据支付方式正确处理订单支付，包括钱包扣款、在线支付、混合支付等。
 
-#### Scenario: 创建号卡订单时未关联号卡
+**钱包支付流程**：
+1. 检查钱包可用余额是否充足
+2. 冻结钱包余额（`frozen_balance` 增加）
+3. 创建订单，状态为"待支付"
+4. 订单完成后，扣减钱包余额（`balance` 减少，`frozen_balance` 减少），创建钱包明细记录
+5. 订单取消时，解冻钱包余额（`frozen_balance` 减少）
+
+**在线支付流程**：
+1. 创建订单，状态为"待支付"
+2. 调用第三方支付接口
+3. 用户完成支付后，订单状态变更为"已支付"
+4. 订单完成后，订单状态变更为"已完成"
+
+**混合支付流程**：
+1. 检查钱包可用余额是否充足（钱包支付部分）
+2. 冻结钱包余额
+3. 创建订单，状态为"待支付"
+4. 调用第三方支付接口（在线支付部分）
+5. 用户完成在线支付后，扣减钱包余额，订单状态变更为"已支付"
+6. 订单完成后，订单状态变更为"已完成"
+
+#### Scenario: 钱包支付订单完成
+
+- **WHEN** 用户使用钱包支付购买套餐，订单金额为 3000 分
+- **THEN** 系统：
+  1. 创建订单，状态为"待支付"，冻结钱包余额 3000 分
+  2. 订单处理完成后，扣减钱包余额 3000 分，解冻 3000 分，创建钱包明细记录（类型为"扣款"），订单状态变更为"已完成"
+
+#### Scenario: 混合支付订单完成
+
+- **WHEN** 用户使用混合支付购买套餐，钱包支付 2000 分 + 在线支付 3000 分
+- **THEN** 系统：
+  1. 创建订单，状态为"待支付"，冻结钱包余额 2000 分
+  2. 用户完成在线支付 3000 分后，扣减钱包余额 2000 分，解冻 2000 分，创建钱包明细记录，订单状态变更为"已支付"
+  3. 订单处理完成后，订单状态变更为"已完成"
+
+#### Scenario: 订单取消，解冻钱包余额
+
+- **WHEN** 用户使用钱包支付创建订单，订单金额为 3000 分，然后取消订单
+- **THEN** 系统解冻钱包余额 3000 分（`frozen_balance` 减少 3000），订单状态变更为"已取消"
+
+---
 
-- **WHEN** 创建号卡订单,`number_card_id` 为 NULL
-- **THEN** 系统拒绝创建,返回错误信息"号卡订单必须关联号卡"

openspec/specs/tag/spec.md

@@ -0,0 +1,222 @@
+# tag Specification
+
+## Purpose
+TBD - created by archiving change add-wallet-transfer-tag-models. Update Purpose after archive.
+## Requirements
+### Requirement: 标签实体定义
+
+系统 SHALL 定义标签(Tag)实体，用于为资源（设备、IoT卡、号卡）提供自定义标签分类功能。
+
+**核心概念**：
+- 企业用户可以为自己的设备/卡片创建和管理标签
+- 标签可以跨资源类型使用（一个标签可以同时用于设备和卡片）
+- 支持按标签查询和筛选资源
+
+**实体字段**：
+- `id`：标签 ID（主键，BIGINT）
+- `name`：标签名称（VARCHAR(100)，唯一）
+- `color`：标签颜色（VARCHAR(20)，可选，用于前端显示，如 "#FF5733"）
+- `usage_count`：使用次数（INT，默认 0，记录有多少资源使用了该标签）
+- `creator`：创建人 ID（BIGINT）
+- `updater`：更新人 ID（BIGINT）
+- `created_at`：创建时间（TIMESTAMP，自动填充）
+- `updated_at`：更新时间（TIMESTAMP，自动填充）
+- `deleted_at`：删除时间（TIMESTAMP，可空，软删除）
+
+**唯一约束**：`name` 在 `deleted_at IS NULL` 条件下唯一
+
+#### Scenario: 创建标签
+
+- **WHEN** 用户创建标签，名称为"生产设备"，颜色为"#FF5733"
+- **THEN** 系统创建标签记录，`name` 为 "生产设备"，`color` 为 "#FF5733"，`usage_count` 为 0
+
+#### Scenario: 标签名称重复
+
+- **WHEN** 用户创建标签，名称为已存在的"生产设备"
+- **THEN** 系统拒绝创建，返回错误信息"标签名称已存在"
+
+#### Scenario: 更新标签
+
+- **WHEN** 用户更新标签（ID 为 101），将颜色从"#FF5733"改为"#33FF57"
+- **THEN** 系统更新标签记录，`color` 为 "#33FF57"，`updated_at` 为当前时间
+
+---
+
+### Requirement: 资源-标签关联
+
+系统 SHALL 定义资源-标签关联(ResourceTag)实体，建立资源与标签的多对多关系，统一管理设备、IoT卡、号卡的标签。
+
+**实体字段**：
+- `id`：关联记录 ID（主键，BIGINT）
+- `resource_type`：资源类型（VARCHAR(20)，枚举值："device"-设备 | "iot_card"-IoT卡 | "number_card"-号卡）
+- `resource_id`：资源 ID（BIGINT）
+- `tag_id`：标签 ID（BIGINT，关联 tb_tag.id）
+- `creator`：创建人 ID（BIGINT）
+- `updater`：更新人 ID（BIGINT）
+- `created_at`：创建时间（TIMESTAMP，自动填充）
+- `updated_at`：更新时间（TIMESTAMP，自动填充）
+- `deleted_at`：删除时间（TIMESTAMP，可空，软删除）
+
+**唯一约束**：`(resource_type, resource_id, tag_id)` 在 `deleted_at IS NULL` 条件下唯一
+
+#### Scenario: 为设备添加标签
+
+- **WHEN** 用户为设备（ID 为 1001）添加标签"生产设备"（ID 为 101）
+- **THEN** 系统创建关联记录，`resource_type` 为 "device"，`resource_id` 为 1001，`tag_id` 为 101，标签的 `usage_count` 增加 1
+
+#### Scenario: 为 IoT 卡添加标签
+
+- **WHEN** 用户为 IoT 卡（ID 为 2001）添加标签"GPS"（ID 为 102）
+- **THEN** 系统创建关联记录，`resource_type` 为 "iot_card"，`resource_id` 为 2001，`tag_id` 为 102，标签的 `usage_count` 增加 1
+
+#### Scenario: 重复添加标签
+
+- **WHEN** 用户为设备（ID 为 1001）添加已存在的标签"生产设备"（ID 为 101）
+- **THEN** 系统拒绝操作，返回错误信息"该资源已添加此标签"
+
+#### Scenario: 移除资源标签
+
+- **WHEN** 用户移除设备（ID 为 1001）的标签"生产设备"（ID 为 101）
+- **THEN** 系统删除关联记录（软删除），标签的 `usage_count` 减少 1
+
+---
+
+### Requirement: 按标签查询资源
+
+系统 SHALL 支持按标签查询资源，用户可以选择一个或多个标签，查询包含这些标签的资源。
+
+**查询模式**：
+- **AND 模式**：查询同时包含所有指定标签的资源（交集）
+- **OR 模式**：查询包含任一指定标签的资源（并集）
+
+**查询条件**：
+- 资源类型（必选，单选）
+- 标签 ID 列表（必选，可多选）
+- 查询模式（可选，默认 OR）
+
+**分页**：
+- 默认每页 20 条，最大每页 100 条
+- 返回总记录数和总页数
+
+#### Scenario: OR 模式查询设备
+
+- **WHEN** 用户查询包含标签"生产设备"（ID 为 101）或"测试设备"（ID 为 102）的设备
+- **THEN** 系统返回所有包含标签 101 或标签 102 的设备列表
+
+#### Scenario: AND 模式查询设备
+
+- **WHEN** 用户查询同时包含标签"生产设备"（ID 为 101）和"GPS"（ID 为 103）的设备
+- **THEN** 系统返回同时包含标签 101 和标签 103 的设备列表
+
+#### Scenario: 按标签查询 IoT 卡
+
+- **WHEN** 用户查询包含标签"GPS"（ID 为 102）的 IoT 卡
+- **THEN** 系统返回所有包含标签 102 的 IoT 卡列表
+
+---
+
+### Requirement: 获取资源的标签列表
+
+系统 SHALL 支持查询指定资源的所有标签。
+
+**查询条件**：
+- 资源类型（必选）
+- 资源 ID（必选）
+
+**返回内容**：
+- 标签列表（ID、名称、颜色）
+- 按创建时间倒序排列
+
+#### Scenario: 查询设备的标签
+
+- **WHEN** 用户查询设备（ID 为 1001）的所有标签
+- **THEN** 系统返回设备 1001 的标签列表，包含标签 ID、名称、颜色
+
+#### Scenario: 查询没有标签的设备
+
+- **WHEN** 用户查询设备（ID 为 1002）的所有标签，但该设备没有任何标签
+- **THEN** 系统返回空列表
+
+---
+
+### Requirement: 热门标签查询
+
+系统 SHALL 支持查询热门标签，按使用次数倒序排列。
+
+**查询条件**：
+- 限制数量（可选，默认 20）
+
+**返回内容**：
+- 标签列表（ID、名称、颜色、使用次数）
+- 按使用次数倒序排列
+
+#### Scenario: 查询热门标签
+
+- **WHEN** 用户查询热门标签，限制 10 条
+- **THEN** 系统返回使用次数最多的 10 个标签，按使用次数倒序排列
+
+---
+
+### Requirement: 标签批量操作
+
+系统 SHALL 支持为资源批量添加或移除标签。
+
+**批量添加**：
+- 为一个资源添加多个标签
+- 为多个资源添加同一个标签
+
+**批量移除**：
+- 为一个资源移除多个标签
+- 为多个资源移除同一个标签
+
+#### Scenario: 为设备批量添加标签
+
+- **WHEN** 用户为设备（ID 为 1001）批量添加标签["生产设备", "GPS", "4G"]
+- **THEN** 系统为设备 1001 创建 3 条关联记录，所有标签的 `usage_count` 各增加 1
+
+#### Scenario: 批量为设备添加标签
+
+- **WHEN** 用户为设备列表 [1001, 1002, 1003] 批量添加标签"生产设备"（ID 为 101）
+- **THEN** 系统为 3 个设备各创建一条关联记录，标签"生产设备"的 `usage_count` 增加 3
+
+#### Scenario: 为设备批量移除标签
+
+- **WHEN** 用户为设备（ID 为 1001）批量移除标签["生产设备", "GPS"]
+- **THEN** 系统删除设备 1001 的 2 条关联记录（软删除），所有标签的 `usage_count` 各减少 1
+
+---
+
+### Requirement: 标签数据校验
+
+系统 SHALL 对标签数据进行校验，确保数据完整性和一致性。
+
+**标签校验规则**：
+- `name`：必填，长度 1-100 字符，唯一
+- `color`：可选，长度 1-20 字符，建议使用十六进制颜色值（如 "#FF5733"）
+- `usage_count`：必填，≥ 0
+
+**资源-标签关联校验规则**：
+- `resource_type`：必填，枚举值 "device" | "iot_card" | "number_card"
+- `resource_id`：必填，≥ 1
+- `tag_id`：必填，≥ 1，必须是有效的标签 ID
+
+#### Scenario: 创建标签时名称为空
+
+- **WHEN** 用户创建标签，名称为空
+- **THEN** 系统拒绝创建，返回错误信息"标签名称不能为空"
+
+#### Scenario: 创建标签时名称过长
+
+- **WHEN** 用户创建标签，名称长度为 101 字符
+- **THEN** 系统拒绝创建，返回错误信息"标签名称长度不能超过 100 字符"
+
+#### Scenario: 添加标签时资源类型无效
+
+- **WHEN** 用户为资源添加标签，`resource_type` 为 "invalid"
+- **THEN** 系统拒绝操作，返回错误信息"资源类型无效"
+
+#### Scenario: 添加标签时标签不存在
+
+- **WHEN** 用户为设备添加标签，`tag_id` 为 99999（不存在的标签）
+- **THEN** 系统拒绝操作，返回错误信息"标签不存在"
+

openspec/specs/wallet/spec.md

@@ -0,0 +1,203 @@
+# wallet Specification
+
+## Purpose
+TBD - created by archiving change add-wallet-transfer-tag-models. Update Purpose after archive.
+## Requirements
+### Requirement: 钱包实体定义
+
+系统 SHALL 定义钱包(Wallet)实体，统一管理用户钱包和代理钱包，支持余额管理、充值、扣款等操作。
+
+**核心概念**：
+- **用户钱包**：普通用户和企业用户的钱包，用于购买套餐
+- **代理钱包**：代理商的钱包，支持预充值，可用成本价购买套餐
+
+**实体字段**：
+- `id`：钱包 ID（主键，BIGINT）
+- `user_id`：用户 ID（BIGINT，关联 tb_account.id）
+- `wallet_type`：钱包类型（VARCHAR(20)，枚举值："user"-用户钱包 | "agent"-代理钱包）
+- `balance`：余额（BIGINT，单位：分，默认 0）
+- `frozen_balance`：冻结余额（BIGINT，单位：分，默认 0，用于订单待支付、提现申请中等场景）
+- `currency`：币种（VARCHAR(10)，默认 "CNY"）
+- `status`：钱包状态（INT，1-正常 2-冻结 3-关闭）
+- `version`：版本号（INT，默认 0，乐观锁字段，用于防止并发扣款）
+- `creator`：创建人 ID（BIGINT）
+- `updater`：更新人 ID（BIGINT）
+- `created_at`：创建时间（TIMESTAMP，自动填充）
+- `updated_at`：更新时间（TIMESTAMP，自动填充）
+- `deleted_at`：删除时间（TIMESTAMP，可空，软删除）
+
+**唯一约束**：`(user_id, wallet_type, currency)` 在 `deleted_at IS NULL` 条件下唯一
+
+**可用余额计算**：可用余额 = balance - frozen_balance
+
+#### Scenario: 创建用户钱包
+
+- **WHEN** 用户（ID 为 2001）首次充值
+- **THEN** 系统创建钱包记录，`user_id` 为 2001，`wallet_type` 为 "user"，`balance` 为 0，`status` 为 1（正常）
+
+#### Scenario: 创建代理钱包
+
+- **WHEN** 代理商（ID 为 123）首次充值
+- **THEN** 系统创建钱包记录，`user_id` 为 123，`wallet_type` 为 "agent"，`balance` 为 0，`status` 为 1（正常）
+
+#### Scenario: 计算可用余额
+
+- **WHEN** 用户钱包余额为 10000 分（100 元），冻结余额为 3000 分（30 元）
+- **THEN** 系统计算可用余额为 7000 分（70 元）
+
+---
+
+### Requirement: 钱包明细记录
+
+系统 SHALL 记录所有钱包余额变动，包括充值、扣款、退款、分佣、提现等操作，确保完整的审计追踪。
+
+**实体字段**：
+- `id`：明细 ID（主键，BIGINT）
+- `wallet_id`：钱包 ID（BIGINT，关联 tb_wallet.id）
+- `user_id`：用户 ID（BIGINT，关联 tb_account.id）
+- `transaction_type`：交易类型（VARCHAR(20)，枚举值："recharge"-充值 | "deduct"-扣款 | "refund"-退款 | "commission"-分佣 | "withdrawal"-提现）
+- `amount`：变动金额（BIGINT，单位：分，正数为增加，负数为减少）
+- `balance_before`：变动前余额（BIGINT，单位：分）
+- `balance_after`：变动后余额（BIGINT，单位：分）
+- `status`：交易状态（INT，1-成功 2-失败 3-处理中）
+- `reference_type`：关联业务类型（VARCHAR(50)，如 "order" | "commission" | "withdrawal" | "topup"）
+- `reference_id`：关联业务 ID（BIGINT）
+- `remark`：备注（TEXT）
+- `metadata`：扩展信息（JSONB，如手续费、支付方式等）
+- `creator`：创建人 ID（BIGINT）
+- `created_at`：创建时间（TIMESTAMP，自动填充）
+- `updated_at`：更新时间（TIMESTAMP，自动填充）
+- `deleted_at`：删除时间（TIMESTAMP，可空，软删除）
+
+#### Scenario: 充值创建明细记录
+
+- **WHEN** 用户（ID 为 2001）充值 10000 分（100 元）
+- **THEN** 系统创建钱包明细记录，`transaction_type` 为 "recharge"，`amount` 为 10000，`balance_before` 为 0，`balance_after` 为 10000，`status` 为 1（成功）
+
+#### Scenario: 购买套餐扣款创建明细记录
+
+- **WHEN** 用户（ID 为 2001）使用钱包支付购买套餐，金额 3000 分（30 元）
+- **THEN** 系统创建钱包明细记录，`transaction_type` 为 "deduct"，`amount` 为 -3000，`balance_before` 为 10000，`balance_after` 为 7000，`reference_type` 为 "order"，`reference_id` 为订单 ID
+
+#### Scenario: 分佣发放创建明细记录
+
+- **WHEN** 代理（ID 为 123）的分佣 5000 分（50 元）审批通过并发放
+- **THEN** 系统创建钱包明细记录，`transaction_type` 为 "commission"，`amount` 为 5000，`balance_before` 为 20000，`balance_after` 为 25000，`reference_type` 为 "commission"，`reference_id` 为分佣记录 ID
+
+---
+
+### Requirement: 充值记录管理
+
+系统 SHALL 记录所有充值操作，包括充值订单号、金额、支付方式、支付状态等信息。
+
+**实体字段**：
+- `id`：充值记录 ID（主键，BIGINT）
+- `user_id`：用户 ID（BIGINT，关联 tb_account.id）
+- `wallet_id`：钱包 ID（BIGINT，关联 tb_wallet.id）
+- `recharge_no`：充值订单号（VARCHAR(50)，唯一）
+- `amount`：充值金额（BIGINT，单位：分）
+- `payment_method`：支付方式（VARCHAR(20)，枚举值："alipay"-支付宝 | "wechat"-微信 | "bank"-银行转账 | "offline"-线下）
+- `payment_channel`：支付渠道（VARCHAR(50)）
+- `payment_transaction_id`：第三方支付交易号（VARCHAR(100)）
+- `status`：充值状态（INT，1-待支付 2-已支付 3-已完成 4-已关闭 5-已退款）
+- `paid_at`：支付时间（TIMESTAMP，可空）
+- `completed_at`：完成时间（TIMESTAMP，可空）
+- `creator`：创建人 ID（BIGINT）
+- `updater`：更新人 ID（BIGINT）
+- `created_at`：创建时间（TIMESTAMP，自动填充）
+- `updated_at`：更新时间（TIMESTAMP，自动填充）
+- `deleted_at`：删除时间（TIMESTAMP，可空，软删除）
+
+#### Scenario: 创建充值订单
+
+- **WHEN** 用户（ID 为 2001）发起充值 10000 分（100 元），选择支付宝支付
+- **THEN** 系统创建充值记录，生成唯一的 `recharge_no`，`amount` 为 10000，`payment_method` 为 "alipay"，`status` 为 1（待支付）
+
+#### Scenario: 充值支付完成
+
+- **WHEN** 用户完成支付宝支付
+- **THEN** 系统将充值记录状态从 1（待支付）变更为 2（已支付），记录 `paid_at` 时间和 `payment_transaction_id`
+
+#### Scenario: 充值到账
+
+- **WHEN** 充值记录状态为 2（已支付），系统处理充值到账
+- **THEN** 系统将钱包余额增加 10000 分，创建钱包明细记录，将充值记录状态变更为 3（已完成），记录 `completed_at` 时间
+
+---
+
+### Requirement: 钱包余额操作
+
+系统 SHALL 支持钱包余额的充值、扣款、退款、冻结、解冻等操作，使用乐观锁防止并发问题。
+
+**操作类型**：
+- **充值**：增加钱包余额
+- **扣款**：减少钱包余额（如购买套餐）
+- **退款**：增加钱包余额（如订单退款）
+- **冻结**：将部分余额转为冻结状态（如订单待支付）
+- **解冻**：将冻结余额转回可用余额（如订单取消）
+
+**并发控制**：
+- 使用 `version` 字段实现乐观锁
+- 每次更新余额时，检查 `version` 是否匹配
+- 如果 `version` 不匹配，说明有并发更新，操作失败并重试
+
+#### Scenario: 钱包充值
+
+- **WHEN** 用户钱包当前余额为 10000 分，充值 5000 分
+- **THEN** 系统将钱包余额更新为 15000 分，`version` 从 1 变更为 2，创建钱包明细记录
+
+#### Scenario: 钱包扣款
+
+- **WHEN** 用户钱包当前余额为 15000 分，购买套餐扣款 3000 分
+- **THEN** 系统检查可用余额（15000 - 0 = 15000）≥ 3000，将钱包余额更新为 12000 分，`version` 从 2 变更为 3，创建钱包明细记录
+
+#### Scenario: 余额不足扣款失败
+
+- **WHEN** 用户钱包当前余额为 2000 分，购买套餐需要扣款 3000 分
+- **THEN** 系统检查可用余额（2000 - 0 = 2000）< 3000，拒绝扣款，返回错误信息"余额不足"
+
+#### Scenario: 并发扣款乐观锁生效
+
+- **WHEN** 用户钱包当前余额为 10000 分，version 为 1，两个并发请求同时扣款 3000 分和 5000 分
+- **THEN** 第一个请求成功，余额变为 7000 分，version 变为 2；第二个请求因 version 不匹配失败，需重新读取最新余额（7000 分）后重试
+
+#### Scenario: 冻结余额
+
+- **WHEN** 用户创建订单 10001，订单金额 3000 分，选择钱包支付
+- **THEN** 系统将钱包的 `frozen_balance` 增加 3000 分，可用余额减少 3000 分
+
+#### Scenario: 解冻余额
+
+- **WHEN** 用户取消订单 10001，订单金额 3000 分
+- **THEN** 系统将钱包的 `frozen_balance` 减少 3000 分，可用余额增加 3000 分
+
+---
+
+### Requirement: 钱包数据校验
+
+系统 SHALL 对钱包数据进行校验，确保数据完整性和一致性。
+
+**校验规则**：
+- `user_id`：必填，≥ 1
+- `wallet_type`：必填，枚举值 "user" | "agent"
+- `balance`：必填，≥ 0
+- `frozen_balance`：必填，≥ 0，≤ balance
+- `currency`：必填，长度 1-10 字符
+- `status`：必填，枚举值 1-3
+- `version`：必填，≥ 0
+
+#### Scenario: 创建钱包时 user_id 无效
+
+- **WHEN** 创建钱包，`user_id` 为 0
+- **THEN** 系统拒绝创建，返回错误信息"用户 ID 无效"
+
+#### Scenario: 创建钱包时 wallet_type 无效
+
+- **WHEN** 创建钱包，`wallet_type` 为 "invalid"
+- **THEN** 系统拒绝创建，返回错误信息"钱包类型无效"
+
+#### Scenario: 冻结余额超过总余额
+
+- **WHEN** 钱包余额为 10000 分，尝试冻结 15000 分
+- **THEN** 系统拒绝操作，返回错误信息"冻结余额不能超过总余额"
+