CoinCounter 📈

Финансовый ассистент для малого бизнеса и ИП с NLP, автоматизирующий учёт банковских транзакций

⚡ Работает в production 3+ года

💡 История проекта

CoinCounter создавался для небольших ИП и собственников бизнеса, которые не имеют возможности нанять экономиста или платить дорогие подписки за популярные финансовые сервисы.

Проблема: Ручной учёт транзакций отнимает 2-3 часа каждую неделю, а бесплатные решения не дают нужной аналитики.

Решение: Полностью автоматизированная система с AI/NLP-категоризацией, работающая на вашем сервере. Все данные под контролем, никаких подписок.

🎯 Ключевые возможности

📊 Автоматическая категоризация транзакций (99.6% точность)
- 🧠 Продвинутый NLP-алгоритм (подробнее)
- 🔍 Multi-query + Lemmatization + Synonyms + Vector Search
- 🚀 Три источника: по ИНН, по ключевым словам, через AI embeddings
📱 Telegram-уведомления в реальном времени
📑 Экспорт в Google Sheets для совместной работы
📈 Интерактивный Dashboard с аналитикой и графиками
🔗 Интеграция с Битрикс24 для анализа воронки продаж
🎛️ Django Admin для удобного управления данными
💾 Доступ к данным: SQLite + Django Admin (интерфейс для всех операций)

Работает на реальных данных малого бизнеса 3+ года без проблем

🤖 NLP-алгоритм категоризации

Система использует продвинутый многоуровневый NLP-алгоритм для автоматической категоризации транзакций:

Технологии

Multi-Query: разбиение сложных назначений платежей на смысловые единицы
Лемматизация (pymorphy2): приведение слов к начальной форме
Синонимы (RuWordNet): расширение поиска через семантически близкие слова
Vector Search: косинусное расстояние между embedding-векторами (OpenAI API)
Smart Boosting: бонусы за точное совпадение, лемму и синонимы

Формула итогового скора

final_score = base_embedding_similarity 
              + (0.25 if exact_match else 0)
              + (0.15 if lemma_match else 0)
              + (0.10 if synonym_match else 0)

Точность

99.6% (3021/3033 транзакций на реальных данных)
Время обработки: 5-15ms на транзакцию (с кэшем)

📖 Подробное описание алгоритма: NLP_ALGORITHM.md

📸 Примеры интерфейсов

📊 Dashboard: Аналитика в реальном времени

Возможности:

📈 Графики выручки и себестоимости по месяцам
💰 KPI карточки (выручка, расходы, прибыль, маржинальность)
📊 Детальные метрики по месяцам
🏷️ Расходы по категориям
📅 Фильтрация по годам

📱 Telegram Bot: Уведомления и быстрый доступ

Возможности:

✅ Итоги загрузки транзакций
💵 Выручка по контрагентам
📉 Расходы по категориям
🤖 Статистика NLP-категоризации
⚠️ Неразнесённые транзакции

🎛️ В каком виде выгружаются данные в google sheets

📑 Google Sheets: Экспорт и совместная работа

Важно: это примеры и в проекте их нет. Но вы всегда можете собрать такие сводные таблички и диаграммы самостоятельно.

Возможности:

📊 Автоматический экспорт новых транзакций
🔄 Синхронизация с существующими таблицами
📈 Базовая аналитика и сводные таблицы (вы настраиваете самостоятельно)
👥 Совместный доступ для команды

⚡ Производительность

Оптимизация 2026: Добавлено 10 индексов БД для быстрых запросов

Операция	До	После	Улучшение
Запросы по году/месяцу	Полное сканирование	Индекс	10-100x
Запросы по batch_id	Медленно	Индекс	50-100x
Фильтрация по статусам	Медленно	Индекс	10-50x
NLP категоризация	50-150ms	5-15ms	10x (с кэшем)

🛠 Технологии

Backend

Django 5.2.3 - основа проекта, ORM, админ-панель
Celery + Redis - асинхронные задачи для обработки транзакций
SQLite - хранилище данных (рекомендуется PostgreSQL для продакшена)

NLP & AI

pymorphy2 - морфологический анализ русского языка
RuWordNet - русская версия WordNet для синонимов
OpenAI Embeddings API - векторное представление текста
LRU кэширование - оптимизация производительности

Интеграции

Telegram Bot API (aiogram) - уведомления и взаимодействие
Google Sheets API (gspread) - экспорт данных
Bitrix24 REST API - анализ сделок и лидов
Tochka Bank API - автоматическое получение выписок

Deployment

