Ilia Denisov
408da3f201
New public ingress and the first network edge. Framework + a vertical slice of operations end-to-end; remaining ops reuse the same transcode pattern in Stage 7. Contracts (new module scrabble/pkg): - push.proto (backend->gateway gRPC server-stream) + scrabble.fbs (FlatBuffers edge payloads), committed generated Go; buf/flatc Makefiles (dev-time codegen). Backend: - REST handlers on the /api/v1 groups: internal session endpoints (telegram/guest/email login -> mint, resolve, revoke) and the user slice (profile, submit_play, state, lobby enqueue/poll, chat). - internal/notify in-process Publisher hub + internal/pushgrpc gRPC server (BACKEND_GRPC_ADDR) streaming your_turn/opponent_moved/chat/nudge/match_found; emission in game.commit, social, matchmaker. - migration 00005 accounts.is_guest; guests are durable rows excluded from stats; ProvisionGuest; email-as-login (RequestLoginCode/LoginWithCode). Gateway (new module scrabble/gateway): - Connect Gateway service over h2c (Execute + Subscribe), FlatBuffers<->JSON transcode registry, Telegram initData HMAC validator (seam), session cache, token-bucket rate limiter (3 classes), push fan-out hub, backend REST + push gRPC client, admin Basic-Auth reverse proxy. go.work: use ./pkg, ./gateway + replace scrabble/pkg. CI: gateway/**, pkg/** path filters; unit build/vet/test span all three modules. Docs (PLAN, ARCHITECTURE, FUNCTIONAL+ru, TESTING, READMEs) updated; gateway/pkg unit tests + guest/email-login integration tests.
90 lines
8.9 KiB
Markdown
90 lines
8.9 KiB
Markdown
# Scrabble Game — Функциональная спецификация
|
|
|
|
Пользовательские сценарии по доменам: что делает каждая видимая пользователю
|
|
операция. Это зеркало [`FUNCTIONAL.md`](FUNCTIONAL.md) для владельца проекта;
|
|
**авторитетна английская версия**. Любую точечную правку переносим в том же
|
|
патче (переводим только изменённые абзацы). Разделы наполняются по мере этапов;
|
|
*(Stage N)* помечает, где пишется детализация.
|
|
|
|
## Домены
|
|
|
|
### Личность и сессии *(Stage 1 / 6)*
|
|
Игрок приходит с платформы (сначала Telegram), через email-вход или как
|
|
эфемерный гость. Gateway один раз валидирует доступ и выдаёт тонкий
|
|
session-токен; backend сопоставляет его с внутренним `user_id`. Гость —
|
|
только сессия, с урезанными функциями (только авто-подбор; без друзей,
|
|
статистики и истории). Пока приложение открыто, клиент держит живой стрим и
|
|
получает обновления в реальном времени — ход соперника, ваш ход, чат, nudge и
|
|
найденный матч; внеприложенческий push (ваш ход, nudge) платформа доставит
|
|
позже (Stage 8).
|
|
|
|
### Аккаунты, привязка и слияние *(Stage 1 / 10)*
|
|
Первый контакт с платформы заводит постоянный аккаунт. Из профиля игрок
|
|
привязывает другие платформенные личности или email через confirm-поток;
|
|
привязка личности, у которой уже есть история, сливает её в текущий аккаунт
|
|
(статистика суммируется, игры/друзья переносятся).
|
|
|
|
### Лобби и подбор *(Stage 4)*
|
|
Нижнее tab-меню: **мои игры**, **профиль**. Авто-подбор (всегда 2 игрока)
|
|
встаёт в пул по варианту и сводится со следующим ожидающим человеком; через 10 с
|
|
без человека подставляется робот (робот — в Stage 5). Игры с друзьями (2–4)
|
|
формируются приглашением игроков из списка друзей или по внутреннему ID
|
|
(приглашения по deep-link появятся с платформенной интеграцией): инициатор
|
|
выбирает настройки, и партия стартует, когда приняли все приглашённые — любой
|
|
отказ отменяет приглашение, а без ответа приглашение протухает через семь дней.
|
|
|
|
### Игровой процесс *(Stage 3)*
|
|
Выкладывание фишек, пас, обмен или сдача. Ход проверяется по словарю партии при
|
|
сдаче и считается; безлимитный предпросмотр сообщает, сколько принёс бы
|
|
предполагаемый ход и легален ли он. Инструмент проверки слова безлимитный и
|
|
предлагает пожаловаться на любой результат. Подсказки управляются настройками
|
|
партии — разрешены ли они и сколько их у каждого игрока на старте — и расходуют
|
|
личный кошелёк подсказок после исчерпания внутриигрового лимита. Партия
|
|
завершается, когда мешок пуст и игрок выложил стойку, после 6 подряд бесплодных
|
|
ходов, по сдаче, либо по таймауту хода (от 5 минут до 24 часов, дефолт 24 часа):
|
|
пропущенный ход означает авто-сдачу, кроме как когда игрок внутри своего
|
|
суточного окна отсутствия (away). В партии на двоих сдача или таймаут отдают
|
|
победу другому игроку, а вышедший сохраняет свои очки. В партии на троих-четверых
|
|
место вышедшего убирается, остальные играют дальше, и партия завершается, когда
|
|
остаётся один активный игрок; что делать с фишками вышедшего (вернуть в мешок или
|
|
убрать из игры) выбирается при создании партии, а его стойка никогда не
|
|
показывается остальным.
|
|
|
|
### Робот-соперник *(Stage 5)*
|
|
Если авто-подбор не находит человека за десять секунд, свободное место занимает
|
|
робот-соперник, и партия стартует без ожидания. Он задуман неотличимым от человека:
|
|
один раз за партию решает, играть ли на победу (примерно в 40% случаев, так что
|
|
человек выигрывает большинство партий), целится в близкий счёт, а не в разгром или
|
|
поддавки, и ходит с человеческим темпом — чаще короткие раздумья, изредка долгие, и
|
|
ночная пауза, подстроенная под день игрока. На nudge отвечает за несколько минут и
|
|
сам шлёт nudge, когда игрок надолго пропал. Носит человекоподобное имя, не общается
|
|
в чате и не принимает заявки в друзья.
|
|
|
|
### Социальное: друзья, блок, чат, nudge *(Stage 4)*
|
|
Заявка в друзья и её принятие (отклонение или отмена снимают заявку, удаление —
|
|
расторгает дружбу). Глобальная блокировка — отключить входящие чат и/или заявки —
|
|
и блокировка конкретного игрока (пер-юзер блок скрывает его чат и запрещает заявки
|
|
и приглашения в игру в обе стороны, а также расторгает уже имеющуюся дружбу). Чат
|
|
партии — для быстрых реакций: сообщения короткие (до 60 символов) и не должны
|
|
содержать ссылок, email и телефонов, даже завуалированных. Nudge ожидаемого
|
|
соперника — не чаще раза в час (nudge — часть игрового чата); внеприложенческий
|
|
push доставляется через платформу.
|
|
|
|
### Профиль и настройки *(Stage 4)*
|
|
Редактирование языка (en/ru), отображаемого имени, таймзоны, суточного окна
|
|
отсутствия (away) и переключателей блокировок, а также привязка email по
|
|
confirm-коду: backend шлёт на почту короткий код, и после ввода email
|
|
привязывается к аккаунту (email, уже подтверждённый другим аккаунтом, занять
|
|
нельзя — это слияние, отдельный этап). Привязанные платформенные аккаунты и
|
|
слияние появятся в Stage 10.
|
|
|
|
### История и статистика *(Stage 3)*
|
|
Завершённые партии архивируются в независимом от словаря виде и экспортируются
|
|
в GCG. Статистика (только у постоянных аккаунтов): победы, поражения, ничьи,
|
|
макс. очков за партию и макс. очков за один ход (лучший ход, уже включающий все
|
|
образованные им слова и бонус за все фишки).
|
|
|
|
### Администрирование *(Stage 9)*
|
|
Админ (Basic Auth на gateway) разбирает жалобы на слова, управляет версиями
|
|
словаря, смотрит пользователей/игры.
|