Mika Quest Mobile — Flutter RPG Habit & Quest Platform

Нативное кроссплатформенное приложение (iOS / Android) на Flutter & Dart, превращающее семейные дела, привычки и развитие в совместное приключение с маскотом Микой.

Статус проекта: v0.2.0 (Alpha). Реализованы доменные репозитории Drift SQLite, родительская биометрия/PIN с backoff, оффлайн-движок синхронизации SyncEngine на часах Лампорта, а также Go Relay бэкенд на порту 8347 с WAN-доступом https://api.mika-quest.mikaby.ru.

---

🌐 Сетевая инфраструктура и Relay Backend

• Единый WAN API: https://api.mika-quest.mikaby.ru (SSL Let's Encrypt через VPS Nginx -> туннель на мини-ПК :8347).
• Никакого LAN split-brain: все устройства (родители, детский планшет вне дома или в домашней сети) общаются через единый контракт.
• Бэкенд на Go (server/): потокобезопасный IPRateLimiter (5 req/s, burst 10), комнатный WebSocket Relay Hub для броадкаста дельт, SQLite хранилище пейринга и событий.
• E2E верификация: python3 test/e2e_wan_api_test.py — проверяет health, создание семьи, QR пейринг, push/pull синхронизации по HTTPS.

🎯 Ключевые принципы проекта

1. Маскот Мика: Маленькая девочка-домовушка из старого заброшенного дома («Новые хозяева?! Ура-а-а!»). Общается строго от первого лица («Я», «мне», «мой»).
2. Трёхвалютная гармония:
   • Спарки (Sparky ✨): Задания от родителей → реальные семейные радости (время на Steam Deck, поездки, подарки). В игре ничего не продаётся за Спарки!
   • Капли (Capl 💧): Автоматическая системная награда за привычки → ремонт заброшенного дома от Сонной Пыли, мебель, корм для питомца.
   • Люми (Lumi 🌕): Премиум-валюта только для родителей за PIN (эксклюзивные сеты, Family Pass).
3. Семья дома с первой секунды: Аватары всех членов семьи сразу сидят в гостиной.
4. Бескомпромиссная приватность: Никаких пользовательских фото на сервере. Фото-отчёты сохраняются только локально в песочнице устройства.
5. Offline-First: Локальная база данных Drift (SQLite) с фоновой изоляцией запросов.

---

🏗 Архитектура кодовой базы

Проект следует паттерну Feature-First + Clean Architecture:

lib/
├── app/                  # Инициализация приложения, роутинг, глобальная тема
│   ├── app.dart
│   ├── router.dart
│   └── theme.dart
├── core/                 # Общие утилиты, дизайн-токены, тактильный отклик (haptics)
│   ├── constants/
│   ├── errors/
│   ├── haptics/
│   └── widgets/
├── data/                 # Локальная база данных Drift / SQLite
│   └── local/
│       ├── app_database.dart
│       └── tables/
└── features/             # Модули фичей (Feature-First)
    ├── quests/           # Квесты, стрики, подтверждения
    ├── meta_house/       # 2D-домик, кастомизация комнат, мебель
    ├── rewards/          # Родительская витрина наград
    └── parent_insights/  # Радар развития и педагогические подсказки

📱 Мобильная сборка и распространение (Distribution Hub)

Приложение компилируется на рабочей станции (192.168.0.146) и автоматически публикуется в приватный homelab-портал:

# Единая команда сборки и публикации
/opt/data/bin/build-and-publish-mika-quest

