08.06 Transaction Timeline Event Dictionary

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

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

Этот документ описывает dictionary событий transaction timeline для MVP.

Timeline нужен, чтобы platform/support users и merchant users могли понять, что произошло с transaction, без чтения логов и без помощи разработчиков.

2. Core principles

Timeline events должны быть immutable.

Нельзя редактировать или удалять timeline event через обычное user action.

Если нужно исправить или дополнить информацию, система должна создать новый event.

Timeline видят:

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

Но детализация разная:

• merchant user видит merchant-safe timeline;
• platform user с permission видит full internal timeline.

3. Visibility levels

Каждый event должен иметь visibility level.

MVP visibility levels:

merchant_safe
platform_only
sensitive_platform_only

merchant_safe

Event можно показать merchant user-у, если у него есть доступ к transaction и permission смотреть timeline.

Event не должен раскрывать:

• real provider name, если provider access не выдан;
• hidden SUB MID / SUB MID AGGREGATOR details;
• platform-created hidden routing details;
• raw provider payloads;
• provider credentials/secrets;
• internal provider errors.

platform_only

Event виден platform users с permission.

Event может содержать:

• full routing trace;
• selected MASTER MID / SUB MID;
• fallback reason;
• provider callback processing details;
• webhook delivery details.

sensitive_platform_only

Event виден только platform users с sensitive permissions.

Event может ссылаться на:

• raw provider request/response/callback;
• raw merchant webhook payload/response;
• provider error mapping internals;
• hidden routing internals;
• suspicious callback details.

Secret values никогда не должны попадать в timeline даже на sensitive_platform_only.

4. Event structure

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

• eventId;
• transactionId;
• eventType;
• timestamp;
• source;
• actorType;
• actorId, если применимо;
• visibilityLevel;
• title/message;
• reason, если применимо;
• metadata;
• previousStatus, если применимо;
• newStatus, если применимо;
• configVersionRefs, если применимо;
• payloadReference, если применимо;
• requestId/correlationId, если доступно.

5. Payload reference

Timeline event не должен хранить heavy raw payload прямо внутри event metadata.

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

Пример:

payloadReference: provider_callback_payload_id

Это нужно, чтобы:

• timeline оставался легким;
• raw payload можно было скрывать по permissions;
• raw payload можно было хранить с отдельными retention/security rules;
• merchant-safe timeline не раскрывал sensitive details.

Merchant users не получают raw payload reference, если это раскрывает provider/internal data.

6. requestId / correlationId

requestId / correlationId - это технический identifier, который помогает связать:

• API request;
• transaction timeline events;
• provider request;
• provider callback;
• merchant webhook delivery;
• application logs;
• metrics/traces.

Product user может не взаимодействовать с этим полем напрямую.

Но поле полезно для support/development investigation.

Development team должна определить exact naming:

requestId
correlationId
traceId

Product requirement: timeline event должен иметь поле для такого identifier, если он доступен.

7. Core event types

MVP event types:

