Продукт
AI CFO Bot
Записывает расходы и доходы обычным текстом в Telegram и выгружает отчёт в Excel.
Назначение проекта
AI CFO Bot — Telegram-приложение для управленческого финансового учёта малого бизнеса. Сервис избавляет предпринимателей от необходимости вручную заполнять сложные таблицы или мобильные приложения.
Основной пользовательский сценарий: ввод финансовых транзакций естественным языком в чате с ботом (например, «расход 2500 реклама авито», «доход 15000 от клиента», «клиент должен 12000 до пятницы»).
Архитектура: разделение слоёв
Приложение чётко разделено на три изолированных слоя: - bot/ (aiogram 3): отвечает за интерфейс Telegram, клавиатуры, машины состояний (FSM), пагинацию и клиентский HTTP-транспорт; - api/ (FastAPI): модульный REST-бэкенд для управления операциями, аналитикой, долгами, токенами доступа и выгрузками; - core/: доменная логика, модели PostgreSQL, клиент LLM, парсер выписок и генератор финансовых отчётов.
Ключевой принцип: ИИ не считает деньги
Одно из фундаментальных архитектурных решений проекта — строгое разграничение ролей: - Нейросетевая модель (через OpenRouter/DeepSeek) используется исключительно для NLP — извлечения сущностей из текста (сумма, категория, контрагент, дата, тип операции); - Все математические расчёты, суммирование, итоги периодов и балансы вычисляются детерминированным Python- и SQL-кодом на стороне бэкенда; - Вероятностная модель не допускается к операциям с балансом.
Порог уверенности и подтверждение операций
Для предотвращения случайных ошибочных записей внедрён контроль достоверности (confidence threshold ~75%).
Если уверенность модели в распознанных полях ниже порогового значения, бот не производит автосохранение, а выводит распознанные атрибуты и требует подтверждения действия через инлайн-кнопки.
Учёт задолженностей и отчётность
Бот поддерживает полноценный учёт дебиторской и кредиторской задолженности (создание долга, частичное или полное погашение, аннулирование, напоминания).
Реализована аналитика за день, неделю, месяц и произвольный интервал с возможностью генерации текстового саммари. Сформированные данные выгружаются в структурированный Excel-файл (XLSX) через openpyxl, а банковские выписки импортируются через pandas с предварительным просмотром.
База данных, безопасность и тесты
Хранилище спроектировано на PostgreSQL 16 (около 12 таблиц с составными индексами для быстрого поиска транзакций) и асинхронном SQLAlchemy 2 с миграциями Alembic.
Реализована multi-business модель с доступом по токенам и защитой от race conditions. Поддерживается команда /delete_my_data для полного удаления пользовательских данных. Модульные и интеграционные тесты на pytest-asyncio проверяют эндпоинты, корректность парсинга и целостность индексов.