374 lines
12 KiB
Markdown
374 lines
12 KiB
Markdown
|
# 🌟 NakamaSpace - Telegram Mini App
|
|||
|
|
|
|||
|
|
> Полноценная мини-социальная сеть внутри Telegram с 4 вкладками, системой постов, поиском, уведомлениями и модерацией.
|
|||
|
|
|
|||
|
|
[](https://opensource.org/licenses/MIT)
|
|||
|
|
[](https://nodejs.org/)
|
|||
|
|
[](https://reactjs.org/)
|
|||
|
|
[](https://www.mongodb.com/)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## ✨ Возможности
|
|||
|
|
|
|||
|
|
### 🏠 Лента постов
|
|||
|
|
- ✅ Создание постов с текстом и изображениями (до 10MB)
|
|||
|
|
- ✅ Обязательные теги: **Furry** 🦊, **Anime** 🎌, **Other** ⚪
|
|||
|
|
- ✅ Лайки, комментарии, репосты
|
|||
|
|
- ✅ Упоминания пользователей (@username)
|
|||
|
|
- ✅ NSFW маркировка контента
|
|||
|
|
- ✅ Фильтрация по тегам
|
|||
|
|
- ✅ Бесконечная загрузка (пагинация)
|
|||
|
|
|
|||
|
|
### 🔍 Поиск
|
|||
|
|
- ✅ Интеграция с **e621 API** (Furry контент)
|
|||
|
|
- ✅ Интеграция с **gelbooru API** (Anime контент)
|
|||
|
|
- ✅ **Прокси изображений через сервер** (доступ из РФ)
|
|||
|
|
- ✅ Смешанный режим поиска (Mixed)
|
|||
|
|
- ✅ Автокомплит тегов с количеством результатов
|
|||
|
|
- ✅ Просмотрщик изображений с swipe навигацией
|
|||
|
|
- ✅ Скачивание изображений
|
|||
|
|
- ✅ Отображение рейтинга и тегов
|
|||
|
|
|
|||
|
|
### 🔔 Уведомления
|
|||
|
|
- ✅ Telegram-стиль баблов с цветовой кодировкой
|
|||
|
|
- ✅ Уведомления о подписках, лайках, комментариях, репостах
|
|||
|
|
- ✅ Упоминания в постах
|
|||
|
|
- ✅ Счётчик непрочитанных
|
|||
|
|
- ✅ Превью постов в уведомлениях
|
|||
|
|
- ✅ Переходы к постам и профилям
|
|||
|
|
|
|||
|
|
### 👤 Профиль
|
|||
|
|
- ✅ Аватар и данные из Telegram
|
|||
|
|
- ✅ Редактируемое био (до 300 символов)
|
|||
|
|
- ✅ Статистика: подписчики / подписки
|
|||
|
|
- ✅ Настройки фильтров контента:
|
|||
|
|
- Без Furry контента
|
|||
|
|
- Только Anime
|
|||
|
|
- Без NSFW
|
|||
|
|
- ✅ Настройки поиска (Furry / Anime / Mixed)
|
|||
|
|
- ✅ Донаты через Telegram Stars (UI готов)
|
|||
|
|
- ✅ Роли: User / Moderator / Admin
|
|||
|
|
|
|||
|
|
### 🛡️ Модерация
|
|||
|
|
- ✅ Система жалоб на посты
|
|||
|
|
- ✅ Панель модератора
|
|||
|
|
- ✅ Удаление постов
|
|||
|
|
- ✅ Блокировка пользователей (временная/постоянная)
|
|||
|
|
- ✅ Установка NSFW флага
|
|||
|
|
- ✅ Просмотр и обработка репортов
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🚀 Быстрый старт
|
|||
|
|
|
|||
|
|
### Супер быстрый запуск (5 минут)
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 1. Клонировать репозиторий
|
|||
|
|
git clone <repository-url>
|
|||
|
|
cd nakama
|
|||
|
|
|
|||
|
|
# 2. Запустить автоматический скрипт
|
|||
|
|
./start.sh
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Скрипт автоматически:
|
|||
|
|
- ✅ Проверит и запустит MongoDB
|
|||
|
|
- ✅ Установит все зависимости
|
|||
|
|
- ✅ Создаст .env файлы из примеров
|
|||
|
|
- ✅ Запустит приложение
|
|||
|
|
|
|||
|
|
**Единственное что нужно** - получить Telegram Bot Token у [@BotFather](https://t.me/BotFather) и добавить в `.env`
|
|||
|
|
|
|||
|
|
📖 Подробная инструкция: [QUICKSTART.md](QUICKSTART.md)
|
|||
|
|
|
|||
|
|
### Ручная установка
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 1. Установить зависимости
|
|||
|
|
npm install
|
|||
|
|
cd frontend && npm install && cd ..
|
|||
|
|
|
|||
|
|
# 2. Настроить .env файлы
|
|||
|
|
cp .env.example .env
|
|||
|
|
cp frontend/.env.example frontend/.env
|
|||
|
|
# Отредактируйте .env файлы
|
|||
|
|
|
|||
|
|
# 3. Запустить MongoDB
|
|||
|
|
brew services start mongodb-community # macOS
|
|||
|
|
sudo systemctl start mongod # Linux
|
|||
|
|
|
|||
|
|
# 4. Запустить приложение
|
|||
|
|
npm run dev
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
📖 Полная инструкция: [SETUP.md](SETUP.md)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🎨 Дизайн-система
|
|||
|
|
|
|||
|
|
### Минималистичный iOS-стиль 2025
|
|||
|
|
|
|||
|
|
- **Философия**: Чистый, минималистичный интерфейс в стиле нового Telegram
|
|||
|
|
- **Типографика**: SF Pro Display (iOS) / Roboto (Android)
|
|||
|
|
- **Радиус**: 16px для карточек, 12px для кнопок
|
|||
|
|
- **Тени**: Мягкие, rgba(0,0,0,0.08)
|
|||
|
|
- **Анимации**: Плавные, 0.2-0.3s ease-out
|
|||
|
|
|
|||
|
|
### Цветовая палитра
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
🎨 Основные цвета
|
|||
|
|
├── Фон: #F2F3F5
|
|||
|
|
├── Карточки: #FFFFFF
|
|||
|
|
├── Текст: #1C1C1E
|
|||
|
|
├── Акцент: #007AFF (iOS синий)
|
|||
|
|
└── Границы: #C7C7CC
|
|||
|
|
|
|||
|
|
🏷️ Теги
|
|||
|
|
├── Furry: #FF8A33 (оранжевый)
|
|||
|
|
├── Anime: #4A90E2 (синий)
|
|||
|
|
└── Other: #A0A0A0 (серый)
|
|||
|
|
|
|||
|
|
⚠️ Дополнительные
|
|||
|
|
├── NSFW: #FF3B30 (красный)
|
|||
|
|
├── Успех: #34C759 (зелёный)
|
|||
|
|
└── Донаты: #FFD700 (золотой)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 📱 Технологии
|
|||
|
|
|
|||
|
|
### Frontend
|
|||
|
|
- **React 18** - UI библиотека
|
|||
|
|
- **Vite** - Быстрый сборщик
|
|||
|
|
- **React Router** - Маршрутизация
|
|||
|
|
- **Telegram Mini App SDK** - Интеграция с Telegram
|
|||
|
|
- **Axios** - HTTP клиент
|
|||
|
|
- **Lucide React** - Иконки
|
|||
|
|
|
|||
|
|
### Backend
|
|||
|
|
- **Node.js + Express** - API сервер
|
|||
|
|
- **MongoDB + Mongoose** - База данных
|
|||
|
|
- **Multer** - Загрузка файлов
|
|||
|
|
- **Crypto** - Telegram Init Data валидация
|
|||
|
|
|
|||
|
|
### Интеграции
|
|||
|
|
- **Telegram Bot API** - Авторизация через Init Data
|
|||
|
|
- **e621 API** - Поиск Furry контента
|
|||
|
|
- **gelbooru API** - Поиск Anime контента
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 📂 Структура проекта
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
nakama/
|
|||
|
|
├── 📁 backend/ Backend сервер (Node.js + Express)
|
|||
|
|
│ ├── 📁 models/ MongoDB схемы (User, Post, Notification, Report)
|
|||
|
|
│ ├── 📁 routes/ API endpoints (auth, posts, users, etc)
|
|||
|
|
│ ├── 📁 middleware/ Middleware функции (auth)
|
|||
|
|
│ └── 📄 server.js Точка входа сервера
|
|||
|
|
│
|
|||
|
|
├── 📁 frontend/ Frontend приложение (React + Vite)
|
|||
|
|
│ ├── 📁 src/
|
|||
|
|
│ │ ├── 📁 components/ React компоненты (PostCard, Modals, etc)
|
|||
|
|
│ │ ├── 📁 pages/ Страницы-вкладки (Feed, Search, Notifications, Profile)
|
|||
|
|
│ │ ├── 📁 utils/ Утилиты (API клиент, Telegram SDK)
|
|||
|
|
│ │ └── 📁 styles/ CSS стили с переменными
|
|||
|
|
│ └── 📄 index.html
|
|||
|
|
│
|
|||
|
|
├── 📄 README.md Основная документация (этот файл)
|
|||
|
|
├── 📄 SETUP.md Подробная инструкция по установке
|
|||
|
|
├── 📄 QUICKSTART.md Быстрый старт за 5 минут
|
|||
|
|
├── 📄 PROJECT_STRUCTURE.md Детальная карта проекта
|
|||
|
|
├── 📄 CONTRIBUTING.md Гайд для разработчиков
|
|||
|
|
└── 📄 start.sh Скрипт быстрого запуска
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
📖 Полная карта проекта: [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🔐 Безопасность
|
|||
|
|
|
|||
|
|
- ✅ **Telegram Init Data** валидация с HMAC-SHA256
|
|||
|
|
- ✅ **Безопасная загрузка** файлов с проверкой типов
|
|||
|
|
- ✅ **Роли и права** доступа (User, Moderator, Admin)
|
|||
|
|
- ✅ **XSS защита** через React
|
|||
|
|
- ✅ **CORS** настройки
|
|||
|
|
- ✅ **HTTPS only** для production
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 📚 Документация
|
|||
|
|
|
|||
|
|
- [📖 README.md](README.md) - Основная документация (вы здесь)
|
|||
|
|
- [⚡ QUICKSTART.md](QUICKSTART.md) - Быстрый старт за 5 минут
|
|||
|
|
- [🔧 SETUP.md](SETUP.md) - Подробная инструкция по установке и деплою
|
|||
|
|
- [📂 PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) - Детальная структура проекта
|
|||
|
|
- [🤝 CONTRIBUTING.md](CONTRIBUTING.md) - Гайд для разработчиков
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🛠️ Разработка
|
|||
|
|
|
|||
|
|
### Скрипты
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# Запуск в dev режиме (backend + frontend)
|
|||
|
|
npm run dev
|
|||
|
|
|
|||
|
|
# Только backend
|
|||
|
|
npm run server
|
|||
|
|
|
|||
|
|
# Только frontend
|
|||
|
|
npm run client
|
|||
|
|
|
|||
|
|
# Сборка для production
|
|||
|
|
npm run build
|
|||
|
|
|
|||
|
|
# Production запуск
|
|||
|
|
npm start
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Локальное тестирование в Telegram
|
|||
|
|
|
|||
|
|
Telegram требует HTTPS для Mini Apps. Используйте ngrok:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# Установить ngrok
|
|||
|
|
brew install ngrok # macOS
|
|||
|
|
|
|||
|
|
# Запустить туннель
|
|||
|
|
ngrok http 5173
|
|||
|
|
|
|||
|
|
# Скопируйте HTTPS URL и добавьте в BotFather
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Назначение модераторов
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
// Подключиться к MongoDB
|
|||
|
|
mongo nakama
|
|||
|
|
|
|||
|
|
// Назначить роль
|
|||
|
|
db.users.updateOne(
|
|||
|
|
{ telegramId: "YOUR_TELEGRAM_ID" },
|
|||
|
|
{ $set: { role: "moderator" } } // или "admin"
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🚢 Деплой
|
|||
|
|
|
|||
|
|
### Рекомендуемые платформы
|
|||
|
|
|
|||
|
|
- **Backend**: Railway, Render, Heroku
|
|||
|
|
- **Frontend**: Vercel, Netlify
|
|||
|
|
- **MongoDB**: MongoDB Atlas (бесплатный tier)
|
|||
|
|
|
|||
|
|
### Быстрый деплой на Railway
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
npm i -g @railway/cli
|
|||
|
|
railway login
|
|||
|
|
railway init
|
|||
|
|
railway up
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
📖 Подробнее: [SETUP.md - Production деплой](SETUP.md#production-деплой)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🎯 Roadmap
|
|||
|
|
|
|||
|
|
### ✅ Реализовано (v2.0)
|
|||
|
|
- [x] Backend API (Express + MongoDB)
|
|||
|
|
- [x] Frontend React приложение
|
|||
|
|
- [x] Telegram авторизация
|
|||
|
|
- [x] Система постов (CRUD, лайки, комментарии, репосты)
|
|||
|
|
- [x] Теги (Furry, Anime, Other)
|
|||
|
|
- [x] Поиск (e621 + gelbooru)
|
|||
|
|
- [x] Уведомления
|
|||
|
|
- [x] Профили и подписки
|
|||
|
|
- [x] Модерация и жалобы
|
|||
|
|
- [x] Настройки фильтров
|
|||
|
|
- [x] iOS-стиль дизайн
|
|||
|
|
- [x] **Dark mode** - переключатель тем
|
|||
|
|
- [x] **Rate limiting** - защита от спама
|
|||
|
|
- [x] **Redis кэширование** - ускорение API
|
|||
|
|
- [x] **Поиск по постам** - полнотекстовый
|
|||
|
|
- [x] **Хэштеги** - система #тегов
|
|||
|
|
- [x] **Статистика** - просмотры, engagement
|
|||
|
|
- [x] **WebSocket** - real-time уведомления
|
|||
|
|
- [x] **Telegram Stars** - UI готов
|
|||
|
|
|
|||
|
|
### 🔜 В планах (v3.0)
|
|||
|
|
- [ ] Unit и E2E тесты
|
|||
|
|
- [ ] Приватные сообщения (чаты)
|
|||
|
|
- [ ] Группы/сообщества
|
|||
|
|
- [ ] Рекомендательный алгоритм (ML)
|
|||
|
|
- [ ] Мультиязычность (EN/RU/JP)
|
|||
|
|
- [ ] Telegram Mini App Ads
|
|||
|
|
- [ ] Stories функция
|
|||
|
|
- [ ] Voice messages
|
|||
|
|
- [ ] Live streaming
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🤝 Вклад в проект
|
|||
|
|
|
|||
|
|
Мы рады любому вкладу! Смотрите [CONTRIBUTING.md](CONTRIBUTING.md) для деталей.
|
|||
|
|
|
|||
|
|
### Как помочь
|
|||
|
|
1. 🐛 Сообщить о баге через Issues
|
|||
|
|
2. 💡 Предложить новую функцию
|
|||
|
|
3. 🔧 Исправить баг или добавить фичу
|
|||
|
|
4. 📖 Улучшить документацию
|
|||
|
|
5. ⭐ Поставить звезду проекту!
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 📄 Лицензия
|
|||
|
|
|
|||
|
|
MIT License - см. [LICENSE](LICENSE)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 👥 Авторы
|
|||
|
|
|
|||
|
|
Создано с ❤️ для сообщества
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 📞 Поддержка
|
|||
|
|
|
|||
|
|
- 💬 **Issues**: Создайте Issue на GitHub
|
|||
|
|
- 📖 **Документация**: Смотрите [SETUP.md](SETUP.md)
|
|||
|
|
- 🐛 **Баги**: Смотрите [Troubleshooting](SETUP.md#troubleshooting)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 🌟 Благодарности
|
|||
|
|
|
|||
|
|
- [Telegram](https://telegram.org/) за отличную платформу Mini Apps
|
|||
|
|
- [e621](https://e621.net/) за API
|
|||
|
|
- [gelbooru](https://gelbooru.com/) за API
|
|||
|
|
- Сообществу за поддержку и идеи
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
<div align="center">
|
|||
|
|
|
|||
|
|
**[⬆ Наверх](#-nakamaspace---telegram-mini-app)**
|
|||
|
|
|
|||
|
|
Сделано с 🦊 и 🎌
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
|