glpshchn
/
nakama
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
nakama/PROJECT_STRUCTURE.md

396 lines
17 KiB
Markdown
Raw Normal View History

Initial commit
2025-11-03 20:35:01 +00:00
# 📂 Структура проекта 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