huang
18daeae65a
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m17s
## 变更概述 将统一钱包系统拆分为代理钱包和卡钱包两个独立系统，实现数据表和代码层面的完全隔离。 ## 数据库变更 - 新增 6 张表：tb_agent_wallet、tb_agent_wallet_transaction、tb_agent_recharge_record、tb_card_wallet、tb_card_wallet_transaction、tb_card_recharge_record - 删除 3 张旧表：tb_wallet、tb_wallet_transaction、tb_recharge_record - 代理钱包：按 (shop_id, wallet_type) 唯一标识，支持主钱包和分佣钱包 - 卡钱包：按 (resource_type, resource_id) 唯一标识，支持物联网卡和设备 ## 代码变更 - Model 层：新增 AgentWallet、AgentWalletTransaction、AgentRechargeRecord、CardWallet、CardWalletTransaction、CardRechargeRecord 模型 - Store 层：新增 6 个独立 Store，支持事务、乐观锁、Redis 缓存 - Service 层：重构 commission_calculation、commission_withdrawal、order、recharge 等 8 个服务 - Bootstrap 层：更新 Store 和 Service 依赖注入 - 常量层：按钱包类型重新组织常量和 Redis Key 生成函数 ## 技术特性 - 乐观锁：使用 version 字段防止并发冲突 - 多租户：支持 shop_id_tag 和 enterprise_id_tag 过滤 - 事务管理：所有余额变动使用事务保证 ACID - 缓存策略：Cache-Aside 模式，余额变动后删除缓存 ## 业务影响 - 代理钱包和卡钱包业务完全隔离，互不影响 - 为独立监控、优化、扩展打下基础 - 提升代理钱包的稳定性和独立性 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
154 lines
6.5 KiB
Markdown
154 lines
6.5 KiB
Markdown
# 钱包系统分离提案
|
||
|
||
## Why
|
||
|
||
当前所有钱包类型（代理钱包、卡钱包）混在同一张表 `tb_wallet` 中，通过 `resource_type` 和 `wallet_type` 字段区分。业务方担心未来某个钱包业务的代码问题会影响其他钱包类型，特别是代理钱包作为核心资产需要最高等级的稳定性保障。在系统复杂度增长前，需要提前做预防性架构优化，将代理钱包和卡钱包在数据层和代码层完全隔离。
|
||
|
||
## What Changes
|
||
|
||
### 数据库层变更
|
||
|
||
**新增表**：
|
||
- `tb_agent_wallet` - 代理钱包主表（店铺级别）
|
||
- `tb_agent_wallet_transaction` - 代理钱包交易记录表
|
||
- `tb_agent_recharge_record` - 代理充值记录表
|
||
- `tb_card_wallet` - 卡钱包主表（物联网卡和设备）
|
||
- `tb_card_wallet_transaction` - 卡钱包交易记录表
|
||
- `tb_card_recharge_record` - 卡充值记录表
|
||
|
||
**删除表** - **BREAKING**：
|
||
- `tb_wallet` - 统一钱包表（由新的两张表替代）
|
||
- `tb_wallet_transaction` - 统一交易记录表（由新的两张表替代）
|
||
- `tb_recharge_record` - 统一充值记录表（由新的两张表替代）
|
||
|
||
### 代码层变更
|
||
|
||
**新增 Model**：
|
||
- `internal/model/agent_wallet.go` - 代理钱包相关 Model（AgentWallet、AgentWalletTransaction、AgentRechargeRecord）
|
||
- `internal/model/card_wallet.go` - 卡钱包相关 Model（CardWallet、CardWalletTransaction、CardRechargeRecord）
|
||
|
||
**删除 Model** - **BREAKING**：
|
||
- `internal/model/wallet.go` - 统一钱包 Model（由新的两个文件替代）
|
||
|
||
**新增 Store**：
|
||
- `internal/store/postgres/agent_wallet_store.go` - 代理钱包数据访问层
|
||
- `internal/store/postgres/agent_wallet_transaction_store.go` - 代理钱包交易记录访问层
|
||
- `internal/store/postgres/agent_recharge_store.go` - 代理充值记录访问层
|
||
- `internal/store/postgres/card_wallet_store.go` - 卡钱包数据访问层
|
||
- `internal/store/postgres/card_wallet_transaction_store.go` - 卡钱包交易记录访问层
|
||
- `internal/store/postgres/card_recharge_store.go` - 卡充值记录访问层
|
||
|
||
**删除 Store** - **BREAKING**：
|
||
- `internal/store/postgres/wallet_store.go` - 统一钱包 Store（由新的 Store 替代）
|
||
- `internal/store/postgres/wallet_transaction_store.go` - 统一交易记录 Store（由新的 Store 替代）
|
||
|
||
**重构 Service**：
|
||
- `internal/service/commission_*` - 佣金相关服务改用 `AgentWalletStore`
|
||
- `internal/service/order` - 订单服务改用 `CardWalletStore`
|
||
- `internal/service/recharge` - 充值服务拆分为代理充值和卡充值两个独立服务
|
||
|
||
**更新常量定义**：
|
||
- `pkg/constants/wallet.go` - 按钱包类型隔离常量定义和 Redis Key 生成函数
|
||
|
||
**更新依赖注入**：
|
||
- `internal/bootstrap/stores.go` - 注册新的 Store 实例
|
||
- `internal/bootstrap/services.go` - 更新 Service 依赖注入
|
||
|
||
### 监控和运维
|
||
|
||
**新增监控指标**（建议）：
|
||
- `agent_wallet_transaction_count` - 代理钱包交易量
|
||
- `agent_wallet_error_rate` - 代理钱包错误率
|
||
- `card_wallet_transaction_count` - 卡钱包交易量
|
||
- `card_wallet_error_rate` - 卡钱包错误率
|
||
|
||
**告警策略差异化**：
|
||
- 代理钱包错误率阈值更严格（建议 P0 级别告警）
|
||
- 卡钱包错误率阈值相对宽松（建议 P1 级别告警）
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `agent-wallet`: 代理钱包系统，提供店铺级别的主钱包和分佣钱包管理，支持充值、扣款、冻结、提现等操作
|
||
- `card-wallet`: 卡钱包系统，提供物联网卡和设备级别的钱包管理，支持充值、套餐扣费、余额查询等操作
|
||
|
||
### Modified Capabilities
|
||
|
||
- `wallet`: 需求变更 - 废弃统一钱包设计，拆分为 `agent-wallet` 和 `card-wallet` 两个完全独立的系统，要求在数据表、Model、Store、部分 Service 层面完全隔离
|
||
|
||
## Impact
|
||
|
||
### 受影响的模块
|
||
|
||
| 模块类型 | 受影响组件 | 变更类型 |
|
||
|---------|-----------|---------|
|
||
| **数据库** | `tb_wallet`、`tb_wallet_transaction`、`tb_recharge_record` | 删除并替换为 6 张新表 |
|
||
| **Model** | `internal/model/wallet.go` | 删除并替换为 2 个新文件 |
|
||
| **Store** | `internal/store/postgres/wallet_*.go` | 删除并替换为 6 个新 Store |
|
||
| **Service** | `internal/service/commission_*` | 依赖注入改为 `AgentWalletStore` |
|
||
| **Service** | `internal/service/order` | 依赖注入改为 `CardWalletStore` |
|
||
| **Service** | `internal/service/recharge` | 拆分为两个独立服务 |
|
||
| **Bootstrap** | `internal/bootstrap/stores.go`、`services.go` | 更新依赖注入配置 |
|
||
| **常量** | `pkg/constants/wallet.go` | 按钱包类型重构常量定义 |
|
||
| **Redis Key** | 钱包相关缓存 Key | 按钱包类型隔离（`agent_wallet:*`、`card_wallet:*`） |
|
||
|
||
### API 影响
|
||
|
||
**无 API 破坏性变更** - 所有对外 API 接口保持不变，仅内部实现重构
|
||
|
||
### 性能影响
|
||
|
||
**预期正向影响**：
|
||
- 代理钱包和卡钱包数据量独立，查询性能提升
|
||
- 索引优化可针对不同钱包类型的查询模式独立调优
|
||
- 减少单表数据量，降低锁竞争概率
|
||
|
||
### 部署影响
|
||
|
||
**当前处于开发阶段**：
|
||
- 无需数据迁移
|
||
- 删除旧表，创建新表
|
||
- 一次性部署代码变更
|
||
|
||
**如果未来生产环境部署**（预留方案）：
|
||
- 需要制定数据迁移脚本
|
||
- 需要停机窗口或在线双写迁移方案
|
||
|
||
### 风险评估
|
||
|
||
| 风险项 | 风险等级 | 缓解措施 |
|
||
|-------|---------|---------|
|
||
| 代码重构引入 Bug | 中 | 充分的手动测试，验证核心流程 |
|
||
| 遗漏依赖点导致编译失败 | 低 | 编译检查，逐步重构 |
|
||
| 数据表设计遗漏字段 | 低 | 参考现有 Model 设计，保持字段完整性 |
|
||
| 性能回退 | 低 | 索引设计参考现有表，预期性能持平或提升 |
|
||
|
||
### 测试策略
|
||
|
||
**手动测试覆盖**：
|
||
- 代理钱包：佣金发放、提现、余额查询
|
||
- 卡钱包：订单支付、充值、余额查询
|
||
- 边界场景：余额不足、并发扣款、冻结/解冻
|
||
|
||
**数据一致性验证**：
|
||
- 验证代理钱包交易记录的 `balance_before` 和 `balance_after` 准确性
|
||
- 验证卡钱包交易记录的余额变动准确性
|
||
- 验证乐观锁（version 字段）在并发场景下的有效性
|
||
|
||
### 时间估算
|
||
|
||
**预估工作量**：
|
||
- 数据库迁移文件编写：0.5 天
|
||
- Model 和 Store 重构：2 天
|
||
- Service 层重构：2 天
|
||
- Bootstrap 和常量更新：0.5 天
|
||
- 手动测试和验证：1 天
|
||
- **总计：6 天**
|
||
|
||
### 依赖和前置条件
|
||
|
||
- ✅ 项目处于开发阶段，可直接重构
|
||
- ✅ 无生产数据，无需迁移方案
|
||
- ✅ 技术栈符合项目规范（GORM、PostgreSQL、Redis）
|