Ilia Denisov
4999478ded
CI / changes (pull_request) Successful in 3s
CI / unit (pull_request) Successful in 9s
CI / integration (pull_request) Successful in 11s
CI / ui (pull_request) Successful in 35s
CI / gate (pull_request) Successful in 0s
CI / deploy (pull_request) Successful in 2m16s
A player can remove a finished game from their own 'my games' list. The action is per-account, finished-only and irreversible (the game stays for the other players; there is no un-hide). - backend: migration 00012 game_hidden(account_id, game_id); store HideGame + hiddenGameIDs + ListGamesForAccount filtering; service HideGame (seat + finished checks, reusing ErrNotAPlayer / ErrGameActive); POST /api/v1/user/games/:id/hide. - gateway: game.hide edge op (reuses GameActionRequest -> Ack) + backendclient.HideGame. - ui: finished rows reveal a delete via swipe-left (touch) or a kebab tap (desktop), active rows get an inert chevron for icon alignment; optimistic removal + lobby-cache sync; mock + transport + client wiring; lobby.hideGame label (en/ru). - tests: integration (active->ErrGameActive, outsider->ErrNotAPlayer, per-account, idempotent), gateway transcode round-trip, mock e2e (kebab -> delete); hardened a pre-existing chat-screen .back transition flake surfaced by the new test's timing. - docs: ARCHITECTURE persistence list, FUNCTIONAL (+ _ru) lobby story, PLAN tracker.
163 lines
12 KiB
Markdown
163 lines
12 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
|
||
|
||
### Client app *(Stage 7 / 8)*
|
||
The web/app client (Svelte + Vite) realizes these stories. The **playable slice**
|
||
(Stage 7) covers signing in (guest or email), the "my games" lobby, starting an
|
||
auto-match, playing the board (place tiles by drag or tap, pass, exchange, resign),
|
||
the top-1 hint, the unlimited word-check with complaint, per-game chat and nudge,
|
||
real-time in-app updates, switching interface language (en/ru) and theme, and a
|
||
read-only profile. **Stage 8** adds managing friends (including one-time friend
|
||
codes) and blocks, friend-game invitations, editing the profile and binding an
|
||
email, the statistics screen, and the in-game history viewer with GCG export.
|
||
Settings also pick the board's bonus-label style (beginner / classic / none). A hint **lays the suggested tiles on the board** for the player to confirm and
|
||
costs nothing when the rack has no legal move. The word-check accepts only the
|
||
variant's alphabet, remembers answers within the session and rate-limits repeats.
|
||
A public **landing page** at the site root introduces the game, switches language and
|
||
theme, and links to the matching per-language Telegram channel; the game itself runs at
|
||
`/app/` (web) and `/telegram/` (the Telegram Mini App). The landing's theme is ephemeral
|
||
(it follows the system scheme, not the saved preference); its language choice is saved.
|
||
|
||
### Identity & sessions *(Stage 1 / 6 / 9 / 15)*
|
||
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`. A **Telegram Mini
|
||
App** launch authenticates from the platform's signed `initData`, themes the UI to
|
||
the Telegram colours, and — on first contact — seeds the new account's interface
|
||
language from the Telegram client. The sign-in service also declares the **game
|
||
languages** it offers (a set of en/ru, at least one), which gate the New Game variant
|
||
choice in the lobby. Telegram runs a separate bot per language (an English bot and a
|
||
Russian bot, the same player spanning both); the bot a player signed in through both
|
||
sets their offered languages and is the bot their out-of-app notifications come from. Guests are session-only with restricted features
|
||
(auto-match only; no friends, stats or history); an abandoned guest that never
|
||
joined a game and has been idle past the retention window is garbage-collected. While the app is open the client
|
||
keeps a live stream and receives in-app updates in real time — the opponent's move,
|
||
your turn, chat, nudges and a found match. When the app is **closed**, the chosen
|
||
out-of-app events (your turn, nudge, a found match, an invitation or friend request)
|
||
arrive as a **Telegram notification** instead — unless the player keeps notifications
|
||
in the app only (a profile setting, **on by default**).
|
||
|
||
### Accounts, linking & merge *(Stage 1 / 11)*
|
||
First platform contact auto-provisions a durable account. From the profile a player
|
||
links an email (via a confirm code) or their Telegram (via the web sign-in); a guest
|
||
who links their first identity becomes a durable account. The "already taken" status
|
||
of an identity is never revealed before the code/sign-in is verified. If the linked
|
||
identity already belongs to another account, the player is shown an explicit,
|
||
**irreversible** confirmation and the two accounts are merged into the one they are
|
||
using (statistics summed, games and friends transferred, duplicates removed) — except
|
||
when a guest links an identity that already has a durable account, where the durable
|
||
account is kept and the guest's games move into it. A merge is blocked only while the
|
||
two accounts share a game still in progress.
|
||
|
||
### Lobby & matchmaking *(Stage 4 / 15)*
|
||
Bottom tab menu: **my games**, **profile**. The **my games** list groups games into three
|
||
sections — *your turn*, *opponent's turn* and *finished* (empty sections are hidden) — and
|
||
orders them so the games awaiting your move come first, the longest-waiting on top, while
|
||
opponent-turn and finished games are most-recent first; it renders as a compact,
|
||
line-separated list (Stage 17). You can **remove a finished game from your own list**:
|
||
swipe a finished row left (or, on desktop, tap its **⋮**) to reveal a **❌**, then tap it.
|
||
The removal is per-account and permanent — the game disappears only from your list and stays
|
||
in the other players' lists, and there is no undo. The game types offered on **New Game** are
|
||
limited to the languages the player's sign-in service supports (English → Scrabble;
|
||
Russian → Scrabble + Erudite; a bilingual service shows all three, and the web client is
|
||
unrestricted). Variants are shown by their **display name** — both Scrabble variants read
|
||
"Scrabble"/"Скрэббл" and Erudit reads "Erudite"/"Эрудит" (by the interface language), and
|
||
the same name titles the in-game screen. This gates only **starting** a new game — both auto-match and a friend
|
||
invitation — so a player still sees and plays existing games of any language. Auto-match
|
||
(always 2 players) joins a per-variant pool and is paired with the next waiting human;
|
||
after 10 s with no human the robot substitutes (the robot arrives in Stage 5). Friend games (2–4) are
|
||
formed by inviting players from the friend list (an invitation, like a friend code,
|
||
is shareable as a Telegram deep link that opens it directly): the inviter chooses the
|
||
settings and the game starts once every invitee has accepted — any decline cancels it, and an unanswered invitation
|
||
expires after seven days.
|
||
|
||
### 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. In a two-player game a resignation or timeout gives the win to
|
||
the other player and the leaver keeps their score. In a game with three or four
|
||
players the leaver's seat is dropped and the others play on, the game ending when a
|
||
single active player remains; the disposition of the leaver's tiles (returned to
|
||
the bag or removed from play) is chosen when the game is created, and the leaver's
|
||
rack is never shown to the others. A player's **board composition is kept per game**:
|
||
the rack arrangement and the tiles laid but not yet submitted are saved as they compose
|
||
and restored on return (including on another device); a player may **arrange tiles during
|
||
the opponent's turn**, but that draft is position-only — the score preview and submission
|
||
stay available only on the player's own turn.
|
||
|
||
### Robot opponent *(Stage 5)*
|
||
When auto-match finds no human within ten seconds, a robot opponent takes the empty
|
||
seat so the game starts without waiting. It is meant to feel like a person: it
|
||
decides once per game whether to play to win (about 40% of the time, so the human
|
||
wins most games), aims for a close score rather than crushing or throwing the game,
|
||
and plays at a human pace — short thinking times for most moves, the occasional long
|
||
one, and a night-time pause that tracks the player's own day. It answers a nudge
|
||
within a few minutes and nudges back when the player has been away a long time. It
|
||
carries a human-like, language-appropriate name (a Russian game draws mostly Russian
|
||
names); it does not chat, and **silently ignores friend requests** — a request to a
|
||
robot stays pending and expires, exactly like a human who never responds.
|
||
|
||
### Social: friends, block, chat, nudge *(Stage 4 / 8)*
|
||
Become friends in two ways: redeem a **one-time code** the other player issues (six
|
||
digits, valid for twelve hours), or send a **request to someone you have played
|
||
with** — they accept, ignore it (a request lapses after thirty days and can then be
|
||
re-sent), or decline (a decline blocks further requests from you until they hand you
|
||
a code). Cancelling your own pending request withdraws it; unfriending removes the
|
||
friendship. In a game, an **add to friends** item for each opponent mirrors the live
|
||
relationship: it reads *request sent* (disabled) while a request is pending or was
|
||
declined, and *in friends* once accepted — updating in place the moment the opponent
|
||
answers, and staying correct across reloads (Stage 17). Block globally — switch off incoming chat
|
||
and/or friend requests — and block individual players (a per-user block hides that
|
||
person's chat and stops requests and game invitations both ways; it also ends any
|
||
existing friendship). Per-game chat is for quick reactions: messages are short
|
||
(up to 60 characters) and may not contain links, email addresses or phone numbers,
|
||
even disguised. Nudge the player whose turn is awaited at most once per hour (the
|
||
nudge is part of the game chat); the out-of-app push is delivered via the platform.
|
||
Chat and the word-check tool open as their **own screens** (with a back to the game), and a
|
||
new chat message raises an **unread badge** on the game's menu until the chat is opened.
|
||
|
||
### Profile & settings *(Stage 4 / 8)*
|
||
Edit the display name (letters joined by a single space / "." / "_" separator, with an
|
||
optional trailing ".", up to 32 characters), the timezone (chosen as a UTC offset), the
|
||
daily away window (on a 10-minute grid, at most 12 hours, wrapping midnight) and the
|
||
block toggles. The profile form is edited inline (no separate edit mode). Linking
|
||
an email or Telegram and merging accounts are covered under "Accounts, linking &
|
||
merge" (Stage 11).
|
||
|
||
### History & statistics *(Stage 3 / 8)*
|
||
Finished games are archived in a dictionary-independent form and exportable to
|
||
GCG; the export is offered **only once a game is finished** (exporting a live game
|
||
would leak the move journal), and the client shares the `.gcg` file where the
|
||
platform supports it, otherwise downloads it. 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 10)*
|
||
Operators reach a server-rendered admin console at `${DOMAIN}/_gm` — the backend
|
||
renders it; the gateway gates it with HTTP Basic Auth on its public listener and
|
||
proxies it verbatim. The console lists and inspects **users** (profile, statistics,
|
||
identities, their games) and **games** (summary + seats), works the **word-complaint
|
||
review queue** — resolving each as reject / accept-add / accept-remove — and exposes
|
||
the **dictionary**: the resident versions per variant, a **hot-reload** of a new
|
||
version from `BACKEND_DICT_DIR/<version>/`, and the **pending wordlist changes**
|
||
derived from accepted complaints (which feed the offline rebuild and are marked
|
||
applied after a reload). When a Telegram connector is configured an operator can also
|
||
**message a user** (by their Telegram identity) or **post to the game channel**.
|
||
State-changing actions are protected by a same-origin check; the console tracks no
|
||
operator identity.
|