08. Глоссарий
Сокращения, термины проекта и где что лежит в коде.
Общие термины
LMS — Learning Management System.
MVP — Minimum Viable Product.
RLS — Row-Level Security (Postgres). Изоляция школ на уровне строк.
RBAC — Role-Based Access Control. У нас: platform_admin / school_admin / teacher / student.
JWT — JSON Web Token, используется для access/refresh.
ADR — Architecture Decision Record. Файлы в docs/decisions/NNNN-*.md.
TTL — Time To Live (access 15min, refresh 2 months rolling).
SLA — Service Level Agreement.
Роли
| Роль | В БД | Что делает |
|---|---|---|
| platform_admin | users.is_platform_admin = TRUE |
Владелец платформы, видит всё |
| school_admin | user_memberships.role_code = 'school_admin' |
Админит одну школу |
| teacher | user_memberships.role_code = 'teacher' |
Создаёт курсы |
| student | user_memberships.role_code = 'student' |
Проходит курсы |
Сущности БД (главные)
| Таблица | Что хранит |
|---|---|
schools |
Школы (теннант) |
users |
Аутентификация |
user_memberships |
Связка user × school × role |
course_drafts |
Черновики курсов (editable) |
published_courses |
Замороженные версии курсов (v1, v2, ...) |
course_translations |
Переводы на другие языки |
glossary_entries |
Термины для `{{term:id |
media_assets |
Сгенерированные картинки/аудио/видео (MinIO URI) |
agent_prompts |
Append-only статические промпты агентов (ADR-0011) |
llm_cost_entries |
Cost tracking каждого LLM-вызова |
payment_providers |
Конфиг провайдеров платежей |
payment_events |
Webhook'и (идемпотентные) |
learner_events |
События обучения (view/attempt/pass/fail/complete/skip) |
adaptive_blocks |
Закэшированные адаптивные подсказки |
ER-диаграмма — через MCP lms-db.er_diagram или docs/db/schema.md.
Runtime-агенты (packages/agents/)
| Slug | Роль | Tier |
|---|---|---|
| Harvester | Нормализует исходники | FAST |
| DocumentIngestor | Чанкинг | FAST |
| EmbeddingComputer | pgvector embeddings | — (Gemini Embedding) |
| Curator | Отбор релевантного | PRO |
| Architect | Структура курса | REASONING |
| Composer | Генерит все блоки | PRO |
| NarrativeKeeper | Связность | FAST |
| GlossaryCurator | Термины | FAST |
| Critic | 36 проверок качества | REASONING |
| Publisher | Финализация в published_courses | — |
| Localizer | Перевод курсов | PRO |
| AdaptiveSupplementer | Адаптивные подсказки студентам | FAST |
ModelTier — enum в packages/shared/llm_client.py. FAST = gemini-3.1-flash-preview, PRO = gemini-3.1-pro-preview, REASONING = gemini-3-pro-image-preview-class (см. manifest §3).
Типы блоков (packages/block_types/)
text, quiz_single, quiz_multi, flashcard_deck, ordering, matching, fill_in_the_blank, code_runner, image, audio, embed.
Для каждого — пять файлов:
packages/block_types/<type>/
schema.py Pydantic модель контента
generator.py Промпт + post-processing
validator.py Доп. правила валидации
renderer.tsx React-компонент для студента (скомпилирован в frontend)
registry entry packages/block_types/registry.py
Детали для student'а: 04-student.md.
Workflows (packages/workflows/)
| Workflow | Назначение |
|---|---|
CourseGenerationWorkflow |
Сгенерировать курс с нуля |
CourseLocalizationWorkflow |
Перевод существующего курса |
MediaGenerationWorkflow |
Сгенерировать медиа-артефакты |
CriticReworkWorkflow |
Прогнать Rework → Critic loop |
Правила workflow: без datetime.now(), без I/O, только activities. prompt_snapshot пробрасывается первой activity (ADR-0011).
Пути в проекте
| Артефакт | Путь |
|---|---|
| Манифест | docs/PROJECT_MANIFEST.md |
| ADR | docs/decisions/*.md |
| Backend API | packages/core/main.py + packages/core/api/*.py |
| Миграции | packages/core/migrations/versions/*.py |
| Агенты | packages/agents/<slug>/ |
| Workflow | packages/workflows/ |
| Блоки | packages/block_types/<type>/ |
| LLM-клиент | packages/shared/llm_client.py |
| Prompt registry | packages/shared/prompt_registry.py |
| Frontend | frontend/app/ |
| Дизайн-система | frontend/app/globals.css (.lms-*) |
| Docker | infra/docker-compose.dev.yml |
| Тесты | tests/ |
| Скрипты | scripts/ |
| MCP-серверы | tools/mcp_servers/<name>/ |
Команды-шпаргалка
# Инфра
docker compose --env-file .env.local -f infra/docker-compose.dev.yml up -d
docker compose --env-file .env.local -f infra/docker-compose.dev.yml down
# API / Web / Worker
make dev-api
make dev-web
.venv/bin/python -m packages.workflows.worker # Temporal worker (Makefile-таргета нет)
# Тесты
.venv/bin/pytest -q tests/
cd frontend && npx tsc --noEmit
# БД
.venv/bin/alembic upgrade head
.venv/bin/alembic current
bash scripts/backup_db_to_minio.sh <tag>
# MCP smoke
make mcp-test
# Promo new prompt version
.venv/bin/python -m scripts.prompt_cli publish <slug> --file body.txt --notes "..."
Внешние ссылки
- FastAPI docs: https://fastapi.tiangolo.com/
- Temporal Python SDK: https://docs.temporal.io/dev-guide/python
- PostgreSQL RLS: https://www.postgresql.org/docs/16/ddl-rowsecurity.html
- pgvector: https://github.com/pgvector/pgvector
- Gemini API: https://ai.google.dev/gemini-api/docs
- Next.js App Router: https://nextjs.org/docs/app
- shadcn/ui: https://ui.shadcn.com/
- Judge0: https://judge0.com/
Конец набора руководств. Стартовая точка — README.md.