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

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

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

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

### 1. Unit тесты ✅
```bash
cd /Users/vallyenfail/Work/smart-search-back
go test ./internal/service/tests/... -v
```

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

### 2. E2E тесты ✅
```bash
cd /Users/vallyenfail/Work/e2e-tests
go test -v
```

**Важно**: Перед запуском e2e тестов убедитесь, что Docker контейнеры запущены:
```bash
cd /Users/vallyenfail/Work
docker-compose up -d
```

### 3. Линтер ✅
```bash
cd /Users/vallyenfail/Work/smart-search-back
make lint
```

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

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

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

```bash
#!/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 исполняемым:
```bash
chmod +x .git/hooks/pre-commit
```

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

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

1. Создайте новую ветку от `main`:
   ```bash
   git checkout main
   git pull
   git checkout -b feature/название-фичи
   ```

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

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

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

5. Создайте коммит:
   ```bash
   git add .
   git commit -m "feat: описание новой функциональности"
   ```

6. Отправьте изменения:
   ```bash
   git push origin feature/название-фичи
   ```

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

1. Создайте ветку:
   ```bash
   git checkout -b fix/описание-бага
   ```

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

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

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

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

6. Создайте коммит:
   ```bash
   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](./TESTING.md).

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

```bash
# 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`:

```go
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`

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

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

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

```go
// ❌ Плохо
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
```

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

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

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

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

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

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

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

```bash
# 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
```

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

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

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

```bash
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](./TESTING.md) - подробное руководство по тестированию
- [GRPC_SERVICES.md](./GRPC_SERVICES.md) - описание gRPC сервисов
- [DEPLOYMENT.md](./DEPLOYMENT.md) - инструкции по деплою
- [README.md](./README.md) - общая информация о проекте

## 🆘 Помощь

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

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

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

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

---

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