ATOM ДОБРО

Версия: 2.0.0

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

Описание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• 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 - система уведомлений
• Emoji Picker React - выбор эмодзи для организаций и квестов

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

• React Joyride - интерактивные туры по интерфейсу
• Next Themes - управление темами оформления

Тестирование

• Vitest - быстрый unit-тест фреймворк
• React Testing Library - тестирование React компонентов
• MSW (Mock Service Worker) - мокирование HTTP запросов для интеграционных тестов
• @testing-library/jest-dom - дополнительные матчеры для DOM

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

Требования

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

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

pnpm install

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

pnpm dev

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

Сборка для production

pnpm build

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

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

pnpm preview

Линтинг кода

pnpm lint

Тестирование

Запуск всех тестов:

pnpm test

Запуск тестов с UI интерфейсом:

pnpm test:ui

Запуск тестов с покрытием кода:

pnpm test:coverage

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

src/
  components/          - React компоненты
    forms/            - Компоненты форм (регистрация, вход, создание организаций и квестов)
    header/           - Компонент шапки сайта
    home/             - Компоненты главной страницы (Hero, About, Features и т.д.)
    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/          - Константы приложения
  data/               - Статические данные (достижения и т.д.)
  lib/                - Библиотечные функции
  provider/           - Провайдеры (ProtectedRoute)
  pwa/                - Конфигурация Progressive Web App (компоненты и хуки)
  styles/             - Глобальные стили
  tests/              - Тесты приложения
    unit/            - Unit тесты
    integration/     - Интеграционные тесты

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

• / - Главная страница с описанием платформы
• /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 визуально помечаются как находящиеся на модерации.

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

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

Тестирование

Проект включает комплексную систему тестирования:

• Unit тесты - тестирование отдельных компонентов и утилит
• Интеграционные тесты - тестирование взаимодействия компонентов и API
• MSW (Mock Service Worker) - мокирование HTTP запросов для изоляции тестов
• React Testing Library - тестирование компонентов с фокусом на пользовательский опыт
• Vitest - быстрый тест раннер с поддержкой TypeScript

Тесты расположены в директории src/tests/ и автоматически запускаются в CI/CD.

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

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

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

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

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

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

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

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

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

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

• Алиасы путей для импортов (@/ для src/)
• Оптимизацию сборки с разделением на чанки (vendor chunks)
• Настройки file-based routing через w2b-vite-filebased-routing
• Конфигурацию Vitest для тестирования
• SEO оптимизацию с генерацией sitemap и метаданных

Разработка

Структура файлов

Проект использует file-based routing - страницы создаются как файлы в директории src/pages/. Роутинг обрабатывается автоматически через w2b-vite-filebased-routing.

Code style

• Используется ESLint для проверки кода
• TypeScript строгий режим
• Prettier для форматирования (если настроен)

Коммиты

Рекомендуется использовать conventional commits для описания изменений.

Лицензия

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