# TMC Test Task — Claude Code Prompt

> Запусти этот промт из корня `A:\my-apps\tmc-test-task`

---

## Контекст и цель

Ты создаёшь fullstack-приложение для тестового задания. В текущей директории создай две папки: `backend` и `frontend`. Начни с бэкенда, затем фронтенд. Работай итеративно — сначала scaffold, потом реализация по фичам.

---

## Структура репозитория

```
tmc-test-task/
├── backend/
│   ├── src/
│   │   ├── index.ts
│   │   ├── routes/
│   │   │   └── items.ts
│   │   ├── services/
│   │   │   ├── itemsStore.ts      ← in-memory хранилище
│   │   │   └── queue.ts           ← очередь с дедупликацией
│   │   ├── middleware/
│   │   │   └── batcher.ts         ← батчинг запросов
│   │   └── swagger.ts
│   ├── eslint.config.js
│   ├── tsconfig.json
│   └── package.json
└── frontend/
    ├── app/
    │   ├── components/
    │   │   ├── LeftPanel.vue
    │   │   └── RightPanel.vue
    │   ├── composables/
    │   │   └── useItems.ts
    │   ├── services/              ← сюда генерится axios-клиент
    │   └── app.vue
    ├── eslint.config.js
    ├── nuxt.config.ts
    └── package.json
```

---

## BACKEND

### Технологии

- **Runtime**: Node.js + TypeScript
- **Framework**: Express.js
- **Package manager**: pnpm
- **Dev runner**: `tsx watch`
- **Build**: `tsc && tsc-alias`
- **Lint**: `@antfu/eslint-config`
- **Docs**: `swagger-jsdoc` + `swagger-ui-express`

### package.json (backend)

```json
{
  "name": "tmc-backend",
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc && tsc-alias",
    "start": "node dist/index.js",
    "lint": "eslint ."
  }
}
```

Зависимости: `express`, `swagger-jsdoc`, `swagger-ui-express`, `cors`
Dev: `tsx`, `tsc-alias`, `typescript`, `@types/node`, `@types/express`, `@types/swagger-jsdoc`, `@types/swagger-ui-express`, `@types/cors`, `eslint`, `@antfu/eslint-config`

### tsconfig.json (backend)

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}
```

### eslint.config.js (backend)

```js
import antfu from '@antfu/eslint-config'

