junhong_cmp_fiber/openspec/changes/archive/2026-02-25-separate-agent-card-wallets/design.md

钱包系统分离 - 技术设计

Context

当前架构

当前系统使用统一钱包表设计，所有钱包类型存储在同一张表中：

tb_wallet (统一钱包表)
├─ resource_type (iot_card / device / shop)
├─ resource_id
├─ wallet_type (main / commission)
├─ balance, frozen_balance
└─ version (乐观锁)

tb_wallet_transaction (统一交易记录)
tb_recharge_record (统一充值记录)

代码层面：

• 统一的 WalletStore，所有钱包类型共用相同的数据访问方法
• 多个 Service 依赖同一个 Store：
  • commission_* Service（代理钱包）
  • order Service（卡钱包）
  • recharge Service（代理+卡）

现存问题

1. 隔离性不足：代理钱包和卡钱包在数据层和代码层耦合，某个钱包类型的问题可能影响其他类型
2. 性能优化受限：单表数据量大，索引优化需要兼顾多种查询模式，难以针对性优化
3. 业务语义模糊：代理钱包（店铺级别）和卡钱包（资源级别）在业务上差异很大，但使用同一套字段设计
4. 稳定性风险：代理钱包作为核心资产（涉及资金结算），需要更高的隔离级别

约束条件

• ✅ 项目处于开发阶段，无生产数据，可直接删除旧表
• ✅ 必须遵循 Handler → Service → Store → Model 分层架构
• ✅ 禁止使用外键约束和 GORM 关联关系
• ✅ 必须使用乐观锁（version 字段）防止并发余额冲突
• ✅ 所有常量定义在 pkg/constants/

Goals / Non-Goals

Goals

1. 数据层完全隔离：代理钱包和卡钱包使用独立的数据表，包括交易记录表和充值记录表
2. 代码层完全隔离：独立的 Model、Store，类型不兼容，编译期防止混用
3. 业务语义清晰化：代理钱包简化为 shop_id 主键设计，卡钱包保留 resource_type + resource_id 设计
4. 独立优化能力：两种钱包的索引、缓存策略、监控指标完全独立
5. 保持 API 兼容性：对外接口不变，仅内部实现重构

Non-Goals

1. 不做服务拆分：不将钱包系统拆分为独立的微服务，仍在单体应用内
2. 不引入抽象层：不创建统一的 WalletService 接口，两种钱包完全独立实现
3. 不做数据迁移：当前处于开发阶段，直接删除旧表，不考虑迁移脚本
4. 不修改对外 API：Handler 层接口保持不变，仅内部调用改为新的 Store

Decisions

决策 1：交易记录表和充值记录表也完全分离

决策：不仅分离钱包主表，交易记录表和充值记录表也按钱包类型分离

理由：

• 数据量级差异大：卡钱包交易记录可能是代理钱包的 100 倍以上（每次套餐扣费都有记录）
• 查询隔离：代理的对账报表不应该被卡交易的查询拖慢
• 索引优化独立：代理钱包的交易查询模式（按店铺、按时间范围）与卡钱包（按资源、按订单）完全不同

替代方案：

• ❌ 保留统一交易记录表，通过 wallet_table_type 字段区分：隔离不彻底，查询性能受限

代价：

• 如果未来需要跨钱包类型的全局交易统计，需要跨表查询（UNION）或创建视图

---

决策 2：代理钱包简化为 shop_id 主键设计

当前设计（统一表）：

tb_wallet (
    resource_type = 'shop',
    resource_id = shop_id,
    wallet_type = 'main' | 'commission'
)

新设计（简化）：

tb_agent_wallet (
    shop_id,
    wallet_type = 'main' | 'commission'
)

理由：

• 代理钱包只归属店铺，不需要 resource_type 字段
• 简化查询逻辑，直接用 shop_id 查询
• 类型更明确，编译期防止误用

索引设计：

UNIQUE INDEX idx_agent_wallet_shop_type (shop_id, wallet_type, deleted_at)
INDEX idx_agent_wallet_status (status)
INDEX idx_agent_wallet_shop_tag (shop_id_tag)  -- 多租户过滤

---

决策 3：卡钱包保留 resource_type + resource_id 设计

设计：

tb_card_wallet (
    resource_type = 'iot_card' | 'device',
    resource_id,
    balance, frozen_balance, version
)

理由：

• 卡钱包需要支持两种资源类型（物联网卡、设备）
• 保留灵活性，未来可能增加其他资源类型（如企业设备）
• 与现有业务逻辑保持一致

索引设计：

UNIQUE INDEX idx_card_wallet_resource (resource_type, resource_id, deleted_at)
INDEX idx_card_wallet_status (status)
INDEX idx_card_wallet_shop_tag (shop_id_tag)  -- 多租户过滤

---

决策 4：Model 层类型完全独立

设计：

// internal/model/agent_wallet.go
type AgentWallet struct {
    gorm.Model
    ShopID        uint
    WalletType    string
    Balance       int64
    FrozenBalance int64
    Version       int
}

// internal/model/card_wallet.go
type CardWallet struct {
    gorm.Model
    ResourceType  string
    ResourceID    uint
    Balance       int64
    FrozenBalance int64
    Version       int
}

理由：

• 两个独立类型，编译期防止混用（AgentWallet 不能传给 CardWalletStore）
• 字段设计针对各自业务场景优化
• 清晰的类型语义，代码可读性更高

替代方案：

• ❌ 共用一个 Wallet 基类 + 接口抽象：过度设计，增加复杂度

---

决策 5：Store 层完全独立

设计：

// internal/store/postgres/agent_wallet_store.go
type AgentWalletStore struct {
    db    *gorm.DB
    redis *redis.Client
}

func (s *AgentWalletStore) GetCommissionWallet(ctx, shopID) (*model.AgentWallet, error)
func (s *AgentWalletStore) FreezeBalanceWithTx(ctx, tx, walletID, amount, version) error

// internal/store/postgres/card_wallet_store.go
type CardWalletStore struct {
    db    *gorm.DB
    redis *redis.Client
}

func (s *CardWalletStore) GetByResourceTypeAndID(ctx, resourceType, resourceID) (*model.CardWallet, error)
func (s *CardWalletStore) DeductBalanceWithTx(ctx, tx, walletID, amount, version) error

理由：

• 方法名更具体（GetCommissionWallet vs GetByResourceTypeAndID），减少参数传递
• 每个 Store 只处理自己的表，职责单一
• 独立优化查询逻辑和缓存策略

事务处理：

• 所有需要事务的方法接收 tx *gorm.DB 参数
• 调用方（Service 层）负责开启和提交事务
• Store 层只执行数据库操作，不管理事务生命周期

---

决策 6：充值服务拆分

当前：

internal/service/recharge/
└─ service.go  // 处理所有类型钱包的充值

新设计：

internal/service/agent_recharge/
└─ service.go  // 只处理代理钱包充值

internal/service/card_recharge/
└─ service.go  // 只处理卡钱包充值

理由：

• 代理充值和卡充值的业务流程差异大：
  • 代理充值：金额限制更高（100元起）、支持线下转账、需要审核
  • 卡充值：金额限制更低（1元起）、仅支持在线支付、自动到账
• 拆分后代码更清晰，避免 if-else 分支判断
• 独立部署和监控（如果未来微服务化）

Handler 层不变：

• Handler 层根据用户类型调用不同的 Service
• 对外 API 接口保持不变

---

决策 7：Redis Key 按钱包类型隔离

当前：

wallet:balance:{wallet_id}
wallet:lock:{wallet_id}

新设计：

agent_wallet:balance:{shop_id}:{wallet_type}
agent_wallet:lock:{shop_id}:{wallet_type}

card_wallet:balance:{resource_type}:{resource_id}
card_wallet:lock:{resource_type}:{resource_id}

理由：

• 从 Key 就能明确区分钱包类型，避免误操作
• 独立的 Key 前缀便于监控和清理
• 支持针对性的 TTL 策略（代理钱包缓存时间可能更长）

常量定义（pkg/constants/wallet.go）：

func RedisAgentWalletBalanceKey(shopID uint, walletType string) string {
    return fmt.Sprintf("agent_wallet:balance:%d:%s", shopID, walletType)
}

func RedisCardWalletBalanceKey(resourceType string, resourceID uint) string {
    return fmt.Sprintf("card_wallet:balance:%s:%d", resourceType, resourceID)
}

---

决策 8：索引策略独立优化

