ATOM ДОБРО

Веб-приложение для управления волонтерскими организациями и квестами на интерактивной карте атомных городов.

Описание

ATOM ДОБРО представляет собой единую платформу для волонтеров, организаций и всех участников благотворительной деятельности. Приложение обеспечивает визуализацию волонтерских организаций и квестов на интерактивной карте, управление профилями пользователей, систему достижений и геймификацию участия в социальных проектах.

Основной функционал

Управление организациями

• Просмотр волонтерских организаций на интерактивной карте
• Добавление новых организаций с указанием местоположения, контактов и описания
• Редактирование информации об организациях
• Фильтрация организаций по городам, типам помощи и направлениям деятельности
• Просмотр списка собственных организаций в профиле пользователя
• Модерация организаций с визуальным отображением статуса

Управление квестами

• Создание квестов с многоэтапной структурой
• Определение требований для этапов квеста: финансовые средства, волонтеры, материалы
• Управление прогрессом выполнения квестов
• Отслеживание участия пользователей в квестах
• Система QR-кодов для регистрации участия
• Архивация и завершение квестов

Профиль пользователя

• Просмотр статистики участия в квестах и организациях
• Система уровней и опыта
• Достижения и награды
• История участия в проектах
• Управление активными квестами

Аутентификация и авторизация

• Регистрация новых пользователей
• Вход в систему
• Восстановление пароля
• Защищенные маршруты для авторизованных пользователей

Интерактивная карта

• Отображение организаций и квестов на карте
• Кластеризация маркеров для оптимизации отображения
• Фильтрация по различным критериям
• Детальная информация об объектах на карте

Технологический стек

Основные технологии

• React 19 - библиотека для построения пользовательского интерфейса
• TypeScript - типизированный язык программирования
• Vite - инструмент сборки и разработки
• React Router - маршрутизация на основе файловой структуры (file-based routing)

Управление состоянием

• Redux Toolkit - управление глобальным состоянием приложения
• RTK Query - работа с API и кэширование данных
• Redux Persist - сохранение состояния в локальном хранилище

Картография

• Leaflet - библиотека для работы с интерактивными картами
• React Leaflet - React-компоненты для Leaflet
• Leaflet MarkerCluster - кластеризация маркеров на карте

Стилизация

• Tailwind CSS - утилитарный CSS-фреймворк
• Tailwind Animate CSS - анимации

Формы и валидация

• React Hook Form - управление формами
• Zod - схема валидации данных
• Hookform Resolvers - интеграция Zod с React Hook Form

UI компоненты

• Shadcn UI - доступные компоненты интерфейса
• Lucide React - библиотека иконок
• Sonner - система уведомлений

Дополнительные библиотеки

• React Joyride - интерактивные туры по интерфейсу
• Next Themes - управление темами оформления
• Vite PWA - поддержка Progressive Web App
• W2B File based routing - кастомная библиотека для роутинга

Установка и запуск

Требования

• Node.js версии 18 или выше
• pnpm менеджер пакетов

Установка зависимостей

pnpm install

Запуск в режиме разработки

pnpm dev

Приложение будет доступно по адресу http://localhost:5173

Сборка для production

pnpm build

Собранные файлы будут находиться в директории dist

Предпросмотр production сборки

pnpm preview

Линтинг кода

pnpm lint

Структура проекта

src/
  components/          - React компоненты
    forms/            - Компоненты форм (регистрация, вход, создание организаций и квестов)
    header/           - Компонент шапки сайта
    manage/           - Компоненты управления квестами и организациями
    map/              - Компоненты для работы с картой
    profile/          - Компоненты профиля пользователя
    support/          - Компоненты поддержки
    tour/             - Компоненты интерактивных туров
    ui/               - Переиспользуемые UI компоненты
  pages/              - Страницы приложения (file-based routing)
    (auth)/          - Страницы аутентификации
    (header)/        - Страницы с шапкой
    (manage)/        - Страницы управления
  store/              - Redux store и сервисы
    entities/        - RTK Query сервисы для работы с API
    hooks/           - Redux хуки
  hooks/              - Кастомные React хуки
  contexts/           - React контексты
  utils/              - Утилитарные функции
  types/              - TypeScript типы и интерфейсы
  constants/          - Константы приложения
  lib/                - Библиотечные функции
  provider/           - Провайдеры (ProtectedRoute)
  pwa/                - Конфигурация Progressive Web App
  styles/             - Глобальные стили

Основные маршруты

• / - Главная страница с описанием платформы
• /map - Интерактивная карта с организациями и квестами
• /login - Страница входа в систему
• /registration - Страница регистрации нового пользователя
• /forgot-password - Восстановление пароля
• /reset-password - Сброс пароля
• /profile - Профиль пользователя
• /add-organization - Форма добавления организации
• /add-quest - Форма создания квеста
• /organizations/:id/manage - Управление организацией
• /quests/:id/manage - Управление квестом
• /support - Страница поддержки

API интеграция

Приложение взаимодействует с REST API для следующих операций:

• Аутентификация и авторизация пользователей
• Управление организациями (создание, чтение, обновление, удаление)
• Управление квестами (создание, чтение, обновление, удаление)
• Управление обновлениями организаций
• Получение списка участников квестов
• Управление требованиями этапов квестов
• Получение статистики пользователя

Все запросы к API обрабатываются через RTK Query с автоматическим кэшированием и инвалидацией данных.

Особенности реализации

Управление требованиями квестов

Квесты поддерживают три типа требований для этапов:

• Финансовые средства (finance)
• Волонтеры (contributers)
• Материалы и предметы (material)

Тип требования определяется на уровне этапа квеста и передается в API при создании или обновлении.

Модерация организаций

Организации проходят процесс модерации перед публикацией. Организации со статусом isApproved: false визуально помечаются как находящиеся на модерации.

Система достижений

Пользователи получают достижения за участие в квестах и организациях. Система уровней основана на накопленном опыте.

Progressive Web App

Приложение поддерживает установку как PWA с возможностью работы в офлайн-режиме через Service Worker.

Развертывание

Для развертывания приложения используется Docker. Подробные инструкции по развертыванию находятся в файле DEPLOY.md.

Основные шаги развертывания

1. Создание Docker сети
2. Настройка переменных окружения
3. Сборка и запуск контейнеров
4. Выполнение миграций базы данных
5. Настройка reverse proxy (опционально)

Конфигурация

Переменные окружения

Приложение использует переменные окружения для настройки подключения к API. Основные переменные:

• VITE_API_URL - базовый URL API сервера

Конфигурация Vite

Конфигурация сборки находится в файле vite.config.ts. Настройки включают:

• Алиасы путей для импортов
• Оптимизацию сборки с разделением на чанки
• Конфигурацию PWA
• Настройки file-based routing

Лицензия

Проект разработан в рамках хакатона командой w2b.