Модуль «Финансы»: архитектура, реализация и доработки

Цели и охват

• Двойная запись (double-entry) с отложенными проверками баланса.
• Номинальные счета, комиссионные доходы, задолженности партнёрам, возвраты.
• Мульти‑тенант: tenant_id в каждой таблице и функции.
• Идемпотентность, защита от дублей вебхуков, неизменяемость проводок.
• Автоматические синхронизации балансов кошельков.
• Отчёты: GMV, net revenue, ожидающие выплаты.
• RPC‑функции для безопасных транзакций: create_ledger_transaction, create_refund_transaction.
• FastAPI API, React UI (shadcn‑UI) для админов.

Данные и ограничения

• Таблицы: accounts, wallets, ledger_transactions, ledger_entries, payout_requests, invoice_documents, webhook_events_in.
• Ограничения:
• ledger_entries неизменяемы после вставки.
• Constraint trigger enforce_double_entry проверяет равенство суммы дебетов и кредитов.
• wallets синхронизируются из ledger_entries при изменении (триггеры).
• Идемпотентность и антиповторы на уровне индексов.

RPC‑функции

• create_ledger_transaction(...):
• Создаёт транзакцию ledger_transactions со статусом posted.
• Вставляет массив проводок ledger_entries для этой транзакции.
• Возвращает JSON с идентификаторами.
• create_refund_transaction(...):
• Находит исходную транзакцию и проверяет суммы.
• Создаёт возврат refund с инверсией направлений проводок.
• Делит сумму возврата пропорционально исходным проводкам, учитывая округление.

FastAPI

• Роутер /api/v1/finance:
• POST /charges — создание операции списания с разнесением на номинальный счёт, задолженность партнёру и комиссию портала.
• POST /refunds — частичный или полный возврат.
• POST /payouts/requests — заявка на выплату партнёру.
• GET /wallets — список кошельков текущего tenant.
• GET /reports/gmv и GET /reports/net-revenue — отчёты за период.
• GET /reports/pending-payouts — ожидающие выплаты.
• Сервис:
• Автосоздание недостающих счётов при первом обращении.
• Привязка реальных account_id по code+currency с владельцем.

React (Админ)

• Страница /admin/finance:
• Фильтр по дате.
• Карточки GMV, net revenue, ожидающие выплаты.
• Таблица кошельков: баланс/доступно/ожидает.
• Форма создания payout‑заявки с идемпотентным заголовком.

Верификация и тесты

• Линт/типизация: npm run lint, сборка.
• Интеграционные тесты RPC:
• Проверяют пропорциональный partial refund.
• Гарантируют double‑entry баланс при транзакциях.

Доработки

• Чарт‑оф‑аккаунтс: выделить обязательные шаблоны по аренде/страховке/доп.услугам и миграции для их начального наполнения.
• Расширить отчёты: маржинальность по направлениям, комиссии по поставщикам, удержания, акты сверок.
• Провести нормализацию кошельков: разделить кошельки партнёров и номинальные на уровень справочника.
• Настроить роле‑бэйзд доступ: только админы могут видеть агрегированные отчёты; партнёры — только свои кошельки и выплаты.
• Добавить события в шину: finance.transaction.posted, finance.payout.requested для аудита и нотификаций.
• Метрики и алерты: ошибки double‑entry, недостающие счета, отклонения по отчётам.
• Вебхуки провайдеров: валидация подписей и регламент повторной доставки.