396 lines
17 KiB
Markdown
396 lines
17 KiB
Markdown
# 📂 Структура проекта NakamaSpace
|
||
|
||
Полная карта проекта с описанием каждого файла и директории.
|
||
|
||
## 🗂️ Корневая директория
|
||
|
||
```
|
||
nakama/
|
||
├── backend/ # Backend сервер (Node.js + Express)
|
||
├── frontend/ # Frontend приложение (React + Vite)
|
||
├── .gitignore # Игнорируемые файлы для Git
|
||
├── .env.example # Пример переменных окружения
|
||
├── package.json # Зависимости backend и скрипты
|
||
├── README.md # Основная документация
|
||
├── SETUP.md # Подробная инструкция по установке
|
||
├── QUICKSTART.md # Быстрый старт за 5 минут
|
||
├── CONTRIBUTING.md # Гайд для разработчиков
|
||
├── LICENSE # MIT лицензия
|
||
└── start.sh # Скрипт быстрого запуска
|
||
```
|
||
|
||
## 🔧 Backend (`/backend`)
|
||
|
||
### Структура
|
||
|
||
```
|
||
backend/
|
||
├── models/ # MongoDB схемы
|
||
│ ├── User.js # Модель пользователя
|
||
│ ├── Post.js # Модель поста с комментариями
|
||
│ ├── Notification.js # Модель уведомлений
|
||
│ └── Report.js # Модель жалоб
|
||
├── routes/ # API endpoints
|
||
│ ├── auth.js # Авторизация через Telegram
|
||
│ ├── posts.js # CRUD постов, лайки, комментарии
|
||
│ ├── users.js # Профили, подписки, поиск
|
||
│ ├── notifications.js # Система уведомлений
|
||
│ ├── search.js # Интеграция e621 и gelbooru
|
||
│ └── moderation.js # Модерация и жалобы
|
||
├── middleware/ # Middleware функции
|
||
│ └── auth.js # Проверка Telegram Init Data
|
||
└── server.js # Точка входа, Express сервер
|
||
```
|
||
|
||
### Модели данных
|
||
|
||
#### User (Пользователь)
|
||
- `telegramId` - ID из Telegram (уникальный)
|
||
- `username`, `firstName`, `lastName` - Данные пользователя
|
||
- `photoUrl` - Аватар из Telegram
|
||
- `bio` - Описание профиля (до 300 символов)
|
||
- `role` - Роль: user / moderator / admin
|
||
- `followers` / `following` - Подписчики и подписки
|
||
- `settings` - Настройки фильтров и поиска
|
||
- `banned` - Флаг блокировки
|
||
|
||
#### Post (Пост)
|
||
- `author` - Автор (ref User)
|
||
- `content` - Текст поста (до 2000 символов)
|
||
- `imageUrl` - URL изображения
|
||
- `tags` - Массив тегов: furry / anime / other
|
||
- `mentionedUsers` - Упомянутые пользователи
|
||
- `isNSFW` - Флаг 18+ контента
|
||
- `likes` - Массив ID пользователей
|
||
- `comments` - Встроенные комментарии
|
||
- `reposts` - Массив ID пользователей
|
||
|
||
#### Notification (Уведомление)
|
||
- `recipient` - Получатель (ref User)
|
||
- `sender` - Отправитель (ref User)
|
||
- `type` - Тип: follow / like / comment / repost / mention
|
||
- `post` - Связанный пост (опционально)
|
||
- `read` - Флаг прочтения
|
||
|
||
#### Report (Жалоба)
|
||
- `reporter` - Кто пожаловался (ref User)
|
||
- `post` - На какой пост (ref Post)
|
||
- `reason` - Причина жалобы
|
||
- `status` - Статус: pending / reviewed / resolved / dismissed
|
||
- `reviewedBy` - Модератор (ref User)
|
||
|
||
### API Endpoints
|
||
|
||
#### Авторизация
|
||
- `POST /api/auth/verify` - Верификация Telegram Init Data
|
||
|
||
#### Посты
|
||
- `GET /api/posts` - Получить ленту (с фильтрами и пагинацией)
|
||
- `POST /api/posts` - Создать пост (с изображением)
|
||
- `POST /api/posts/:id/like` - Лайк/дизлайк
|
||
- `POST /api/posts/:id/comment` - Добавить комментарий
|
||
- `POST /api/posts/:id/repost` - Репост
|
||
- `DELETE /api/posts/:id` - Удалить (автор или модератор)
|
||
|
||
#### Пользователи
|
||
- `GET /api/users/:id` - Профиль пользователя
|
||
- `GET /api/users/:id/posts` - Посты пользователя
|
||
- `POST /api/users/:id/follow` - Подписаться/отписаться
|
||
- `PUT /api/users/profile` - Обновить свой профиль
|
||
- `GET /api/users/search/:query` - Поиск пользователей
|
||
|
||
#### Уведомления
|
||
- `GET /api/notifications` - Список уведомлений
|
||
- `PUT /api/notifications/:id/read` - Отметить прочитанным
|
||
- `PUT /api/notifications/read-all` - Прочитать все
|
||
|
||
#### Поиск
|
||
- `GET /api/search/furry?query=tags` - Поиск в e621
|
||
- `GET /api/search/anime?query=tags` - Поиск в gelbooru
|
||
- `GET /api/search/furry/tags?query=tag` - Автокомплит e621
|
||
- `GET /api/search/anime/tags?query=tag` - Автокомплит gelbooru
|
||
- `GET /api/search/proxy/:encodedUrl` - Проксирование изображений с e621/gelbooru
|
||
|
||
#### Модерация (требуют роли moderator/admin)
|
||
- `POST /api/moderation/report` - Создать жалобу (все пользователи)
|
||
- `GET /api/moderation/reports` - Список жалоб
|
||
- `PUT /api/moderation/reports/:id` - Обработать жалобу
|
||
- `PUT /api/moderation/posts/:id/nsfw` - Установить NSFW
|
||
- `PUT /api/moderation/users/:id/ban` - Заблокировать пользователя
|
||
|
||
## 🎨 Frontend (`/frontend`)
|
||
|
||
### Структура
|
||
|
||
```
|
||
frontend/
|
||
├── src/
|
||
│ ├── components/ # React компоненты
|
||
│ │ ├── Layout.jsx # Основной Layout с навигацией
|
||
│ │ ├── Navigation.jsx # Нижняя панель навигации
|
||
│ │ ├── PostCard.jsx # Карточка поста
|
||
│ │ ├── CreatePostModal.jsx # Модалка создания поста
|
||
│ │ ├── CommentsModal.jsx # Модалка комментариев
|
||
│ │ └── PostMenu.jsx # Меню поста (удалить, пожаловаться)
|
||
│ ├── pages/ # Страницы-вкладки
|
||
│ │ ├── Feed.jsx # Лента постов
|
||
│ │ ├── Search.jsx # Поиск (e621 + gelbooru)
|
||
│ │ ├── Notifications.jsx # Уведомления
|
||
│ │ ├── Profile.jsx # Свой профиль
|
||
│ │ └── UserProfile.jsx # Профиль другого пользователя
|
||
│ ├── utils/ # Утилиты
|
||
│ │ ├── api.js # Axios API клиент
|
||
│ │ └── telegram.js # Telegram Mini App SDK
|
||
│ ├── styles/ # Глобальные стили
|
||
│ │ └── index.css # CSS переменные и базовые стили
|
||
│ ├── App.jsx # Корневой компонент
|
||
│ └── main.jsx # Точка входа React
|
||
├── index.html # HTML шаблон
|
||
├── vite.config.js # Конфигурация Vite
|
||
├── package.json # Зависимости frontend
|
||
└── .env.example # Пример переменных окружения
|
||
```
|
||
|
||
### Компоненты
|
||
|
||
#### Layout & Navigation
|
||
- **Layout** - Обёртка с навигацией, содержит React Router Outlet
|
||
- **Navigation** - 4 кнопки: Лента, Поиск, Уведомления, Профиль
|
||
- Использует lucide-react иконки
|
||
- Активная вкладка подсвечивается синим
|
||
|
||
#### PostCard (Карточка поста)
|
||
Основной компонент для отображения постов:
|
||
- Аватар и имя автора (кликабельно → профиль)
|
||
- Дата публикации
|
||
- Текст поста
|
||
- Изображение (если есть)
|
||
- Теги с цветовой кодировкой:
|
||
- 🦊 Furry - оранжевый (#FF8A33)
|
||
- 🎌 Anime - синий (#4A90E2)
|
||
- ⚪ Other - серый (#A0A0A0)
|
||
- NSFW badge (если помечено)
|
||
- Действия: лайк, комментарий, репост
|
||
- Меню (три точки): удалить или пожаловаться
|
||
|
||
#### CreatePostModal (Создание поста)
|
||
Модальное окно с функциями:
|
||
- Текстовое поле (до 2000 символов)
|
||
- Загрузка изображения (до 10MB)
|
||
- Выбор тегов (обязательно хотя бы один)
|
||
- Поиск и упоминание пользователей (@username)
|
||
- Чекбокс NSFW
|
||
- Превью изображения с кнопкой удаления
|
||
|
||
#### CommentsModal (Комментарии)
|
||
- Список комментариев с аватарами
|
||
- Форма добавления (Enter для отправки)
|
||
- Время публикации ("только что", "5 мин", "2 ч")
|
||
- Автоматическая прокрутка к новому комментарию
|
||
|
||
#### PostMenu (Меню поста)
|
||
- Для своих постов: Удалить
|
||
- Для чужих: Пожаловаться
|
||
- Для модераторов: дополнительные опции
|
||
|
||
### Страницы
|
||
|
||
#### Feed (Лента)
|
||
- Хедер с названием и кнопкой "+"
|
||
- Фильтры: Все / Furry / Anime / Other
|
||
- Бесконечная загрузка (пагинация)
|
||
- Применяет whitelist настройки пользователя
|
||
- Pull-to-refresh (планируется)
|
||
|
||
#### Search (Поиск)
|
||
- Переключатель: Furry / Anime / Mixed
|
||
- Строка поиска с автокомплитом тегов
|
||
- Сетка результатов (2 колонки)
|
||
- Просмотрщик изображений:
|
||
- Полноэкранный режим
|
||
- Swipe влево/вправо
|
||
- Скачивание изображения
|
||
- Информация о тегах и рейтинге
|
||
|
||
#### Notifications (Уведомления)
|
||
Telegram-стиль баблов:
|
||
- Цветовая кодировка по типу уведомления
|
||
- Аватар отправителя с иконкой действия
|
||
- Превью поста (текст или изображение)
|
||
- Непрочитанные выделены фоном
|
||
- Счётчик непрочитанных
|
||
- Кнопка "Прочитать все"
|
||
- Клик → переход к посту или профилю
|
||
|
||
#### Profile (Свой профиль)
|
||
- Аватар из Telegram
|
||
- Имя, username, роль (модератор/админ)
|
||
- Редактируемое био (до 300 символов)
|
||
- Статистика: подписчики / подписки
|
||
- Донаты через Telegram Stars
|
||
- Быстрые настройки:
|
||
- Без Furry контента
|
||
- Только Anime
|
||
- Без NSFW
|
||
- Кнопка настроек → полная модалка
|
||
|
||
#### UserProfile (Профиль другого пользователя)
|
||
- Информация о пользователе
|
||
- Кнопка подписаться/отписаться
|
||
- Список постов пользователя
|
||
- Кнопка "Назад"
|
||
|
||
### Утилиты
|
||
|
||
#### api.js
|
||
Axios клиент с:
|
||
- Автоматической добавкой Telegram Init Data в headers
|
||
- Обработкой ошибок
|
||
- Типизированными методами для всех endpoints
|
||
- Dev моками для разработки без Telegram
|
||
|
||
#### telegram.js
|
||
Обёртка над Telegram Mini App SDK:
|
||
- `initTelegramApp()` - Инициализация
|
||
- `getTelegramUser()` - Получить данные пользователя
|
||
- `getTelegramInitData()` - Init Data для API
|
||
- `showAlert()`, `showConfirm()` - Нативные диалоги
|
||
- `hapticFeedback()` - Тактильная обратная связь
|
||
- `openLink()`, `openTelegramLink()` - Открыть ссылки
|
||
- Dev моки для тестирования
|
||
|
||
### Стили
|
||
|
||
#### Цветовая палитра (CSS переменные)
|
||
```css
|
||
--bg-primary: #F2F3F5 /* Основной фон */
|
||
--bg-secondary: #FFFFFF /* Фон карточек */
|
||
--text-primary: #1C1C1E /* Основной текст */
|
||
--text-secondary: #5C5C5C /* Второстепенный текст */
|
||
--border-color: #C7C7CC /* Границы */
|
||
--divider-color: #E5E5EA /* Разделители */
|
||
|
||
--tag-furry: #FF8A33 /* Оранжевый */
|
||
--tag-anime: #4A90E2 /* Синий */
|
||
--tag-other: #A0A0A0 /* Серый */
|
||
|
||
--button-dark: #1C1C1E /* Тёмная кнопка */
|
||
--button-accent: #007AFF /* Акцентная кнопка (iOS синий) */
|
||
|
||
--search-bg: #E6E6E8 /* Фон поиска */
|
||
```
|
||
|
||
#### Анимации
|
||
- `fadeIn` - Плавное появление (0.3s)
|
||
- `slideUp` - Слайд снизу (0.3s)
|
||
- `scaleIn` - Масштабирование (0.2s)
|
||
|
||
#### Компоненты
|
||
- Радиус скругления: 16px для карточек, 12px для кнопок
|
||
- Тени: мягкие rgba(0,0,0,0.08)
|
||
- Отступы: 16px стандарт
|
||
- Шрифт: SF Pro Display (iOS) / Roboto (Android)
|
||
|
||
## 🚀 Скрипты
|
||
|
||
### Корневые (package.json)
|
||
```bash
|
||
npm run dev # Запуск backend + frontend
|
||
npm run server # Только backend (nodemon)
|
||
npm run client # Только frontend (vite)
|
||
npm run build # Сборка frontend для production
|
||
npm start # Production сервер
|
||
```
|
||
|
||
### Frontend (frontend/package.json)
|
||
```bash
|
||
npm run dev # Dev сервер Vite (HMR)
|
||
npm run build # Сборка для production
|
||
npm run preview # Превью production сборки
|
||
```
|
||
|
||
## 🔐 Безопасность
|
||
|
||
### Backend
|
||
- Telegram Init Data валидация с HMAC-SHA256
|
||
- JWT для сессий (опционально)
|
||
- Multer для безопасной загрузки файлов
|
||
- Rate limiting (TODO)
|
||
- Санитизация входных данных
|
||
|
||
### Frontend
|
||
- XSS защита через React
|
||
- CORS настройки
|
||
- HTTPS only для production
|
||
- Нет хранения секретов в коде
|
||
|
||
## 📦 Зависимости
|
||
|
||
### Backend
|
||
- `express` - Web framework
|
||
- `mongoose` - MongoDB ORM
|
||
- `cors` - CORS middleware
|
||
- `dotenv` - Переменные окружения
|
||
- `axios` - HTTP клиент (для API e621/gelbooru)
|
||
- `multer` - Загрузка файлов
|
||
- `crypto` - Криптография для Telegram
|
||
|
||
### Frontend
|
||
- `react` + `react-dom` - UI библиотека
|
||
- `react-router-dom` - Роутинг
|
||
- `@twa-dev/sdk` - Telegram Mini App SDK
|
||
- `axios` - HTTP клиент
|
||
- `lucide-react` - Иконки
|
||
- `vite` - Сборщик
|
||
|
||
## 🎯 Ключевые особенности
|
||
|
||
### Дизайн
|
||
- ✅ iOS-стиль минимализм
|
||
- ✅ Нейтральная серая палитра
|
||
- ✅ Bubble-дизайн для уведомлений
|
||
- ✅ Плавные анимации
|
||
- ✅ Адаптивная вёрстка
|
||
|
||
### Функциональность
|
||
- ✅ Полный CRUD постов
|
||
- ✅ Лайки, комментарии, репосты
|
||
- ✅ Система тегов (Furry, Anime, Other)
|
||
- ✅ Интеграция e621 и gelbooru API
|
||
- ✅ **Проксирование изображений для доступа из РФ**
|
||
- ✅ Система уведомлений
|
||
- ✅ Подписки на пользователей
|
||
- ✅ Модерация и жалобы
|
||
- ✅ Настройки whitelist фильтров
|
||
- ✅ Telegram авторизация
|
||
|
||
### Качество кода
|
||
- ✅ Модульная архитектура
|
||
- ✅ Переиспользуемые компоненты
|
||
- ✅ Централизованное управление API
|
||
- ✅ Error handling
|
||
- ✅ Логирование
|
||
- ✅ Документация
|
||
|
||
## 📝 TODO / Планы развития
|
||
|
||
- [ ] Unit тесты
|
||
- [ ] E2E тесты
|
||
- [ ] Rate limiting
|
||
- [ ] Кэширование (Redis)
|
||
- [ ] WebSocket для real-time уведомлений
|
||
- [ ] Telegram Stars интеграция
|
||
- [ ] Поиск по постам
|
||
- [ ] Хэштеги
|
||
- [ ] Приватные сообщения
|
||
- [ ] Группы/сообщества
|
||
- [ ] Рекомендации постов (алгоритм)
|
||
- [ ] Статистика для авторов
|
||
- [ ] Dark mode
|
||
- [ ] Мультиязычность
|
||
|
||
---
|
||
|
||
**Вопросы?** Смотрите полную документацию в README.md, SETUP.md и CONTRIBUTING.md
|
||
|