vigdorov
dea0676169
Some checks reported errors
continuous-integration/drone/push Build encountered an error
207 lines
5.7 KiB
Markdown
207 lines
5.7 KiB
Markdown
# Правила локальной разработки
|
||
|
||
> **Обязательно к прочтению перед началом работы!**
|
||
|
||
---
|
||
|
||
## Инструменты
|
||
|
||
### 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. Переходит к следующему этапу
|
||
```
|