Files
sor/SOR.Bazaar.12FactorPlan.md
2026-07-02 13:09:05 -04:00

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.