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

Ingestion Layer — Приём, нормализация, маппинг и governance

Версия: 2.0
Дата: 23.04.2026
Статус: Готов к обсуждению

Назначение документа​

Этот документ фиксирует ingestion layer не как технический набор парсеров и очередей, а как полноценный платформенный контур, который отвечает за переход:

supplier reality
  → supplier trace
  → normalized representation
  → mapping and matching
  → governance decision
  → canonical model update
  → downstream operational availability for offers

Именно здесь платформа перестаёт быть пассивным потребителем внешних API и начинает формировать собственную управляемую truth-модель.

Этот документ описывает:

  • как принимаются supplier-данные;
  • как они нормализуются;
  • как сохраняется их trace;
  • как происходят matching, merge и precedence decisions;
  • где появляется human-in-the-loop;
  • как ingestion связан с persistent model, storage layer, offers и governance;
  • как проектировать ingestion для промышленной платформы, а не для “разового ETL”.

Опорные документы​

Этот документ нужно читать вместе с:

Что Исправляет Новый Подход​

Старая версия документа правильно чувствовала, что ingestion — это важный слой, но по сути всё ещё мыслила его как:

  • queue + parser + matcher pipeline;
  • автоматическое превращение “одного отеля у трёх поставщиков” в одну запись;
  • поток технической обработки, а не управляемый доменный контур.

Для промышленной платформы этого недостаточно.

Новый подход исходит из того, что ingestion — это не только throughput и parsing. Это контур, где должны быть формализованы:

  • supplier trace;
  • normalization boundaries;
  • canonical mapping;
  • merge policy;
  • source precedence;
  • confidence model;
  • anomaly detection;
  • manual review;
  • replay and recovery.
  • repricing triggers;
  • publication gating for commercial impact;
  • downstream signals for quote invalidation and settlement-relevant change.

Главная Роль Ingestion Layer​

Ingestion layer нужен не для того, чтобы “засунуть supplier данные в базу”.

Его главная роль:

  1. принять внешнюю supplier reality;
  2. сохранить её trace в платформе;
  3. нормализовать в управляемую внутреннюю форму;
  4. сопоставить с canonical model;
  5. зафиксировать степень уверенности и происхождение;
  6. либо обновить canonical layer,
  7. либо отправить объект в governance / review path,
  8. либо зафиксировать anomaly и не пускать сомнительные данные дальше без контроля.

Ingestion Layer Как Доменный Контур​

Этот слой должен мыслиться как самостоятельный контур, а не как служебная подсистема между API и БД.

В него входят​

  • supplier adapters;
  • fetch / pull / receive logic;
  • raw payload capture;
  • normalization;
  • canonical candidate generation;
  • mapping and matching;
  • merge decision support;
  • source precedence evaluation;
  • anomaly and conflict detection;
  • replay and recovery capabilities;
  • handoff в governance layer;
  • handoff в canonical persistent model;
  • handoff в downstream offer-relevant update flows.
  • handoff в repricing / revalidation candidate flows.

В него не входят как финальные истины​

  • окончательная booking truth;
  • окончательная commercial truth;
  • окончательная identity truth;
  • пользовательские read surfaces как primary concern.

Но ingestion обязан поставлять факты и сигналы, без которых downstream commercial truth не может быть честной.

При этом transport and coordination discipline для этих сигналов отдельно зафиксирована в Eventing And Queue Baseline — Событийная шина, очереди и асинхронная дисциплина платформы.

Уровни Данных В Ingestion​

Ingestion должен жёстко различать несколько уровней данных.

1. Raw Supplier Payload​

Это то, что реально пришло от внешнего источника.

Характеристики:

  • supplier-specific;
  • неканоническое;
  • может быть шумным;
  • может быть неполным;
  • обязано быть traceable;
  • полезно для replay и расследования.

2. Normalized Supplier Representation​

Это внутренняя унифицированная форма supplier-данных.

