KSAILab Platform - Детальная архитектурная документация

Статус раздела

Актуализация выполнена для архитектурного ядра, на котором сейчас строится миграция платформы:

• 02-backend-platform — актуализирован под фактический backend-репозиторий и целевую роль backend в KSAILab.
• 06-authorization — полностью переосмыслен под Keycloak вместо Zitadel и дополнен разделением между landed baseline и следующей logout/session wave.
• 09-frontend-platform — добавлен новый раздел про текущий фронт, его ограничения и целевую permission-модель.
• 10-development-workflow — добавлен раздел с единым flow разработки, тестов, changelog и merge request процесса.

Остальные разделы остаются полезными как контекст по инфраструктуре, CI/CD, Celery и сетевым потокам, но их нужно читать с поправкой на то, что часть старых упоминаний Zitadel и старой auth-схемы там ещё не перенесена в новую модель.

Назначение

Этот раздел описывает не просто "как платформа задумана", а:

• какие компоненты реально участвуют в текущей реализации;
• какие части системы сейчас являются legacy;
• какую целевую архитектуру нужно реализовать для KSAILab;
• какие ограничения уже диктуют backend, frontend и IAM-слой.

Главное архитектурное решение этой итерации:

• Keycloak становится единственным IAM-компонентом платформы;
• backend становится владельцем canonical browser auth flow, точкой исполнения RBAC/ABAC и поставщиком capability manifest;
• frontend получает права через /auth/me и рендерит UI по capabilities, а не по жёстко зашитым ролям.

Для текущей auth-документации теперь важно читать ещё одну boundary:

• landed baseline уже фиксирует backend-owned browser auth surface;
• следующая wave отдельно фиксирует target contract для opaque browser cookie, server-side auth session, full platform logout и различия между local app logout и full SSO logout;
• до завершения backend-ksailab#14, frontend-ksailab#8 и ksailab-keycloak-scripts#9 target contract нельзя описывать как уже везде landed runtime.

Как читать раздел

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

1. 06-authorization/README.md — целевая auth-модель и контракты доступа.
2. 06-authorization/account-provisioning.md — как заводятся преподаватели, группы и студенты в первой версии.
3. 06-authorization/permission-administration-model.md — где живут capabilities, bundles, assignments и что именно настраивается в Keycloak.
4. 10-development-workflow/README.md — issue-first flow, тестовые гейты, devlog/changelog и MR-процесс.
5. 10-development-workflow/gitlab-instance-and-mcp.md — канонический GitLab-инстанс, MCP setup и fallback для агентов.
6. 02-backend-platform/README.md — текущие ограничения backend и целевая backend-архитектура.
7. 09-frontend-platform/README.md — текущий фронт, меню, route guards и ограничения UI.
8. 06-authorization/permission-catalog.md — каталог capabilities.
9. 06-authorization/frontend-permission-matrix.md — привязка текущих экранов к правам.
10. 06-authorization/migration-from-zitadel.md — карта миграции документации и реализации.

Карта разделов

Ключевые решения, от которых теперь нужно отталкиваться

1. IAM

• Используем Keycloak, а не Zitadel.
• Realm roles: admin, teacher, student.
• User lifecycle управляется через platform UI + Keycloak Admin API.
• Первая версия onboarding работает без почты и внешнего SSO: admin заводит аккаунты вручную через platform UI.

2. Авторизация

• Глобальный доступ к разделам и кнопкам даётся через capability catalog.
• Сам каталог capabilities живёт как контракт в backend/docs, а рабочее администрирование bundles и assignments выполняется в platform UI.
• Тонкая проверка по конкретным курсам, группам, темам, лабораторным, авторам и студентам остаётся в backend как ABAC.
• UI-права не считаются источником истины: backend всегда перепроверяет доступ.

3. Backend

• Backend уже landed в Keycloak-first runtime contract для human/browser auth.
• Canonical browser entry/callback/logout теперь принадлежат backend session surface: /api/v1/auth/login, /api/v1/auth/callback, POST /api/v1/auth/logout.
• Backend также остаётся единственной точкой расчёта effective_capabilities и resource-scoped ABAC.
• Следующая auth wave отдельно вводит target contract: browser cookie должен быть opaque session key, auth session и токены должны жить server-side, а продуктовая кнопка Выйти должна означать full platform logout, а не только local session cleanup.

4. Frontend

• Текущий Nuxt-фронт уже задаёт реальную поверхность прав: меню, страницы, настройки, monitoring, permissions.
• Сейчас frontend находится в transition-состоянии: /auth/me и post-session bootstrap уже aligned с backend-owned contract, а для logged-out всё ещё существует временный UX gap до полного platform logout.
• Именно эта поверхность используется как база для capability catalog и permission matrix.

Что ещё остаётся синхронизировать после этой итерации

• Упоминания Zitadel в инфраструктурных разделах и схемах.
• Схемы и draw.io-диаграммы, где auth-контур ещё подписан как Zitadel.
• Детали по namespace и остальным сетевым потокам за пределами уже синхронизированного browser auth contract.
• Финальный runtime rollout для full platform logout, Redis-backed auth session и Keycloak post-logout redirect contract.

Пока эти части не обновлены, источником истины по auth и permission-модели нужно считать раздел 06-authorization и связанные с ним материалы.

Особенно важно читать вместе:

• 06-authorization/README.md — архитектурные принципы;
• 06-authorization/account-provisioning.md — модель завода аккаунтов и onboarding;
• 06-authorization/permission-administration-model.md — operating model и администрирование;
• 06-authorization/permission-catalog.md — словарь прав;
• 06-authorization/frontend-permission-matrix.md — фронтовая поверхность прав.
• 10-development-workflow/README.md — сквозной engineering flow для frontend/backend/keycloak/docs.
• 10-development-workflow/gitlab-instance-and-mcp.md — как агенты должны работать с gitlab.fxserver.ru и GitLab MCP.