АБС — Архитектура системы

Документ 1 из 6. Контекст и цели — в разделе Видение и рамки.

1. Стиль архитектуры: модульный монолит

Микросервисы для команды из 1–3 разработчиков — самоубийство: сетевые границы, распределённые транзакции, зоопарк деплоев. Мы строим модульный монолит на NestJS:

• Один деплоймент, одна база данных на тенант, одна транзакция БД на бизнес-операцию.
• Жёсткие границы модулей внутри процесса: модуль общается с другим только через его публичный сервис-интерфейс, никогда — через чужие таблицы напрямую.
• Если когда-нибудь понадобится выделить модуль в сервис (например, Statement Import) — граница уже готова.

2. Контекстная диаграмма

3. Модули и их ответственность

4. Ядро: леджер двойной записи

Самая важная часть системы. Три таблицы (детали схемы — в разделе Модель данных):

Правила:

1. journal_entry — атомарная транзакция: 2+ postings, SUM(debit) = SUM(credit) по каждой валюте. Проверяется constraint-триггером в PostgreSQL при COMMIT.
2. Postings append-only: ни UPDATE, ни DELETE (запрещены грантами БД). Исправление — сторнирующая проводка со ссылкой на оригинал.
3. Каждый posting ссылается либо на клиентский счёт, либо на GL-счёт. Клиентский счёт всегда привязан к GL (пассивы банка), поэтому баланс банка сходится на любом уровне.
4. Баланс = SUM(credits) - SUM(debits) (для пассивных счетов). Кэш в account_balances обновляется в той же транзакции; ночной job пересчитывает и сверяет кэш с сырыми postings.
5. Available balance = ledger balance − активные холды.
6. balance_date (операционный день) на каждой проводке; закрытие дня фиксирует end-of-day снапшоты для отчётности.

5. Платёжный поток: 3-step flow сохраняем

Совместимость с текущим Client Bank — осознанное решение (см. принцип 7 в разделе Видение и рамки). API повторяет семантику Elcoin:

POST /api/v1/payments/{model}/prepare    → дефолты: GL, канал, комиссия, имя отправителя
POST /api/v1/payments/{model}/validate   → бизнес-правила: баланс, лимиты, IBAN, blocklist
POST /api/v1/payments/{model}/commit     → создание платежа + hold, необратимо (бывш. putDb)

где model ∈ internal | outward | conversion (+ inward создаётся импортом выписок).

Статусная машина (совпадает с текущей, к которой привык фронт и операторы):

Проводки по этапам (пример outward 1000 EUR + fee 25):

Транзитный GL между «отправили» и «увидели в выписке» — то, что делает реконсиляцию ностро тривиальной: остаток на транзитном счёте = платежи в пути.

6. Асинхронная обработка

Всё, что не обязано случиться синхронно, идёт через transactional outbox:

1. Бизнес-транзакция пишет событие (payment.accepted, statement.line.matched…) в таблицу outbox_events в той же транзакции БД.
2. Диспетчер читает outbox и кладёт задачи в BullMQ (Redis): отправка в кор-банк, вебхуки, email, пересчёт кэшей.
3. Обработчики идемпотентны; ретраи с backoff; DLQ для разбора вручную.

Так мы не теряем события при падении процесса и не тащим Kafka в проект на 3 человека.

7. Мульти-тенантность

Database-per-tenant. Один инстанс приложения (или по инстансу на регион), у каждого банка своя PostgreSQL-база:

Почему не schema-per-tenant и не row-level:

• изоляция данных абсолютная (требование резидентности: базы физически в разных регионах);
• бэкап/рестор и миграция независимы;
• невозможно случайно смешать данные банков одним WHERE, забытым в запросе.

Цена — прогон Prisma-миграций по N баз; при N=2 это не цена.

8. Безопасность

• API клиентов: JWT (короткоживущий access + refresh), 2FA на логин и подтверждение платежей, rate limiting, idempotency keys на все POST.
• API операторов: отдельный issuer, роли (viewer / operator / authorizer / admin), maker-checker на платежи выше порога и на ручные проводки — всегда.
• Секреты: переменные окружения из секрет-менеджера облака, никаких секретов в репо.
• БД: приложение работает под ролью без прав UPDATE/DELETE на postings и audit_log; TLS до БД; шифрование дисков.
• Аудит: каждый запрос, изменивший состояние — запись (кто, что, когда, до/после, IP, tenant) в append-only audit_log.

