03.07 Transaction Investigation And Timeline

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

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

Этот документ описывает transaction investigation flow и transaction timeline.

Цель:

• дать platform/support пользователям возможность расследовать transaction без помощи разработчиков;
• дать merchant users безопасную видимость по transaction;
• сохранить полный internal trace для platform users;
• скрыть provider-sensitive и platform-created internal configuration от merchant users;
• обеспечить auditability всех важных событий transaction lifecycle.

2. Кто видит transaction timeline

Transaction timeline могут видеть:

• platform users с соответствующей permission;
• merchant users с соответствующей permission.

Доступ к timeline всегда permission-based.

3. Уровни видимости timeline

Нужно поддержать разные уровни видимости:

• merchant_safe;
• platform_only;
• sensitive_platform_only.

Это может быть реализовано как один timeline с masking/filtering, но продуктово должны существовать разные visibility levels.

Event dictionary описан отдельно:

08-dictionaries/06-transaction-timeline-event-dictionary.md

4. Merchant-safe timeline

Merchant user может видеть timeline events, если:

• у него есть доступ к merchant / merchant group;
• у него есть permission смотреть transaction timeline;
• event не раскрывает скрытую provider/internal информацию;
• event относится к сущностям, которые merchant user имеет право видеть.

Merchant user может видеть:

• transaction created;
• payment method selected;
• MASTER MID GROUP selected;
• MASTER MID selected;
• status changed;
• webhook sent;
• webhook failed;
• webhook retried;
• manual webhook resend;
• transaction correction, если есть permission;
• expiration;
• legacy marker;
• merchant-visible routing events;
• error code / description.

5. Merchant visibility for SUB MID entities

Merchant user может видеть:

• SUB MID;
• SUB MID GROUP;

только если:

• merchant user получил возможность создавать эти сущности;
• merchant user создал эти сущности;
• у merchant user есть соответствующая permission.

Если SUB MID / SUB MID GROUP были созданы platform admin, merchant user не должен видеть их внутреннее устройство.

SUB MID AGGREGATOR не должен отображаться merchant user-у как отдельная execution entity внутри SUB MID GROUP.

Merchant user не видит:

• provider raw response;
• provider raw callback;
• provider raw error;
• key/secret data;
• provider-specific internal routing, если оно создано platform admin;
• internal provider failure reasons;
• hidden fallback internals;
• platform-only operational metadata.

6. Platform/support timeline

Platform user с permission должен видеть full internal timeline.

Platform/support может видеть:

• full routing trace;
• first-level rule matched;
• MASTER MID GROUP selected;
• MASTER MID selected;
• MASTER MID blueprint rule matched;
• SUB MID GROUP selected;
• SUB MID selected;
• SUB MID AGGREGATOR selected;
• fallback attempts;
• fallback reasons;
• provider request sent;
• provider payment URL received;
• provider response received;
• raw provider callback;
• provider callback validation result;
• provider status mapping;
• raw provider error;
• merchant webhook payload;
• merchant response code/body;
• correction details;
• audit links;
• ignored callbacks;
• suspicious callbacks;
• duplicate callbacks;
• full fallback chain;
• skipped candidates;
• skip/fallback reasons;
• configuration versions used;
• payload references, если permission позволяет;
• requestId/correlationId, если доступно.

7. Required timeline events

Timeline должна поддерживать events:

• transaction_created;
• validation_failed;
• routing_started;
• payment_method_selected;
• rule_matched;
• master_mid_group_selected;
• master_mid_selected;
• master_mid_rule_matched;
• sub_mid_group_selected;
• sub_mid_selected;
• sub_mid_aggregator_selected;
• velocity_checked;
• velocity_rejected;
• dynamic_attributes_required;
• dynamic_attributes_submitted;
• provider_request_sent;
• provider_response_received;
• provider_payment_url_received;
• provider_error_received;
• provider_callback_received;
• provider_callback_validated;
• provider_callback_rejected;
• provider_callback_ignored;
• duplicate_callback_ignored;
• unknown_provider_status_ignored;
• status_changed;
• webhook_created;
• webhook_sent;
• webhook_delivered;
• webhook_failed;
• webhook_retry_scheduled;
• webhook_retry_exhausted;
• manual_webhook_resend;
• manual_correction_applied;
• expiration_applied;
• legacy_marker_added;
• error_mapped;
• raw_payload_saved.

8. Timeline event structure

Каждый timeline event должен содержать:

