11.02 Configuration Snapshot Requirements

Статус: черновик для обсуждения

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

Этот документ описывает product-level requirements к configuration snapshots, которые должны сохраняться на transaction.

Это не database schema.

Development team должна сама определить:

• exact tables;
• snapshot structure;
• version references;
• normalization/denormalization;
• storage format;
• indexing;
• retention.

Product requirement: transaction details must always be able to explain which configuration was actually used.

2. Что означает transaction configuration

Transaction configuration - это весь набор опубликованных настроек, которые были применены к transaction during processing.

Сюда входят:

• Payment Method / MID configuration;
• first-level routing blueprint;
• MASTER MID GROUP;
• MASTER MID;
• MASTER MID processing fee configuration;
• MASTER MID routing blueprint;
• SUB MID GROUP;
• SUB MID or SUB MID AGGREGATOR;
• SUB MID credentials/config reference;
• velocity rules/result;
• FX/conversion fee snapshot;
• processing fee snapshot;
• provider method/config reference.

Если после transaction эти settings изменились, transaction details должны показывать historical version/snapshot, which was actually used.

3. Why snapshots are required

Configuration snapshots нужны, чтобы:

• расследовать transaction через месяц/год;
• понимать, по каким rules transaction прошла;
• видеть, какой MASTER MID / SUB MID реально использовался;
• понимать, какие fees были применены;
• понимать, какой FX rate был использован;
• не ломать historical transaction details после изменения configuration;
• не зависеть от current published version;
• не терять investigation data after soft-delete/archive.

Без snapshots transaction details могут начать показывать current configuration вместо фактически использованной.

Это недопустимо для payment system.

4. Payment Method / MID configuration snapshot

Transaction должна сохранять version/reference Payment Method / MID configuration, по которой она была создана/processed.

Нужно понимать:

• какой paymentMethodId был передан merchant-ом;
• какая published version была активна at processing step;
• какие first-level routing rules были доступны;
• какой method type represented this configuration.

5. First-level routing blueprint snapshot

Transaction должна сохранять version/reference first-level routing blueprint.

Да, эту version нужно сохранять.

Причина:

• first-level routing determines MASTER MID GROUP;
• rules могут измениться после transaction;
• без version reference невозможно понять, почему transaction ушла в конкретную MASTER MID GROUP.

Snapshot должен позволять расследовать:

• which ruleSet/rule matched;
• which conditions were evaluated;
• which MASTER MID GROUP was selected;
• why fallback/default rule was used, if applicable.

6. MASTER MID GROUP snapshot

Transaction должна сохранять selected MASTER MID GROUP and selection settings used at the moment of selection.

Нужно сохранять:

• selected MASTER MID GROUP reference/version;
• group selection mode: sequence/weight;
• fallback enabled/disabled;
• candidate MASTER MIDs considered;
• selected MASTER MID;
• skipped/rejected MASTER MIDs and reasons, если были.

7. MASTER MID snapshot

Transaction должна сохранять selected MASTER MID and version/reference used.

Нужно сохранять:

• selected MASTER MID;
• MASTER MID version/reference;
• payment method association;
• processing fee configuration used;
• processing fee threshold/tier used, if applicable;
• processing fee calculation result.

Processing fee snapshot обязателен, потому что fee может измениться позже.

8. MASTER MID routing blueprint snapshot

Transaction должна сохранять version/reference routing blueprint inside selected MASTER MID.

Нужно сохранять:

• MASTER MID routing blueprint version;
• matched ruleSet/rule;
• evaluated conditions;
• selected SUB MID GROUP;
• fallback/default behavior, if applied.

9. SUB MID GROUP snapshot

Transaction должна сохранять selected SUB MID GROUP and selection settings used.

Нужно сохранять:

• selected SUB MID GROUP reference/version;
• group selection mode: sequence/weight;
• fallback enabled/disabled;
• candidate SUB MIDs / SUB MID AGGREGATORS considered;
• selected SUB MID or SUB MID AGGREGATOR;
• skipped/rejected candidates and reasons.

10. SUB MID / SUB MID AGGREGATOR snapshot

Transaction должна сохранять selected SUB MID or SUB MID AGGREGATOR configuration version/reference.

Нужно сохранять:

• selected SUB MID or SUB MID AGGREGATOR;
• aggregator flag;
• config version/reference;
• provider method reference;
• non-secret config snapshot/reference;
• credentials/config version reference;
• expiration time used;
• email replacement setting used, if applied;
• FX/conversion fee configuration reference, if applied.

Secret values must never be included in transaction snapshot.

11. Credentials/config snapshot reference

Transaction должна сохранять reference to SUB MID / SUB MID AGGREGATOR credentials/config version used.

Но:

• secret values не сохраняются in transaction;
• secret values не показываются in UI;
• secret values не попадают в audit/export/logs/timeline.

Transaction details can show:

• config version used;
• non-secret config values visible by permission;
• secret field configured/changed state, if needed;
• no actual secret values.

