Mutabor: Интеллектуальный Таск-менеджер

"Mutabor" — это веб-приложение для управления задачами с Kanban-доской, созданное для небольших команд. Ключевая особенность — встроенный AI-ассистент, который помогает автоматизировать рутинные задачи, такие как декомпозиция и анализ.

Продукт спроектирован как платформа, позволяющая пользователям подключать свои собственные ключи к AI-провайдерам для персонализации и контроля над расходами.

Оглавление (Table of Contents)

• 🚀 Установка и Запуск (Installation and Startup)
  • Предварительные требования (Prerequisites)
  • Общая первоначальная настройка (Common Initial Setup)
  • Режим локальной разработки (Manual Local Development Setup)
  • Локальный запуск через Docker Compose (Full Stack Docker Compose Setup)
• 🛠️ Основные команды для разработки (Key Development Commands)
• 🏛️ Архитектура и Ключевые особенности (Architecture and Key Features)
• 🔌 API Документация (API Documentation)
• 💡 Точки расширения (Extension Points)
• ✅ Тестирование (Testing)

🚀 Установка и Запуск (Installation and Startup)

В этом разделе описываются различные способы установки и запуска проекта для локальной разработки.

Предварительные требования (Prerequisites)

• Node.js (v20.x или выше)
• Docker и Docker Compose

Общая первоначальная настройка (Common Initial Setup)

1. Клонировать репозиторий:

   git clone https://github.com/your-repo/mutabor.git
   cd mutabor

2. Создать и настроить файл .env для API: Скопируйте api/.env.example в api/.env (cp api/.env.example api/.env) и проверьте переменные.

   Ключевые моменты конфигурации:

   • PORT: Мы рекомендуем установить PORT=3001, чтобы избежать конфликтов с фронтенд-сервером разработки, который обычно занимает порт 3000.
   • DATABASE_URL: Используется приложением Nest.js для подключения к базе данных. Формат зависит от способа запуска БД (см. ниже).
   • DB_* переменные: Обязательны для скрипта миграций Liquibase (npm run migrate). Они должны точно соответствовать настройкам вашей базы данных.
   • JWT_SECRET: Замените значение по умолчанию на ваш собственный секретный ключ.

Режим локальной разработки (Manual Local Development Setup)

Этот режим идеален для разработки, так как позволяет запускать сервисы по отдельности.

1. Запуск базы данных в Docker

Мы рекомендуем запускать PostgreSQL через Docker Compose, даже при ручном запуске остальных сервисов.

1. Убедитесь, что у вас есть файл docker-compose.yml в корне проекта.

2. Запустите только сервис базы данных db в фоновом режиме:

   docker compose up -d db

3. Настройте api/.env: В вашем файле api/.env должны быть следующие значения для подключения к БД, запущенной в Docker:

   # Используется приложением Nest.js
   DATABASE_URL="postgresql://user:password@localhost:54321/mutabor?schema=public"
   
   # Используется скриптом миграций Liquibase
   DB_HOST=localhost
   DB_PORT=54321
   DB_NAME=mutabor
   DB_USER=user
   DB_PASSWORD=password

   Примечание: Порт 54321 используется, так как он проброшен из контейнера в docker-compose.yml. Если у вас локально установлен PostgreSQL на порту 5432, измените эти значения соответственно.

4. Примените миграции БД: После первого запуска или при изменениях схемы выполните:

   npm run migrate -w api

   Эта команда использует переменные DB_HOST, DB_PORT и т.д. из вашего .env файла.

2. Запуск сервисов вручную

Откройте два терминала:

• Терминал 1: Запуск Бэкенда (API)

  npm run start:dev -w api

  API будет доступен по адресу http://localhost:3001 (или на порту, указанном в PORT).

• Терминал 2: Запуск Фронтенда (Client)

  npm run dev -w client

  Фронтенд будет доступен по адресу http://localhost:3000.

Локальный запуск через Docker Compose (Full Stack Docker Compose Setup)

Этот метод запускает всё приложение (фронтенд, бэкенд, БД) одной командой.

1. Убедитесь, что ваш файл api/.env создан и в нем установлен JWT_SECRET.
2. Запустите все сервисы:

   docker compose up --build

   • Фронтенд (Client) будет доступен по адресу: http://localhost:3000
   • Бэкенд (API) будет доступен по адресу: http://localhost:3001

🛠️ Основные команды для разработки

• npm run start:dev -w <workspace>: Запустить client или api в режиме разработки с hot-reload.
• npm run build -w <workspace>: Собрать продакшн-версию client или api.
• npm run test -w api: Запустить тесты (unit и интеграционные) для backend.
• npm run test -w client: Запустить тесты для frontend.
• npm run lint: Проверить код всего проекта на соответствие стандартам стиля.
• npm run migrate -w api: Применить новые миграции схемы базы данных Liquibase.

🏛️ Архитектура и Ключевые особенности

Проект построен как монорепозиторий с двумя основными частями: /api (backend на Nest.js) и /client (frontend на React).

• Модульность: Бэкенд строго разделен на модули (auth, projects, tasks, notifications).
• Строгие слои: Архитектура следует принципам Layer Guides, где контроллеры "тонкие", а бизнес-логика находится в сервисах.
• Человеко-понятные ID: Система использует легко читаемые идентификаторы для задач (PHX-1, PROJ-10).
• Контракты: Все взаимодействие происходит по строгим контрактам (DTO, OpenAPI), что гарантирует предсказуемость.

🔌 API Документация

Автоматически генерируемая интерактивная документация API (Swagger) доступна после запуска бэкенда по адресу:

http://localhost:3001/api/v1/api-docs

Используйте её для изучения и тестирования эндпоинтов.

💡 Точки расширения

1. Добавление новой AI-функции

Пример: Добавление функции "AI-генерация тегов для задачи"

1. ai.service.ts: Добавьте новый метод в сервис-адаптер.
2. tasks.controller.ts: Создайте новый эндпоинт, который вызывает сервис.
3. tasks.service.ts: Оркестрируйте вызов AiService и сохранение результата.

2. Интеграция с Git-репозиторием (Стратегическое направление)

• Шаг 1: Модель данных. Расширить модель Project, добавив поля для URL репозитория и токена доступа.
• Шаг 2: Сервис-адаптер. Создать GitService для работы с репозиторием.
• Шаг 3: Расширение AI. Научить AiService использовать контекст из файлов кода.

✅ Тестирование

• Backend: Мы используем Jest. Запуск: npm run test -w api.
• Frontend: Мы используем Vitest. Запуск: npm run test -w client.

Вы можете запустить генерацию отчетов о покрытии, используя команды test:cov.