diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index cb742b2..a22f398 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -61,18 +61,18 @@ Requirements for Phase 1 (Development Focus: Live Tournament Management). Each m - [x] **FIN-01**: Buy-in configuration (amount, starting chips, per-player rake, fixed rake, house contribution, bounty cost, points) - [x] **FIN-02**: Multiple rake categories (staff fund, league fund, house) -- [ ] **FIN-03**: Late registration cutoff (by level, by time, or by level AND remaining time — e.g., "end of Level 6 or first 90 minutes, whichever comes first") -- [ ] **FIN-04**: Re-entry support (distinct from rebuy — new entry after busting) +- [x] **FIN-03**: Late registration cutoff (by level, by time, or by level AND remaining time — e.g., "end of Level 6 or first 90 minutes, whichever comes first") +- [x] **FIN-04**: Re-entry support (distinct from rebuy — new entry after busting) - [x] **FIN-05**: Rebuy configuration (cost, chips, rake, points, limits, level/time cutoff, chip threshold) - [x] **FIN-06**: Add-on configuration (cost, chips, rake, points, availability window) -- [ ] **FIN-07**: Fixed bounty system (bounty cost, chip issued, hitman tracking, chain tracking, cash-out) -- [ ] **FIN-08**: Prize pool auto-calculation from all financial inputs -- [ ] **FIN-09**: Guaranteed pot support (house covers shortfall) +- [x] **FIN-07**: Fixed bounty system (bounty cost, chip issued, hitman tracking, chain tracking, cash-out) +- [x] **FIN-08**: Prize pool auto-calculation from all financial inputs +- [x] **FIN-09**: Guaranteed pot support (house covers shortfall) - [x] **FIN-10**: Payout structures (percentage, fixed, custom table) with configurable rounding - [ ] **FIN-11**: Chop/deal support (ICM calculator, chip-chop, even-chop, custom) -- [ ] **FIN-12**: End-of-season withholding (reserve rake portion for season prizes) -- [ ] **FIN-13**: Every financial action generates a receipt with full transaction log -- [ ] **FIN-14**: Transaction editing with audit trail and receipt reprint capability +- [x] **FIN-12**: End-of-season withholding (reserve rake portion for season prizes) +- [x] **FIN-13**: Every financial action generates a receipt with full transaction log +- [x] **FIN-14**: Transaction editing with audit trail and receipt reprint capability ### Player Management @@ -337,18 +337,18 @@ Which phases cover which requirements. Updated during roadmap reorganization. | MULTI-02 | Phase 1 | Pending | | FIN-01 | Phase 1 | Complete | | FIN-02 | Phase 1 | Complete | -| FIN-03 | Phase 1 | Pending | -| FIN-04 | Phase 1 | Pending | +| FIN-03 | Phase 1 | Complete | +| FIN-04 | Phase 1 | Complete | | FIN-05 | Phase 1 | Complete | | FIN-06 | Phase 1 | Complete | -| FIN-07 | Phase 1 | Pending | -| FIN-08 | Phase 1 | Pending | -| FIN-09 | Phase 1 | Pending | +| FIN-07 | Phase 1 | Complete | +| FIN-08 | Phase 1 | Complete | +| FIN-09 | Phase 1 | Complete | | FIN-10 | Phase 1 | Complete | | FIN-11 | Phase 1 | Pending | -| FIN-12 | Phase 1 | Pending | -| FIN-13 | Phase 1 | Pending | -| FIN-14 | Phase 1 | Pending | +| FIN-12 | Phase 1 | Complete | +| FIN-13 | Phase 1 | Complete | +| FIN-14 | Phase 1 | Complete | | PLYR-01 | Phase 1 | Complete | | PLYR-02 | Phase 1 | Pending | | PLYR-03 | Phase 1 | Pending | diff --git a/.planning/STATE.md b/.planning/STATE.md index 53f174b..46f2487 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -8,7 +8,7 @@ progress: total_phases: 1 completed_phases: 0 total_plans: 14 - completed_plans: 7 + completed_plans: 8 --- # Project State @@ -23,28 +23,28 @@ See: .planning/PROJECT.md (updated 2026-02-28) ## Current Position Phase: 1 of 7 (Tournament Engine) -Plan: 8 of 14 in current phase +Plan: 9 of 14 in current phase Status: Executing Phase 1 -Last activity: 2026-03-01 — Completed Plan M (Layout Shell) +Last activity: 2026-03-01 — Completed Plan F (Financial Engine) -Progress: [█████░░░░░] 50% +Progress: [██████░░░░] 57% ## Performance Metrics **Velocity:** -- Total plans completed: 7 +- Total plans completed: 8 - Average duration: 8min -- Total execution time: 0.97 hours +- Total execution time: 1.12 hours **By Phase:** | Phase | Plans | Total | Avg/Plan | |-------|-------|-------|----------| -| 01-tournament-engine | 7 | 58min | 8min | +| 01-tournament-engine | 8 | 67min | 8min | **Recent Trend:** -- Last 5 plans: 01-10 (5min), 01-04 (8min), 01-05 (10min), 01-03 (5min), 01-13 (5min) -- Trend: accelerating +- Last 5 plans: 01-04 (8min), 01-05 (10min), 01-03 (5min), 01-13 (5min), 01-06 (9min) +- Trend: steady *Updated after each plan completion* @@ -86,6 +86,11 @@ Recent decisions affecting current work: - [01-13]: FAB actions dispatched via callback prop for centralized routing in layout - [01-13]: Multi-tournament state is a separate store from singleton tournament state - [01-13]: DataTable uses Record with render functions (not generics) for Svelte compat +- [01-06]: PKO bounty half-split uses integer division (cashPortion = bountyValue/2, bountyPortion = remainder) +- [01-06]: Unique entry count for bracket selection uses COUNT(DISTINCT player_id) on non-undone buyin tx only +- [01-06]: Late reg checks level AND time cutoffs independently (either exceeded closes registration) +- [01-06]: Rebuy/addon rake splits proportionally scaled from buyin rake splits (last gets remainder) +- [01-06]: CI gate: CalculatePayoutsFromPool is pure function tested with 10,000+ random inputs, zero deviation ### Pending Todos @@ -103,5 +108,5 @@ None yet. ## Session Continuity Last session: 2026-03-01 -Stopped at: Completed 01-13-PLAN.md (Layout Shell) +Stopped at: Completed 01-06-PLAN.md (Financial Engine) Resume file: None diff --git a/.planning/phases/01-tournament-engine/01-06-SUMMARY.md b/.planning/phases/01-tournament-engine/01-06-SUMMARY.md new file mode 100644 index 0000000..d2e7419 --- /dev/null +++ b/.planning/phases/01-tournament-engine/01-06-SUMMARY.md @@ -0,0 +1,131 @@ +--- +phase: 01-tournament-engine +plan: 06 +subsystem: financial +tags: [int64, poker, buyin, rebuy, payout, bounty, pko, receipt, audit, rake] + +# Dependency graph +requires: + - phase: 01-tournament-engine/plan-03 + provides: audit trail and undo engine + - phase: 01-tournament-engine/plan-05 + provides: buyin configs with rake splits, payout structures with brackets +provides: + - Financial transaction engine (buy-in, rebuy, add-on, re-entry) + - PKO bounty transfer with half-split chain tracking + - Prize pool calculation from all transaction types + - Payout distribution with int64 rounding (round DOWN, remainder to 1st) + - CI gate test proving sum(payouts) == prize_pool across 10,000+ inputs + - Bubble prize proposal/confirm with proportional shaving + - Receipt generation with sequential numbering and reprint + - Late registration with level AND time cutoffs plus admin override + - Season reserve tracking via rake split categories + - Financial API routes (prize-pool, payouts, transactions, receipts) +affects: [01-tournament-engine/plan-07, 01-tournament-engine/plan-09, 01-tournament-engine/plan-12] + +# Tech tracking +tech-stack: + added: [] + patterns: + - "int64 cents for all monetary values (zero float64)" + - "Round DOWN to venue denomination, remainder to 1st place" + - "Property-based CI gate test with 10,000+ random payout combinations" + - "Rake split transactions per category (house, staff, league, season_reserve)" + - "Proportional rake scaling for rebuy/addon (different rake amounts)" + +key-files: + created: + - internal/financial/engine.go + - internal/financial/engine_test.go + - internal/financial/payout.go + - internal/financial/payout_test.go + - internal/financial/receipt.go + - internal/server/routes/financials.go + modified: [] + +key-decisions: + - "PKO bounty half-split uses integer division (half = bountyValue/2, remainder stays with bounty portion)" + - "Unique entry count for bracket selection uses COUNT(DISTINCT player_id) on non-undone buyin transactions" + - "Rebuy/addon rake splits are proportionally scaled from buyin rake splits" + - "Receipt number is sequential per tournament (COUNT of existing receipts + 1)" + - "Bubble prize shaves proportionally from top 3 positions, extending to 5 if needed" + - "Late reg checks level AND time cutoffs independently (either exceeded closes registration)" + +patterns-established: + - "Financial engine pattern: load tournament info, load buyin config, validate, create transaction, audit, broadcast" + - "CalculatePayoutsFromPool is a pure function for testability and CI gate" + - "Transaction undo marks undone=1 and reverses player state effects" + +requirements-completed: [FIN-03, FIN-04, FIN-07, FIN-08, FIN-09, FIN-12, FIN-13, FIN-14] + +# Metrics +duration: 9min +completed: 2026-03-01 +--- + +# Plan 06: Financial Engine Summary + +**Int64 financial engine with buy-in/rebuy/addon/re-entry transactions, PKO bounty half-split, payout calculation with CI gate (10,000+ tests, zero deviation), bubble prize, receipts, and late registration cutoffs** + +## Performance + +- **Duration:** 9 min +- **Started:** 2026-03-01T03:06:59Z +- **Completed:** 2026-03-01T03:16:22Z +- **Tasks:** 2 +- **Files created:** 6 + +## Accomplishments +- Full financial transaction engine processing buy-ins, rebuys, add-ons, re-entries with all validation checks +- PKO progressive knockout bounty transfer with half cash / half bounty split and chain tracking +- CI gate test proving sum(payouts) == prize_pool across 10,000+ random combinations -- zero deviation +- Prize pool auto-calculation from all non-undone transactions minus categorized rake +- Late registration enforcement with level AND time cutoffs, admin override logged in audit trail +- Receipt generation with sequential numbering, venue info, and reprint capability +- Financial API routes for prize pool, payouts, transactions, receipts, bubble prize, and season reserves + +## Task Commits + +Each task was committed atomically: + +1. **Task F1: Financial transaction engine** - `51153df` (feat) +2. **Task F2: Prize pool, payouts, receipts, and API routes** - `56a7ef1` (feat) + +## Files Created/Modified +- `internal/financial/engine.go` - Financial transaction engine (buy-in, rebuy, addon, re-entry, bounty, undo) +- `internal/financial/engine_test.go` - 14 tests for all transaction flows and edge cases +- `internal/financial/payout.go` - Prize pool calculation, payout distribution, bubble prize +- `internal/financial/payout_test.go` - 7 tests including CI gate (10,000+ random combinations) +- `internal/financial/receipt.go` - Receipt generation, retrieval, and reprint +- `internal/server/routes/financials.go` - API routes for all financial endpoints + +## Decisions Made +- PKO bounty half-split uses integer division: cashPortion = bountyValue/2, bountyPortion = bountyValue - cashPortion (handles odd cents correctly) +- Unique entry count for payout bracket selection uses COUNT(DISTINCT player_id) on non-undone buyin transactions only (not rebuys, not re-entries) +- Rebuy and addon rake splits are proportionally scaled from the buyin rake split amounts (last split gets remainder for exact sum) +- Receipt numbering is sequential per tournament based on count of existing receipts +- Bubble prize shaves proportionally from top 3 positions, extending to top 5 if the top 3 cannot cover the amount +- Late registration checks level AND time cutoffs independently -- if either is exceeded, registration closes +- Rounding denomination loaded from venue_settings (default 100 cents if not configured) +- Guaranteed pot support: if FinalPrizePool < Guarantee, HouseContribution = Guarantee - PrizePool + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered +- Task F2 files were inadvertently included in a prior session's docs commit (56a7ef1) alongside the SUMMARY.md for plan 13. The code content is correct and complete. + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness +- Financial engine ready for player management (Plan G) to call ProcessBuyIn/ProcessRebuy on player actions +- Payout calculation ready for tournament completion (Plan I) to apply final payouts +- Season reserve tracking ready for multi-tournament views (Plan L) +- All 21 tests passing, full project builds cleanly + +--- +*Phase: 01-tournament-engine* +*Completed: 2026-03-01*