kungfuman-platform

Академия Kungfuman — Платформа

Техническое задание и пошаговый план реализации

Версия 1.0 · Сентябрь 2026 Автор задачи: Акмал (Kungfuman, Худжанд) Назначение документа: исходник для работы с Claude Code и точка сборки для всех решений по продукту.

0. Как пользоваться этим документом

Документ состоит из трёх частей:

Часть	Что внутри	Кому
I. Спецификация	Принципы, архитектура, модель данных, SQL-схема, RLS	Claude Code — контекст проекта
II. План этапов	8 этапов с задачами, DoD и готовыми промптами	Тебе — порядок работы
III. Операционный контур	Юрлицо, платежи, видео, право	Тебе — идёт параллельно коду

Важно. Не отдавай Claude Code весь файл целиком одним промптом. Положи его в репозиторий как docs/SPEC.md, а работай задачами по одному этапу за раз. Как это организовать — раздел 12.

ЧАСТЬ I. СПЕЦИФИКАЦИЯ

1. Продуктовые принципы

Пять правил, которые определяют все решения ниже. Если возникает спор — решает этот список.

Методика — это данные, а не контент. Семиуровневая программа описывается один раз как структура в базе: дисциплина → уровень → практика → критерий аттестации. Видео, тексты и занятия только ссылаются на неё. Каталог видео копируется за месяц. Структурированная методика с прогрессией и аттестацией — нет. Это главный актив платформы.
Офлайн и онлайн — два интерфейса к одному ядру. Не два продукта. Занятие в парке Камоли Худжанди и урок онлайн-курса ссылаются на одну и ту же запись practices. Ученик имеет один прогресс независимо от того, где занимался.
Мультитенантность с первого дня. Худжанд — это первая запись в таблице schools, а не хардкод. Регион, валюта, язык, часовой пояс — поля, а не константы. Добавление Москвы или Дубая позже не должно требовать миграции.
Мультиязычность с первого дня, наполнение — по мере надобности. Все пользовательские тексты хранятся как JSONB {"ru": "...", "tg": "...", "en": "..."}. Сегодня заполняется только ru. Переход на tg и en не потребует переписывания схемы.
Запуск по очереди, архитектура — сразу общая. Одна база, одна авторизация, один репозиторий. Но релизы последовательные: сначала офлайн-контур на живой группе, потом онлайн. Курс, снятый до обкатки на людях, снимается вслепую.

2. Пользователи и роли

Роль	Кто	Основные права
`owner`	Акмал	Всё в своей школе + управление школами
`admin`	Администратор школы	Ученики, группы, расписание, платежи
`instructor`	Инструктор	Свои группы, посещаемость, аттестации
`student`	Ученик	Свой профиль, свой прогресс, свои платежи, купленные курсы
`guest`	Лид из WhatsApp	Публичный контент, превью-уроки

Роль хранится в profiles.role и всегда проверяется на уровне БД через RLS, а не только в UI.

3. Технологический стек

Слой	Выбор	Почему
Фронтенд	Next.js 15 (App Router) + TypeScript	SSR для SEO лендингов, один язык на весь стек
UI	Tailwind CSS + shadcn/ui	Быстро, темизируемо под чёрно-золотую айдентику Kungfuman
БД + Auth + Storage	Supabase (Postgres 15+)	RLS даёт безопасность на уровне данных; auth по телефону/OTP критичен для Таджикистана
Хостинг	Vercel	Нулевой девопс, edge-кэш
Видео (РФ/СНГ)	Kinescope	Скорость в РФ, защита от скачивания, подписанные ссылки
Видео (мир)	Bunny.net Stream	Дёшево, глобальный CDN
WhatsApp	Business API (позже) / вручную на старте	Аудитория Худжанда уже там
Аналитика	Plausible или Umami	Без cookie-баннеров, проще с GDPR

Почему не готовый LMS (GetCourse, Teachable). Они закрывают онлайн-курсы, но не закрывают офлайн-операционку и, главное, не дают хранить методику как структуру. Ты потеряешь принцип №1. При этом на первые 2–3 месяца GetCourse допустим как костыль для продаж, пока строится своё — см. этап 3.

Почему не Unreal Engine. Твоя экспертиза в UE здесь не применяется до этапа 8. Веб-платформа — это CRUD и права доступа. UE-модуль разбора формы движения через видеоанализ — отдельный продукт, к которому имеет смысл идти после того, как наберётся база учеников и материала.

