Smart-search/smart-search-back

Fork 0

Files

vallyenfail e2968722ed

Deploy Smart Search Backend / deploy (push) Failing after 1m54s

Details

add service

2026-01-17 20:41:37 +03:00

10 KiB

Raw Blame History

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

Спасибо за участие в разработке 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. Создание новой функциональности

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

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

Внесите изменения в код
Напишите/обновите unit тесты для новой функциональности
Запустите все проверки (см. раздел "Обязательные проверки")

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

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

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

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

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

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

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

Воспроизведите баг в тесте (TDD подход)
Исправьте баг
Убедитесь, что тест проходит
Запустите все проверки

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

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 - общая информация о проекте

🆘 Помощь

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

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

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

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

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

10 KiB Raw Blame History Unescape Escape