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>
|
||
|