Перейти к содержанию

Навигатор по технической документации Payment Manager для разработчиков и операторов.

Payment Manager — dev docs

Этот раздел собирает всё, что нужно человеку, который читает или меняет код PM: устройство сервиса, контракты API, внутренние модули, интеграции с TigerBeetle и PSP, процедуры эксплуатации и готовые рецепты для типовых задач. Каждый подраздел самодостаточен и ссылается на соседей по мере необходимости.

С чего начать

Новому разработчику рекомендуется идти по такому маршруту:

  1. architecture/01-overview.md — что такое PM, его границы и место в системе.
  2. architecture/02-module-map.md — карта внутренних модулей и как они связаны.
  3. architecture/03-intent-saga.md — поток intent от приёма до расчёта в ledger.
  4. modules/intent.md — главный модуль и точка входа в платёжный поток.
  5. api/intents.md — основной HTTP-контракт POST /intents.

После этого можно нырять в нужный модуль по карте или в reference/ за справочниками.

architecture/

Как PM устроен в целом: границы сервиса, поток intent, разделение схем PostgreSQL и роль TigerBeetle.

  • 01-overview.md — общая картина PM и его место в OneWallet.
  • 02-module-map.md — карта модулей src/ и кто кого зовёт.
  • 03-intent-saga.md — жизненный цикл intent и saga-механика.
  • 04-two-phase-channels.md — pending/post-расчёт для асинхронных каналов и синхронный INTERNAL.
  • 05-tigerbeetle-accounts.md — устройство TB-аккаунтов, типы и инвариант transit.balance = 0.
  • 06-deterministic-ids.md — детерминированная генерация TB account/transfer ID.

modules/

Карта внутренних модулей кода: что делает, где живёт, какие соседи зовут его и кого он зовёт.

  • auth.md — HMAC- и JWT-аутентификация, проверка X-Service-Id/X-Signature.
  • channels.md — реестр каналов (INTERNAL, IPPS, QP) и их различия.
  • intent.md — приём, нормализация и роутинг intent, главный entry point.
  • ledger.md — обёртка над TigerBeetle SDK, создание аккаунтов и трансферов.
  • limits.md — дневные/месячные лимиты и их проверка.
  • operation-types.md — реестр типов операций и их семантика.
  • policies.md — step-up auth policies (биометрия, PIN).
  • psp.md — psp-router, psp-worker и интеграция с PSP-адаптерами.
  • rule-engine.md — единый движок правил для fee/limit/policy.
  • shared.md — общие утилиты, конфиг, логгер, error-классы.
  • workers.md — OutboxWorker и фоновые роли (psp-worker, saga-worker).

api/

Внешние HTTP-контракты: эндпоинты, схемы, формат ошибок, HMAC и JWT.

  • accounts.md — GET /accounts/balance, история и read-only-доступ к TB.
  • admin.md — admin-эндпоинты (корректировки, ручное завершение intent).
  • auth.md — HMAC-схема для service-to-service и JWT для пользовательских роутов.
  • errors.md — единый формат ошибок и таблица кодов.
  • intents.md — POST /intents, GET /intents/:id, POST /intents/:id/confirm|cancel.
  • policies.md — эндпоинты для оценки и управления auth-политиками.

reference/passport/

Канонический контракт PM — DTO, перечисления, коды. Перед изменением парсеров и тестов сверяйся именно здесь.

reference/database/

Схема pm.* в PostgreSQL: таблицы, связи, миграции через Drizzle.

reference/

  • env-vars.md — справочник всех переменных окружения PM.

integrations/

Внешние зависимости PM. Старый closeloop — не используется, см. историю git.

  • admin-panel.md — read-only-доступ Admin Panel к TigerBeetle.
  • auth-center.md — JWT, вызовы POST /intents от Auth Center.
  • ipps.md — IPPS-драйвер и Phase 1 PSP-логика (psp-worker + PostgreSQL queue).
  • nginx.md — ingress, auth_request, проксирование /api/pm/*.
  • redis.md — pub/sub для intent-статусов и (Phase 2B) Redis Streams.
  • tigerbeetle.md — TB SDK, инварианты, two-phase transfers.

closeloop — не используется, см. историю git (старый docs/CLOSELOOP-INTEGRATION.md удалён).

operations/

Эксплуатация PM: запуск, миграции, мониторинг, разбор инцидентов.

  • deployment.md — Docker, окружения, выкат, конфиги.
  • health-checks.md — endpoint'ы readiness/liveness и их семантика.
  • monitoring.md — метрики, алёрты, дашборды.
  • runbook.md — разбор инцидентов и восстановление застрявших intent.
  • seed-and-migrations.md — seed-скрипты и порядок миграций.
  • worker-roles.md — роли процессов (api, outbox-worker, psp-worker, …).

cookbook/

Пошаговые рецепты под типовые задачи разработки.

testing/

Как устроены тесты PM.

  • examples.md — примеры тестов на типовые сценарии.
  • overview.md — обзор тестовой стратегии PM.
  • patterns.md — паттерны: fixtures, in-memory TB, мокирование PSP.