Быки и коровы 🐂🐄

▶ Играть: Mini App в Telegram · бот: @dementev_b_and_c_bot

Логическая игра в Telegram Mini App. Сервер загадывает число из 4 разных цифр (ноль может стоять первым), игрок угадывает его по подсказкам:

• 🐂 бык — цифра есть в числе и стоит на своём месте;
• 🐄 корова — цифра есть, но на другом месте.

Ходов сколько угодно; после каждого видно, сколько чисел ещё подходит. Личная статистика и общий рейтинг по среднему числу попыток за последние 20 игр. Русский и английский.

О проекте

Это вторая версия уже выпущенного продукта, написанная с нуля. Цель — проверить, что те же свойства для игрока и та же защита достигаются кратно меньшим кодом, если не строить слои «на вырост». Вышло в 3,2 раза меньше строк (сравнение).

Разработка — с ИИ-агентом (Claude Code): агент пишет код и автотесты, автор принимает решения, задаёт требования и проверяет руками. Каждое решение и каждая найденная ошибка — в журнале решений.

Архитектура

Телефон (Telegram) ─HTTPS─► Caddy ─► сервер (Node, Fastify, Kysely) ─► PostgreSQL
                            └─ файлы Mini App          ▲
Telegram ──webhook─────────────────────────────────────┘  бот: /start → правила и «Играть»

Три контейнера Docker на одной ВМ; из интернета открыт только Caddy (HTTPS, 80/443).

src/domain/   правила игры, статистика, рейтинг — чистые функции без базы и сети
src/server/   вход, API, сценарии в транзакциях, бот, миграции
src/web/      Mini App (React)
src/shared/   типы API и переводчик — общие для сервера и браузера
src/locales/  тексты: ru.ftl, en.ftl

Принципы

1. Сервер решает всё. Клиент передаёт намерение, сервер проверяет, применяет правила и возвращает состояние. Mini App правил не знает — линтер не даёт ей импортировать src/domain.
2. Клиенту не доверяем. Игрок определяется только по подписи Telegram (initData) со сроком годности. Загаданное число не уходит клиенту, пока партия идёт.
3. Правила — отдельно и чисто. Подсчёт, проверка хода, статистика и рейтинг — функции без ввода-вывода, покрытие тестами 100%.
4. Целостность — в несколько слоёв. Каждое действие — одна транзакция; двойной ход останавливают блокировка партии, номер хода и уникальный ключ в базе; ограничения записаны в самой базе.
5. История, а не счётчики. Хранятся партии и ходы; рейтинг — сводка, пересчитываемая из них в транзакции конца партии и читаемая по индексу.
6. Тексты вне кода. Каждый язык написан отдельно; склонения — Project Fluent; в разметке нет ни одной фразы.
7. Соразмерность. Слой добавляется, когда без него что-то ломается, а не «на всякий случай». Отложенное записано вместе с сигналом, при котором к нему вернуться.

Ключевые решения

Решение	Почему
Один клиент — Telegram Mini App; бот только открывает её	Вход и выпуск новой версии делает Telegram: нет своей авторизации и старых версий клиента
Один пакет с папками, не монорепозиторий	Общий код сервера и браузера — несколько типов; границы держит линтер
Kysely вместо ORM	Запросы на TypeScript, выполняется ровно написанное. Prisma в первой версии ела 18% процессора и тайком читала всю таблицу
Без слоя репозитория; тесты на настоящей PostgreSQL	Базу менять не собираемся; подмена в памяти не знает блокировок и ключей, которые и защищают от двойного хода
Бот на webhook, а не long polling	HTTPS уже есть; нет конфликта «один токен — один процесс»
API без версий	Mini App выкладывается вместе с сервером; меняем только совместимо (добавляем, не переименовываем)
Нет журнала событий и дашбордов	Смотреть некому; история ходов со временем есть, вопросы — SQL
Один процесс сервера	Медиана хода 19 мс при 1000 игроков, но 95% в цель 500 мс не уложились — решено ждать реальной нагрузки; сигнал и план — в замере

Полностью — с датами, отвергнутыми вариантами и итогами каждого этапа — в журнале решений.

Сравнение с первой версией

Непустые строки, одинаковые правила подсчёта; код, сгенерированный Prisma, в первой версии не учтён.

	Первая версия	Облегчённая	Меньше в
Код (сервер, клиент, правила)	6 507	2 784	2,3 раза
Автотесты	9 056	2 104	4,3 раза
Документы	2 778	570	4,9 раза
Инфраструктура и скрипты	1 835	758	2,4 раза
Всего	20 176	6 216	3,2 раза

Оговорка: у первой версии два клиента — чат-бот и Mini App с общей партией; у облегчённой один.

Качество

• Правила — примеры и свойства на случайных данных (fast-check), покрытие 100%.
• Сервер — сценарии на настоящей PostgreSQL: подделки входа, одновременные ходы, рейтинг против правил на случайных историях; каждый ответ проверяется на утечку загаданного числа.
• Mini App — экраны и сбои с подменённым сервером; тексты — одинаковые ключи в обоих языках.
• Сквозные — рабочая сборка против сервера в Chromium и WebKit, с проверкой доступности (axe).
• Нарочные поломки на каждом этапе — так найдены тесты, которые ничего не ловили.
• Нагрузочный замер — 1000 игроков, база 10 000 (отчёт).
• Ревью кода из отдельной сессии — нашло ошибки, прошедшие мимо тестов; исправлены с тестами.
• Руками — iPhone SE, VoiceOver, тёмная тема, «уменьшить движение», восстановление из копии.

CI в GitHub Actions на каждый PR. Копии базы — ежедневно вне сервера, восстановление проверено.

Запуск для разработки

Нужны Node 24, pnpm и Docker Desktop.

pnpm install
copy .env.example .env    # вписать пароль базы
pnpm db:up
pnpm check                # формат, линтер, типы, тесты
pnpm test:e2e             # сквозные в Chromium и WebKit
pnpm dev                  # сервер
pnpm dev:web              # Mini App в браузере, вход подписывается сам

Документы

Требования · Правила · API и данные · Журнал решений и итоги этапов · Нагрузочный замер · Деплой

Лицензия — MIT.