POS System - Standalone

Автономна касова система з локальною базою даних SQLite.

Технології

• Backend: FastAPI + SQLAlchemy + SQLite
• Frontend: Flet
• Python: 3.11+
• Пакетний менеджер: uv (швидка альтернатива pip)

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

pos-standalone/
├── config/          # Конфігурація
├── backend/         # FastAPI API сервер
│   ├── api/v1/      # REST API endpoints
│   ├── database/    # Моделі БД
│   ├── schemas/     # Pydantic схеми
│   └── services/    # Бізнес-логіка
├── frontend/        # Flet UI додаток
│   ├── screens/     # Екрани інтерфейсу
│   └── api_client/  # HTTP клієнт
├── data/            # SQLite база даних
└── tests/           # Тести

Встановлення

Попередні вимоги

Встановіть uv - швидкий пакетний менеджер для Python:

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Linux/Mac:

curl -LsSf https://astral.sh/uv/install.sh | sh

Або через pip:

pip install uv

1. Синхронізація залежностей

uv автоматично створить віртуальне середовище та встановить всі залежності:

uv sync

2. Додавання тестових даних

uv run python add_test_products.py

3. Налаштуйте змінні середовища (опціонально)

Скопіюйте .env.example в .env та налаштуйте параметри:

Windows:

copy .env.example .env

Linux/Mac:

cp .env.example .env

Запуск

Швидкий старт

Варіант 1: Окремі процеси (рекомендовано для розробки)

У першому терміналі запустіть Backend API:

uv run python run_backend.py

У другому терміналі запустіть Frontend:

uv run python run_frontend.py

Варіант 2: Прямі команди

Backend API:

uv run uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000

Frontend:

uv run python run_frontend.py

Варіант 3: Через головний файл

uv run python main.py

Доступ до системи

• API: http://127.0.0.1:8000
• Swagger документація: http://127.0.0.1:8000/docs
• Frontend: Автоматично відкривається після запуску

Розробка

Встановлення dev-залежностей

uv sync --extra dev

Запуск тестів

uv run pytest

Форматування коду

uv run black .
uv run ruff check .

Додавання нових залежностей

uv add package-name              # Додати залежність
uv add --dev package-name        # Додати dev-залежність
uv remove package-name           # Видалити залежність

Створення міграцій БД

База даних SQLite створюється автоматично при першому запуску.

Корисні команди uv

uv sync                # Синхронізувати залежності
uv lock                # Оновити uv.lock
uv run <command>       # Виконати команду у віртуальному середовищі
uv pip list            # Показати встановлені пакети

Тестові дані

Після запуску add_test_products.py будуть доступні тестові товари:

Штрих-код	Товар	Ціна
4820000000017	Хліб білий	25.50 грн
4820000000024	Молоко 1л	35.00 грн
4820000000031	Яйця 10шт	48.00 грн
4820000000048	Масло вершкове 200г	85.00 грн
4820000000055	Цукор 1кг	32.00 грн
4820000000062	Сіль 1кг	12.00 грн
4820000000079	Олія соняшникова 1л	65.00 грн
4820000000086	Макарони 400г	28.00 грн
4820000000093	Рис 1кг	45.00 грн
4820000000109	Кава розчинна 100г	125.00 грн

API Endpoints

Товари

• GET /api/v1/products - список товарів (з пагінацією)
• GET /api/v1/products/{id} - отримати товар за ID
• GET /api/v1/products/barcode/{barcode} - пошук за штрих-кодом
• POST /api/v1/products - створити товар
• PUT /api/v1/products/{id} - оновити товар
• DELETE /api/v1/products/{id} - видалити товар (м'яке видалення)

Продажі

• POST /api/v1/sales - створити продаж
• GET /api/v1/sales - список продажів (з фільтрацією по датах)
• GET /api/v1/sales/{id} - отримати продаж за ID

Ліцензія

MIT