Общее описание проекта и процесса разработки

Rubas

Аннотация

Приводится детальное описание проекта и его ключевых (технологических) особенностей, а также особенностей процесса разработки.

Общие сведения

RUBAS WEB3 APPLICATION представляет собой приложение, обеспечивающее дружественный пользовательский интерфейс для взаимодействия со смарт-контрактами экосистемы RUBAS (см. myrubas), а также для отслеживания некоторых статистических показателей в виде таблиц и диаграмм. Подписание транзакций осуществляется через MetaMask.

Приложение имеет две языковые версии: русскоязычную и англоязычную.

Технологические сведения

Стек используемых библиотек и фреймворков

В проекте используется стек - Ant Design (UI) + Icons, wagmi + viem (Web3), zustand (стейт), i18next + react-i18next (i18n), loglevel (логирование), а также дополнительные утилиты для удобства разработки:

UI: реализован на основе Ant Design + Icons с использованием Emotion для CSS-in-JS стилизации, что позволяет обеспечить единый стиль, поддержку тем и гибкую кастомизацию компонентов.

Web3: реализуется через связку wagmi + viem, предоставляющую удобные React-хуки для работы с кошельками, контрактами, сетями и подписанием транзакций.

Управление состоянием: zustand - минималистичный state-менеджер для хранения пользовательских данных, состояния кошелька и UI-состояния, дополненный хуком use-sync-external-store для стабильных подписок.

Интернационализация: i18next + react-i18next с использованием i18next-browser-languagedetector для автоматического определения языка пользователя.

Логирование: loglevel - легковесное и настраиваемое решение для логирования, подходящее для приложений любого масштаба.

Дополнительные утилиты: markdown-to-jsx для преобразования markdown в React-компоненты, react-textarea-autosize для автозаполняющихся текстовых полей, react-use - коллекция полезных React хуков.

Конкретные версии представлены в следующей таблице:

Категория	Технологии	Пакеты (версии)
UI Framework	Ant Design + Icons, Emotion	antd (5.24.9), @ant-design/icons (6.0.0), @emotion/react (11.14.0), @emotion/styled (11.14.0)
Web3	Wagmi + Viem	wagmi (2.15.2), viem (2.28.4)
State Management	Zustand	zustand (5.0.4), use-sync-external-store (1.5.0)
i18n	i18next + React Integration	i18next (25.0.2), react-i18next (15.5.1), i18next-browser-languagedetector (8.1.0)
Utilities	React Hooks, Markdown, UI Helpers	react-use (17.6.0), markdown-to-jsx (7.7.6), react-textarea-autosize (8.5.9)
Логирование	loglevel	loglevel (1.9.2)
React Core	React 19	react (19.1.0), react-dom (19.1.0)

Стек инструментов разработки

Категория	Инструменты / Конфигурации
Bundler	Vite (6.3.5) с плагином @vitejs/plugin-react (4.4.1)
Linting	ESLint (9.26.0) с плагинами:
	- @typescript-eslint/eslint-plugin (8.32.0), @typescript-eslint/parser (8.32.0)
	- eslint-plugin-import (2.31.0)
	- eslint-plugin-prettier (5.4.0), eslint-config-prettier (10.1.3)
	- eslint-plugin-react-hooks (5.2.0)
	- eslint-plugin-react-refresh (0.4.19)
	- eslint-plugin-simple-import-sort (12.1.1)
	- eslint-plugin-storybook (0.12.0)
Форматирование кода	Prettier (3.5.3) с интеграцией в ESLint
Type Checking	TypeScript (5.8.3), @types/react (19.1.2), @types/react-dom (19.1.2)
Тестирование	- Vitest (3.1.3) с дополнениями: @vitest/browser (3.1.3), @vitest/coverage-v8 (3.1.3)
	- Playwright (1.52.0) для E2E-тестирования
	- jsdom (26.1.0) для эмуляции DOM в тестах
Component Development	Storybook (8.6.12) с набором аддонов:
	- Документирование: @storybook/addon-docs (8.6.12), react-docgen-typescript (2.2.2)
	- Разработка: @storybook/addon-actions (8.6.12), @storybook/addon-console (3.0.0)
	- Тестирование: @storybook/experimental-addon-test (8.6.12), @storybook/test-runner (0.22.0)
Стилизация	sass (1.87.0)
Node.js	v22.13.1

Разрабатываемые компоненты могут быть проверены визуально и протестированы через Storybook.

Требования к процессу разработки

