Work-Task Frontend

Быстрый старт

Требования:
- Node.js >= 20.17.0 — это среда, в которой запускается JavaScript вне браузера. Необходима для работы всех современных фронтенд-проектов
- npm >= 10.8.2 — менеджер пакетов для установки зависимостей
- Рекомендуется nvm — это инструмент для удобного переключения между разными версиями Node.js
- Проверить версии:
```
node -v
npm -v
```
- Если версия ниже:
  - Обновить через сайт:
    1. Перейдите на nodejs.org
    2. Скачайте и установите последнюю LTS-версию для вашей ОС
    3. Перезапустите терминал и проверьте версии снова
  - Обновить через nvm (если установлен):
```
nvm install 20
nvm use 20
nvm alias default 20
node -v
npm -v
```
- Зачем это нужно: Современные проекты используют новые возможности языка и инструментов, которые не поддерживаются старыми версиями Node.js и npm. Если не обновить — проект может не запуститься или работать с ошибками.
Установка и запуск:
- Склонируйте репозиторий: скачайте проект к себе на компьютер.
```
git clone <ссылка на репозиторий>
```
- Установите зависимости: скачайте все нужные библиотеки для работы проекта.
```
npm install
```
- Запустите проект в режиме разработки:
```
npm run dev
```
  После запуска откройте http://localhost:3000 в браузере.
  - Если порт 3000 занят, либо закройте другое приложение, либо используйте переменную окружения: PORT=3001 npm run dev
- Сборка и запуск для продакшена:
```
npm run build
npm start
```
  Это создаст оптимизированную версию приложения и запустит её как production-сервер.
- Если что-то не работает:
  - Проверьте сообщения об ошибках в терминале — они обычно подсказывают, что делать.
  - Убедитесь, что установлены правильные версии Node.js и npm.
  - Попробуйте удалить папку node_modules и файл package-lock.json, затем снова выполнить npm install.

🛠️ Полезные команды для фронта

npm run dev — запуск проекта в режиме разработки (автоматически обновляет страницу при изменениях кода)
npm run build — сборка проекта для продакшена (создаёт оптимизированную версию)
npm start — запуск production-сервера (используется после сборки)
npm run lint — проверка кода на стиль и ошибки (ESLint)
npm run format — автоформатирование кода (например, Prettier; может не быть настроено)
npm run analyze — анализ размера бандла (если настроено; помогает понять, что занимает место в сборке)
npm run test — запуск тестов (если есть; для проверки работоспособности кода)
npm outdated — показать устаревшие зависимости (помогает поддерживать проект в актуальном состоянии)
npm audit — аудит безопасности зависимостей (ищет уязвимости)
npm ls — показать дерево зависимостей (для диагностики проблем с пакетами)

Некоторые команды могут быть не настроены по умолчанию — смотрите package.json для полного списка и описания.

🧬 Автоматическая генерация типов из OpenAPI

В проекте все типы данных для API (DTO) автоматически генерируются из OpenAPI-спецификации бэкенда. Это гарантирует актуальность типов и избавляет от ручного дублирования.

Где лежат типы:
src/lib/types.api.ts — автогенерируемый файл, не редактируйте его вручную!

Как обновить типы при изменении API:

Убедитесь, что установлен пакет swagger-typescript-api (уже есть в devDependencies).
Выполните команду:
```
npm run openapi
```
или вручную:
```
npx swagger-typescript-api -p http://91.211.249.37/test/v3/api-docs -o src/lib -n types.api.ts
```
- -p — путь к OpenAPI/Swagger JSON
- -o — куда положить сгенерированные типы
- -n — имя файла
После генерации используйте типы из @/lib/types.api во всех API-хуках и сервисах.

Важно:

Не редактируйте types.api.ts вручную — все изменения будут перезаписаны при следующей генерации.

Если структура API изменилась, всегда обновляйте типы перед началом работы.

📝 Сводка о проекте

Что это: Приложение для управления задачами и проектами (таск-трекер)
Технологии: Next.js 14, TypeScript, React, Tailwind CSS, React Query, Radix UI
Где работает: Любой современный браузер, Node.js >= 20.17.0
Интеграции:
- Внешний REST API (бэкенд на отдельном сервере)
- CI/CD через GitHub Actions
- Docker/Kubernetes (K3s)
Структура:
- UI-компоненты (src/components/)
- Бизнес-логика (src/features/)
- Конфигурация API (src/config.ts)
- Конфиги, хуки, утилиты и т.д.

