457 lines
17 KiB
Markdown
457 lines
17 KiB
Markdown
# TMC Test Task — Claude Code Prompt
|
||
|
||
> Запусти этот промт из корня проекта (например `~/projects/dev-landing`)
|
||
|
||
---
|
||
|
||
## Цель
|
||
|
||
Создать fullstack-приложение: **backend API на NestJS** + **лендинг на Nuxt 3**.
|
||
Монорепозиторий с двумя папками: `backend/` и `frontend/`.
|
||
Работай итеративно: сначала scaffold → потом реализация по фичам. Не переходи к следующему шагу, пока текущий не работает.
|
||
|
||
---
|
||
|
||
## Структура репозитория
|
||
|
||
```
|
||
internetlab-test-task/
|
||
├── backend/
|
||
│ ├── src/
|
||
│ │ ├── main.ts
|
||
│ │ ├── app.module.ts
|
||
│ │ ├── contact/
|
||
│ │ │ ├── contact.module.ts
|
||
│ │ │ ├── contact.controller.ts
|
||
│ │ │ ├── contact.service.ts
|
||
│ │ │ ├── dto/
|
||
│ │ │ │ └── create-contact.dto.ts
|
||
│ │ │ └── interfaces/
|
||
│ │ │ └── contact.interface.ts
|
||
│ │ ├── ai/
|
||
│ │ │ ├── ai.module.ts
|
||
│ │ │ └── ai.service.ts
|
||
│ │ ├── mail/
|
||
│ │ │ ├── mail.module.ts
|
||
│ │ │ └── mail.service.ts
|
||
│ │ ├── health/
|
||
│ │ │ └── health.controller.ts
|
||
│ │ ├── metrics/
|
||
│ │ │ ├── metrics.module.ts
|
||
│ │ │ ├── metrics.controller.ts
|
||
│ │ │ └── metrics.service.ts
|
||
│ │ ├── logger/
|
||
│ │ │ └── logger.service.ts
|
||
│ │ └── storage/
|
||
│ │ └── file-storage.service.ts
|
||
│ ├── data/
|
||
│ │ ├── logs/ ← логи запросов (создаётся автоматически)
|
||
│ │ ├── metrics.json ← статистика обращений
|
||
│ │ └── rate-limit/ ← данные rate limiting
|
||
│ ├── .env.example
|
||
│ ├── tsconfig.json
|
||
│ └── package.json
|
||
└── frontend/
|
||
├── app/
|
||
│ ├── pages/
|
||
│ │ └── index.vue
|
||
│ ├── components/
|
||
│ │ ├── HeroSection.vue
|
||
│ │ ├── AboutSection.vue
|
||
│ │ ├── SkillsSection.vue
|
||
│ │ ├── ProjectsSection.vue
|
||
│ │ └── ContactForm.vue
|
||
│ ├── composables/
|
||
│ │ └── useContact.ts
|
||
│ └── assets/
|
||
│ └── styles/
|
||
│ └── main.scss
|
||
├── .env.example
|
||
├── nuxt.config.ts
|
||
└── package.json
|
||
```
|
||
|
||
---
|
||
|
||
## BACKEND
|
||
|
||
### Технологии
|
||
|
||
- **Runtime**: Node.js + TypeScript
|
||
- **Framework**: NestJS 10 + Fastify adapter (`@nestjs/platform-fastify`)
|
||
- **Package manager**: pnpm
|
||
- **Validation**: `class-validator` + `class-transformer`
|
||
- **Docs**: `@nestjs/swagger`
|
||
- **Rate limiting**: `@nestjs/throttler`
|
||
- **Mail**: `nodemailer`
|
||
- **Logging**: `winston`
|
||
- **AI**: `openai` (OpenAI-compatible SDK, используем Groq baseURL)
|
||
- **Config**: `@nestjs/config` + `dotenv`
|
||
|
||
### package.json (backend)
|
||
|
||
```json
|
||
{
|
||
"name": "dev-landing-backend",
|
||
"scripts": {
|
||
"dev": "nest start --watch",
|
||
"build": "nest build",
|
||
"start": "node dist/main.js",
|
||
"lint": "eslint \"{src,apps,libs,test}/**/*.ts\""
|
||
}
|
||
}
|
||
```
|
||
|
||
Зависимости: `@nestjs/common`, `@nestjs/core`, `@nestjs/platform-fastify`, `@nestjs/config`, `@nestjs/swagger`, `@nestjs/throttler`, `class-validator`, `class-transformer`, `reflect-metadata`, `rxjs`, `nodemailer`, `winston`, `openai`, `uuid`
|
||
|
||
Dev: `@nestjs/cli`, `@nestjs/schematics`, `@types/node`, `@types/nodemailer`, `@types/uuid`, `typescript`, `ts-node`, `eslint`, `@antfu/eslint-config`
|
||
|
||
### Переменные окружения (`.env.example`)
|
||
|
||
```env
|
||
# Server
|
||
PORT=3001
|
||
NODE_ENV=development
|
||
|
||
# CORS
|
||
FRONTEND_URL=http://localhost:3000
|
||
|
||
# Mail (SMTP)
|
||
SMTP_HOST=smtp.gmail.com
|
||
SMTP_PORT=587
|
||
SMTP_USER=your@gmail.com
|
||
SMTP_PASS=your-app-password
|
||
MAIL_FROM=your@gmail.com
|
||
MAIL_TO=owner@gmail.com
|
||
|
||
# AI (Groq)
|
||
GROQ_API_KEY=your-groq-api-key
|
||
GROQ_MODEL=llama-3.3-70b-versatile
|
||
|
||
# Rate limiting
|
||
THROTTLE_TTL=60000
|
||
THROTTLE_LIMIT=5
|
||
```
|
||
|
||
### Архитектура и реализация
|
||
|
||
#### `main.ts`
|
||
|
||
- NestJS + Fastify adapter
|
||
- Включить `ValidationPipe` глобально (с `transform: true`, `whitelist: true`)
|
||
- Настроить CORS: разрешить `FRONTEND_URL` из env
|
||
- Настроить Swagger: `DocumentBuilder` → title, description, version → `SwaggerModule.setup('api/docs', app, document)`
|
||
- Порт из `process.env.PORT ?? 3001`
|
||
|
||
#### `app.module.ts`
|
||
|
||
Импортировать: `ConfigModule.forRoot({ isGlobal: true })`, `ThrottlerModule.forRootAsync(...)`, `ContactModule`, `HealthModule`, `MetricsModule`
|
||
|
||
#### DTO (`create-contact.dto.ts`)
|
||
|
||
```typescript
|
||
export class CreateContactDto {
|
||
@IsString()
|
||
@IsNotEmpty()
|
||
@MaxLength(100)
|
||
@ApiProperty({ example: "Иван Иванов" })
|
||
name: string;
|
||
|
||
@IsString()
|
||
@IsNotEmpty()
|
||
@Matches(/^[\+]?[(]?[0-9]{3}[)]?[-\s\.]?[0-9]{3}[-\s\.]?[0-9]{4,6}$/)
|
||
@ApiProperty({ example: "+7 999 123-45-67" })
|
||
phone: string;
|
||
|
||
@IsEmail()
|
||
@ApiProperty({ example: "ivan@example.com" })
|
||
email: string;
|
||
|
||
@IsString()
|
||
@IsOptional()
|
||
@MaxLength(1000)
|
||
@ApiProperty({ example: "Хочу обсудить проект", required: false })
|
||
comment?: string;
|
||
}
|
||
```
|
||
|
||
#### `ContactController` (`POST /api/contact`)
|
||
|
||
- Декоратор `@UseGuards(ThrottlerGuard)`
|
||
- Принимает `CreateContactDto`
|
||
- Вызывает `contactService.handleContact(dto)`
|
||
- Возвращает `{ success: true, message: string, ai: { sentiment, category, autoReply } }`
|
||
- Обработка ошибок: если mail упал — вернуть 500 с понятным сообщением; если AI упал — продолжить без AI (graceful fallback)
|
||
- Все ошибки логировать через `LoggerService`
|
||
|
||
#### `ContactService`
|
||
|
||
Метод `handleContact(dto: CreateContactDto)`:
|
||
|
||
1. Логировать входящий запрос через `LoggerService` (в файл)
|
||
2. Вызвать `aiService.analyzeContact(dto)` — получить `{ sentiment, category, autoReply }`. Если упал — `null`, продолжить
|
||
3. Вызвать `mailService.sendOwnerNotification(dto, aiResult)`
|
||
4. Вызвать `mailService.sendUserConfirmation(dto, aiResult)`
|
||
5. Обновить метрики через `metricsService.increment(category)`
|
||
6. Вернуть результат
|
||
|
||
#### `AiService`
|
||
|
||
Используй `openai` SDK с Groq baseURL:
|
||
|
||
```typescript
|
||
import OpenAI from "openai";
|
||
|
||
const groq = new OpenAI({
|
||
apiKey: process.env.GROQ_API_KEY,
|
||
baseURL: "https://api.groq.com/openai/v1",
|
||
});
|
||
```
|
||
|
||
Метод `analyzeContact(dto)`:
|
||
|
||
- Промпт (системный): "Ты — аналитик обращений. Отвечай ТОЛЬКО валидным JSON без markdown и пояснений."
|
||
- Промпт (пользователь): передать имя, email, комментарий
|
||
- Ожидаемый JSON-ответ от модели:
|
||
```json
|
||
{
|
||
"sentiment": "positive" | "neutral" | "negative",
|
||
"category": "question" | "partnership" | "job" | "spam" | "other",
|
||
"autoReply": "текст автоответа на русском языке (2-3 предложения)"
|
||
}
|
||
```
|
||
- Graceful fallback: обернуть в `try/catch`, при ошибке логировать и вернуть `null`
|
||
- Таймаут запроса: 10 секунд
|
||
|
||
#### `MailService`
|
||
|
||
`sendOwnerNotification(dto, aiResult)`:
|
||
|
||
- Тема: `Новое обращение от ${dto.name}`
|
||
- HTML-письмо: имя, телефон, email, комментарий, блок AI-анализа (если есть)
|
||
|
||
`sendUserConfirmation(dto, aiResult)`:
|
||
|
||
- Тема: `Спасибо за обращение, ${dto.name}!`
|
||
- HTML-письмо: подтверждение получения + `autoReply` от AI (если есть) или дефолтный текст
|
||
|
||
#### `LoggerService`
|
||
|
||
Использовать `winston`:
|
||
|
||
- Транспорты: Console + File (`data/logs/requests-YYYY-MM-DD.log`)
|
||
- Формат файла: JSON с `timestamp`, `level`, `message`, `meta`
|
||
- Метод `logRequest(method, path, body, response, duration)` — логировать каждый запрос
|
||
- Метод `logError(error, context)` — логировать ошибки
|
||
|
||
#### `FileStorageService`
|
||
|
||
Простой сервис для работы с JSON-файлами:
|
||
|
||
- `read<T>(filepath): T | null`
|
||
- `write<T>(filepath, data: T): void`
|
||
- Все операции синхронные (`fs.readFileSync` / `writeFileSync`)
|
||
- Автосоздание директории если не существует
|
||
|
||
#### `MetricsService`
|
||
|
||
Хранить данные в `data/metrics.json`:
|
||
|
||
```json
|
||
{
|
||
"total": 0,
|
||
"byCategory": {
|
||
"question": 0,
|
||
"partnership": 0,
|
||
"job": 0,
|
||
"spam": 0,
|
||
"other": 0
|
||
},
|
||
"bySentiment": { "positive": 0, "neutral": 0, "negative": 0 },
|
||
"lastUpdated": "ISO timestamp"
|
||
}
|
||
```
|
||
|
||
`MetricsController` → `GET /api/metrics` → вернуть текущие метрики
|
||
|
||
#### `HealthController` → `GET /api/health`
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"timestamp": "ISO",
|
||
"uptime": 12345,
|
||
"version": "1.0.0"
|
||
}
|
||
```
|
||
|
||
#### Rate Limiting
|
||
|
||
`ThrottlerModule` с настройками из env: `ttl: THROTTLE_TTL (60000ms)`, `limit: THROTTLE_LIMIT (5)`.
|
||
Применять `ThrottlerGuard` к `POST /api/contact`.
|
||
При превышении лимита — NestJS вернёт 429 автоматически.
|
||
|
||
#### Глобальный error handler
|
||
|
||
Создать `AllExceptionsFilter` (`@Catch()`):
|
||
|
||
- Логировать все необработанные ошибки через `LoggerService`
|
||
- Возвращать единообразный JSON: `{ statusCode, message, timestamp, path }`
|
||
- Зарегистрировать глобально в `main.ts`
|
||
|
||
#### Swagger
|
||
|
||
- Доступен по `GET /api/docs`
|
||
- Все эндпоинты задокументированы с `@ApiOperation`, `@ApiResponse`, `@ApiBody`
|
||
- DTO с `@ApiProperty` декораторами
|
||
|
||
---
|
||
|
||
## FRONTEND
|
||
|
||
### Технологии
|
||
|
||
- **Framework**: Nuxt 3
|
||
- **UI**: `@nuxt/ui` (последняя версия)
|
||
- **Styling**: Tailwind CSS (через `@nuxt/ui`) + SASS
|
||
- **Package manager**: pnpm
|
||
- **Lint**: `@antfu/eslint-config`
|
||
- **HTTP**: встроенный `$fetch` / `useFetch` Nuxt
|
||
|
||
### `nuxt.config.ts`
|
||
|
||
```typescript
|
||
export default defineNuxtConfig({
|
||
modules: ["@nuxt/ui"],
|
||
compatibilityDate: "2024-11-01",
|
||
devtools: { enabled: true },
|
||
css: ["~/assets/styles/main.scss"],
|
||
runtimeConfig: {
|
||
public: {
|
||
apiBase: process.env.NUXT_PUBLIC_API_BASE ?? "http://localhost:3001/api",
|
||
},
|
||
},
|
||
});
|
||
```
|
||
|
||
### Переменные окружения (`.env.example`)
|
||
|
||
```env
|
||
NUXT_PUBLIC_API_BASE=http://localhost:3001/api
|
||
```
|
||
|
||
### Страница (`pages/index.vue`)
|
||
|
||
Лендинг разработчика. Секции по порядку:
|
||
|
||
1. **HeroSection** — имя, должность, краткое описание, кнопка "Связаться"
|
||
2. **AboutSection** — несколько предложений о себе
|
||
3. **SkillsSection** — карточки со скиллами (NestJS, Nuxt, TypeScript, etc.)
|
||
4. **ProjectsSection** — карточки проектов (можно placeholder данные)
|
||
5. **ContactForm** — форма обратной связи
|
||
|
||
Навбар: фиксированный вверху, ссылки-якоря на секции. Плавный скролл через CSS `scroll-behavior: smooth`.
|
||
|
||
### `ContactForm.vue`
|
||
|
||
Поля формы: Имя (required), Телефон (required), Email (required), Комментарий (textarea, optional).
|
||
|
||
Логика:
|
||
|
||
- Валидация на клиенте перед отправкой (не пустые обязательные поля, формат email)
|
||
- `POST` на `${apiBase}/contact`
|
||
- Состояния: `idle → loading → success | error`
|
||
- При `success`: показать сообщение + `autoReply` от AI если есть
|
||
- При `error`: показать текст ошибки из ответа
|
||
- При 429 (rate limit): показать "Слишком много запросов, попробуйте позже"
|
||
|
||
### `composables/useContact.ts`
|
||
|
||
```typescript
|
||
export function useContact() {
|
||
const config = useRuntimeConfig();
|
||
const loading = ref(false);
|
||
const error = ref<string | null>(null);
|
||
const success = ref(false);
|
||
const aiReply = ref<string | null>(null);
|
||
|
||
async function submit(data: ContactFormData) {
|
||
loading.value = true;
|
||
error.value = null;
|
||
try {
|
||
const res = await $fetch(`${config.public.apiBase}/contact`, {
|
||
method: "POST",
|
||
body: data,
|
||
});
|
||
success.value = true;
|
||
aiReply.value = res.ai?.autoReply ?? null;
|
||
} catch (e: any) {
|
||
if (e.status === 429)
|
||
error.value = "Слишком много запросов. Попробуйте через минуту.";
|
||
else error.value = e.data?.message ?? "Что-то пошло не так";
|
||
} finally {
|
||
loading.value = false;
|
||
}
|
||
}
|
||
|
||
return { loading, error, success, aiReply, submit };
|
||
}
|
||
```
|
||
|
||
### Дизайн
|
||
|
||
Тёмная тема (dark mode по умолчанию). Современный минималистичный стиль разработчика.
|
||
Использовать компоненты `@nuxt/ui`: `UButton`, `UInput`, `UTextarea`, `UCard`, `UBadge`, `UAlert`.
|
||
Анимации появления секций при скролле через CSS `@keyframes` + `IntersectionObserver`.
|
||
|
||
---
|
||
|
||
## Порядок выполнения
|
||
|
||
### Backend
|
||
|
||
1. `mkdir backend && cd backend` → `pnpm init` → установить зависимости → scaffold через `nest new . --package-manager pnpm` или вручную
|
||
2. Настроить `tsconfig.json`, `.env` из `.env.example`
|
||
3. Создать `FileStorageService`, `LoggerService` (базовые утилиты)
|
||
4. Создать `AiService` → протестировать вызов Groq
|
||
5. Создать `MailService` → протестировать отправку (можно с `SMTP_HOST=smtp.ethereal.email` для теста)
|
||
6. Создать `ContactModule`: DTO → Controller → Service (с AI + mail + logging)
|
||
7. Создать `MetricsModule` и `HealthController`
|
||
8. Настроить `ThrottlerModule`, `AllExceptionsFilter`, Swagger
|
||
9. Проверить: `pnpm dev` → `http://localhost:3001/api/docs` открывается
|
||
|
||
### Frontend
|
||
|
||
1. `pnpm dlx nuxi@latest init frontend` → выбрать нужные модули
|
||
2. Установить `@nuxt/ui`, `sass`
|
||
3. Настроить `nuxt.config.ts`, `.env`
|
||
4. Создать `useContact` composable
|
||
5. Сверстать секции лендинга (Hero → About → Skills → Projects → Contact)
|
||
6. Реализовать `ContactForm.vue` с полной логикой
|
||
7. Проверить: форма отправляет запрос, показывает AI-ответ
|
||
|
||
---
|
||
|
||
## Важные детали
|
||
|
||
- `data/` директория в `backend/` — создавать автоматически при старте если не существует
|
||
- Метрики и rate-limit данные — хранить в файлах, не в памяти (чтобы переживали рестарт)
|
||
- Логи — один файл в день, имя формата `requests-2025-01-15.log`
|
||
- AI fallback — если `GROQ_API_KEY` не задан или запрос упал, ContactService продолжает работу (отправляет письма без AI-анализа), в ответе `ai: null`
|
||
- Mail fallback — если SMTP не настроен (пустой `SMTP_HOST`), MailService логирует письмо в консоль вместо отправки (для удобства разработки)
|
||
- CORS — только `FRONTEND_URL` из env, не `*`
|
||
- Все секреты только через env, никаких хардкодов
|
||
|
||
---
|
||
|
||
## Что должно работать в итоге
|
||
|
||
- `http://localhost:3001/api/docs` — Swagger UI со всеми эндпоинтами
|
||
- `POST http://localhost:3001/api/contact` — принимает форму, анализирует AI, отправляет письма, логирует
|
||
- `GET http://localhost:3001/api/health` — статус сервиса
|
||
- `GET http://localhost:3001/api/metrics` — статистика обращений
|
||
- `http://localhost:3000` — лендинг с формой, которая работает с бэком
|
||
- Форма показывает AI-автоответ после успешной отправки
|
||
- Rate limiting: больше 5 запросов в минуту → 429
|
||
- Логи пишутся в `backend/data/logs/`
|