4. Модель данных

4.1 Обзорная схема

schools (Худжанд, Москва, ...)
  │
  ├── profiles ──── student_health (защищённые данные)
  │      │
  │      ├── enrollments ──── attestations
  │      │        │
  │      │        └── practice_progress
  │      │
  │      ├── subscriptions ──── payments
  │      └── lesson_progress
  │
  ├── disciplines ──── levels ──── practices ──── practice_criteria
  │                                    ▲    ▲
  │                                    │    │
  ├── venues        groups ──── sessions ──── attendance
  │                                         │
  ├── courses ──── course_modules ──── lessons
  │                                         │
  ├── media_assets ─────────────────────────┘
  │
  ├── products ──── product_prices
  └── leads

4.2 Полная SQL-схема (Supabase)

Файл: supabase/migrations/00001_core.sql (см. одноимённый файл в репозитории — там хранится актуальная версия схемы; ниже приведён её обзор).

Перечисления (enums):

app_role — student, instructor, admin, owner
session_kind — offline, online_live, self_paced
attendance_status — registered, present, absent, late, cancelled
enrollment_status — active, paused, completed, dropped
sub_status — pending, active, paused, expired, cancelled
payment_status — pending, succeeded, failed, refunded
payment_provider — cash, alif, dc_wallet, korti_milli, yookassa, paddle, manual
media_provider — kinescope, vk_video, bunny, youtube, supabase
product_kind — subscription, course, workshop, retreat, single_visit
content_status — draft, review, published, archived
progress_status — not_started, in_progress, completed
lead_status — new, contacted, trial_booked, trial_attended, converted, lost

Таблицы (26):

Тенанты и люди: schools, profiles, student_health
Методика: disciplines, levels, practices, practice_criteria
Обучение ученика: enrollments, attestations, practice_progress
Офлайн-контур: venues, groups, sessions, session_practices, attendance
Онлайн-контур: media_assets, courses, course_modules, lessons, lesson_progress
Деньги: products, product_prices, subscriptions, payments
Воронка и аудит: leads, audit_log

Точные определения колонок, индексы и ограничения — в файле миграции supabase/migrations/00001_core.sql.

4.3 Триггеры и служебные функции

Файл: supabase/migrations/00002_functions.sql.

set_updated_at() — автообновление updated_at (триггеры на profiles, practice_progress, lesson_progress).
RLS-хелперы (все security definer с фиксированным search_path = public, pg_temp): auth_school_id(), auth_role(), is_staff(), is_admin(), has_course_access(p_course_id).
consume_session_credit() — списание занятия с активного абонемента при отметке присутствия (триггер trg_attendance_credit на attendance).

Внимание: для RLS-хелперов security definer + фиксированный search_path обязательны.

4.4 RLS-политики

Файл: supabase/migrations/00003_rls.sql.

Принцип: ученик видит только своё, персонал видит всю свою школу, чужие школы не видит никто.

RLS включается на всех 26 таблицах. Ключевые правила:

schools — своя школа читается участниками; правит только owner.
profiles — сам себя (read/update без смены роли), персонал читает свою школу, админ правит всё в школе.
student_health — только сам ученик и персонал школы.
Методика (disciplines/levels/practices/practice_criteria) — читают участники школы (practices — только published или персонал), правит только админ.
Обучение — ученик видит своё, персонал школы правит.
Расписание/посещаемость — читают все в школе, персонал правит; ученик видит свою посещаемость.
Онлайн-контент — courses/modules/lessons публичны при published или доступе через has_course_access(); превью-уроки открыты; правит админ. lesson_progress — сам ученик, персонал читает.
Деньги — products/prices читаются активными; subscriptions/payments — ученик видит своё, админ правит.
leads — только персонал; audit_log — читает только админ.

Проверить обязательно. После применения политик залогинься тестовым учеником и попробуй прочитать чужой профиль, чужие платежи и непревьюшный урок неоплаченного курса. Если что-то отдаётся — политика дырявая. Это единственный тест, который нельзя пропустить.

4.5 Структура репозитория