12. Velocity snapshot/result

Transaction должна сохранять applied velocity check result.

Нужно сохранять:

• velocity configuration/rule version used;
• metric checked;
• scope checked: SUB MID / SUB MID AGGREGATOR, customer/user;
• time window;
• limit;
• current value at check time;
• pass/fail result;
• rejection reason if failed;
• fallback action if triggered.

Merchant user should see generic velocity reason if visibility requires it.

Platform user with permission should see detailed velocity result.

13. FX / conversion fee snapshot

Transaction должна сохранять FX / conversion fee snapshot.

Нужно сохранять:

• original amount;
• original currency;
• amount in EUR;
• conversion date/time;
• conversion rate;
• rate source/reference, if available;
• conversion fee configuration used;
• conversion fee amount;
• conversion fee amount in EUR;
• conversion fee amount in original currency;
• final customer amount.

FX/conversion snapshot должен оставаться historical and deterministic.

14. Processing fee snapshot

Transaction должна сохранять processing fee snapshot.

Нужно сохранять:

• MASTER MID processing fee configuration used;
• threshold/tier used;
• current turnover level used for threshold selection;
• fee type;
• fee percent/fixed/min/max if applicable;
• processing fee amount in EUR;
• processing fee amount in original currency, if applicable.

Processing fee оплачивает merchant and does not affect customer amount.

15. Historical visibility after changes/deletes

Если configuration изменилась после transaction, transaction details must still show historical version/snapshot used.

Если version была archived/soft-deleted после transaction, transaction must still be investigable.

Historical transaction details should not break if:

• Payment Method was edited;
• routing blueprint changed;
• MASTER MID changed;
• SUB MID changed;
• SUB MID was soft-deleted;
• SUB MID AGGREGATOR was changed;
• fee configuration changed;
• velocity configuration changed;
• FX configuration changed.

Physical deletion of data required for historical investigation is not acceptable for MVP.

16. Merchant visibility

Merchant user должен видеть historical config snapshot only at levels available to him.

Merchant user can see:

• payment method;
• first-level routing result;
• MASTER MID GROUP;
• MASTER MID;
• merchant-visible fee/FX data if permission allows;
• merchant-created SUB MID/SUB MID GROUP if user has access and permission.

Merchant user must not see:

• platform-hidden SUB MID internals;
• SUB MID AGGREGATOR internals;
• provider credentials/config secrets;
• hidden provider names if no provider access;
• platform-only fallback internals;
• raw provider errors.

17. Platform visibility

Platform user with permission должен видеть full historical config snapshot.

Platform visibility includes:

• all routing levels;
• MASTER MID GROUP and selection settings;
• MASTER MID and processing fee snapshot;
• MASTER MID routing blueprint version;
• SUB MID GROUP and selection settings;
• selected SUB MID / SUB MID AGGREGATOR;
• provider/method references;
• velocity result;
• FX/conversion fee snapshot;
• processing fee snapshot;
• skipped/rejected candidates and reasons.

Secret values still must not be visible even to platform user.

18. Data ownership

Configuration snapshot requirements belong to transaction investigation and processing domain.

Orchestrator Service should own the final transaction configuration snapshot.

Exact storage can be:

• references to immutable versions;
• denormalized snapshot JSON;
• separate snapshot records;
• hybrid approach.

Development team should choose storage design.

Product requirement:

• historical investigation works;
• snapshots survive configuration changes;
• snapshots survive soft-delete/archive;
• visibility rules can be applied;
• secrets are never exposed.

19. Acceptance Criteria

Configuration Snapshot Requirements считаются согласованными для MVP, если:

• Transaction stores Payment Method / MID configuration version/reference.
• Transaction stores first-level routing blueprint version/reference.
• Transaction stores selected MASTER MID GROUP and selection settings.
• Transaction stores selected MASTER MID and processing fee configuration used.
• Transaction stores MASTER MID routing blueprint version/reference.
• Transaction stores selected SUB MID GROUP and selection settings.
• Transaction stores selected SUB MID / SUB MID AGGREGATOR config version/reference.
• Transaction stores credentials/config snapshot reference without secret values.
• Transaction details show historical version/snapshot used, not current configuration.
• Soft-deleted/archived versions remain available for historical investigation.
• Applied velocity rule/result is saved.
• Applied FX/conversion fee snapshot is saved.
• Applied processing fee snapshot is saved.
• Merchant user sees historical config snapshot only at visible levels.
• Platform user with permission sees full historical config snapshot.
• Secret values are never included in snapshots.

20. Open Questions

Product open questions отсутствуют.

Technical/design follow-up:

1. Development team должна выбрать exact snapshot storage approach.
2. Development team должна определить immutable version/reference model.
3. Development team должна определить how visibility filtering applies to snapshots.
4. Development team должна определить retention rules for historical snapshots.
5. Development team должна определить how snapshots are written from async processing.