export default antfu({
  typescript: true,
  node: true,
  formatters: true,
  rules: {
    'no-console': 'warn',
    'node/prefer-global/process': 'off',
  },
})
```

### Бизнес-логика

#### In-memory хранилище (`itemsStore.ts`)

- При старте приложения инициализировать массив `allItems` с ID от 1 до 1 000 000
- `selectedIds: Set<number>` — множество выбранных ID
- `orderedSelected: number[]` — массив для сохранения порядка drag&drop
- Методы:
  - `getItems(page, limit, search)` — возвращает НЕвыбранные элементы с пагинацией и фильтрацией по ID (строковый поиск по ID)
  - `getSelectedItems(page, limit, search)` — возвращает выбранные в порядке `orderedSelected`
  - `addItem(id)` — добавить новый элемент (id может быть любым числом)
  - `selectItem(id)` — переместить в правое окно
  - `deselectItem(id)` — вернуть в левое окно
  - `reorderSelected(ids: number[])` — сохранить новый порядок

#### Очередь с дедупликацией (`queue.ts`)

Реализовать `RequestQueue` класс:
- Очередь принимает задачи типа: `'add' | 'select' | 'deselect' | 'reorder'`
- **Дедупликация**: для `add`, `select`, `deselect` — ключ дедупликации это `${type}:${id}`. Если такая задача уже в очереди (не выполнена), повторно не добавлять
- **Гарантия**: одно значение не будет добавлено повторно (проверять и в store)
- Батчинг:
  - Задачи `add` — флашатся раз в **10 секунд** (или при накоплении 100 задач)
  - Задачи `select`, `deselect`, `reorder` — флашатся раз в **1 секунду**
- При флаше — выполнять все задачи из батча атомарно

#### Swagger (`swagger.ts`)

Настроить `swagger-jsdoc` + `swagger-ui-express`:
- Документация доступна по `GET /docs`
- JSON-схема по `GET /docs/json` (нужен для генерации клиента во фронте)
- Описать все модели и ответы

### API Routes

Все роуты с JSDoc-комментариями для swagger. Базовый путь: `/api`

#### `GET /api/items`

Возвращает НЕвыбранные элементы (левое окно).

Query params:
- `page` (number, default: 1)
- `limit` (number, default: 20, max: 20)
- `search` (string, optional) — фильтр по ID (поиск подстроки в строке ID)

Response:
```json
{
  "data": [{ "id": 1 }, { "id": 2 }],
  "total": 999980,
  "page": 1,
  "limit": 20,
  "hasMore": true
}
```

#### `GET /api/items/selected`

Возвращает выбранные элементы (правое окно) в сохранённом порядке.

Query params:
- `page` (number, default: 1)
- `limit` (number, default: 20, max: 20)
- `search` (string, optional)

Response: аналогично выше.

#### `POST /api/items/add`

Добавить элемент в очередь на добавление.

Body:
```json
{ "id": 1000001 }
```

Response:
```json
{ "queued": true, "id": 1000001 }
```

Ошибки: 400 если `id` не передан или не число.

#### `POST /api/items/select`

Добавить элемент в очередь на выбор (переместить вправо).

Body:
```json
{ "id": 42 }
```

Response:
```json
{ "queued": true }
```

#### `POST /api/items/deselect`

Вернуть элемент в левое окно.

Body:
```json
{ "id": 42 }
```

#### `PUT /api/items/reorder`

Сохранить новый порядок выбранных элементов после drag&drop.

Body:
```json
{ "ids": [5, 3, 1, 42] }
```

Response:
```json
{ "queued": true }
```

### CORS и порт

- Порт: `1337`
- CORS: разрешить `http://localhost:3000` (фронт на nuxt)
- Swagger UI: `GET /docs`, JSON: `GET /docs/json`

---

## FRONTEND

### Технологии

- **Framework**: Nuxt 3
- **UI**: `@nuxt/ui` (последняя версия)
- **Styling**: Tailwind CSS (через `@nuxt/ui`), SASS
- **Package manager**: pnpm
- **Lint**: `@antfu/eslint-config` + `vue-tsc`
- **API клиент**: axios + автогенерация через `swagger-typescript-api`

### package.json (frontend) — scripts

```json
{
  "scripts": {
    "dev": "nuxt dev",
    "build": "nuxt build",
    "preview": "nuxt preview",
    "lint": "eslint .",
    "typecheck": "vue-tsc --noEmit",
    "gen:api": "npx swagger-typescript-api generate --path http://localhost:1337/docs/json --output ./app/services --name api.ts --axios --unwrap-response-data"
  }
}
```

Зависимости: `@nuxt/ui`, `axios`, `vue-draggable-next` (drag&drop)
Dev: `eslint`, `@antfu/eslint-config`, `vue-tsc`, `typescript`, `sass`, `swagger-typescript-api`

### nuxt.config.ts

```ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  compatibilityDate: '2024-11-01',
  devtools: { enabled: true },
  css: ['~/assets/styles/main.scss'],
  runtimeConfig: {
    public: {
      apiBase: process.env.API_BASE ?? 'http://localhost:1337/api',
    },
  },
})
```

### eslint.config.js (frontend)

```js
import antfu from '@antfu/eslint-config'

export default antfu({
  typescript: true,
  vue: true,
  formatters: true,
  rules: {
    'no-console': 'warn',
  },
})
```

### UI и функционал

#### Главная страница (`app/app.vue` или `app/pages/index.vue`)

Разметка: два равных контейнера в ряд (50/50 или flex/grid), высота — весь экран минус header.

#### Левое окно (компонент `LeftPanel.vue`)

- Заголовок: "All items"
- Инпут поиска: фильтрация по ID (debounce 300ms)
- Кнопка "Add item": открывает modal/popover с инпутом для ввода ID → POST /api/items/add
- Список элементов:
  - Каждый элемент: `#ID` + кнопка "→" для выбора (POST /api/items/select)
  - Инфинити-скролл: IntersectionObserver на sentinel-элементе в конце списка, подгружать по 20 элементов
  - При поиске — сбрасывать страницу, начинать с 1
  - `hasMore` из ответа API определяет, показывать ли sentinel

