Участие в разработке

Спасибо за интерес к участию в разработке Elftia. В этом документе описан полный рабочий процесс для участия в разработке.

---

Настройка среды разработки

Подробные шаги описаны в руководстве Локальная разработка. Краткая сводка:

{/* Prerequisites */}
{/* Node.js v24 (see .nvmrc) + native build tools */}

git clone <repo-url> elftia
cd elftia
npm install
cp .env.example .env
npm run dev

---

Стратегия ветвления

Ветка	Назначение	Правила защиты
main	Стабильный релиз, всегда готов к выпуску	Требует PR + ревью
dev/*	Ветки разработки функций	-
fix/*	Ветки исправления ошибок	-

Именование веток

{/* New feature */}
git checkout -b dev/feature-name

{/* Bug fix */}
git checkout -b fix/bug-description

{/* Examples */}
git checkout -b dev/notes-feature
git checkout -b fix/chat-scroll-issue

---

Стандарты кода

Полная спецификация описана в разделе Стандарты кода. Ключевые моменты:

ESLint

• Правила уровня error блокируют коммиты (порядок импортов, no-var, eqeqeq, prefer-const, правила хуков)
• Правила уровня warn позволяют совершать коммиты, но рекомендуется их исправлять
• Husky автоматически запускает eslint --fix перед коммитами

Размер файлов

Тип файла	Рекомендуемый лимит	Жёсткий лимит
React-компоненты	400 строк	800 строк
Пользовательские хуки	300 строк	600 строк
Вспомогательные функции	150 строк	300 строк
Определения типов	100 строк	200 строк
Сервисы	300 строк	600 строк

Именование

• Компоненты: PascalCase (UserMessage.tsx)
• Хуки: usePascalCase (useChatActions.ts)
• Директории: kebab-case (chat-messages/)
• Семантические токены (без хардкода цветов)

---

Соглашение о коммитах

Используйте формат Conventional Commits:

<type>: <description>

[optional body]

[optional footer]

Справочник типов

Тип	Описание	Пример
feat	Новая функция	feat: add notes export feature
fix	Исправление ошибки	fix: resolve chat scroll position reset
refactor	Рефакторинг	refactor: split ChatInterface into smaller components
docs	Документация	docs: update IPC channels reference
style	Форматирование кода (без изменения логики)	style: fix import ordering
test	Тесты	test: add unit tests for useFavorites
chore	Изменения сборки/инструментов	chore: update Vite to v7.1

Пример

git commit -m "feat: add favorites feature with session-scoped bookmarks

- Add FavoritesService with SQLite persistence
- Add FavoritesRouter with Zod validation
- Add useFavorites hook and FavoritesList component
- Add i18n support for en/zh/ja"

---

Требования к Pull Request

Основные принципы

• Один PR — одно изменение — не смешивайте разработку функций с исправлением ошибок
• Тесты — новые функции должны включать тесты
• Документация — обновляйте документацию при необходимости
• Прохождение CI — все проверки должны пройти успешно

Заголовок PR

Кратко опишите изменение в формате Conventional Commits:

feat: add favorites feature
fix: resolve chat message duplication
refactor: extract message rendering into separate components

Шаблон описания PR

## Changes
- Brief description of change 1
- Brief description of change 2

## How to Test
- [ ] Manual test step 1
- [ ] Manual test step 2
- [ ] Unit tests pass

## Screenshots (if UI changes)

---

Чеклист разработки новой функции

Полный сквозной процесс описан в руководстве Добавление функции.

Бэкенд

Шаг	Расположение файла	Описание
1. Общие типы	packages/desktop/app/shared/contracts/	Определения типов, общих для фронтенда и бэкенда
2. Сервис	packages/desktop/app/main/services/	Инкапсуляция бизнес-логики
3. Роутер	packages/desktop/app/main/services/routers/	IPC-роутинг + валидация Zod
4. Регистрация	routers/index.ts → registerAllRouters()	Создание экземпляра и регистрация
5. Preload	packages/desktop/app/preload/index.ts	Предоставление доступа фронтенду

Фронтенд

Шаг	Расположение файла	Описание
1. Хук	packages/renderer/src/features/<feature>/hooks/ (хуки общего назначения — в shared/hooks/)	Получение данных и управление состоянием
2. Компонент	packages/renderer/src/features/<feature>/components/ (общий UI — в components/ui/)	Рендеринг UI
3. Маршрут	app/lazy/ (pages.tsx и др.) + app/App.tsx	Новые страницы требуют регистрации с ленивой загрузкой (устаревший путь импорта from '../lazy' через barrel lazy/index.ts по-прежнему совместим)
4. i18n	packages/renderer/src/locales/{en,zh,ja}/	Переводы на три языка

Документация

Условие	Требует обновления
Добавлен новый модуль	.claude/skills/architecture-index/SKILL.md
Видимая пользователю функция	База знаний docs/elfi-kb/
Добавлен новый маршрут	Таблица маппинга docs/elfi-kb/INDEX.md

---

Фокус при ревью кода

Разделение фронтенда и бэкенда

• Передаёт ли фронтенд только пользовательский ввод и параметры конфигурации?
• Обрабатывает ли бэкенд все внешние вызовы?
• Возвращаются ли данные уже в окончательном виде?
• Исключена ли передача больших данных (например, base64) через IPC?

Безопасность

• Валидируются ли параметры роутера с помощью Zod?
• Используются ли API-ключи только в главном процессе?
• Отсутствуют ли потенциальные риски XSS?

Размер файлов

• Укладывается ли новый файл в рекомендуемый лимит?
• Превышает ли изменённый файл порог предупреждения?
• Нужно ли его разделить?

Обработка ошибок

• Есть ли try-catch для сетевых запросов?
• Дружественны ли сообщения об ошибках для пользователя?
• Реализованы ли состояния загрузки и пустого списка?

Документация

• Обновлён ли индекс архитектуры?
• Обновлена ли база знаний?
• Синхронизированы ли все три языка i18n?

---

Отчёты об ошибках

Шаблон отчёта

## Environment
- OS: Windows 11 / macOS 15 / Ubuntu 24
- Elftia version: v0.5.0
- Node.js version: v24.x

## Steps to Reproduce
1. Open the settings page
2. Switch to the "Appearance" tab
3. Click on wallpaper settings
4. After selecting an image...

## Expected Behavior
The wallpaper should display normally.

## Actual Behavior
The wallpaper does not display; console error: TypeError: Cannot read property 'path' of undefined

## Additional Information
- Diagnostic data export (Settings → Advanced → Export Diagnostic Data)
- Screenshots or screen recordings
- Console error logs

Экспорт диагностических данных

Экспортируйте диагностические данные из приложения для помощи в устранении неполадок:

Settings → Advanced → Diagnostic Tools → Export Diagnostic Data

Или через консоль DevTools:

const data = await window.api.diagnostics.bundle({ includeLogs: true });

---

Контакты

• Issues проекта — запросы функций и отчёты об ошибках
• Pull Requests — вклад в код
• Discussions — технические обсуждения и вопросы