Документация проекта¶
Этот каталог описывает кредитный конвейер «Альфа · Бизнес»: предметную область, пользовательский и банковский процессы, решение по заявке, данные, интерфейсы и ограничения прототипа. Документы написаны по-русски. Имена файлов, код, идентификаторы и API оставлены на английском.
Адрес онлайн-версии после настройки DNS и деплоя: docs.etabank.ru. Демонстрационное приложение работает отдельно: etabank.ru.
С чего начать¶
| Читатель | Рекомендуемый порядок |
|---|---|
| Эксперт или демонстратор | Корневой README → демо-персоны → модель процесса → реестр упрощений |
| Бизнес-аналитик | условия и Q&A хакатона → модель процесса → спецификация кредитной логики v2 → модель данных → контракты |
| Разработчик | архитектура → спецификация v2 → задачи и решения команды → документация нужного компонента ниже |
| Эксплуатация | запуск и демо → VPS → SLA и критичность |
Документы верхнего уровня¶
| Документ | Назначение и содержание |
|---|---|
| Корневой README | Назначение прототипа, запуск, переменные окружения, демо-профили и сценарии проверки, LLM, Telegram, API и проверочные команды |
| Архитектура | Сервисы и модули, поток обработки решения, каналы клиента, безопасность и эксплуатационные границы |
| Модель кредитного процесса | Роли, этапы, статусы и обоснование включённых, упрощённых и отсутствующих шагов |
| Модель данных | Хранимые сущности и файлы, версии решения, доступ клиента и сотрудника |
| SLA и критичность | Критичные этапы и механизмы устойчивости прототипа |
| Упрощения и моки | Внешние системы и бизнес-операции, заменённые синтетическими данными, заглушками или упрощённым процессом |
| Условия хакатона и выжимка Q&A | Требования кейса и ответы экспертов, используемые при выборе объёма и поведения прототипа |
Проектирование кредитного решения¶
- Спецификация v2 — предметная логика: качество данных, этапы конвейера, стоп-факторы и флаги, скоринг, лимит, ставка, набор предложений, маршрутизация, роли и статусы.
- Контракты v2 — форматы между источниками данных, API, скорингом и интерфейсами; схемы Pydantic в
apps/api/contracts.pyостаются источником правды. - Задачи и журнал решений — разбивка разработки по трекам, владельцы и принятые решения.
- Заметки между задачами — открытые передачи и ограничения, которые ещё требуют внимания.
- Каталог
config/— JSON-файлы кредитной политики, признаков, качества данных и маршрутизации; назначение и версии параметров описаны также в соответствующих документах компонентов.
Спецификация v2 является авторитетным описанием кредитной логики. Старые модули v1 и анкета из 43 вопросов не участвуют в основном сценарии; их статус отмечен в docs/v2/NOTES.md и AGENTS.md.
Документация компонентов¶
| Компонент | Руководство | Что покрывает |
|---|---|---|
| Синтетический мир | apps/world, персоны | Генерация компаний и финансовых историй, воспроизводимость, ожидаемые исходы демо |
| Источники данных | apps/sources | Моки внешних систем, обогащение заявки, повторы, тайм-ауты и сценарии недоступности |
| Признаки | библиотека признаков | Вычисление признаков, качество данных, правила по просрочкам и выручке |
| Скоринговая модель | apps/ml, модуль скоринга | Обучение на синтетическом мире, валидация, версии и интерфейс моделей |
| API и жизненный цикл | workflow, OpenAPI, HTTP-сценарий | Маршруты, переходы статусов, контрактные запросы и ответы |
| Стоп-факторы | apps/api/STOP_FACTORS.md | Блокирующие основания и предупреждения для ручного рассмотрения |
| Лимит и ставка | apps/api/LIMITS.md | Расчёт денежного потока, доступного лимита и составляющих ставки |
| Предложения | apps/api/OFFERS.md | Подбор вариантов финансирования, маршруты и объяснения для клиента |
| Решения сотрудников | маршрутизация, действия сотрудников | Полномочия, ручное рассмотрение, комитет, переопределения и журнал действий |
| Выписки | apps/api/STATEMENTS.md | Запрос, загрузка и проверка выписок из другого банка |
| Подписание и выдача | apps/api/DISBURSEMENT.md | Документы, код подтверждения, отлагательные условия и мок зачисления |
| Предодобрение | apps/api/PREAPPROVAL.md | Пакетный расчёт и выдача предодобренного предложения |
| Веб-клиенты | apps/web, mini app | Кабинет предпринимателя, рабочее место банка и компактный интерфейс |
Поток обработки заявки¶
- Действующий клиент выбирает компанию по ИНН и даёт необходимые согласия. Регистрация нового бизнеса и подключение реальных банковских систем не входят в сценарий.
- Клиент описывает потребность в финансировании. История бизнеса и подтверждаемые сведения загружаются из внутренних мок-источников; при недостатке данных система может запросить выписку.
- Конвейер проверяет источники и качество данных, рассчитывает признаки, проверяет стоп-факторы, выполняет скоринг, рассчитывает лимит и ставку и строит предложения.
- Автоматическое решение либо передаёт заявку сотруднику в соответствии с матрицей полномочий. Сотрудник видит досье, причины и события и выполняет действия в пределах своей роли.
- Клиент выбирает условия, подтверждает подписание кодом, проходит проверку отлагательных условий и видит результат моковой выдачи.
Порядок, статусы и альтернативные ветви процесса подробно заданы в PROCESS.md и SPEC.md. Для готовых примеров используйте сценарии и персоны из корневого README.
Устройство решения и данные¶
Приложение состоит из API на Python, клиентских интерфейсов на React/TypeScript, фонового worker и PostgreSQL при запуске через Docker Compose. Без Docker поддерживается локальный запуск с SQLite. Синтетический мир генерируется в репозитории и используется моками источников и обучением скоринговой карты.
Основные каталоги:
apps/world/ синтетические компании, история и демо-персоны
apps/sources/ симуляторы источников и обогащение заявок
apps/api/ API, признаки, решение, роли, статусы и журнал
apps/ml/ обучение и валидация скоринговой карты
apps/web/ основной веб-интерфейс клиента и банка
apps/mini/ компактный интерфейс клиента
config/ версии политик и порогов
docs/ аналитика, спецификации, OpenAPI и инструкции
tests/ модульные и сквозные проверки, фикстуры контрактов
scripts/ настройка окружения и генерация артефактов
deploy/ конфигурация развёртывания
misc/ исходные материалы кейса и Q&A
Подробности о таблицах, файлах и воспроизводимости решения находятся в модели данных. Схема маршрутов публикуется в OpenAPI; примеры последовательных запросов находятся в requests.http.
Ограничения и корректное прочтение результата¶
- Все компании, финансовые записи, ответы источников и кредитные исходы в демонстрации синтетические.
- Внешние проверки, согласия, SMS/код, реестры, подписание и зачисление представлены моками или симуляциями. Живых интеграций нет.
- Скоринговая карта обучена на синтетических данных. Метрики демонстрируют работу процесса обучения и валидации, но не подтверждают качество кредитного риска на реальном портфеле.
- Кредитные пороги, продукты и ставки — демонстрационная политика из конфигурации, а не предложение или действующие условия Альфа-Банка.
- LLM-помощник необязателен и не принимает решения. Основной сценарий работает без него; доступные ограничения контекста описаны в корневом README.
- Текущий объём заканчивается подписанием и моковой выдачей. Сопровождение кредита после выдачи и реальные проводки вне объёма.
Полный перечень упрощений и их обоснования — в реестре.
Актуализация документации¶
При изменении поведения обновляйте руководство компонента и связанные аналитические материалы в том же изменении. Контракты и конфигурацию сверяйте с кодом и фикстурами; описания не заменяют схемы и реализацию. Изменения функциональности отражайте в корневом README, статус задачи — в docs/v2/TASKS.md, а незакрытую передачу — в docs/v2/NOTES.md согласно правилам AGENTS.md.