Ilia Denisov
3bceafbc12
CI / changes (pull_request) Successful in 2s
CI / unit (pull_request) Successful in 9s
CI / integration (pull_request) Successful in 13s
CI / ui (pull_request) Has been skipped
CI / gate (pull_request) Successful in 0s
CI / deploy (pull_request) Successful in 1m9s
The robot followed its per-game playToWin/lose intent on every move, which made the outcome too predictable. It now flips that intent for a single move on ~20% of opening/midgame turns (a winning robot eases off, a losing one surges ahead), so the chosen strategy may not pan out — which favours the human. The chance tapers linearly to 0 over the last 14 tiles in the bag and is 0 once the bag is empty, so the endgame follows the chosen strategy strictly. The decision is deterministic from the seed (mix(seed,"deviate",moveCount)) and applies to both robot paths via the shared selectMove; the per-game play-to-win intent the admin card shows is unchanged. Adds deviateProb/deviates helpers and unit tests (taper bounds + monotonicity, never-in-endgame, determinism, ~20% distribution); bakes the behaviour into ARCHITECTURE §7, FUNCTIONAL (+_ru), backend/README, PRERELEASE and PLAN Stage 5.
1581 lines
128 KiB
Markdown
1581 lines
128 KiB
Markdown
# Scrabble Game — implementation plan
|
||
|
||
Living plan and **stage tracker**. Each stage is implemented in its own session;
|
||
the rules for starting and finishing a stage are in [`CLAUDE.md`](CLAUDE.md).
|
||
The architecture/decision record is [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md);
|
||
behaviour is [`docs/FUNCTIONAL.md`](docs/FUNCTIONAL.md). When a stage produces a
|
||
decision, bake it back here **and** into the affected docs/code in the same PR.
|
||
|
||
## Context
|
||
|
||
Greenfield multiplatform Scrabble. Players arrive from a platform (Telegram
|
||
first; later VK/MAX/iOS/Android) or standalone web (email / guest). Three
|
||
executables — `gateway`, `backend`, `ui` — plus per-platform side-services.
|
||
Deliberately simpler than the sibling `../galaxy-game` (idea donor, not a
|
||
template). The `../scrabble-solver` engine is embedded in-process as a library.
|
||
|
||
## Locked decisions (recap — full record in docs/ARCHITECTURE.md)
|
||
|
||
Stack: `go.work` monorepo, modules `scrabble/<name>`, Go 1.26.x, backend
|
||
gin+pgx+Postgres(schema `backend`)+goose+zap+OTel (deps added when first used).
|
||
Wire: Connect-RPC + FlatBuffers (client↔gateway), REST/JSON + `X-User-ID`
|
||
(gateway↔backend), gRPC server-stream for live events. Auth: platform-native,
|
||
thin opaque session token, no Ed25519/signing, likely no Redis. UI: pure
|
||
HTML5/CSS, plain Svelte + Vite, Capacitor for native. MVP surfaces: Telegram +
|
||
web (email + ephemeral guest) + link/merge. Variants: ru/en/Эрудит.
|
||
Legality: validate-at-submit. End: empty bag+rack / 6 scoreless / 24h timeout.
|
||
Hint: top-1. Word-check: unlimited + complaint. Robot: P(win)≈0.40, margin
|
||
targeting, [2,90]min skewed timing, sleep 00:00–07:00 opp-tz, nudge logic.
|
||
Dictionary: pin per game. History: structured + GCG export, dictionary-
|
||
independent (see ARCHITECTURE §9.1).
|
||
|
||
## Stage tracker
|
||
|
||
| # | Stage | Status |
|
||
|---|-------|--------|
|
||
| 0 | Scaffolding (go.work, backend skeleton, docs, CI) | **done** |
|
||
| 1 | Backend foundation (config, server, Postgres+goose, sessions, accounts) | **done** |
|
||
| 2 | Engine package over scrabble-solver | **done** |
|
||
| 3 | Game domain (lifecycle, rules, hint, word-check, history+GCG, stats) | **done** |
|
||
| 4 | Lobby & social (matchmaking, friends, block, chat, profile, nudge) | **done** |
|
||
| 5 | Robot opponent | **done** |
|
||
| 6 | Gateway edge (Connect/FB, platform auth, sessions, push bridge, admin) | **done** |
|
||
| 7 | UI — playable slice + UX polish (Svelte+Vite, board, lobby, chat, hint/word-check, i18n) | **done** |
|
||
| 8 | UI — social/account/history (friends, blocks, invitations, profile edit, stats, history/GCG) | **done** |
|
||
| 9 | Telegram integration (bot side-service, deep-link, push) | **done** |
|
||
| 10 | Admin & dictionary ops (complaint review, version reload) | **done** |
|
||
| 11 | Account linking & merge | **done** |
|
||
| 12 | Observability & performance (telemetry, metrics, guest GC) | **done** |
|
||
| 13 | Alphabet on the wire (UI alphabet-agnostic) | **done** |
|
||
| 14 | Solver & dictionary split (publish solver + scrabble-dictionary repo/artifact) | **done** |
|
||
| 15 | Dual Telegram bots & language-gated variants | **done** |
|
||
| 16 | Deploy infra & test contour (Dockerfiles, gateway static UI, compose, observability) | **done** |
|
||
| 17 | Test-contour verification & defect fixes | **done** |
|
||
| 18 | Prod contour deploy (SSH export/import, manual after merge) | todo |
|
||
| 19 | User feedback (in-app submit + attachment, admin review/reply, account roles) | **done** |
|
||
|
||
Scaffolding is incremental: `go.work` lists only existing modules; each stage
|
||
adds the modules it needs.
|
||
|
||
## Stages
|
||
|
||
Each stage: read this plan + relevant docs, **interview the owner on the open
|
||
details below**, implement within scope, then update plan/docs/code and get CI
|
||
green before marking done.
|
||
|
||
### Stage 0 — Scaffolding *(done)*
|
||
Scope: `go.work` (Go 1.26.3, `use ./backend`); minimal runnable `backend`
|
||
(gin, zap, `/healthz`, `/readyz`, env config); docs skeleton; `PLAN.md`;
|
||
`CLAUDE.md`; `.gitea/workflows/go-unit.yaml`; README; `.gitignore`.
|
||
Acceptance: `go build ./backend/...` + `go vet` + gofmt clean +
|
||
`go test ./backend/...` green; CI green on push.
|
||
|
||
### Stage 1 — Backend foundation
|
||
Scope: config/server route groups (`/api/v1/{public,user,internal,admin}`,
|
||
probes), Postgres (pgx) + embedded goose migrations + schema `backend`,
|
||
telemetry (OTel) wiring, in-memory cache scaffolding, thin sessions + accounts +
|
||
platform identities.
|
||
Open details: Postgres version + DSN/`search_path` convention; jet vs
|
||
sqlc/sqlx (default jet); migration naming; exact session-token shape (opaque
|
||
random length, TTL, revocation); account/identity table shape; whether the
|
||
admin bootstrap lands here or in Stage 10.
|
||
|
||
### Stage 2 — Engine package
|
||
Scope: `backend/internal/engine` over scrabble-solver — versioned DAWG
|
||
load/registry, GenerateMoves/ValidatePlay/ScorePlay wrappers, bag/rack, the
|
||
**dictionary-independent** game-state model + decode helpers. Add
|
||
`replace scrabble-solver => ../scrabble-solver` to `go.work` here and solve the
|
||
CI sibling-checkout (clone `gitea.iliadenisov.ru/.../scrabble-solver`).
|
||
Open details: how CI obtains the solver (clone sibling vs publish/tag the
|
||
solver module); in-memory game-state representation; how blanks and exchanges
|
||
are modelled; Эрудит specifics to verify against the solver.
|
||
|
||
### Stage 3 — Game domain
|
||
Scope: create/join, turn order, submit play/pass/exchange/resign,
|
||
validate-at-submit, scoring, end-conditions, 24h timeout/auto-resign, hint,
|
||
word-check + complaint capture, structured history + GCG writer, stats on
|
||
finish.
|
||
Open details: GCG dialect details (blanks, exchanges, notation); exact stats
|
||
edge cases; turn-timeout scheduler mechanism (cron vs per-game timer);
|
||
complaint payload shape.
|
||
|
||
### Stage 4 — Lobby & social
|
||
Scope: matchmaking pool, friends, block, per-game chat, profile + email
|
||
confirm-code, nudge.
|
||
Open details: pool fairness/keying confirmation; deep-link format per platform;
|
||
chat length limit + retention; friend-request lifecycle; email-code provider
|
||
(SMTP relay choice).
|
||
|
||
### Stage 5 — Robot opponent
|
||
Scope: human-like player — balance ~0.40, margin targeting, skewed [2,90]min
|
||
timing + sleep + nudge logic, friend/DM blocking, name pool.
|
||
Open details: exact delay distribution + parameters; margin band; name pool
|
||
source; how the scheduler drives robot moves; metrics for tuning balance.
|
||
|
||
### Stage 6 — Gateway edge
|
||
Scope: Connect/gRPC-Web (h2c), Telegram initData validation → session →
|
||
`X-User-ID`, in-memory rate-limit, admin Basic-Auth passthrough, FlatBuffers
|
||
transcoding, in-app push stream bridging backend `push` gRPC stream, email +
|
||
ephemeral-guest paths.
|
||
Open details: FlatBuffers schema layout + message_type catalog; rate-limit
|
||
classes/limits; admin surface routing; session cache shape at the gateway.
|
||
|
||
### Stage 7 — UI
|
||
Scope: plain Svelte + Vite static; Connect-web + FlatBuffers client; lobby (my
|
||
games, profile tabs); board (HTML5/CSS grid, drag-n-drop, no assets); chat;
|
||
hint/word-check; in-app stream; i18n en/ru; in-memory session (+IndexedDB if
|
||
available); Capacitor-ready structure.
|
||
Open details: detailed game-board UX (deferred by the owner to this stage);
|
||
client routing; offline/refresh behaviour; design system / theming.
|
||
|
||
#### Suggested layouts (lobby + game screen)
|
||
|
||
User note:
|
||
> Detailed interview about UI/UX is **strongly** required.
|
||
> Too much to discuss.
|
||
|
||
```text
|
||
┌────────────────────┐
|
||
│ Display_Name =│- Profile
|
||
├────────────────────┤- Settings
|
||
│ Invitations │- About
|
||
│ - list │
|
||
├────────────────────┤
|
||
│ Active games │
|
||
│ - list │
|
||
├────────────────────┤
|
||
│ Finished games │
|
||
│ - list │
|
||
│ │
|
||
│ │
|
||
│ │
|
||
│ │
|
||
│ │
|
||
│ │
|
||
│ │
|
||
├────────────────────┤
|
||
│ ┌───┐ ┌───┐ ┌───┐│
|
||
│ New │ Stats Tourn│
|
||
│ └───┘ └───┘ └───┘│
|
||
└────────────────────┘
|
||
┌────────────────────┐
|
||
Lobby│◄ ==│- History
|
||
├────────────────────┤- Chat
|
||
│You Ann Kaya Rick│- Check word
|
||
│136 700 179 39│- Drop game
|
||
├────────────────────┤
|
||
│ │
|
||
│ │
|
||
│ │
|
||
│ c │
|
||
│ words │
|
||
│ o │
|
||
│ s │
|
||
│ s │
|
||
│ │
|
||
│ │
|
||
├──┬──┬──┬──┬──┬──┬──┤ ┌──┐
|
||
│A │Q │Z │* │N │I │W │◄│ │MakeMove/Reset
|
||
├──┴──┴──┴──┴──┴──┴──┤ └──┘
|
||
│ ┌───┐ ┌───┐ ┌───┐ │
|
||
│ Draw│ Skip│ Shfl│ │
|
||
│ └───┘ └───┘ └───┘ │
|
||
└────────────────────┘
|
||
```
|
||
|
||
### Stage 8 — UI: social, account & history surfaces
|
||
Scope: the UI surfaces deferred from Stage 7's playable slice, wiring the matching
|
||
backend/gateway operations as each screen needs them (the Stage 6 vertical-slice
|
||
pattern): friends (request/accept/decline/list), per-user blocks, friend-game
|
||
invitations (create 2–4 player, accept/decline, invitations list), profile **editing**
|
||
(`account.UpdateProfile` + the email confirm-code binding UI), the statistics screen,
|
||
and the history viewer with GCG export/download.
|
||
Open details: friends/invitations UX; stats presentation; history/GCG viewer + download
|
||
mechanics; any new validation the profile-editing forms need.
|
||
|
||
### Stage 9 — Telegram integration
|
||
Scope: bot side-service, deep-link invites, platform push (your-turn / nudge),
|
||
Mini App launch/auth; backend↔platform internal API.
|
||
Open details: bot framework/library; deep-link scheme; push message templates;
|
||
internal API contract; Mini App hosting/origin.
|
||
|
||
### Stage 10 — Admin & dictionary ops
|
||
Scope: admin endpoints (users, games, complaint review queue, dictionary
|
||
versions + reload), complaint→dictionary update pipeline.
|
||
Open details: whether a server-rendered console is wanted or JSON-only; the
|
||
dictionary rebuild/deploy pipeline; complaint resolution workflow.
|
||
|
||
### Stage 11 — Account linking & merge
|
||
Scope: link-via-confirm; merge-into-A (stats sum, transfer games/friends,
|
||
dedupe). High blast-radius — focused regression tests.
|
||
Open details: conflict resolution (active games on both, duplicate friends,
|
||
display-name collisions); irreversibility/audit; confirm-flow per platform.
|
||
|
||
### Stage 12 — Observability & performance
|
||
Scope: wire a configurable **OTLP** exporter (alongside `none`/`stdout`), shared in a
|
||
new `pkg/telemetry`; add telemetry to the **gateway** and the **Telegram connector**
|
||
(providers + `otelgrpc` on the gRPC hops) for parity with the backend; add
|
||
domain/operational **metrics** close to the business (game replay/validate timings,
|
||
started/abandoned games, live-cache size, chat/nudge counts, the edge roundtrip, Go
|
||
runtime metrics); discharge **TODO-3** (abandoned-guest GC). The OTLP collector and
|
||
dashboards are stood up with the deploy (Stage 15); the default exporter stays `none`,
|
||
so CI needs no collector. Performance is operational-metric instrumentation, not
|
||
speculative optimisation (the standing "evidence first" rule — no measured hotspot yet).
|
||
Open details: exporter default and whether a collector is stood up now; the metric set
|
||
and its attributes; the guest-reaper trigger given revoke-only sessions.
|
||
|
||
### Stage 13 — Alphabet on the wire (TODO-4)
|
||
Scope: make the UI **alphabet-agnostic**. On game-screen load the client receives the
|
||
variant's alphabet table `(letter, index, value)` for **display only**, caches it in
|
||
memory by variant (a request flag gates whether the table is included, so it is not
|
||
resent on every state poll); live play then exchanges **letter indices** both ways, and
|
||
**word-check** sends indices, constraining input to the variant's alphabet. The engine
|
||
already works in alphabet-index bytes, so the wire does *less* decoding in live play; the
|
||
durable journal / history / GCG stay decoded concrete characters (the §9.1
|
||
dictionary-independent invariant is untouched). The alphabet comes from the **solver's
|
||
rules** (not the DAWG), so the wire table is pinned by the solver version. **Index-drift
|
||
caveat:** the running solver, the DAWGs (built against it — Stage 14 / TODO-2) and the
|
||
wire table must agree, or letter indexing silently corrupts. Blast radius: `pkg/fbs`
|
||
(a new Alphabet table; index fields in `StateView`/rack and in
|
||
`SubmitPlay`/`Exchange`/`check_word`) → backend DTO encode/decode → UI
|
||
`codec.ts`/`premiums.ts` → board/rack render, the move/exchange/word-check senders, the
|
||
mock transport and the Vitest tests.
|
||
Open details: the fbs shape and `include_alphabet` flag placement; whether to keep
|
||
concrete-letter fields during the transition; whether tile exchange moves fully to
|
||
indices; the premiums.ts parity-test rework.
|
||
|
||
### Stage 14 — Solver & dictionary split (TODO-1 + TODO-2)
|
||
Re-scoped from the original "CI & deploy": that was several sessions of work, so the
|
||
deploy + observability + the two-bots idea were split into **Stages 15–18** below and this
|
||
stage took only the dependency/artifact split that everything else builds on. Scope: publish
|
||
`scrabble-solver` as a versioned Gitea module and split the dictionary build into a new
|
||
`scrabble-dictionary` repo delivering a **release artifact**, then make `scrabble-game` consume
|
||
both — discharging **TODO-1** and **TODO-2**.
|
||
|
||
- **TODO-1 — solver published.** `scrabble-solver` renamed to module
|
||
`gitea.iliadenisov.ru/developer/scrabble-solver`, tagged **v1.0.0**; `wordlist`/`dictdawg`
|
||
de-internalised to public packages (the dict repo imports them); `cmd/builddict`/`dictprep`/the
|
||
`dictionaries` submodule moved out; `internal/dict` repointed at the committed `dawg/*.dawg`
|
||
fixtures. `backend/go.mod` pins `v1.0.0`; the `go.work` replace and the CI sibling-clone are
|
||
gone; `GOPRIVATE=gitea.iliadenisov.ru/*` makes go fetch it directly (no public proxy/checksum DB).
|
||
- **TODO-2 — dictionary artifacts.** New repo `developer/scrabble-dictionary` holds the word-list
|
||
sources + `cmd/builddict` and builds the three DAWGs against the **published solver + pinned
|
||
`dafsa`/`alphabet` v1.1.0**, so they are byte-identical to the solver's fixtures (no index drift).
|
||
Released as `scrabble-dawg-vX.Y.Z.tar.gz` (flat, one semver per set); the Go workflows download it
|
||
and point `BACKEND_DICT_DIR` at it. The runtime contract is unchanged (additive
|
||
`BACKEND_DICT_DIR/<version>/`, `engine.OpenWithVersions`, per-game `dict_version` pin; a version is
|
||
safe to retire once no active game pins it).
|
||
|
||
### Stage 15 — Dual Telegram bots & language-gated variants *(done)*
|
||
Re-framed at its start to be **service-agnostic**: the sign-in service returns, with the user identity, a
|
||
**set of supported game languages** (subset of `{en, ru}`, ≥ 1) that gates the New Game variant choice.
|
||
Built: the connector hosts **two bots in one container** (one per service language, each its own token +
|
||
game channel; the same Telegram user id spans both); `ValidateInitData` tries each token in turn and
|
||
returns the validating bot's **`service_language`** + **`supported_languages`** set. The set rides the
|
||
`Session` (FlatBuffers, session-scoped, not persisted) and the UI offers only the matching variants on New
|
||
Game (en → English; ru → Russian + Эрудит) — gating **only** the start of a new game (auto-match + friend
|
||
invite); existing games of any language are unrestricted and the backend does not enforce. The service
|
||
language is persisted (`accounts.service_language`, migration `00010`, written on every login —
|
||
last-login-wins) and routes the user-facing out-of-app push (`Notify`) back through the right bot (falls
|
||
back to `preferred_language`). Non-Telegram logins (web/email/guest) carry the gateway default set
|
||
(`GATEWAY_DEFAULT_SUPPORTED_LANGUAGES`, all variants). Admin broadcasts (`SendToUser`/`SendToGameChannel`)
|
||
pick the bot by an **operator-chosen** language in the console — unrelated to `ValidateInitData`.
|
||
|
||
### Stage 16 — Deploy infra & test contour *(done)*
|
||
Scope: the deploy machinery + the **test contour** (the bulk of the original Stage 14). Backend +
|
||
gateway **Dockerfiles** (multi-stage distroless, mirroring the Stage 9 connector image); the gateway
|
||
gains **static UI serving** — **embedded** via `go:embed` (a node build stage in the gateway image),
|
||
SPA served at both `/` (web) and `/telegram/` (Mini App), the §13 single-origin model; prod UI build
|
||
vars (`VITE_TELEGRAM_BOT_ID`, `VITE_TELEGRAM_LINK`, `VITE_GATEWAY_URL`) as image build-args; a root
|
||
`deploy/docker-compose.yml` (backend + gateway + Postgres + connector + VPN sidecar + the **full
|
||
observability stack** — OTel Collector + Prometheus + Tempo + Grafana with provisioned dashboards) on
|
||
the external `edge` network behind the host caddy (VPN sidecar only for the connector); the backend
|
||
image pulls the DAWG release artifact (Stage 14). **The test contour deploys automatically on push to
|
||
a feature branch** (`docker compose up -d --build` on the local host where the gitea runner lives),
|
||
with a post-deploy probe (`GET /` on the gateway). Test-contour secrets use the **`TEST_`** prefix
|
||
(see Stage 16).
|
||
Open details (re-interview at start): the dashboard set; the gateway static-serving hook (before the
|
||
h2c wrap — `/` + `/telegram/` mounts; a committed `dist` placeholder so `go build` works without a UI
|
||
build); Postgres healthcheck/volume; whether the connector-scoped compose is retired for the root one;
|
||
collector/Tempo/Prometheus retention.
|
||
|
||
### Stage 17 — Test-contour verification & defect fixes *(done)*
|
||
Scope: exercise the deployed **test contour** end-to-end and fix the defects it surfaces — the
|
||
"does it actually work in the contour" pass before prod. Bring up the `development` deploy, then
|
||
verify each piece against a real run: the gateway serves the SPA at `/` and `/telegram/`; the admin
|
||
console and Grafana sit behind the single `/_gm` Basic-Auth; the Telegram **bots** start (test
|
||
environment) and the Mini App launches/authenticates; a game can be created and played through (web
|
||
+ Mini App); the **observability** stack receives data (Prometheus targets up, the dashboards
|
||
populate incl. `accounts_created_total`/`active_users`, traces reach Tempo); the out-of-app push
|
||
works. Fix the defects found and harden where the run exposes gaps — notably a CI **connector
|
||
liveness check** (the deploy probe only hits the gateway today, so a crash-looping connector is
|
||
invisible — that is how the Stage 16 test-env miss went unnoticed) and **path-conditional CI** (skip
|
||
the jobs whose code did not change, behind a single always-running gate job so branch-protection
|
||
required checks stay satisfiable — a skipped required check otherwise blocks the merge).
|
||
Open details (interview at start): the verification checklist + pass bar; which discovered defects
|
||
are in-scope vs deferred; the changed-paths design + the aggregate gate job; the connector
|
||
liveness-check grace period (the VPN sidecar handshake lets the connector restart a few times before
|
||
it settles).
|
||
|
||
#### Found caveats (all resolved in Stage 17 — see *Refinements → Stage 17*)
|
||
|
||
The owner's collected caveats below were classified (fix-now / verify-then-fix / discuss),
|
||
discussed where they were forks, and resolved in one session with tests where practical. The
|
||
per-item outcomes are recorded under *Refinements logged during implementation → Stage 17*; the
|
||
raw list is kept here as the record of what the first contour run surfaced.
|
||
|
||
- /_gm/grafana/ требует повторного ввода пароля basic auth, хотя до этого я уже зашёл в /_gm/
|
||
Такого быть не должно: графана живёт под /_gm/ и ей не нужен свой auth.
|
||
|
||
- нужна ещё метрика "продолжительность хода" - сколько игроки тратят на каждый ход,
|
||
скорее всего, понадобится новое поле last_move_ts если ещё нет, так же нужно будет завести
|
||
метрику в графане как общую, так и и по конкретному пользователю (можно ли? дорого ли?),
|
||
а так же с привязкой к номеру хода и без номера хода. Всё это понадобится для анализа
|
||
способностей игроков, чтобы подогнать под них роботоа. А так же - выявлять читеров.
|
||
|
||
- регистрация пользователя из телеграм (как и других коннекторов):
|
||
пытаться очистить имя от посторонних символов, аналогично проверке при вводе имени в профиле.
|
||
если после очистки ничего не осталось, поставить имя Player/Игрок-XXXXX (5 рандомных цифр),
|
||
язык в зависимости от внешнего коннектора.
|
||
|
||
- game - chat - nudge. Когда мой ход и я жму nudge, появляется сообщение "сейчас не ваш ход".
|
||
Думаю, опечатка - "не" лишняя, проверь на всех языках.
|
||
|
||
- если открыли игру через telegram, надо в настройках вообще полностью скрыть переключатель темы "авто/светлая/темная",
|
||
т.к. тему задаёт сам телеграм (уточни, в какой проперти её можно забрать, и нужно ли, сейчас оно уже нормально работает
|
||
на самих стилях)
|
||
|
||
- возможно, к предыдущему пункту: запускаю мини апп на macos/telegram desktop. в самой macos у меня темная тема.
|
||
когда я включаю тему "авто" в настройках mini app, а в самом телеграме - светлую, всё ломается, nav bar и tab bar
|
||
рисуются темным фоном, список игр и меню - светлым, поле игры - тёмное, вокруг него светлоая рамка.
|
||
Провернул тот же трюк на ios - всё чётко, в режиме "авто" он полностью держит ту настройку, которая в
|
||
самом телеграме задана. Проверь, можно ли это починить для desktop-версии тг, скорее всего там
|
||
системные настройки как-то в браузер протекают. Ну если не получится понять причину, тогда и черт с ним.
|
||
|
||
- не знаю, ошибка это или by design - если у меня открыта игра сразу в desktop telegram и на ios,
|
||
то когда я делаю ход, в другом окне не обновляется ничего - ни само игровое поле, ни лобби.
|
||
интересно, как ходят уведомления через gateway - по последнему активному push-каналу, что ли?
|
||
если так, стоит ли чинить, чтобы у пользователя все пуш-каналы поддерживались или это дорого?
|
||
нужен твой анализ и совет.
|
||
|
||
- надо подкрутить тайминг автоматического хода работа. идея такая: сейчас, насколько я помню, время хода
|
||
выбирается от 2 до 90 минут с перекосом ближе к 2 минутам (поправь если что). я предлагаю этот интервал
|
||
сделать динамическим в зависимости от хода. Например, средяя партия это 25-30 ходов, предположительно.
|
||
На первом ходу интервал должен быть 1..5 минут, на последнем - 10..90 минут, всё так же с перекосом в меньшую сторону.
|
||
А то я сейчас поиграл, роботы на первых ходах по 15 минут думают.
|
||
Сможешь такую хитрую формулу составить? Цифры ориентировочные. Потом после набора реальной статистики подкрутим цифры.
|
||
Заодно напомни, как работает формула "перекоса", можно ли её "заставить" косить почаще в меньшую сторону, как бы имитируя
|
||
активного игрока. Этот пункт требует тщательного обсуждения, пожалуй.
|
||
|
||
- при навигации между лобби и игрой есть задержка едва заметная на глаз, думаю, связанная с тем, что UI все данные по игре перезапрашивает
|
||
каждый раз. Кроме этого, когда я в лобби возвращаюсь, глаз ловит перерисовку экрана, довольно быстро, но есть какое-то
|
||
неприятное ощущение, что туда что-то подгружается. А мы можем внутри UI наполнять кэш этими данными и экраны не рисовать
|
||
каждый раз, а просто подменять? не знаю, как это работает, если честно. Но вот информацию по игре, в которую пользователь
|
||
проваливался 1 раз, совершенно точно можно положить в кэш и обновлять его когда с сервера приходит новый ход и т.п.
|
||
|
||
- при запуске в telegram, надо бы цвет фона nav bar сделать фоном телеграма, а то он "выпадает" из общего дизайна.
|
||
|
||
- а вот фон рекламной строчки под nav bar наоборот, сделать бы чуть светлее (в тёмной теме) или темнее (в светлой),
|
||
чтобы был акцентирован, но не ярко. что-то там есть в стилях телеграма такое готовое?
|
||
ну и для собственного дефолтного стиля тоже надо выбрать соответствующие.
|
||
|
||
- Переключаюсь в ios в другое приложение, по возвращении ловлю "проблема соединения, повторяем".
|
||
Вроде бы в телеграм-бандле есть обработчики всяких событий, в том числе background in/out, или как там оно зовётся.
|
||
Посмотри, можно ли что-то с этим сделать? Если да, то именно в случаях когда приложение уходит в фон - не надо рисовать
|
||
плашку с ошибкой, просто молча пытаться соединиться, то есть плашка появится когда приложение на в фоне на следующем retry.
|
||
|
||
- при использовании подсказки в игре ато зум ведёт в лево-верх, а не туда, где была поставлена подсказка.
|
||
|
||
- В русских партиях нужны русские имена для роботов, но можно вперемешку с латинскими именами, только чтобы латинских имён
|
||
было не больше 20%.
|
||
|
||
- Сделать анимацию переходов между экранами: наезд справа если из лобби куда-то переходим и наоборот, уезжание вправо и открытие лобби, когда нажимаем back в навигации.
|
||
|
||
- Цвет и размер плашки с игроками над доской: давай сделаем не "кнопками" самих игроков, а просто поделим это пространство
|
||
поровну между игроками, а активного игрока будем показывать за счёт "поднятия" его плашки, за счёт теней слева и справа, чтобы
|
||
остальные игроки были как бы "утоплены" внутрь.
|
||
|
||
- В игре клик/тач по плашке с именами игроков открывает/закрывает историю.
|
||
|
||
- В истории ходов странное выравнивание колонки со словами, они буквально скачут влево-вправо.
|
||
|
||
- В многословных партиях надо в истории показывать основное слово + дополнительное (если это ещё не сделано, надо проверить)
|
||
|
||
- При открытии истории нижнюю границу таблицы ("тень") сразу прибивать к доске, а не растягивать вслед за таблицей.
|
||
|
||
- Баг. Открыл игру через ru-телеграм бота, пытаюсь сделать "new -> русский" (это скрэбл с русским алфавитом), появляется красная плашка
|
||
"что-то пошло не так". при этом "new -> эрудит" работает. Попробуй посмотреть в логах сейчас, может что-то есть. Или как-то иначе проанализируй, или давай вместе будем смотреть, если не получится.
|
||
|
||
### Stage 18 — Prod contour deploy
|
||
Scope: the **production contour** on a remote host over SSH. Deploy by **container export/import**
|
||
(`docker save` → `scp`/ssh → `docker load` → `docker compose up` on the remote), the SSH key + host IP
|
||
in Gitea secrets; **strictly manual** (`workflow_dispatch`) after `development` is merged to `master`
|
||
(the Stage 16 branch model: `feature/* → development → master`, merge gated green). Two-contour config
|
||
uses **`TEST_`/`PROD_` secret/variable prefixes** — Gitea 1.26 has no deployment environments (verified:
|
||
the `environments` API 404s), so a flat prefixed namespace is the convention.
|
||
Reuses the Stage 16 `deploy/docker-compose.yml` as-is, mapping the **`PROD_`** set onto the same
|
||
unprefixed compose vars. **No host caddy on prod**, so the contour's own caddy terminates TLS — set
|
||
`CADDY_SITE_ADDRESS` to the prod domain so caddy does its own ACME (the Caddyfile is already
|
||
parameterised for this; the test contour leaves it `:80` behind the host caddy).
|
||
Open details (re-interview): export/import vs a registry trade-off; prod domain/cert source (ACME vs a
|
||
provided cert) at the contour caddy; prod VPN; rollback.
|
||
|
||
### Stage 19 — User feedback *(done)*
|
||
A user→operator feedback channel, sequenced after the numbered stages but shipped **before** the Stage 18
|
||
prod deploy. Scope: a **Feedback** screen under Settings → Info where a registered player sends a message
|
||
(≤1024 runes) with an optional single attachment; the operator reviews and replies in the server-rendered
|
||
**admin console**; the reply is delivered back in-app with a Settings/Info badge. Introduces the project's
|
||
**first per-account role** (`account_roles`), the reusable replacement for per-feature flags: the
|
||
`feedback_banned` role blocks **only** feedback submission (not the whole account, unlike a suspension),
|
||
granted from the feedback section's delete-with-block and granted/revoked from `/users`.
|
||
|
||
- **Data:** migration `00004_feedback` — `feedback_messages` (body, attachment `bytea`, sender_ip, channel,
|
||
read/archived/reply/reply-read timestamps) + `account_roles` (account_id, role). New backend domain
|
||
`internal/feedback` (store + service), modelled on `internal/social` + the admin chat-moderation surface.
|
||
- **Anti-spam gate:** a player with an unreviewed message cannot send another ("Ожидаем рассмотрения вашего
|
||
последнего обращения"); enforced server-side. This *is* the rate limit — no separate one.
|
||
- **Reply lifecycle:** the reply lives on the message row; shown on the feedback screen ("Ответ на ваше
|
||
последнее сообщение") for the player's latest replied message; it becomes read the moment the screen
|
||
fetches it (delivery = read) and is hidden one week after. The badge (lobby ⚙️, combined with friend
|
||
requests; Settings → Info "1") rides the existing `NotificationEvent` with a new `admin_reply` sub-kind —
|
||
no wire-schema change for the push.
|
||
- **Wire:** new FlatBuffers `feedback.submit` / `feedback.get` / `feedback.unread`; `feedback.submit` is
|
||
**guest-gated at the gateway** via a new `Op.NonGuest` flag (the session resolve now carries `is_guest`),
|
||
so a guest's submission never reaches the backend; the backend rejects guests too.
|
||
- **Security:** body + attachment limits enforced server-side (the UI limits are UX only); attachments
|
||
served with `X-Content-Type-Options: nosniff`, images inline-previewed via `<img>` (which never
|
||
executes), everything else download-only; the UI gates the attachment by extension (allowed types not
|
||
listed) and the backend mirrors the allow-list + size as the trust boundary; the console renders user
|
||
content as auto-escaped text (`html/template`).
|
||
Open details settled at planning: attachment ≤1,000,000 B (keeps the 1 MiB edge cap); allowed types
|
||
(images + pdf/txt/log/doc/docx/rtf/zip/gz/7z); channel from the client (telegram/ios/android/web); guests
|
||
cannot submit; three-way admin filter.
|
||
|
||
## Refinements logged during implementation
|
||
|
||
- **Stage 0**: solver `replace` deferred to Stage 2 (nothing imports it yet;
|
||
adding the path now would break CI, which checks out only this repo). Docker /
|
||
compose deferred to a stage that has something to deploy. Trunk is `master`
|
||
(owner preference); `feature/*` + PR from Stage 1; the genesis commit lands on
|
||
`master` by necessity.
|
||
- **Stage 1** (interview + implementation):
|
||
- Query layer: **go-jet** over `database/sql` (pgx stdlib) + otelsql; a
|
||
`cmd/jetgen` tool regenerates the **committed** code from a throwaway
|
||
container. Postgres **17** pinned for jetgen, tests and prod.
|
||
- Sessions: opaque token stored only as a **SHA-256 hash** (kept as hex
|
||
`text`, not `bytea` — avoids jet bytea-literal friction), **revoke-only**
|
||
(no TTL); revocation-audit table deferred. Backend keeps a warmed
|
||
write-through session cache that gates `/readyz`.
|
||
- Data model: **UUIDv7** PKs; one unified `identities` table
|
||
(`kind ∈ telegram|email`, widen to `vk`/`max` later); no soft-delete /
|
||
actor-audit columns yet.
|
||
- HTTP surface: **service/store/cache layer only**. `/api/v1/{public,user,
|
||
internal,admin}` groups + `X-User-ID` middleware are scaffolding (exposed via
|
||
`Server` group accessors); the session/account REST handlers land with the
|
||
gateway in **Stage 6**. Admin bootstrap deferred to **Stage 10**.
|
||
- Telemetry: providers + request-timing middleware + otelsql; exporters
|
||
`none` (default) / `stdout`; OTLP + dashboards deferred to **Stage 12**.
|
||
- Tests/CI: integration tests behind the `integration` build tag in
|
||
`backend/internal/inttest` + new `integration.yaml` (testcontainers, Ryuk
|
||
off, serial), firing on push and PR. Backend now **hard-depends on Postgres
|
||
at boot** (migrations at startup) — a deliberate contract change from
|
||
Stage 0, documented in both READMEs. All code stays in the existing
|
||
`backend` module under `internal/` (+ `cmd/jetgen`); `go.work` untouched.
|
||
- **Stage 2** (interview + implementation):
|
||
- Scope: `internal/engine` is a self-contained **library** (registry, bag,
|
||
`Game` state machine, decode/replay). No `config`/`main`/`server` wiring this
|
||
stage — there is no consumer yet; wiring lands in **Stage 3**, mirroring
|
||
Stage 1's deferred handlers.
|
||
- **Pure rules engine** (interview): the engine owns the in-memory `Game`,
|
||
pure transitions (play/pass/exchange/resign + draw) **and end-condition
|
||
detection**, including the standard **end-game rack-adjustment scoring** — a
|
||
deliberate slice of Stage 3's "scoring/end-conditions" that the pure-engine
|
||
boundary implies. Stage 3 keeps scheduling, the 24h timeout, persistence and
|
||
GCG.
|
||
- **Solver wiring**: `replace scrabble-solver => ../scrabble-solver` in
|
||
`go.work`; `backend/go.mod` requires `scrabble-solver` (placeholder version,
|
||
redirected by the replace) and `github.com/iliadenisov/dafsa` directly (for
|
||
`dawg.Load`). CI clones the **public** solver repo at **master HEAD**
|
||
anonymously into `../scrabble-solver` (no token); both Go workflows gained
|
||
the step (the engine's untagged tests run under the integration workflow too)
|
||
and set `BACKEND_DICT_DIR`.
|
||
- **Dictionaries**: registry loads the committed DAWGs from a directory
|
||
parameter; `dict_version` is an explicit string label; the latest version
|
||
per variant is tracked. Smoke tests validate a known word per variant
|
||
(English/Russian/Эрудит). **Эрудит is handled uniformly** — every real
|
||
difference is already in `rules.Erudit()`; the move.go "single orientation
|
||
per turn" note needs no special code (any single play is one-directional).
|
||
- **Bag/blanks/exchange**: own deterministic `Bag` (Draw + Return) because
|
||
`selfplay.Bag` cannot return tiles; exchange is legal only when the bag holds
|
||
at least a rack and draws replacements before returning the swapped tiles. A
|
||
blank is `Placement{Blank:true}` carrying its designated letter; the history
|
||
keeps the concrete letter plus a blank flag (decoded via `Alphabet.Character`
|
||
/ `Decode`). `ReplayBoard` reuses `scrabble.Apply`, so no `internal/encoding`
|
||
dependency.
|
||
- **Deviation from the approved plan**: `docs/FUNCTIONAL.md` (+`_ru`) was left
|
||
unchanged. Stage 2 adds no user-visible behaviour; the variant, per-game
|
||
dictionary and dictionary-independent-history user stories already live in
|
||
Stages 3–4, so a "light touch" here would have duplicated or pre-empted them.
|
||
- **Stage 3** (interview + implementation):
|
||
- Scope, as in Stages 1–2: **domain service/store layer + engine wiring, no
|
||
HTTP** (`internal/game`). The gateway↔backend REST surface lands in Stage 6;
|
||
the only active driver this stage is a background turn-timeout sweeper started
|
||
from `main`. The robot (Stage 5) will consume the same service API.
|
||
- **Persistence = event-sourcing + warm cache** (interview): durable state is
|
||
the `games` row plus an append-only decoded move journal (`game_moves`); the
|
||
live position is an `engine.Game` kept in an in-memory cache with a ~24h idle
|
||
TTL and rebuilt by replaying the journal on a miss (the seeded bag makes
|
||
replay exact). Each game is serialised by a per-game mutex; a persistence
|
||
failure evicts the live game so the next access rebuilds. §9 reworded from
|
||
"stored structurally" to this model.
|
||
- **Resign/timeout split** (interview): 2-player resign/timeout only this stage
|
||
(the other player wins); multiplayer drop-out-and-continue + resigned-tiles
|
||
disposition deferred to Stage 4. Per-game **turn-timeout duration** setting
|
||
(5/10/15/30 min, 1/2/3/6/12/24 h; default 24 h) and a per-user **away window**
|
||
(`accounts.away_start/away_end`, default 00:00–07:00 local, honoured by the
|
||
sweeper with midnight-cross handling) added now; profile editing of the away
|
||
window is Stage 4 and the robot's sleep (Stage 5) reuses it.
|
||
- **Engine `Resign` fix** (interview, in `internal/engine`): the resigner keeps
|
||
their accumulated score (no end-game rack adjustment) and never wins; `winner`
|
||
excludes the resigner, so a two-player resign/timeout gives the win to the
|
||
other player regardless of score. Timeout reuses `Resign`, so the game domain
|
||
needs no winner override.
|
||
- **Additive engine domain API**: `Direction`, `Game.SubmitPlay/SubmitExchange/
|
||
EvaluatePlay/HintView/Hand`, `MoveRecord.{Dir,MainRow,MainCol}`,
|
||
`Registry.Lookup`, `ParseVariant` — so `internal/game` never imports
|
||
`scrabble-solver` (keeps the §5 single-importer invariant).
|
||
- **Create = atomic with seats** (interview): `Create` seats all accounts and
|
||
starts; lobby seat-filling is Stage 4. **Sweeper = periodic goroutine**
|
||
(interview; default 60 s, `BACKEND_GAME_TIMEOUT_SWEEP_INTERVAL`).
|
||
- **Hint = settings + wallet** (interview): per-game `hints_allowed` +
|
||
`hints_per_player`, plus a profile wallet `accounts.hint_balance` (spent after
|
||
the allowance; purchases later). Category defaults (random 1 / tournament 0 /
|
||
friendly 1-or-0) are the caller's job (lobby/tournaments).
|
||
- **Stats** (interview): `account_stats` with **`draws`** added beyond §9's
|
||
wins/losses; `max_word_points` = best single **move** score; ties draw,
|
||
resign/timeout is a loss, guests get no stats.
|
||
- **Complaint** (interview): full payload with `game_id`; word-check is scoped
|
||
to the game's pinned `(variant, dict_version)`. Stage 10 owns the resolution
|
||
lifecycle, so the `status` column carries no value CHECK yet.
|
||
- **GCG** (interview): standard Poslfit dialect (UTF-8, `#player`/`#lexicon`
|
||
pragmas, `8G`/`H8` coordinates, lower-case blanks, `.` pass-throughs, `-TILES`
|
||
exchange) plus `#note` lines for resign/timeout; derived from the journal, so
|
||
dictionary-independent.
|
||
- **Engine wiring + config**: `main` loads the registry (`engine.Open`, a hard
|
||
boot dependency like migrations) and starts the sweeper. New config:
|
||
`BACKEND_DICT_DIR` (required), `BACKEND_DICT_VERSION` (default `v1`),
|
||
`BACKEND_GAME_TIMEOUT_SWEEP_INTERVAL` (60 s), `BACKEND_GAME_CACHE_TTL` (24 h).
|
||
No CI change — both Go workflows already clone the solver sibling and export
|
||
`BACKEND_DICT_DIR`. `accounts` gained `away_start`/`away_end`/`hint_balance`
|
||
and the `account` package gained `SpendHint` (it owns its table).
|
||
|
||
- **Stage 4** (interview + implementation):
|
||
- Scope, as in Stages 1–3: **domain service/store layer, no HTTP** — REST/stream
|
||
is Stage 6. Chat and nudges are **persisted** now; live delivery (push /
|
||
in-app stream) is Stage 6/8. New packages `internal/social` (friends, blocks,
|
||
chat+nudge) and `internal/lobby` (matchmaking + invitations); profile editing
|
||
and the email confirm-code extend `internal/account`. The services have no
|
||
active driver this stage, so `main` builds them and hands them to the server,
|
||
which exposes them via accessors (the Stage 1 scaffolding-accessor pattern) for
|
||
the Stage 6 handlers.
|
||
- **Friends** (interview): request → accept on a single `friendships` table;
|
||
decline/cancel delete the pending row; **blocking severs** any friendship.
|
||
- **Blocks** (interview): the existing global toggles **plus** a per-user
|
||
`blocks` table; block effects are **mutual** (a block either way suppresses
|
||
chat visibility and prevents requests/invitations between the pair).
|
||
- **Friend games** (interview): invitation → accept; the game starts only when
|
||
**all** invitees accept, any decline cancels it, and a pending invitation
|
||
**lazily expires after 7 days** (checked on access — no new sweeper).
|
||
- **Chat** (interview): ≤ **60 runes**, stored with the game forever, the
|
||
sender **IP** kept for moderation (as `text`, following Stage 1's no-`bytea`
|
||
precedent; the gateway forwards it in Stage 6), input **content-filtered**
|
||
(links/emails/phone numbers incl. obfuscated forms) via `mvdan.cc/xurls/v2`
|
||
plus a compact leet/separator normaliser and a ≥7-digit phone heuristic — the
|
||
one new dependency. **Nudge is a chat message** (`kind='nudge'`), rate-limited
|
||
to once per hour per game per sender.
|
||
- **Matchmaking** (interview): an **in-memory** FIFO pool keyed by **variant**
|
||
only (variant fixes the board language), pairing two humans (seat order
|
||
randomised). The 10 s wait and **robot substitution are deferred to Stage 5**.
|
||
The pool does **not** consult blocks (auto-match is anonymous) — a deliberate
|
||
simplification of the plan's optional block-skip that also avoids a DB call
|
||
under the pool lock.
|
||
- **Email confirm-code** (interview): 6-digit code, 15-min TTL, ≤ 5 attempts,
|
||
stored as a **SHA-256 hash**; a `Mailer` seam with an SMTP relay
|
||
(`BACKEND_SMTP_*`) and a default **log mailer**. It binds an email to the
|
||
current account; an email already confirmed by another account → `ErrEmailTaken`
|
||
(**merge is Stage 11**); email-as-login is Stage 6 and reuses this mechanism.
|
||
- **Multi-player drop-out** (interview; discharges the Stage 3 deferral): the
|
||
engine's `Resign` now drops a seat and the rest **play on** while ≥ 2 are
|
||
active, finishing (last-survivor wins) when one remains; `winner` excludes all
|
||
resigned seats. A per-game **`dropout_tiles`** setting (`remove` default |
|
||
`return`) governs the leaver's rack, which is **never revealed** to the others.
|
||
Timeout reuses `Resign`, so a multi-player timeout drops one seat and play
|
||
continues; `game.commit`/`timeoutGame` were already keyed on `g.Over()`, so they
|
||
only needed the setting threaded through create/replay.
|
||
- **Build/deps**: `go mod tidy` is not run — the bare-path `scrabble-solver`
|
||
replace lives only in `go.work`, so `tidy`/`go get` cannot resolve it; the
|
||
`xurls` dependency was added with `go mod edit -require` + `go mod download`,
|
||
its checksums recorded in the committed **`go.work.sum`**. No CI workflow change
|
||
(both Go workflows already clone the solver sibling and export
|
||
`BACKEND_DICT_DIR`).
|
||
|
||
- **Stage 5** (interview + implementation):
|
||
- Scope, as in Stages 1–4: **domain layer, no HTTP** — the robot consumes the
|
||
public game API as an ordinary seated player (`internal/robot`), so only
|
||
`internal/engine` still imports the solver. New: `engine.Candidates()` (decoded
|
||
ranked plays) and a thin `game.Service.Candidates` + `RobotTurns` read.
|
||
- **Account model** (interview): a pool of **durable accounts**, each a single
|
||
`identities` row `kind='robot'` (migration `00004` widens the kind CHECK — a
|
||
CHECK-only change, no jetgen). A curated ~16-name pool in code; `EnsurePool`
|
||
provisions them idempotently at boot (a hard dependency, like the registry) with
|
||
`block_chat`/`block_friend_requests` set, which is **all** the friend/DM blocking
|
||
needs (no special-casing).
|
||
- **Driver + state** (interview): a background sweeper goroutine
|
||
(`robot.Service.Run`/`Drive`, mirroring the timeout sweeper); **every per-game
|
||
and per-turn choice is derived deterministically from the game `seed`** (FNV-1a
|
||
mix, restart-stable — not `hash/maphash`), so the robot keeps **no extra state**.
|
||
`playToWin = mix(seed,"win")%100 < 40`; per-turn `delay`; sleep `drift`.
|
||
- **Timing** (interview): per-move delay `2 + 88·u^k` minutes, `u~U(0,1)`,
|
||
**k≈3.5 → median ~10 min**, clamped to [2,90]. A daytime nudge on the robot's
|
||
turn pulls the move into a 2–10 min reply window; the robot proactively nudges
|
||
after **12 h** idle on the human's turn (reusing `social.Nudge`'s once-per-hour
|
||
guard; `social.LastNudgeAt` added to detect the human's nudge).
|
||
- **Sleep** (interview — resolves the §7-vs-`account.go` mismatch): the robot
|
||
sleeps 00:00–07:00 in the **opponent's timezone shifted by a per-game drift ∈
|
||
[−3,+3]h** (so its night overlaps the human's rather than running anti-phase),
|
||
computed on the fly per game — **no profile mutation, no concurrency cap**. The
|
||
`account.go` away-window comment was corrected accordingly.
|
||
- **Margin** (interview): pick the candidate whose resulting margin (own+move−opp)
|
||
is closest to **[1,30]** when playing to win / **[−30,−1]** when playing to lose,
|
||
tie-broken toward the conservative edge; no legal play → exchange the full rack
|
||
when the bag can refill it, else pass. *(Later refined — separate PR: on ≈20% of
|
||
opening/midgame moves the robot flips its intent for that one move, the chance
|
||
tapering to 0 over the last 14 bag tiles and 0 at an empty bag, so the endgame
|
||
stays strict; deterministic from the seed.)*
|
||
- **Substitution** (interview): a matchmaker **reaper** (`Reap`/`RunReaper`)
|
||
substitutes a pooled robot after a **10 s** wait (`BACKEND_LOBBY_ROBOT_WAIT`),
|
||
`NewMatchmaker` now takes a `RobotProvider`. A waiter learns of a match — human
|
||
pairing **or** substitution — through a new `Poll` + results map; production
|
||
delivery is a **match-found notification** (session/in-app push + side-service),
|
||
Stage 6/8 — noted in §10.
|
||
- **Metrics** (interview, 1+2): robots are durable accounts, so `account_stats`
|
||
is the authoritative, complete balance ground-truth (target ~40% robot wins);
|
||
an OTel counter (`robot_games_finished_total`, exporter `none` today) and a
|
||
structured log cover robot-finished games for live observation.
|
||
- **Config**: `BACKEND_ROBOT_DRIVE_INTERVAL` (30 s), `BACKEND_LOBBY_ROBOT_WAIT`
|
||
(10 s), `BACKEND_LOBBY_REAPER_INTERVAL` (1 s). No CI change (both Go workflows
|
||
already clone the solver sibling and export `BACKEND_DICT_DIR`).
|
||
|
||
- **Stage 6** (interview + implementation):
|
||
- **Scope = framework + vertical slice** (interview): the *whole* edge mechanism
|
||
is built and the backend's REST surface + the live-event seam are opened for
|
||
the first time, but only a representative slice of operations is wired
|
||
end-to-end — auth (`auth.telegram`/`auth.guest`/`auth.email.request`/
|
||
`auth.email.login`), `profile.get`, `game.submit_play`/`game.state`,
|
||
`lobby.enqueue`/`lobby.poll`, `chat.post`, all five push events, and the admin
|
||
passthrough. The remaining domain operations reuse the identical transcode
|
||
pattern and are wired as the UI needs them: the play-loop ops (pass/exchange/
|
||
resign, hint, evaluate, word-check/complaint, history, my-games list, chat
|
||
list/nudge) in **Stage 7**; the social/account ops (friends, blocks,
|
||
invitations, profile editing, stats, GCG export) in **Stage 8**.
|
||
- **Wire contracts in a new shared `scrabble/pkg` module** (interview): the
|
||
backend push proto (`pkg/proto/push/v1`) and the FlatBuffers edge payloads
|
||
(`pkg/fbs`, one `scrabblefb` namespace) live here with **committed** generated
|
||
Go, imported by both backend and gateway. The Connect envelope proto lives in
|
||
`gateway/proto/edge/v1`. Codegen is dev-time (`buf generate` with **local**
|
||
plugins + `flatc`, driven by per-module `Makefile`s, mirroring `cmd/jetgen`);
|
||
CI only builds the committed output. `pkg` and `gateway` are bare-path modules
|
||
like `scrabble-solver`, so `go.work` carries `use ./pkg`, `use ./gateway` and a
|
||
`replace scrabble/pkg v0.0.0 => ./pkg` (the no-dot path is not VCS-fetchable);
|
||
deps were added with `go mod edit` + `go work sync` (the established no-tidy
|
||
pattern). `flatc` is pinned to **23.5.26** to match the `flatbuffers` Go runtime.
|
||
- **Guest = durable account + `is_guest`** (interview): migration `00005` adds
|
||
`accounts.is_guest`; a guest is a durable row with **no identity** (so the
|
||
`sessions`/`game_players` foreign keys hold) that is **excluded from statistics**
|
||
(the finish-time recompute skips guest seats) and from friends/history. The
|
||
earlier "guests never reach this table" comments and §3/§9 were softened to
|
||
"no profile/friends/stats persisted". Guest-row GC is a logged TODO (TODO-3).
|
||
- **Push = in-process `Publisher` + backend gRPC listener** (interview): a new
|
||
`internal/notify` hub (a `Publisher` interface defaulting to `Nop`, installed on
|
||
`game`/`social`/`lobby` via `SetNotifier` during boot — additive, existing tests
|
||
unchanged) is drained by a new backend gRPC server (`internal/pushgrpc`,
|
||
`BACKEND_GRPC_ADDR` default `:9090`) serving `Push.Subscribe`. Emission lives in
|
||
`game.commit` (so robot-driver and timeout-sweep moves emit `your_turn`/
|
||
`opponent_moved` too — the background sources a handler-only design would miss),
|
||
`social` (`chat_message`/`nudge`) and the matchmaker (`match_found`). Event
|
||
payloads are FlatBuffers-encoded **in the backend** (it imports `pkg/fbs`); the
|
||
gateway forwards them verbatim. Revoke/session-invalidation and cursor-resume are
|
||
**deferred** (single-instance MVP).
|
||
- **Edge envelope = minimal, token in header** (interview): the `Gateway` Connect
|
||
service is `Execute(message_type, payload, request_id)` + `Subscribe`; the
|
||
session token rides in `Authorization: Bearer`; auth ops are unauthenticated and
|
||
return the token in the FlatBuffers `Session`. Domain outcomes ride back in the
|
||
`ExecuteResponse.result_code` (HTTP 200); only edge failures (rate limit, missing
|
||
session, unknown type, internal) are Connect error codes. No Ed25519/signing
|
||
(the galaxy donor's crypto stack was dropped, per §3).
|
||
- **Admin = gateway validates Basic-Auth** (interview): the gateway checks
|
||
`GATEWAY_ADMIN_USER`/`_PASSWORD` and reverse-proxies to backend
|
||
`/api/v1/admin/*`; the backend admin surface is a single `ping` until Stage 10.
|
||
- **Rate-limit = 2 dimensions, 3 classes** (interview): public per-IP (30/min,
|
||
burst 10), authenticated per-user (120/min, burst 40), admin per-IP (60/min,
|
||
burst 20), plus an email-code per-IP sub-limit (5/10 min); token bucket
|
||
(`golang.org/x/time/rate`) with a lazy stale-bucket sweep.
|
||
- **Email-as-login** (discharges the Stage 4 deferral): `account.EmailService`
|
||
gained `RequestLoginCode`/`LoginWithCode`, reusing the confirm-code mechanism but
|
||
provisioning-or-finding the account by email identity (it does **not** refuse an
|
||
already-confirmed address — that is the returning user).
|
||
- **CI**: both Go workflows gained `gateway/**` (and `pkg/**` where backend depends
|
||
on it) path filters and now build/vet/test `./backend/... ./pkg/... ./gateway/...`
|
||
(unit) — integration stays `./backend/...` (the only module with tagged tests).
|
||
The solver clone + `BACKEND_DICT_DIR` steps are unchanged.
|
||
|
||
- **Stage 7** (interview + implementation):
|
||
- **Scope = playable slice** (interview): the *whole* UI shell plus the core play
|
||
loop end-to-end; the social/account/history surfaces were split out into a new
|
||
**Stage 8** and the later stages shifted +1 (Telegram→9, Admin→10, Linking→11,
|
||
Polish→12). Stage 7 wires only the operations the slice needs (the Stage 6
|
||
"as the UI needs them" pattern): the new gateway/transcode + backend-REST ops
|
||
`games.list`, `game.{pass,exchange,resign,hint,evaluate,check_word,complaint,
|
||
history}`, `chat.{list,nudge}`. The only new domain code is `game.ListForAccount`
|
||
(the "my games" query) and seat **`display_name`** resolution (server DTO layer);
|
||
`SeatView` gained a trailing `display_name`. Friends/blocks/invitations,
|
||
profile-editing, stats and the history/GCG viewer are Stage 8.
|
||
- **Stack** (interview): plain **Svelte 5 (runes) + TypeScript + Vite**, no
|
||
SvelteKit; `@connectrpc/connect-web` + the `flatbuffers` runtime, with the edge
|
||
TS bindings generated from the **same** `edge.proto` (`protoc-gen-es`) and
|
||
`scrabble.fbs` (`flatc --ts`) and **committed** under `ui/src/gen/` (dev-time
|
||
codegen, like `cmd/jetgen` / `pkg/Makefile`; CI builds the committed output).
|
||
- **No board on the wire** (discovered): `StateView` carries no grid, so the client
|
||
**replays the decoded move journal** (`game.history`, newly wired) onto an empty
|
||
board; premium squares + tile values are a client-side map **ported from
|
||
`scrabble-solver/rules/rules.go`** with a Vitest parity test.
|
||
- **Board UX** (interview): full-width, borderless; tiles placed by **Pointer-Events
|
||
drag or tap** (no HTML5 DnD — it has no touch support); a contextual **MakeMove**
|
||
control (short tap → make/reset popup, ~1 s press-and-hold → commit); per-tile
|
||
recall by tapping a pending tile; a **two-state zoom** (15↔9 cells) on touch only
|
||
(auto-zoom-in on placement, double-tap / pinch manual); a blank-letter chooser.
|
||
All board/tiles/effects are **pure HTML5/CSS + Unicode** — no image/font/SVG asset.
|
||
- **Theming** (interview): own **CSS custom-property tokens**, light/dark via
|
||
`prefers-color-scheme`, **Telegram-themeParams-ready** (a runtime hook can override
|
||
the tokens; the SDK is wired in the Telegram stage). **Navigation** (interview):
|
||
dependency-free **hash router**; session token in memory + **IndexedDB**, re-resolved
|
||
on reload (reopen Subscribe, refetch the open game); stream reconnect on focus.
|
||
**i18n** en/ru is a hand-rolled typed catalog (compile-time key parity + a test).
|
||
- **Mock transport** (owner request): a build-flagged in-memory fake (`VITE_MOCK`,
|
||
`pnpm start`) drives lobby → active game → board with no backend, tree-shaken out
|
||
of production; it is the same fixture the Playwright smoke uses.
|
||
- **Tests/CI** (interview): **Vitest** units (board replay, placement machine,
|
||
premium parity, i18n parity, FlatBuffers codec) + a **Playwright** smoke against
|
||
the mock; a new **`ui-test.yaml`** workflow (type-check, unit, build with a
|
||
**bundle-size budget** — prod is ~67 KB gzip JS — and a chromium e2e). The Go
|
||
workflows already cover the new backend/gateway/pkg code; a `game.ListForAccount`
|
||
integration test and gateway transcode tests for the new ops were added.
|
||
- **UX polish** (follow-up PR): a mobile-app **app shell** (growing nav bar, content
|
||
pinned to the bottom) + a one-line **announcement banner** (client-side mock
|
||
rotation now; server-driven channel later — §10); a mobile-OS **tab bar** and a
|
||
reusable **HoldConfirm** press-and-hold control (MakeMove 🏁 + game-action confirms);
|
||
board **zoom reworked** to a width-based zoom in a fixed viewport (real native
|
||
scroll, double-tap; pinch/swipe dropped) with constant `cqw` labels, corner-letter
|
||
tiles, contrasting grid lines, last-word dark-tile highlight, and a Settings
|
||
**bonus-label style** (beginner/
|
||
classic/none); **hint lays its tiles on the board** (no spend when no move — a new
|
||
`no_hint_available` result code); the history opens as an in-place **slide-down**
|
||
(not a modal); word-check is alphabet/length-limited, cached and throttled. Design
|
||
details live in the new [`docs/UI_DESIGN.md`](docs/UI_DESIGN.md).
|
||
|
||
- **Stage 8** (interview + implementation):
|
||
- **Scope = vertical slice continued**: the social/account/history operations were
|
||
opened end-to-end (UI → gateway transcode → backend REST → existing domain
|
||
services). The only new backend logic is `lobby.ListInvitations`,
|
||
`account.Store.GetStats`, a `game.SharedGame` seam (self-join on `game_players`),
|
||
the friend-code mechanism, and the friendships `declined`-status change.
|
||
- **Friends — two add paths** (interview, a deliberate plan change): **one-time
|
||
friend codes** (the player to be added issues a **6-digit numeric** code, 12 h TTL,
|
||
SHA-256-hashed like email codes, single active per issuer, single-use, redeem
|
||
rate-limited) and a **play-gated request** (`SendFriendRequest` now requires a
|
||
shared game — active or finished). An explicit **decline is permanent** (blocks
|
||
re-send), an **ignored request lazily expires after 30 days** and may be re-sent,
|
||
and a **code from the same person bypasses a prior decline**. This **supersedes
|
||
Stage 4's** "declining/cancelling deletes the row" (cancel by the requester still
|
||
deletes; decline now sets `status='declined'`). Migration **00006** widens
|
||
`friendships_status_chk` and adds **`friend_codes`** (jetgen regen). No public ID
|
||
or name search — discovery is codes + befriend-an-opponent.
|
||
- **Badges = poll + push** (interview): a new generic **`notify`** push event
|
||
(`notify.KindNotification`, sub-kinds friend_request/friend_added/invitation/
|
||
game_started) drives the lobby hamburger + "Friends" badge; emitted on friend-
|
||
request and invitation create and on the invitation's game start. The client polls
|
||
incoming requests + open invitations on lobby open and on focus (a missed push
|
||
while hidden), and re-polls on the `notify` event. Cursor-resume stays deferred
|
||
(single-instance MVP, §10).
|
||
- **Language single-control** (interview): the Settings language control writes
|
||
through to the durable account's `preferred_language` (`profile.update`); guests
|
||
keep only the client preference. Seeding the language from the platform/client on
|
||
first provider login is a **Stage 9** forward-note.
|
||
- **Guests = durable-only** (interview): friends/blocks/invitations/statistics and
|
||
history management are durable-account-only; a guest sees a sign-in prompt.
|
||
Binding an email to an existing guest (account linking) stays **Stage 11**.
|
||
- **GCG = finished-only + share** (interview): `game.ExportGCG` refuses an active
|
||
game (`game.ErrGameActive`) to avoid leaking the live journal mid-play; the client
|
||
exports via the **Web Share API** where available, else a **Blob download**
|
||
(`game-<id>.gcg`). Capacitor-native file save lands with the native wrapper.
|
||
- **IA = as the mockup** (interview): Friends (friends + blocks) is its own screen
|
||
from the lobby menu; Invitations is a lobby section + a "play with friends" mode in
|
||
New game; Stats is a lobby tab-bar button; profile editing is on Profile; history +
|
||
GCG stay in the game.
|
||
- **Wire/codegen**: new fbs tables (friends/blocks/invitations/profile-update/email-
|
||
bind/stats/gcg + `NotificationEvent`; `Profile` gained trailing away fields) in
|
||
`pkg/fbs`, regenerated to committed Go + TS; ~21 new gateway transcode ops; new
|
||
REST handlers under `/api/v1/user/{friends,blocks,invitations,profile,email,stats}`
|
||
and `…/games/:id/gcg`. UI grows to ~82 KB gzip JS (budget 100 KB). No CI workflow
|
||
change (the Go and UI workflows already cover the new code).
|
||
- **UI polish (owner review follow-up)**: a copyable friend code (📋 + toast); the
|
||
lobby notification badge fixed (it had inherited the hamburger-bar style) and made
|
||
a proper count dot; Safari flex inputs given `min-width:0`; **profile-edit
|
||
validation on both UI and backend** — display-name format (letters + single
|
||
`␠`/`.`/`_`, ≤ 32 runes), a **UTC-offset** timezone picker (`account.ResolveZone`
|
||
parses `±HH:MM` or IANA; DST is traded for the simple picker), a 10-minute away grid
|
||
capped at **12 h** (wrap-aware), email format — with Save disabled and invalid
|
||
fields red-bordered while any field is invalid; language stays in Settings; in a
|
||
game, an "add to friends" item flips to a disabled "request sent"; chat send/nudge
|
||
became ⬆️/🛎️ icons; a **finished game** drops its last-word highlight, hides Check
|
||
word / Drop game, disables zoom, and draws an **inert footer** (greyed rack + tab
|
||
bar) instead of hiding it. Two **iPhone-simulator** passes then made the chat and
|
||
modals keyboard-aware (`dvh` plus a `visualViewport` listener that sizes the modal
|
||
backdrop to the area above the keyboard), reserved the rack height so a finished
|
||
footer does not collapse, and compacted the play-with-friends form (a searchable
|
||
bounded-scroll friend list, a pinned invite, and an explicit, **required game
|
||
type** — a smart default is TODO-6). On the owner's call, **every profile / new-game
|
||
picker is a native `<select>`** (the away window as hour + 10-minute selects, the
|
||
timezone as a UTC-offset select): native time/wheel inputs render differently per
|
||
OS and can't be forced to match, and a select also avoids the iOS "clear" button
|
||
that would empty a time field.
|
||
|
||
- **Stage 9** (interview + implementation):
|
||
- **Connector as its own container** (interview): the Telegram side-service is a
|
||
standalone module `platform/telegram` (binary `cmd/telegram`) holding the bot
|
||
token **only there**; gateway and backend reach it by **unauthenticated gRPC**
|
||
on the trusted internal network, and it egresses to `api.telegram.org` through a
|
||
**VPN sidecar** (`deploy/docker-compose.yml`, mirroring `../15-puzzle`). Bot
|
||
library **`github.com/go-telegram/bot`** (one new dep), **long-poll** updates.
|
||
- **initData validation moved off the gateway** (interview): the gateway's HMAC
|
||
validator was **relocated** into the connector (`internal/initdata`, now also
|
||
returning `language_code`); the gateway calls `connector.ValidateInitData` over
|
||
gRPC during `auth.telegram`. The hop is negligible (loopback gRPC, once per
|
||
login). `GATEWAY_TELEGRAM_BOT_TOKEN` is gone; `GATEWAY_CONNECTOR_ADDR` replaces
|
||
it. The `gateway/internal/auth` package was deleted.
|
||
- **Connector gRPC API** (`pkg/proto/telegram/v1`, service `Telegram`): the
|
||
generic methods are **platform-agnostic**, keyed by the identity `external_id`
|
||
(so a future VK/MAX connector reuses them); only `ValidateInitData` is
|
||
Telegram-specific. Methods: `ValidateInitData`, **`Notify`** (the out-of-app push
|
||
— renders a localized message + a Mini App deep-link button from the FlatBuffers
|
||
payload), `SendToUser` and `SendToGameChannel` (arbitrary admin messages — built
|
||
and unit-tested now, **wired to the admin surface in Stage 10**; the game channel
|
||
id lives only in connector config).
|
||
- **Push = fallback, gateway-routed, de-dup by presence** (interview): the gateway
|
||
already consumes the firehose and knows in-app presence (`push.Hub.HasSubscribers`),
|
||
so it decides in-app vs out-of-app **atomically**: for a recipient with **no live
|
||
in-app stream** it fetches a new backend `/internal/push-target`
|
||
(`{external_id, language, notifications_in_app_only}`) and calls `connector.Notify`
|
||
only when they have a Telegram identity and have **not** set the new flag. Push
|
||
set: `your_turn`, `nudge`, `match_found`, and the `notify` sub-kinds `invitation`/
|
||
`friend_request` (the connector skips the rest). Delivery runs in a goroutine so a
|
||
slow connector never stalls the firehose; best-effort (no cursor resume — single
|
||
instance, §10).
|
||
- **Profile flag `notifications_in_app_only`** (interview, **default true** → push
|
||
is **opt-in**): migration `00007` (+ jetgen), threaded through
|
||
`account.Profile`/`UpdateProfile`, the REST DTOs, the fbs `Profile`/
|
||
`UpdateProfileRequest` (default `true` in the schema so an unset field reads
|
||
conservatively), and a Profile-screen toggle. Flagged at review: the channel is
|
||
silent until a user turns it off.
|
||
- **Language seeding from the platform** (discharges the Stage 8 forward-note):
|
||
`account.ProvisionTelegram` seeds a **brand-new** account's `preferred_language`
|
||
from the Telegram `language_code` and its display name from `first_name`/
|
||
`username` (existing accounts untouched); the UI's `adoptSession` already adopts
|
||
the server language when the user has not locked a locale, so no extra UI seeding
|
||
was needed. The gateway forwards the fields from `ValidateInitData`.
|
||
- **Mini App = `/telegram/` + guard** (interview): the gateway serves the one SPA
|
||
build under `/telegram/` (Vite **relative base**; the hash router is
|
||
path-agnostic). The UI detects a Telegram launch by `Telegram.WebApp.initData`,
|
||
applies `themeParams`, authenticates via the existing `auth.telegram` op (UI
|
||
`authTelegram` codec/client/transport/mock added), and routes the deep-link
|
||
`start_param` (`g`/`i`/`f` → game / lobby-invitation / friend-code redeem). On the
|
||
`/telegram/` path **without** initData it redirects to the site root. The official
|
||
`telegram-web-app.js` loads from `index.html` (harmless outside Telegram).
|
||
- **Deep-link scheme** (shared Go `platform/telegram/internal/deeplink` ↔ TS
|
||
`ui/src/lib/deeplink.ts`): `g<game uuid>` / `i<invitation uuid>` / `f<6-digit
|
||
code>` / empty = lobby. A friend-code **share-to-Telegram** link is shown when
|
||
`VITE_TELEGRAM_LINK` is configured (**partially discharges TODO-5**; QR still
|
||
open). The `Notify` button and the bot `/start` reply both wrap the payload as
|
||
`<MiniAppURL>?startapp=<payload>`.
|
||
- **Test environment** (interview nuance): the Bot API base is overridable for
|
||
Telegram's test environment — `TELEGRAM_TEST_ENV=true` suffixes the token with
|
||
`/test` so the client hits `/bot<token>/test/METHOD` (`TELEGRAM_API_BASE_URL`
|
||
overrides the host for a mock/self-hosted server).
|
||
- **Deploy groundwork** (interview): `platform/telegram/Dockerfile` (builds the
|
||
connector standalone — drops backend/gateway and the solver replace from a copy
|
||
of `go.work`, validated with `docker build`) + the connector-scoped compose with
|
||
the VPN sidecar; a root `.dockerignore`. **No public ingress** for the connector
|
||
(long-poll + sidecar egress); the host reverse proxy routes only to the gateway
|
||
port, which serves the Mini App. The full multi-service deploy is **Stage 12**.
|
||
- **Wire/codegen/CI**: new proto `pkg/proto/telegram/v1` (committed Go); fbs
|
||
`Profile`/`UpdateProfileRequest` gained `notifications_in_app_only` (committed Go
|
||
+ TS). `go.work` gains `use ./platform/telegram`; deps via `go mod edit` +
|
||
`go work sync` (no-tidy). `go-unit.yaml` gained the `platform/**` path filter and
|
||
builds/vets/tests `./platform/telegram/...`. UI grows to ~86 KB gzip JS (budget
|
||
100 KB). The connector's unit tests use an httptest fake Bot API; a Playwright
|
||
smoke drives the Mini App launch + guard with an injected `window.Telegram`.
|
||
- **Stage 10 forward-note**: the admin surface will wire `connector.SendToUser`/
|
||
`SendToGameChannel` (backend gains its own connector client) for operator
|
||
broadcasts to a user and the game channel.
|
||
- **Verification-time fixes** (caught by the CI gate): (1) the gateway transcode
|
||
dropped `notifications_in_app_only` in four places (`ProfileResp`, `encodeProfile`,
|
||
`profileUpdateHandler`, the `UpdateProfile` body) so the toggle never reached the
|
||
backend — fixed, with a round-trip transcode test added. (2) The e2e suite was made
|
||
**hermetic** (a shared `ui/e2e/fixtures.ts` blocks the real `telegram-web-app.js`):
|
||
the render-blocking CDN `<script>` hung every page load on the CI runner, where
|
||
telegram.org is unreachable, timing out all non-Telegram specs. (3) A pre-existing
|
||
time-of-day flake in `TestTimeoutSweep` (the default 00:00–07:00 away window made
|
||
the sweeper skip when CI ran with `now-1h` inside it) was made deterministic by
|
||
clearing the test account's away window.
|
||
|
||
- **Stage 10** (interview + implementation):
|
||
- **Admin console = backend-rendered `/_gm`, gateway Basic-Auth** (interview, two
|
||
rounds): the owner chose a dedicated web console but, pointing at `../galaxy-game`
|
||
and asking to keep it simple, the deliverable is **server-rendered Go
|
||
`html/template` + one embedded CSS** (`backend/internal/adminconsole`: a
|
||
framework-agnostic renderer + page view-models, `//go:embed` templates/assets, zero
|
||
JS, no build step), **not** a SPA. It lives **in the backend** on its own route
|
||
`/_gm/*`; the **gateway** (the project's built-in reverse proxy) gates `/_gm/*` with
|
||
the existing `GATEWAY_ADMIN_USER/PASSWORD` Basic-Auth on its **public** listener and
|
||
proxies **verbatim** to backend `/_gm/*` (mounted on the edge mux below the h2c wrap
|
||
so Connect keeps working). This **supersedes Stage 6's** gateway-fronts-
|
||
`/api/v1/admin` model: the separate admin port `GATEWAY_ADMIN_ADDR` is dropped (only
|
||
the port — user/password stay), the backend `/api/v1/admin` group + `ping` are
|
||
removed, and `gateway/internal/admin` is repurposed to the verbatim proxy. The
|
||
backend keeps **no operator identity** and no `admin_accounts` table; CSRF on the
|
||
console's POSTs is a **same-origin** check (`Origin`/`Referer` vs `Host`, the gateway
|
||
preserves the inbound Host) — no token. Discharges Stage 1's "admin bootstrap" (it is
|
||
config, not a DB seed).
|
||
- **Complaint resolution + dictionary pipeline** (interview): migration **00008**
|
||
(+ jetgen) adds `disposition`/`resolution_note`/`resolved_at`/`applied_in_version`
|
||
to `complaints` and the deferred `status` CHECK (`open|resolved`) — **discharges
|
||
Stage 3's** deferral (no `resolved_by`: operator identity is not tracked). Resolution
|
||
sets a disposition (`reject`/`accept_add`/`accept_remove`); accepted complaints are
|
||
**derived by query** into a pending dictionary-change list (no new table), stamped
|
||
`applied_in_version` once a rebuilt version is loaded. New `game` reads
|
||
`ListComplaints`/`GetComplaint`/`CountComplaints`/`ResolveComplaint`/
|
||
`DictionaryChanges`/`MarkChangesApplied`; admin list/count reads
|
||
`account.ListAccounts/CountAccounts/Identities` and `game.ListGames/CountGames/
|
||
GameByID`.
|
||
- **Dictionary hot-reload = per-version subdir** (interview): the launch version stays
|
||
in the flat `BACKEND_DICT_DIR` (CI/dev untouched); a reloaded version `X` loads from
|
||
`BACKEND_DICT_DIR/X/` via the new `Registry.LoadAvailable` (present variants only),
|
||
and boot re-loads every subdirectory via `engine.OpenWithVersions` so reloaded
|
||
versions survive a restart. **Partially addresses TODO-2** (the runtime reload
|
||
contract; the offline DAWG generator stays future work).
|
||
- **Operator broadcasts** (discharges Stage 9's forward-note): the backend gains its
|
||
own connector gRPC client (`backend/internal/connector`, `BACKEND_CONNECTOR_ADDR`,
|
||
nil when unset) over the existing `pkg/proto/telegram/v1`; the console messages a
|
||
user by `account_id` (backend resolves the Telegram `external_id`) and posts to the
|
||
game channel via `SendToUser`/`SendToGameChannel`.
|
||
- **Config/CI**: backend adds `BACKEND_CONNECTOR_ADDR`; gateway drops
|
||
`GATEWAY_ADMIN_ADDR` (keeps user/password). No new module and no fbs/proto/UI codegen
|
||
(the console is server-rendered Go). The Go workflows already span
|
||
`./backend/... ./gateway/... ./pkg/...`; integration stays `./backend/...`.
|
||
|
||
- **Stage 11** (interview + implementation):
|
||
- **Scope = link-via-confirm + merge for email and Telegram** (interview): the
|
||
current account is the merge **primary**; a linked identity that already has its
|
||
own account is merged into the current one and the secondary is retired as an
|
||
**audit tombstone** (`accounts.merged_into`/`merged_at`, migration `00009`
|
||
+ jetgen). Linkable this stage: **email** (the existing confirm-code) and
|
||
**Telegram via the Login Widget** (the web sign-in). New `internal/accountmerge`
|
||
(the single-transaction data merge) and `internal/link` (the orchestrator over
|
||
account + accountmerge + session).
|
||
- **Tombstone, not delete** (interview): the secondary row is kept so a **shared
|
||
finished game**'s no-cascade `game_players`/`chat`/`complaints` foreign keys stay
|
||
valid; its seat in such a game is left in place. The merge is **refused**
|
||
(`ErrActiveGameConflict`) only when the two share an **active** game.
|
||
- **Merge algorithm** (one tx): stats summed (wins/losses/draws) + max kept;
|
||
`hint_balance` summed; identities repointed; non-shared `game_players` transferred
|
||
(shared kept); `chat_messages`/`complaints` reassigned; friendships/blocks repointed
|
||
with self-edge drop and dedupe (friendships by status precedence
|
||
accepted>pending>declined); invitations: secondary's as inviter deleted, invitee
|
||
rows deduped; secondary's `email_confirmations`/`friend_codes` dropped; secondary
|
||
tombstoned. Sessions are handled one layer up: `session.Service.RevokeAllForAccount`
|
||
(+ `Cache.RemoveByAccount`) retires the secondary's sessions after the tx.
|
||
- **Primary direction + guest inversion** (interview): primary = the current account,
|
||
**except** when the initiator is a **guest** and the linked identity already has a
|
||
**durable** owner — then the **durable account wins**, the guest's active games
|
||
transfer into it, the guest is retired, and a **fresh session for the durable
|
||
account is minted and returned** (the client adopts it). Binding a **free** identity
|
||
to a guest is a plain upgrade (clear `is_guest`, same session). Discharges Stage 8's
|
||
"guest email-binding is Stage 11".
|
||
- **API/UX = dedicated ops; reveal only after the code** (interview): new edge ops
|
||
`link.email.request/confirm/merge` (Email-rate-limited) and
|
||
`link.telegram.confirm/merge`. `request` **always** mails a code (no pre-send
|
||
"taken" signal, so a probe cannot enumerate registered addresses); a required merge
|
||
is revealed **only after** the code is verified, gating an explicit irreversible
|
||
merge step (the Profile screen's confirmation dialog). This **supersedes Stage 8's**
|
||
`email.bind.*` ops (and their fbs `EmailBindRequest`/`EmailConfirmRequest` tables),
|
||
which were retired from the gateway/UI for that reason; the backend
|
||
`EmailService.RequestCode`/`ConfirmCode` primitives stay (still covered by inttest).
|
||
- **Field policy** (interview): `display_name` = primary's; profile prefs/flags
|
||
(language, timezone, away window, block toggles, `notifications_in_app_only`) =
|
||
primary's; `hint_balance` = **sum**. A new service column **`paid_account`**
|
||
(`bool`, default false; lifetime one-time-payment marker, no purchase flow yet) is
|
||
added in `00009` and **ORed** on merge (`true` always wins). It is not user-editable
|
||
and is shown read-only on the admin account-detail page.
|
||
- **Telegram Login Widget** (interview, owner chose the broader scope): the connector
|
||
validates it (`internal/loginwidget`, secret = `SHA-256(bot_token)`, distinct from
|
||
initData) via a new `Telegram.ValidateLoginWidget` RPC; the gateway validates the
|
||
widget payload and passes the **trusted** `external_id` to the backend link route
|
||
(same trust model as `auth.telegram`). The UI offers "Link Telegram" only in a plain
|
||
web context (`loginWidgetAvailable`), driving the popup `Telegram.Login.auth`; it is
|
||
**inert in production until BotFather `/setdomain`** registers the site domain and
|
||
`VITE_TELEGRAM_BOT_ID` is configured (a deploy concern, Stage 12). e2e mocks the
|
||
widget (telegram.org is blocked on CI).
|
||
- **Wire/CI**: new fbs `LinkEmailRequest`/`LinkEmailConfirm`/`LinkTelegramRequest`/
|
||
`LinkResult` (committed Go + TS); new proto RPC (committed Go); new REST routes under
|
||
`/api/v1/user/link/*`. The Go workflows already span `./backend/... ./gateway/...
|
||
./pkg/... ./platform/telegram/...`; integration stays `./backend/...`. UI ~90 KB gzip
|
||
JS (budget 100 KB). New error code `merge_active_game_conflict`.
|
||
|
||
- **Stage 12** (interview + implementation):
|
||
- **Re-scoped & split** (interview): the original "Polish (observability + perf +
|
||
deploy)" was too large for one session, so it was split — **Stage 12** = observability
|
||
+ performance + guest GC; **Stage 13** = alphabet-on-the-wire (TODO-4); **Stage 14** =
|
||
CI & deploy (TODO-1, TODO-2, the collector + dashboards). The latter two were written
|
||
into the plan now as the agreed baseline (each still re-interviews at its own start).
|
||
(Stage 14 was itself later re-scoped to the solver/dictionary split alone; deploy +
|
||
observability + the dual-bot idea split into Stages 15–18.)
|
||
- **Shared telemetry** (interview): a new `pkg/telemetry` owns the OTel provider
|
||
bootstrap (exporter selection, W3C propagators, shutdown, Go runtime metrics); the
|
||
backend `internal/telemetry` is now a thin facade over it (keeping its gin middleware),
|
||
and the gateway and connector gained telemetry runtimes. A configurable **`otlp`**
|
||
exporter was added alongside `none`/`stdout`; the **default stays `none`**, the OTLP
|
||
endpoint comes from the standard `OTEL_EXPORTER_OTLP_*` env, and the collector +
|
||
dashboards are Stage 15 (so CI needs none). `otelgrpc` instruments the backend push
|
||
server, the gateway's backend + connector clients, and the connector's gRPC server.
|
||
New config `GATEWAY_SERVICE_NAME`/`GATEWAY_OTEL_*` and `TELEGRAM_SERVICE_NAME`/
|
||
`TELEGRAM_OTEL_*`; the backend's existing `BACKEND_OTEL_*` gained the `otlp` value.
|
||
- **Metrics = operational, business-near** (interview): histograms
|
||
`game_replay_duration` and `game_move_validate_duration`; counters
|
||
`games_started_total`, `games_abandoned_total` (a turn-timeout seat drop) and
|
||
`chat_messages_total` (`kind`=message/nudge); an observable gauge `game_cache_active`;
|
||
the gateway `edge_request_duration` (`message_type`/`result`); plus Go runtime/heap
|
||
metrics. Game-scoped metrics carry a **`variant`** attribute
|
||
(english/russian_scrabble/erudit — chosen over a coarser `language`, which it
|
||
subsumes); the gateway edge metric is variant-agnostic. Optional wiring uses the
|
||
established `SetMetrics`/`SetNotifier` setter pattern (default no-op meter), so existing
|
||
constructors and tests are untouched. **No speculative optimisation** — there is no
|
||
measured hotspot; the deliverable is the instrumentation (the standing "performance only
|
||
with evidence" rule). pprof was not added (reframed away by the owner).
|
||
- **Guest GC** (interview, TODO-3): age-based, no-seat-only — see the discharged TODO-3
|
||
below; new config `BACKEND_GUEST_REAP_INTERVAL`/`BACKEND_GUEST_RETENTION`.
|
||
- **Deps/CI**: new OTel modules (the OTLP exporters,
|
||
`contrib/instrumentation/runtime`, `otelgrpc`) added with the no-tidy pattern
|
||
(`go mod edit` + `go mod download` + `go work sync`; `pkg` carries no bare-path dep, so
|
||
it tidies cleanly). No workflow change — the Go workflows already span
|
||
`./backend/... ./gateway/... ./pkg/... ./platform/telegram/...`, integration stays
|
||
`./backend/...`, and the default `none` exporter keeps CI collector-free.
|
||
|
||
- **Stage 13** (interview + implementation, discharges TODO-4):
|
||
- **Scope = live play only** (interview): indices ride the wire for `StateView.rack`
|
||
(out) and `SubmitPlay`/`Evaluate`/`Exchange`/`CheckWord` (in). The **board path is
|
||
untouched** — `MoveRecord` (history, move results, hint), formed `words`,
|
||
`ComplaintRequest.word` (durable, admin-reviewed) and `WordCheckResult.word` (echo) stay
|
||
decoded concrete characters, so the durable journal / GCG and the §9.1 invariant are
|
||
unchanged. **Hard cutover**, no dual letter/index fields (single client; the fbs Go + TS
|
||
regenerate in one PR; no external wire consumer). Exchange moved fully to indices, a
|
||
blank = the shared sentinel index **255** (`engine.BlankIndex`).
|
||
- **Edge-mapping layering** (engineering): the engine gained a cached per-variant codec —
|
||
`AlphabetTable` (the `(index, letter, value)` table from the solver ruleset),
|
||
`LetterForIndex`, `EncodeRack`, `DecodeTiles`, `DecodeWord` — and the backend **server
|
||
edge** owns the index↔letter mapping. `game.Service`'s domain methods, `engine.Game` and
|
||
the **robot** keep a single **letter-based** play path (untouched); a new thin
|
||
`game.Service.GameVariant` (a single-column `SELECT variant`, cheaper than `GetGame`)
|
||
lets the inbound handlers resolve the variant without doubling the play-path read. The
|
||
**gateway carries no alphabet table** — it passes indices through verbatim; `check_word`
|
||
rides as repeated `?idx=` query params.
|
||
- **`include_alphabet` flag** (interview): `StateRequest.include_alphabet` gates the table
|
||
so it is not resent on every poll; the client sets it only on a **per-variant cache
|
||
miss** (first open of a variant), and the table then arrives with the index rack so the
|
||
rack is always decodable. The client caches the table in memory by variant
|
||
(`ui/src/lib/alphabet.ts`).
|
||
- **Letter case** (discovered): the solver emits **lower-case** letters and the rest of
|
||
the UI works in **upper case**. The wire and the journal stay lower case; the **UI
|
||
normalises display to upper case** (the codec upper-cases decoded board tiles and words,
|
||
and the alphabet cache upper-cases on ingest), so `placement.ts` / `board.ts` /
|
||
`checkword.ts` are unchanged and the latent real-backend lower-case display is fixed.
|
||
- **Parity rework** (interview): the real value/alphabet parity moved to a **Go engine
|
||
test** (`engine.AlphabetTable`: EN/RU/Эрудит sizes, EN a=1/q=10, **Эрудит ё=index 6,
|
||
value 0**); `ui/src/lib/premiums.ts` is now **geometry only** (its value tables,
|
||
`tileValue` and `alphabet` were removed, its parity test trimmed to the premium grid);
|
||
the codec test round-trips the index tiles + the alphabet table; the **mock keeps a
|
||
fixture table** (relocated from `premiums.ts`) seeded into the client cache, so the
|
||
mock-driven UI is alphabet-agnostic too.
|
||
- **Wire/codegen/CI**: new fbs `AlphabetEntry` + `PlayTile`; `StateView.rack`→`[ubyte]` +
|
||
`alphabet`; `StateRequest.include_alphabet`; `SubmitPlay`/`Eval` tiles→`[PlayTile]`;
|
||
`Exchange` tiles→`[ubyte]`; `CheckWord.word`→`[ubyte]` (committed Go + TS regenerated).
|
||
UI ~90 KB gzip JS (budget 100 KB). **No CI workflow change** — the Go workflows already
|
||
span `./backend/... ./gateway/... ./pkg/...` and the UI workflow runs check/unit/build +
|
||
a chromium/webkit e2e. `docs/FUNCTIONAL.md` is **untouched** (no user-visible behaviour
|
||
change — the UI looks and plays the same; like Stage 2). The index-drift caveat is
|
||
handled by construction (the running backend produces the table, so client↔server cannot
|
||
drift); the DAWG/solver build-time agreement remains **Stage 14 / TODO-2**.
|
||
|
||
- **Stage 14** (interview + implementation, re-scoped + discharges TODO-1/TODO-2):
|
||
- **Re-scoped to the split** (interview): the original "CI & deploy" was several sessions of work,
|
||
so it was cut to the **solver/dictionary split** (the dependency foundation) and the deploy +
|
||
observability + the dual-bot idea were written into the plan as new **Stages 15–18**. The deploy
|
||
decisions taken at the interview are recorded there (embed the UI in the gateway via `go:embed`;
|
||
full Collector+Prometheus+Tempo+Grafana stack; **two contours** — test = auto on feature-branch
|
||
push on the local host, prod = manual SSH `docker save`/`load` after merge; `TEST_`/`PROD_` secret
|
||
prefixes since Gitea 1.26 has no environments — verified).
|
||
- **TODO-1 — publish solver** (interview: "опубликовать и запинить"): `scrabble-solver` renamed to
|
||
module `gitea.iliadenisov.ru/developer/scrabble-solver`, `internal/{wordlist,dictdawg}`
|
||
**de-internalised** to public packages (so the dict repo imports one builder — no drift), the build
|
||
pipeline (`cmd/builddict`, `dictprep`, the `dictionaries` submodule) moved out, `internal/dict`
|
||
repointed at the committed `dawg/*.dawg` fixtures, tagged **v1.0.0**. scrabble-game pins it in
|
||
`backend/go.mod`, drops the `go.work` replace + the CI clone, and sets `GOPRIVATE=gitea.iliadenisov.ru/*`
|
||
(go fetches the module directly from Gitea — verified end-to-end). The solver hash lives in
|
||
`go.work.sum` (workspace mode; the bare-path `scrabble/pkg` replace still blocks `go mod tidy`).
|
||
- **TODO-2 — dictionary repo** (interview: "полный TODO-2, новый репо"): `developer/scrabble-dictionary`
|
||
builds the three DAWGs against the published solver + pinned `dafsa`/`alphabet` v1.1.0,
|
||
**byte-identical** to the solver fixtures; published as the release artifact
|
||
`scrabble-dawg-v1.0.0.tar.gz`; both Go workflows download it for `BACKEND_DICT_DIR` instead of
|
||
cloning the solver. English source vendored from `kamilmielnik/scrabble-dictionaries`; the Эрудит
|
||
fold is committed as `dictprep/russian/erudit.txt`, so the build needs no `python`.
|
||
- **Bootstrap nuances** (encountered): the dict repo was created empty with a protected `master`, so
|
||
it was seeded once via an owner-authorised protection lift→push→restore (a subsequent CI-fix push
|
||
correctly went through a PR, not another lift); it was made **public** (like the solver) so the Go
|
||
workflows fetch the artifact anonymously. Its CI is a **build-only** validation gate — the
|
||
auto-release step's `${{ github.* }}` contexts failed the Gitea workflow compile, so releases are
|
||
published manually for now (a logged follow-up).
|
||
|
||
- **Stage 15** (interview + implementation):
|
||
- **Re-framed service-agnostic** (interview): the owner kept the two-bots-in-one-container model but
|
||
generalised the language signal — the sign-in service returns a **set** of supported game languages
|
||
(subset of `{en, ru}`, ≥ 1) on the validate response, and the **UI gates** the New Game variant choice
|
||
by it. Two distinct scopes, deliberately not conflated: the **gating set** is per-session (rides the
|
||
`Session` fbs, never persisted — so the same `telegram_id` logged in through the en- and ru-bot gates
|
||
differently, which is correct), and the **routing language** is per-account.
|
||
- **Push routing resolved** (interview, the original "which bot delivers" open detail): only the
|
||
**user-facing `Notify`** carries the `en`/`ru` language from the user's **last `ValidateInitData`**,
|
||
persisted as `accounts.service_language` (migration `00010`, written every login — new and existing —
|
||
last-login-wins, read by `/internal/push-target` with a `preferred_language` fallback). It is NOT the
|
||
game's variant language. **Correction mid-interview:** the admin broadcasts `SendToUser` /
|
||
`SendToGameChannel` are admin-panel-only and unrelated to `ValidateInitData`; they pick the bot by an
|
||
**operator-chosen** language (a console `<select>`), so a `language` field was added to those two RPCs
|
||
sourced from the form, not from `service_language`.
|
||
- **Gating = UI-only, creation-only** (interview): the backend does not enforce (a valid game is
|
||
harmless, not a trust boundary); only the New Game pickers (auto-match + friend invite) filter — there
|
||
is no variant picker on accept/open/play, so those are inherently ungated. Non-Telegram logins
|
||
(web/email/guest) carry the gateway default set (`GATEWAY_DEFAULT_SUPPORTED_LANGUAGES`, default all).
|
||
- **Wire/connector**: `ValidateInitDataResponse` gained `service_language` + `supported_languages`; the
|
||
fbs `Session` gained `supported_languages:[string]`; `SendToUser`/`SendToGameChannel` gained
|
||
`language` (committed Go + TS regenerated via `make -C pkg gen` + `pnpm -C ui codegen`). The connector
|
||
config moved to **per-language** bots (`TELEGRAM_BOT_TOKEN_EN/_RU`, `TELEGRAM_GAME_CHANNEL_ID_EN/_RU`;
|
||
`TELEGRAM_MINIAPP_URL` shared; ≥ 1 token required — a breaking config change, no prod yet); the
|
||
server hosts a bot map and routes by language. The push template language now follows the routing bot
|
||
(was `preferred_language`) — a documented change. The deploy compose/Dockerfile env was updated to the
|
||
per-language vars (the full deploy stack is Stage 16). No CI workflow change (the Go and UI workflows
|
||
already span the touched modules).
|
||
|
||
- **Stage 16** (interview + implementation):
|
||
- **Branch model reshaped** (interview, supersedes the Stage 0 `feature/* → master`): a long-lived
|
||
**`development`** integration branch + **`master`** as the prod trunk. Feature branches are cut from
|
||
`development`; a feature-branch commit triggers nothing. A single consolidated
|
||
`.gitea/workflows/ci.yaml` (Gitea has no cross-workflow `needs`) runs `unit`+`integration`+`ui` on a PR
|
||
into `development`/`master` and a **gated `deploy`** job (`needs` the three) that auto-rolls the test
|
||
contour **on a PR into — or a push to — `development`** (owner's "и PR, и push"). A PR into `master` is
|
||
test-only; prod is the manual Stage 18. The former `go-unit`/`integration`/`ui-test` workflows were
|
||
folded in (no path filters — full CI on every PR, per the owner). Console kept plain (`NO_COLOR`,
|
||
`docker compose --ansi never`, `--progress plain`).
|
||
- **Gateway serves the UI** (interview, the §13 single-origin): a new `gateway/internal/webui` embeds
|
||
`dist` via `go:embed` (a committed placeholder index so `go build`/CI compile without a UI build) and
|
||
serves the SPA at `/` and `/telegram/` (a path-stripping SPA handler, index.html fallback for the hash
|
||
router), mounted in the edge mux **below** the h2c wrap; `/_gm` stays an explicit 404 when the local
|
||
admin proxy is off so the catch-all does not leak the shell. The `gateway/Dockerfile` node stage builds
|
||
the UI with the `VITE_*` build-args and copies it into the embed dir before `go build`.
|
||
- **Images** (interview): multi-stage distroless `backend/Dockerfile` (a DAWG stage `curl`s the
|
||
`scrabble-dawg` release pinned to `DICT_VERSION`, `GOPRIVATE` fetches the solver) and `gateway/Dockerfile`
|
||
(node UI stage + Go stage), both trimming `go.work` like `platform/telegram/Dockerfile`. Built and
|
||
verified locally.
|
||
- **Contour = caddy-fronted** (interview, "caddy всё равно нужен для https"): a new `caddy` service owns
|
||
a **single `/_gm` Basic-Auth** and routes `/_gm/grafana/*` → Grafana (anonymous-admin + sub-path, no
|
||
own accounts) and the rest of `/_gm/*` → the backend console; everything else → the gateway. This
|
||
**supersedes Stage 10's** gateway-fronts-`/_gm` model **in the deploy topology** (the gateway's own
|
||
`/_gm` proxy stays for a local non-caddy run). TLS: the **host caddy** terminates it for the test
|
||
contour and forwards to `scrabble:80`; the in-compose caddy is parameterised (`CADDY_SITE_ADDRESS`) to
|
||
own ACME on prod (Stage 18) where there is no host caddy.
|
||
- **Networks** (engineering): inter-service traffic on a private `internal` network (project-scoped DNS,
|
||
no name collisions on the shared `edge`); only caddy joins the external `edge` (alias `scrabble`). The
|
||
connector keeps its VPN sidecar (the only egress that needs the tunnel). The connector-scoped
|
||
`platform/telegram/deploy/docker-compose.yml` was **retired** (the root `deploy/docker-compose.yml`
|
||
supersedes it; the connector Dockerfile stays).
|
||
- **Observability stack** (interview): OTel Collector (OTLP/gRPC → a Prometheus scrape endpoint +
|
||
Tempo OTLP) + Prometheus (**15d**) + Tempo (**72h**) + Grafana (provisioned Prometheus+Tempo datasources
|
||
+ four dashboards: Service overview, Edge/UX, Game domain, Users; Traces via the Tempo datasource +
|
||
Explore, no fixed panels). The collector's prometheus exporter uses `add_metric_suffixes:false` +
|
||
`resource_to_telemetry_conversion` so the dashboards' PromQL matches the in-code metric names and carries
|
||
`service_name`. The three services export `otlp` in the contour (default stays `none`, so CI needs no
|
||
collector). Loki/logs were left out of scope (container stdout / zap JSON).
|
||
- **User metrics** (interview): a backend `accounts_created_total{kind}` counter (telegram/email/guest;
|
||
robots excluded — they are a provisioned pool, not users) via the Stage-12 `SetMetrics` no-op pattern,
|
||
and a gateway **in-memory** `active_users{window=24h,7d}` observable gauge (distinct authenticated edge
|
||
actors). The owner chose the in-memory gauge over a DB `last_seen_at` (overkill); its single-instance /
|
||
reset-on-restart limits are documented (a live gauge, not billing).
|
||
- **Owner actions before the contour is green** (surfaced, not blockers): set the **`TEST_`** Gitea
|
||
secrets/variables (see `deploy/.env.example`) and add a host-caddy route `<test domain> → scrabble:80`
|
||
on the runner host. CI bootstrap nuance: the first PR introducing `ci.yaml` may first deploy on the
|
||
post-merge push to `development` (depending on whether Gitea runs head/base workflows for a PR), after
|
||
which PR-time deploys work.
|
||
- **Telegram test environment** (post-deploy fix): the connector now selects Telegram's test env with the
|
||
library's native `tgbot.UseTestEnvironment()` (was a `token += "/test"` hack — functionally identical,
|
||
verified, but the option is idiomatic and now has a `bot` test asserting the `/bot<token>/test/getMe`
|
||
path). The test contour **pins `TELEGRAM_TEST_ENV=true` in `ci.yaml`** (the contour is the test
|
||
environment) rather than via a `TEST_`-prefixed variable — removing a confusing double-`TEST` operator
|
||
knob and the secret-vs-variable footgun; prod (Stage 18) leaves it `false`.
|
||
|
||
- **Stage 17** (interview + implementation): the test-contour verification pass. The owner's
|
||
collected caveats were classified (fix-now / verify-then-fix / discuss) and resolved in one session.
|
||
- **Russian Scrabble fixed** (#6): the UI sent the variant id `russian` while the backend's canonical
|
||
string (and `StateView`) is `russian_scrabble`, so `lobby.enqueue`/invite returned 400 (confirmed in
|
||
the contour logs). The UI was aligned to `russian_scrabble` (the `Variant` type, `variants.ts`,
|
||
`Lobby.svelte`, mock fixtures, premium/alphabet keys, tests); the backend label is unchanged
|
||
(persisted games, GCG and the `variant` metric attribute keep it).
|
||
- **Nudge message** (#3): `social.ErrNudgeOnOwnTurn` shared the `not_your_turn` result code with
|
||
`game.ErrNotYourTurn`, so nudging on your own turn read "it is not your turn" — backwards. A distinct
|
||
`nudge_own_turn` code + i18n message was added, and the UI disables the nudge control on your own turn.
|
||
- **Connector name sanitization** (#2): `account.ProvisionTelegram` now cleans the platform name to the
|
||
editable display-name format (`sanitizeDisplayName`) and falls back to `Player`/`Игрок-NNNNN` (by
|
||
language) when nothing remains. A new `account.ProvisionRobot` lets system robot names bypass editor
|
||
validation (e.g. "Peter J.").
|
||
- **Robot names** (#5, interview): per-language composed pools — 32 full + 32 colloquial first names
|
||
paired by index, plus a surname pool (gender-agreed for Russian) rendered in three forms (first only /
|
||
first + surname initial / first + full surname), composed deterministically per pool slot (stable
|
||
across restarts). `Pick(variant)` is variant-aware: a Russian game draws Russian names with ≤ ~20%
|
||
Latin, an English game the Latin pool. Robot identities are keyed `robot-<lang>-<index>`.
|
||
- **Robot timing** (#4, interview): the fixed `2 + 88·u^3.5` move delay became move-number-aware — the
|
||
band interpolates from [3,10] min at the first move (raised from [1,5] in round 4, #14) to [10,90] min
|
||
by ~28 moves, right-skewed by k=4, so early moves are quick and the endgame can be long. A daytime
|
||
nudge pulls the reply toward the move's lower band.
|
||
- **Multi-device push** (#7, interview): `emitMove` no longer skips the acting seat, so the mover's own
|
||
other devices (and their lobby) refresh. `opponent_moved` stays in-app only (no out-of-app push to the
|
||
actor), and the gateway already fans each event out to all of a user's live streams.
|
||
- **Move-duration analytics** (#1, interview): a live `game_move_duration{variant,phase}` histogram
|
||
(opening/middle/endgame) + a Grafana panel, plus offline per-user analytics in the admin console —
|
||
min/avg/max columns in the user list and an inline-SVG chart of think-time by the player's move number,
|
||
computed from the journal (`game_moves.created_at` deltas; no schema change). Per-user stays offline,
|
||
not a Prometheus label, to avoid cardinality blow-up; the live histogram aggregates all seats (robots
|
||
included), so the per-human admin view is authoritative.
|
||
- **CI** (#9/#10, interview): `unit`/`integration`/`ui` are path-conditional behind a `changes` job; an
|
||
always-running `gate` job aggregates them (success-or-skipped) and is the single branch-protection
|
||
required check (`CI / gate`), so a skipped job never blocks a merge. The deploy job gained a
|
||
Telegram-connector liveness probe (`docker inspect`: running, not restarting, stable restart count,
|
||
with a VPN-handshake grace period) — closing the Stage 16 blind spot where a crash-looping connector
|
||
was invisible to the gateway-only probe.
|
||
- **UI theming / UX**: inside Telegram the colour scheme is forced from `WebApp.colorScheme` over the OS
|
||
`prefers-color-scheme` (fixes the Telegram Desktop breakage, #12) and the theme switcher is hidden
|
||
(#11); the nav bar takes Telegram's bg and the announcement banner a subtle `--ad-bg` accent (#14/#15);
|
||
the reconnect banner is suppressed while backgrounded and the stream reconnects on return (#16); hint
|
||
zoom scrolls to the placement (#17); the players plaque raises the active seat and sinks the others
|
||
with a tap toggling history (#19/#20); history fixes the word-column jitter and pins its bottom shadow
|
||
to the board (#21/#23); directional screen-slide transitions (#18a); a per-game in-memory cache renders
|
||
instantly on re-entry and refreshes in the background (#13).
|
||
- **Grafana repeated password (#8) — not a server defect**: verified live that caddy challenges `/_gm`
|
||
and `/_gm/grafana` with one identical realm and Grafana serves anonymously, so the repeated prompt is a
|
||
browser Basic-Auth scoping quirk (likely Safari/Desktop), not infra — left for the owner to re-verify,
|
||
no server change. **Multi-word history (#22)** was already implemented (all formed words shown).
|
||
- **Contour-verification follow-ups** (rounds 2–3, from live testing): the Grafana
|
||
double-password was its **Live WebSocket** tripping caddy Basic-Auth — Grafana Live is
|
||
disabled (`GF_LIVE_MAX_CONNECTIONS=0`) and the admin console links to Grafana; the
|
||
move-duration panel was invisible because the deploy reseed (`rm -rf`) left the
|
||
config-only services on a stale bind mount — the deploy now **force-recreates**
|
||
caddy/otelcol/prometheus/tempo/grafana; the **per-user rate limit** was raised 120/40 →
|
||
300/80 and the UI no longer reloads on the echo of its own move; the iOS/Telegram
|
||
reconnect banner gained a resume **grace window** (visibilitychange + pageshow/pagehide
|
||
+ Telegram `activated`/`deactivated`); **Telegram Mini Apps polish** was adopted —
|
||
chrome colours (`setHeaderColor`/`setBackgroundColor`/`setBottomBarColor`), native
|
||
**BackButton**, **HapticFeedback**, **closing confirmation** in a game,
|
||
**disableVerticalSwipes**; the players-plaque highlight was inverted so the active seat
|
||
pops; the make-move popover became a direct **✅** with a tab-bar **↩️ Reset**; the hint
|
||
button disables at zero hints; plus **board-only vertical scroll** (#9) and a
|
||
**keyboard-overlay** check-word dialog (#10).
|
||
- **Contour-verification follow-ups** (round 4, from live testing): the robot early-move band was raised
|
||
[1,5] → [3,10] min so openings are less hasty (#14); the **profile** is edited inline (the Edit/Cancel
|
||
toggle is gone, the form is always shown for durable accounts, hint balance stays read-only) and a
|
||
single trailing "." is allowed in display names (#5/#6); a pending tile now recalls by **double-tap**
|
||
or by **dragging it back onto the rack** (single-tap recall removed), and **holding a dragged tile over
|
||
a cell ~1 s auto-zooms** there (#3/#10); **🔀 Shuffle is animated** — tiles hop along a low parabola to
|
||
their new slots, duration scaled by distance, with a haptic shake (#9); a **lines-off board** Settings
|
||
toggle (default off) renders a gapless checkerboard with rounded, right-shadowed tiles, reclaiming
|
||
~14px of width (#12). **Deferred (discussed):** board **pinch zoom** (#2) — it fights both the native
|
||
scroll and the new one-finger drag-back, so it stays dropped in favour of double-tap + hover-hold zoom;
|
||
**robot win% in the admin game detail** (#16) — needs the seed-derived play-to-win decision exposed
|
||
across the game/robot package boundary, to be picked up when that seam is added.
|
||
- **Contour-verification follow-ups** (round 5, from live testing): **resign on the opponent's turn**
|
||
now works — the engine gained `ResignSeat(seat)` and `game.Resign` bypasses the turn check to forfeit
|
||
the actor's own seat (it no longer returned "not your turn"); **quick-match cancel** was a UI no-op
|
||
(only stopped polling) — added the full path (REST `/lobby/cancel` → gateway → client) and clear the
|
||
matchmaker's pending result on cancel, so a cancelled search is dequeued (no "already queued", no later
|
||
robot-substituted game); **lobby win/loss** ranked by score, so a 0-0 resignation read as a win —
|
||
`result.ts` now places the viewer below the winner (rank ≥ 2), matching the game detail; a **friend
|
||
request to a robot** is accepted as pending and expires like a human ignore (robots no longer set
|
||
`BlockFriendRequests`); the **nudge cooldown** error got its own `nudge_too_soon` code/message and the
|
||
chat button disables for the hour, with the note reworded to "Waiting for your move!". UI polish:
|
||
**even zoom** (interpolate the scroll toward a pre-clamped target as the real width grows/shrinks — no
|
||
lurch-and-snap) that **recentres only on the first zoom-in**; a drag **drop-target highlight**; **pinch
|
||
zoom** (two-finger, preventDefault only on two touches; a second finger aborts a drag); shuffle hop
|
||
capped at **0.3 s** and off under reduce-motion; a **borderless** make-move icon, disabled on a known-
|
||
illegal pending word; **variant display names** (english & russian_scrabble → Scrabble/Скрэббл, erudit
|
||
→ Erudite/Эрудит) shown on the create-game controls and the in-game title. **L2 done:** the admin game
|
||
card now shows each robot seat's per-game play-to-win **intent** + the ~40% target and, on the robot's
|
||
turn, its deterministic **next-move ETA**. *Open edge:* a bilingual New Game (both en+ru offered) would
|
||
show two "Scrabble" buttons — left as the owner's chosen naming; disambiguate if it bites.
|
||
- **Contour-verification follow-ups** (round 6, from live testing) — **shipped & deployed:** profile drops
|
||
the hint-balance line; no mobile tap-flash on a board cell (`-webkit-tap-highlight-color`); variant
|
||
display names keyed by the game's **alphabet**, not the UI language (english → "Scrabble",
|
||
russian_scrabble → "Скрэббл", both unlocalized so they never collide; erudit localized), and the in-game
|
||
title shows the variant name; **chat & nudge are mutually exclusive by turn** (message field on your
|
||
turn, nudge on the opponent's, grey "awaiting reply" caption during the cooldown), with chat enforced
|
||
server-side to your own turn (`ErrChatNotYourTurn`); the **nudge cooldown resets** once the player has
|
||
moved or chatted since the last nudge (`game.LastMoveAt` + last chat vs last nudge; the UI mirrors it);
|
||
the **About** screen got localized titles + a rules link + the random/friends sections, and the app
|
||
**version comes from `git describe`** (Vite define `__APP_VERSION__` ← Docker build-arg in the deploy
|
||
step, default "dev"); the **quick-game buttons** became lobby-style plaques — name + flag (🇺🇸/🇷🇺 + a
|
||
bundled minimalist USSR-flag SVG) + a one-line rules summary (bag size, the ё rule, bonus differences
|
||
from the engine rulesets) + the 24h move-limit beneath; two follow-up fixes (pin the nudge right when
|
||
available; redraw the USSR emblem as a thin schematic hammer & sickle); **#3 drag-reorder of rack tiles**
|
||
with a visual gap (the dragged tile lifts out, the rest slide to open a slot; `reorderIndices`
|
||
unit-tested; only with no pending tiles); and the **persistence backend foundation** (#4/#5/#6): a
|
||
`game_drafts` table (migration 00011) + raw-SQL store/service (`GetDraft`/`SaveDraft`) that, on every
|
||
committed move, clears the actor's own draft and resets any opponent's board draft whose cell the play
|
||
overlapped — 5 integration tests.
|
||
- **Stage 17 round 6 — final pass (#4/#5/#6 + #16–20), shipped:**
|
||
1. **Draft persistence — gateway slice + UI (#4/#5/#6, PR #20).** FB `DraftRequest{game_id, json}`
|
||
(save) + `DraftView{json}` (get reuses `GameActionRequest`); the client serializes
|
||
`{rack_order, board_tiles}` itself (no FB tile array), the gateway forwards it as `json.RawMessage`
|
||
both ways (no double-encode), and `GET`/`PUT /games/:id/draft` (a server `draftDTO` ↔ `game.Draft`)
|
||
is the only place that reads the shape. UI: debounced save of the rack order (#4) + board draft (#6)
|
||
and restore on load (`lib/draft.ts`, reconciling against the committed board); **#5** — tiles may be
|
||
arranged on the opponent's turn (placement relaxed; the preview and Make-move stay your-turn-only,
|
||
so an off-turn draft is position-only). Off-turn tiles keep the **existing pending highlight** — no
|
||
caption, no new style (owner's call). The backend draft endpoint is sub-ms.
|
||
2. **Landing + `/app/` move (#16–20, this PR).** One Vite build with **two HTML entries** — the game
|
||
SPA (`index.html`) and a new lightweight landing (`landing.html` → `Landing.svelte`, reusing the
|
||
theme/i18n/`aboutContent` leaf modules, not the app store, so it stays small). The gateway serves the
|
||
**landing at `/`** and the **game SPA at `/app/` and `/telegram/`** (`webui.Handler(stripPrefix,
|
||
indexName)`); relative base keeps one build serving every mount with a shared `dist/assets/` (the
|
||
planned per-target `base` conditional proved unnecessary). **Correction to the original note:** the
|
||
Telegram **Mini App stays at `/telegram/`** — only the plain web app moved off `/` to `/app/`, so
|
||
BotFather is untouched. The landing's "Play in Telegram" link is **per-language** via two new build
|
||
vars `VITE_TELEGRAM_LINK_EN` / `VITE_TELEGRAM_LINK_RU` (test/prod bots differ → no hardcoding; the
|
||
button hides when unset). Logo copied `.claude/telegram-logo.svg` → `ui/public/` (source stays
|
||
untracked).
|
||
- **Edge robustness (folded into the landing PR).** (a) **Static cache headers** — the embedded
|
||
`http.FileServer` over `go:embed` has a zero modtime, so it emitted no validators → the client
|
||
re-downloaded the whole bundle every launch; now hash-named `/assets/*` are `immutable` (a relaunch
|
||
is a cache hit) and the HTML shells are `no-cache`. (b) **Live-stream 15 s abort** — the `Subscribe`
|
||
heartbeat only fired after the first 15 s tick, so the stream sat silent and raced a ~15 s edge idle
|
||
timeout (constant reconnects in the caddy log); now an **immediate heartbeat on open** + a **10 s**
|
||
default interval. Both surfaced while diagnosing a reported "slow load in Telegram" that was actually
|
||
the owner's **external network** (the server is sub-ms end-to-end) — not a regression.
|
||
- **Landing follow-up (owner review pass):** reworked from the first cut — the per-language Telegram
|
||
link var renamed `VITE_TELEGRAM_LINK_EN/_RU` → **`VITE_TELEGRAM_GAME_CHANNEL_NAME_EN/_RU`** (it carries
|
||
a channel **username**, the landing builds `https://t.me/<name>`; the connector keeps the matching
|
||
`..._CHANNEL_ID_..` to post). Switchers became icons — a 🌐 language dropdown (saved, synced to the app)
|
||
and a ☼/☾ theme toggle that is **ephemeral** (follows the system scheme, never persisted, no "auto").
|
||
The "Play in browser" CTA was dropped (no standalone-web onboarding yet).
|
||
- **Game/Telegram review-pass polish:** the USSR flag emblem redrawn (canonical hammer & sickle,
|
||
scaled down ×1.5 below the star, the star itself +25%); touch drag enlarges the drag ghost ×1.5
|
||
(touch only — the finger hides the tile) and suppresses the iOS tap-highlight that lingered on a
|
||
rack tile sliding into a dragged tile's slot; a placed tile can be **dragged to another board
|
||
cell** (it lifts off its origin for the drag, and `touch-action:none` lets the drag win over the
|
||
board pan when zoomed) and the manual-select ring clears when a tile is recalled; and **Telegram
|
||
fullscreen** no longer hides our header under its native nav — the whole header drops below the
|
||
content-safe-area top inset (title and the right-aligned menu both clear the nav), via
|
||
`--tg-content-top` from the SDK + a `tg-fullscreen` class. (Telegram's Mini App SDK exposes no way
|
||
to set the native nav-bar title, move its buttons, or add items to its "⋯" menu, so we keep our
|
||
own header and simply push it clear.)
|
||
- **Lobby sort + in-game friend state (review pass, PR C):** the **my-games** lobby now groups games
|
||
into *your turn* / *opponent's turn* / *finished* (empty sections hidden) and orders them by last
|
||
activity — your-turn oldest-first (the longest-waiting on top), the other two newest-first — in a
|
||
compact, line-separated list (the owner's density pick over bordered cards). `gameDTO` / FB
|
||
`GameView` gained `last_activity_unix` (the turn start while active, the finish time once
|
||
finished). The in-game **"add to friends"** item is now **server-derived** (new `GET
|
||
/user/friends/outgoing` + `friends.outgoing` op, returning the addressees already requested —
|
||
pending **or** declined, which both read as "request sent") so it is correct across reloads, shows
|
||
a disabled **"✓ in friends"** once accepted, and **live-updates** when the opponent answers:
|
||
`RespondFriendRequest` now publishes `friend_added` (accept) / `friend_declined` (a new notify
|
||
sub-kind, decline) to the **original requester**, whose open game re-derives its friend state.
|
||
Owner decisions: a declined request stays "request sent" (non-revealing); an accepted opponent
|
||
reads "✓ in friends"; rack-tile reorder while tiles are placed stays disabled by design.
|
||
- **Admin "Messages" moderation section (#18, PR D):** a new `/_gm/messages` console page lists
|
||
posted chat messages (**nudges excluded**) newest-first — time · **source** (guest / robot /
|
||
oldest identity kind) · sender (→ user card) · IP · body · game (→ game card) — searchable by
|
||
sender name / external-id glob masks and pinnable to one game (`?game=`) or sender (`?user=`),
|
||
linked from the game and user cards. Server-rendered (`adminconsole` `MessagesView` +
|
||
`messages.gohtml`, 50/page via the shared pager); the list query lives in `social` (raw SQL,
|
||
`kind='message'`, the source via a SQL `CASE`), reusing the now-exported `account.LikePattern`
|
||
glob helper. Owner decisions: messages only (no nudges), separate name/ext masks (matching the
|
||
Users section), a top-level nav entry plus the card deep-links.
|
||
- **Round-6 follow-up — UX polish + client-IP fix (this PR):**
|
||
- **Client IP through the edge.** The compose caddy now sets `trusted_proxies static
|
||
private_ranges`, so the real client IP survives the host-caddy hop (it was logging the
|
||
docker-network caddy hop `172.18.0.x` for chat moderation, and bucketing the gateway's
|
||
per-IP rate limiter on it). Correct + spoof-safe in **both** contours (prod has no host
|
||
caddy → public clients untrusted → real peer used). `peerIP` unit-tested.
|
||
- **Ad banner** gated **off** behind a compile-time `SHOW_AD_BANNER=false` in `Screen.svelte`
|
||
— the `{#if}` branch, the `AdBanner` import and `banner.ts` are tree-shaken out of the prod
|
||
bundle (code kept for post-release polish).
|
||
- **Landing** Telegram entry is now just the **64px logo** (clickable, no button/caption).
|
||
- **TG-fullscreen header** reworked again: title + menu are one **centred pair** (hamburger
|
||
right of the title) pinned to the **bottom** of the TG nav band, lining up with Telegram's
|
||
own controls.
|
||
- **Edge-swipe back** (`Screen.svelte`): a left-edge rightward drag navigates to `back`
|
||
(touch/pen only, armed only from ≤24px so it never fights the board's gestures; skipped
|
||
inside Telegram, which has its own back).
|
||
- **Chat + word-check are now their own routed screens** (`/game/:id/chat`,
|
||
`/game/:id/check`, header back to the game, no tab-bar) so the soft keyboard simply resizes
|
||
the **visible viewport** — mirrored into a `--vvh` CSS var the `Screen` height uses, since
|
||
iOS doesn't shrink `dvh` for the keyboard — with the input pinned to the bottom: no modal
|
||
relayout, no page jump (this superseded a first bottom-sheet-`Modal` attempt). New chat
|
||
messages raise an **unread badge** on the in-game hamburger + the Chat menu row (per game,
|
||
cleared on open), mirroring the lobby badge; the chat screen is routable for a future
|
||
Telegram deep-link. The TG-fullscreen header was also finalised over a couple of review
|
||
passes: title + menu as a centred pair inside Telegram's nav band (between `--tg-safe-top`
|
||
and `--tg-content-top`), with a small padding bump so the native controls aren't flush.
|
||
- **Tests backfilled** for the merged round-6 work: e2e for the in-game "✓ in friends" item
|
||
and a board→board tile relocation; codec units for `last_activity_unix` + `OutgoingRequestList`.
|
||
- **Hide finished games (#5, shipped):** a player can remove a finished game from their own
|
||
*my games* list — **per-account, finished-only and irreversible** (the game stays for the
|
||
other players; there is no un-hide). On a finished row a **swipe-left** (touch) or a tap on
|
||
its **kebab ⋮** (the desktop affordance) reveals a **❌** that hides it; active rows carry an
|
||
inert **›** chevron purely to keep the right-edge icons aligned. New table
|
||
`game_hidden(account_id, game_id)` + migration `00012`; `ListGamesForAccount` filters the
|
||
hidden set; `POST /api/v1/user/games/:id/hide` behind the `game.hide` edge op (reusing
|
||
`GameActionRequest` → an `Ack`); the lobby drops the card optimistically and keeps the cache
|
||
in sync. Covered by an integration test (active→`ErrGameActive`, outsider→`ErrNotAPlayer`,
|
||
per-account visibility, idempotent), a gateway transcode test, and a mock e2e (kebab → ❌).
|
||
- **Enriched out-of-app push (#4, shipped):** the "your turn" Telegram notification now names
|
||
the opponent and recaps their last move — voiced as the opponent, `«{name}: my move —
|
||
«WORD». Score 120:95»` for a scoring play, or a short "swapped / passed, your turn" — and a
|
||
new **game-over** notification reports the result + final score when a game ends (any path:
|
||
closing play, all-pass, resign, timeout). Scores are **recipient-first** (the reader's
|
||
score leads), 2- to 4-player (`120:95:80`). `YourTurnEvent` gained `opponent_name`/
|
||
`last_action`/`last_word`/`score_line` (appended, backward-compatible) and a new
|
||
`GameOverEvent` carries `result`/`score_line`; both emit per-recipient from the game commit
|
||
(`emitMove`), join the out-of-app whitelist, and render per language (en/ru) in the Telegram
|
||
connector. The backend resolves the mover's display name (the score line and result are
|
||
built per recipient). Covered by notify round-trip, emit, connector-render (en/ru) and
|
||
routing tests.
|
||
- **No-op drain of all bot updates (#1, investigated — no change):** confirmed the Telegram bot
|
||
already long-polls and the library advances the offset for every delivered update (the default
|
||
handler no-ops anything but `/start`), so the queue never piles up. Telegram withholds only
|
||
`message_reaction` / `message_reaction_count` / `chat_member` by default, and — being
|
||
unrequested — those never queue either. Owner chose to leave `allowed_updates` at the default
|
||
(zero risk) rather than hand-maintain a full whitelist (a wrong/stale type would break
|
||
`getUpdates` entirely); a specific type will be requested when a concrete handler needs it.
|
||
- **Reconnect UX — "Connecting…" + soft-disable (#2, shipped):** connectivity failures became
|
||
**state, not toasts**. A global `online` signal (`lib/connection.svelte.ts`) flips on a
|
||
transport `unavailable` / `rate_limited` (and on the live stream's drop), driving a pure-CSS
|
||
header **spinner + "Connecting…"** in place of the title and softly disabling the in-game
|
||
server actions (commit / exchange / pass / hint; local board/rack/reset stay live). The
|
||
transport (`exec`) **auto-retries with capped backoff** — every op on a rate-limit, **reads
|
||
only** on `unavailable` (mutations are not blindly re-sent; their buttons are disabled while
|
||
offline, so the player re-issues on reconnect — the idempotency caveat the owner accepted). A
|
||
reachability **watcher** (`profile.get` probe) and any successful traffic clear the signal; the
|
||
old red `error.unavailable` toast is gone (the indicator replaces it). A server-data screen
|
||
still **opens with the spinner** and fills on reconnect (global indicator + read auto-retry),
|
||
so navigation is never dead. Pure policy unit-tested (`retry.ts`); a mock-only `window.__conn`
|
||
hook drives a Chromium+WebKit e2e (indicator appears offline, the action disables, both clear
|
||
on reconnect). The visual soft-disable spans the server-action buttons across the app: the
|
||
game bar (commit/exchange/pass/hint/resign), chat send + nudge, profile save / link / merge,
|
||
friends (request/respond/unfriend/block/code), New Game (auto-match + invite) and the lobby
|
||
hide ❌; purely local controls (board/rack/reset, menu, navigation, settings) stay live.
|
||
- **Nudge defects (owner-reported, shipped):** two from a live contour game.
|
||
**(A) Frequency** — the robot's proactive nudge fired hourly for 12 h+ (12 h idle threshold +
|
||
the 1 h cooldown, uncapped). Replaced with a **lengthening, randomized schedule** in the
|
||
robot strategy/driver: the first nudge ~60-90 min into the human's turn, each later gap
|
||
growing toward 1-6 h (the gap is a uniform sample in `[60 min, ceil]`, `ceil` ramping from
|
||
90 min to 6 h over 12 h of idle, measured from the previous nudge), so a long wait gets a
|
||
handful of increasingly-spaced reminders. **(B) Language** — the out-of-app push routed by
|
||
the recipient's **global `service_language`** (last-login-wins), so after re-logging through
|
||
the RU bot an English game's nudges came from the RU bot. Now a game push (your_turn,
|
||
game_over, nudge, match_found) carries the **game's own language** (`engine.Variant.Language`)
|
||
on `push.Event`, and the gateway routes by it (falling back to `service_language` for
|
||
non-game pushes); the New-Game variant-gating guarantees deliverability. Covered by the
|
||
`proactiveNudgeGap` unit test, the retimed `TestRobotProactiveNudge`, `TestVariantLanguage`,
|
||
emit (`your_turn`/`game_over` language) and a `TestNudgeRoutedByGameLanguage` integration test.
|
||
|
||
### Stage 19 — user feedback
|
||
- Dropped the planned `feedback_messages.attachment_type` column: the safe content-type is derived from the
|
||
file-name extension at both validate and serve time (one source of truth), so a stored column was
|
||
redundant.
|
||
- The admin filter is **three-way** (Непрочитанные / Прочитанные / Архив) rather than the two first
|
||
sketched, mirroring complaints' `open·resolved·all`, so a read-but-unarchived message is never
|
||
unreachable (owner-approved at planning).
|
||
- The guest gate was extended to the **gateway** at the owner's request: a new `Op.NonGuest` flag plus
|
||
`is_guest` threaded through the session resolve + gateway cache reject a guest's `feedback.submit` with
|
||
the `guest_forbidden` result code before any backend call (the backend keeps its own guest check as the
|
||
backstop). `handleResolveSession` now loads the account best-effort to report `is_guest` (a read error
|
||
falls back to false so the auth hot path stays resilient).
|
||
|
||
## Deferred TODOs (cross-stage)
|
||
|
||
- ~~**TODO-1 — publish & version the solver.**~~ **Done in Stage 14.** `scrabble-solver` is
|
||
published as module `gitea.iliadenisov.ru/developer/scrabble-solver` (tagged `v1.0.0`, with
|
||
`wordlist`/`dictdawg` de-internalised to public packages); `backend/go.mod` pins it, the `go.work`
|
||
replace and the CI sibling-clone are gone, and `GOPRIVATE=gitea.iliadenisov.ru/*` fetches it directly
|
||
(no public proxy/checksum DB). Removes the floating `master` dependency accepted since Stage 2.
|
||
- ~~**TODO-2 — split the solver into engine vs dictionary generator + versioned dictionary
|
||
artifacts.**~~ **Done in Stage 14.** A new repo `developer/scrabble-dictionary` holds the word-list
|
||
sources + `cmd/builddict` (moved out of the solver, with `dictprep` and the `dictionaries` submodule)
|
||
and builds the three DAWGs against the **published solver + pinned `dafsa`/`alphabet` v1.1.0** — the
|
||
output is **byte-identical** to the solver's committed fixtures, so the index-drift caveat is handled
|
||
by construction. Delivered as a Gitea **release artifact** `scrabble-dawg-vX.Y.Z.tar.gz` (not
|
||
`go get`; DAWGs are data; **one semver label for the whole set**); the Go workflows download it for
|
||
`BACKEND_DICT_DIR`. The runtime dynamic-reload contract (per-version `BACKEND_DICT_DIR/<version>/` via
|
||
`Registry.LoadAvailable` / `engine.OpenWithVersions`, Stage 10) is unchanged — a deploy drops a new
|
||
set into the directory; a version is safe to retire once no active game pins it.
|
||
- ~~**TODO-3 — garbage-collect abandoned guest accounts.**~~ **Done in Stage 12.**
|
||
A periodic `account.GuestReaper` deletes guests (`is_guest`) **with no game seat at
|
||
all** whose account age exceeds `BACKEND_GUEST_RETENTION` (default 30 d, swept every
|
||
`BACKEND_GUEST_REAP_INTERVAL`, default 1 h). Two schema facts shaped this, narrowing
|
||
the original sketch: (1) `game_players`/`chat_messages`/`complaints` reference accounts
|
||
**without** `ON DELETE CASCADE`, and a finished game belongs to the other players'
|
||
history, so a guest with any seat is retained (a delete would be blocked anyway) — hence
|
||
"no seat", not "no active game"; (2) sessions are revoke-only with no maintained
|
||
`last_seen_at`, so a lingering session never expires and **account age** is the
|
||
abandonment trigger, not "last session gone". The reaped guest's `sessions`/`identities`/
|
||
`account_stats` fall away via their own `ON DELETE CASCADE`.
|
||
- ~~**TODO-4 — put the per-game alphabet on the wire (owner's idea, Stage 7).**~~ **Done in
|
||
Stage 13.** The client is now alphabet-agnostic: it caches each variant's `(index, letter,
|
||
value)` table — sent by the backend behind `StateRequest.include_alphabet` on a per-variant
|
||
cache miss — and live play exchanges **letter indices** both ways (rack, submit-play,
|
||
evaluate, exchange, word-check; a blank rides as the sentinel index 255). The table is
|
||
produced from the solver ruleset (`engine.AlphabetTable`), so it is pinned by the solver
|
||
version and cannot drift from the running backend, and `ui/src/lib/premiums.ts` is now
|
||
geometry only. The durable journal / history / GCG stay decoded concrete characters (§9.1,
|
||
unchanged). The DAWG/solver build-time agreement (the original caveat, shared with TODO-2) was
|
||
discharged in Stage 14: the dict repo builds against the published solver + pinned
|
||
`dafsa`/`alphabet`, byte-identical to the fixtures.
|
||
- **TODO-5 — QR friend codes (owner's idea, Stage 8).** *Partially done in Stage 9, extended later:*
|
||
the deep-link scheme exists (`f<code>`, shared Go ↔ TS), the bot redeems it on launch, and the UI
|
||
offers a real **Share** control for an issued code — Telegram's native share-to-chat picker inside
|
||
the Mini App (`openTelegramLink` + `t.me/share/url`), the system share sheet (`navigator.share`) on
|
||
the web, else copy-the-link. The shared link points at the **same bot the player signed in through**:
|
||
it carries the session's `service_language` (now on the `Session` wire) and picks
|
||
`VITE_TELEGRAM_LINK_EN`/`_RU`, falling back to `VITE_TELEGRAM_LINK`. **Still open:** render the link
|
||
as a **QR** so a friend can add you by scanning. The code semantics (12 h TTL, single use, one active
|
||
per issuer) stay as-is; only the delivery changes.
|
||
- **TODO-6 — smart default for the friend-game "game type" (owner's idea, Stage 8).**
|
||
The play-with-friends form has no preselected variant today (an empty, required
|
||
pick). Default it from the player's history (the variant they play most, from
|
||
`account_stats` or a games query), falling back to their interface language
|
||
(en → English, ru → Russian/Эрудит). Until then the explicit pick avoids guessing
|
||
wrong.
|