• event ID;
• transaction ID;
• event type;
• timestamp;
• source;
• actor;
• visibility level;
• message;
• reason;
• metadata;
• previous status, если применимо;
• new status, если применимо.
• config version refs, если применимо;
• payload reference, если применимо;
• request ID / correlation ID, если доступно.

Metadata должна учитывать visibility rules. Merchant-safe representation не должна раскрывать скрытые provider/internal данные.

Raw payload не должен храниться прямо внутри timeline event.

Если event относится к raw provider callback/request/response или merchant webhook payload, timeline должен хранить только payload reference.

Payload reference - это id/link на payload, сохраненный отдельно с отдельными permission/security/retention rules.

Raw payload details открываются только по explicit user action и только если permission позволяет.

Request ID / correlation ID - это технический identifier, который помогает связать timeline, logs, provider request, callback and webhook delivery.

Exact naming (requestId, correlationId, traceId) должна определить development team.

9. Event source / actor

Для каждого event нужно хранить source / actor.

Возможные sources:

• system;
• provider;
• platform user;
• merchant user;
• merchant API;
• hosted form;
• webhook worker;
• routing engine;
• provider callback worker;
• migration tool.

Если event создан пользователем, нужно хранить actor user.

Если event создан system component, нужно хранить component/source.

10. Timeline filtering

Timeline должна поддерживать фильтры.

Минимальные filters:

• status events;
• routing events;
• provider events;
• webhook events;
• audit/manual events;
• errors only.

Это нужно, чтобы support мог быстро разобраться в длинном transaction flow.

11. Transaction details page

Transaction details page должна содержать блоки:

• summary;
• current status;
• amount/currency;
• merchant;
• brand;
• payment method;
• customer data;
• visible routing result;
• fees/FX;
• timeline;
• provider callbacks;
• merchant webhooks;
• audit/corrections;
• raw provider data, только для platform users с permission.

Transaction details page в MVP должна иметь следующие sections/tabs:

• Summary;
• Timeline;
• Webhooks;
• Provider callbacks;
• Routing;
• FX / Fees;
• Audit / Corrections;
• Raw Payloads.

Tabs должны отображаться based on permissions and visibility rules.

Merchant user должен видеть merchant-safe representation sections/tabs.

Минимально merchant user может видеть:

• Summary;
• Timeline;
• Webhooks;
• Routing;
• FX / Fees, если есть permission;
• Audit / Corrections, если есть permission.

Merchant user не должен видеть Provider callbacks tab.

Merchant user должен видеть Routing tab always, но только в merchant-safe representation:

• first-level Payment Method / MID routing;
• MASTER MID GROUP;
• MASTER MID;
• visible route result;
• hidden/internal entities as hidden placeholders, если они созданы platform user и не доступны merchant user-у.

Merchant user не должен видеть hidden second-level routing / provider internals, если нет специального доступа.

12. Merchant transaction details

Merchant user с permission может видеть:

• summary;
• status;
• amount/currency;
• payment method;
• visible routing level;
• webhooks;
• webhook payload;
• webhook response code/body;
• error code;
• error description;
• merchant-safe timeline;
• fees;
• customer data.

Merchant видит только те данные, которые разрешены его permissions и visibility rules.

Merchant user не видит:

• Provider callbacks tab;
• raw provider request;
• raw provider response;
• raw provider callback;
• hidden routing internals.

13. Raw data visibility

Raw provider request / response / callback видят только:

• platform users;
• с соответствующей permission.

Merchant users не должны видеть raw provider data.

Provider callbacks tab для platform user не должен показывать raw callback payload сразу. Raw payload должен открываться только через explicit action:

View raw

14. Webhook payload visibility

Merchant user с permission может видеть:

• webhook payload, который мы отправили;
• merchant response code;
• merchant response body;
• delivery attempts;
• timestamps;
• signature headers.

Platform users с permission видят то же самое.

14.1 Raw Payloads tab

Raw Payloads tab является platform/internal tab.

Merchant user не должен иметь отдельный Raw Payloads tab для provider payloads.

Merchant user с permission может видеть merchant webhook payloads inside Webhooks tab:

• webhook payload;
• webhook response;
• delivery attempts;
• signature headers, если они были отправлены merchant-у.

Platform user может видеть raw provider request/response/callback только если имеет соответствующую permission.

15. Transaction export

Transaction export доступен любому user с соответствующей permission.

Export должен учитывать visibility/masking rules.

User может экспортировать только те поля, которые он имеет право видеть в transaction table.

Если user имеет permission видеть поле в UI, это поле может быть включено в export. Если поле скрыто, замаскировано или недоступно по permissions, оно не должно попадать в export.

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