🏗️ Как работает Work-Task: пошаговый разбор

1. Конкретный пример: пользователь создаёт новую задачу

Что видит пользователь:

Открывает страницу "Задачи"
Нажимает кнопку "Создать задачу"
Заполняет форму: название, описание, срок
Нажимает "Сохранить"
Видит новую задачу в списке

Что происходит в коде (пошагово):

sequenceDiagram
    participant User as "👤 Пользователь"
    participant UI as "🎨 Интерфейс"
    participant Logic as "🧠 Бизнес-логика"
    participant Config as "⚙️ Config.ts"
    participant Server as "🖥️ Внешний сервер"
    participant DB as "🗄️ База данных"

    User->>UI: 1. Нажимает "Создать задачу"
    UI->>Logic: 2. Вызывает createTask()
    Logic->>Config: 3. Формирует URL: /tasks/create
    Config->>Server: 4. POST запрос с данными
    Server->>DB: 5. Сохраняет в БД
    DB-->>Server: 6. "OK, задача создана"
    Server-->>Config: 7. JSON ответ
    Config-->>Logic: 8. Передаёт ответ
    Logic-->>UI: 9. Обновляет список
    UI-->>User: 10. Показывает новую задачу

Где в проекте это происходит:

Шаг	Что происходит	Файл в проекте	Код
1-2	Пользователь нажимает кнопку	`src/components/`	`onClick={handleCreate}`
3	Формируется запрос	`src/features/tasks/`	`useCreateTask()`
4	Отправляется на сервер	`src/config.ts`	`buildApiUrl('/tasks/create')`
5-6	Сервер сохраняет данные	Внешний сервер	`INSERT INTO tasks...`
7-10	Ответ возвращается обратно	Все те же файлы	Обновление UI

2. Ещё пример: пользователь входит в систему

Что видит пользователь:

Открывает страницу входа
Вводит email и пароль
Нажимает "Войти"
Попадает на главную страницу

Что происходит в коде:

sequenceDiagram
    participant User as "👤 Пользователь"
    participant Auth as "🔐 Форма входа"
    participant Logic as "🧠 Auth Logic"
    participant Config as "⚙️ Config.ts"
    participant Server as "🖥️ Сервер"

    User->>Auth: 1. Вводит логин/пароль
    Auth->>Logic: 2. Вызывает login()
    Logic->>Config: 3. POST /auth/login
    Config->>Server: 4. Проверка данных
    Server-->>Config: 5. JWT токен
    Config-->>Logic: 6. Передаёт токен
    Logic-->>Auth: 7. Сохраняет в localStorage
    Auth-->>User: 8. Перенаправляет на главную

3. Архитектура проекта: что где лежит

🎨 UI-компоненты (src/components/):

Кнопки, формы, списки
Всё, что пользователь видит и с чем взаимодействует
Пример: Button.tsx, TaskForm.tsx, TaskList.tsx

🧠 Бизнес-логика (src/features/):

Обработка действий пользователя
Правила работы приложения
Пример: useCreateTask.ts, useLogin.ts

⚙️ Конфигурация (src/config.ts):

Настройки API
URL сервера, эндпоинты
Пример: buildApiUrl('/tasks/create')

🖥️ Внешний сервер:

Обработка запросов
База данных
Безопасность

4. Почему так устроено?

✅ Преимущества:

Чёткое разделение: UI отдельно от логики, логика отдельно от API
Легко тестировать: каждую часть можно проверить отдельно
Просто поддерживать: если сломалась кнопка — идём в компоненты, если логика — в features
Масштабируемо: легко добавлять новые функции

🔧 Как это помогает разработчику:

Нужно изменить дизайн кнопки → src/components/
Нужно добавить валидацию формы → src/features/
Нужно поменять URL API → src/config.ts
Нужно изменить логику на сервере → внешний репозиторий

5. Полная картина: от клика до результата

flowchart TD
    A["👤 Пользователь кликает"]
    B["🎨 UI-компонент обрабатывает"]
    C["🧠 Бизнес-логика выполняет"]
    D["⚙️ Config.ts отправляет запрос"]
    E["🖥️ Внешний сервер обрабатывает"]
    F["🗄️ База данных сохраняет"]
    G["📤 Ответ идёт обратно"]
    H["🎨 UI обновляется"]
    I["👤 Пользователь видит результат"]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I

🧩 Как данные путешествуют по приложению

Что происходит, когда ты работаешь с задачами в Work-Task

Конкретный пример: создание задачи

