KarmaCode: функциональная карта MVP backend¶

Статус: проектирование, версия документа 1.0 от 2026-09-03.

Этот файл — точка входа в документацию и предлагаемая декомпозиция backend. За основу продукта взято более конкретное исходное ТЗ, дополненное прямо заданными требованиями: собственный Node.js backend и AI-помощник. Рекомендуемые defaults приняты как текущий план. Административная панель и admin API последним решением полностью исключены из MVP и будут отдельным post-MVP модулем.

Что именно строим¶

KarmaCode принимает имя, дату, точное местное время и место рождения, детерминированно рассчитывает четыре системы (астрология, нумерология, Дизайн Человека, Матрица судьбы), бесплатно показывает фактический результат и продаёт интерпретацию, единый маршрут, динамические прогнозы и трекер целей по подписке. Консультации практиков оплачиваются отдельно.

Основная воронка MVP:

ввод данных → четыре расчёта → регистрация e-mail → бесплатный результат → paywall → оплата → платный разбор

Backend входит в текущий scope. Мобильное приложение, клиентский web/PWA, админ-панель и admin API не входят.

Предлагаемые модули¶

Модуль	Что делает	Приоритет MVP
`auth`	Passwordless OTP по e-mail через Resend, регистрация до paywall, access/rotating refresh sessions	P0
`users`	Профиль, согласия, настройки, данные рождения, безопасное удаление/анонимизация	P0
`places`	Поиск места, фиксация координат и IANA-таймзоны с историческим UTC offset	P0
`calculations`	Оркестрация четырёх независимых движков, хэш входа, версионирование и кэш результата	P0
`astrology`	Планеты, ASC/MC, дома, знаки и аспекты на Swiss Ephemeris; алгоритм описан отдельно	P0
`numerology`	Заменяемая пифагорейская методика `numerology-pythagorean-v0`	P0, provisional
`human-design`	Заменяемый `human-design-standard-v0`: дуга 88°, профиль, центры и каналы	P0, provisional
`destiny-matrix`	Заменяемая собственная схема арканов `destiny-matrix-22-v0`	P0, provisional
`interpretations`	Платная AI-интерпретация JSON четырёх систем по стабильным осям, с доказательствами и кэшем	P0
`forecasts`	Детерминированный слой транзитов/циклов и AI-текст дня, недели, месяца по четырём сферам	P0
`billing`	Расширяемый каталог тарифов, один активный тариф MVP, YooKassa, продления, разовые оплаты и возвраты	P0
`goals`	Цель, срок, check-in, результат и накопительная статистика	P0
`practitioners`	Ручной онбординг, проверка документов, профиль, специализации, кейсы и видимость в каталоге	P0
`consultations`	Каталог, заявка, ручное согласование, статусы и отдельная оплата; без calendar/chat/video	P0
`notifications`	Транзакционные e-mail через Resend; Telegram и push не входят	P1
`analytics`	Серверные события воронки, UTM first/last touch, подписки, LTV, цели и заявки	P0
`audit`	Неизменяемый журнал критических действий и outbox для надёжных внешних вызовов	P0

P0 — нужен для проверки главной воронки; P1 — можно подключать после первого сквозного платного сценария.

Границы функциональных блоков¶

Расчёт и трактовка разделены принципиально:

движки получают нормализованный ввод и возвращают версионированный JSON без AI;
слой интерпретаций получает только сохранённые результаты и формирует платный текст;
AI не имеет права менять координаты планет, числа, арканы или тип;
одинаковые inputHash + algorithmVersion возвращают один расчёт, а одинаковые calculationHash + promptVersion + provider/model snapshot — сохранённую интерпретацию.

Оплата отделена от выдачи доступа: YooKassa сообщает состояние операции, billing фиксирует подтверждённый факт, а entitlements внутри модуля подписки решает, к каким материалам пользователь имеет доступ. Redirect из платёжной формы не является подтверждением оплаты.

Будущий admin module будет подключаться к публичным use cases/отдельным безопасным операциям, но в MVP нет admin role, admin endpoints и административного CRUD.

Документы¶

Блокеры¶

План разрешения зафиксирован в реестре. Архитектурных блокеров для проектирования БД нет. Provisional-методики и вопросы публичного запуска не останавливают internal-разработку, но обязательны к проверке по pre-pilot checklist.