Она нужна для:

  • дальнейшей обработки;
  • match / merge logic;
  • storage in supplier layer;
  • quality checks;
  • unified downstream reasoning.

Но это всё ещё не canonical truth.

3. Canonical Candidate​

Это кандидат на:

  • создание новой canonical entity;
  • обновление существующей canonical entity;
  • обновление product mapping;
  • обновление content or attribute set;
  • update in supplier mapping layer.

4. Governance Decision Context​

Это набор фактов, по которым система может:

  • автоматически принять решение;
  • отложить объект на ручной review;
  • пометить anomaly;
  • отказать в апдейте canonical layer до подтверждения.

5. Downstream Update Signal​

Это уже не supplier trace, а сигнал, что:

  • canonical inventory изменился;
  • content изменился;
  • pricing/availability projections требуют пересборки;
  • offer-related caches и snapshots нужно пересмотреть;
  • search projections нужно инвалидировать.
  • quote-related publication promises нужно пересмотреть;
  • repricing candidate появился;
  • settlement-relevant downstream interpretation может измениться.

Основные Подконтуры Ingestion​

1. Supplier Intake​

Отвечает за приём и первичную фиксацию данных.

Возможные формы intake​

  • batch file ingest;
  • FTP/XML feed;
  • GraphQL pull;
  • REST polling;
  • webhook intake;
  • scheduled supplier sync;
  • manual import / replay import.

Основная задача​

Не потерять факт поставки и не смешать получение данных с их последующей доменной интерпретацией.

2. Raw Trace Capture​

Отвечает за сохранение сырого следа.

Нужно хранить​

  • supplier identity;
  • payload type;
  • received_at;
  • correlation / run id;
  • source endpoint or file reference;
  • raw payload ref;
  • ingest context.

Почему это обязательно​

Без raw trace платформа не может:

  • повторить обработку;
  • расследовать ошибку;
  • сравнить старое и новое поведение нормализатора;
  • доказать происхождение поля;
  • объяснить спорное canonical решение.

3. Normalization​

Отвечает за приведение supplier reality к внутренней унифицированной форме.

Что сюда входит​

  • field standardization;
  • country / currency / language normalization;
  • geo normalization;
  • amenity normalization;
  • product normalization;
  • text cleanup;
  • semantic classification.

Что сюда не должно входить​

  • окончательное canonical merge decision;
  • final governance resolution;
  • коммерческая интерпретация цены;
  • booking-time semantics.

4. Matching And Mapping​

Это один из самых важных контуров ingestion.

Он отвечает за​

  • поиск вероятных canonical correspondences;
  • property mapping;
  • product mapping;
  • duplicate detection;
  • confidence evaluation;
  • candidate ranking;
  • decision support для governance.

Что нужно различать​

  • automatic match;
  • probable match requiring review;
  • no-match new entity candidate;
  • conflict case;
  • ambiguous multi-candidate case.

5. Merge And Precedence Evaluation​

Даже если mapping найден, это ещё не означает, что нужно автоматически переписать canonical layer.

Нужно учитывать:

  • source precedence;
  • field-level trust;
  • freshness;
  • conflict severity;
  • manual override history;
  • canonical policy.

6. Governance Handoff​

Если система не должна принимать решение автоматически, она обязана передать кейс в governance and review layer.

7. Downstream Publication​

После одобренного обновления ingestion должен публиковать структурный факт изменения:

  • inventory changed;
  • content changed;
  • supplier mapping changed;
  • offer-affecting data changed;
  • cache invalidation required;
  • repricing or revalidation candidate appeared.

Supplier Trace Как Обязательная Часть Архитектуры​

Одна из ключевых идей нового подхода:

supplier trace — это не служебный мусор, а важный persistent слой платформы.

Согласно database-schema.md, supplier-related truth должна жить отдельно от canonical truth.

