# 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.