mikkel/felt
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(01-06): complete Financial Engine plan

Browse source 
- SUMMARY.md with all accomplishments and decision documentation
- STATE.md updated: plan 9/14, 57% progress, 5 new decisions, session
- ROADMAP.md updated: 8/14 plans complete
- REQUIREMENTS.md: FIN-03, FIN-04, FIN-07, FIN-08, FIN-09, FIN-12, FIN-13, FIN-14 marked complete

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Mikkel Georgsen 2026-03-01 04:18:09 +01:00
parent 56a7ef1e31
commit 3b571c36dd
3 changed files with 162 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
.planning/REQUIREMENTS.md
View file

@ -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-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) - [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") - [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")
- [ ] **FIN-04**: Re-entry support (distinct from rebuy — new entry after busting) - [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-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) - [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) - [x] **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 - [x] **FIN-08**: Prize pool auto-calculation from all financial inputs
- [ ] **FIN-09**: Guaranteed pot support (house covers shortfall) - [x] **FIN-09**: Guaranteed pot support (house covers shortfall)
- [x] **FIN-10**: Payout structures (percentage, fixed, custom table) with configurable rounding - [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-11**: Chop/deal support (ICM calculator, chip-chop, even-chop, custom)
- [ ] **FIN-12**: End-of-season withholding (reserve rake portion for season prizes) - [x] **FIN-12**: End-of-season withholding (reserve rake portion for season prizes)
- [ ] **FIN-13**: Every financial action generates a receipt with full transaction log - [x] **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-14**: Transaction editing with audit trail and receipt reprint capability
### Player Management ### Player Management
@ -337,18 +337,18 @@ Which phases cover which requirements. Updated during roadmap reorganization.
| MULTI-02 | Phase 1 | Pending | | MULTI-02 | Phase 1 | Pending |
| FIN-01 | Phase 1 | Complete | | FIN-01 | Phase 1 | Complete |
| FIN-02 | Phase 1 | Complete | | FIN-02 | Phase 1 | Complete |
| FIN-03 | Phase 1 | Pending | | FIN-03 | Phase 1 | Complete |
| FIN-04 | Phase 1 | Pending | | FIN-04 | Phase 1 | Complete |
| FIN-05 | Phase 1 | Complete | | FIN-05 | Phase 1 | Complete |
| FIN-06 | Phase 1 | Complete | | FIN-06 | Phase 1 | Complete |
| FIN-07 | Phase 1 | Pending | | FIN-07 | Phase 1 | Complete |
| FIN-08 | Phase 1 | Pending | | FIN-08 | Phase 1 | Complete |
| FIN-09 | Phase 1 | Pending | | FIN-09 | Phase 1 | Complete |
| FIN-10 | Phase 1 | Complete | | FIN-10 | Phase 1 | Complete |
| FIN-11 | Phase 1 | Pending | | FIN-11 | Phase 1 | Pending |
| FIN-12 | Phase 1 | Pending | | FIN-12 | Phase 1 | Complete |
| FIN-13 | Phase 1 | Pending | | FIN-13 | Phase 1 | Complete |
| FIN-14 | Phase 1 | Pending | | FIN-14 | Phase 1 | Complete |
| PLYR-01 | Phase 1 | Complete | | PLYR-01 | Phase 1 | Complete |
| PLYR-02 | Phase 1 | Pending | | PLYR-02 | Phase 1 | Pending |
| PLYR-03 | Phase 1 | Pending | | PLYR-03 | Phase 1 | Pending |

25
.planning/STATE.md
View file

@ -8,7 +8,7 @@ progress:
total_phases: 1 total_phases: 1
completed_phases: 0 completed_phases: 0
total_plans: 14 total_plans: 14
completed_plans: 7 completed_plans: 8
--- ---
# Project State # Project State
@ -23,28 +23,28 @@ See: .planning/PROJECT.md (updated 2026-02-28)
## Current Position ## Current Position
Phase: 1 of 7 (Tournament Engine) Phase: 1 of 7 (Tournament Engine)
Plan: 8 of 14 in current phase Plan: 9 of 14 in current phase
Status: Executing Phase 1 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 ## Performance Metrics
**Velocity:** **Velocity:**
- Total plans completed: 7 - Total plans completed: 8
- Average duration: 8min - Average duration: 8min
- Total execution time: 0.97 hours - Total execution time: 1.12 hours
**By Phase:** **By Phase:**
| Phase | Plans | Total | Avg/Plan | | Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------| |-------|-------|-------|----------|
| 01-tournament-engine | 7 | 58min | 8min | | 01-tournament-engine | 8 | 67min | 8min |
**Recent Trend:** **Recent Trend:**
- Last 5 plans: 01-10 (5min), 01-04 (8min), 01-05 (10min), 01-03 (5min), 01-13 (5min) - Last 5 plans: 01-04 (8min), 01-05 (10min), 01-03 (5min), 01-13 (5min), 01-06 (9min)
- Trend: accelerating - Trend: steady
*Updated after each plan completion* *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]: 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]: Multi-tournament state is a separate store from singleton tournament state
- [01-13]: DataTable uses Record<string,unknown> with render functions (not generics) for Svelte compat - [01-13]: DataTable uses Record<string,unknown> 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 ### Pending Todos
@ -103,5 +108,5 @@ None yet.
## Session Continuity ## Session Continuity
Last session: 2026-03-01 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 Resume file: None

131
.planning/phases/01-tournament-engine/01-06-SUMMARY.md Normal file
View file

@ -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*