Общие требования заключаются в том, чтобы обеспечивать модульность, слабую связанность и "чистую" архитектуру, а также поддерживаемость, тестируемость и расширяемость кода.

При написании нового кода необходимо следовать этим рекомендациям:

1. Применять подход «атомарного дизайна» (Atomic Design): atoms → molecules → organisms.
2. Учитывать разбиение на папки:
   • assets/ — общие файлы (статика).
   • components/ — визуальные компоненты (атомы, молекулы, организмы).
   • constants/ — общие константы проекта (глобальные).
   • hooks/ — бизнес-логика в виде хуков (useWallet, useTokenBalance).
   • locales/ — языковые локализации (en, ru).
   • services/ — сервисные, вспомогательные функции.
   • stores/ — хранение и распространение глобального состояния.
3. Соблюдать следующие правила:
   • UI-компоненты должны поддерживать:
     • собственные (модульные) стили в форме scss;
     • локализацию через i18n;
     • логирование;
     • каждый UI-компонент должен иметь набор историй с тестами для Storybook.
   • При этом бизнес-логика должна быть вынесена из UI-компонентов (ее следует описывать в виде хуков, которые компонент принимает в числе прочих пропсов).
   • Код компонентов должен быть документирован в стиле JSDoc. Кроме того, первая строка всегда должна содержать однострочный комментарий, который должен быть использован при суммаризации проекта (в этом комментарии очень кратко должна передаваться основная суть). Опционально: по тексту компонента можно добавлять краткие комментарии, если это будет способствовать лучшему пониманию кода.
   • Следует использовать args для передачи пропсов ("пробрасывать" пропсы).
   • Все пропсы и/или параметры должны быть описаны в JSDocs ().
   • Следует всегда прямо и явно указывать все типы (для пропсов, для компонентов и т.д.).
   • Каждый UI-компонент должен быть снабжен историей для Stroybook и минимальным набором тестов (файл *.stories.tsx должен быть в той же папке, что и сам компонент).

Система оценки готовности кода

Код оценивается в виде звезд. Оценка выставляется в однострочном комментарии (в квадратных скобках).

• ☆☆☆☆☆ — первый вариант кода, к которому предъявляется только требование: работоспособность
• ★☆☆☆☆ — работоспособный код + комментарии: однострочный, JSDoc, и опционально - минимальные комментарии по тексту
• ★★☆☆☆ — всё перечисленное + отсутствуют замечания со стороны линтера
• ★★★☆☆ — всё перечисленное + оптимизированы и упорядочены импорты
• ★★★★☆ — всё перечисленное + выполнено ревью кода (внесены исправления и улучшения)
• ★★★★★ — всё перечисленное + имеются истории для Сторибука и тесты

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

В связи с тем, что разработка ведется силам одного специалиста, ветвление с использованием фича-веток представляется избыточным.

Вместо этого работа должна вестись всего в двух ветках: master (основной более-менее стабильный код) и dev (текущая разработка).

Этап	Действие
Разработка	В ветке dev, с осмысленными коммитами (см. ниже)
Код-ревью	Через Pull Request из dev в master
Слияние	После ревью, merge ветки dev → master

То есть, перед слиянием должны осуществляться код-ревью (с последующим вероятным рефакторингом).

Комментарии к коммитам должны иметь формат:

[ttp-NNNNNN], где

• ttp - task type (см. ниже);
• NNNNNN - номер задачи (с ведущими нулями)

Типы задач (и соответствующие префиксы):

• [ftr] feature/ - добавление нового функционала (вплоть до уровня ревью);
• [tst] testing/ - ручное (визуальное) тестирование;
• [ref] refactoring/ - модернизация, направленная на улучшение чистоты кода и применение лучших практик;
• [bfx] bugfix/ - исправление обнаруженной ошибки;
• [dcs] docs/ - работа над документацией (в коде и в файле README);
• [chr] chore/ - прочие (технологические, рутинные и т.д.) изменения, не влияющие на функционал.

📌 Пример рабочего цикла

• Переключиться на dev:

git checkout dev

• Выполнить изменения, выполнить коммит:

git add auth.js
git commit -m "[ftr-00012] Добавлен модуль для новой фичи"

• Запушить изменения:

git push master dev

• Создать Pull Request в GitHub:

From: dev
To: master
Название: ftr-00012: Модуль для новой фичи
Описание: Добавлен базовый функционал новой фичи. Обновлены файлы локализации

• Выполнить код-ревью, внести правки при необходимости.
• Выполнить слияние dev → master.