• platform export может содержать internal fields, если user имеет permission;
• merchant export не должен содержать hidden provider/internal data;
• key/secret data никогда не должны попадать в merchant-facing export.

Набор полей export не должен быть единым для всех users. Он должен формироваться на основе:

• user type;
• merchant / merchant group access;
• permissions;
• visibility level;
• masking rules;
• selected visible columns;
• current filters.

Export в MVP должен экспортировать only visible columns.

Export date range limit:

maximum 90 days per export

16. Transaction list columns

Transaction list в MVP должна иметь следующие columns:

• Merchant Name;
• Brand Name;
• transaction ID;
• merchant user ID;
• merchant group;
• user email;
• MID ID;
• MID Name;
• type: wd / dp;
• amount original;
• amount in EUR;
• currency;
• status;
• corrected;
• account reference;
• created;
• updated.

MID ID and MID Name относятся к Payment Method / MID configuration, через которую merchant создал transaction.

merchant user ID - это userId, который merchant передал в deposit request.

user email - это customer email, который merchant передал в deposit request.

corrected должна быть отдельной column.

legacy не должна быть отдельной technical column в MVP, но legacy state должен быть виден user-у как badge/marker в transaction list row и на transaction details page.

Actions вроде manual correction или resend webhook должны выполняться только из transaction details.

Default visible columns

По default transaction list должен показывать только основные columns:

• Merchant Name;
• Brand Name;
• transaction ID;
• merchant user ID;
• type;
• amount original;
• currency;
• status;
• created;
• updated.

Остальные columns должны быть доступны через UI настройки columns.

Error code / error description не должны быть columns в transaction list. Эта информация отображается в transaction details.

Column customization

User должен иметь возможность:

• выбрать visible columns;
• скрыть columns;
• поменять порядок columns, если UI это поддерживает;
• сохранить свой table view.

Все columns, кроме transaction ID, можно скрывать/показывать через настройку table view.

Transaction ID всегда остается visible и не может быть скрыт.

Saved table view должен сохраняться на client side.

Saved table view должен быть user-specific в рамках client/browser storage.

User не может включить column, которую он не имеет permission видеть.

Sorting and pagination

Transaction list должна использовать pagination.

Default sorting:

created desc

Date filter в MVP фильтрует по:

created

17. Transaction list search and filters

Transaction list должна поддерживать filters:

• merchant;
• brand;
• payment method;
• status;
• date;
• amount;
• currency;
• provider, platform/internal visibility only;
• user ID;
• country;
• error code;
• account reference;
• transaction ID search.

Для transaction ID search нужен один input, который ищет по нескольким identifiers:

• internal transaction ID;
• merchant transaction ID;
• provider transaction ID.

Account reference должен быть отдельным search/filter.

18. Transaction export behavior

CSV export должен экспортировать:

• только visible columns;
• только данные, доступные user-у по permissions and visibility rules;
• только transactions, которые попадают под current filters/search.

Export должен учитывать:

• current filters;
• current search;
• current visible columns.

Bulk export selected transactions в MVP не нужен.

Export работает как:

export by current filters/search/view

19. Error display

Merchant user видит:

• status;
• internal error code;
• human-readable description.

Platform user с permission видит:

• status;
• internal error code;
• human-readable description;
• provider raw error;
• provider code;
• provider status;
• mapping information.

20. Legacy transactions

Migrated historical transactions должны быть помечены как:

legacy

Для legacy transactions:

• timeline отсутствует
• actions limited;
• user должен понимать, что данные пришли из старой системы;
• transaction list row должен показывать legacy badge/marker;
• transaction details должны ясно показывать legacy marker.

21. Transaction correction visibility

Transaction correction events видят:

• platform users с permission;
• merchant users с permission.

Visibility зависит от permissions и masking rules.

Если correction раскрывает hidden provider/internal reason, merchant-safe timeline должна скрыть эту часть.

Correction event должен показывать:

• previous status;
• new status;
• actor;
• timestamp;
• reason/comment, если был указан;
• был ли сделан resend webhook.

Manual correction action может быть доступна для transactions в любых statuses, если user имеет permission.

Manual correction должна показываться/выполняться только из transaction details.

Если correction меняет final status, это считается manual override и должно быть явно видно в timeline, audit log and webhook payload marker corrected.

21.1 Manual webhook resend availability

Manual resend callback/webhook action доступен:

• на PROCESSING;
• на final statuses.

Action доступен только из transaction details и только если user имеет permission.

User обязан указать reason/comment для manual resend.

Resend использует webhook URL(s), которые были переданы merchant-ом при создании transaction.