Event type	Visibility default	Назначение
transaction_created	merchant_safe	Transaction создана.
validation_failed	platform_only	Validation failed. Обычно transaction может не быть создана.
routing_started	merchant_safe	Routing execution started.
payment_method_selected	merchant_safe	Payment Method / MID определен.
rule_matched	platform_only	Routing rule matched. Merchant-safe version может быть simplified.
master_mid_group_selected	merchant_safe	MASTER MID GROUP selected.
master_mid_selected	merchant_safe	MASTER MID selected.
master_mid_rule_matched	platform_only	Rule inside MASTER MID routing matched.
sub_mid_group_selected	platform_only	SUB MID GROUP selected. Merchant sees only if allowed.
sub_mid_selected	platform_only	SUB MID selected. Merchant sees only if allowed.
sub_mid_aggregator_selected	platform_only	SUB MID AGGREGATOR selected. Merchant does not see internals.
velocity_checked	platform_only	Velocity limit checked.
velocity_rejected	merchant_safe	Transaction rejected/skipped due to velocity. Merchant-safe reason only.
dynamic_attributes_required	merchant_safe	Additional customer fields required.
dynamic_attributes_submitted	merchant_safe	Customer submitted missing fields.
provider_request_sent	platform_only	Request sent to provider.
provider_response_received	platform_only	Provider response received.
provider_payment_url_received	merchant_safe	Payment URL/instruction received.
provider_error_received	platform_only	Provider returned error.
provider_callback_received	platform_only	Provider callback received.
provider_callback_validated	platform_only	Callback validation passed.
provider_callback_rejected	platform_only	Callback validation failed/rejected.
provider_callback_ignored	platform_only	Callback ignored.
duplicate_callback_ignored	platform_only	Duplicate callback ignored.
unknown_provider_status_ignored	platform_only	Unknown provider status ignored.
status_changed	merchant_safe	Transaction status changed.
webhook_created	platform_only	Merchant webhook delivery created.
webhook_sent	merchant_safe	Merchant webhook sent.
webhook_delivered	merchant_safe	Merchant webhook delivered.
webhook_failed	merchant_safe	Merchant webhook failed.
webhook_retry_scheduled	merchant_safe	Merchant webhook retry scheduled.
webhook_retry_exhausted	merchant_safe	Merchant webhook retries exhausted.
manual_webhook_resend	merchant_safe	User triggered webhook resend.
manual_correction_applied	merchant_safe	Manual transaction correction applied.
expiration_applied	merchant_safe	Transaction/payment session expired.
legacy_marker_added	merchant_safe	Transaction marked as migrated legacy.
error_mapped	platform_only	Provider/internal error mapped to unified error.
raw_payload_saved	sensitive_platform_only	Raw payload saved and referenced.

8. Fallback visibility

Merchant user может видеть fallback attempts только в merchant-safe форме.

Merchant-safe fallback event может показывать:

• что система попробовала другой route;
• что предыдущий route был недоступен;
• generic reason, например route unavailable.

Merchant-safe fallback event не должен раскрывать:

• real provider name;
• hidden SUB MID;
• SUB MID AGGREGATOR;
• internal provider error;
• platform-created hidden routing internals.

Platform user с permission должен видеть:

• full fallback chain;
• skipped candidates;
• skip/fallback reason;
• provider errors/timeouts;
• velocity exceeded details;
• inactive/deleted configuration reason;
• routing/config versions.

9. Manual correction events

Manual correction обязательно создает timeline event:

manual_correction_applied

Event должен хранить:

• actor;
• previous status;
• new status;
• timestamp;
• reason/comment;
• whether merchant webhook resend was requested.

Если correction раскрывает platform/provider-sensitive reason, merchant-safe representation должна скрыть sensitive part.

10. Config version references

Timeline event должен хранить references на фактически использованные configuration versions, если применимо:

• Payment Method / MID routing version;
• MASTER MID GROUP version;
• MASTER MID version;
• MASTER MID routing version;
• SUB MID GROUP version;
• SUB MID / SUB MID AGGREGATOR config version;
• credentials/config version;
• velocity rule/version;
• FX/fee configuration version.

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

11. Acceptance Criteria

Timeline Event Dictionary считается согласованным для MVP, если:

• Timeline events immutable.
• Timeline доступен platform users и merchant users с permission.
• Timeline поддерживает visibility levels: merchant_safe, platform_only, sensitive_platform_only.
• Merchant user видит merchant-safe events.
• Platform user с permission видит full internal events.
• Merchant user может видеть fallback attempts только без provider/SUB MID internal details.
• Platform user видит полную routing/fallback chain и reasons.
• Timeline event содержит eventId, transactionId, eventType, timestamp, source, actor, visibilityLevel, message, reason, metadata, previous/new status.
• Timeline event может содержать configVersionRefs.
• Timeline event может содержать payloadReference вместо raw payload.
• Timeline event может содержать requestId/correlationId.
• Raw payload не хранится прямо внутри timeline event.
• Manual correction создает timeline event с actor and reason/comment.
• Secret values никогда не попадают в timeline.

12. Open Questions

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

Technical/design follow-up:

1. Определить exact event type enum.
2. Определить exact metadata schema per event type.
3. Определить final naming: requestId, correlationId или traceId.
4. Определить storage для raw payload и payloadReference.