03.11 Legacy Transaction Migration

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

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

Этот документ описывает migration flow для переноса historical transactions из старой системы в новую.

Migration нужна, чтобы после перевода merchant / payment method на новую систему можно было видеть старые transactions в новом Back Office.

Migration выполняется не во время live traffic switching, а после того, как merchant перестал отправлять traffic в v1 по конкретному payment method.

Пока merchant продолжает использовать v1 endpoints, старая система остается активной.

2. Основной принцип

Migration запускается вручную platform user-ом.

Инструмент запуска может быть:

• Back Office;
• internal admin tool.

Для product requirements важно, чтобы migration была controlled platform operation и не запускалась автоматически.

3. Что переносим

В MVP переносим только historical transactions.

Не переносим:

• customers как отдельные profiles;
• webhook delivery history;
• old provider callbacks;
• old transaction logs, если они не входят в transaction record;
• users;
• roles;
• old configuration;
• old routing rules.

4. Source input

Для выбора transactions в старой системе migration input должен содержать:

• old merchantId;
• old merchantConfigId.

Эти identifiers используются, чтобы понять:

• из какого merchant-а старой системы переносить transactions;
• из какого старого payment method переносить transactions.

5. Target input

Для переноса в новую систему migration input должен содержать:

• new merchantId;
• target brandId;
• target paymentMethodId.

target brandId обязателен.

Система не создает default brand автоматически.

Если target brandId не указан или не принадлежит target merchant:

• migration не выполняется;
• migration report должен показать validation error.

Если target paymentMethodId не принадлежит target merchant:

• migration не выполняется;
• migration report должен показать validation error.

6. Date range

Date range для migration в MVP не нужен.

Migration переносит transactions по заданным:

• old merchantId;
• old merchantConfigId.

7. Dry run

Dry run перед реальным переносом в MVP не нужен.

При этом migration tool должен делать validation перед выполнением и вернуть report, если input некорректный.

8. Legacy transaction identifiers

Старые transaction IDs нужно сохранить.

Нужно сохранить старые identifiers как grouped legacy metadata, чтобы:

• support мог сопоставить old Back Office и new Back Office;
• merchant мог найти old transaction по привычному ID;
• migration report мог ссылаться на old transaction;
• investigation была возможна без обращения к разработчикам.

9. Migrated transaction status

Migrated transaction должна сохранить historical status из старой системы.

10. Read-only behavior

Migrated transactions должны быть read-only.

Для migrated transactions нельзя:

• менять status через manual correction;
• делать resend webhook;
• запускать provider actions;
• запускать callback retry;
• менять routing result;
• пересчитывать FX/fees, если они были imported as historical data.

User может:

• смотреть transaction;
• фильтровать transaction;
• экспортировать transaction, если permission позволяет;
• видеть legacy marker;
• видеть migration metadata.

11. Webhooks for migrated transactions

По migrated transactions webhooks не отправляются.

Migration не должна триггерить:

• merchant webhook;
• callback resend;
• transaction lifecycle events наружу.

Migration является historical data import, а не повторной обработкой transaction.

12. Legacy marker

Все migrated transactions должны быть явно помечены:

legacy

Legacy marker должен быть виден:

• в transaction list;
• в transaction details;

Для legacy transactions UI должен показывать, что:

• данные пришли из старой системы;
• timeline может быть неполной;
• actions limited/read-only.

13. Migration report

Migration должна формировать report.

Report генерируется сразу после запуска migration.

Report не является отдельной долгоживущей сущностью в MVP.

Отдельное хранение migration report в системе не требуется.

Report должен содержать:

• migration ID;
• started at;
• finished at;
• actor;
• source old merchantId;
• source old merchantConfigId;
• target merchantId;
• target brandId;
• target paymentMethodId;
• total records;
• success count;
• failed count;
• skipped count;
• errors per record;
• skipped reasons per record;
• warnings, если есть;
• final migration status.

Report должен быть показан / выдан platform user-у после выполнения migration.

14. Temporary operational tool

Migration tool является временным operational functionality.

Цель:

• один раз или ограниченное время перенести old transactions;
• после завершения migration phase удалить / отключить этот functionality;
• не создавать постоянный продуктовый модуль migration reports.

Migration tool может быть реализован максимально просто:

• internal admin tool;
• Swagger/internal API;
• временная Back Office action, если development team решит, что так быстрее.

Это не должно превращаться в полноценный долгосрочный Back Office module.

Для MVP не требуется:

• отдельная permission для просмотра migration reports;
• отдельная долговременная report storage model;
• отдельный audit log для migration actions.

15. Acceptance Criteria

Legacy Transaction Migration считается согласованной для MVP, если:

• Migration запускается вручную platform user-ом.
• Migration запускается через Back Office или internal admin tool.
• Source input содержит old merchantId и old merchantConfigId.
• Target input содержит new merchantId, brandId, paymentMethodId.
• brandId обязателен.
• Default brand автоматически не создается.
• Date range в MVP не нужен.
• Dry run в MVP не нужен.
• Migration переносит только transactions.
• Старые transaction IDs сохраняются как grouped legacy metadata.
• Старые IDs можно использовать для поиска/investigation.
• Migrated transactions помечаются как legacy.
• Migrated transactions read-only.
• По migrated transactions webhooks не отправляются.
• Migration формирует immediate report с total/success/failed/skipped и errors per record.
• Migration report не требует отдельного постоянного хранения.
• Migration не требует отдельного audit log.