FinTracker

Современное веб-приложение для управления личными финансами

Интуитивный интерфейс · Мощная аналитика · Полный контроль

---

Содержание

• Быстрый запуск для новых устройств
• Быстрый запуск (обычный)
• Системные требования
• Основные возможности
• Backup и перенос данных
• Конфигурация проекта
• Решение проблем

---

Быстрый запуск для новых устройств

Первый раз запускаете проект? Начните здесь!

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

git clone https://github.com/S-NOWNUM-B/-Fin_Sector-.git FinTracker
cd FinTracker

2. Автоматическая настройка (РЕКОМЕНДУЕТСЯ)

python3 setup.py

Скрипт setup.py автоматически:

• Сгенерирует безопасные пароли для PostgreSQL
• Создаст случайный SECRET_KEY для JWT
• Настроит все .env файлы (backend, frontend, docker)
• Обновит .gitignore для защиты паролей
• Проверит наличие Python, Node.js, Docker

Что он спросит:

• Использовать Docker для PostgreSQL? (yes/no)
• Allowed CORS origins (можно оставить по умолчанию)
• Порты для сервисов (можно оставить по умолчанию)

3. Запуск проекта

# Автоматический запуск (launcher выберет Docker или прямой режим)
python3 launcher.py

# Или с Docker
docker-compose up -d

# Или без Docker (требуется PostgreSQL локально)
cd backend && uvicorn app.main:app --host 0.0.0.0 --port 8010
cd frontend && npm install && npm run dev

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

http://localhost:3010

Готово! Проект полностью настроен и готов к работе.

---

Быстрый запуск (обычный)

Два способа запуска приложения

Способ 1: Через ярлык (Рекомендуется)

Установка один раз:

python3 install.py  # macOS/Linux
python install.py   # Windows

Затем просто дважды кликните по ярлыку FinTracker на рабочем столе!

Способ 2: Напрямую

python3 launcher.py  # macOS/Linux
python launcher.py   # Windows

Launcher предложит выбрать режим запуска:

• Прямой запуск - быстрее, для разработки (без Docker)
• Docker - изолированное окружение (требуется Docker)

---

Системные требования

Компонент	Минимум	Рекомендуется	Проверка
Python	3.8+	3.10+	python --version
Node.js	16+	18+	node --version
npm	8+	9+	npm --version
Порты	3010, 8010	Свободны	Автоматическая
RAM	512 MB	1 GB+	—
Диск	100 MB	200 MB+	Зависимости + БД

---

Основные возможности

Управление счетами Множественные типы счетов Сберегательные, общие, наличные, кредитные Отслеживание в реальном времени Автоматический пересчёт балансов Мультивалютность KZT · USD · EUR · RUB Гибкое управление Активация/деактивация без потери данных Конфиденциальность Скрытие балансов одним кликом Экспорт данных CSV с индикатором прогресса	Транзакции Быстрое добавление Интуитивные формы доходов/расходов Умные категории Иерархия + цветовое кодирование Расширенные фильтры Дата · Сумма · Категория · Счёт · Тип Оптимизированный поиск Debounce 300мс для производительности Массовые операции Экспорт в CSV/Excel Визуальные индикаторы Toast-уведомления + загрузка
Управление долгами Двусторонний учёт Кому должны · Кто должен вам Прогресс погашения Визуальные индикаторы + проценты Архивирование Активные/погашенные долги История платежей Детальная информация по каждому долгу Частичное погашение Автоматический расчёт остатка Напоминания Настраиваемые даты уведомлений	Аналитика и отчёты Интерактивные графики Доходы/расходы с масштабированием Круговые диаграммы Распределение по категориям Тренды по месяцам Сравнение периодов Сводная статистика Экспорт всех показателей Прогнозирование На основе исторических данных Сравнительная аналитика Между различными счетами

Безопасность и приватность

Функция	Описание
Контроль доступа	Многоуровневая защита данных на уровне API
Валидация	Проверка на уровне форм, типов и бэкенда
Логирование	Аудит всех действий для безопасности
Защита от дублей	Блокировка кнопок во время операций
Debounce	Защита от избыточных запросов к API

---

Backup и перенос данных

КРИТИЧЕСКИ ВАЖНО: Ваши финансовые данные хранятся локально в PostgreSQL. При переносе на другое устройство или переустановке системы данные будут потеряны без резервной копии!

