This commit is contained in:
202
docs/ISSUE-312-LOBBY-FUPOGFAKTA-EXTRACTION-MAP.md
Normal file
202
docs/ISSUE-312-LOBBY-FUPOGFAKTA-EXTRACTION-MAP.md
Normal file
@@ -0,0 +1,202 @@
|
|||||||
|
# Issue #312 — FupOgFakta extraction map for logic currently living in `lobby/`
|
||||||
|
|
||||||
|
Parent: #311
|
||||||
|
Issue: #312
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
This artifact documents the concrete FupOgFakta-specific logic that still lives in `lobby/`, separates it from true platform/session concerns, and names the intended destination ownership before any larger code move happens.
|
||||||
|
|
||||||
|
It is intentionally an inventory + extraction plan only. It does **not** perform the full move.
|
||||||
|
|
||||||
|
## Architectural boundary this map is enforcing
|
||||||
|
|
||||||
|
The target boundary is already described in:
|
||||||
|
|
||||||
|
- `docs/plans/2026-03-09-fupogfakta-game-engine-design.md`
|
||||||
|
- `docs/plans/2026-03-09-fupogfakta-implementation-plan.md`
|
||||||
|
- `docs/ARCHITECTURE.md`
|
||||||
|
|
||||||
|
Those docs consistently describe:
|
||||||
|
|
||||||
|
- `lobby/` as the **platform layer** for session lifecycle, player presence, host ownership, generic game-run orchestration, and transport-facing platform concerns.
|
||||||
|
- `fupogfakta/` as the **game cartridge** that owns question selection rules, round config semantics, lie/guess/reveal/scoreboard flow, answer mixing, scoring, and game-specific response/event payloads.
|
||||||
|
|
||||||
|
In other words:
|
||||||
|
|
||||||
|
- **Platform (`lobby/`)** should know that a session exists and that a game can be started/observed.
|
||||||
|
- **Cartridge (`fupogfakta/`)** should know what a lie is, what a guess is, how answers are mixed, when phases advance, and what payload shape those game phases expose.
|
||||||
|
|
||||||
|
## Summary split
|
||||||
|
|
||||||
|
### Generic platform/session concerns that belong in `lobby/`
|
||||||
|
|
||||||
|
These are not FupOgFakta-specific and should remain platform-owned:
|
||||||
|
|
||||||
|
- Session code parsing/generation:
|
||||||
|
- `lobby/views.py::_generate_session_code`
|
||||||
|
- `lobby/views.py::_normalize_session_code`
|
||||||
|
- `lobby/views.py::_create_unique_session_code`
|
||||||
|
- Generic request parsing:
|
||||||
|
- `lobby/views.py::_json_body`
|
||||||
|
- Session lifecycle and player presence endpoints:
|
||||||
|
- `lobby/views.py::create_session`
|
||||||
|
- `lobby/views.py::join_session`
|
||||||
|
- `lobby/views.py::session_detail` **only for the generic session/player shell part**
|
||||||
|
- Generic ownership / host authorization checks
|
||||||
|
- Generic session detail payload fields:
|
||||||
|
- `session.code`
|
||||||
|
- `session.status`
|
||||||
|
- `session.host_id`
|
||||||
|
- `session.current_round`
|
||||||
|
- `session.players_count`
|
||||||
|
- `players[].id|nickname|score|is_connected`
|
||||||
|
- Generic i18n/error transport helper usage:
|
||||||
|
- `lobby/i18n.py`
|
||||||
|
- `api_error(...)`
|
||||||
|
- Route mounting / namespace ownership in `lobby/urls.py` for platform routes only
|
||||||
|
|
||||||
|
### FupOgFakta-specific logic currently misplaced in `lobby/`
|
||||||
|
|
||||||
|
These items are game-cartridge logic and should move behind `fupogfakta/` ownership:
|
||||||
|
|
||||||
|
- Round question selection by category and previously-used questions
|
||||||
|
- Lie-phase payload construction and lie timer semantics
|
||||||
|
- Mixed-answer preparation for bluff gameplay
|
||||||
|
- Guess correctness / fooled-player detection
|
||||||
|
- Bluff/correct-answer score resolution
|
||||||
|
- Reveal payload construction
|
||||||
|
- Reveal → scoreboard promotion rules
|
||||||
|
- Start round / mix answers / submit lie / submit guess / calculate scores / reveal scoreboard / next round / finish game gameplay endpoints
|
||||||
|
- Phase view-model booleans that encode FupOgFakta rules rather than generic platform readiness
|
||||||
|
|
||||||
|
## Extraction map
|
||||||
|
|
||||||
|
| Source file | Current function / concern | Why it is FupOgFakta-specific | Intended destination / owner |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| `lobby/views.py` | `_build_player_ref(player)` | Helper is only used to shape FupOgFakta reveal payloads; not a generic platform concern today. | `fupogfakta/serializers.py` or `fupogfakta/payloads.py` owned by cartridge. |
|
||||||
|
| `lobby/views.py` | `_build_reveal_payload(round_question)` | Encodes FupOgFakta reveal contract: lies, guesses, fooled-player refs, correct answer, prompt. | `fupogfakta/payloads.py::build_reveal_payload` or equivalent cartridge response builder. |
|
||||||
|
| `lobby/views.py` | `_build_leaderboard(session)` | Current implementation is generic-ish, but used exclusively by FupOgFakta scoreboard/finish flow and coupled to that response shape. | Short term: keep shared helper if multiple games will consume same contract; otherwise move to `fupogfakta/payloads.py` until a true shared scoreboard contract exists. |
|
||||||
|
| `lobby/views.py` | `_get_current_round_question(session)` | Depends on FupOgFakta `RoundQuestion` model and current-round semantics. | `fupogfakta/services/rounds.py` or `fupogfakta/queries.py`. |
|
||||||
|
| `lobby/views.py` | `_select_round_question(session, round_config)` | Implements FupOgFakta question selection rules by category, active questions, and not-yet-used question set. | `fupogfakta/services/rounds.py::select_round_question`. |
|
||||||
|
| `lobby/views.py` | `_build_lie_started_payload(session, round_config, round_question)` | Builds a FupOgFakta event/response contract for lie phase, including category, prompt, lie deadline, round question id. | `fupogfakta/payloads.py::build_lie_started_payload`. |
|
||||||
|
| `lobby/views.py` | `_prepare_mixed_answers(round_question)` | Bluff-answer dedupe and shuffle is core FupOgFakta gameplay logic. | `fupogfakta/services/answers.py::prepare_mixed_answers`. |
|
||||||
|
| `lobby/views.py` | `_resolve_scores(session, round_question, round_config)` | Applies FupOgFakta scoring rules for correct guesses and successful bluffs; depends on `Guess`, `LieAnswer`, `ScoreEvent`, `points_correct`, `points_bluff`. | `fupogfakta/services/scoring.py::resolve_scores`. |
|
||||||
|
| `lobby/views.py` | `_maybe_promote_reveal_to_scoreboard(session)` | Encodes FupOgFakta reveal completion semantics and scoreboard transition trigger. | `fupogfakta/services/phases.py::maybe_promote_reveal_to_scoreboard`. |
|
||||||
|
| `lobby/views.py` | `_build_phase_view_model(session, players_count, has_round_question)` | Most booleans are not platform-generic; they encode FupOgFakta phase names (`lie`, `guess`, `scoreboard`) and MVP constraints (`3-5 players`, round-question readiness, next-round/finish gating). | Split: keep platform-shell fields in `lobby/`; move game-specific readiness/action flags to `fupogfakta/payloads.py::build_phase_view_model` or cartridge driver payload builder. |
|
||||||
|
| `lobby/views.py` | `start_round(request, code)` | Starts FupOgFakta round, binds category, creates `RoundConfig`, selects `RoundQuestion`, transitions to `LIE`, broadcasts `phase.lie_started`. | `fupogfakta/views.py` or cartridge command handler behind a future `GameDriver.on_game_start` / round bootstrap service. |
|
||||||
|
| `lobby/views.py` | `show_question(request, code)` | Emits lie-phase question payload using FupOgFakta `RoundQuestion` and `RoundConfig`. | `fupogfakta/views.py` or remove entirely once canonical driver flow owns the transition. |
|
||||||
|
| `lobby/views.py` | `submit_lie(request, code, round_question_id)` | Pure FupOgFakta gameplay endpoint: lie validation, deadline semantics, auto-advance to guess phase, `phase.guess_started` payload. | `fupogfakta/views.py::submit_lie` (or cartridge intent handler). |
|
||||||
|
| `lobby/views.py` | `mix_answers(request, code, round_question_id)` | Manual FupOgFakta host action for lie→guess transition and answer mixing. | `fupogfakta/views.py` short term; long term likely deleted in favor of cartridge-driven automatic transition. |
|
||||||
|
| `lobby/views.py` | `submit_guess(request, code, round_question_id)` | Pure FupOgFakta gameplay endpoint: validates answer choice, resolves correctness/bluff source, auto-calculates scores, transitions to reveal. | `fupogfakta/views.py::submit_guess` plus `fupogfakta/services/scoring.py` and `fupogfakta/services/phases.py`. |
|
||||||
|
| `lobby/views.py` | `reveal_scoreboard(request, code)` | FupOgFakta reveal/scoreboard progression, not a generic platform capability. | `fupogfakta/views.py::reveal_scoreboard` or cartridge phase service. |
|
||||||
|
| `lobby/views.py` | `start_next_round(request, code)` | FupOgFakta next-round bootstrap: copies prior `RoundConfig`, increments round, picks next question, re-enters lie phase. | `fupogfakta/services/rounds.py::start_next_round` plus cartridge-owned endpoint/driver integration. |
|
||||||
|
| `lobby/views.py` | `finish_game(request, code)` | Current finish path is tied to FupOgFakta scoreboard semantics and winner payload. | `fupogfakta/views.py::finish_game` until a truly generic platform finish contract exists. |
|
||||||
|
| `lobby/views.py` | `calculate_scores(request, code, round_question_id)` | Explicit FupOgFakta score resolution endpoint. | `fupogfakta/services/scoring.py` and/or remove when fully absorbed by cartridge phase driver. |
|
||||||
|
| `lobby/urls.py` | Gameplay routes for rounds, lies, guesses, scoreboard, finish | These route names expose FupOgFakta-specific phase/actions from the platform namespace. | Re-home under `fupogfakta/urls.py` or leave mounted under `/lobby/sessions/...` only as a temporary façade delegating to cartridge-owned code. |
|
||||||
|
| `lobby/tests.py` | `StartRoundTests`, `LieSubmissionTests`, `MixAnswersTests`, `GuessSubmissionTests`, `CanonicalRoundFlowTests`, `ScoreCalculationTests`, `RevealRoundFlowTests`, `SessionDetailRoundQuestionTests`, `SessionDetailPhaseViewModelTests`, `SmokeStagingCommandTests` | These test classes verify FupOgFakta game flow rather than platform mechanics. | Move/split into `fupogfakta/tests/` with only session creation/join/platform transport tests left in `lobby/tests.py`. |
|
||||||
|
| `lobby/management/commands/smoke_staging.py` | End-to-end gameplay smoke through lies/guesses/finish | Script executes one concrete game flow and should be cartridge-aware, not platform-owned. | `fupogfakta/management/commands/` or a shared smoke harness that delegates into cartridge-specific scenario runners. |
|
||||||
|
|
||||||
|
## Recommended ownership split by module
|
||||||
|
|
||||||
|
### Keep in `lobby/`
|
||||||
|
|
||||||
|
- Session creation/join and session-code lifecycle
|
||||||
|
- Generic player membership/presence reads
|
||||||
|
- Generic auth/host checks helpers (if extracted from views)
|
||||||
|
- Generic API error/i18n plumbing
|
||||||
|
- Future `GameRun` / driver orchestration, timers, and cartridge dispatch
|
||||||
|
- A slim generic `session_detail` envelope that can embed cartridge payloads under a dedicated game key
|
||||||
|
|
||||||
|
### Move to `fupogfakta/`
|
||||||
|
|
||||||
|
- Round state queries
|
||||||
|
- Question selection
|
||||||
|
- Lie/guess/reveal/scoreboard/finish transition rules
|
||||||
|
- Score calculation
|
||||||
|
- Answer mixing
|
||||||
|
- Gameplay payload/response builders
|
||||||
|
- Gameplay endpoints and tests
|
||||||
|
- Gameplay smoke command
|
||||||
|
|
||||||
|
## Explicit boundary for `session_detail`
|
||||||
|
|
||||||
|
`session_detail` is currently mixed.
|
||||||
|
|
||||||
|
### Generic part that should remain platform-owned
|
||||||
|
|
||||||
|
- Session identity/status metadata
|
||||||
|
- Player list / presence list
|
||||||
|
- Generic host/player capability envelope if it is game-agnostic
|
||||||
|
|
||||||
|
### FupOgFakta part that should move or be delegated
|
||||||
|
|
||||||
|
- `round_question` payload
|
||||||
|
- `reveal` payload
|
||||||
|
- `scoreboard` payload
|
||||||
|
- `phase_view_model` fields keyed to `lie`, `guess`, `scoreboard`, `finished`, `question_ready`, and 3–5-player MVP rules
|
||||||
|
|
||||||
|
A clean future shape would be:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"session": {"code": "ABC123", "status": "active", "game_type": "fupogfakta"},
|
||||||
|
"players": [...],
|
||||||
|
"game": {
|
||||||
|
"phase": "lie",
|
||||||
|
"payload": {"round_question": {...}, "reveal": null, "scoreboard": null}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
That makes `lobby/` the shell and `fupogfakta/` the authority for game-state payloads.
|
||||||
|
|
||||||
|
## Concrete extraction sequence
|
||||||
|
|
||||||
|
1. **Move pure helpers first**
|
||||||
|
- `_get_current_round_question`
|
||||||
|
- `_select_round_question`
|
||||||
|
- `_prepare_mixed_answers`
|
||||||
|
- `_resolve_scores`
|
||||||
|
- `_build_lie_started_payload`
|
||||||
|
- `_build_reveal_payload`
|
||||||
|
2. **Move gameplay endpoints behind cartridge-owned service functions**
|
||||||
|
- `submit_lie`
|
||||||
|
- `submit_guess`
|
||||||
|
- `start_round`
|
||||||
|
- `start_next_round`
|
||||||
|
- `finish_game`
|
||||||
|
- `reveal_scoreboard`
|
||||||
|
- `calculate_scores`
|
||||||
|
3. **Slim `session_detail` into platform envelope + delegated cartridge payload**
|
||||||
|
4. **Move gameplay tests out of `lobby/tests.py`**
|
||||||
|
5. **Optionally leave compatibility routes in `lobby/urls.py` as a façade** until clients are rewired
|
||||||
|
|
||||||
|
## Risks this map is explicitly preventing
|
||||||
|
|
||||||
|
- Moving only models but leaving hidden phase-transition rules in `lobby/views.py`
|
||||||
|
- Treating `session_detail` as platform-generic while it still leaks cartridge payload semantics
|
||||||
|
- Leaving scoreboard/reveal transition logic behind as an undocumented coupling
|
||||||
|
- Splitting tests incorrectly so regressions stay "green" in `lobby/` while FupOgFakta behavior silently drifts
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
For #311 / #312, the repository should treat the following as **game-specific and extraction candidates**:
|
||||||
|
|
||||||
|
- round-question selection
|
||||||
|
- lie/guess/reveal/scoreboard/finish transitions
|
||||||
|
- answer mixing
|
||||||
|
- score resolution
|
||||||
|
- reveal/scoreboard payload builders
|
||||||
|
- FupOgFakta-specific session-detail subpayloads
|
||||||
|
- gameplay flow tests and smoke command
|
||||||
|
|
||||||
|
And it should treat the following as **platform-generic**:
|
||||||
|
|
||||||
|
- session identity/lifecycle
|
||||||
|
- player presence/membership
|
||||||
|
- host authorization shell
|
||||||
|
- generic error transport
|
||||||
|
- future game-driver dispatch/orchestration
|
||||||
|
|
||||||
|
That is the explicit `lobby` vs `fupogfakta` boundary this issue needs before code extraction proceeds.
|
||||||
Reference in New Issue
Block a user