9. Наблюдаемость и эксплуатация

• Структурированные логи (pino) с tenant_id, request_id, payment_uid.
• Метрики Prometheus: платежи по статусам, лаг очередей, расхождения реконсиляции.
• Алерты: расхождение в реконсиляции ≠ 0, DLQ не пустая, кэш балансов разошёлся с postings.
• Бэкапы: WAL-архивирование + ежедневный полный дамп, регулярная проверка восстановления.
• RTO ≤ 4 часа, RPO ≤ 5 минут (WAL) для MVP.

10. Что мы сознательно НЕ делаем

АБС — Технологический стек

Документ 2 из 6. Общее устройство системы — в разделе Архитектура. Главный критерий выбора: команда 1–3 разработчика уже пишет на TypeScript (Express + React + PostgreSQL), стек должен быть скучным, проверенным и единым.

1. Сводная таблица

2. Структура репозитория (монорепо)

abs/
├── apps/
│   ├── core/            # NestJS: API + модули (ledger, payments, ...)
│   ├── worker/          # BullMQ-воркеры (тот же код, другой entrypoint)
│   ├── client-bank/     # React фронт клиента (переносится из MD)
│   └── admin/           # React админ-панель оператора
├── packages/
│   ├── contracts/       # zod-схемы + типы API (шарятся фронт/бек)
│   ├── decimal/         # обёртка денежной арифметики
│   └── statements/      # парсеры camt.053 / MT940 / CSV (чистые функции)
├── prisma/
│   ├── schema.prisma    # схема тенант-базы
│   └── migrations/
├── tools/
│   └── import-elcoin/   # одноразовый мигратор (см. раздел про миграцию)
├── docker-compose.yml
└── .github/workflows/

pnpm workspaces + turborepo (опционально). Один pnpm test гоняет всё.

3. Ключевые технические решения

3.1 Деньги и точность

• БД: NUMERIC(20, 4) для сумм, NUMERIC(20, 10) для курсов.
• API: суммы — строки ("1030.00"), как делает Elcoin. JSON number запрещён.
• Код: decimal.js; ESLint-правило запрещает арифметические операторы над типом Money вне пакета packages/decimal.
• Округление: banker's rounding по умолчанию, per-currency decimal_points из справочника валют (у Elcoin есть крипта с 8 знаками — берём NUMERIC(30,10) где нужно).

3.2 Целостность леджера на уровне БД

-- Роль приложения не может изменять историю
REVOKE UPDATE, DELETE ON postings, journal_entries, audit_log FROM abs_app;

-- Constraint-триггер: транзакция сбалансирована по каждой валюте
CREATE CONSTRAINT TRIGGER trg_entry_balanced
AFTER INSERT ON postings
DEFERRABLE INITIALLY DEFERRED
FOR EACH ROW EXECUTE FUNCTION check_entry_balanced();

DEFERRABLE INITIALLY DEFERRED — проверка в момент COMMIT, когда все postings транзакции уже вставлены.

3.3 Идемпотентность

Таблица idempotency_keys (key, endpoint, request_hash, response, created_at). Все POST принимают Idempotency-Key; повтор с тем же ключом возвращает сохранённый ответ. Для commit платежа ключ обязателен.

3.4 Конкурентность балансов

Списание: SELECT ... FOR UPDATE строки счёта в account_balances внутри транзакции → проверка available (баланс − холды) → insert postings → update кэша. Никаких «проверили баланс, потом записали» без блокировки.

3.5 Почему не готовые леджер-библиотеки (TigerBeetle, Formance)

Рассматривались. TigerBeetle — отдельная СУБД со своей моделью эксплуатации; Formance — ещё один вендор (от вендора мы и уходим). Наши объёмы (десятки тысяч проводок в месяц) PostgreSQL обрабатывает с огромным запасом, а весь стек остаётся одной технологией. Пересмотреть при >100 платежей/сек.

4. Версии и фиксация

Renovate/Dependabot для обновлений; мажоры — только осознанно.

АБС — Модель данных ядра

Документ 3 из 6. Основан на анализе 64 экспортированных таблиц Elcoin и реверс-инжиниринге платёжных схем. Схема — одна на тенант-базу (database-per-tenant, см. раздел Архитектура).

