upd
This commit is contained in:
Oscar
131
README.md
Normal file
131
README.md
Normal file
@@ -0,0 +1,131 @@
|
||||
# TMC Test Task
|
||||
|
||||
Fullstack-приложение для управления коллекцией элементов с двухпанельным интерфейсом, виртуальным скроллом и drag & drop.
|
||||
|
||||
**Задеплоенное приложение:** [https://test-1.koptilnya.xyz/](https://test-1.koptilnya.xyz/)
|
||||
|
||||
---
|
||||
|
||||
## Что это
|
||||
|
||||
Интерфейс с двумя панелями: слева — 1 000 000 предсгенерированных элементов, справа — выбранные. Элементы можно перемещать между панелями, искать, добавлять новые и менять порядок через drag & drop.
|
||||
|
||||
---
|
||||
|
||||
## Стек
|
||||
|
||||
| Слой | Технологии |
|
||||
|---|---|
|
||||
| Backend | Node.js 22, Express 4, TypeScript 5 |
|
||||
| Frontend | Nuxt 4 (SPA), Vue 3, TypeScript 6 |
|
||||
| UI | @nuxt/ui, vue-draggable-next, SCSS |
|
||||
| Инфраструктура | Docker, Traefik, Let's Encrypt |
|
||||
| CI/CD | Gitea Actions |
|
||||
|
||||
---
|
||||
|
||||
## Архитектура бэкенда
|
||||
|
||||
Сервер запускается на порту **1337**. API задокументировано через Swagger: `/api/docs`.
|
||||
|
||||
### Эндпоинты (`/api/items`)
|
||||
|
||||
| Метод | Путь | Описание |
|
||||
|---|---|---|
|
||||
| `GET` | `/` | Невыбранные элементы (пагинация, поиск) |
|
||||
| `GET` | `/selected` | Выбранные элементы в заданном порядке |
|
||||
| `POST` | `/add` | Добавить элемент в очередь на создание |
|
||||
| `POST` | `/add-value` | Создать элемент с произвольным значением |
|
||||
| `POST` | `/select` | Переместить элемент в правую панель |
|
||||
| `POST` | `/deselect` | Вернуть элемент в левую панель |
|
||||
| `PUT` | `/reorder` | Изменить порядок выбранного элемента |
|
||||
|
||||
### Хранилище
|
||||
|
||||
In-memory хранилище с 1 000 000 предсгенерированных элементов (случайные строки 6–12 символов). Выбранные элементы хранятся в `Set` для O(1)-поиска и в упорядоченном массиве для drag & drop. Новые элементы получают ID начиная с 1 000 001.
|
||||
|
||||
### Очередь с батчингом
|
||||
|
||||
Ключевая часть бэкенда — класс `RequestQueue` (`src/services/queue.ts`):
|
||||
|
||||
- **Добавление элементов** — батч сбрасывается каждые **10 секунд** или при достижении **100 операций**
|
||||
- **Select / Deselect** — применяются **немедленно** для мгновенного отклика UI
|
||||
- **Reorder** — батч сбрасывается каждую **1 секунду**
|
||||
- **Дедупликация** — повторные операции над одним элементом отбрасываются
|
||||
|
||||
Такое разделение позволяет держать UI отзывчивым для частых пользовательских действий и одновременно снижать нагрузку на запись.
|
||||
|
||||
---
|
||||
|
||||
## Архитектура фронтенда
|
||||
|
||||
SPA на Nuxt 4, SSR отключён. Сервер отдаётся через Nginx.
|
||||
|
||||
### Панели
|
||||
|
||||
**Левая панель (`LeftPanel.vue`)** — невыбранные элементы:
|
||||
- Виртуальный скролл (высота строки 47px, overscan 5 элементов)
|
||||
- Infinite scroll для подгрузки страниц
|
||||
- Поиск с дебаунсом 300 мс
|
||||
- Модальное окно добавления нового элемента
|
||||
|
||||
**Правая панель (`RightPanel.vue`)** — выбранные элементы:
|
||||
- Те же параметры виртуализации
|
||||
- Drag & drop через `vue-draggable-next`
|
||||
- Автоскролл во время перетаскивания (зона 80px, скорость до 12px/тик)
|
||||
- После отпускания — синхронизация нового порядка с бэкендом
|
||||
|
||||
### Состояние
|
||||
|
||||
Composable `useItems.ts` управляет всем состоянием: загрузка, пагинация, поиск, операции select/deselect/reorder. API-клиент генерируется автоматически из OpenAPI-спеки бэкенда (`npm run gen:api`).
|
||||
|
||||
---
|
||||
|
||||
## CI/CD и деплой
|
||||
|
||||
Пайплайны описаны в `.gitea/workflows/` и запускаются при пуше в `main`.
|
||||
|
||||
### deploy-backend.yml
|
||||
|
||||
Триггер: изменения в `/backend/**`
|
||||
|
||||
1. Checkout через SSH
|
||||
2. `docker build -t tmc-backend ./backend`
|
||||
3. Остановка старого контейнера
|
||||
4. Запуск нового в сети `traefik` с env `PATH_PREFIX=/test-1`
|
||||
5. Traefik автоматически получает Let's Encrypt сертификат и проксирует на `api.koptilnya.xyz`
|
||||
|
||||
### deploy-frontend.yml
|
||||
|
||||
Триггер: изменения в `/frontend/**`
|
||||
|
||||
1. Checkout через SSH
|
||||
2. `docker build` с build-arg `API_BASE_URL` (URL бэкенда)
|
||||
3. Остановка старого контейнера
|
||||
4. Запуск нового; Traefik проксирует на `test-1.koptilnya.xyz`
|
||||
|
||||
Оба сервиса живут в одной Docker-сети `traefik`. Traefik роутит запросы по хосту и управляет TLS.
|
||||
|
||||
---
|
||||
|
||||
## Локальный запуск
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
cd backend
|
||||
pnpm install
|
||||
pnpm dev # :1337
|
||||
|
||||
# Frontend
|
||||
cd frontend
|
||||
pnpm install
|
||||
pnpm dev # :3000
|
||||
```
|
||||
|
||||
По умолчанию фронт обращается к `http://localhost:1337`. Переопределить через `NUXT_PUBLIC_API_BASE`.
|
||||
|
||||
```bash
|
||||
# Обновить API-клиент после изменений в бэкенде
|
||||
cd frontend
|
||||
pnpm gen:api # требует запущенного бэкенда на :1337
|
||||
```
|
||||
Reference in New Issue
Block a user