This commit is contained in:
vallyenfail
347
CONTRIBUTING.md
Normal file
347
CONTRIBUTING.md
Normal file
@@ -0,0 +1,347 @@
|
||||
# Руководство по разработке
|
||||
|
||||
Спасибо за участие в разработке 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 логов
|
||||
- [ ] Секреты не попали в репозиторий
|
||||
|
||||
---
|
||||
|
||||
**Важно**: Соблюдение этих правил обеспечивает качество кода и стабильность проекта. Спасибо за вклад! 🚀
|
||||
Reference in New Issue
Block a user