Глоссарий и canonical vocabulary

Паспорт документа

• Статус документа: working reference
• Актуально на: 29 марта 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении доменной модели, API-контракта или терминологических решений
• Область применения: канонический словарь проекта для документации, API и delivery-коммуникации
• Связанные документы:
  • Требования проекта
  • Roadmap
  • API conventions

Цель документа

Этот документ убирает терминологический drift между кодом, roadmap, спеками и handoff-слоем. Если в разных документах встречаются конкурирующие формулировки, каноническими считаются термины из этого словаря.

1. Базовые сущности

Account

Базовая учётная запись аутентификации. Account хранит credentials, тип аккаунта и статус аккаунта.

Buyer

Покупательская роль аккаунта. Buyer не равен отдельной системе аутентификации. Один account может иметь buyer-роль как часть multi-role модели.

Parent buyer

Buyer типа PARENT, который может вести список детей и управлять их интересами/заявками.

Student buyer

Buyer типа STUDENT, который действует от собственного профиля и не ведёт список детей.

Seller

Продавец образовательных услуг. Seller-профиль связан с account и содержит профильные поля, адреса, Telegram binding и продуктовый каталог.

Seller staff

Сотрудник продавца. Канонический термин — SELLER_STAFF. Это отдельный account type, а не “подтип seller”.

Admin

Внутренняя административная роль платформы.

2. Продуктовые сущности

Item

Канонический backend-термин для продаваемой единицы в каталоге. Во frontend и продуктовых текстах допустимо называть его “курс”, но source-of-truth термин в API и data layer — item.

Lead

Заявка buyer на item или seller.

Review

Отзыв buyer по item.

Subject

Справочник направлений/предметов. Канонический публичный endpoint — /api/v1/subjects.

Address

Физический адрес seller-профиля.

Roadmap-портал

Внутренний сервис документации на домене qadam-roadmap.2fab.app, runtime которого живёт в qadam-web/apps/roadmap.

3. Канонические статусные модели

Account status

• ACTIVE
• UNDER_REVIEW
• BLOCKED

Не использовать альтернативы вроде approved, suspended или disabled, если речь идёт именно о текущем account status.

Moderation status item

• PENDING
• ACTIVE
• REJECTED

Для item source-of-truth статус публикации — ACTIVE. Не использовать approved как отдельный статус.

Lead status

• CREATED
• CONTACTED
• ENROLLED
• REJECTED

Старые названия вроде pending, processing, not_purchased считаются legacy/историческими и не должны использоваться как current transport contract.

4. Канонические write-contract термины

• Buyer profile: канонический write-method — PATCH /api/v1/me/profile
• Seller profile: канонический write-method — PATCH /api/v1/seller/profile
• PUT на этих маршрутах допустим только как legacy alias
• Registration flow: канонический новый контракт — POST /api/v1/auth/register/buyer и POST /api/v1/auth/register/seller
• Старый POST /api/v1/auth/register — legacy route

5. Термины, которые считаются deprecated

6. Термины уровня документации и delivery

Roadmap

Стратегический план развития проекта. Источник истины: docs/project/roadmap.md.

Execution checkpoints

Операционный документ, который показывает, какие этапы реализации фактически закрыты, какие в работе и какие заблокированы. Источник истины: docs/project/execution-checkpoints.md.

Project change log

Хронология реально выполненных change packages на уровне платформы. Источник истины: docs/project/project-change-log.md.

Frontend change log

Специальный changelog для внешней frontend-команды по backend/API пакетам. Источник истины: docs/frontend/frontend-change-log.md.