smart-search-back/CONTRIBUTING.md

Руководство по разработке

Спасибо за участие в разработке Smart Search! Этот документ описывает процесс разработки и правила работы с проектом.

🚨 Обязательные проверки перед коммитом

Перед каждым коммитом ОБЯЗАТЕЛЬНО выполнять в указанном порядке:

1. Unit тесты ✅

cd /Users/vallyenfail/Work/smart-search-back
go test ./internal/service/tests/... -v

Все тесты должны проходить без ошибок.

2. E2E тесты ✅

cd /Users/vallyenfail/Work/e2e-tests
go test -v

Важно: Перед запуском e2e тестов убедитесь, что Docker контейнеры запущены:

cd /Users/vallyenfail/Work
docker-compose up -d

3. Линтер ✅

cd /Users/vallyenfail/Work/smart-search-back
make lint

Линтер должен показывать 0 issues.

Автоматизация

Рекомендуется использовать git pre-commit hook для автоматической проверки. Создайте файл .git/hooks/pre-commit:

#!/bin/sh

echo "🧪 Запуск unit тестов..."
cd /Users/vallyenfail/Work/smart-search-back
go test ./internal/service/tests/... -v
if [ $? -ne 0 ]; then
    echo "❌ Unit тесты провалились"
    exit 1
fi

echo "🧪 Запуск e2e тестов..."
cd /Users/vallyenfail/Work/e2e-tests
go test -v
if [ $? -ne 0 ]; then
    echo "❌ E2E тесты провалились"
    exit 1
fi

echo "🔍 Запуск линтера..."
cd /Users/vallyenfail/Work/smart-search-back
make lint
if [ $? -ne 0 ]; then
    echo "❌ Линтер нашел проблемы"
    exit 1
fi

echo "✅ Все проверки пройдены!"
exit 0

Не забудьте сделать hook исполняемым:

chmod +x .git/hooks/pre-commit

📝 Процесс разработки

1. Создание новой функциональности

1. Создайте новую ветку от main:

   git checkout main
   git pull
   git checkout -b feature/название-фичи
   

2. Внесите изменения в код

3. Напишите/обновите unit тесты для новой функциональности

4. Запустите все проверки (см. раздел "Обязательные проверки")

5. Создайте коммит:

   git add .
   git commit -m "feat: описание новой функциональности"
   

6. Отправьте изменения:

   git push origin feature/название-фичи
   

2. Исправление бага

1. Создайте ветку:

   git checkout -b fix/описание-бага
   

2. Воспроизведите баг в тесте (TDD подход)

3. Исправьте баг

4. Убедитесь, что тест проходит

5. Запустите все проверки

6. Создайте коммит:

   git commit -m "fix: описание исправления"
   

🏗️ Архитектура проекта

smart-search-back/
├── cmd/server/          # Точка входа приложения
├── internal/
│   ├── ai/             # Интеграция с AI сервисами (OpenAI, Perplexity)
│   ├── config/         # Конфигурация приложения
│   ├── database/       # Миграции БД
│   ├── grpc/           # gRPC handlers
│   ├── mocks/          # Автогенерированные моки (minimock)
│   ├── model/          # Доменные модели
│   ├── repository/     # Слой работы с БД
│   │   ├── interfaces.go
│   │   └── *.go
│   ├── service/        # Бизнес-логика
│   │   ├── interfaces.go
│   │   ├── tests/      # Unit тесты сервисов
│   │   └── *.go
│   └── worker/         # Фоновые задачи (cleaners)
├── migrations/         # SQL миграции
└── pkg/               # Переиспользуемые пакеты
    ├── crypto/        # Шифрование и хэширование
    ├── errors/        # Система ошибок
    ├── jwt/           # JWT токены
    └── pb/            # Сгенерированные protobuf файлы

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

Подробнее о тестировании смотрите в TESTING.md.

Быстрые команды

# Unit тесты
go test ./internal/service/tests/... -v

# Unit тесты с покрытием
go test ./internal/service/tests/... -cover

