Платформа ликвидности · MVP для SBER HACK

Цифровая площадка трансграничного финансирования между юрлицами: российские компании публикуют заявки на ликвидность, проверенные зарубежные кредиторы присылают предложения, платформа сравнивает их по полной стоимости и ведёт сделку до статуса «Согласовано».

Демо: https://sber-delta.vercel.app · на странице входа в демо-режиме есть кнопки входа в любую роль.

---

Сценарий за 3 минуты

1. Заёмщик (ООО «Альфа Технологии») — заявка №1: три предложения, отсортированные по полной стоимости, лучшее выделено, видна экономия. Можно принять или отклонить.
2. Кредитор (Beta Capital Ltd) — лента заявок с фильтрами по стране, валюте, сумме и сроку; при заполнении предложения сразу видна полная стоимость, которую увидит заёмщик.
3. Оператор — только то, на что сработали автоматические правила: предложение со ставкой далеко от рынка, крупная заявка; жалоба кредитора на заявку. Подтверждение сделки — только при договоре и KYC обеих сторон.
4. Администратор — очередь KYC, ручная проверка заявок и жалобы, аналитика по валютам и странам, архив согласованных сделок, кнопка «Сбросить демо-данные».

Что реализовано

Требование	Реализация
Регистрация юрлиц с ролями, KYC/AML через администратора	Заёмщик (РФ, ИНН из 10 цифр) или кредитор (страна + рег. номер). Пакет документов PDF, решение администратора по всему пакету: одобрение или отказ с причиной, которую видит компания
Заявка: сумма и валюта, юрисдикция, назначение, срок, способ передачи, модерация	Все поля, способы передачи SWIFT / СПФС / CIPS / платёжный агент. Модерация автоматическая: правила проверяют сумму, срок, назначение и стоп-слова и публикуют заявку сразу. Оператору уходят только первая заявка компании и суммы выше порога; опубликованную заявку оператор снимает по жалобе кредитора
Отклики кредиторов с фильтрами по стране, сумме и сроку	Фильтры страна / валюта / сумма от–до / срок до. Предложение: сумма к выдаче, ставка, комиссия за организацию, дополнительные условия
Статусная модель, принятие/отклонение, чат, «В работе» / «Согласовано», архив и история	Шкала этапов Проверка → Публикация → Предложения → Сделка → Договор → Согласовано; предложение видно заёмщику сразу после автопроверки, оператор показывает или скрывает только отмеченные правилом; заёмщик принимает или отклоняет; чат и документы сделки; журнал событий каждой заявки; архив согласованных сделок
Аналитика: количество заявок, средний размер, топ-страны по спросу и предложению	Средний размер — отдельно по каждой валюте; спрос — страны получения средств; предложение — страны кредиторов; доля заявок, дошедших до сделки

Сверх задания.

• Калькулятор полной стоимости на главной: сумма, валюта, срок, ставка и комиссия; переплата в рублях по курсу ЦБ РФ; подсказка средних условий на платформе.
• Профиль и рейтинг кредитора (/creditors/{id}): завершённые сделки, средняя ставка и комиссия, скорость ответа, доля принятых предложений. Рейтинг из 5 появляется после первой сделки или трёх решений заёмщиков. Профиль видят заёмщики, которым показали предложение, сам кредитор и сотрудники.
• Автоматическая проверка вместо ручной модерации (services/screening.py, пороги в config.py). Жёсткие правила отклоняют сразу с понятной причиной: сумма заявки, длина назначения, стоп-слова, ставка до 50%, комиссия кредитора до 10%, минимум 10% суммы. Мягкие правила отправляют оператору: первая заявка компании, сумма выше порога, ставка дальше 5 п. п. от рыночной (медиана показанных предложений в валюте). Кредиторы могут пожаловаться на опубликованную заявку.
• Сроки ответа: KYC 48 ч, ручная проверка заявки 24 ч, ручная проверка предложения 24 ч. У сотрудников задачи подсвечиваются «осталось …» / «просрочено на …».
• Проект договора займа в PDF (/deal/{id}/contract-draft.pdf): стороны, сумма, ставка, комиссия, срок и график подставлены из сделки.
• Выгрузка для администратора в Excel (/admin/export.xlsx): аналитика, сделки, заявки, предложения.
• Сохранённые фильтры кредитора (до 5): уведомление о каждой новой опубликованной заявке, которая под них подходит.
• Страница «Безопасность и документы» (/security): как проверяются участники, кто что видит, перечень документов KYC, сроки.
• Частичное финансирование: заявку собирают из нескольких предложений. Сделка начинается, когда сумма покрыта, или раньше — по решению заёмщика. Несколько кредиторов работают как синдикат: общий чат, ставка и комиссия средневзвешенные, доли в проекте договора и PDF-сводке.
• Встречное предложение: заёмщик просит снизить ставку (одно на оффер), кредитор соглашается или оставляет свою.
• Сроки действия: заявка открыта 30 дней после публикации, предложение — 7/14/30 дней на выбор кредитора. Просроченные закрываются автоматически с уведомлениями.
• Журнал действий сотрудников для главного администратора (вкладка «Журнал»).
• Отпечаток SHA-256 загруженного договора: все стороны видят, что у них один и тот же файл.
• Валютный риск: сколько рублей вернуть при ослаблении рубля на 10–30% — в калькуляторе и в сделке.
• Автозаполнение по ИНН из ЕГРЮЛ через DaData (переменная DADATA_API_KEY, без неё выключено).
• Чек-лист первых шагов в кабинетах заёмщика и кредитора.
• Главная: живые цифры платформы и схема потоков ликвидности; админка: тепловая карта «страна × валюта», ставки по неделям, время этапов; в сравнении предложений — полосы полной стоимости.

