docs: add README with project overview, setup and configuration

2026-07-06 23:08:44 +04:00
parent 7d0cb2b443
commit 3c1614cf23
1 changed files with 124 additions and 0 deletions
@@ -0,0 +1,124 @@
+# 💆 Demo SPA Bot
+
+Telegram-бот для SPA-салона: запись на услуги, выбор мастера, управление бронированиями и админ-панель.
+
+Построен на **aiogram** с JSON-хранилищем — лёгкий, без БД, готов к запуску.
+
+---
+
+## 🚀 Возможности
+
+- **📋 Услуги** — массаж, SPA, косметология (настраивается в `config.py`)
+- **👩‍🔬 Мастера** — выбор специалиста с эмодзи-аватарками
+- **📅 Запись** — календарь, слоты по 1 часу, мультиуслуги
+- **👤 Профиль** — просмотр имени / ID
+- **📄 Мои записи** — просмотр, отмена, редактирование броней
+- **🔐 Админ-панель** — просмотр и отмена любых записей (пароль `admin123`)
+- **📞 Контакты** — адрес и телефон салона
+
+---
+
+## 🧱 Структура
+
+```
+demo_spa_bot/
+├── app/
+│   ├── main.py              # Точка входа
+│   ├── config.py            # Услуги, мастера, слоты
+│   ├── logger.py            # Логирование
+│   ├── db/
+│   │   ├── __init__.py
+│   │   └── memory.py        # JSON-хранилище (users, bookings)
+│   ├── handlers/
+│   │   ├── admin.py         # Админ-панель
+│   │   ├── about.py         # "О нас"
+│   │   ├── booking.py       # Процесс записи (FSM)
+│   │   ├── contacts.py      # Контакты
+│   │   ├── mybookings.py    # Мои записи
+│   │   ├── profile.py       # Профиль
+│   │   ├── services.py      # Список услуг
+│   │   └── start.py         # Команда /start
+│   ├── keyboards/           # Reply-клавиатуры
+│   ├── services/
+│   │   └── booking_service.py  # Бизнес-логика бронирования
+│   └── states/
+│       └── booking.py       # Состояния FSM
+└── data/                    # JSON-файлы (users.json, bookings.json)
+```
+
+---
+
+## 🛠 Установка и запуск
+
+```bash
+# 1. Клонировать
+git clone https://git.labnethub.ru/grejoi4621/demo_spa_bot.git
+cd demo_spa_bot
+
+# 2. Виртуальное окружение
+python -m venv .venv
+source .venv/bin/activate   # Linux/macOS
+# .venv\Scripts\activate    # Windows
+
+# 3. Зависимости
+pip install -r requirements.txt
+
+# 4. Переменные окружения
+cp .env.example .env        # или создать вручную
+# BOT_TOKEN=ваш_токен_бота
+
+# 5. Запуск
+python -m app.main
+```
+
+---
+
+## ⚙️ Конфигурация
+
+В `app/config.py`:
+
+| Переменная         | Описание                    | Значение по умолчанию |
+|--------------------|-----------------------------|-----------------------|
+| `BOT_TOKEN`        | Токен Telegram-бота         | из `.env`             |
+| `ADMIN_PASSWORD`   | Пароль для /admin           | `admin123`            |
+| `SERVICES`         | Словарь услуг               | массаж, SPA, косметология |
+| `MASTERS`          | Словарь мастеров            | Анна, Мария, Алексей  |
+| `TIME_SLOTS`       | Доступное время             | 09:00–18:00, каждый час |
+
+---
+
+## 🔐 Админ-панель
+
+В чате с ботом: `/admin пароль`
+
+Админ видит все бронирования и может отменять любые.
+
+---
+
+## 🗄 Хранилище
+
+Данные хранятся в JSON-файлах в папке `data/`:
+- `users.json` — пользователи
+- `bookings.json` — бронирования
+
+Файлы создаются автоматически при первом запуске.
+
+---
+
+## 🤝 Разработка
+
+1. Создаёшь ветку от `master`
+2. Вносишь изменения
+3. Открываешь Pull Request в `master`
+
+```bash
+git checkout -b feat/my-feature
+# ... работа ...
+git push origin feat/my-feature
+```
+
+---
+
+## 📄 Лицензия
+
+MIT — делайте что хотите.