Reference-данные

Зачем нужно

Документ описывает общеплатформенные справочники: subject, level, format, grade_range. Они используются всеми 7 доменами и не принадлежат ни одному из них.

Сущности

`subject`

Каноническая образовательная область платформы.

Поле	Тип	Описание
`key`	string	стабильный ключ, snake_case (`mathematics`, `informatics`, `programming`)
`title`	i18n object	отображаемое имя
`description`	i18n object	описание
`parent_key`	string?	для иерархических направлений
`display_order`	int	порядок отображения
`is_active`	bool	можно ли назначать новые сущности

`level`

Каноническая шкала сложности внутри направления.

Поле	Тип	Описание
`key`	string	`beginner`, `basic`, `advanced`, `olympiad`, `pro`
`title`	i18n object	имя
`display_order`	int	порядок
`is_active`	bool

`format`

Способ доставки обучения.

Поле	Тип	Описание
`key`	string	`online_course`, `intensive`, `mini_group`, `circle`, `individual`, `offline`, `competition`
`title`	i18n object
`description`	i18n object
`is_active`	bool

`grade_range`

Возрастной/школьный диапазон.

Поле	Тип	Описание
`key`	string	`g1-2`, `g3-4`, `g5-6`, `g7-8`, `g9-11`, `adult`
`min_grade`	int?	школьный класс от
`max_grade`	int?	до
`min_age`	int?	возраст от
`max_age`	int?	до
`title`	i18n object
`display_order`	int
`is_active`	bool

Владелец

Платформа. Runtime-хранение обслуживает identity-api как текущий platform host; ownership остаётся у platform-слоя, а не у identity-домена. Управление справочниками — административная функция, доступная по permission platform.reference-data.manage.

UI управления справочниками — в identity-admin-web (как наиболее платформенный фронтенд).

Хранение

Справочники хранятся:

источник истины: packages/reference-data (TypeScript) с migration в БД identity (или отдельный platform-сервис в будущем);
доменные сервисы кэшируют справочник локально и обновляются по событию platform.reference_data.changed.

Это сознательный компромисс: чтобы доменам не нужен был online-call за справочником при каждом запросе.

API

Чтение:

GET /api/v2/platform/reference/subjects
GET /api/v2/platform/reference/levels
GET /api/v2/platform/reference/formats
GET /api/v2/platform/reference/grade-ranges

Управление:

POST   /api/v2/platform/reference/<entity>
PATCH  /api/v2/platform/reference/<entity>/{key}
DELETE /api/v2/platform/reference/<entity>/{key}

Удаление допускается только для неиспользованных ключей; иначе — is_active = false.

События

Пока отдельного domains/platform/events.md нет, platform-owned события для ../integrations/platform--all.md фиксируются здесь.

platform.reference_data.changed — при создании/обновлении/деактивации.
- data: { entity: 'subject'|'level'|'format'|'grade_range', key: string, action: 'created'|'updated'|'deactivated' }.
platform.feature_flag.changed — при создании/изменении/отключении platform-owned feature flag.
- data: { flagKey: string, service?: string, action: 'created'|'updated'|'disabled', version: number }.
platform.i18n.changed — при публикации или отзыве пакета переводов.
- data: { locale: string, namespace?: string, action: 'published'|'revoked', version: string }.

Подписаны: доменные сервисы, использующие соответствующий platform artifact.

Использование в доменах

Доменная сущность ссылается на ключ справочника, а не дублирует поля:

{
  subjectKey: 'mathematics',
  levelKey: 'advanced',
  formatKey: 'mini_group',
  gradeRangeKey: 'g5-6'
}

Денормализация имени для UI — на уровне backend (через локальный кеш) или frontend (через справочник в packages/reference-data).

Запрещено

Локально определять subject, level, format, grade_range внутри домена.
Хранить названия справочников в качестве источника связи (использовать key).
Удалять справочный ключ, на который есть ссылки.
Менять смысл существующего ключа (создавать новый ключ).

Зачем нужно​

Сущности​

subject​

level​

format​

grade_range​

Владелец​

Хранение​

API​

События​

Использование в доменах​

Запрещено​

Связанные документы​