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

ADR-0050: Разделение API-контрактов и Domain JSONB-моделей

Статус​

Принято

Контекст​

Публичные API forms и Application results напрямую использовали Domain.JsonDocuments (DictionarySchemaDocument, CatalogEntryPayload, SchemaDocument). Клиенты получали системные поля (SchemaVersion, Signature, DocumentVersion, import Meta) и должны были знать server-generated идентификаторы (FieldId) при создании сущностей.

Решение​

  1. Три слоя моделей: Domain JSONB (persistence) → Application CRUD contracts (API) → Api forms (HTTP binding).
  2. Явные типы по операции: Create*, Update*, Get*, List*Entry — без универсальных *Input/*View/*Upsert*.
  3. Create: FieldKey (slug) required; FieldId отсутствует в типе; server генерирует Guid.
  4. Update: FieldId для существующих полей; новые поля — только FieldKey.
  5. Get: FieldId + FieldKey + read-only metadata (SchemaVersion, Signature, …).
  6. Mappers: ToDocument(Create*), ToDocument(Update*, existing), ToGetModel(document) в Application.
  7. Именование API: Schema, FieldValues, EntryFields вместо SchemaJsonb/DataJsonb; EF column names не меняются.
  8. Идентификаторы: DictionaryId, CatalogEntryId в queries/results вместо generic Id.

Последствия​

  • Breaking change для OpenAPI и generated frontend clients.
  • Дублирование полей между Create/Update/Get компенсируется строгой типизацией и отдельными validators.
  • Domain JSONB может эволюционировать независимо от API при сохранении mappers.

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

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

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