Шаг 1: Ты открываешь страницу "Задачи"

Что происходит: загружается список задач
Где в коде: src/app/(dashboard)/tasks/page.tsx
Что видишь: список задач, кнопка "Создать задачу"

Шаг 2: Ты нажимаешь "Создать задачу"

Что происходит: открывается модальное окно с формой
Где в коде: src/features/tasks/components/create-task-modal.tsx
Что видишь: форму для ввода названия, описания, срока

Шаг 3: Ты заполняешь форму и нажимаешь "Сохранить"

Что происходит: данные передаются в обработчик
Где в коде: src/features/tasks/components/create-task-form.tsx
Что происходит: валидация данных, подготовка к отправке

Шаг 4: Данные отправляются на сервер

Что происходит: формируется HTTP запрос
Где в коде: src/features/tasks/api/use-create-task.ts
Что отправляется: название, описание, срок, проект

Шаг 5: Сервер обрабатывает запрос

Что происходит: данные сохраняются в базе данных
Где в коде: внешний сервер (не в этом проекте)
Что возвращается: ID новой задачи, статус "создана"

Шаг 6: Ответ приходит обратно

Что происходит: обновляется список задач
Где в коде: src/features/tasks/api/use-get-tasks.ts
Что видишь: новая задача появляется в списке

Шаг 7: Интерфейс обновляется

Что происходит: модальное окно закрывается, список обновляется
Где в коде: src/components/data-display/tasks.tsx
Что видишь: новая задача в списке с правильным статусом

Ещё пример: вход в систему

Шаг 1: Ты открываешь страницу входа

Что происходит: загружается форма входа
Где в коде: src/app/(auth)/sign-in/page.tsx

Шаг 2: Ты вводишь email и пароль

Что происходит: данные сохраняются в форме
Где в коде: src/features/auth/components/sign-in-card.tsx

Шаг 3: Ты нажимаешь "Войти"

Что происходит: данные отправляются на сервер
Где в коде: src/features/auth/api/use-login.ts

Шаг 4: Сервер проверяет данные

Что происходит: проверка email/пароля в базе
Где в коде: внешний сервер

Шаг 5: Сервер возвращает токен

Что происходит: JWT токен сохраняется в браузере
Где в коде: src/features/auth/api/use-current.ts

Шаг 6: Ты попадаешь на главную страницу

Что происходит: перенаправление на dashboard
Где в коде: src/app/(dashboard)/page.tsx

Структура файлов по шагам:

👤 Пользователь → 📄 Страница → 🎨 Компонент → 🧠 API → 🌐 Сервер

Каждый шаг — это конкретный файл в проекте:

Страницы: src/app/(dashboard)/tasks/page.tsx
Компоненты: src/features/tasks/components/
API: src/features/tasks/api/
Конфигурация: src/config.ts

Если что-то не работает:

Форма не открывается → проверь src/features/tasks/components/create-task-modal.tsx
Данные не отправляются → проверь src/features/tasks/api/use-create-task.ts
Список не обновляется → проверь src/features/tasks/api/use-get-tasks.ts
Ошибка подключения → проверь src/config.ts

⚙️ CI/CD Pipeline (Деплой)

Как код из репозитория автоматически попадает на сервер и разворачивается.

flowchart LR
  Dev["Разработчик"] -->|"Push/PR"| GitHub["GitHub"]
  GitHub -->|"Workflow"| Actions["GitHub Actions"]
  Actions -->|"Docker build"| Image["Docker Image"]
  Actions -->|"SCP/SSH"| VPS["Сервер (K3s)"]
  VPS -->|"kubectl"| K8s["Kubernetes"]
  K8s -->|"Обновление"| App["Work-Task Frontend"]

Пояснение: Показывает, как происходит автоматический деплой: от коммита до обновления приложения на сервере.

🗂️ Архитектура основных папок проекта

src/components/ — UI-компоненты: кнопки, формы, списки, модальные окна и всё, что отвечает за внешний вид и взаимодействие с пользователем.
src/features/ — бизнес-логика: обработка действий пользователя, правила работы приложения, интеграция с API.
src/config.ts — конфигурация API: настройки для подключения к внешнему серверу, эндпоинты и утилиты для работы с API.
src/hooks/ — кастомные хуки React: переиспользуемые функции для работы с состоянием, эффектами и т.д.
src/lib/ — утилиты, вспомогательные функции и типы.
public/ — статические файлы: картинки, иконки, шрифты.
config.ts, package.json, конфиги — настройки, зависимости, скрипты.