Операция	Команда	Результат
Создать backup	./scripts/auto_backup.sh	Сохранение в ~/FinTracker_Backups/
Восстановить	./scripts/restore_backup.sh	Восстановление последнего backup
Указать файл	./scripts/restore_backup.sh путь/к/файлу	Восстановление конкретного backup

Пошаговый перенос на другое устройство

Шаг 1 — На исходном устройстве:

./scripts/auto_backup.sh
cp ~/FinTracker_Backups/latest_backup.sql.gz ~/Desktop/

Шаг 2 — Перенос файла:

• USB флешка
• Google Drive / iCloud / Dropbox
• Email (если файл <25 MB)
• AirDrop (macOS)

Шаг 3 — На новом устройстве:

git clone https://github.com/S-NOWNUM-B/-Fin_Sector-.git FinTracker
cd FinTracker
python3 setup.py
docker-compose up -d postgres
./scripts/restore_backup.sh ~/Desktop/latest_backup.sql.gz
python3 launcher.py

Автоматический ежедневный backup

macOS/Linux:

crontab -e
# Добавить строку (backup каждый день в 3:00 ночи):
0 3 * * * /Users/stanislavmamaev/Documents/Работа/Devolopment/Pycharm/FinTracker/scripts/auto_backup.sh

Windows:

Task Scheduler → Создать задачу:
- Имя: "FinTracker Daily Backup"
- Триггер: Ежедневно в 3:00
- Действие: Запуск программы
- Программа: C:\Windows\System32\bash.exe
- Аргументы: /path/to/FinTracker/scripts/auto_backup.sh

---

Конфигурация проекта

Структура .env файлов

Файл	Назначение	Обязательность
backend/.env	PostgreSQL, SECRET_KEY, CORS	Да
frontend/.env.local	API URL	Рекомендуется
.env.docker	Порты и пароли для Docker	Да (Docker)

Автоматическая генерация (рекомендуется)

python3 setup.py

Скрипт автоматически:

• Генерирует безопасные случайные пароли (20 символов)
• Создает уникальный SECRET_KEY для JWT (32 байта, URL-safe)
• Настраивает CORS origins для frontend
• Конфигурирует порты для Docker
• Проверяет наличие Python, Node.js, Docker
• Обновляет .gitignore для защиты конфиденциальных данных

Ручная настройка .env

Развернуть для ручной настройки

backend/.env

# PostgreSQL Connection (ОБЯЗАТЕЛЬНО!)
DATABASE_URL=postgresql://user:password@localhost:5432/fintracker_db

# Security & Authentication (ОБЯЗАТЕЛЬНО!)
SECRET_KEY=ваш_случайный_ключ_32_символа
ACCESS_TOKEN_EXPIRE_MINUTES=30

# CORS Settings (опционально)
ALLOWED_ORIGINS=http://localhost:3010,http://127.0.0.1:3010

frontend/.env.local

# Backend API URL
NEXT_PUBLIC_API_URL=http://localhost:8010

.env.docker (для Docker)

# Database Credentials
POSTGRES_USER=fintracker_user
POSTGRES_PASSWORD=ваш_безопасный_пароль
POSTGRES_DB=fintracker_db

# Security
SECRET_KEY=ваш_секретный_ключ_32_символа

# Ports Configuration
POSTGRES_PORT=5432
BACKEND_PORT=8010
FRONTEND_PORT=3010

Генерация безопасных ключей

# Генерация SECRET_KEY (32 байта, URL-safe)
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

# Генерация пароля (20 символов, буквы + цифры)
python3 -c "import secrets, string; print(''.join(secrets.choice(string.ascii_letters + string.digits) for _ in range(20)))"

# Генерация UUID для дополнительной безопасности
python3 -c "import uuid; print(str(uuid.uuid4()))"

---

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

Задача	Команда
Запустить проект	python3 launcher.py
Создать backup	./scripts/auto_backup.sh
Восстановить backup	./scripts/restore_backup.sh
Проверка портов	lsof -i :8010 (macOS/Linux)
Логи Backend	docker logs fintracker-backend
Логи Frontend	docker logs fintracker-frontend
Логи PostgreSQL	docker logs fintracker-postgres
Перезапуск БД	docker-compose restart postgres
Остановить всё	docker-compose down
Удалить всё + volumes	docker-compose down -v
Обновить зависимости	pip install -r requirements.txt
Проверка Python	python3 --version
Проверка Node.js	node --version
Проверка Docker	docker --version