kungfuman-platform/
├── app/
│   ├── (public)/            # лендинги, публичные страницы школ
│   │   ├── page.tsx
│   │   ├── [school]/
│   │   └── courses/[slug]/
│   ├── (student)/           # кабинет ученика
│   │   ├── dashboard/
│   │   ├── schedule/
│   │   ├── progress/
│   │   └── learn/[courseSlug]/[lessonId]/
│   ├── (staff)/             # админка
│   │   ├── students/
│   │   ├── groups/
│   │   ├── sessions/
│   │   ├── attendance/[sessionId]/
│   │   ├── payments/
│   │   ├── curriculum/      # редактор методики
│   │   └── leads/
│   ├── api/
│   │   ├── webhooks/[provider]/
│   │   └── media/sign/
│   └── layout.tsx
├── components/
│   └── ui/                  # shadcn
├── lib/
│   ├── supabase/            # server.ts, client.ts, middleware.ts
│   ├── domain/              # чистая бизнес-логика, без React
│   │   ├── curriculum.ts
│   │   ├── attendance.ts
│   │   ├── billing.ts
│   │   └── progress.ts
│   ├── i18n/
│   └── types/database.ts    # сгенерировано supabase gen types
├── supabase/
│   ├── migrations/
│   └── seed/
├── docs/
│   ├── SPEC.md              # этот документ
│   └── DECISIONS.md         # журнал архитектурных решений
├── CLAUDE.md
└── tests/

ЧАСТЬ II. ПЛАН ЭТАПОВ

Оценки в неделях даны для работы соло с Claude Code, ~15–20 часов в неделю. Если занят проектами по UE — умножай на 1.5.

Этап 0. Операционный контур — начать сегодня

Не код. Идёт параллельно всему остальному и является критическим путём.

Регистрация юрлица, открытие счёта и подключение эквайринга займут больше времени, чем ты напишешь MVP. Если начать это на этапе 3, платформа будет готова, а принимать деньги будет некуда.

Задачи:

Зарегистрировать ИП в Таджикистане (закрывает Худжанд и локальные платежи)
Расчётный счёт + подключение Алиф / DC Wallet / Корти Милли
Проконсультироваться у бухгалтера по контуру для РФ — см. раздел 11
Купить домен (kungfuman.academy или аналог), настроить почту
Завести аккаунты: Supabase, Vercel, Kinescope (триал)

DoD: есть реквизиты, на которые можно принять первый платёж от ученика в Худжанде.

Этап 1. Ядро — 2 недели

Цель: база данных, авторизация, оболочка приложения. Ни одной бизнес-фичи.

Задачи:

npx create-next-app + TypeScript + Tailwind + shadcn/ui
Проект Supabase, применение миграций 00001–00003
Генерация типов: supabase gen types typescript --local > lib/types/database.ts
Auth по телефону + OTP (основной сценарий для Худжанда), email как запасной
Триггер создания profiles при регистрации нового пользователя
Middleware: редирект неавторизованных, разведение по ролям (student → (student), остальные → (staff))
Сид-данные: школа Худжанд, 4 дисциплины, 7 уровней в каждой, твой профиль как owner
Слой i18n: хелпер t(jsonb, locale) с фолбэком на ru

DoD:

Регистрируешься по телефону, попадаешь в пустой кабинет
Тестовый ученик не может прочитать чужой профиль через прямой запрос к API
Типы TypeScript совпадают со схемой БД

Этап 2. Методика — 1 неделя

Цель: твои 7 уровней перенесены в базу и редактируются через интерфейс. Это фундамент всего дальнейшего.

Задачи:

CRUD-экраны в (staff)/curriculum: дисциплины → уровни → практики → критерии
Drag-and-drop сортировка практик внутри уровня
Импорт из твоей концепции: заполнить реальным содержанием все 7 уровней хотя бы по одной дисциплине (Цигун — как самая массовая)
Публичная страница программы: дерево уровней, читаемое без регистрации — это будет продающая страница

DoD: заходишь в админку и видишь всю свою методику как структуру. Можешь добавить практику за 30 секунд.

Этап 3. Офлайн-контур — 2 недели

Цель: перестать вести учёт в тетради и в WhatsApp.

Задачи:

