Mikkel Georgsen
66d7894c24
- SUMMARY.md with balance engine, break table, and API route details - STATE.md updated with position (plan 10/14), decisions, metrics - ROADMAP.md progress updated to 9/14 plans complete - REQUIREMENTS.md: SEAT-01 through SEAT-09 all marked complete Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
104 lines
4.7 KiB
Markdown
104 lines
4.7 KiB
Markdown
---
|
|
phase: 01-tournament-engine
|
|
plan: 08
|
|
subsystem: seating
|
|
tags: [table-balancing, break-table, tda-rules, auto-seating, dealer-button, hand-for-hand, chi-router]
|
|
|
|
requires:
|
|
- phase: 01-tournament-engine
|
|
provides: "table schema, tournament_players schema, audit trail, WebSocket hub, clock registry"
|
|
provides:
|
|
- "BalanceEngine with TDA-compliant suggestion generation and live-adaptive invalidation"
|
|
- "BreakTableService for fully automatic player redistribution"
|
|
- "Full REST API for tables, seating, balancing, blueprints, dealer button, hand-for-hand"
|
|
- "TableService.DB() accessor for cross-service database access"
|
|
affects: [02-multi-device, frontend-tournament-view]
|
|
|
|
tech-stack:
|
|
added: []
|
|
patterns: [live-adaptive-suggestions, stale-detection-on-accept, clockwise-distance-fairness]
|
|
|
|
key-files:
|
|
created:
|
|
- internal/seating/balance.go
|
|
- internal/seating/breaktable.go
|
|
- internal/seating/balance_test.go
|
|
- internal/seating/breaktable_test.go
|
|
- internal/server/routes/tables.go
|
|
modified:
|
|
- internal/seating/table.go
|
|
|
|
key-decisions:
|
|
- "Balance suggestions use clockwise distance from dealer button for move fairness (player closest after button moves first)"
|
|
- "Stale suggestion re-validation requires fromCount - toCount >= 2 before accepting (ensures move still needed)"
|
|
- "Break table is fully automatic (applies immediately, result is informational per CONTEXT.md)"
|
|
- "Blueprint routes are venue-level (not tournament-scoped); admin role required for mutations"
|
|
|
|
patterns-established:
|
|
- "Live-adaptive pattern: suggestions are proposals that are re-validated on accept and invalidated on state change"
|
|
- "Break table distributes by iterating sorted destination tables (ascending player count) for each player"
|
|
|
|
requirements-completed: [SEAT-01, SEAT-02, SEAT-03, SEAT-04, SEAT-05, SEAT-06, SEAT-07, SEAT-08, SEAT-09]
|
|
|
|
duration: 6min
|
|
completed: 2026-03-01
|
|
---
|
|
|
|
# Phase 1 Plan 8: Table & Seating Engine Summary
|
|
|
|
**TDA-compliant balance engine with live-adaptive suggestions, fully automatic break table, and complete REST API for table/seating management**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** 6 min
|
|
- **Started:** 2026-03-01T03:19:29Z
|
|
- **Completed:** 2026-03-01T03:25:01Z
|
|
- **Tasks:** 2
|
|
- **Files modified:** 6
|
|
|
|
## Accomplishments
|
|
- Balance engine detects unbalanced tables (diff > 1) and generates TDA-compliant move suggestions with button-aware fairness
|
|
- Suggestions are live and adaptive: re-validated on accept, auto-invalidated when state changes (bust, move, etc.)
|
|
- Break table fully automatically distributes players evenly and deactivates the dissolved table
|
|
- Complete REST API covering tables, seating, balancing, blueprints, dealer button, and hand-for-hand
|
|
- 15 tests covering balance detection, suggestion lifecycle, stale detection, auto-seat, break table distribution, and dealer button advancement
|
|
|
|
## Task Commits
|
|
|
|
Each task was committed atomically:
|
|
|
|
1. **Task H1: Table management, auto-seating, blueprints, hand-for-hand** - `e947ab1` (feat)
|
|
2. **Task H2: Balance engine, break table, API routes, tests** - `2d3cb0a` (feat)
|
|
|
|
## Files Created/Modified
|
|
- `internal/seating/balance.go` - BalanceEngine with CheckBalance, SuggestMoves, AcceptSuggestion, CancelSuggestion, InvalidateStaleSuggestions
|
|
- `internal/seating/breaktable.go` - BreakTableService with BreakTable (fully automatic redistribution)
|
|
- `internal/seating/table.go` - Added DB() accessor method for cross-service use
|
|
- `internal/seating/balance_test.go` - 10 tests: balance detection, suggestions, stale detection, auto-seat, dealer button
|
|
- `internal/seating/breaktable_test.go` - 5 tests: even distribution, odd count, deactivation, error cases
|
|
- `internal/server/routes/tables.go` - Full REST API handler with 22 endpoints
|
|
|
|
## Decisions Made
|
|
- Balance suggestions use clockwise distance from dealer button for fairness: player closest after button (small blind position) is moved first, as they are least disadvantaged by a move
|
|
- Stale suggestion re-validation requires source table to have at least 2 more players than destination (the threshold that makes a move necessary)
|
|
- Break table is fully automatic per CONTEXT.md -- moves are applied immediately and result is informational for TD display
|
|
- Blueprint CRUD routes are venue-level (not tournament-scoped) with admin role for mutations, read for any authenticated user
|
|
|
|
## Deviations from Plan
|
|
|
|
None - plan executed exactly as written.
|
|
|
|
## Issues Encountered
|
|
None
|
|
|
|
## User Setup Required
|
|
None - no external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
- Table and seating engine is feature-complete for Phase 1
|
|
- Frontend can integrate table views, balance alerts, and break table UI
|
|
- Balance suggestions ready for real-time WebSocket push to connected clients
|
|
|
|
---
|
|
*Phase: 01-tournament-engine*
|
|
*Completed: 2026-03-01*
|