1. Обзор: ER-диаграмма ядра

2. Блоки модели

2.1 Леджер (сердце системы)

gl_accounts — план счетов

journal_entries — транзакции (заголовки проводок)

Аналог Elcoin: transactionEntryHeader / transactionViewHeader (27 колонок → сжимаем до нужного).

postings — строки проводок (append-only)

Инварианты (constraint-триггеры БД):

• SUM(debit) = SUM(credit) по каждой валюте внутри journalEntryId на момент COMMIT;
• UPDATE/DELETE запрещены грантами;
• ровно один из accountId / glAccountId не null.

Аналог Elcoin: transactionViewLine (37 колонок; их debet_num/credit_num в одной строке разносим на две postings-строки — классическая нормализация двойной записи).

account_balances — кэш балансов

Обновляется в транзакции проводки (SELECT FOR UPDATE); ночной job пересчитывает с нуля и алертит при расхождении.

eod_balances — снапшоты на конец дня

(accountId | glAccountId, balanceDate, balance) — для отчётности и быстрых выписок.

2.2 Клиенты

2.3 Счета

accounts — клиентские счета

Источник: remoteAccount_remoteAccount (43 колонки). Балансовые поля (available_amount, ledger_balance) НЕ переносятся как данные — пересчитываются из мигрированных проводок и сверяются (см. раздел Миграция с Elcoin).

nostro_accounts — наши счета в кор-банках

2.4 Холды

holds

id, accountId, amount, currency, holdType (PAYMENT/COURT/AML/MANUAL), status (ACTIVE/RELEASED/EXPIRED/CONSUMED), paymentOrderId nullable, expiresAt, reason

Источник: holdInstruction_holdInstruction (37 колонок, 21 тип из enum — оставляем востребованные, остальные заводим по мере надобности).

2.5 Платежи

Elcoin держит 3 таблицы по ~100 колонок (paymentInward/Internal/Convertation). Мы сводим в одну payment_orders + JSONB для канальных полей:

payment_orders

payment_status_history

paymentOrderId, fromStatus, toStatus, changedBy, reason, createdAt — полный след статусов.

2.6 Валюты и курсы

2.7 Комиссии и тарифы

Расчёт комиссии = функция (client, eventCode, channel, amount, currency) → fee, детерминированная и покрытая тестами.

2.8 Справочники и инфраструктура

2.9 Выписки и реконсиляция

3. Prisma-схема ядра леджера (выдержка)

model GlAccount {
  id         Int         @id @default(autoincrement())
  glNumber   String      @unique
  name       String
  glType     GlType
  currency   String?     @db.Char(3)
  isPostable Boolean     @default(true)
  parentId   Int?
  parent     GlAccount?  @relation("GlHierarchy", fields: [parentId], references: [id])
  children   GlAccount[] @relation("GlHierarchy")
  postings   Posting[]
  accounts   Account[]
  createdAt  DateTime    @default(now())
  updatedAt  DateTime    @updatedAt

  @@index([glType])
  @@map("gl_accounts")
}

model JournalEntry {
  id                BigInt         @id @default(autoincrement())
  uid               String         @unique @default(uuid()) @db.Uuid
  documentReference String         @unique
  entryType         EntryType
  balanceDate       DateTime       @db.Date
  description       String?
  paymentOrderId    BigInt?
  paymentOrder      PaymentOrder?  @relation(fields: [paymentOrderId], references: [id])
  reversalOfId      BigInt?
  reversalOf        JournalEntry?  @relation("Reversal", fields: [reversalOfId], references: [id])
  reversals         JournalEntry[] @relation("Reversal")
  postings          Posting[]
  createdById       Int
  createdBy         User           @relation("EntryCreator", fields: [createdById], references: [id])
  authorizedById    Int?
  authorizedBy      User?          @relation("EntryAuthorizer", fields: [authorizedById], references: [id])
  createdAt         DateTime       @default(now())
  updatedAt         DateTime       @updatedAt

  @@index([balanceDate])
  @@index([paymentOrderId])
  @@map("journal_entries")
}

