Imported from Elizaveta2304/ferum_customs_release_final-main (AGENTS.md). Install upstream with npx skills add Elizaveta2304/ferum_customs_release_final-main. Copyright stays with the author.

Руководство для AI Агентов по проекту Ferum Customs

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

1. Обзор и Цель

Проект ferum_customs является кастомным приложением для Frappe/ERPNext, предназначенным для автоматизации работы с сервисными заявками. Ключевая цель — поддерживать высокое качество кода, следовать архитектуре Frappe и обеспечивать полное тестовое покрытие.

2. Основные Технологии и Инструменты

• Фреймворк: Frappe v15, ERPNext v15
• Язык: Python 3.10+
• Качество кода:
  • Форматирование: black
  • Линтинг: ruff
  • Анализ типов: mypy
• Тестирование: pytest
• Оркестрация проверок: pre-commit

3. Процесс Разработки и Тестирования

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

1. Установка зависимостей: Все зависимости для разработки и тестирования находятся в dev-requirements.txt. Установите их командой:

   pip install -r dev-requirements.txt

2. Проверка качества кода: Перед коммитом всегда запускайте полный набор проверок через pre-commit:

   pre-commit run --all-files

   Это автоматически отформатирует код (black) и проверит его на ошибки (ruff, mypy).

3. Запуск тестов: Для выполнения тестов используйте pytest. Тестовая среда настраивается автоматически через фикстуры в ferum_customs/tests/conftest.py, которые создают временный сайт Frappe со всеми установленными приложениями.

   pytest

4. Архитектурные Принципы

• Структура проекта: Следуйте существующей структуре, описанной в README.md.
• Бизнес-логика: Выносите серверную логику и обработчики событий в директорию ferum_customs/custom_logic/ и подключайте их через ferum_customs/hooks.py.
• Миграции БД: Изменения структуры данных, требующие миграции, должны оформляться в виде патчей в директории ferum_customs/patches/.
• API: Публичные серверные методы, доступные с клиента, размещайте в ferum_customs/api.py.

5. Важные Файлы

• setup-environment.sh: Основной скрипт для полного развертывания проекта.
• ferum_customs/tests/conftest.py: Ключевой файл для настройки тестовой среды.
• docs/INSTALL_FULL.md: Подробная пошаговая инструкция по ручной установке.