income_calculator/README.md

Личные финансы — учёт баланса и выписок

Учёт операций по нескольким банкам: импорт PDF-выписок, дедупликация, расчёт баланса, дохода, дебета/кредита, копилки. Дашборд с фильтрами и графиками на localhost.

Поддерживаемые банки

• Т — Т-банк (файлы Т-MM-YY.pdf)
• С — Сбербанк (С-MM-YY.pdf)
• Я — Яндекс Банк (Я-MM-YY.pdf)

Выписки кладутся в папку Выписки банков/.

Запуск

Вариант 1: Docker (рекомендуется)

Нужны установленные Docker и Make.

make run

Откройте в браузере http://127.0.0.1:8000. База данных хранится в Docker-volume income_calculator_data, папка Выписки банков/ с хоста монтируется в контейнер — импорт из папки работает с вашими PDF.

Полезные команды:

• make stop — остановить контейнер
• make logs — логи
• make shell — shell внутри контейнера
• make help — список целей

Вариант 2: Локально (venv)

1. Создать venv и установить зависимости:

   python3 -m venv venv
   ./venv/bin/pip install -r backend/requirements.txt
   

2. Запустить сервер:

   cd /path/to/income_calculator
   PYTHONPATH=. ./venv/bin/uvicorn backend.main:app --host 127.0.0.1 --port 8000
   

3. Открыть в браузере: http://127.0.0.1:8000

Настройки приложения

В разделе Настройки:

• Выбрать зарплатный банк (кнопка «Сделать зарплатным»), при необходимости — зарплатную карту (доход считается по приходам на этот банк или только на выбранную карту).
• Включить при необходимости «Доход только по зарплатной карте».
• Нажать Импорт из папки, чтобы загрузить все выписки из Выписки банков/, или загрузить один PDF вручную.

Дашборд

• Фильтры: период (дата с/по), банки (галочки), «Не учитывать переводы» — при включении все операции с текстом «Перевод» в описании исключаются из расчётов (баланс, доход, дебет/кредит, копилка и графики).
• Сводка: суммарный баланс, доход (по зарплатному банку/карте), дебет, кредит, копилка (накопления).
• Графики: доход и расход по месяцам, динамика остатка, динамика копилки.
• Операции: список с пагинацией; у каждой операции можно снять галочку «В расчёте», тогда она не участвует в балансе и сводке.

Копилка: операции с описанием «Перевод между счетами одного клиента» (Яндекс Банк): отрицательная сумма — взнос в копилку, положительная — вывод; в сводке и на графике отображается итог по копилке.

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

• backend/ — FastAPI, SQLite, парсеры выписок Т/С/Я, API и раздача статики.
• frontend/dist/ — фронтенд (один HTML с Chart.js), сборка не требуется.
• Выписки банков/ — PDF-выписки (Т-MM-YY.pdf, С-MM-YY.pdf, Я-MM-YY.pdf).

База данных: SQLite — backend/finance.db.

API (кратко)

• Банки: GET /api/banks, PUT /api/banks/salary/{id}.
• Счета: GET /api/accounts, POST /api/accounts/{account_id}/opening-balance.
• Импорт: POST /api/import/upload, POST /api/import/from-folder.
• Баланс и операции: GET /api/balance/summary, GET /api/balance/by-account, GET /api/transactions (параметры: period_start, period_end, bank_ids).
• Графики: GET /api/charts/income-expense, GET /api/charts/balance-dynamics, GET /api/charts/savings-dynamics (те же параметры фильтрации).
• Настройки: GET/PUT /api/settings/income (зарплатная карта, «только по карте»), GET/PUT /api/settings/exclude-transfers (не учитывать переводы).