Что именно нужно сохранять​

  • raw supplier property;
  • raw supplier product;
  • raw supplier content fragments;
  • sync runs;
  • sync events;
  • payload versions;
  • parse failures;
  • normalized intermediate state.

Что это даёт​

  • replay;
  • auditability;
  • compare-before-after;
  • governance explainability;
  • safe algorithm evolution;
  • confidence tuning.

После фиксации коммерческого слоя supplier trace также даёт:

  • explainability для repricing причин;
  • объяснение, почему quote был invalidated;
  • основу для dispute handling между quoted promise и supplier-side economics;
  • базу для reconciliation of supplier inputs versus settlement outputs.

Matching Как Reviewable Process, А Не Как “Скор”​

Одна из ошибок старого подхода — мыслить matching как алгоритм, который просто выдаёт confidence.

Для промышленной платформы этого недостаточно.

Matching должен быть:

  • reviewable;
  • explainable;
  • traceable;
  • replayable;
  • policy-aware.

Что должен давать matcher​

Не только итоговый score, но и:

  • набор кандидатов;
  • факторы совпадения;
  • причины совпадения;
  • причины сомнения;
  • поля-конфликты;
  • recommended action.

Возможные исходы​

  1. auto_accept
  2. review_required
  3. new_entity_candidate
  4. reject_candidate
  5. conflict_unresolved

Почему это критично​

Потому что matching — это не просто технический фильтр. Это точка, где качество данных либо становится активом платформы, либо превращается в постоянную операционную боль.

Field-Level Lineage И Source Precedence​

Ingestion не должен обновлять canonical entity “целиком одним апдейтом”, если разные поля имеют разные источники и разную степень доверия.

Для каждого важного поля нужно понимать​

  • кто был источником;
  • когда значение пришло;
  • было ли оно применено автоматически;
  • влияло ли оно только на canonical content;
  • влияло ли оно на offer/publication;
  • влияло ли оно на repricing or quote validity;
  • влияло ли оно на settlement-relevant downstream interpretation.

Commercially Relevant Ingestion Signals​

После фиксации Commercial Model — Коммерческая модель, цена, settlement и канальные условия ingestion layer обязан различать просто “новые supplier данные” и supplier changes с коммерческими последствиями.

Минимальные Типы Таких Сигналов​

  • price drift;
  • tax/fee component drift;
  • cancellation penalty drift;
  • availability change affecting quote viability;
  • currency basis drift;
  • booking-side economic rule change.

Почему Это Важно​

Не каждое supplier update должно одинаково действовать вниз по платформе.

Одни изменения требуют:

  • обычного cache invalidation;

другие требуют:

  • revalidation;
  • repricing;
  • quote invalidation;
  • blocked publication;
  • downstream settlement review.

Repricing And Quote Invalidation As Downstream Outcomes​

Ingestion layer сам не формирует final visible price, но он обязан уметь порождать структурные сигналы для следующих сценариев:

  • repricing_recommended;
  • quote_revalidation_required;
  • quote_invalidation_candidate;
  • publication_hold_required;
  • settlement_basis_change_detected.

Эти сигналы должны быть:

  • traceable;
  • replayable;
  • explainable;
  • пригодными для governance and operational handling.

Publication Gating For Commercially Sensitive Updates​

Если supplier update влияет на коммерчески значимые поля, ingestion не должен считать downstream publication автоматической по умолчанию.

Особенно Это Касается​

  • supplier price anomalies;
  • suspicious tax/fee changes;
  • inconsistent cancellation terms;
  • out-of-pattern supplier behavior;
  • changes from low-trust or degraded suppliers.

Практический Вывод​

Ingestion должен уметь не только отправить событие “данные обновились”, но и отправить более честный сигнал:

  • данные обновились и безопасны для публикации;
  • данные обновились, но нужен repricing flow;
  • данные обновились, но quote promises должны считаться под риском;
  • данные обновились, но publication должна быть удержана до review.

Что Commercial Model Требует От Ingestion Layer​

После фиксации коммерческого слоя ingestion layer обязан удерживать:

  • различие между supplier economic input и platform commercial output;
  • field-level traceability причин repricing;
  • downstream signals для quote validity и publication safety;
  • сигналы, что settlement basis могла измениться без немедленного изменения visible price;
  • replayable основание для audit, support и reconciliation сценариев.
  • было ли подтверждено вручную;
  • какое precedence rule сработало;
  • какое предыдущее значение было заменено.

Типы precedence policy​

  • preferred source by field;
  • preferred source by region;
  • preferred source by supplier class;
  • most-recent-wins only for selected fields;
  • manual-lock for protected fields;
  • merge-only-if-confidence-above-threshold;
  • do-not-overwrite-with-null-or-weaker-data.

Именно ingestion должен уметь эти политики исполнять или выносить на governance review.

Аномалии И Конфликтные Кейсы​

Промышленная платформа должна считать аномалии нормальной частью реальности, а не редкими исключениями.

Типовые аномалии​

  • supplier резко меняет координаты;
  • supplier suddenly changes star rating;
  • supplier присылает противоречащий address;
  • цена или availability аномально скачет;
  • один supplier product matchится сразу к нескольким canonical products;
  • content becomes poorer than trusted canonical state;
  • duplicate entities suddenly appear after normalization.

Что должно происходить​

Не просто запись в лог, а структурный anomaly workflow:

  • anomaly registration;
  • classification;
  • severity;
  • possible auto-mitigation;
  • review routing;
  • downstream publication policy.

Manual Review Path​

Если платформа серьёзно относится к качеству данных, она обязана проектировать ручной review path как нормальный operational путь.

Review path нужен для​

  • uncertain property match;
  • product ambiguity;
  • content conflicts;
  • suspicious geo changes;
  • questionable supplier precedence;
  • anomaly resolution;
  • protected-field overwrite attempts.

Что должен содержать review case​

  • supplier trace reference;
  • normalized candidate;
  • current canonical state;
  • candidate matches;
  • decision factors;
  • proposed action;
  • diff view;
  • history of related cases.

Replay And Recoverability​

Ингестион без replay model — это не промышленная платформа, а хрупкий pipeline.

Платформа должна поддерживать​

  • replay of raw payloads;
  • replay of normalized records;
  • re-run of matching after algorithm changes;
  • re-run after precedence policy changes;
  • safe reprocessing after downstream failure;
  • partial replay by supplier / region / run / entity class.

Что для этого нужно​

  • raw payload trace;
  • ingest runs;
  • deterministic or explainably versioned normalization logic;
  • versioned matching policy;
  • replay-safe downstream updates.

Ingestion И Storage Layer​

Согласно storage.md, ingestion использует несколько storage classes.

Persistent Store​

Нужен для:

  • supplier trace;
  • normalized supplier representations;
  • mapping outcomes;
  • governance handoff;
  • anomalies;
  • replay metadata.

Rebuildable Cache​

Может использоваться для:

  • short-lived intermediate projections;
  • hot precomputed candidate sets;
  • temporary batching and dedup windows.

Ephemeral Runtime State​

Подходит для:

  • locks;
  • in-flight run markers;
  • short dedup windows;
  • transient orchestrator hints.

Ingestion И Database Schema​

Согласно database-schema.md, ingestion primarily works against:

  • supplier.*
  • governance.*
  • selected core.*
  • selected offer.*

Что ingestion не должен делать напрямую без правил​

  • blindly mutate canonical core entities;
  • overwrite protected fields without precedence evaluation;
  • превращать supplier payload в booking-level truth;
  • публиковать unstable data как confirmed operational basis.

Ingestion И Business Services​

Согласно business-services.md, ingestion не является заменой offer/pricing/booking logic.

Ingestion поставляет​

  • canonical update candidates;
  • supplier trace;
  • governance context;
  • offer-affecting signals;
  • invalidation and refresh triggers.

Business services решают​

  • как использовать canonical inventory;
  • как строить offers;
  • как интерпретировать pricing;
  • как проводить revalidation;
  • как принимать booking decisions.

Это разграничение принципиально важно.

Обновления Цен И Доступности​

Не все supplier updates равны по смыслу.

Stable-content updates​

Примеры:

  • address;
  • name;
  • amenities;
  • descriptions;
  • images;
  • classifications.

Такие обновления чаще идут через canonical and governance path.

Operational updates​

Примеры:

  • availability;
  • price;
  • restrictions;
  • stop-sale;
  • booking conditions.

Такие обновления чаще влияют на:

  • offer.*
  • cache invalidation
  • repricing
  • quote revalidation

Но даже здесь supplier trace должен сохраняться.

Event Model In Ingestion​

Ингестион-контур должен мыслить события как управляемые факты.

Типы событий​

  • supplier_payload_received
  • supplier_payload_failed
  • normalization_succeeded
  • normalization_failed
  • match_auto_accepted
  • match_review_required
  • canonical_update_applied
  • canonical_update_rejected
  • anomaly_detected
  • offer_rebuild_required

Зачем это нужно​

Чтобы downstream системы работали не от “магического апдейта таблицы”, а от понятных и прослеживаемых доменных сигналов.

Надёжность И Масштабирование Ingestion​

Промышленная платформа должна исходить из того, что ingestion:

  • high-volume;
  • noisy;
  • bursty;
  • failure-prone;
  • supplier-dependent;
  • требует safe replay.

Что это означает practically​

  • supplier intake должен быть идемпотентным;
  • deduplication должна существовать явно;
  • partial failure не должен делать весь run непрозрачным;
  • очередь не должна быть единственным местом истины;
  • processing state должен быть recoverable;
  • downstream publication должно быть controlled and repeatable.

Метрики, Которые Реально Нужны​

Throughput Metrics​

  • supplier payloads per run;
  • normalized entities per run;
  • accepted updates per run;
  • anomalies per run;
  • replay volume.

Quality Metrics​

  • auto-match rate;
  • review-required rate;
  • false-match corrections;
  • anomaly rate by supplier;
  • precedence overrides by supplier and field.

Reliability Metrics​

  • normalization failures;
  • replay success rate;
  • stuck run count;
  • time-to-canonical-update;
  • time-to-review-resolution.

Governance Metrics​

  • open review tasks from ingestion;
  • average resolution time;
  • anomaly backlog by type;
  • protected-field overwrite attempts.

Что Должно Быть Перепроверено После Этого Документа​

После стабилизации ingestion model нужно будет синхронизировать:

  • suppliers.md Там supplier integrations нужно будет читать не только как adapters, но и как risk / capability / ingestion sources.

  • api-contracts.md Нужно убедиться, что наружные контракты не делают ложных предположений о freshness и update semantics.

  • clients.md Нужно увязать потребительские surfaces с truth/freshness reality ingestion and offer layers.

Роль Старых Черновиков​

Предыдущая версия документа сохранена в:

Её можно использовать как архив технических идей по pipeline, parser logic и ранним примерам реализации. Но текущей source of truth для ingestion layer является уже новая версия.

Текущий Практический Вывод​

Ingestion layer платформы должен проектироваться так:

  • не как “парсер + очередь + матчинг”;
  • не как технический ETL-проход;
  • не как место, где supplier truth автоматически становится platform truth;
  • а как управляемый контур превращения внешней реальности в canonical platform model через trace, normalization, matching, governance и controlled downstream publication.

Именно в таком виде ingestion становится опорой масштабируемой промышленной платформы, а не источником постоянной неясности и скрытых данных конфликтов.

Уточнение под Фазы 4–6 (28.04.2026) — связь с правилом 00000, isolation, security, events​