Площадки (venues): набережная Сырдарьи, парк Камоли Худжанди
Группы с расписанием (JSONB: день недели + время + длительность)
Автогенерация sessions из расписания группы на 4 недели вперёд (cron через Supabase Edge Function или кнопка в админке)
Экран отметки посещаемости — проектировать под телефон и под одну руку. Ты отмечаешь людей на набережной в 5 утра, а не за компьютером. Крупные кнопки, работа офлайн с последующей синхронизацией
Планирование практик на занятие (session_practices)
Отметка прогресса ученика по практикам прямо с экрана посещаемости
Карточка ученика: посещаемость, текущий уровень, прогресс, медданные, история

DoD: проводишь реальное утреннее занятие и отмечаешь всех через телефон, не открывая тетрадь.

Этап 4. Деньги — 1.5 недели

Цель: абонементы и учёт платежей.

Задачи:

Продукты и цены: разовое посещение, абонемент 8/12 занятий, безлимит
Оформление абонемента ученику из админки
Ручное подтверждение платежа (перевод на Алиф → админ подтверждает → абонемент активируется)
Автосписание занятий с абонемента (триггер consume_session_credit уже в схеме)
Дашборд: активные абонементы, заканчивающиеся на этой неделе, должники
Экспорт платежей в CSV для бухгалтерии

Не делать на этом этапе: автоматическую онлайн-оплату. При 50 учениках ручное подтверждение занимает 5 минут в день, а интеграция эквайринга — неделю. Автоматизируй, когда станет больно.

DoD: видишь, кто заплатил, у кого сколько занятий осталось, и кто пропал.

Этап 5. Кабинет ученика — 1.5 недели

Цель: ученик перестаёт спрашивать «а когда занятие» в WhatsApp.

Задачи:

Расписание своих групп, запись на занятие
Свой прогресс: текущий уровень, освоенные практики, что дальше
Свой абонемент: остаток занятий, дата окончания
История посещений
PWA: manifest, service worker, установка на домашний экран. Отдельное нативное приложение не нужно
Публичная страница записи на пробное занятие → создаёт lead. Заменяет твою ссылку wa.me, но WhatsApp остаётся как кнопка

DoD: ученик ставит иконку на телефон и видит своё расписание и прогресс.

Этап 6. Онлайн-курсы — 3 недели

Цель: первый продаваемый онлайн-продукт.

Задачи:

Аккаунт Kinescope, загрузка видео, подписанные ссылки через api/media/sign — никогда не отдавать прямой URL видео клиенту
Курсы → модули → уроки; каждый урок ссылается на practice_id
Плеер с сохранением прогресса (lesson_progress, обновление раз в 15 секунд)
Гейтинг доступа: превью-уроки открыты, остальные — через has_course_access()
Продающая страница курса: программа, превью-урок, отзывы, цена по региону
Сертификат по завершении курса (генерация PDF)

Что снимать первым. Курс на базе уровня 1 Цигун, уже обкатанного на живой группе с этапа 3. У тебя к этому моменту есть: понимание, где люди спотыкаются, реальные вопросы учеников, и отснятый материал с утренних занятий.

DoD: курс опубликован, куплен, пройден одним реальным человеком не из твоего окружения.

Этап 7. Регионы и языки — 2 недели

Цель: вторая школа и второй язык без переписывания кода.

Задачи:

Роутинг /[locale]/..., определение локали по домену/гео/выбору
Наполнение tg (таджикский) для публичных страниц Худжанда — сильный сигнал доверия локально
Наполнение en для международных страниц
Отображение цен по региону (product_prices.region)
Создание второй школы в базе, проверка изоляции данных
Онлайн-эквайринг: ЮKassa для РФ (требует РФ-юрлица) или Merchant of Record для мира

DoD: открываешь сайт с российского IP — видишь рубли и РФ-контур; с таджикского — сомони.

Этап 8. Дальше — после 200+ учеников

Идеи, к которым имеет смысл возвращаться только когда база наберётся:

Видеоразбор формы. Ученик снимает своё выполнение практики, система сравнивает с эталоном по ключевым точкам (MediaPipe / Pose Estimation). Вот здесь наконец пригодится твой опыт в 3D и UE.
Сообщество: чаты по уровням, совместные челленджи.
Программа сертификации инструкторов (структура федерации из твоей концепции).
Мобильное приложение на React Native, если PWA упрётся в ограничения.
Ретриты и офлайн-интенсивы как отдельный тип продукта.

ЧАСТЬ III. ОПЕРАЦИОННЫЙ КОНТУР

11. Юридическая и платёжная схема

