DARK.STORE OS — Telegram Mini App (SaaS E-Commerce Template)

Обзор проекта

DARK.STORE OS — это готовый автономный программный комплекс интернет-магазина, оптимизированный для работы в виде Telegram Mini App (TMA) и в веб-браузерах. Архитектура построена по принципу тиражируемого SaaS-решения, упакована в изолированный Docker-контейнер и предназначена для быстрого развертывания витрин электронной коммерции (электроника, кастомные девайсы, аксессуары, мерч и цифровые товары).

Архитектура и стек технологий

Backend:

* Python 3.11 на базе легковесного дистрибутива python:3.11-slim.

* FastAPI: асинхронный REST API для отдачи статики, маршрутизации заказов, аутентификации владельца и синхронизации каталога.

* Aiogram 3.x: интеграция с Telegram Bot API, управление постоянной клавиатурой (Reply / WebApp Dock), обработка команд /start и мгновенная отправка карточек заказов администратору в ЛС.

* Uvicorn: производительный ASGI-сервер.

Frontend:

* Vanilla JavaScript (ES6+), HTML5, CSS3: отсутствие сторонних тяжелых фреймворков обеспечивает мгновенный отклик даже на бюджетных смартфонах.

* Telegram WebApp API: интеграция нативных компонентов Telegram (виброотклик HapticFeedback, MainButton, автоматическая адаптация под тему мессенджера).

* Яндекс Карты (API 2.1): динамический блок локации/самовывоза с автонастройкой координат через админку.

База данных и персистентность:

* Серверное хранилище на базе структурированного файла data/store.json.

* Автономный fallback в браузере (localStorage + кэширование) для стабильной работы интерфейса при кратковременной потере сети.

DevOps и контейнеризация:

* Docker и Docker Compose: изоляция окружения, автоматическая сборка зависимостей из requirements.txt и монтирование тома volumes: - ./data:/app/data для гарантированной сохранности данных при обновлениях.

* Полное разделение конфигурации и кода через .env и .env.example.

Ключевой функционал системы

1. Клиентская витрина (index.html):

* Каталог и карусель: адаптивная сетка карточек товаров с бейджами (ХИТ, NEW, TOP, SALE) и интерактивная горизонтальная карусель бестселлеров.

* Поиск и фильтрация: фильтры по категориям и интеллектуальная строка поиска, которая при вводе символов автоматически прокручивает страницу к каталогу.

* Маркетинговые триггеры конверсии: верхняя панель дедлайна акций (FOMO-бар) с тикающим таймером обратного отсчета, индикаторы дефицита остатков (Осталось 2 шт.), режим покупки в один клик или через корзину с подсчетом позиций.

* Экран технических работ: переключаемый режим Maintenance Mode, блокирующий витрину заглушкой при обновлении ассортимента.

* Динамическая карта: отображение физической точки самовывоза или шоурума с интерактивной меткой.

2. Панель управления владельца (admin.html):

* Интерфейс в стиле мобильных настроек: блочная группировка параметров (iOS Settings style).

* Управление каталогом: добавление, редактирование, удаление товаров, назначение бейджей и статуса Хит.

* Массовая модификация цен: изменение стоимости всего ассортимента на заданный процент (+/- %) в один клик.

* Кастомизация брендинга: смена названия магазина, радиуса скругления блоков, валюты и автоизвлечение акцентного цвета из загружаемого логотипа через HTML5 Canvas.

* Конструктор кастомных блоков: возможность создавать дополнительные промо-баннеры и секции без вмешательства в исходный код.

* Безопасность: авторизация по паролю или связке с Telegram ID владельца, а также механизм аварийного сброса через секретное кодовое слово.

* Бэкап: выгрузка и загрузка всего состояния магазина в JSON-файл прямо из интерфейса.

3. Модуль заказов и бот (app.py):

* Обработка заявок через внутренний эндпоинт /api/order.

* Формирование структурированного отчета с составом корзины, суммой, типом покупки и прямым контактом покупателя (@username или Telegram ID).

* Мгновенный проброс уведомления в диалог администратора без спама в переписке с клиентом.

Структура дистрибутива (готовый архив к продаже)

darkstore_os/

├── data/ (Том постоянного хранения базы магазина store.json)

├── .env.example (Шаблон конфигурации для быстрого запуска)

├── .dockerignore (Правила исключения временных файлов и кэша)

├── Dockerfile (Сборка изолированного Python-образа)

├── docker-compose.yml (Манифест оркестрации контейнера)

├── requirements.txt (Список зависимостей: FastAPI, aiogram, uvicorn и др.)

├── index.html (Разметка витрины магазина)

├── admin.html (Разметка панели управления)

├── style.css (Оформление и адаптивная темная тема)

├── app.js (Клиентская логика, реактивность и синхронизация)

├── app.py (Серверная часть, REST API и бот Telegram)

└── README.md (Пошаговая инструкция по установке в 1 команду)