---

Решение проблем

Обновил код из репозитория, но изменения не применяются

Проблема: После git pull новый код не работает, старые ошибки остаются.

Причина: Backend/Frontend работают в памяти со старой конфигурацией. Перезагрузка браузера не помогает!

Решение:

# 1. Остановите ВСЕ процессы FinTracker
pkill -f "uvicorn"      # Останавливает Backend
pkill -f "next"         # Останавливает Frontend
# или просто Ctrl+C в терминалах, где они запущены

# 2. Обновите код
git pull origin main

# 3. Перезапустите проект
python3 launcher.py

Если используете Docker:

# Пересоздать контейнеры с новым кодом
docker-compose down
docker-compose up -d --build

Проверка успешного обновления:

• Backend: curl http://localhost:8010/docs (должна открыться Swagger документация)
• Frontend: откройте http://localhost:3010 в новой вкладке (Cmd+T / Ctrl+T)
• Очистите кеш браузера: Cmd+Shift+R (Mac) или Ctrl+Shift+R (Windows/Linux)

Launcher не запускается / Frontend timeout

# Проверьте версии
python --version      # Требуется 3.8+
node --version        # Требуется 16+

# Запуск с диагностикой
python launcher.py --dev --no-browser

При таймауте Frontend (первый запуск может занять до 60 секунд):

# Терминал 1 - Backend
cd backend && python -m uvicorn app.main:app --host 0.0.0.0 --port 8010 --reload

# Терминал 2 - Frontend
cd frontend && pnpm run dev

Порты заняты (8010, 3010)

Проверка занятых портов:

# Linux/macOS
lsof -i :8010
lsof -i :3010

# Windows
netstat -an | findstr :8010
netstat -an | findstr :3010

Освобождение портов:

# Linux/macOS
sudo kill -9 $(lsof -ti:8010)
sudo kill -9 $(lsof -ti:3010)

# Windows
taskkill /F /PID <PID_NUMBER>

Проблемы с базой данных PostgreSQL

# Проверка работы PostgreSQL (через Docker)
docker ps | grep postgres

# Перезапуск БД
docker-compose restart postgres

# Пересоздание БД с нуля
docker-compose down -v
docker-compose up -d postgres

# Инициализация базы данных вручную
cd backend
python3 scripts/init_db.py

Типичные проблемы:

• connection refused → PostgreSQL не запущен
• database does not exist → Запустите python3 backend/scripts/init_db.py
• authentication failed → Проверьте credentials в .env
• could not translate host name → Запустите python3 scripts/fix_password.py

Проблемы с зависимостями

Backend — виртуальное окружение:

cd backend
python -m venv .venv

# Активация
source .venv/bin/activate    # Linux/macOS
.venv\Scripts\activate       # Windows

# Установка
pip install -r requirements.txt

Frontend:

cd frontend
pnpm install  # Рекомендуется
# или
npm install

Проблемы с сетью и CORS

# Проверка доступности сервисов
curl http://localhost:8010/docs     # Backend API Documentation
curl http://localhost:3010          # Frontend

# Проверка переменных окружения
env | grep ALLOWED_ORIGINS

Типичные проблемы:

• Frontend не может подключиться к Backend → проверьте NEXT_PUBLIC_API_URL
• CORS ошибки → добавьте URL frontend в ALLOWED_ORIGINS
• 502 Bad Gateway → Backend не запущен или порт неверный

Расширенная диагностика

# Полная диагностика системы
python launcher.py --dev --no-browser 2>&1 | tee debug.log

# Проверка логов Docker
docker-compose logs -f --tail=100

# Проверка конкретного сервиса
docker-compose logs backend -f
docker-compose logs frontend -f
docker-compose logs postgres -f

# Проверка процессов
ps aux | grep python
ps aux | grep node
ps aux | grep postgres

# Проверка использования портов
lsof -i :8010  # Backend
lsof -i :3010  # Frontend
lsof -i :5432  # PostgreSQL

---

Для новых пользователей

Этап	Описание
Чистая установка	Никаких демо-данных, только ваши данные
Создание базы данных	Автоматическая инициализация PostgreSQL
Настройка таблиц	Инициализация всех необходимых таблиц
Базовые категории	Создание категорий доходов и расходов
Система безопасности	Настройка защиты и контроля доступа
Готовность к работе	Можете сразу добавлять счета и транзакции

---

Вернуться наверх