代理钱包索引（低频、大金额）：

-- 主查询：按店铺查询钱包
idx_agent_wallet_shop_type (shop_id, wallet_type, deleted_at)

-- 次要查询：按状态过滤异常钱包
idx_agent_wallet_status (status)

-- 多租户过滤：GORM Callback 需要
idx_agent_wallet_shop_tag (shop_id_tag)

卡钱包索引（高频、小金额）：

-- 主查询：按资源查询钱包
idx_card_wallet_resource (resource_type, resource_id, deleted_at)

-- 次要查询：按状态过滤
idx_card_wallet_status (status)

-- 多租户过滤
idx_card_wallet_shop_tag (shop_id_tag)

交易记录索引：

代理钱包交易：

idx_agent_tx_wallet (agent_wallet_id, created_at)    -- 按钱包查询交易历史
idx_agent_tx_shop (shop_id, created_at)              -- 按店铺汇总交易
idx_agent_tx_ref (reference_type, reference_id)      -- 按关联业务查询
idx_agent_tx_type (transaction_type, created_at)     -- 按交易类型统计

卡钱包交易：

idx_card_tx_wallet (card_wallet_id, created_at)      -- 按钱包查询
idx_card_tx_resource (resource_type, resource_id, created_at)  -- 按资源查询
idx_card_tx_ref (reference_type, reference_id)       -- 按订单查询
idx_card_tx_type (transaction_type, created_at)      -- 按类型统计

---

决策 9：乐观锁继续使用 version 字段

设计：

// 扣款时检查 version
result := tx.Model(&model.AgentWallet{}).
    Where("id = ? AND balance >= ? AND version = ?", walletID, amount, currentVersion).
    Updates(map[string]interface{}{
        "balance": gorm.Expr("balance - ?", amount),
        "version": gorm.Expr("version + 1"),
    })

if result.RowsAffected == 0 {
    return errors.New(errors.CodeConcurrentConflict, "余额不足或并发冲突")
}

理由：

• 与现有钱包系统保持一致
• 乐观锁适用于读多写少的场景（钱包查询频繁，扣款相对低频）
• 相比悲观锁（SELECT FOR UPDATE），性能更好

并发处理：

• Service 层捕获 RowsAffected == 0 错误，重试 1-2 次
• 重试前重新读取最新余额和 version

---

决策 10：不引入抽象层

决策：不创建统一的 WalletService 接口或抽象基类

理由：

• 代理钱包和卡钱包的业务场景差异太大，强行抽象反而增加复杂度
• Go 推崇组合优于继承，过度抽象违背 Go 惯用法
• 两种钱包的方法签名不同（shop_id vs resource_type + resource_id）

替代方案：

• ❌ 创建 WalletService 接口，定义 GetBalance(id WalletID)：过度抽象，实际调用时仍需类型断言

如果未来需要通用逻辑：

• 可以提取为独立的 helper 函数，而不是接口
• 例如：pkg/wallet/helper.go 中定义 ValidateAmount(amount int64) error

---

Risks / Trade-offs

风险 1：代码重构引入 Bug

风险：重构涉及多个模块（Model、Store、Service、Bootstrap），可能引入逻辑错误

缓解措施：

• 逐步重构，先完成 Model 和 Store，再重构 Service
• 每个模块完成后进行编译检查
• 手动测试核心流程：
  • 代理钱包：佣金发放、提现、余额查询
  • 卡钱包：订单支付、充值、余额查询
  • 边界场景：余额不足、并发扣款

---

风险 2：遗漏依赖点导致编译失败

风险：可能有隐藏的依赖点未被发现，删除旧 Model 后编译失败

缓解措施：

• 先创建新 Model 和 Store，保留旧代码
• 逐步替换依赖点，每次替换后编译验证
• 最后删除旧 Model 和 Store，确保编译通过

---

风险 3：性能回退

风险：新表的索引设计不当，导致查询性能下降

缓解措施：

• 索引设计参考现有表，保持覆盖常用查询
• 分离后单表数据量减少，预期性能持平或提升
• 如有性能问题，可以针对性优化索引（不影响其他钱包类型）

---

权衡 1：完全分离交易记录表 vs 统一表

选择：完全分离

代价：