Сравнение предложений. Для каждого оффера: проценты за срок заявки, комиссия в деньгах, переплата и полная стоимость в % годовых = ставка + комиссия × 12 / срок. Экономия лучшего предложения считается на сумму заявки, чтобы офферы с разной суммой к выдаче сравнивались честно.

Архитектура

main.py                  точка входа (Vercel / uvicorn ищут здесь app)
liquidity/
  config.py              переменные окружения и справочники (валюты, страны, статусы, документы KYC)
  database.py            подключение к БД, миграции новых колонок
  models.py              ORM: users, applications, offers, documents, messages, application_events, stored_files
  security.py            пароли (bcrypt), сессия (JWT в httpOnly-cookie со сроком), роли, CSRF
  web.py                 шаблоны Jinja2, форматирование сумм и процентов
  services/              бизнес-логика без HTTP
    accounts.py          регистрация, вход, сотрудники
    kyc.py               пакет документов и решение администратора
    applications.py      заявки, модерация, поиск с фильтрами, этапы
    offers.py            предложения, проверка оператором, решение заёмщика
    deals.py             доступ к сделке, чат, договор, подтверждение
    costs.py             полная стоимость и сравнение предложений
    analytics.py         аналитика и архив
    files.py             безопасная загрузка и выдача файлов
    events.py            история заявки
    demo.py              демо-данные
  routers/               HTTP-слой по ролям: auth, borrower, creditor, kyc, deals, operator, admin
  app.py                 сборка FastAPI: middleware, обработчики ошибок, роутеры
templates/               base.html (каркас и меню по ролям), _ui.html (общие элементы), экраны
static/css/app.css       дизайн-система без внешних CDN
tests/                   pytest: сквозной сценарий, сервисы, безопасность

Роутеры только принимают форму, проверяют роль (require_role) и вызывают сервис; сервисы бросают доменные исключения NotFound / Forbidden / Invalid, которые app.py превращает в ответы 404 / 403 / 400.

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

• Роли проверяются на сервере зависимостью require_role на каждом маршруте; самостоятельно можно зарегистрироваться только заёмщиком или кредитором.
• CSRF — double-submit: случайный токен в httpOnly-cookie и в скрытом поле каждой формы, глобальная проверка всех POST.
• XSS — автоэкранирование Jinja2; пользовательский ввод нигде не выводится как HTML.
• Сессия — JWT в cookie httpOnly, SameSite=Lax, Secure на HTTPS, срок жизни SESSION_HOURS (8 ч).
• Данные — сделку и её файлы видят только заёмщик, принятый кредитор и сотрудники; документы KYC — владелец и сотрудники; имена файлов очищаются, размер ограничен 4 МБ; если предложение ушло на ручную проверку, до решения оператора заёмщик не видит, кто его прислал.
• Заголовки X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy.

Описание API

Интерфейс серверный (HTML-формы). Полная схема — /docs (Swagger) и /openapi.json.