22. Timeline immutability

Нельзя редактировать или удалять timeline events.

23. Notes / comments

Notes/comments на transaction не входят в MVP.

В MVP не нужно делать:

• отдельную вкладку Comments / Notes;
• permissions для transaction comments;
• создание notes/comments;
• редактирование notes/comments;
• edit history для notes/comments;
• attachments/files;
• mentions.

Если notes/comments понадобятся после MVP, их нужно описать отдельным flow.

Важно: это решение не отменяет обязательный reason/comment для отдельных manual actions, например:

• manual transaction correction;
• manual resend callback/webhook;
• publish routing/configuration draft.

В этих случаях reason/comment является обязательным reason field для конкретного действия, а не отдельной transaction comments feature.

24. Timeline UI grouping recommendation

Timeline может быть длинной, поэтому UI должен поддерживать grouping/collapse.

Рекомендуемый подход:

• routing execution показывать как expandable routing block;
• fallback attempts группировать внутри routing block;
• provider callback validation steps группировать внутри provider callback event;
• webhook retry attempts группировать внутри одного webhook delivery block;
• duplicate callbacks группировать, если их несколько;
• ignored callbacks группировать, если их несколько;
• raw payload/details открывать только по explicit user action и только если permission позволяет.

В collapsed view user должен видеть короткое human-readable summary. В expanded view user должен видеть технические детали, которые доступны ему по permissions и visibility rules.

25. Acceptance Criteria

Transaction investigation считается реализованным для MVP, если:

• Platform users с permission видят full internal timeline.
• Merchant users с permission видят merchant-safe timeline.
• Timeline поддерживает visibility levels: merchant_safe, platform_only, sensitive_platform_only.
• Merchant может видеть SUB MID / SUB MID GROUP только если сам имеет доступ создавать/видеть эти сущности и они не являются platform-hidden.
• Merchant user не видит SUB MID AGGREGATOR как отдельную execution entity.
• Merchant не видит internal structure сущностей, созданных platform admin, если нет специального доступа.
• Platform/support видит full routing trace.
• Platform/support видит full fallback chain and skip/fallback reasons.
• Platform/support видит provider callbacks, webhook delivery и correction details.
• Timeline содержит все required events.
• Timeline event содержит event ID, transaction ID, type, timestamp, source, actor, visibility level, message, reason, metadata, previous/new status.
• Timeline event может содержать config version refs.
• Timeline event может содержать payload reference вместо raw payload.
• Timeline event может содержать request ID / correlation ID, если доступно.
• Raw payload не хранится прямо внутри timeline event.
• Manual correction event содержит actor and reason/comment.
• Timeline поддерживает filters.
• Transaction details page содержит summary, status, amount, merchant, brand, method, customer, routing, fees/FX, timeline, provider callbacks, webhooks, audit/corrections.
• Transaction details tabs отображаются according to permissions and visibility rules.
• Merchant user видит Routing tab всегда, но только merchant-safe routing representation.
• Merchant user не видит Provider callbacks tab.
• Raw provider data доступна только platform users с permission.
• Merchant user с permission видит webhook payload и merchant response body.
• Merchant user с permission видит merchant webhook payloads in Webhooks tab.
• Transaction list содержит обязательные MVP columns.
• Transaction list по default показывает только основные columns.
• Все columns, кроме transaction ID, можно скрывать/показывать.
• Transaction ID нельзя скрыть.
• User может настраивать visible columns and save table view на client side.
• Transaction list использует pagination.
• Default sorting: updated desc.
• Date filter работает по updated.
• Transaction list показывает corrected как отдельную column.
• Transaction list показывает legacy как badge/marker, а не как отдельную technical column.
• Transaction list row не содержит quick actions, кроме открытия details.
• Export доступен users с permission и учитывает visibility/masking.
• Export CSV экспортирует только visible columns.
• Export учитывает current filters/search.
• Transaction list поддерживает нужные filters.
• Transaction ID search ищет по internal transaction ID, merchant transaction ID, provider transaction ID.
• Merchant видит internal error code и description.
• Platform видит provider raw error и mapping information.
• Legacy transactions имеют visible legacy marker.
• Manual correction доступна для любых statuses при наличии permission.
• Resend callback/webhook доступен на PROCESSING and final statuses при наличии permission.
• Manual resend callback/webhook требует reason/comment.
• Timeline events immutable.
• Export включает только те поля, которые доступны конкретному user по permissions и visibility/masking rules.
• Timeline UI поддерживает grouping/collapse для длинных transaction flows.