# Правила локальной разработки

> **Обязательно к прочтению перед началом работы!**

---

## Инструменты

### MCP серверы
- **Serena** — для работы с кодом (символьная навигация, редактирование)
- **Context7** — для получения актуальной документации по библиотекам

Используй эти инструменты для эффективной работы с кодовой базой.

---

## Локальное окружение

### Порты
| Сервис | Порт | Описание |
|--------|------|----------|
| Frontend (React) | 4000 | Vite dev server |
| Backend (NestJS) | 4001 | NestJS API |
| PostgreSQL | 5432 | Docker container |
| AI Proxy (туннель) | 3000 | SSH туннель к K8s |

### База данных
PostgreSQL поднимается в Docker. Файл `docker-compose.yml` в корне проекта.

```bash
# Запуск БД
docker-compose up -d postgres
```

### Настройка Backend

Создай файл `backend/.env`:

```bash
# Database
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=teamplanner
DB_PASSWORD=teamplanner
DB_DATABASE=teamplanner

# Keycloak
KEYCLOAK_REALM_URL=https://auth.vigdorov.ru/realms/team-planner

# AI Proxy (для Фазы 3)
AI_PROXY_BASE_URL=http://localhost:3000
AI_PROXY_API_KEY=<your-ai-proxy-api-key>
```

### AI Proxy — port-forward

Для локальной работы с AI Proxy нужен port-forward:

```bash
# Запуск port-forward (в отдельном терминале или в фоне)
kubectl port-forward svc/ai-proxy-service 3000:3000 -n ai-proxy
```

Проверка:
```bash
curl http://localhost:3000/health
# {"status":"ok","service":"ai-proxy-service","version":"0.0.1",...}
```

**Примечание:** kubectl настроен для доступа к production кластеру.

---

## Работа с Production кластером

kubectl настроен для доступа к production кластеру:

```bash
# Проверка статуса приложения
kubectl get pods -n team-planner

# Просмотр логов
kubectl logs -f deployment/team-planner-backend -n team-planner

# Проверка AI Proxy
kubectl get pods -n ai-proxy
kubectl logs -f deployment/ai-proxy-service -n ai-proxy
```

**⚠️ Внимание:** Будьте осторожны при работе с production окружением!

---

## Правила работы

### 1. Никогда не запускай сервисы самостоятельно

**ЗАПРЕЩЕНО** запускать `npm run dev`, `npm start` и подобные команды.

**Вместо этого:**
1. Убедись, что команда запуска есть в `package.json`
2. Если команды нет — создай её
3. Попроси пользователя запустить:

```
Запусти, пожалуйста:
cd backend && npm run dev
```

### 2. Тестирование — только ручное

После завершения задачи:
1. Опиши сценарии для проверки
2. Попроси пользователя проверить вручную
3. Дождись фидбека

**Формат:**
```
Готово! Проверь, пожалуйста:

1. Открой http://localhost:4000
2. Нажми кнопку "Создать идею"
3. Заполни форму и сохрани
4. Убедись, что идея появилась в списке

Напиши, если что-то не работает.
```

### 3. Работа поэтапно

Делай работу **небольшими итерациями**:

1. **Один этап = одна логическая единица**
   - Один endpoint
   - Один компонент
   - Одна фича

2. **После каждого этапа:**
   - Сообщи что сделано
   - Дай сценарий проверки
   - Дождись подтверждения

3. **Не делай сразу много:**
   - ❌ Весь CRUD за раз
   - ✅ Сначала GET, проверили, потом POST, проверили...

### 4. Команды в package.json

Все команды запуска должны быть в `package.json`:

```json
// backend/package.json
{
  "scripts": {
    "dev": "nest start --watch",
    "build": "nest build",
    "start:prod": "node dist/main"
  }
}

// frontend/package.json
{
  "scripts": {
    "dev": "vite --port 4000",
    "build": "vite build",
    "preview": "vite preview"
  }
}
```

---

## Чеклист перед началом работы

- [ ] Прочитал CONTEXT.md
- [ ] Прочитал ROADMAP.md (понял текущую фазу)
- [ ] Понял задачу
- [ ] Готов работать поэтапно
- [ ] Помню: не запускаю сервисы сам, прошу пользователя

---

## Пример правильного workflow

```
Пользователь: Сделай endpoint для получения списка идей

Агент:
1. Читает документацию через Context7 (NestJS, TypeORM)
2. Использует Serena для навигации по коду
3. Создаёт endpoint GET /api/ideas
4. Сообщает:

   "Создал endpoint GET /api/ideas.

   Запусти backend:
   cd backend && npm run dev

   Проверь:
   curl http://localhost:4001/api/ideas

   Должен вернуться пустой массив: { data: [], meta: {...} }"

5. Ждёт фидбек
6. Переходит к следующему этапу
```