• URL портала: https://apps.mikaby.ru/mika-quest/ (защищено Authelia SSO).
• Манифест автообновления: https://apps.mikaby.ru/mika-quest/version.json (открыт для in-app проверок).
• Архитектура: apps-hub (:3415) -> туннель ha-tunnel (:23415) -> Nginx VPS (SSL Let's Encrypt).

---

📚 Документация

Полный навигатор — docs/INDEX.md:

Документ	Назначение
docs/brief/PRODUCT_STRATEGY_AND_ROADMAP.md	Видение, GDD, экономика, персоны, метрики MVP, roadmap (SSOT продукта)
docs/brief/COMPETITIVE_ANALYSIS.md	Конкурентный анализ и позиционирование
docs/architecture/ENGINEERING_SPEC_AND_BACKLOG.md	Стек, схема БД Drift, Quest Engine, экономика, роутинг, NFR, бэклог (SSOT инженерии)
docs/ux/DESIGN_SYSTEM.md	Дизайн-система: токены, типографика, компоненты, доступность
docs/ux/USER_FLOWS.md	Пользовательские сценарии
docs/content/MIKA_VOICE_GUIDE.md	Голос и реплики Мики (контент-дизайн)
docs/architecture/SECURITY_AND_PRIVACY.md	Threat model и compliance
docs/ops/ANALYTICS.md	Локальная событийная аналитика
docs/qa/TEST_PLAN.md	Стратегия и план тестирования
docs/GLOSSARY.md	Глоссарий терминов и языковой кодекс Мики
docs/ops/DEVELOPMENT_WORKFLOW.md	Процесс разработки и релизов
docs/brief/RISK_REGISTER.md	Реестр рисков
docs/content/CONTENT_PIPELINE.md	Ассеты: структура и бюджеты
docs/prd/MVP_SCOPE.md	Scope MVP (MoSCoW) и feature-флаги
docs/content/QUEST_TEMPLATES.md	Стартовая библиотека квестов и наград
docs/prd/SEASONAL_META.md	Сезоны, рейды, питомцы (Фазы 2–4)
docs/ops/CI_CD_PIPELINE.md	Пайплайн и quality gates
docs/ops/LOCALIZATION.md	Локализация ru → en
docs/ops/STORE_LISTINGS.md	Метаданные сторов
docs/ux/UX_RESEARCH_PLAN.md	UX-исследования с детьми
docs/architecture/CODE_STYLE.md	Стиль кода и правила слоёв
docs/qa/RUNBOOK.md	Ранбук разработчика
docs/legal/PRIVACY_POLICY_TEMPLATE.md	Шаблон политики конфиденциальности
docs/architecture/BILLING_AND_SUBSCRIPTIONS.md	Биллинг и подписки (Фаза 3)
docs/architecture/SYNC_ARCHITECTURE.md	Синхронизация семьи (Фаза 3)
docs/ops/MODERATION_POLICY.md	Модерация UGC (Фаза 4)
docs/epics/SPRINT_PLAN.md	Спринт-план Alpha
docs/ops/TEAM_RACI.md	Матрица ответственности (RACI)
docs/ux/BRAND_GUIDELINES.md	Брендбук
docs/qa/UAT_CHECKLIST.md	Приёмочные сценарии Alpha
docs/legal/FAQ_PARENTS.md	FAQ для родителей
docs/prd/GAME_BALANCE.md	Гейм-баланс: прогрессия, анти-инфляция, тьюнинг
docs/content/PEDAGOGY_FRAMEWORK.md	Педагогический фреймворк: 5 сфер, красные линии
docs/content/MIKA_LINES_SEED.md	Стартовые реплики Мики (контент v1)
docs/content/SOUND_DESIGN.md	Звуковой дизайн: карта событий, голос, музыка
docs/architecture/DEV_ENVIRONMENT.md	Окружение разработки и tooling
docs/legal/TERMS_OF_SERVICE_TEMPLATE.md	Шаблон пользовательского соглашения
docs/ops/RELEASE_NOTES_TEMPLATE.md	Шаблон release notes (RU/EN)
docs/prd/NOTIFICATIONS_POLICY.md	Локальные уведомления: типы, лимиты, тон
docs/content/HOUSE_META_DESIGN.md	Геймдизайн 2D-домика
docs/ux/ONBOARDING_SCRIPT.md	Поскринный онбординг с копирайтом
docs/ux/ACCESSIBILITY.md	Детская доступность
docs/content/ART_PRODUCTION_PLAN.md	Арт-конвейер: пакеты, дедлайны, placeholder-first
docs/architecture/adr/	Architecture Decision Records (0001–0005)

---

🛠 Стандарты качества и CI/CD

В проекте настроены строгие правила линтинга и контроля качества:

• Анализ кода: flutter analyze
• Форматирование: dart format --output=none --set-exit-if-changed .
• Тесты: flutter test --coverage
• Архитектурный гайд для AI-агентов: см. AGENTS.md и .cursor/rules/