csxj2026/junhong_cmp_fiber

Files

构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m17s

Details

## 变更概述
将统一钱包系统拆分为代理钱包和卡钱包两个独立系统，实现数据表和代码层面的完全隔离。

## 数据库变更
- 新增 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>

2026-02-25 09:51:00 +08:00

6.5 KiB

Raw Blame History

钱包系统分离提案

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）

6.5 KiB Raw Blame History Unescape Escape