PyMASL — Система автоматизации детских развлекательных центров

Производственная desktop-система для автоматизации продаж, учета посетителей и интеграции с торговым оборудованием в детских развлекательных центрах.

Внедрена в эксплуатацию: 01.06.2022 • Статус: ✅ Работает в production

📋 Содержание

• Бизнес-результаты
• Ключевые возможности
• Технологический стек
• Интерфейс и скриншоты
• Установка и запуск
• Сборка .EXE (Production)
• Архитектура
• Лицензия

📊 Бизнес-результаты

Система успешно прошла опытную эксплуатацию и полностью заменила предыдущие процессы. Динамика продаж демонстрирует надежность и масштабируемость решения:

Год	Оборот через систему
2022	1,7 млн. руб. (запуск)
2023	7,6 млн. руб.
2024	8,8 млн. руб.
2025	23,5 млн. руб.
2026	16,8 млн. руб. (01.01.2026 - 01.08.2026)

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

🎫 Учет и продажи

• Полная база клиентов с историей посещений
• Гибкая система формирования заказов
• Сложные правила скидок (многодетные, инвалиды, этапные 5%)
• Автоматическая проверка правил посещения центра
• Привязка посетителей к сопровождающим

💳 Интеграция с оборудованием

• Работа с онлайн-кассами АТОЛ FPrint-22ПТК (драйвер дККТ10)
• Поддержка эквайринговых терминалов PAX/Ingenico
• Проведение наличных и безналичных платежей
• Автоматическая генерация и печать билетов

📈 Аналитика и отчетность

• Статистика продаж и посещений в реальном времени
• Формирование PDF-отчетов (кассир, администратор)
• Гибкие фильтры и временные диапазоны

🛠 Технологический стек

Бэкенд и данные

• Язык: Python 3.9+
• База данных: PostgreSQL
• ORM: SQLAlchemy 2.0
• Миграции: Alembic

Интерфейс

• GUI: PySide6 (Qt 6.0+)
• Дизайн форм: Qt Designer
• Стилизация: Qt Style Sheets (QSS)

Деплой и инфраструктура

• Сборка: PyInstaller (build.bat)
• Целевая ОС: Windows 10/11
• Генерация PDF: ReportLab
• Просмотр PDF: SumatraPDF

Интеграции

• Фискальные регистраторы: АТОЛ FPrint-22ПТК
• Платежные терминалы: PAX/Ingenico
• Принтеры чеков и штрих-кодов

🖼 Интерфейс и скриншоты

Форма аутентификации

Главное окно приложения

Включает вкладки: Посетители, Продажи, Доп.услуги, Статистика, Касса.

Вкладка "Посетители"

Фильтрация по: ФИО, фамилия, телефон, статусы "инвалид"/"многодетный"

Вкладка "Продажи"

Особенности:

• Автоматический расчет стоимости по возрасту (до 5 лет — бесплатно, 5-14 — детский, 14+ — взрослый)
• Дифференциация цен будни/выходные
• Скидки: многодетным 50% в будни, бесплатно 2 часа в 1-е воскресенье месяца
• Инвалиды + сопровождающий — бесплатно всегда

Вкладка "Статистика"

Примеры отчетов

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

1. Клонирование репозитория

git clone https://github.com/MarcusStill/PyMASL.git
cd PyMASL

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

python -m venv .venv
# Для Windows (PowerShell):
.\.venv\Scripts\Activate.ps1
# Для Windows (cmd):
.\.venv\Scripts\activate.bat

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

pip install -r requirements.txt

4. Настройка базы данных

1. Установите PostgreSQL
2. Создайте базу данных и пользователя
3. Настройте подключение в config.ini
4. Выполните миграции:

alembic upgrade head

5. Запуск приложения

python main.py

📦 Сборка .EXE (Production)

Сборка исполняемого .exe файла для Windows выполняется в автоматическом режиме через файл build.bat, расположенный в корне проекта.

Порядок сборки:

1. Убедитесь, что зависимости установлены в виртуальное окружение .venv:

.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip install pyinstaller

2. Запустите файл build.bat (двойным кликом или через консоль):

.\build.bat

3. Готовый дистрибутив будет сформирован в директории dist/

Примечание: Скрипт build.bat автоматически использует относительные пути и вызывает интерпретатор из локального окружения .venv, обеспечивая одинаковый результат сборки на любой рабочей станции.

🏗 Архитектура

PyMASL/
├── 📂 db/                     # 🗄️ База данных (ORM SQLAlchemy)
│   └── 📂 models/             # Модели сущностей (Client, Sale, Ticket, User и др.)
├── 📂 design/                 # 🎨 Графический интерфейс (Qt)
│   ├── 📂 logic/              # Логика контроллеров и диалоговых окон UI
│   └── 📂 resources/          # Вьюхи и формы, созданные в Qt Designer (.ui)
├── 📂 modules/                # 🧠 Ядро приложения и бизнес-логика
│   ├── 📄 auth_logic.py       # Логика аутентификации и прав доступа
│   ├── 📄 sale_logic.py       # Расчет стоимости, правил скидок и продаж
│   ├── 📄 payment_equipment.py# Интеграция с эквайринговыми терминалами (PAX/Ingenico)
│   ├── 📄 libfptr10.py        # Взаимодействие с ККТ АТОЛ (драйвер дККТ10)
│   ├── 📄 otchet.py           # Генерация PDF-отчетов и кассовых документов
│   ├── 📄 config.py           # Загрузка и валидация конфигурации из config.ini
│   ├── 📄 system.py           # Системные проверки (БД, драйверы, окружение)
│   └── 📄 logger.py           # Модуль логирования (Loguru/logging)
├── 📂 files/                  # 📎 Статические ресурсы (шрифты TTF, иконка .ico, шаблоны JSON)
├── 📂 scripts/                # 📜 Системные скрипты печати (.cmd)
├── 📂 tests/                  # 🧪 Модульные тесты pytest (логика, БД, оборудование)
├── 📄 config.ini              # ⚙️ Основной конфигурационный файл
├── 📄 build.bat               # 🚀 Автоматическая сборка в .EXE через PyInstaller (.venv)
└── 📄 main.py                 # 🏁 Точка входа в приложение

📄 Лицензия

PyMASL использует смешанные лицензии в зависимости от компонента:

Компонент	Лицензия	Ссылка
PostgreSQL	PostgreSQL License	Подробнее
Alembic	MIT License	Лицензия
SQLAlchemy	MIT License	Лицензия
PySide6	LGPL v3	Лицензия
PyInstaller	GPL v2 / ALv2	Лицензия
ReportLab	BSD License	Лицензия
SumatraPDF	GPL v3	Лицензия

Основной код проекта: доступен по открытой лицензии.