model Posting {
  id             BigInt       @id @default(autoincrement())
  journalEntryId BigInt
  journalEntry   JournalEntry @relation(fields: [journalEntryId], references: [id])
  accountId      Int?
  account        Account?     @relation(fields: [accountId], references: [id])
  glAccountId    Int?
  glAccount      GlAccount?   @relation(fields: [glAccountId], references: [id])
  side           PostingSide
  amount         Decimal      @db.Decimal(30, 10)
  currency       String       @db.Char(3)
  balanceDate    DateTime     @db.Date
  createdAt      DateTime     @default(now())

  @@index([accountId, balanceDate])
  @@index([glAccountId, balanceDate])
  @@index([journalEntryId])
  @@map("postings")
}

enum GlType {
  ASSET
  LIABILITY
  INCOME
  EXPENSE
  EQUITY
  OFF_BALANCE
}

enum PostingSide {
  DEBIT
  CREDIT
}

enum EntryType {
  PAYMENT
  FEE
  FX
  MANUAL
  REVERSAL
  MIGRATION
  EOD
}

Полная схема (~30 моделей) пишется на фазе 0 по этому документу. Инварианты, которые Prisma выразить не может (сбалансированность транзакции, запрет UPDATE/DELETE, accountId XOR glAccountId), добавляются raw-SQL миграцией поверх сгенерированной (prisma migrate dev --create-only → дописать SQL).

4. Сводный маппинг Elcoin → АБС (основа импорта)

Детальная процедура импорта и сверки — в разделе Миграция с Elcoin.

АБС — Дорожная карта

Документ 4 из 6. Сроки рассчитаны на команду 1–3 разработчика с активным использованием AI-разработки. Горизонт MVP: 4–6 месяцев (фазы 0–4). Каждая фаза заканчивается работающим, демонстрируемым результатом.

1. Диаграмма Ганта

2. Фазы подробно

Фаза 0 — Фундамент (2–3 недели)

Строим «рельсы», по которым поедет всё остальное.

Definition of Done: пустая АБС деплоится в облако одной командой; тест на constraint «дебет = кредит» зелёный; два тенанта видны в control plane.

Фаза 1 — Ядро (6–8 недель)

DoD: вся история MD импортирована в стейджинг; баланс каждого счёта совпадает с remoteAccount.ledger_balance Elcoin (отчёт сверки = 0 расхождений); оператор может сделать ручную проводку через админку.

Фаза 2 — Платежи (6–8 недель)

DoD: через API (Postman/тестовый фронт) проходит internal-платёж и конвертация с комиссией: hold → авторизация → проводки → COMPLETED; отчёт «баланс банка» сходится.

Фаза 3 — Кор-банки (6–8 недель, параллелится с хвостом фазы 2)

DoD: боевая выписка Clear Junction импортируется без ошибок; inward зачисляется автоматически; реконсиляция за тестовый месяц = 0 расхождений; тестовый outward уходит и подтверждается выпиской.

Фаза 3П — Параллельный трек: запуск AB (ноябрь 2026 – январь 2027)

AB — greenfield-тенант: без миграции Elcoin ему нужны только ядро (фаза 1), платежи (фаза 2) и кор-счёт (фаза 3). Ждать cutover MD незачем — запускаемся параллельно с фазой 3 и принимаем первого клиента на M3. Трек преимущественно операционный (настройка, договорённости с банками, KYC-процесс), разработчиков почти не отвлекает.

DoD: первый реальный клиент AB открыл счёт, получил входящий платёж и провёл исходящий — всё в ручном режиме (авторизация оператором); реконсиляция кор-счёта за пилотный период = 0 расхождений; данные тенантов физически изолированы (проверено).

Фаза 4 — Миграция и cutover (4–6 недель)

Детальная процедура — в разделе Миграция с Elcoin.

DoD: MD работает на своей АБС; сверка cutover-балансов подписана; подписка Elcoin переведена в режим завершения.

Фаза 5 — Устойчивость и развитие (после cutover, приоритеты уточняются)

Первый блок — подтверждение боевой устойчивости: оба банка уже в проде, и ядро должно доказать надёжность формальными проверками, а не только штатной работой.

3. Порядок работ и зависимости

Импорт данных начинается внутри фазы 1, как только готов леджер: реальные данные — лучший тест ядра, и именно на них ловятся все сюрпризы модели Elcoin.

4. Риски

5. Контрольные точки для руководства

АБС — План миграции данных с Elcoin

Документ 5 из 6. Маппинг таблиц — в разделе Модель данных (п. 4). Сроки — фаза 1 (импорт v1) и фаза 4 (cutover) в Дорожной карте.