Дисклеймер: это не юридическая и не бухгалтерская консультация. Ниже — карта вопросов, которые надо задать специалисту, а не готовое решение. Всё требует проверки на месте.

Рынок	Что нужно проверить
Таджикистан	ИП, местный эквайринг (Алиф, DC, Корти Милли). Самый быстрый путь, начинать с него.
РФ	Режим самозанятости (НПД) доступен гражданам РФ и стран ЕАЭС; Таджикистан в ЕАЭС не входит, поэтому этот вариант скорее закрыт без гражданства РФ. Реалистичный путь — ИП в РФ, что имеет требования по резидентству и налогам. Обязательно уточнить у бухгалтера.
РФ, данные	ФЗ-152 требует хранить персональные данные россиян на серверах в РФ. При работе на российскую аудиторию это может означать отдельный инстанс БД в РФ. Уточнить у юриста, попадает ли твой сценарий под требование.
Мир	Stripe не поддерживает Таджикистан. Merchant-of-record сервисы (Paddle, Lemon Squeezy) принимают платежи от твоего имени и решают вопрос налогов, но имеют свои списки допустимых стран для выплат. Проверить актуальные условия до этапа 7.

Вывод для архитектуры: заложи в схему возможность двух инстансов БД (TJ и RU) с общим кодом. Поле schools.country_code и разделение по тенантам это уже позволяют. Не реализуй заранее, но не мешай себе.

12. Как работать с Claude Code

Файл CLAUDE.md в корне репозитория содержит незыблемые правила, стек, команды и стиль (см. корень репозитория).

Порядок работы.

Правильно:

Открываешь новую сессию под один этап.
Промпт вида: «Прочитай docs/SPEC.md разделы 4.2 и 4.4. Реализуй этап 3, задачу 1: площадки (venues). CRUD-экраны в (staff)/venues.»
Проверяешь, коммитишь, идёшь к задаче 2.

Неправильно:

«Вот спека, сделай платформу». Получишь 40 файлов, половина из которых не работает, и не поймёшь, где именно.
Работа над несколькими этапами в одной сессии — контекст переполняется, качество падает.

Правила гигиены.

Один коммит на задачу. Задача не проходит pnpm typecheck — не коммитишь.
Миграции только вперёд. Ошибся — новая миграция, а не правка старой.
DECISIONS.md. Каждый раз, когда отходишь от спеки — записываешь почему. Через три месяца не вспомнишь.
RLS проверяется руками. После каждой новой таблицы — логин тестовым учеником и попытка прочитать чужое. Claude Code напишет политики, но не проверит их за тебя.
Сначала домен, потом UI. Просишь реализовать логику в lib/domain/ с тестами, потом отдельно экран поверх неё. Тогда переделка интерфейса не ломает бизнес-правила.

13. Чеклист первого месяца

Неделя 1

Подана заявка на ИП
Домен куплен, Supabase и Vercel заведены
Каркас Next.js + миграции 00001–00003 применены

Неделя 2

Auth по телефону работает
Сид: школа Худжанд, дисциплины, 7 уровней
RLS проверена руками на тестовом ученике

Неделя 3

Редактор методики готов
Цигун, уровень 1–7 заполнен реальным содержанием
Публичная страница программы опубликована

Неделя 4

Группы и расписание заведены
Экран посещаемости работает с телефона
Проведено реальное занятие с отметкой через платформу

Последний пункт — единственная настоящая метрика первого месяца. Всё остальное можно переделать.

14. Риски

Риск	Как проявится	Что делать
Строишь вместо того, чтобы преподавать	Через 3 месяца отличная платформа и та же группа из 12 человек	Жёсткий таймбокс: 15 часов в неделю на код, не больше
Онлайн-курс до обкатки офлайн	Снят курс, который не продаётся	Не начинать этап 6 раньше, чем уровень 1 пройдут 20 живых человек
Платёжный контур не готов к запуску	Продукт есть, деньги принять нечем	Этап 0 стартует сегодня, а не когда код будет готов
Переусложнение схемы	Полгода на архитектуру, ноль пользователей	Схема выше — потолок. Новые таблицы только под подтверждённую потребность
Выгорание на соло-разработке	Проект замирает на этапе 4	После этапа 5 рассмотреть подрядчика на фронтенд. Ядро и методика остаются у тебя

Документ живой. По мере реализации обновляй разделы 4 и 11 — они устареют первыми.