commit 83fca6799f9310ad633fc46becfae05076bb02b6 Author: houseassassin Date: Wed May 20 11:38:33 2026 +0300 docs: add Aura Store design spec diff --git a/docs/2026-05-20-aura-store-design.md b/docs/2026-05-20-aura-store-design.md new file mode 100644 index 0000000..28d1f4e --- /dev/null +++ b/docs/2026-05-20-aura-store-design.md @@ -0,0 +1,228 @@ +# Aura Store — Design Spec +**Дата:** 2026-05-20 +**Статус:** Draft → Approved +**Проект:** VPN-сервис, веб-кабинет для Cricket VPN / Aura VPN + +--- + +## Обзор + +Полноценный веб-сайт **Aura Store** для VPN-сервиса на домене `cricket-vpn.ru`. Включает публичный лендинг и личный кабинет пользователя. Интегрируется с существующим Telegram-ботом через API. + +--- + +## Стек + +| Слой | Технология | +|------|-----------| +| Frontend | Vite + React + TypeScript | +| Роутинг | React Router v6 | +| Состояние | Zustand | +| Анимации | Framer Motion | +| Иконки | Lucide React | +| Стили | Tailwind CSS + custom CSS variables | +| Build output | `/var/www/aura-store/` (статика) | +| Backend (auth) | FastAPI `api/routes/web_auth.py` (новый файл, порт 3004) | +| Backend (actions) | Существующий `/api/webapp/` без изменений | + +--- + +## Архитектура + +``` +cricket-vpn.ru +│ +├── / → /var/www/aura-store/ (Vite SPA) +├── /api/web/* → localhost:3004 (новые JWT-эндпоинты) +└── /api/webapp/* → localhost:3004 (существующий бот API) +``` + +### Новый файл бэкенда + +`/root/cricketvpn/api/routes/web_auth.py` — регистрируется в существующем FastAPI-приложении. Бот не трогается. + +### JWT-схема + +- **Payload:** `{ tg_id, user_id, exp }` +- **Хранение:** `localStorage` на клиенте +- **Заголовок:** `Authorization: Bearer ` +- `tg_id` из JWT используется для вызова всех существующих `_ACTIONS` хендлеров без изменений + +--- + +## Бэкенд: эндпоинты `/api/web/` + +| Метод | URL | Описание | +|-------|-----|----------| +| POST | `/api/web/register` | email + password → JWT | +| POST | `/api/web/login` | email + password → JWT | +| POST | `/api/web/tg_auth` | Telegram Login Widget hash → JWT | +| POST | `/api/web/action` | JWT + action + payload → проксирует в `_ACTIONS` | +| POST | `/api/web/refresh` | refresh_token → новый access JWT | + +### Миграция БД + +```sql +ALTER TABLE users ADD COLUMN IF NOT EXISTS email VARCHAR UNIQUE; +ALTER TABLE users ADD COLUMN IF NOT EXISTS password_hash VARCHAR; +ALTER TABLE users ADD COLUMN IF NOT EXISTS tg_linked BOOLEAN DEFAULT FALSE; +``` + +### Telegram Login Widget + +- Официальный виджет генерирует `hash` на фронте +- Бэкенд верифицирует через HMAC-SHA256 с bot token +- Находит или создаёт пользователя по `tg_id` + +### Регистрация через email + +- Создаётся запись с `tg_id = NULL` если Telegram не привязан +- При последующей привязке Telegram — `tg_id` проставляется +- Весь функционал кабинета доступен сразу + +--- + +## Страницы + +### Публичные + +| Маршрут | Описание | +|---------|----------| +| `/` | Лендинг | +| `/login` | Вход (Telegram + email/password) | +| `/register` | Регистрация | + +### Личный кабинет (требует JWT) + +| Маршрут | Описание | +|---------|----------| +| `/dashboard` | Главная: статус подписки, мои ключи | +| `/dashboard/keys` | Ключи + QR-коды | +| `/dashboard/devices` | Подключённые устройства | +| `/dashboard/payments` | История платежей | +| `/dashboard/servers` | Статус серверов | +| `/profile` | Настройки (имя, смена пароля, привязка TG) | + +Незалогиненный пользователь на `/dashboard/*` → редирект на `/login`. + +--- + +## Структура проекта + +``` +aura-store/ +├── src/ +│ ├── pages/ +│ │ ├── Landing.tsx +│ │ ├── Login.tsx +│ │ ├── Register.tsx +│ │ ├── dashboard/ +│ │ │ ├── Dashboard.tsx +│ │ │ ├── Keys.tsx +│ │ │ ├── Devices.tsx +│ │ │ ├── Payments.tsx +│ │ │ └── Servers.tsx +│ │ └── Profile.tsx +│ ├── components/ +│ │ ├── layout/ Navbar, Sidebar, Footer, PrivateRoute +│ │ ├── landing/ HeroSection, FeaturesSection, PricingSection, +│ │ │ HowToSection, FAQSection +│ │ └── ui/ KeyCard, QRModal, PricingCard, StatusBadge, +│ │ GlassCard, Button, Input +│ ├── api/ +│ │ └── client.ts fetch-wrapper с JWT, все action-вызовы +│ ├── hooks/ +│ │ ├── useAuth.ts +│ │ ├── useProfile.ts +│ │ └── useTariffs.ts +│ ├── store/ +│ │ └── auth.ts Zustand store (token, user, isLoading) +│ └── styles/ +│ └── globals.css +├── public/ +├── index.html +├── vite.config.ts +└── package.json +``` + +--- + +## Дизайн-система + +### Цвета + +```css +--bg: #0d0b1e /* основной фон */ +--bg2: #1a1535 /* фон карточек */ +--accent: #8b5cf6 /* фиолетовый */ +--accent2: #6366f1 /* индиго */ +--green: #34d399 +--red: #f87171 +--text: #ffffff +--text2: rgba(255,255,255,.45) +``` + +### Компоненты + +- **GlassCard** — `backdrop-filter: blur(12px)`, полупрозрачный border +- **Button** — градиент accent→accent2, hover scale transform +- **StatusBadge** — зелёный/красный dot + текст +- **QRModal** — оверлей с QR-кодом (qrcode.js), кнопка закрыть + +### Лендинг (секции) + +1. **Hero** — заголовок "Свобода в сети", подзаголовок, кнопки "Подключиться" / "Войти", анимированный фоновый эффект (CSS) +2. **Преимущества** — 6 карточек: скорость, приватность, кол-во устройств, протоколы (WireGuard/VLESS), поддержка, серверы +3. **Тарифы** — динамически из API, карточки с ценами, бейдж "Популярный" +4. **Как подключиться** — 4 шага: купить → скачать приложение → отсканировать QR → работает +5. **FAQ** — accordion, 5-6 вопросов +6. **Футер** — логотип, ссылки, Telegram-канал + +### Личный кабинет + +- Sidebar слева (десктоп) / bottom nav (мобиле) +- Те же glassmorphism карточки +- QR в модалке + +--- + +## Деплой + +```bash +# Сборка +npm run build + +# Деплой на сервер +rsync -av dist/ root@2.26.52.87:/var/www/aura-store/ +``` + +### Caddy — добавить маршрут + +```caddy +cricket-vpn.ru { + handle /api/* { + reverse_proxy localhost:3004 + } + handle { + root * /var/www/aura-store + try_files {path} /index.html + file_server + } +} +``` + +--- + +## Связанные файлы на сервере + +- `/root/cricketvpn/api/routes/web_auth.py` — новый файл авторизации +- `/root/cricketvpn/modules/user_cabinet/router.py` — существующие `_ACTIONS` (не трогать) +- `/etc/caddy/Caddyfile` — добавить маршрут для cricket-vpn.ru +- `/var/www/aura-store/` — папка для статики (создать) + +--- + +## Репозиторий + +- **Gitea:** https://gitea.houseassassin.keenetic.pro/houseassassin/aura-store +- **Структура репо:** монорепо (frontend + backend файл)