470 lines
18 KiB
Markdown
470 lines
18 KiB
Markdown
# SOR.Bazaar 12-Factor Refactor Plan
|
|
|
|
Date: 2026-06-10
|
|
|
|
Scope reviewed:
|
|
- `Server/src/SOR.Bazaar`
|
|
- Bazaar persistence in `Server/src/SOR.Database/Contexts/BazaarDbContext.cs`
|
|
- Bazaar entities and migrations under `Server/src/SOR.Database`
|
|
- Bazaar wiring in `Server/src/SOR.Host`
|
|
|
|
Reference: https://12factor.net/
|
|
|
|
## Executive Summary
|
|
|
|
`SOR.Bazaar` is a compact service module that registers marketplace and store message handlers when `ENABLED_SERVICES` includes `bazaar`. It handles store browsing, Origin Point balances, booster pack purchases, prebuilt deck purchases, cosmetic purchases, player listings, listing purchases, auction bids, transactions, storefronts, and price suggestions.
|
|
|
|
The service already has useful 12-Factor foundations:
|
|
|
|
- It is enabled by host process formation instead of running as a separate custom executable.
|
|
- It uses explicit database contexts for bazaar, collection, catalog, and identity data.
|
|
- High-value P2P listing purchases use a shared Postgres transaction across contexts.
|
|
- Origin Point debits use conditional SQL updates to prevent overspending.
|
|
- Message contracts are centralized in `BazaarMessages.cs`.
|
|
- The module has no local filesystem state and no direct port binding.
|
|
|
|
The main gaps are structural and operational:
|
|
|
|
- Message handlers contain transport handling, validation, business rules, data access, transaction orchestration, DTO mapping, and response mapping.
|
|
- Store purchases mutate identity, collection, and bazaar data without a single shared transaction boundary.
|
|
- Auction bid and cancellation flows should use the same atomic transaction discipline as fixed-price listing purchases.
|
|
- Pricing, page-size limits, foil odds, supported currencies, sale-history windows, and listing rules are hardcoded.
|
|
- There is no visible idempotency model for purchase commands, which matters for client retry and message redelivery.
|
|
- There is no explicit auction settlement/expiration process.
|
|
- Marketplace audit data exists through transactions and purchase records, but there is no central audit boundary for all money/card mutations.
|
|
- Readiness is host-level only; Bazaar needs dependency-aware checks for Postgres schemas and any catalog/collection/identity dependencies.
|
|
|
|
The plan is to keep `SOR.Bazaar` as the marketplace module, but split handlers into thin transport adapters backed by application services, repositories, typed options, and explicit transaction/idempotency boundaries.
|
|
|
|
## Current Structure Observations
|
|
|
|
### Strong Foundations
|
|
|
|
- `AddBazaarService` clearly registers Bazaar handlers from one place.
|
|
- `BazaarDbContext` owns store products, listings, transactions, purchase records, booster grants, and auction bids.
|
|
- `BazaarHandlerBase` centralizes Origin Point debit/credit helpers.
|
|
- `BazaarBuyListingHandler` uses a shared Npgsql transaction across `BazaarDbContext`, `CollectionDbContext`, and `SorIdentityDbContext`.
|
|
- P2P listing claim uses a conditional SQL update to avoid duplicate sale claims.
|
|
- Listing browsing clamps page size to a maximum of 100.
|
|
- Store products support active windows through `AvailableFrom` and `AvailableUntil`.
|
|
- Masked listings avoid exposing card definition data to clients.
|
|
|
|
### Main Problems
|
|
|
|
- Each handler owns too much business logic.
|
|
- `BazaarBuyBoosterPackHandler` is large and combines pack validation, slot JSON parsing, random card grants, Origin Point debiting, collection writes, purchase records, grant records, and response enrichment.
|
|
- `BazaarBuyPrebuiltDeckHandler` grants cards/decks and records purchases after debiting Origin Points, but does not use the shared transaction helper.
|
|
- `BazaarBuyCosmeticHandler` follows the same store-purchase risk pattern.
|
|
- `BazaarCancelListingHandler` can refund an auction winner and cancel a listing without a shared transaction across identity and bazaar contexts.
|
|
- `BazaarPlaceBidHandler` uses a shared transaction but loads the current winning bid without a row lock or conditional update pattern.
|
|
- `BazaarListCardHandler` checks for active listings before insert, but this should be backed by a database constraint or transactional claim to prevent duplicate active listings under concurrency.
|
|
- Auction expiration is checked when placing bids, but there is no obvious background job or admin process that closes expired auctions and settles winners.
|
|
- `BazaarBuyListingHandler` creates an unused `PurchaseRecord` object and adds the same `BazaarTransaction` twice before saving.
|
|
- Origin Point amounts are cast from decimal to int in several flows.
|
|
- Currency is hardcoded to `Gold` in marketplace flows while the balance field is `OriginPoints`, so naming and rules need to be reconciled.
|
|
- There is no visible `Server/tests/SOR.Bazaar.Tests` project.
|
|
|
|
## Target Bazaar Shape
|
|
|
|
Keep `SOR.Bazaar` as the marketplace service module, but split it into focused layers:
|
|
|
|
```text
|
|
Server/src/SOR.Bazaar/
|
|
Configuration/
|
|
BazaarOptions.cs
|
|
BazaarListingOptions.cs
|
|
BazaarStoreOptions.cs
|
|
BazaarAuctionOptions.cs
|
|
BazaarOptionsValidator.cs
|
|
Bootstrap/
|
|
BazaarRegistration.cs
|
|
BazaarHandlersRegistration.cs
|
|
BazaarJobsRegistration.cs
|
|
BazaarHealthChecks.cs
|
|
Contracts/
|
|
BazaarMessages.cs
|
|
BazaarErrors.cs
|
|
Application/
|
|
Store/
|
|
StoreQueryService.cs
|
|
BoosterPackPurchaseService.cs
|
|
PrebuiltDeckPurchaseService.cs
|
|
CosmeticPurchaseService.cs
|
|
Marketplace/
|
|
ListingQueryService.cs
|
|
ListingCommandService.cs
|
|
ListingPurchaseService.cs
|
|
AuctionBidService.cs
|
|
AuctionSettlementService.cs
|
|
PriceSuggestionService.cs
|
|
Persistence/
|
|
IBazaarRepository.cs
|
|
ICollectionInventoryRepository.cs
|
|
ICatalogLookupRepository.cs
|
|
IOriginPointLedger.cs
|
|
IBazaarUnitOfWork.cs
|
|
BazaarTransactionRunner.cs
|
|
Idempotency/
|
|
IBazaarCommandIdempotencyStore.cs
|
|
Mapping/
|
|
BazaarDtoMapper.cs
|
|
Handlers/
|
|
BazaarGetStoreHandler.cs
|
|
BazaarBuyBoosterPackHandler.cs
|
|
...
|
|
Jobs/
|
|
SettleExpiredAuctionsJob.cs
|
|
RebuildPriceSuggestionsJob.cs
|
|
```
|
|
|
|
Desired handler shape:
|
|
|
|
- Deserialize request.
|
|
- Read authenticated account ID.
|
|
- Call one application service.
|
|
- Map domain result to `ServerMessage`.
|
|
- Avoid direct EF queries in handlers.
|
|
|
|
## 12-Factor Gap Map
|
|
|
|
### 1. Codebase
|
|
|
|
Mostly aligned. `SOR.Bazaar` is one module in the server codebase, but responsibilities are concentrated in message handlers.
|
|
|
|
Plan:
|
|
- Keep one Bazaar module.
|
|
- Split business workflows into application services.
|
|
- Keep message handlers as transport adapters.
|
|
- Add Bazaar tests alongside other server tests.
|
|
|
|
### 2. Dependencies
|
|
|
|
Partially aligned. Dependencies are explicit through project references and DI, but business logic depends directly on EF contexts everywhere.
|
|
|
|
Plan:
|
|
- Keep EF Core and Postgres as explicit dependencies.
|
|
- Introduce repositories for bazaar, collection, catalog, and identity operations.
|
|
- Introduce an `IOriginPointLedger` for all balance changes.
|
|
- Introduce `IBazaarUnitOfWork` or `BazaarTransactionRunner` for cross-context transactions.
|
|
|
|
### 3. Config
|
|
|
|
Weakly aligned. Bazaar runtime rules are mostly code constants.
|
|
|
|
Plan:
|
|
- Add typed `BazaarOptions`.
|
|
- Validate options at startup.
|
|
- Move operational rules into config where appropriate.
|
|
|
|
Candidate config shape:
|
|
|
|
```json
|
|
{
|
|
"Bazaar": {
|
|
"Listings": {
|
|
"DefaultPageSize": 24,
|
|
"MaxPageSize": 100,
|
|
"MaxAuctionDurationHours": 168,
|
|
"AllowMaskedListings": true
|
|
},
|
|
"Store": {
|
|
"FoilChance": 0.05,
|
|
"AllowUsdPrices": false
|
|
},
|
|
"Pricing": {
|
|
"SuggestedPriceSaleWindowDays": 30,
|
|
"SuggestedPriceMinimumSales": 3,
|
|
"SalvageFloorMultiplier": 4
|
|
},
|
|
"Auctions": {
|
|
"SettlementBatchSize": 100,
|
|
"SettlementIntervalSeconds": 60
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4. Backing Services
|
|
|
|
Mostly aligned. Bazaar uses Postgres schemas as attached backing services. Catalog CDN URLs are data references, not direct Bazaar network dependencies.
|
|
|
|
Plan:
|
|
- Treat `BazaarDbContext`, `CollectionDbContext`, `CatalogDbContext`, and `SorIdentityDbContext` as required attached resources.
|
|
- Add readiness checks for required schemas/tables.
|
|
- Document that multi-context transactions require the same Postgres database/connection target.
|
|
- If any future payment provider is added, isolate it as an attached external service with retries, idempotency, and reconciliation.
|
|
|
|
### 5. Build, Release, Run
|
|
|
|
Partially aligned. Bazaar runtime does not apply migrations directly, but marketplace data and store products need release discipline.
|
|
|
|
Plan:
|
|
- Keep schema migrations outside normal runtime startup.
|
|
- Treat store catalog changes as admin/release data changes.
|
|
- Add release checks for active product data, pack slot JSON validity, deck card validity, and cosmetic asset URLs.
|
|
- Add seed/import jobs for store product data instead of hand-editing production data.
|
|
|
|
### 6. Processes
|
|
|
|
Partially aligned. Bazaar is a request/response service module. Auction settlement is not clearly represented as a process.
|
|
|
|
Plan:
|
|
- Keep request handlers in the `bazaar` service role.
|
|
- Add a separate `bazaar-jobs` role for auction settlement, price cache rebuilds, and store-data validation.
|
|
- Avoid starting job loops in normal gateway/game/bazaar request workers unless explicitly enabled.
|
|
|
|
### 7. Port Binding
|
|
|
|
Aligned through `SOR.Host`. Bazaar does not bind a port directly.
|
|
|
|
Plan:
|
|
- Keep port binding in `SOR.Host`.
|
|
- Expose Bazaar readiness through host health checks.
|
|
- Do not add a Bazaar-specific HTTP listener.
|
|
|
|
### 8. Concurrency
|
|
|
|
Partially aligned. Fixed-price purchases use an atomic claim pattern, but other flows need equivalent guarantees.
|
|
|
|
Plan:
|
|
- Use one transaction runner for all high-value mutations.
|
|
- Add database constraints or conditional updates for:
|
|
- one active listing per player card
|
|
- one winning bid per auction
|
|
- listing status transitions
|
|
- idempotent purchase command execution
|
|
- Use row locks or conditional updates when replacing the winning bid.
|
|
- Make auction settlement idempotent.
|
|
- Define retry behavior for serialization/deadlock errors.
|
|
|
|
### 9. Disposability
|
|
|
|
Mostly aligned for request handlers. There are no long-running loops in `SOR.Bazaar` today.
|
|
|
|
Plan:
|
|
- Continue passing cancellation tokens to EF operations.
|
|
- Add cancellation-aware job processing if auction settlement or price rebuild jobs are introduced.
|
|
- Keep mutation workflows short and transactional.
|
|
- Avoid partial writes by ensuring store purchases and auction cancellation use shared transactions.
|
|
|
|
### 10. Dev/Prod Parity
|
|
|
|
Partially aligned. The same Postgres-backed code runs everywhere, but product data and pack JSON validity can drift.
|
|
|
|
Plan:
|
|
- Provide local seed/import data for packs, decks, cosmetics, and listings.
|
|
- Add validation commands that run in every environment.
|
|
- Keep store product rules environment-neutral unless explicitly configured.
|
|
- Use the same auction settlement path locally and in production.
|
|
|
|
### 11. Logs
|
|
|
|
Weakly aligned. Handlers do not visibly log business events.
|
|
|
|
Plan:
|
|
- Add structured logs through application services, not every handler.
|
|
- Log high-value events: purchase completed, listing created/cancelled/sold, bid placed/refunded, auction settled, insufficient funds, invalid store config.
|
|
- Add metrics for purchase latency, listing count, bid failures, settlement lag, transaction rollback count, and idempotency replay count.
|
|
- Avoid logging full account inventory or sensitive account details.
|
|
|
|
Suggested fields:
|
|
|
|
- `accountId`
|
|
- `listingId`
|
|
- `purchaseId`
|
|
- `productId`
|
|
- `playerCardId`
|
|
- `amount`
|
|
- `currency`
|
|
- `messageSeq`
|
|
- `idempotencyKey`
|
|
|
|
### 12. Admin Processes
|
|
|
|
Partially aligned. Store product and auction operations need explicit admin/job surfaces.
|
|
|
|
Plan:
|
|
- Add admin processes for importing store products, validating pack slot JSON, validating prebuilt decks, and settling expired auctions.
|
|
- Add an audit surface for Origin Point changes and item ownership changes.
|
|
- Keep admin-triggered jobs durable and retryable.
|
|
- Document operational recovery for failed purchase, failed settlement, and inconsistent listing state.
|
|
|
|
## Refactor Phases
|
|
|
|
### Phase 0: Baseline Tests and Bug Cleanup
|
|
|
|
Goals:
|
|
- Capture current behavior before structural changes.
|
|
- Fix obvious high-risk issues behind tests.
|
|
|
|
Work:
|
|
- Add tests for listing creation, fixed-price purchase, auction bid replacement, auction cancellation refund, booster purchase, prebuilt deck purchase, and cosmetic purchase.
|
|
- Add tests for insufficient funds, duplicate listing attempts, own-listing purchase prevention, and expired auctions.
|
|
- Cover `BazaarBuyListingHandler` transaction creation so duplicate transaction insertion cannot regress.
|
|
- Add tests for invalid booster slot JSON and empty card pools.
|
|
|
|
Done when:
|
|
- Bazaar mutation behavior has executable coverage.
|
|
- Refactoring can proceed without relying only on manual client testing.
|
|
|
|
### Phase 1: Typed Options and Validation
|
|
|
|
Goals:
|
|
- Move operational Bazaar rules into validated config.
|
|
|
|
Work:
|
|
- Add `BazaarOptions`, `BazaarListingOptions`, `BazaarStoreOptions`, `BazaarPricingOptions`, and `BazaarAuctionOptions`.
|
|
- Bind and validate options in Bazaar registration.
|
|
- Replace hardcoded page-size limits, foil chance, suggested-price windows, and auction duration limits with options.
|
|
- Keep defaults equivalent to current behavior.
|
|
|
|
Done when:
|
|
- Bazaar starts with validated options.
|
|
- Operators can tune marketplace rules without code changes.
|
|
|
|
### Phase 2: Application Services
|
|
|
|
Goals:
|
|
- Make handlers thin and workflows testable.
|
|
|
|
Work:
|
|
- Extract store purchase workflows:
|
|
- `BoosterPackPurchaseService`
|
|
- `PrebuiltDeckPurchaseService`
|
|
- `CosmeticPurchaseService`
|
|
- Extract marketplace workflows:
|
|
- `ListingCommandService`
|
|
- `ListingPurchaseService`
|
|
- `AuctionBidService`
|
|
- `PriceSuggestionService`
|
|
- Keep public message contracts unchanged.
|
|
|
|
Done when:
|
|
- Handlers mostly deserialize, call services, and return mapped responses.
|
|
- Business workflows can be unit/integration tested without transport boilerplate.
|
|
|
|
### Phase 3: Transaction Runner and Ledger
|
|
|
|
Goals:
|
|
- Make all money/card mutations atomic and consistent.
|
|
|
|
Work:
|
|
- Create `BazaarTransactionRunner` for shared cross-context transactions.
|
|
- Create `IOriginPointLedger` for debit, credit, balance reads, and audit metadata.
|
|
- Route all store purchases, listing purchases, bids, refunds, and cancellations through the transaction runner.
|
|
- Add explicit transaction result types for rollback-safe errors.
|
|
|
|
Done when:
|
|
- No high-value mutation writes across contexts without a single transaction boundary.
|
|
- Origin Point changes have one implementation path.
|
|
|
|
### Phase 4: Idempotency
|
|
|
|
Goals:
|
|
- Make purchase and bid commands safe under retries.
|
|
|
|
Work:
|
|
- Add an idempotency key to mutating Bazaar requests or derive one from a message envelope if available.
|
|
- Store command execution results for purchase/listing/bid commands.
|
|
- Return the original result on duplicate command replay.
|
|
- Add unique constraints where appropriate.
|
|
|
|
Done when:
|
|
- Client retry cannot double-purchase, double-grant, or double-bid.
|
|
- Message redelivery behavior is documented and tested.
|
|
|
|
### Phase 5: Marketplace Concurrency Hardening
|
|
|
|
Goals:
|
|
- Make P2P marketplace operations safe under high contention.
|
|
|
|
Work:
|
|
- Add a database-backed guarantee that one player card cannot have multiple active listings.
|
|
- Make listing status transitions conditional and auditable.
|
|
- Make winning bid replacement atomic with row locks or conditional updates.
|
|
- Add retry policy for known transient Postgres failures.
|
|
- Add settlement-safe state transitions for auctions.
|
|
|
|
Done when:
|
|
- Concurrent listing, buying, bidding, and cancellation tests pass.
|
|
- Database constraints enforce the same invariants as application code.
|
|
|
|
### Phase 6: Auction Settlement Jobs
|
|
|
|
Goals:
|
|
- Represent expired auction processing as a 12-Factor admin process.
|
|
|
|
Work:
|
|
- Add `SettleExpiredAuctionsJob`.
|
|
- Transfer card ownership, credit seller, mark listing sold/expired, and create transaction records in one transaction.
|
|
- Make settlement idempotent and batch-based.
|
|
- Register the job only in a dedicated `bazaar-jobs` role or admin process.
|
|
|
|
Done when:
|
|
- Expired auctions settle without waiting for a user action.
|
|
- Settlement can be safely retried.
|
|
|
|
### Phase 7: Store Data Validation and Import
|
|
|
|
Goals:
|
|
- Treat store product data as release/admin data.
|
|
|
|
Work:
|
|
- Add validation for booster `SlotsJson`.
|
|
- Validate that prebuilt deck cards reference published catalog cards.
|
|
- Validate cosmetic asset URLs and product availability windows.
|
|
- Add import/seed commands for packs, decks, and cosmetics.
|
|
|
|
Done when:
|
|
- Bad store data is caught before players can purchase it.
|
|
- Store content can be promoted across environments repeatably.
|
|
|
|
### Phase 8: Observability and Readiness
|
|
|
|
Goals:
|
|
- Make Bazaar operations diagnosable in production.
|
|
|
|
Work:
|
|
- Add Bazaar readiness checks for required DbContexts.
|
|
- Add metrics for purchase success/failure, bid success/failure, settlement lag, active listings, active auctions, and rollback count.
|
|
- Add structured audit logs for every Origin Point and ownership mutation.
|
|
- Add dashboards or runbook notes for marketplace health.
|
|
|
|
Done when:
|
|
- Operators can answer what purchases, listings, bids, refunds, and settlements occurred and whether any are stuck.
|
|
|
|
## Suggested Work Order
|
|
|
|
1. Add baseline tests for high-value mutation flows.
|
|
2. Fix obvious duplicate transaction/audit issues under tests.
|
|
3. Add typed Bazaar options with current defaults.
|
|
4. Extract application services behind existing handlers.
|
|
5. Introduce a transaction runner and Origin Point ledger.
|
|
6. Add idempotency for purchase/listing/bid commands.
|
|
7. Add database constraints and concurrency tests.
|
|
8. Add auction settlement as a dedicated job/admin process.
|
|
9. Add store data validation/import commands.
|
|
10. Add readiness checks, logs, metrics, and runbook documentation.
|
|
|
|
## Completion Criteria
|
|
|
|
The refactor is complete when:
|
|
|
|
- Bazaar handlers are thin transport adapters.
|
|
- Store purchases, listing purchases, bids, refunds, and cancellations use one transaction strategy.
|
|
- Mutating commands are idempotent under retry/redelivery.
|
|
- Database constraints enforce critical marketplace invariants.
|
|
- Auction expiration and settlement are handled by a dedicated, retryable process.
|
|
- Store product data is validated before release.
|
|
- Runtime config is typed and validated.
|
|
- Bazaar readiness accounts for required database schemas.
|
|
- Tests cover high-value purchase, listing, bidding, and settlement workflows.
|
|
|
|
## Immediate Low-Risk Next Steps
|
|
|
|
- Add a `BazaarOptions` class and bind it without changing behavior.
|
|
- Add tests around `BazaarBuyListingHandler` to lock down transaction/audit behavior.
|
|
- Extract `IOriginPointLedger` while preserving the current SQL update logic.
|
|
- Add a validation command for booster pack `SlotsJson`.
|
|
- Document the current assumption that all Bazaar-related DbContexts point at the same Postgres database for shared transactions.
|