diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 0000000..554dc4a --- /dev/null +++ b/PLAN.md @@ -0,0 +1,192 @@ +# Dungeons & Ground — план закрытой web‑альфы + +## 1. Цель продукта + +Dungeons & Ground — англоязычная веб‑платформа для текстовых TTRPG‑кампаний любого жанра, где: + +- AI‑соавтор помогает за несколько сообщений создать собственную вселенную. +- AI Game Master ведёт историю, NPC и последствия. +- Реальные игроки участвуют асинхронно в общем пошаговом чате. +- Постоянные AI‑герои дополняют партию, а при необходимости временно заменяют отсутствующих игроков. +- Сервер, а не языковая модель, рассчитывает проверки, броски, HP и урон. +- Кампания сохраняет мир, отношения, инвентарь, события и долгосрочную память. + +Главный критерий готовности альфы: 2–4 человека создают мир, персонажей и проходят минимум 20–30 минут связной кампании, причём AI не забывает ключевые события и не изменяет игровые значения произвольно. + +В отличие от Friends & Fables, уже совмещающего AI‑ведущего, worldbuilding, память, карты, бой и мультиплеер, первая версия D&G сосредоточится на простом создании мира и партии, которая продолжает игру даже при отсутствии части людей. [Возможности Friends & Fables](https://fables.gg/), [описание их системы памяти](https://help.fables.gg/articles/2838157-memories). + +## 2. Функциональность альфы + +### Пользовательский путь + +1. Вход по email magic link для пользователей из allowlist. +2. Создание приватной вселенной через чат с AI‑соавтором. +3. AI задаёт 3–5 уточняющих вопросов о жанре, атмосфере, конфликте и желаемой роли игроков. +4. Создаётся редактируемый стартовый набор: + - premise, genre, tone и content boundaries; + - стартовая локация; + - 3 значимых NPC; + - 2 фракции; + - сюжетная завязка; + - скрытая угроза или цель; + - начальная сцена. +5. Владелец подтверждает мир, создаёт кампанию и приглашает игроков ссылкой. +6. Каждый игрок создаёт персонажа вручную или с помощью AI. +7. Владелец добавляет постоянных AI‑героев и определяет, чьи персонажи могут временно переходить под управление AI. +8. Игроки отправляют действия в текущем раунде. +9. AI‑DM обрабатывает раунд, когда: + - ответили все активные реальные игроки; или + - владелец нажал `Continue without waiting`. +10. AI‑герои и замены совершают действия после людей, затем AI‑DM публикует единый результат раунда. + +### Облегчённая игровая система + +Использовать классические характеристики `STR`, `DEX`, `CON`, `INT`, `WIS`, `CHA` во всех жанрах, но позволять AI адаптировать названия архетипов, экипировки и способностей под fantasy, sci‑fi, horror и другие сеттинги. + +Первая версия движка покрывает: + +- d20 ability и skill checks; +- proficiency bonus; +- HP, Defense/AC и initiative; +- attack roll, damage и healing; +- advantage/disadvantage; +- простые статусы и ограниченные ресурсы; +- серверный генератор случайных чисел с сохранением формулы и результата; +- ручную корректировку состояния владельцем кампании с записью в аудит. + +Полные классы, заклинания, сетка боя и редкие правила 5e не входят в альфу. Основа — SRD 5.2.1 под CC BY 4.0 с обязательной атрибуцией; закрытые названия и сеттинги D&D не использовать. [Официальные условия SRD 5.2.1](https://www.dndbeyond.com/srd). + +### Память и состояние мира + +Хранить отдельно: + +- неизменяемый журнал действий и результатов; +- текущую сцену и активные сущности; +- структурированное состояние персонажей, NPC, фракций и заданий; +- отношения между персонажами; +- важные воспоминания с привязкой к персонажам, локациям и тегам; +- краткое резюме истории, обновляемое каждые три завершённых раунда. + +В контекст модели передавать только системные инструкции, текущую сцену, последние два раунда, участвующие сущности, активные цели и релевантные воспоминания. Полная история никогда не отправляется автоматически. + +## 3. Техническая архитектура + +### Стек + +- Monorepo на TypeScript. +- Nuxt.js для SSR‑интерфейса и Nitro API. +- Отдельный TypeScript worker для генерации миров и обработки игровых раундов. +- Supabase: PostgreSQL, Auth, Row Level Security и Realtime. +- BullMQ + managed Redis для очереди AI‑задач. +- Railway: отдельные deployments для Nuxt/Nitro и worker. +- OpenRouter provider adapter с моделью `deepseek/deepseek-v4-flash`. +- Zod для общей валидации API, AI‑ответов и игровых команд. +- Vitest, Nuxt Test Utils и Playwright для тестов. + +Desktop‑версия позднее создаётся через Tauri и использует тот же API и web‑интерфейс. + +### Основные сущности и интерфейсы + +- `User`, `Invite`, `World`, `WorldEntity`, `Campaign`, `CampaignMember`. +- `Character`, `CharacterController`, `Relationship`. +- `Round`, `PlayerIntent`, `GameEvent`, `DiceRoll`. +- `SceneState`, `QuestState`, `Memory`, `StorySummary`. +- `AiJob`, `AiUsage`, `AuditEntry`. + +Публичные серверные операции: + +- создание и редактирование мира через coauthor session; +- подтверждение сгенерированного мира; +- создание кампании и приглашение участника; +- создание/назначение персонажа; +- отправка или изменение действия текущего раунда; +- отметка игрока как готового; +- принудительное закрытие раунда владельцем; +- получение истории, состояния персонажа и активной сцены; +- ручная корректировка состояния владельцем. + +### Обработка раунда + +1. Nitro сохраняет `PlayerIntent` и готовность игрока. +2. Транзакция блокирует раунд и создаёт ровно одну задачу после выполнения условия закрытия. +3. Worker собирает минимальный контекст. +4. AI определяет намерения, нужные проверки и действия AI‑героев через типизированные tool calls. +5. Rules engine выполняет все броски и изменения механического состояния. +6. Результаты возвращаются AI для финальной narration. +7. Предложенные события и изменения проходят Zod‑валидацию и проверку разрешённых переходов. +8. Narration, события, память и новое состояние сохраняются атомарно. +9. Supabase Realtime обновляет интерфейсы участников. + +При timeout или ошибке OpenRouter задача повторяется с idempotency key. После исчерпания повторов раунд остаётся открываемым повторно владельцем; частичные изменения не сохраняются. OpenRouter поддерживает tool calling и JSON Schema outputs, которые следует использовать для типизированных AI‑операций. [Tool calling](https://openrouter.ai/docs/guides/features/tool-calling), [structured outputs](https://openrouter.ai/docs/guides/features/structured-outputs). + +## 4. Дорожная карта на 8–10 недель + +### Недели 1–2 — фундамент + +- Monorepo, Nuxt/Nitro, worker, CI и окружения. +- Supabase Auth, allowlist, RLS и базовая схема данных. +- Англоязычный UI: login, dashboard, world list. +- OpenRouter adapter, учёт токенов, дневные квоты и безопасное хранение ключа. +- Первый вертикальный тест: действие игрока → worker → ответ AI. + +### Недели 3–4 — вселенные и персонажи + +- Coauthor chat и структурированная генерация стартового набора. +- Preview/edit/confirm для мира. +- Создание кампании и персонажей. +- Приглашения, lobby, роли owner/player и AI‑герои. +- 13+ фильтрация входных prompts и выходов модели. + +### Недели 5–6 — игровой цикл + +- Раунды, готовность участников и принудительное продолжение владельцем. +- Realtime‑обновления. +- Rules engine и журнал бросков. +- AI‑DM orchestration, AI‑герои и временная замена отсутствующих игроков. +- Защита от двойной обработки и конфликтующих действий. + +### Недели 7–8 — память и стабильность + +- Game events, relationships, memories и story summaries. +- Контекстный retrieval без векторной базы: сущности, локации, теги и PostgreSQL full‑text search. +- Retry, rate limits, usage dashboard и аудит изменений. +- E2E‑сценарий полной партии и набор AI‑регрессионных тестов. + +### Недели 9–10 — закрытая альфа + +- UX‑полировка, responsive web и onboarding. +- Наблюдаемость: ошибки, latency, стоимость раунда, размер контекста. +- Тестирование командой и приглашёнными пользователями. +- Исправление критических проблем и подготовка формы обратной связи. + +## 5. Проверка и критерии приёмки + +Обязательные сценарии: + +- Создать fantasy, sci‑fi и horror‑миры через coauthor chat. +- Отклонить или исправить неполную/невалидную AI‑структуру. +- Два пользователя вступают в одну кампанию и видят одинаковое состояние. +- Раунд ждёт всех активных людей. +- Владелец продолжает без отсутствующего игрока, после чего его персонажа корректно подхватывает AI. +- Постоянный AI‑герой сохраняет характер и отношения между сценами. +- Броски воспроизводимо отображают формулу, модификатор и итог. +- LLM не может напрямую изменить HP, инвентарь или результат броска. +- Повторный запрос, reconnect или retry не создаёт второй narration. +- OpenRouter timeout не повреждает состояние кампании. +- Пользователь не видит чужие приватные миры и кампании. +- 13+ фильтр блокирует запрещённый explicit‑контент. +- После 15–20 раундов AI корректно вспоминает ключевое событие из начала игры. +- Средняя стоимость и задержка раунда укладываются в установленные перед альфой квоты. + +Перед приглашением внешних тестеров провести минимум 20 сценарных AI‑прогонов с заранее ожидаемыми фактами, правилами и последствиями. + +## 6. Зафиксированные ограничения + +- Название `Dungeons & Ground` считается финальным, но перед публичным релизом обязательны проверка товарных знаков, домена и визуального сходства. +- Первая версия: web, English-first, invite-only, private worlds. +- Контент: 13+, без explicit‑материалов. +- OpenRouter оплачивает проект; пользователи не вводят собственные ключи. +- Оплаты нет — используются дневные, пользовательские и кампанийные лимиты. +- MVP полностью текстовый. +- Не входят: публичный каталог, marketplace, карты, изображения, TTS, видеогенерация, полноценный 5e combat, нативный desktop/mobile и пользовательские ruleset. +- После альфы приоритет определяется метриками: удержание кампаний, завершённые раунды, стоимость AI‑хода, частота ручных исправлений и качество памяти.