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

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

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

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

Этот документ убирает терминологический 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

| Deprecated | Канонический термин |
|-----------|----------------------|
| `course` как transport/model термин | `item` |
| `approved` как item status | `ACTIVE` |
| `PUT /me/profile` как основной контракт | `PATCH /me/profile` |
| `PUT /seller/profile` как основной контракт | `PATCH /seller/profile` |
| `legacy monorepo` как production source of truth | split-репозитории `qadam-core` и `qadam-web` |

## 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`.