diff --git a/docs/img/admin_services.png b/docs/img/admin_services.png new file mode 100644 index 0000000..f1f08b9 Binary files /dev/null and b/docs/img/admin_services.png differ diff --git a/docs/img/authentik_login.png b/docs/img/authentik_login.png new file mode 100644 index 0000000..20c510c Binary files /dev/null and b/docs/img/authentik_login.png differ diff --git a/docs/img/payment_success.png b/docs/img/payment_success.png new file mode 100644 index 0000000..938aea4 Binary files /dev/null and b/docs/img/payment_success.png differ diff --git a/docs/user_guide.md b/docs/user_guide.md new file mode 100644 index 0000000..4110d9d --- /dev/null +++ b/docs/user_guide.md @@ -0,0 +1,130 @@ +# Инструкция по использованию сайта и панели администратора ИКП + +Данный документ содержит руководство по работе с сайтом Института Киберспорта (ИКП), включая форму регистрации, систему онлайн-оплаты ЮKassa, личный кабинет администратора и интеграцию с Authentik OIDC (Mailcow). + +--- + +## 1. Общая архитектура системы + +Сайт ИКП состоит из следующих компонентов: +* **Фронтенд**: Лендинг с тарифами и форма регистрации (`/form/index.html`). +* **Бэкенд**: Flask-приложение (`server.py`), работающее в Docker-контейнере. +* **База данных**: SQLite (`bot_database.db`) для хранения активностей, заказов и каталога услуг. +* **Excel-таблица**: `form/registration_for_training.xlsx` — дублирующий реестр заявок на хост-машине. +* **Авторизация**: Интеграция с Authentik (OIDC) для защиты админ-панели с авторизацией через Mailcow. +* **Оплата**: API ЮKassa для создания счетов и фискализации чеков (54-ФЗ). +* **Уведомления**: SMTP-почта и VK API для оперативного информирования менеджеров. + +--- + +## 2. Публичная часть (для клиентов) + +### Шаг 2.1. Выбор тарифа +На главном лендинге клиент выбирает интересующий тариф и нажимает кнопку **«Записаться»**. +Кнопки содержат ссылки с параметром `service_id` (например, `/form/index.html?service_id=web_1`), который автоматически передается на страницу формы. + +### Шаг 2.2. Заполнение формы +На странице формы регистрации клиент заполняет поля: +1. **Имя** (обязательное) +2. **Телефон** (обязательное) +3. **E-mail** (обязательное) +4. **Ссылка на профиль ВКонтакте** (опционально) +5. Согласие с договором-офертой, политикой персональных данных и рассылкой. + +При загрузке форма автоматически запрашивает актуальный список услуг и цен из базы данных бэкенда (`GET /api/services`) и отображает плашку с выбранным тарифом. + +### Шаг 2.3. Переход на оплату и возврат +1. При нажатии кнопки **«Оставить заявку»** бэкенд: + * Проверяет корректность цены в БД (защита от подмены цены клиентом). + * Регистрирует заявку в SQLite со статусом `pending` (Ожидает оплаты). + * Записывает строку в Excel-файл. + * Отправляет первичное уведомление менеджерам на почту и в VK о создании неоплаченного заказа. + * Создает платеж в API ЮKassa и отправляет клиенту ссылку для оплаты. +2. Фронтенд **сразу перенаправляет** клиента на защищенную страницу оплаты ЮKassa. +3. После успешного проведения платежа ЮKassa возвращает клиента на адрес: + `https://infocyber.pro/form/index.html?success=true®_id=id_XXX` +4. Клиент видит красивую плашку об успешной оплате и кнопку **«На главную»**. + +![Успешная регистрация и оплата](img/payment_success.png) + +--- + +## 3. Личный кабинет администратора (`/admin`) + +Панель администратора доступна по адресу: [https://infocyber.pro/admin](https://infocyber.pro/admin). + +### Шаг 3.1. Вход через Authentik (Mailcow) +1. При переходе в `/admin` неавторизованный пользователь автоматически перенаправляется на ваш сервер авторизации Authentik. +2. Благодаря включенной опции **Auto-redirect** в Authentik, страница входа самого Authentik скрыта, и пользователя сразу перенаправляет на форму входа корпоративной почты **Mailcow**. + +![Форма входа в Authentik / Mailcow](img/authentik_login.png) + +> [!TIP] +> **Как зайти локальным администратором Authentik?** +> Если вам нужно обойти авто-переход на Mailcow и войти под локальным администратором Authentik (`akadmin`), используйте ссылку: +> `https://auth.infocyber.pro/if/flow/default-authentication-flow/?ignore_redirect=true` + +--- + +### Шаг 3.2. Раздел «Заявки» (Реестр заказов) +После успешного входа открывается главный экран панели управления: + +* **Карточки статистики**: Отображают общее количество заявок, число успешных оплат, количество неоплаченных заказов и общую сумму сборов (выручку). +* **Поиск**: Живой поиск на лету по имени клиента, телефону или e-mail. +* **Фильтрация**: Быстрое переключение реестра по вкладкам «Все», «Оплачено», «Ожидает оплаты». +* **Таблица заказов**: Содержит ID заявки, ФИО клиента, контактные данные (со ссылкой на VK), выбранный тариф, сумму, статус оплаты и дату создания/оплаты. +* **Кнопка «Проверить»**: Если вебхук от ЮKassa задерживается, администратор может вручную нажать кнопку «🔄 Проверить» напротив неоплаченного заказа. Бэкенд напрямую запросит статус платежа из API ЮKassa и обновит статус в БД и Excel в случае успеха. + +--- + +### Шаг 3.3. Раздел «Услуги» (Каталог тарифов) +Перейдите на вкладку **«Услуги»** в верхнем меню админки: + +![Каталог услуг в панели администратора](img/admin_services.png) + +#### Добавление новой услуги: +1. Нажмите **«Добавить услугу»**. +2. Заполните поля: + * **ID услуги**: Уникальный код латиницей (например, `web_6`). + * **Название услуги**: Отображаемое название (например, `Курс по Dota 2`). + * **Отображаемая цена**: Текст для сайта (например, `1 500 ₽`). + * **Числовая цена (для YooKassa)**: Точная сумма в рублях для выставления счета (например, `1500`). + * **Описание**: Информация о тарифе. +3. Сохраните. Новая услуга сразу станет доступна для записи на сайте. + +#### Редактирование услуги: +1. Нажмите **«Ред.»** (Редактировать) напротив услуги. +2. В появившемся окне можно изменить любые параметры, включая галочку **«Активна»**. +3. Если снять галочку «Активна», услуга скроется с сайта и станет недоступна для оплаты. + +--- + +## 4. Настройки и техническое обслуживание + +### Шаг 4.1. Файл конфигурации `.env` +Все секреты и настройки хранятся в файле `/opt/Site_IKP_zaglushka/.env` на сервере: +* `YOOKASSA_SHOP_ID` и `YOOKASSA_SECRET_KEY` — ключи интеграции платежей. +* Настройки SMTP (`SMTP_SERVER`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASSWORD`) — для отправки писем о заказах. +* Настройки Authentik (`AUTHENTIK_CLIENT_ID`, `AUTHENTIK_CLIENT_SECRET`) — для авторизации. +* `VERIFY_WEBHOOK_IP=True` — защита вебхуков (разрешает принимать статусы оплат только от официальных IP-адресов ЮKassa). + +### Шаг 4.2. Деплой обновлений на сервере `ea2go` +Если вы внесли изменения в код и запушили их в репозиторий, обновите сайт на сервере следующими командами: + +```bash +# Подключитесь к серверу +ssh ea2go + +# Перейдите в папку проекта и обновите код +cd /opt/Site_IKP_zaglushka +git pull origin main + +# Пересоберите и запустите контейнеры в фоновом режиме +docker compose up -d --build +``` + +### Шаг 4.3. Просмотр логов приложения +Чтобы посмотреть логи работы сайта (например, отследить отправку писем или вебхуки оплаты): +```bash +docker compose logs -f --tail=100 +``` diff --git a/zen_57mpP0qXglvS5oDWkRSJfI25Pe31qQlg8jQqMDlJkIm2ygfKyGLxAPAayW6F3oo1.html b/zen_57mpP0qXglvS5oDWkRSJfI25Pe31qQlg8jQqMDlJkIm2ygfKyGLxAPAayW6F3oo1.html new file mode 100644 index 0000000..9c5b0a3 --- /dev/null +++ b/zen_57mpP0qXglvS5oDWkRSJfI25Pe31qQlg8jQqMDlJkIm2ygfKyGLxAPAayW6F3oo1.html @@ -0,0 +1 @@ +