team-planner/DEVELOPMENT.md

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

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

---

Инструменты

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 в корне проекта.

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

Настройка Backend

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

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

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

Проверка:

curl http://localhost:3000/health
# {"status":"ok","service":"ai-proxy-service","version":"0.0.1",...}

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

---

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

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

# Проверка статуса приложения
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:

// 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. Переходит к следующему этапу