1. Источники данных

2. Подготовительный этап (сделать ДО уведомления Elcoin об уходе)

1. Допагинировать неполные таблицы зеркала. По описанию экспортированных таблиц в лимит 1000 строк упёрлись: additionalInformation, clientCounterparty, clientExternalRegistration, transactionEntryHeader, transactionViewHeader, transactionViewLine, remoteCounterparty, remoteWebhook, sepaParticipants, clientMessage. Критичны для миграции: transactionViewHeader / transactionViewLine (это вся бухгалтерская история) и clientCounterparty. Написать пагинирующий экспортёр и выгрузить полностью.
2. Зафиксировать контрольные суммы: по каждой таблице — количество строк, MAX(id), MAX(updated_at); по каждому счёту — ledger_balance и available_amount из remoteAccount; сумма дебетов/кредитов по GL.
3. Собрать полный архив выписок кор-банков за всю историю (независимая верификация ностро-балансов).
4. Реверс тарифов: выписать действующие комиссии по каждому тарифному плану (из прод-платежей: fee_amount_num по типам/каналам) — Elcoin не отдаёт правила, только результаты.

3. Порядок импорта (идемпотентный пайплайн tools/import-elcoin)

Каждый шаг — отдельная команда, безопасная для повторного запуска (upsert по бизнес-ключам). Прогон полностью автоматический: «снести тенант-базу → импорт → отчёт сверки» должен выполняться одной командой, потому что прогонов будет много.

Ключевые решения шага 5 (проводки)

• Каждая пара transactionViewHeader + строки transactionViewLine → один journal_entry (entryType = MIGRATION, migrationSourceId = header_id) с postings по строкам: debet_num > 0 → DEBIT, credit_num > 0 → CREDIT.
• Строки на GL-счета линкуются к gl_accounts, строки на клиентские счета — к accounts.
• Несбалансированные заголовки (если найдутся) — в карантинную таблицу migration_quarantine и ручной разбор; НЕ вставляем силой.
• Opening balance fallback: если история проводок в Elcoin неполна (глубина экспорта меньше возраста счёта), балансы не сойдутся из проводок. Тогда стратегия: импортируем проводки за доступную глубину + одна opening-balance проводка на счёт на дату начала истории (Dr/Cr против GL «миграционный мост», который в итоге обязан схлопнуться в ноль по каждой валюте). Решение принимаем после первого прогона на реальных данных.

Шаг 9 — сверка (обязательный отчёт каждого прогона)

Отчёт сохраняется как артефакт; cutover разрешён только при полном PASS.

4. Параллельный прогон (shadow ledger, 2–4 недели)

1. Elcoin остаётся мастером; клиенты ничего не замечают.
2. Ежедневный инкрементальный импорт дельты (новые проводки, платежи, клиенты) по id/updated_at водяным знакам.
3. Ежедневная сверка балансов (тот же отчёт из шага 9). Любое расхождение — баг импортера или пропуск данных: чиним до cutover.
4. Shadow-валидация платежей: сервер Client Bank дублирует prepare/validate в нашу АБС (fire-and-forget, ответ клиенту — только от Elcoin) и логирует различия (комиссия, канал, ошибки валидации). Так мы проверяем платёжную логику на реальном трафике без риска.

5. Cutover (выходные, план по часам)

Точка невозврата — первый платёж, проведённый в нашей АБС после C4. До неё откат — это смена одной переменной конфигурации.

6. После cutover

• Elcoin-зеркало и архивные таблицы остаются в схеме elcoin_archive тенант-базы (историческая справка, разборы споров).
• Ежедневная реконсиляция ностро становится штатным процессом (модуль recon).
• Через 1–2 месяца стабильной работы — расторжение договора с Elcoin.

7. Чек-лист готовности к миграции

• Допагинированы transactionViewHeader/Line, clientCounterparty, sepaParticipants
• Контрольные суммы зафиксированы
• Архив выписок кор-банков собран, ностро сверен независимо
• Тарифы реверс-инжинирены и заведены в fee_rules
• Импортер прогоняется одной командой, отчёт сверки PASS на стейджинге
• Shadow-прогон ≥ 2 недель с нулевыми расхождениями
• Смоук-чек-лист Client Bank написан и отрепетирован
• План cutover согласован с операционной командой, дата назначена