Метод и путь	Роль	Назначение
GET / · POST /login · GET /logout	все	вход и выход
GET/POST /register	гость	регистрация юрлица
GET /dashboard	все	кабинет по роли
GET /kyc · POST /kyc/upload · POST /kyc/submit	заёмщик, кредитор	пакет документов KYC
POST /create_application	заёмщик	заявка (автопроверка; подозрительные — оператору)
POST /applications/{id}/complain	кредитор	жалоба на опубликованную заявку
GET /applications/{id}/offers	заёмщик	карточка заявки: этапы, сравнение, история
POST /accept_offer/{id} · POST /reject_offer/{id}	заёмщик	решение по предложению
POST /create_offer/{app_id}	кредитор	предложение по опубликованной заявке
GET /operator/offers · POST /operator/offer/{id}/show · /hide	оператор, админ	предложения, отмеченные автопроверкой
GET /operator/deals · GET /operator/deal/{id} · POST /operator/deal/{id}/confirm	оператор, админ	проверка и подтверждение сделки
GET /deal/{id} · POST /deal/{id}/send · /upload_contract · /call_operator	участники, сотрудники	комната сделки
GET /uploads/{file}	владелец, участники, сотрудники	скачать документ
GET /admin · POST /admin/application/{id}/moderate · POST /admin/complaint/{id}/dismiss	админ, оператор	аналитика, архив, ручная проверка заявок, жалобы
POST /admin/kyc/approve_user/{id} · /reject_user/{id}	админ

Запуск локально

pip install -r requirements.txt
cp .env.example .env        # заполните DATABASE_URL, SECRET_KEY, ADMIN_EMAIL, ADMIN_PASSWORD
uvicorn main:app --reload

Для быстрого старта без PostgreSQL: DATABASE_URL=sqlite:///./local.db DEMO_MODE=1 uvicorn main:app.

Переменная	Назначение
DATABASE_URL	PostgreSQL (на Vercel подставляется интеграцией Neon) или SQLite
SECRET_KEY	подпись сессий — длинная случайная строка
ADMIN_EMAIL, ADMIN_PASSWORD	первый администратор, создаётся при старте
DEMO_MODE=1	демо-данные и вход в роли одной кнопкой
SESSION_HOURS	срок жизни сессии, по умолчанию 8
DADATA_API_KEY	необязательно: автозаполнение компании по ИНН при регистрации (бесплатный ключ на dadata.ru)

Деплой на Vercel

Vercel сам распознаёт FastAPI в main.py; каждый push в main выкатывается автоматически, для других веток — превью-ссылка.

1. Vercel → Add New → Project → импорт репозитория с GitHub.
2. Storage → Create Database → Neon (Postgres) → подключить к проекту.
3. Settings → Environment Variables: SECRET_KEY, ADMIN_EMAIL, ADMIN_PASSWORD, для презентации — DEMO_MODE=1.
4. Deployments → Redeploy.

Таблицы и новые колонки создаются при старте. Файлы хранятся в БД (у Vercel нет постоянного диска), лимит файла — 4 МБ.

Тесты

pip install -r requirements.txt -r requirements-dev.txt
pytest -q

• tests/test_flow.py — сквозной сценарий из задания: регистрация → KYC с отказом и повторной подачей → модерация → фильтры → предложения → оператор → отклонение и принятие → договор → «Согласовано» → архив и аналитика; доступ к файлам.
• tests/test_services.py — расчёт полной стоимости и сравнение, этапы, аналитика по валютам, валидация регистрации, демо-данные (сброс не трогает реальные данные).
• tests/test_autocheck.py — автоматическая проверка: публикация сразу, флаги для оператора, ставка далеко от рынка, стоп-слова, жалобы кредиторов.
• tests/test_feedback.py — KYC и чат без перезагрузки, удаление договора, главный администратор, модерация оператором, снятие заявки, подсказки к терминам.
• tests/test_extras.py — калькулятор, профиль и рейтинг кредитора, сроки ответа, проект договора, выгрузка в Excel, сохранённые фильтры, страница безопасности.
• tests/test_more.py — частичное финансирование и синдикат, встречная ставка, сроки действия, журнал, отпечаток договора, валютный риск, ИНН, графики, английская версия, PWA.
• tests/test_security.py — CSRF, флаги и срок сессии, поддельный и истёкший токен, ролевая модель, экранирование HTML, заголовки, демо-режим.

Тесты запускаются на GitHub Actions при каждом push (.github/workflows/tests.yml).

Стек

Python 3.12, FastAPI, SQLAlchemy 2, PostgreSQL (Neon), Jinja2, python-jose, passlib/bcrypt · собственная дизайн-система на CSS · Vercel.