Payment Orchestrator

Тема

03.12 Configuration Draft, Publish And Versioning ​

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

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

Этот документ описывает lifecycle изменения payment/routing/provider configurations в Back Office.

Главная идея: пользователь не должен случайно сломать live routing одним изменением поля. Все важные изменения должны сначала собираться в draft, затем явно публиковаться.

2. Какие configurations входят в scope ​

Draft / publish / versioning должны применяться к configurations, которые влияют на payment execution:

  • Payment Method / MID routing;
  • MASTER MID routing blueprint;
  • MASTER MID GROUP settings;
  • SUB MID GROUP settings;
  • SUB MID settings;
  • SUB MID AGGREGATOR settings;
  • velocity limits;
  • FX / conversion fee;
  • processing fee;

Обычные сущности, которые не влияют напрямую на routing/payment execution, не требуют Save as draft.

Для них достаточно обычного Save.

Примеры:

  • Merchant;
  • Merchant Group;
  • Brand;
  • User;
  • Role metadata;
  • Provider Access grant/revoke;
  • API key actions, с учетом OTP для sensitive actions.

3. Основной lifecycle ​

Configuration имеет published version и может иметь draft version.

Базовый flow:

  1. User открывает configuration.
  2. User нажимает Create draft.
  3. Система создает draft version как copy текущей published version.
  4. Все изменения сохраняются в draft.
  5. User проверяет изменения.
  6. User указывает publish comment / reason.
  7. User нажимает Publish.
  8. Draft становится новой published version.
  9. Предыдущая published version сохраняется в version history.

Publish comment / reason является обязательным.

Отдельный visual diff / preview перед publish в MVP не требуется.

На странице configuration должна быть version panel, где user видит:

  • current published version;
  • current published version number;
  • active draft, если он есть;
  • active draft version number, если draft существует;
  • previous published versions;
  • versions available for rollback.

4. Draft behavior ​

Draft нужен для того, чтобы:

  • собирать несколько изменений перед активацией;
  • не применять изменение частично;
  • дать user возможность проверить blueprint до публикации;
  • сохранить историю того, что именно было изменено.

Draft не должен влиять на live transaction processing.

Transaction processing использует только published configurations.

5. Publish behavior ​

После publish новая version становится активной.

Новые routing steps должны использовать новую published version.

Если transaction уже создана, но еще не дошла до конкретного routing/configuration step, она должна использовать актуальную published version на момент выполнения этого step.

Это означает:

  • transaction не обязательно закрепляется за старой configuration version в момент создания;
  • если configuration была опубликована после создания transaction, но до выполнения routing step, transaction может использовать новую version;
  • в transaction timeline обязательно нужно сохранить, какая version была использована фактически.

6. Version snapshot in transaction ​

Для investigation система должна сохранять version references, которые были использованы transaction.

Минимально нужно сохранить:

  • payment method configuration version;
  • first-level routing version;
  • MASTER MID GROUP version;
  • selected MASTER MID version;
  • MASTER MID routing version;
  • SUB MID GROUP version;
  • selected SUB MID / SUB MID AGGREGATOR version;
  • velocity configuration version;
  • FX / fee configuration version;

Это нужно, чтобы support/platform могли понять:

  • почему transaction пошла именно по этому route;
  • какие rules были актуальны в момент routing;
  • какие settings повлияли на provider execution;
  • что изменилось после transaction.

7. Rollback ​

Система должна поддерживать rollback configuration на предыдущую published version.

Rollback не должен удалять историю.

Rollback должен создавать новую published version, которая повторяет выбранную старую version.

Пример:

text
v1 published
v2 published
rollback to v1 -> creates v3 published with content from v1

Так сохраняется полная история изменений.

8. Concurrent editing ​

Нужно запретить одновременное редактирование одной configuration несколькими users.

Если один user уже редактирует configuration:

  • другой user может открыть configuration read-only;
  • UI должен показать, кто сейчас редактирует configuration;
  • второй user не может начать edit до тех пор, пока draft не опубликован, отменен или edit lock не истек.

Это правило нужно, чтобы не возникали конфликты и случайная потеря изменений.

Точный edit lock timeout должен предложить development team.