#### Правое окно (компонент `RightPanel.vue`)

- Заголовок: "Selected items"
- Инпут поиска: фильтрация по ID (debounce 300ms)
- Список с drag&drop (библиотека `vue-draggable-next`):
  - Drag&drop работает для видимого (в том числе отфильтрованного) списка
  - После drop: PUT /api/items/reorder с полным новым порядком
  - Каждый элемент: drag-handle иконка + `#ID` + кнопка "←" для возврата (POST /api/items/deselect)
  - Инфинити-скролл аналогично левому окну

#### Composable (`composables/useItems.ts`)

Создать composable `useItems()` с методами:
- `fetchLeft(reset?)` — загрузить/дозагрузить левую панель
- `fetchRight(reset?)` — загрузить/дозагрузить правую панель
- `selectItem(id)` — выбрать элемент
- `deselectItem(id)` — вернуть
- `reorderSelected(ids)` — сохранить порядок
- `addItem(id)` — добавить новый элемент
- Реактивные состояния: `leftItems`, `rightItems`, `leftSearch`, `rightSearch`, `leftLoading`, `rightLoading`

Использовать axios для запросов. После каждой мутации (select/deselect/add) — перезагрузить обе панели (reset + fetch).

#### Сохранение состояния

**На сервере** хранится выбор и порядок (in-memory). Фронт при монтировании делает `fetchLeft()` и `fetchRight()` — данные восстанавливаются из сервера. Поиск не сохраняется (сбрасывается при перезагрузке страницы — это правильное поведение).

---

## Порядок выполнения

1. Создать директории `backend/` и `frontend/`
2. **Backend**:
   1. Инициализировать `pnpm init` + установить зависимости
   2. Создать `tsconfig.json`, `eslint.config.js`
   3. Реализовать `itemsStore.ts`
   4. Реализовать `queue.ts`
   5. Реализовать роуты в `routes/items.ts`
   6. Настроить swagger в `swagger.ts`
   7. Собрать всё в `index.ts`
   8. Проверить `pnpm dev` — должен стартовать на порту 1337
3. **Frontend**:
   1. `pnpm dlx nuxi@latest init frontend` (или вручную scaffold)
   2. Установить зависимости
   3. Создать `nuxt.config.ts`, `eslint.config.js`
   4. Создать структуру папок
   5. Реализовать composable `useItems.ts`
   6. Реализовать `LeftPanel.vue`
   7. Реализовать `RightPanel.vue`
   8. Собрать главную страницу
   9. Добавить скрипт `gen:api` и сгенерировать клиент (бэк должен быть запущен)

---

## Важные детали реализации

- Инфинити-скролл: не забудь `disconnect()` observer при unmount
- Дедупликация в очереди: если `POST /api/items/select` вызывается дважды для одного ID — второй запрос игнорируется до выполнения первого
- При инициализации 1М элементов — не держать в памяти объекты, только числа (массив `number[]` весит ~8MB, приемлемо)
- Типы из swagger: после `gen:api` в `app/services/api.ts` будет класс `Api` с axios. Использовать его в composable через `const api = new Api({ baseURL: config.public.apiBase })`
- CORS: обязательно, иначе фронт не достучится до бэка
- Батчинг 10 сек для `add` — при разработке можно уменьшить до 3 сек для теста, но в финальной версии должно быть 10 сек
- `reorder` через очередь: drag&drop может вызываться часто, дедуплицировать по типу (последний вызов побеждает, предыдущие отменяются — реализовать как "debounced queue" для `reorder`)

---

## Что должно работать в итоге

- `http://localhost:1337/docs` — Swagger UI с описанием всех эндпоинтов
- `http://localhost:1337/docs/json` — OpenAPI JSON (для генерации клиента)
- `http://localhost:3000` — фронт с двумя панелями
- Левая панель: поиск + инфинити-скролл + добавление + перемещение вправо
- Правая панель: поиск + инфинити-скролл + drag&drop + перемещение влево
- Состояние сохраняется при перезагрузке страницы (данные на сервере)
- Все запросы через очередь с дедупликацией и батчингом