Ilia Denisov
751e74b14f
internal/game drives the engine over a single match and owns everything the
engine does not: event-sourced persistence (a games row + an append-only decoded
move journal, with the live engine.Game kept warm in a cache and rebuilt by
replay on a miss), the play/pass/exchange/resign transitions with
validate-at-submit scoring, an unlimited score/legality preview, the hint
(per-game allowance + profile wallet), the word-check tool with complaint
capture, per-player game state, history and GCG export (Poslfit dialect), and a
background turn-timeout sweeper that auto-resigns overdue turns honouring each
player's daily away window. Like Stages 1-2 it is a service/store layer with no
HTTP; the gateway surface lands in Stage 6.
Engine: additive decoded domain API (Direction, SubmitPlay/SubmitExchange/
EvaluatePlay/HintView/Hand, MoveRecord.{Dir,MainRow,MainCol}, Registry.Lookup,
ParseVariant) so internal/game never imports scrabble-solver; and a Resign fix
so the resigner keeps their score yet never wins (the other player wins a
two-player game). Timeout reuses Resign.
Persistence: migration 00002 adds games, game_players, game_moves, complaints,
account_stats and extends accounts with away_start/away_end/hint_balance; go-jet
regenerated. account gained SpendHint. Config adds BACKEND_DICT_DIR (required),
BACKEND_DICT_VERSION, BACKEND_GAME_TIMEOUT_SWEEP_INTERVAL, BACKEND_GAME_CACHE_TTL;
main loads the registry at boot (hard dependency) and starts the sweeper.
Tests: engine resign + decoded-API tests; game unit tests (GCG, away-window
boundaries, hint budget, cache, keyed mutex, payload); inttest integration
(lifecycle, replay equivalence, timeout sweep with away grace, resign stats,
hint policy, word-check/complaint, per-game-lock). Docs (PLAN, ARCHITECTURE,
FUNCTIONAL +_ru, TESTING, README) updated.
66 lines
3.3 KiB
Markdown
66 lines
3.3 KiB
Markdown
# Scrabble Game — Functional spec
|
||
|
||
Per-domain user stories: what each user-visible operation does. This is the
|
||
starting point for any change request that touches behaviour. The English
|
||
version is authoritative; [`FUNCTIONAL_ru.md`](FUNCTIONAL_ru.md) is a mirror for
|
||
the project owner — mirror every point edit in the same patch (translate only
|
||
the changed paragraphs). Sections deepen as stages land; *(Stage N)* marks where
|
||
the detail is authored.
|
||
|
||
## Domains
|
||
|
||
### Identity & sessions *(Stage 1 / 6)*
|
||
A player arrives from a platform (Telegram first), via email login, or as an
|
||
ephemeral guest. The gateway validates the credential once and mints a thin
|
||
session token; the backend resolves it to an internal `user_id`. Guests are
|
||
session-only with restricted features (auto-match only; no friends, stats or
|
||
history).
|
||
|
||
### Accounts, linking & merge *(Stage 1 / 10)*
|
||
First platform contact auto-provisions a durable account. From the profile a
|
||
player links additional platform identities or an email via a confirm flow;
|
||
linking an identity that already has history merges it into the current
|
||
account (stats summed, games/friends transferred).
|
||
|
||
### Lobby & matchmaking *(Stage 4)*
|
||
Bottom tab menu: **my games**, **profile**. Auto-match (always 2 players) joins
|
||
a `(variant, language)` pool; after 10 s with no human, the robot substitutes.
|
||
Friend games (2–4) are formed by friend list, internal ID, or deep-link.
|
||
|
||
### Playing a game *(Stage 3)*
|
||
Place tiles, pass, exchange, or resign. A play is validated against the game's
|
||
dictionary at submit time and scored; an unlimited preview reports what a
|
||
tentative move would score and whether it is legal. The dictionary check tool is
|
||
unlimited and offers a complaint on any result. Hints are governed per game —
|
||
whether they are allowed and how many each player starts with — and draw on a
|
||
personal hint wallet once the per-game allowance is spent. The game ends when the
|
||
bag empties and a player clears their rack, after 6 consecutive scoreless turns,
|
||
by resignation, or by the per-game move timeout (5 minutes to 24 hours, default
|
||
24 hours): a missed turn auto-resigns, except while the player is inside their
|
||
daily away window. A resignation or timeout gives the win to the other player and
|
||
the leaver keeps their score (two-player games; multi-player drop-out-and-continue
|
||
arrives with the lobby in Stage 4).
|
||
|
||
### Robot opponent *(Stage 5)*
|
||
Indistinguishable-from-human substitute in auto-match. Decides once whether to
|
||
play to win (~40%), targets a small score margin, plays with human-like timing
|
||
and a night sleep window, and nudges/answers nudges like a person.
|
||
|
||
### Social: friends, block, chat, nudge *(Stage 4)*
|
||
Add friends; block chat and/or friend requests independently; per-game chat;
|
||
nudge the awaited opponent at most once per hour (platform-native push).
|
||
|
||
### Profile & settings *(Stage 4)*
|
||
Language (en/ru), display name, linked accounts, email binding, timezone, block
|
||
toggles.
|
||
|
||
### History & statistics *(Stage 3)*
|
||
Finished games are archived in a dictionary-independent form and exportable to
|
||
GCG. Statistics (durable accounts only): wins, losses, draws, max points in a
|
||
game, and max points for a single move (the best play, which already includes
|
||
every word it formed plus the all-tiles bonus).
|
||
|
||
### Administration *(Stage 9)*
|
||
Admin (Basic Auth at the gateway) reviews word complaints, manages dictionary
|
||
versions, and inspects users/games.
|