§ 01О чём проектWhat this is
Банк выдаёт кредиты малому бизнесу. На каждую заявку у кредитного аналитика уходит 2 – 4 часа: вручную собрать налоговые выписки клиента, счета-фактуры, справки из ГНК, посчитать кучу коэффициентов, оформить отчёт для кредитного комитета. Полдня впустую — а заявок десятки в день. The bank issues SME loans. Each application takes a credit analyst 2 – 4 hours: manually collecting tax exports, invoices, GNK certificates, calculating a pile of ratios, formatting a report for the credit committee. Half a day wasted — and there are dozens of applications a day.
Задача: сделать так, чтобы тот же отчёт собирался за 8 – 20 минут без потери качества. Система берёт исходные документы клиента (налоговые формы, счета, справки), прогоняет через 24 проверки и считает 8 ключевых показателей, выдаёт PDF на двух языках — русский и узбекский — с обоснованием по каждой цифре. Goal: shrink the same report to 8 – 20 minutes without losing quality. The system takes the client's source documents (tax forms, invoices, certificates), runs them through 24 checks and computes 8 key indicators, produces a PDF in two languages — Russian and Uzbek — with a justification for every figure.
Где работает: продано и работает в коммерческом банке Узбекистана (имя под NDA). Интересуются ещё две финансовые организации. Сервер банка не подключён к интернету — требование банковской безопасности: данные клиентов физически не могут утечь. Where it runs: sold and live at a commercial bank in Uzbekistan (name under NDA). Two more financial institutions are in talks. The bank's server has no internet — that's serious banking security: client data must not leak.
§ 02Как устроеноHow it's built
Один сервис, но разделён на части так, чтобы каждую можно было менять отдельно. Логика кредитных решений — отдельно от базы данных, отдельно от веб-интерфейса. Это значит: банк просит перерисовать PDF — код решений не трогаем. Завтра приходит второй банк-клиент — подключаем без переделок. One service, but split into parts so each can be changed independently. The credit-decision logic is separate from the database and from the web UI. That means: bank asks to redesign the PDF — we don't touch the decision code. Tomorrow a second bank-client comes in — we plug them in without rewrites.
┌─────────────────────────────────────────────────────────┐ │ ВЕБ FastAPI — приём запросов, OpenAPI-документация │ │ два интерфейса: для банка + для бухгалтера │ ├─────────────────────────────────────────────────────────┤ │ СЕРВИС движок правил · расчёт показателей · оценка │ │ сценарии работы · права доступа · LDAP/MFA │ ├─────────────────────────────────────────────────────────┤ │ ЛОГИКА 24 проверки · 8 показателей · модели данных │ │ чистая бизнес-логика, без баз и сети │ ├─────────────────────────────────────────────────────────┤ │ ИНФРА Postgres · LDAP · WeasyPrint (PDF) · Redis │ │ парсеры: налог. выписки · счета · справки ГНК │ ├─────────────────────────────────────────────────────────┤ │ КОНФ. настройки на каждый банк-клиент отдельно │ │ проверка ключей шифрования при старте — не упадёт молча│ └─────────────────────────────────────────────────────────┘
Один движок — два интерфейсаOne engine — two interfaces
Под капотом — те же 24 проверки и 8 показателей. Снаружи — два разных режима работы: Under the hood — same 24 checks and 8 indicators. Outside — two different modes:
- Для банка — полный режим. Кредитный аналитик заходит через корпоративный логин с двухфакторкой, загружает документы клиента, получает готовый PDF на двух языках для кредитного комитета. Каждое действие записывается в журнал — кто открыл, кто скачал, когда. For the bank — full mode. A credit analyst logs in via corporate SSO with 2FA, uploads client documents, gets a ready-made bilingual PDF for the credit committee. Every action is logged — who opened it, who downloaded it, when.
- Для бухгалтера МСБ — упрощённый режим. Бухгалтер видит «что бы увидел банк по моему клиенту» и может поправить данные до того, как клиент пойдёт за кредитом. Бухгалтеры приводят клиентов в банк — все довольны. For the SME accountant — simplified mode. The accountant sees "what the bank would see for my client" and can fix the data before the client applies for a loan. Accountants bring clients to the bank — everyone happy.
24 проверки и 8 показателей24 checks and 8 indicators
Проверки ловят конкретные риски. Например: резкое падение выручки, смена директора прямо перед заявкой, непонятные контрагенты, расхождение между налоговой декларацией и реальными счетами, перекредитованность. Каждая проверка ссылается на конкретный источник — приказ ЦБ Узбекистана, статью налогового кодекса, банковский стандарт или академическое исследование. Не «по опыту банкиров», а «по приказу №X пункту Y». Checks catch concrete risks. Examples: sharp revenue drop, director change right before the application, suspicious counterparties, mismatch between tax declarations and actual invoices, over-leverage. Each check cites a concrete source — a CBU regulation, a tax code article, a banking standard, or academic research. Not "based on banker experience" but "based on regulation X paragraph Y".
Показатели — это привычные банкиру цифры: прибыль, отношение долга к прибыли, оборотные средства, способность бизнеса покрывать выплаты по кредиту. Если в данных не хватает чего-то для расчёта — показатель честно показывает «нет данных», а не подставляет ноль. Это важно: ноль выглядит как реальная цифра и может стоить банку решения. Indicators are familiar numbers for any banker: profit, debt-to-profit ratio, working capital, the business's ability to cover loan payments. If something's missing in the data — the indicator honestly shows "no data" rather than substituting zero. That matters: zero looks like a real number and can cost the bank a decision.
§ 03Что было сложноWhat was hard
1. Документы клиентов в десяти разных видах1. Client documents in ten different shapes
Клиент банка приносит данные из трёх систем: налоговая, электронные счета-фактуры, справки ГНК. И только внутри налоговой — пять разных форм отчётности. Каждая форма год от года чуть меняется: появляются новые колонки, заголовок сдвигается на строку. Парсер должен это всё съесть и не подавиться. A bank client brings data from three systems: tax authority, e-invoice platform, GNK certificates. Inside the tax authority alone — five different report forms. Each form changes slightly year over year: new columns appear, the header shifts a row. The parser needs to swallow all of it and not choke.
Решение — на каждый тип документа свой разборщик, плюс ручной ввод для случаев, когда клиент принёс данные на бумаге. Внутри системы все данные приводятся к одному виду — дальше алгоритмам уже всё равно, откуда они пришли. Solution — a dedicated parser for each document type, plus manual input for cases when the client brings paper records. Inside the system everything is normalized to a single shape — from there on, the algorithms don't care where it came from.
2. PDF на двух языках, который выглядит одинаково везде2. A bilingual PDF that looks the same everywhere
Отчёт идёт на русском и узбекском. Узбекский — латиницей по умолчанию (так в налоговой), но ИНН и коды деятельности — кириллицей (так в госреестре). Шрифты вшиты прямо в систему вместе с лицензиями — потому что банковский сервер не может скачивать шрифты из интернета. Результат: PDF выглядит одинаково на сервере банка, на моём ноутбуке и на принтере кредитного комитета. The report goes out in Russian and Uzbek. Uzbek — Latin by default (that's what the tax authority uses), but tax IDs and activity codes stay in Cyrillic (that's what the state registry uses). Fonts are bundled into the system together with their licenses — because the bank's server can't download fonts from the internet. Result: the PDF looks the same on the bank's server, on my laptop, and on the credit committee's printer.
Один отчёт собирается ~0.75 секунды. Не «когда-то рендерится» — а нажал кнопку, и через секунду готовый PDF в руках. One report assembles in ~0.75 seconds. Not "renders eventually" — press the button and within a second the PDF is in your hands.
3. Сервер без интернета3. A server without internet
Банковский сервер физически отключён от интернета — это требование безопасности. Обновления приходят на флешке: я собираю новую версию у себя, проверяю, отправляю банку. Это значит — никаких «о, сейчас докачаем библиотеку из интернета». Всё, что нужно для работы, лежит внутри готового пакета. Ошибиться нельзя — некому передать «у нас не работает», когда тыкать палкой удалённо невозможно. The bank's server is physically disconnected from the internet — that's a security requirement. Updates arrive on a USB stick: I build a new version locally, test it, hand it to the bank. That means no "oh let's just download a library from the internet". Everything needed to run is inside the package. You can't afford mistakes — there's no one to forward "it's not working" to when you can't poke things remotely.
§ 04ЦифрыNumbers
Систему отдельно проверял независимый аудитор — выставил 8.5/10 за качество архитектуры: «преобразования данных симметричны, миграции базы дисциплинированы». The system was independently audited — 8.5/10 for architecture quality: "data transformations are symmetric, DB migrations are disciplined".
Что работает сейчас: система продана и запущена в коммерческом банке Узбекистана. Имя банка под NDA — как и положено в финансовом секторе. Что открыто и можно проверить — код, тесты и CI в публичном репозитории. В разговорах две другие финансовые организации. Точные цифры по объёму проходящих заявок — тоже под NDA. What's live now: sold and deployed at a commercial bank in Uzbekistan. The bank's name is under NDA — standard for the financial sector. What's open and verifiable: the code, tests and CI in a public repository. Two other financial institutions are in talks. Exact figures on processed applications volume are also under NDA.
Проверяемо. Код, тесты и CI — в открытом репозитории. Цифры выше можно не принимать на слово, а запустить у себя: Verifiable. The code, tests and CI are in a public repository. You don't have to take the numbers above on trust — run them yourself:
§ 05Что я вынесLessons learned
(а) Чем строже проверять данные на входе — тем меньше сюрпризов внутри. Если на границе системы пропустить кривую цифру — она будет всплывать в самых неожиданных местах три месяца спустя. Если развернуть на входе — фиксится один раз и навсегда. (a) The stricter you validate input data — the fewer surprises inside. If you let a malformed number cross the boundary — it'll resurface in the strangest places three months later. Catch it at the entrance — fix it once, for good.
(б) Правила со временем меняются — закладывайте это. ЦБ поменяет один коэффициент в положении — нужно уметь объяснить, почему прошлогодние решения были правильными по тогдашним правилам. Версии правил с датой действия — дорого вначале, бесценно через полгода. (b) Rules change over time — plan for it. The Central Bank changes a coefficient in a regulation — you need to be able to explain why last year's decisions were correct under the rules in force at the time. Versioned rules with effective dates — expensive up front, priceless six months in.
(в) Источникам нельзя верить с первого захода. Если ваше решение опирается на «приказ №X статью Y» — проверьте, что и приказ существует, и статья там та, что вы думаете. На следующем банковском проекте я закладывал отдельные дни на эту проверку с первого дня. (c) Don't trust sources on the first pass. If your decision rests on "regulation X article Y" — verify both that the regulation exists and that the article is what you think it is. On the next banking project, I budgeted dedicated days for this check from day one.
(г) «Сервер без интернета» — это отдельный мир. Закладывайте две недели сверху, если делаете для банка впервые. Всё, что вы привыкли «потянуть из репозитория во время сборки» — придётся положить заранее. Ошибиться нельзя: тыкать палкой удалённо некому. (d) "Server without internet" is its own world. Budget two extra weeks if it's your first bank project. Everything you're used to "pull from the repo at build time" — you'll need to bundle ahead. You can't afford mistakes: there's no one to remote-poke things.