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

Правила Документирования Сущностей

Поля Сущности​

  • Все поля сущности описываются таблицей: имя, тип, обязательность, описание, ограничения, источник значения.
  • Для enum полей перечисляются допустимые значения и смысл каждого значения.
  • Boolean flags не используются для доменных состояний, если состояние может расширяться или участвует в бизнес-правилах.
  • Вместо boolean flags используются enum: VisibilityStatus, ReviewStatus, FeatureState, AvailabilityMode.
  • Magic constants запрещены. Любой конечный набор значений документируется как enum или справочник.
  • Money хранится через decimal + CurrencyId (short, справочник handbook), time через DateTimeOffset, проценты и rates через decimal.
  • Поля с типом object, json, jsonb, metadata, settings, attributes, parameters, payload, context запрещены без отдельной именованной typed модели и таблицы полей.
  • Для полей CountryId/CurrencyId/LanguageId (short) и RegionId/CityId (long) owner service — справочник handbook (ADR-0063); указывается допустимый scope, freshness rule для replica/snapshot и поведение при архивной (IsArchived) записи справочника.

State Transitions​

  • Если сущность имеет status/state, раздел State Transitions обязателен.
  • Каждый переход описывается таблицей: From, To, условие, инициатор, проверки, побочные эффекты.
  • Статус нельзя менять без проверки текущего состояния.
  • Illegal transition должен иметь явный typed error.
  • Для сущностей с жизненным циклом (бронирование, фиксация клиента, сделка, публикация объекта, сессии, провайдерские колбэки) таблица переходов обязательна.
  • Если сущность не является state machine, раздел переходов опускается целиком (заглушка Сущность не имеет state machine не пишется).

Invariants И Concurrency​

  • Инварианты описываются как проверяемые правила на уровне конкретных полей.
  • Если параллельные правки сущности могут затирать друг друга, это фиксируется как бизнес-правило («правка не должна затирать чужую»); конкретный механизм оптимистичной блокировки — деталь реализации и в постановке не указывается.
  • Для append-only сущностей явно пишется, что update/delete запрещены и исправления выполняются correction/reversal записью.
  • Для денежных сумм, исторических снапшотов и провайдерских колбэков описывается, какие поля immutable после создания.

JSON / JSONB В Entity Docs​

  • jsonb допускается только для bounded document model: rule snapshot, external payload snapshot, UI/template variables, provider callback snapshot, audit/event payload.
  • jsonb не используется для обычных связей 1:1, 1:N и M:N.
  • Связи описываются отдельными таблицами связи или дочерними сущностями: например project_amenities, building_layouts, lot_restriction_values.
  • Если поле имеет тип json или jsonb, рядом обязательно описывается его модель в разделе JSONB Модели.
  • JSONB модель описывается как полноценная сущность: поле, JSON path, тип, обязательность, описание, ограничения, допустимые enum значения и правила совместимости.
  • JSONB модель получает явное имя, например BookingDecisionSnapshotModel, ProviderCallbackSnapshotModel, PriceRuleConditionModel; безымянные JSON-фрагменты запрещены.
  • Поле с типом Dictionary<string, string> или Dictionary<string, object> допускается только после замены на typed коллекцию пар, где документированы допустимые ключи, тип значения для каждого ключа, максимальный размер и правила валидации.
  • Если подробная JSONB модель делает entity file больше лимита размера, модель выносится в соседний файл <entity>-json-models.md; основной entity file сохраняет раздел JSONB Модели со ссылкой и кратким индексом моделей.
  • У каждой persisted JSONB модели есть SchemaVersion или внешний version field рядом с агрегатом.
  • Breaking change требует новой версии модели и миграционного/совместимого reader.
  • Для JSONB массивов нужно указать максимальный размер или объяснить, почему коллекция bounded.
  • Для JSONB полей нужно указать GIN/BTREE expression indexes, если поле участвует в фильтрации, или прямо написать, что поле не индексируется и читается только вместе с агрегатом.
  • JSONB не должен содержать secrets, raw PII, access/refresh tokens, provider credentials и unbounded external payload.
  • Если JSONB хранит ссылку на другую сущность, это должен быть snapshot/reference для воспроизводимости решения, а не замена relational foreign key внутри сервиса.

Связи​

  • Связи внутри owning service моделируются явно: FK, link entity или дочерняя entity.
  • Cross-service связи хранят foreign id и snapshot без cross-service FK.
  • M:N связи описываются отдельной таблицей связи с полями и constraints.
  • Если связь историческая и должна быть воспроизводимой, допускается snapshot, но текущая operational связь остается relational.

Replicas И Snapshots​

  • Snapshot хранит состояние чужой сущности на момент события, решения или проводки; он immutable и нужен для audit/replay.
  • Replica хранит актуальную локальную проекцию чужой сущности; она eventually consistent и обновляется через documented consumers.
  • Entity doc для replica обязан иметь явное примечание Это replica, не source of truth.
  • Для replica указываются owner/source service, producer events, consumer docs, freshness policy, stale behavior и поля, которые запрещено хранить.
  • Replica не может содержать raw PII, secrets, payment requisites, tokens и provider credentials, если это не согласовано отдельной security-моделью.
  • Financial/security-critical decisions по stale replica должны быть fail closed, manual review или owner API lookup по описанному алгоритму.

Events, Audit И Observability​

  • Entity doc перечисляет события, которые создают или изменяют сущность.
  • Для сущностей с чувствительными данными указываются audit actions и masked fields.
  • Для критичных state transitions указываются метрики изменения статусов.
  • Инфраструктурные сущности общего назначения не копируются в каждый сервис. Они документируются в shared/common docs, а service docs описывают только business-specific behavior.

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

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