Документ опубликован 23.04.2026 (Фаза 3). Ingestion layer — критическая точка реализации правила 00000 (платформа главенствует над поставщиками). После Фаз 4–6 интеграция с новыми доменами требует фиксации.

Главный принцип — правило 00000​

development/Закон 00000 — платформа главенствует над поставщиками.md применяется напрямую к ingestion:

  • Ingestion adapters переводят произвольные supplier representations в каноничную модель Vitiana, не наоборот;
  • canonical Property, CanonicalProduct не подгоняются под структуры конкретного поставщика;
  • captive supplier-specific логика в общем коде запрещена — только в adapter layer;
  • любой поставщик отключаем без переделки каноничной модели.

Связь с tenant isolation​

reference/multi-tenant-isolation-strength.md (Фаза 5):

  • ingestion data per-tenant aware (если supplier обслуживает несколько tenants — отдельные ingestion runs);
  • ingestion writes — tenant_id обязателен во всех canonical writes;
  • supplier credentials изолированы per tenant (см. security-architecture.md).

Связь с security architecture​

reference/security-architecture.md (Фаза 10) — supplier credentials как critical secrets:

  • automated rotation 90 дней;
  • supplier signature verification (для production webhooks);
  • ingestion audit log (что прислал, что сохранили, что отклонили, почему);
  • 7 лет retention для ingestion audit (regulated).

Связь с data platform — supplier events​

reference/data-platform-and-events-tracking.md (Фаза 4) — ingestion генерирует:

  • supplier.intake.received, supplier.intake.parsed, supplier.intake.normalized, supplier.intake.mapped;
  • supplier.sync.started, supplier.sync.completed, supplier.sync.failed;
  • supplier.payload.rejected_to_governance (отклонено в review).

Эти — domain events с at-least-once + ordered per supplier guarantee.

Связь с governance​

reference/data-governance-and-matching.md — ingestion → governance handoff:

  • unmapped supplier entities → governance queue;
  • ambiguous mappings → review;
  • supplier drift → governance может suppress supplier до review.

Связь со статусной машиной бронирования​

reference/booking-state-machine.md (Фаза 5) — supplier ingestion критична для transitions:

  • pending_supplier_confirmation → supplier_confirmed — на основе ingestion supplier response;
  • pending_supplier_confirmation → unknown_external_state — supplier timeout;
  • partially_confirmed — supplier подтвердил часть позиций.

Качество ingestion напрямую определяет SLI 6 (unknown_external_state ratio < 1%).

Связь с supplier metering​

reference/api-metering-and-usage-governance.md (Фаза 3 + Фаза 10 уточнение) — ingestion измеряет:

  • supplier load profile per tenant (cost driver для dynamic pricing partner);
  • supplier-specific quota usage;
  • supplier reliability metrics (для tier-based supplier classification).

Связь с DR — Tier 2 backup​

operations/disaster-recovery-and-capacity.md (Фаза 6) — ingestion data:

  • Supplier trace layer — Tier 2 (RTO 4ч, RPO 30м);
  • Replay capability — supplier traces append-only, replay из любой точки;
  • Tier 1 для booking-related ingestion (если supplier confirmation flow).

Связь с правилом «captive integrations запрещены»​

development/Современные лучшие практики верхнеуровневых платформ.md — каждый supplier через adapter pattern; Stuba — первый adapter, не mainstream supplier. Все следующие поставщики (HomeToGo, и т.д.) — равноправные источники данных.

Связь с relation-to-implementation-baseline​

overview/relation-to-implementation-baseline.md — текущая реализация Stuba module в home-to-go-api/api-module-stuba/ — первый adapter. Долг 2 — hotels schema смешивает canonical + supplier-derived; ingestion должен разделить на canonical layer + отдельный supplier trace layer.

Каноничный итог уточнения​

Ingestion остаётся слоем приёма, но интегрирован:

Уточнение выполнено через no-destruction.