Эти папки — основа архитектуры. Внутри них могут появляться новые файлы и подпапки, но сами разделы почти не меняются.

🧩 Технологии

Next.js 14 — современный фреймворк для сайтов
TypeScript — помогает не ошибаться в коде
React Query — ускоряет работу с сервером
Tailwind CSS — красивые стили прямо в коде
Radix UI — готовые элементы интерфейса

💡 Советы

Читать README.md в каждой папке — там всё объяснено.
Если что-то не работает — внимательно читайте ошибку в терминале.
Перед коммитом всегда запускайте npm run lint.
Любое изменение — это вклад в проект!

❓ FAQ (Частые вопросы и проблемы)

Q: У меня ошибка про несовместимость Node.js или npm
A: Проверьте версии через node -v и npm -v. Если ниже требуемых — обновите Node.js (см. раздел "Требования").

Q: Ошибка EADDRINUSE: порт 3000 уже используется
A: Закройте другое приложение, использующее этот порт, или запустите проект на другом порту: PORT=3001 npm run dev

Q: Ошибка при установке зависимостей (npm install)
A: Попробуйте удалить папку node_modules и файл package-lock.json, затем снова выполнить npm install.

Q: Ошибка 'Cannot find module ...' или 'Module not found'
A: Проверьте, что все зависимости установлены (npm install). Если не помогло — удалите node_modules и package-lock.json, затем снова установите.

Q: Ошибка 'npm: command not found'
A: Убедитесь, что Node.js и npm установлены и доступны в PATH. Проверьте через node -v и npm -v.

Q: Как обновить npm до последней версии?
A: Выполните npm install -g npm@latest (может потребоваться sudo на Linux/Mac).

Q: Как очистить кэш npm?
A: Выполните npm cache clean --force.

Q: Как узнать, какие зависимости устарели?
A: Выполните npm outdated.

Q: Как проверить проект на уязвимости?
A: Выполните npm audit.

Q: Как запустить тесты?
A: Если тесты настроены — используйте npm run test.

Q: Где искать документацию по отдельным модулям?
A: В каждой основной папке есть свой README.md с деталями и примерами.

Q: Как внести свой вклад?
A: Создайте ветку, внесите изменения, отправьте Pull Request.

Автор: @krutakov

Name		Name	Last commit message	Last commit date
Latest commit History 75 Commits
.github/workflows		.github/workflows
public		public
src		src
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.nvmrc		.nvmrc
Dockerfile		Dockerfile
README.md		README.md
components.json		components.json
next.config.mjs		next.config.mjs
nginx.conf		nginx.conf
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Work-Task Frontend

Быстрый старт

🛠️ Полезные команды для фронта

🧬 Автоматическая генерация типов из OpenAPI

📝 Сводка о проекте

🏗️ Как работает Work-Task: пошаговый разбор

1. Конкретный пример: пользователь создаёт новую задачу

2. Ещё пример: пользователь входит в систему

3. Архитектура проекта: что где лежит

4. Почему так устроено?

5. Полная картина: от клика до результата

🧩 Как данные путешествуют по приложению

Конкретный пример: создание задачи

Ещё пример: вход в систему

Структура файлов по шагам:

Если что-то не работает:

⚙️ CI/CD Pipeline (Деплой)

🗂️ Архитектура основных папок проекта

🧩 Технологии

💡 Советы

❓ FAQ (Частые вопросы и проблемы)

About

Uh oh!

Releases

Packages

Uh oh!

Contributors 5

Uh oh!

Languages

WorkTechDevelop/frontend

Folders and files

Latest commit

History

Repository files navigation

Work-Task Frontend

Быстрый старт

🛠️ Полезные команды для фронта

🧬 Автоматическая генерация типов из OpenAPI

📝 Сводка о проекте

🏗️ Как работает Work-Task: пошаговый разбор

1. Конкретный пример: пользователь создаёт новую задачу

2. Ещё пример: пользователь входит в систему

3. Архитектура проекта: что где лежит

4. Почему так устроено?

5. Полная картина: от клика до результата

🧩 Как данные путешествуют по приложению

Конкретный пример: создание задачи

Ещё пример: вход в систему

Структура файлов по шагам:

Если что-то не работает:

⚙️ CI/CD Pipeline (Деплой)

🗂️ Архитектура основных папок проекта

🧩 Технологии

💡 Советы

❓ FAQ (Частые вопросы и проблемы)

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 5

Uh oh!

Languages

Packages