# E2E тесты
cd /Users/vallyenfail/Work/e2e-tests && go test -v

# Линтер
make lint

# Генерация моков
make generate-mock

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

1. Именование

• Интерфейсы: UserService, AuthService (без суффикса Interface)
• Структуры реализации: userService, authService (private)
• Переменные: camelCase для private, PascalCase для public
• Константы: UPPER_CASE или PascalCase для экспортируемых

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

Всегда используйте кастомные ошибки из pkg/errors:

if user == nil {
    return errors.NewBusinessError(errors.UserNotFound, "user not found")
}

if err := db.Query(); err != nil {
    return errors.NewInternalError(errors.DatabaseError, "failed to query", err)
}

3. Context

• Context всегда первый параметр
• Context создается только один раз в main.go
• Пробрасывается через все слои: main → worker → handler → service → repository

func (s *userService) GetUser(ctx context.Context, userID int) (*model.User, error) {
    return s.userRepo.FindByID(ctx, userID)
}

4. Закрытие ресурсов

Всегда проверяйте ошибки при закрытии ресурсов:

// ❌ Плохо
defer file.Close()

// ✅ Хорошо
defer func() { _ = file.Close() }()

// ✅ Если нужна обработка
defer func() {
    if err := file.Close(); err != nil {
        log.Printf("failed to close file: %v", err)
    }
}()

🔧 Работа с базой данных

Миграции

Миграции находятся в migrations/ и нумеруются последовательно:

migrations/
├── 00001_create_users.sql
├── 00002_create_sessions.sql
└── 00003_create_invite_codes.sql

Для создания новой миграции:

# Формат: 0000X_название_миграции.sql
touch migrations/00008_add_new_table.sql

Миграции применяются автоматически при запуске приложения через goose.

🐳 Docker и локальная разработка

Запуск всех сервисов

cd /Users/vallyenfail/Work
docker-compose up -d

Просмотр логов

# Backend
docker logs smart-search-back --tail 50 -f

# Gateway
docker logs smart-search-gateway --tail 50 -f

# PostgreSQL
docker logs smart-search-postgres --tail 50 -f

Пересборка после изменений

cd /Users/vallyenfail/Work
docker-compose down
docker-compose up -d --build

Подключение к БД

docker exec -it smart-search-postgres psql -U postgres -d b2b_search

🔄 Git Flow

Ветки

• main - основная стабильная ветка
• feature/* - новая функциональность
• fix/* - исправления багов
• refactor/* - рефакторинг без изменения функциональности

Commit Messages

Используйте conventional commits:

• feat: - новая функциональность
• fix: - исправление бага
• refactor: - рефакторинг кода
• test: - добавление/изменение тестов
• docs: - документация
• chore: - рутинные задачи (обновление зависимостей и т.д.)

Примеры:

feat: добавлена функция экспорта поставщиков в Excel
fix: исправлена ошибка при валидации токена
refactor: упрощена логика создания сессии
test: добавлены тесты для InviteService
docs: обновлена документация по тестированию

📚 Дополнительная документация

• TESTING.md - подробное руководство по тестированию
• GRPC_SERVICES.md - описание gRPC сервисов
• DEPLOYMENT.md - инструкции по деплою
• README.md - общая информация о проекте

🆘 Помощь

Если у вас возникли вопросы или проблемы:

1. Проверьте документацию в репозитории
2. Убедитесь, что все зависимости установлены
3. Проверьте, что Docker контейнеры запущены
4. Убедитесь, что используете правильные версии Go (1.21+) и зависимостей

⚡ Чеклист перед коммитом

• Код проходит линтер (make lint)
• Все unit тесты проходят
• Все e2e тесты проходят
• Добавлены/обновлены тесты для нового кода
• Документация обновлена (если нужно)
• Commit message следует conventional commits
• Нет закомментированного кода
• Нет debug логов
• Секреты не попали в репозиторий

---

Важно: Соблюдение этих правил обеспечивает качество кода и стабильность проекта. Спасибо за вклад! 🚀