csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
6e2dc325d7220ee973edb563c2aead9c2452207d
junhong_cmp_fiber/openspec/specs/wallet/spec.md
huang 6e2dc325d7 新增钱包、换卡、标签系统的数据模型和规范 
本次提交完成 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 行
2026-01-13 15:47:32 +08:00

204 lines
9.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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** 系统拒绝操作，返回错误信息"冻结余额不能超过总余额"
Reference in New Issue View Git Blame Copy Permalink