Ubuntu 22.04 - production сервер
HTTPS (Let's Encrypt) - SSL-сертификат
tmux - фоновый запуск сервисов
python-dotenv - управление конфигурацией

📁 Структура проекта

CoinCounter/
├── 📄 README.md                          # Этот файл
├── 📄 NLP_ALGORITHM.md                   # Описание NLP-алгоритма
├── 📄 env.example                        # Шаблон для .env (НАЧНИ ОТСЮДА!)
├── 📄 requirements.txt                   # Зависимости проекта
├── 📄 manage.py                          # Django management
│
├── 📁 coin_counter/                      # Основные настройки Django
│   ├── settings.py                       # Конфигурация + валидация
│   ├── celery.py                         # Настройки Celery
│   ├── urls.py                           # URL-маршруты
│   └── wsgi.py
│
├── 📁 coin_desk/                         # Главное приложение
│   ├── models.py                         # Модели БД (с индексами!)
│   ├── views.py                          # Webhook'и Битрикс24
│   ├── tasks.py                          # Celery-задачи
│   ├── admin.py                          # Админ-панель
│   │
│   ├── 📁 management/commands/           # Django команды
│   │   ├── fetch_bank_data.py           # Получение выписок
│   │   ├── export_transactions_to_sheets.py  # Экспорт в Sheets
│   │   ├── notify_about_new_transactions.py  # Уведомления
│   │   └── run_telegram_bot.py          # Запуск бота
│   │
│   ├── 📁 scripts/                       # Бизнес-логика
│   │   ├── bank_fetch.py                # Работа с банковским API
│   │   └── keywords.py                  # Ключевые слова для категоризации
│   │
│   ├── 📁 telegram_bot/                  # Telegram интеграция
│   │   ├── bot.py                       # Инициализация бота
│   │   ├── handlers.py                  # Обработчики команд
│   │   └── utils.py                     # Утилиты для уведомлений
│   │
│   ├── 📁 utils/                         # NLP утилиты
│   │   ├── nlp_processor.py             # Основной NLP-процессор
│   │   ├── embedding.py                 # AI embeddings
│   │   └── embedding_cache.py           # Кэш embeddings
│   │
│   └── 📁 migrations/                    # Миграции БД
│
├── 📁 dashboard/                         # Dashboard приложение
│   ├── dashboard_transactions.py        # Логика формирования данных
│   ├── views.py                         # Views для дашборда
│   └── 📁 templates/dashboard/          # HTML шаблоны
│
├── 📁 config/                            # Конфигурация
│   └── *.json                           # Google Sheets credentials
│
├── 📁 examples/                          # Скриншоты интерфейсов
│
└── 📁 staticfiles/                       # Статика Django (создаётся автоматически)

🚀 Установка и запуск

Требования

Python 3.11+
Redis (для Celery)
SQLite (в разработке) или PostgreSQL (продакшен)

Установка (5 минут)

1. Клонируйте репозиторий

git clone https://github.com/OlgaKalinina101/CoinCounter
cd CoinCounter

2. Создайте виртуальное окружение

python3.11 -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

3. Установите зависимости

pip install -r requirements.txt

4. Установите Redis

# Ubuntu/Debian
sudo apt install redis-server

# macOS
brew install redis

# Windows
# Используйте WSL или Docker

5. Настройте .env файл

ВАЖНО: Используйте env.example как шаблон!

cp env.example .env

Минимальная конфигурация для разработки:

# Django (обязательно!)
SECRET_KEY=your-secret-key-here-generate-with-python-manage-py-shell
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1
CURRENT_YEAR=2026

# Timezone
TIMEZONE=Europe/Moscow

# Database
SQLITE_PATH=db.sqlite3

# Static files
STATIC_URL=static/

📖 Как получить остальные ключи, читайте в разделе Получение API-ключей

6. Примените миграции

python manage.py migrate

7. Соберите статику

python manage.py collectstatic --noinput

8. Создайте суперпользователя

python manage.py createsuperuser

9. Запустите проект

Вариант 1: Только Django (для начала)

python manage.py runserver

Вариант 2: С Celery (полный функционал)

# Терминал 1: Django
python manage.py runserver

# Терминал 2: Redis
redis-server

# Терминал 3: Celery Worker
celery -A coin_counter worker -l info

# Терминал 4: Celery Beat (опционально, для расписания)
celery -A coin_counter beat -l info

Вариант 3: С APScheduler (альтернатива Celery Beat)

Если вы не хотите использовать Celery Beat для расписания задач, можно использовать automation_scheduler.py с APScheduler:

# Терминал 1: Django
python manage.py runserver

# Терминал 2: Automation Scheduler
python automation_scheduler.py

Что делает automation_scheduler.py:

📅 Автоматическая загрузка банковских транзакций (два раза в день, или как настроите)
📊 Экспорт новых транзакций в Google Sheets (два раза в день, или как настроите)
📱 Отправка уведомлений в Telegram (два раза в день, или как настроите)

💡 Преимущества APScheduler:

Не требует Redis

Проще в настройке

Работает в одном процессе

Идеален для небольших проектов

⚠️ Важно: Используйте либо Celery Beat, либо APScheduler, но не оба одновременно!

10. Откройте в браузере

Админка: http://localhost:8000/admin/
Dashboard: http://localhost:8000/dashboard/

✅ Готово!

⚙️ Настройка категоризации

Добавление новых категорий расходов

Все категории управляются через Django Admin:

Откройте http://localhost:8000/admin/
Перейдите в Expense Categories (Категории расходов)
Нажмите Add Expense Category
Заполните:
- Name: Название категории (например, "Расходы на маркетинг")
- PL Entry: Статья отчета о прибылях и убытках

Привязка контрагентов к категориям

Вы можете настроить автоматическую категоризацию по ИНН контрагента:

Откройте http://localhost:8000/admin/
Перейдите в Contractor Expense Mappings (Привязка контрагентов)
Нажмите Add Contractor Expense Mapping
Заполните:
- Contractor: Выберите контрагента из списка
- Expense Category: Выберите категорию
- Description: Описание (опционально)

Пример: Все транзакции от ООО "Яндекс" (ИНН: 7736207543) автоматически попадут в категорию "Расходы на рекламу".

Настройка ключевых слов для NLP

Ключевые слова для автоматической категоризации хранятся в файле:

coin_desk/scripts/keywords.py

Структура файла:

CATEGORY_KEYWORDS = {
    "Название категории": [
        "ключевое слово 1",
        "ключевое словосочетание 2",
        "фраза для поиска 3"
    ],
    "Аренда офиса": [
        "за аренду",
        "по договору аренды",
        "арендная плата"
    ],
    "Расходы на рекламу": [
        "рекламные услуги",
        "продвижение в яндекс",
        "контекстная реклама"
    ]
}

Как добавить новые ключевые слова:

Откройте файл coin_desk/scripts/keywords.py
Найдите нужную категорию или создайте новую
Добавьте ключевые слова/фразы в список
Сохраните файл
Перезапустите Django сервер

Советы:

💡 Используйте фразы из реальных назначений платежей
💡 Добавляйте частичные совпадения (например, "за аренду" вместо "оплата за аренду помещения")
💡 NLP алгоритм автоматически учитывает словоформы ("аренда", "аренды", "аренде")
💡 Регистр не важен (система приводит всё к нижнему регистру)

Пример реального назначения платежа:

"Оплата за аренду офисного помещения по договору №123 от 01.01.2025"

Ключевое слово:

"за аренду"  # ✅ Найдёт совпадение

Приоритет категоризации

Система использует три метода категоризации в следующем порядке:

По ИНН контрагента (самый приоритетный)
- Если у контрагента есть маппинг в Contractor Expense Mappings
По ключевым словам + NLP
- Поиск по keywords.py с учетом:
  - Точного совпадения слов
  - Лемматизации (словоформ)
  - Синонимов из RuWordNet
  - Semantic similarity через embeddings
По умолчанию
- Если ничего не найдено, категория остается пустой (None)

Проверка категоризации:

После добавления ключевых слов протестируйте на реальных транзакциях:

# Загрузите новые транзакции
python manage.py fetch_bank_data

# Проверьте логи
tail -f debug.log | grep "CATEGORY-NLP"

В логах вы увидите:

[CATEGORY-NLP][batch-uuid] Категория определена: Аренда офиса (score=0.950) [boosts: exact, lemma]

🔑 Получение API-ключей и токенов

1. Telegram Bot Token

Зачем: Для отправки уведомлений о новых транзакциях

Как получить:

Откройте Telegram, найдите @BotFather
Отправьте команду /newbot
Следуйте инструкциям (придумайте имя и username бота)
Скопируйте токен вида 123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Добавьте в .env:

TELEGRAM_BOT_TOKEN=your-telegram-bot-token

Как узнать свой Chat ID:

Откройте https://t.me/userinfobot
Отправьте боту /start
Скопируйте ваш ID (число)

Добавьте в .env:

TELEGRAM_CHAT_IDS=123456789,987654321  # Можно несколько через запятую

2. Google Sheets API

Зачем: Для экспорта транзакций в Google Таблицы

Как получить:

Шаг 1: Создайте проект в Google Cloud

Откройте https://console.cloud.google.com/
Создайте новый проект (или выберите существующий)
Перейдите в APIs & Services → Enable APIs and Services
Найдите и включите Google Sheets API
Найдите и включите Google Drive API

Шаг 2: Создайте Service Account

Перейдите в APIs & Services → Credentials
Нажмите Create Credentials → Service Account
Заполните форму (имя, описание)
Нажмите Create and Continue
Пропустите опциональные шаги

Шаг 3: Создайте ключ

Найдите созданный Service Account в списке
Нажмите на него → вкладка Keys
Add Key → Create New Key → JSON
Скачайте файл (например, credentials.json)

Шаг 4: Настройте проект

Создайте папку config в корне проекта:
```
mkdir config
```
Переместите скачанный JSON в config/credentials.json
Откройте JSON, найдите поле client_email (например, your-service@project.iam.gserviceaccount.com)
Создайте новую Google Таблицу
Нажмите Share → добавьте этот email с правами Editor

Скопируйте ID таблицы из URL:

https://docs.google.com/spreadsheets/d/[ВОТ_ЭТОТ_ID]/edit

Добавьте в .env:

GOOGLE_SHEETS_CREDENTIALS=config/credentials.json
GOOGLE_SHEET_ID=your-google-sheet-id

3. Tochka Bank API

Зачем: Для автоматического получения банковских выписок

Важно: Проект работает с банком Точка. Если у вас другой банк, адаптируйте coin_desk/scripts/bank_fetch.py.

Как получить:

Откройте личный кабинет банка Точка
Перейдите в раздел API или Интеграции
Создайте API-ключ или JWT-токен
Скопируйте Client ID и токен
Найдите номера счетов и БИК банка

Добавьте в .env:

CLIENT_ID=your-bank-client-id
JWT_TOKEN=your-bank-jwt-token
BANK_ACCOUNTS=account1,account2,account3  # Через запятую
BANK_BIC=bank-bic-code

4. Bitrix24 Webhooks (опционально)

Зачем: Для интеграции с CRM и анализа сделок/лидов

Как получить:

Откройте ваш портал Bitrix24
Перейдите в Настройки → Настройки портала → Вебхуки
Нажмите Создать вебхук
Выберите нужные права (например, crm для сделок и лидов)
Скопируйте URL вида https://your-domain.bitrix24.ru/rest/1/your-token/
Токен - это часть после /rest/1/

Добавьте в .env:

WEBHOOK_TOKEN=your-deals-webhook-token
WEBHOOK_TOKEN_2=your-leads-webhook-token

5. OpenAI API

Зачем: Для AI-категоризации транзакций через embeddings

Как получить:

Откройте https://platform.openai.com/ (требует VPN).
Зарегистрируйтесь или войдите
Перейдите в API Keys
Нажмите Create new secret key
Скопируйте ключ (показывается один раз!)

Добавьте в .env:

OPENAI_API_KEY=sk-your-openai-api-key
LLM_API_KEY=sk-your-openai-api-key  # Можно использовать тот же ключ

⚠️ Внимание: Использование OpenAI API платное (~~три копейки, за три года не сьел даже доллар). Проверьте тарифы на https://openai.com/pricing

В проекте сознательно отсутствует эмбеддинг модель с hugging face, так как целевая аудитория не имеет возможности купить себе хороший ноутбук.

💾 Доступ к данным

SQLite База данных

Путь: db.sqlite3 (в корне проекта)

Инструменты для просмотра:

DB Browser for SQLite - графический интерфейс
SQLite CLI - командная строка
DBeaver - универсальный клиент БД

Пример запроса:

sqlite3 db.sqlite3
SELECT * FROM coin_desk_transaction ORDER BY date DESC LIMIT 10;

Django Admin

URL: http://localhost:8000/admin/

Возможности:

✏️ CRUD операции для всех моделей
🔍 Поиск и фильтрация
📊 Экспорт в CSV
🎨 Удобный веб-интерфейс

🌐 Production деплой

Текущее окружение

Сервер: Ubuntu 22.04
HTTPS: SSL-сертификат через Let's Encrypt
Процесс-менеджер: tmux (3+ года без проблем)
База: SQLite (рекомендуется PostgreSQL для масштабирования)

tmux сессии

# Сессия 1: Django
tmux new -s django
python manage.py runserver 0.0.0.0:8000

# Сессия 2: Celery Worker
tmux new -s celery
celery -A coin_counter worker -l info

# Сессия 3: Telegram Bot
tmux new -s telegram
python manage.py run_telegram_bot

🧭 Roadmap

В перспективе (архитектурно заложено, реализуется поэтапно)

Улучшение Dashboard
- Drill-down: провал в детали любой ячейки таблицы
- Экспорт графиков в PDF
- Кастомные фильтры и отчёты
Расширение функционала
- Ввод наличных операций (эквайринг)
- Подотчётные расходы сотрудников
- Планирование бюджета
ML улучшения
- Fine-tuning эмбеддинг-модели на доменных данных
- Обучение на ручных корректировках
- Предсказание категорий с учётом истории
Интеграции
- Поддержка других банков
- Интеграция с 1С
- REST API для внешних систем

📝 Статистика и качество

Точность категоризации

99.6% точность (3021/3033 транзакций)
Проверено на вручную размеченных данных за 3 года
Три метода: ИНН маппинг, AI embeddings, правила по умолчанию

Качество кода

✅ Модульная архитектура
✅ 10 индексов БД для производительности
✅ DRY principle (без дублирования)
✅ Полное логирование (debug.log)
✅ Валидация всех входных данных
✅ PEP8 compliance

📬 Контакты

Разработчик: Ольга Калинина

💼 GitHub: @OlgaKalinina101
📧 Email: kalinina.olgarbc@gmail.com
💬 Issues: https://github.com/OlgaKalinina101/CoinCounter/issues

📄 Лицензия

MIT License - используйте свободно в коммерческих и личных проектах

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
coin_counter		coin_counter
coin_desk		coin_desk
config		config
dashboard		dashboard
examples		examples
templates		templates
.gitignore		.gitignore
LICENSE.txt		LICENSE.txt
NLP_ALGORITHM.md		NLP_ALGORITHM.md
README.md		README.md
automation_scheduler.py		automation_scheduler.py
count_by_lines.py		count_by_lines.py
env.example		env.example
help.md		help.md
manage.py		manage.py
print_tree.py		print_tree.py
requirements.txt		requirements.txt
run.sh		run.sh
run_all.py		run_all.py

License

OlgaKalinina101/CoinCounter

Folders and files

Latest commit

History

Repository files navigation

CoinCounter 📈

Финансовый ассистент для малого бизнеса и ИП с NLP, автоматизирующий учёт банковских транзакций

💡 История проекта

🎯 Ключевые возможности

📚 Оглавление

🤖 NLP-алгоритм категоризации

Технологии

Формула итогового скора

Точность

📸 Примеры интерфейсов

📊 Dashboard: Аналитика в реальном времени

📱 Telegram Bot: Уведомления и быстрый доступ

🎛️ В каком виде выгружаются данные в google sheets

📑 Google Sheets: Экспорт и совместная работа

Важно: это примеры и в проекте их нет. Но вы всегда можете собрать такие сводные таблички и диаграммы самостоятельно.

⚡ Производительность

🛠 Технологии

Backend

NLP & AI

Интеграции

Deployment

📁 Структура проекта

🚀 Установка и запуск

Требования

Установка (5 минут)

1. Клонируйте репозиторий

2. Создайте виртуальное окружение

3. Установите зависимости

4. Установите Redis

5. Настройте .env файл

6. Примените миграции

7. Соберите статику

8. Создайте суперпользователя

9. Запустите проект

10. Откройте в браузере

⚙️ Настройка категоризации

Добавление новых категорий расходов

Привязка контрагентов к категориям

Настройка ключевых слов для NLP

Приоритет категоризации

🔑 Получение API-ключей и токенов

1. Telegram Bot Token

2. Google Sheets API

Шаг 1: Создайте проект в Google Cloud

Шаг 2: Создайте Service Account

Шаг 3: Создайте ключ

Шаг 4: Настройте проект

3. Tochka Bank API

4. Bitrix24 Webhooks (опционально)

5. OpenAI API

В проекте сознательно отсутствует эмбеддинг модель с hugging face, так как целевая аудитория не имеет возможности купить себе хороший ноутбук.

💾 Доступ к данным

SQLite База данных

Django Admin

🌐 Production деплой

Текущее окружение

tmux сессии

Рекомендации для production

🧭 Roadmap

В перспективе (архитектурно заложено, реализуется поэтапно)

📝 Статистика и качество

Точность категоризации

Качество кода

📬 Контакты

📄 Лицензия

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages