Handbook API — реестр операций областей public / internal / admin

Индекс HTTP-операций контекста handbook и общие правила областей: модель акторов, маршрутные схемы, сквозные соглашения (видимость архивных записей, пагинация, кэширование, формат ошибок). Файлы операций разложены по областям-акторам (public/, internal/, admin/) и описывают только свою дельту; дом полей справочных записей — ../domain/, дом snapshot-моделей — ../domain/snapshots.md.

handbook — ACL-реплика внешнего Talent Handbook (ADR-0063): API контекста — только чтение и archive/restore. CRUD справочных данных в PIN нет — записи создаёт и обновляет исключительно синк источника (INV-HND-1, ../domain/country.md).

Metadata

Поле	Значение
Сервис/контекст	handbook
Статус	draft
Области	public (lookup для фронтов, аноним), internal (batch-resolve, m2m), admin (archive/restore записей, состояние синка — администратор платформы)

Ошибки — ProblemDetails с кодом. Ведение (создание/правка) справочных данных — в Talent Handbook, не здесь.

Маршрутные схемы областей

Область	Префикс маршрутов	Актор
public	/api/v1/handbook/…	аноним (гость) — авторизация не требуется
internal	/internal/handbook/…	m2m service token внутренних сервисов PIN
admin	/api/v1/admin/handbook/…	администратор платформы через admin API (ADR-0053)

Общие правила областей

Область public (lookup, /api/v1/handbook/…)

Правило	Значение
Actor type	Anonymous — справочники нужны гостю до регистрации (фильтры каталога, формы)
Видимость	только неархивные записи (INV-HND-5, ../domain/country.md)
Tenant isolation	не применяется — справочники платформенные
Кэширование	ответы кэшируемы: Cache-Control: public, max-age=300 — данные меняются редко, устаревание ≤ 5 минут допустимо
Пагинация	только у городов (page/pageSize, default 50, max 200) — единственный справочник в тысячи строк; остальные выдаются целиком

Область internal (batch-resolve, /internal/handbook/…)

Правило	Значение
Actor type	ServiceAccount — m2m service token (client-credentials), не user JWT; policy InternalServiceOnly, allowlist потребителей (chessboard, crm, profile, rewards, promotion, investor-owner)
Видимость	включая архивные (INV-HND-5): исторические ссылки по id не ломаются; решение «допустима ли архивная запись» — за вызывающим
Семантика отсутствия	неизвестный id просто отсутствует в ответе — вызывающий решает, ошибка ли это (и возвращает свой код: CRM_CITY_UNKNOWN, PROFILE_COUNTRY_UNKNOWN, CHESSBOARD_GEO_REF_UNKNOWN и т.п.)
Tenant isolation	не применяется

Область admin (/api/v1/admin/handbook/…)

Правило	Значение
Actor type	Администратор платформы через admin API — отдельная admin-система вне основной Identity (ADR-0053); m2m-токен admin-системы, audience pin.handbook.admin
Permission	handbook.entries.manage (каталог admin-permissions)
Границы	только archive/restore (ручной tombstone для delete-gap источника, ADR-0063 п.5) и диагностика синка; правка реплика-полей администратору недоступна (INV-HND-1)
Audit	обязателен: X-Admin-User-Id (header) — актор каждой команды логируется

Сквозные соглашения областей

Соглашение	Правило
Модели ответов	Internal resolve выдаёт snapshot-модели платформы (CountrySnapshot/RegionSnapshot/CitySnapshot/CurrencySnapshot + IsArchived) — единый дом полей ../domain/snapshots.md; public lookup — проекции реплик (дома полей — ../domain/*.md)
Типы id	как у источника (ADR-0063 п.2): страна/валюта/язык — short, регион/город — long; Guid для справочных записей не используется
Идемпотентность	все операции безопасны для повтора: чтения — по природе; archive/restore — повторный вызов — no-op 200
Событийные эффекты	archive/restore re-publish-ит {x}-upserted в соответствующий compacted-топик pin.handbook.*.v1 (только при фактическом изменении состояния)
Валидация	нарушение формата/диапазонов параметров → VALIDATION_FAILED (400); точечное обращение к несуществующей записи → HANDBOOK_ENTRY_NOT_FOUND (404)

Реестр операций — область public

Пять GET-операций консолидированы в одном документе (единая форма read-only lookup).

#	Операция	HTTP	Route	Документ
1	listCountries	GET	/api/v1/handbook/countries	lookup-references.md
2	listRegions	GET	/api/v1/handbook/regions?countryId=	lookup-references.md
3	listCities	GET	/api/v1/handbook/cities?countryId=&regionId=&search=&page=&pageSize=	lookup-references.md
4	listCurrencies	GET	/api/v1/handbook/currencies	lookup-references.md
5	listLanguages	GET	/api/v1/handbook/languages	lookup-references.md

Реестр операций — область internal

#	Операция	HTTP	Route	Документ
6	resolveReferences	POST	/internal/handbook/resolve	resolve-references.md

Реестр операций — область admin

#	Операция	HTTP	Route	Документ
7	archiveEntry	POST	/api/v1/admin/handbook/{type}/{id}/archive	archive-restore-entry.md
8	restoreEntry	POST	/api/v1/admin/handbook/{type}/{id}/restore	archive-restore-entry.md
9	getSyncState	GET	/api/v1/admin/handbook/sync-state?aggregateType=&status=	get-sync-state.md

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

• Дома полей: ../domain/country.md, ../domain/region.md, ../domain/city.md, ../domain/currency.md, ../domain/language.md; snapshot-модели — ../domain/snapshots.md; инварианты INV-HND-1..5 — ../domain/country.md.
• Синк источника: ../domain/talent-replica.md (правила, HandbookSyncState), ../consumers/talent-handbook-sync.md; пересинхронизация — ../background/talent-initial-import.md.
• События: ../events/{country|region|city|currency|language}-upserted.md.
• Решения: ADR-0063, ADR-0053.