• 如果未来需要全局交易统计（跨钱包类型），需要 UNION 查询或创建视图
• 增加表数量（6 张表 vs 3 张表）

收益：

• 查询性能独立优化
• 数据量隔离，避免单表过大
• 代理钱包的对账查询不受卡钱包高频交易影响

结论：收益大于代价，全局交易统计并非高频需求，可以通过定时汇总解决

---

权衡 2：不引入抽象层 vs 统一接口

选择：不引入抽象层

代价：

• 如果未来需要第三种钱包类型（如企业钱包），需要独立实现，不能复用接口
• 代码重复度略高（如余额校验逻辑）

收益：

• 代码简单，符合 Go 惯用法
• 编译期类型安全，避免接口断言
• 每个钱包类型独立演进，互不影响

结论：当前场景不需要抽象层，如果未来真的需要，再重构也不迟（YAGNI 原则）

---

权衡 3：充值服务拆分 vs 统一服务

选择：拆分为两个独立服务

代价：

• 增加 Service 文件数量
• Handler 层需要根据用户类型调用不同 Service

收益：

• 代码逻辑清晰，避免 if-else 分支
• 业务规则独立（金额限制、支付方式、审核流程）
• 独立测试和监控

结论：拆分更符合单一职责原则，代价可接受

---

Migration Plan

实施步骤

由于当前处于开发阶段，无需数据迁移，直接重构：

阶段 1：数据库层（0.5 天）

1. 编写迁移文件创建 6 张新表
2. 本地执行迁移验证表结构
3. 删除旧表的迁移文件（tb_wallet, tb_wallet_transaction, tb_recharge_record）

阶段 2：Model 和 Store 层（2 天）

1. 创建新 Model：agent_wallet.go、card_wallet.go
2. 创建新 Store：
   • agent_wallet_store.go
   • agent_wallet_transaction_store.go
   • agent_recharge_store.go
   • card_wallet_store.go
   • card_wallet_transaction_store.go
   • card_recharge_store.go
3. 更新 pkg/constants/wallet.go（常量定义和 Redis Key 函数）
4. 保留旧 Model 和 Store（暂不删除）

阶段 3：Service 层重构（2 天）

1. 更新 internal/bootstrap/stores.go（注册新 Store）
2. 重构 commission_* Service（改用 AgentWalletStore）
3. 重构 order Service（改用 CardWalletStore）
4. 拆分 recharge Service 为两个独立服务
5. 更新 internal/bootstrap/services.go（依赖注入）
6. 编译验证，逐步替换依赖点

阶段 4：清理和测试（1.5 天）

1. 删除旧 Model：internal/model/wallet.go
2. 删除旧 Store：wallet_store.go、wallet_transaction_store.go
3. 编译检查，确保无引用残留
4. 手动测试核心流程
5. 数据一致性验证

总计：6 天

回滚策略

如果重构失败（仅适用于代码未合并到主分支前）：

1. 恢复旧 Model 和 Store 代码
2. 恢复旧的数据库表（从备份或重新运行旧迁移）
3. 恢复旧的依赖注入配置

预防措施：

• 在独立分支上进行重构
• 每个阶段完成后提交代码
• 保留旧代码直到新代码验证通过

---

Open Questions

Q1：是否需要创建数据库视图方便全局统计？

场景：未来可能需要全局交易统计（跨代理钱包和卡钱包）

选项：

• 选项 A：创建 VIEW v_all_wallet_transactions（UNION 两张交易表）
• 选项 B：不创建视图，需要时在应用层 UNION 查询
• 选项 C：创建定时任务，汇总到独立的统计表

建议：等到有明确需求时再决定，当前不创建（YAGNI 原则）

---

Q2：监控指标如何实现？

场景：提案中建议新增监控指标（agent_wallet_error_rate、card_wallet_error_rate）

问题：

• 是否在本次重构中实现监控埋点？
• 还是只预留接口，后续专门做监控系统？

建议：本次重构不包含监控实现，只确保代码层面可以区分钱包类型（便于未来埋点）

---

Q3：是否需要为 BaseModel 字段添加到新表？

当前：旧表包含 BaseModel（shop_id_tag、enterprise_id_tag 等多租户字段）

问题：新表是否需要保留这些字段？

建议：保留，因为系统使用 GORM Callback 自动过滤多租户数据，这些字段是必需的