348 lines
10 KiB
Markdown
348 lines
10 KiB
Markdown
# Руководство по разработке
|
||
|
||
Спасибо за участие в разработке 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 логов
|
||
- [ ] Секреты не попали в репозиторий
|
||
|
||
---
|
||
|
||
**Важно**: Соблюдение этих правил обеспечивает качество кода и стабильность проекта. Спасибо за вклад! 🚀
|