9. Version deletion / archiving ​

User может удалить non-active version из UI, если имеет permission.

Active published version удалить нельзя.

Deletion version должна быть soft-delete / archive, а не физическим удалением данных.

Если version использовалась transaction processing, система должна сохранить техническую возможность расследовать transaction и увидеть фактически использованную configuration version.

Иными словами:

  • UI может скрыть archived/deleted non-active version из обычного списка;
  • transaction timeline и investigation не должны ломаться;
  • physical deletion version history не является MVP behavior.

10. Permissions ​

User может publish changes сам, если у него есть permission на редактирование этой configuration.

Примеры:

  • merchant user с can_edit_payment_method_routing может менять и publish first-level Payment Method / MID routing;
  • merchant user с can_edit_master_mid_routing может менять и publish MASTER MID routing blueprint, если этот MASTER MID доступен ему для редактирования;
  • platform user с соответствующими permissions может менять и publish platform-controlled configurations;
  • merchant user не может publish hidden/internal configuration, созданную platform user, если у него нет доступа к этой configuration.

11. SUB MID disabled during processing ​

Если SUB MID / SUB MID AGGREGATOR был выключен или изменен после создания transaction, но до provider request:

  1. Система не должна отправлять request в inactive SUB MID.
  2. Routing должен пропустить этот SUB MID.
  3. Если в SUB MID GROUP включен fallback, система пробует следующий SUB MID / SUB MID AGGREGATOR.
  4. Если доступных candidates больше нет, система возвращается на уровень MASTER MID GROUP fallback.
  5. Если route полностью exhausted, transaction становится REJECTED.

Если provider request уже был отправлен, transaction продолжает обрабатываться по факту уже начатого provider flow.

12. Audit Log ​

Draft / publish / rollback actions должны попадать в audit log.

Audit log должен сохранять:

  • кто начал edit;
  • кто создал draft;
  • кто изменил draft;
  • кто publish-нул draft;
  • кто отменил draft;
  • кто сделал rollback;
  • кто archive/delete non-active version;
  • какую entity изменили;
  • from version;
  • to version;
  • publish comment / reason;
  • timestamp;
  • safe diff или summary изменений.

Sensitive fields, например credentials, не должны храниться в audit log в открытом виде.

13. Back Office UI Requirements ​

На страницах configuration должны быть видны:

  • current published version;
  • current published version number;
  • draft exists / no draft;
  • active draft version number, если draft существует;
  • кто сейчас редактирует draft;
  • last published by;
  • last published at;
  • version history;
  • archive/delete non-active version action, если user имеет permission;
  • rollback action, если user имеет permission;
  • indication, что live processing использует только published version.

Для blueprint screens нужно визуально отличать:

  • published view;
  • draft editing mode;
  • unpublished changes.

14. Acceptance Criteria ​

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

  • Payment/routing/provider configurations редактируются через draft.
  • Обычные сущности, которые не влияют напрямую на routing/payment execution, используют обычный Save.
  • Draft создается через Create draft как copy текущей published version.
  • Draft не влияет на live transaction processing.
  • Version panel показывает published version number и draft version number, если draft существует.
  • User должен нажать Save / Publish, чтобы изменения стали active.
  • User должен указать publish comment / reason перед publish.
  • Published version используется transaction processing.
  • Если transaction еще не дошла до routing/configuration step, она использует актуальную published version на момент step execution.
  • Transaction timeline сохраняет фактически использованные configuration versions.
  • Version history хранится для payment/routing/provider/velocity/FX/fee configurations.
  • Rollback на предыдущую version поддерживается.
  • Rollback создает новую published version, а не удаляет историю.
  • Non-active version можно archive/delete из UI, если user имеет permission.
  • Archive/delete version не должен ломать transaction investigation.
  • Одновременное редактирование одной configuration несколькими users запрещено.
  • User с edit permission может сам publish-ить изменения.
  • Platform approval для merchant user changes в MVP не требуется.
  • SUB MID, который стал inactive до provider request, пропускается routing execution.
  • Draft/publish/rollback actions пишутся в audit log.
  • Archive/delete non-active version action пишется в audit log.
  • Publish comment / reason сохраняется в audit log / version history.