Перейти к основному содержимому

Snapshot-модели справочника (единый дом платформы)

Единственный дом snapshot-моделей справочных записей для всей платформы: CountrySnapshot, RegionSnapshot, CitySnapshot, CurrencySnapshot. Контракты остальных сервисов (payload событий, модели ответов, хранимые документы) ссылаются сюда и описывают только использование — поля моделей нигде не переописываются.

Назначение​

Snapshot — вложенная display-модель справочной записи, зафиксированная в контракте (обычно — в payload события) на момент публикации. Даёт потребителю человекочитаемые имена без синхронного резолва в handbook и сохраняет исторический след: как называлась запись в момент факта, даже если позже её переименовали или заархивировали.

Классификация​

ПолеЗначение
Контекстhandbook (дом моделей); используются контрактами всех сервисов
KindSnapshot (иммутабельная вложенная модель, не хранимая таблица handbook)
Source of truth полейреплики справочника: country.md, region.md, city.md, currency.md

Модели​

CountrySnapshot​

ПолеТипОбязательностьОграниченияИсточник (поле реплики)
CountryIdshortДа—CountryEntity.Id
IsoCode2stringДаchar(2), ISO 3166-1 alpha-2CountryEntity.IsoCode2
NamestringДа≤ 64 символовCountryEntity.ShortName ?? FullName (ADR-0063 п.2)
к сведению
Семантика CountrySnapshot.Name

У источника Country.ShortName необязателен (краткое имя, напр. «Россия»), FullName обязателен (полное, напр. «Российская Федерация»); каноническое отображаемое имя страны в PIN — ShortName, а при его отсутствии — FullName (country.md, ADR-0063 п.2). Snapshot фиксирует уже разрешённое значение: при пустом ShortName в snapshot попадает FullName (отдельного признака «какое из имён взято» контракт не несёт).

RegionSnapshot​

ПолеТипОбязательностьОграниченияИсточник (поле реплики)
RegionIdlongДа—RegionEntity.Id
NamestringДа≤ 256 символовRegionEntity.Name

CitySnapshot​

ПолеТипОбязательностьОграниченияИсточник (поле реплики)
CityIdlongДа—CityEntity.Id
NamestringДа≤ 256 символовCityEntity.Name

CurrencySnapshot​

ПолеТипОбязательностьОграниченияИсточник (поле реплики)
CurrencyIdshortДа—CurrencyEntity.Id
IsoCodestringДаchar(3), ISO-4217 (уже нормализован репликой)CurrencyEntity.IsoCode
NamestringДа≤ 64 символовCurrencyEntity.Name
Signstring?Нет≤ 16 символовCurrencyEntity.Sign
к сведению
Нормализация IsoCode

Display-код валюты (IsoCode) в контрактах потребителей живёт только внутри CurrencySnapshot — отдельных строковых полей кода валюты контракты не несут (currency.md). IsoCode snapshot-а — нормализованный char(3) реплики: источник хранит код в varchar(16), но значения длиной ≠ 3 в реплику и, следовательно, в snapshot не попадают (reject на синке, INV-HND-6 — currency.md); в snapshot всегда валидный ISO-4217.

Связи​

Каждая snapshot-модель фиксирует значение своей реплики справочника на момент публикации несущего контракта (один источник — множество снапшотов во времени, по одному на каждую публикацию):

Правила использования​

  1. Деньги. Любое событие/контракт с денежной суммой несёт типизированную ссылку CurrencyId short + CurrencySnapshot. Snapshot — display и юридический след; допустимость валюты в операции ограничена ADR-0048 (RUB-only, справочник ≠ мультивалютность).
  2. Гео. События/контракты с географией несут id (CountryId / RegionId / CityId) + соответствующие снапшоты имён (CountrySnapshot / RegionSnapshot / CitySnapshot); состав — по потребности контракта (например, карточка проекта — все три, лид — только город).
  3. Фиксация на момент публикации. Snapshot снимается в момент публикации события/записи документа и не «догоняется»: последующие переименования или архив записи справочника уже опубликованные payload-ы не меняют. Актуальные значения потребитель получает из pin.handbook.*-топиков, публичного lookup или internal resolve — не из старых снапшотов.
  4. Единый дом. Контракты других сервисов ссылаются на этот документ и не переописывают поля моделей; в контракте указывается только факт использования («Price.CurrencyId + CurrencySnapshot — см. handbook/domain/snapshots.md»).
  5. Архивные записи. Snapshot корректно строится и для архивной записи: internal resolve резолвит включая архивные (INV-HND-5, country.md) — исторические события и документы, ссылающиеся на выведенную из оборота запись, остаются полными.
  6. Хранение у потребителей. Канонический паттерн хранимых сущностей — <X>Id (тип источника) + денормализованное display-имя <X>Name, снятое при записи (ADR-0063 п.6); полный snapshot — в payload событий. Обновление денормализованных имён при переименованиях — ответственность потребителя с локальной репликой (chessboard), остальные живут с историческим именем до перезаписи сущности.

Совместимость​

  • Snapshot-модели вкладываются в контракты потребителей и версионируются вместе с несущим контрактом (отдельного ContractVersion у snapshot-модели нет).
  • Изменения моделей — только additive (новые nullable-поля); переименование/удаление/смена типа поля — breaking сразу для всех несущих контрактов платформы и требует сводной ревизии.
  • Неизвестные поля snapshot-а потребитель игнорирует.

Обратные ссылки​

Автоссылки: где используется этот документ.

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