跳到主要内容

Ruby Wallet Split Structure Implementation Plan

Status​

In Progress

Date​

2026-04-23

Owners​

  • Platform Backend
  • Wallet Domain

Affected Services​

  • wallet_service
  • rolling_service
  • promotion_service
  • game_service
  • gateway
  • admin_service
  • docs/specs/wallet/2026-04-23-ruby-wallet-split-structure.md
  • docs/adr/ADR-005-wallet-topology-bucket-ledger-model.md
  • docs/runbooks/wallet/ruby-wallet-topology-rollout.md

Goal​

Implement the clean Ruby Wallet split structure before production launch, without preserving legacy wallet fields as canonical domain state.

Success Signals​

  • Wallet source of truth is bucket, coupon grant, and ledger data.
  • Wallet shape is controlled by versioned topology and bucket-type configuration.
  • Sports, live, and slots betting policies are configurable from admin APIs.
  • All funding, settlement, rollback, transfer, and promotion credit paths have TDD coverage before implementation.
  • Local Docker validates sports and casino end-to-end money flows.

Preconditions​

  • Product confirms that live and slots share the casino wallet group for the first release.
  • Product confirms default policy values for sports normal and casino normal winning destinations.
  • Product confirms whether event rewards can target bonus, normal, points, or withdrawable buckets.
  • Product confirms whether existing local/staging data can be dropped or must be migrated.

Tasks​

  • Freeze this spec as the active wallet domain truth.
  • Add an ADR for wallet bucket plus append-only ledger as the canonical money model.
  • Add policy test matrix before touching wallet implementation.
  • Update shared contracts with stable role/provider enums and wallet DTOs; bucket type codes stay topology data, not hard-coded contract enums.
  • Add wallet-owned schema migrations for topology, bucket type, account, bucket, coupon grant, ledger, policy, bet authorization, and transfer tables.
  • Remove legacy flat wallet fields from canonical wallet contracts.
  • Implement topology loader and validator before implementing money commands.
  • Implement pure wallet policy engine for provider type, funding mode, deduction order, coupon eligibility, transfer policy, and withdrawable rolling attribution.
  • Implement settlement destination policy for topology-wallet bet settlement.
  • Ensure wallet commands resolve authoritative policy server-side; callers may submit only selected wallet source when wallet-selection mode requires it.
  • Rebuild wallet bet authorization on the policy engine.
  • Rebuild wallet bet settlement to use stored authorization snapshot.
  • Rebuild wallet rollback to restore stored funding sources.
  • Publish topology bet settlement and rollback outbox events for rolling progress and projection compatibility.
  • Implement topology-wallet deposit approval command requiring target bucket type code validated against the active topology.
  • Rebuild legacy deposit create, cash auto-approve, and recycle flows so they resolve topology targets and write the wallet ledger.
  • Implement topology-wallet promotion credit command so rebate, cashback, and lossback can credit points.
  • Implement topology-wallet coupon grant command around scoped coupon grants.
  • Implement topology-wallet promotion/coupon reversal command for saga compensation.
  • Implement topology-wallet transfer command for configured normal-wallet and points-to-normal transfer edges.
  • Implement topology-wallet player snapshot command for bucket and coupon display.
  • Wire legacy deposit approval callers to the topology-wallet deposit command.
  • Wire promotion settlement callers to the topology-wallet points credit command.
  • Wire promotion coupon issue callers to the topology-wallet coupon grant command.
  • Wire player-facing rebate/points transfer callers to the topology-wallet transfer command.
  • Replace withdrawal creation, withdrawal refund, and admin adjustment money writes with topology bucket commands while keeping compatibility routes stable.
  • Replace legacy withdrawal transfer UX/API with normal-wallet transfer.
  • Replace wallet-side rolling completion and cancellation handlers with topology-safe bucket commands.
  • Update rolling creation and progress to store topology version, wallet group, source bucket type, provider type, and policy snapshot.
  • Update promotion settlement tests and implementation for points credit.
  • Update game service wallet client payloads to pass provider type, provider ID, and selected wallet source when required.
  • Add admin policy CRUD routes with validation and audit logging.
  • Add admin topology CRUD and activation routes with validation and audit logging.
  • Add gateway player balance snapshot routes for split wallet display.
  • Update and promote the wallet topology rollout runbook after local Docker and staging validation are proven.
  • Update service docs and architecture docs after implementation.
  • Run service-level test suites.
  • Run local Docker end-to-end tests for sports and casino flows.

Implementation Target Map​

Primary code areas to replace or rewrite:

  • servers_v2/shared/contracts/src/rgb_contracts/enums.py
  • servers_v2/shared/contracts/src/rgb_contracts/wallet/
  • servers_v2/shared/rgb_db/src/rgb_db/models/player.py
  • servers_v2/shared/rgb_db/src/rgb_db/models/finance.py
  • servers_v2/wallet_service/app/services/wallet_bucket_commands.py
  • servers_v2/wallet_service/app/services/wallet_topology_policy.py
  • servers_v2/wallet_service/app/services/wallet_topology_store.py
  • servers_v2/wallet_service/app/api/routes/wallet.py
  • servers_v2/wallet_service/app/api/routes/topology.py
  • servers_v2/wallet_service/app/api/routes/bucket_wallet.py
  • servers_v2/wallet_service/app/api/routes/queries.py
  • servers_v2/promotion_service/app/api/routes/coupon.py
  • servers_v2/promotion_service/app/tasks/settlement.py
  • servers_v2/rolling_service/app/services/rolling_ops.py
  • servers_v2/rolling_service/app/services/event_consumer.py
  • servers_v2/game_service wallet client call sites
  • servers_v2/gateway player balance and finance routes
  • servers_v2/admin_service wallet topology and policy admin routes

Primary tests to add or rewrite:

  • wallet pure policy tests
  • wallet topology validation tests
  • wallet topology store tests
  • wallet topology command tests
  • wallet API command tests
  • promotion points credit tests
  • coupon grant saga tests
  • rolling attribution tests
  • gateway split-balance route tests
  • admin policy validation tests
  • local Docker end-to-end sports and casino flows

Risks​

  • Funding and settlement mistakes are direct money bugs; policy logic must be pure-function tested before I/O wiring.
  • Coupon grants have heterogeneous restrictions, so aggregating them into one balance would lose auditability and must be avoided.
  • Rolling inheritance on normal-wallet transfer is easy to get wrong if wallet and rolling updates are not transactionally coordinated.
  • Changing provider type mapping after bets are authorized can create settlement drift; wallet must store policy snapshots.
  • Admin policy changes can affect real-money authorization immediately; policy activation requires versioning, validation, and audit logs.
  • Topology changes are more dangerous than policy value changes because they alter available bucket types; activation must be blocked when unresolved balances or active records would become unreachable.

Done Definition​

  • Spec status is updated to Approved.
  • ADR is accepted.
  • Topology CRUD and activation tests pass.
  • All listed TDD suites pass locally.
  • Local Docker end-to-end validation passes.
  • No wallet mutation path writes directly to legacy flat player wallet fields.
  • New wallet shapes can be configured by topology without adding new player balance columns.
  • Cross-service review confirms wallet_service remains the only money writer.