home-service/README.md

home-service

Современный монорепозиторий для сервиса домашней автоматизации с бэкендом и фронтенд-панелью.

🚀 Стек технологий

Инфраструктура:

• Turborepo - система сборки монорепозитория
• pnpm Workspaces - управление зависимостями

Backend:

• NestJS 10
• PGLite (встроенная PostgreSQL БД)
• Drizzle ORM
• Zod для валидации
• date-fns для работы с датами

Frontend:

• Next.js 16 (App Router)
• React 19
• TailwindCSS 4
• TypeScript

📁 Структура проекта

home-service/
├── backend/          # NestJS API (@home-service/backend)
│   ├── src/
│   │   ├── database/      # Схема БД и модуль
│   │   ├── events/        # Модуль событий
│   │   ├── utils/         # Утилиты для дат
│   │   └── pipes/         # Zod validation pipe
│   ├── migrations/        # Миграции БД
│   └── data/             # База данных PGLite
│
├── frontend/         # Next.js админка (@home-service/frontend)
│   └── src/
│       ├── app/          # Страницы
│       ├── components/   # React компоненты
│       └── lib/          # API клиент
│
├── turbo.json        # Конфигурация Turborepo
├── pnpm-workspace.yaml  # Конфигурация pnpm workspaces
└── package.json      # Корневой package.json

🎯 Типы событий

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

1. recurring - Обычное повторяющееся событие

   • Поля: month, day
   • Пример: Новый год, 8 марта

2. anniversary - Годовщина с отслеживанием времени

   • Поля: month, day, startYear
   • Пример: день рождения, свадьба

3. duration - Продолжительное событие

   • Поля: month, day, startYear, endMonth, endDay, endYear
   • Пример: отпуск, командировка

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

Требования

• Node.js 20+
• pnpm 9+

Установка

# Установить pnpm глобально (если еще не установлен)
npm install -g pnpm

# Установить все зависимости для всех пакетов
pnpm install

Разработка

# Запустить все приложения в режиме разработки
pnpm dev

# Запустить только backend
pnpm --filter @home-service/backend dev

# Запустить только frontend
pnpm --filter @home-service/frontend dev

Адреса:

• Backend API: http://localhost:3000
• Frontend панель: http://localhost:3001

Сборка

# Собрать все приложения (с кешированием через Turborepo)
pnpm build

# Собрать только backend
pnpm --filter @home-service/backend build

# Собрать только frontend
pnpm --filter @home-service/frontend build

Другие команды

# Линтинг всех пакетов
pnpm lint

# Форматирование (для backend с Biome)
pnpm format

# Тестирование
pnpm test

# Очистка всех node_modules и кеша
pnpm clean

API Endpoints

GET /countdown

Главный endpoint для виджета Glance. Возвращает все события с расчетами.

Ответ:

{
  "events": [
    {
      "id": "uuid",
      "type": "recurring",
      "emoji": "🎄",
      "name": "Новый год",
      "date": "2026-01-01",
      "display": "365д 5ч 36м",
      "days": 365,
      "hours": 5,
      "minutes": 36
    }
  ],
  "current": {
    "year": 2025,
    "month": 11,
    "day": 29
  },
  "months": [...],
  "timelineGrid": [...]
}

GET /api/events

Получить все события

POST /api/events

Создать новое событие

Body:

{
  "title": "День рождения",
  "emoji": "🎂",
  "month": 6,
  "day": 15,
  "startYear": 1990
}

DELETE /api/events/:id

Удалить событие

Конфигурация

Backend (.env)

PORT=3000
CORS_ORIGIN=http://localhost:3001
DATABASE_PATH=./data/events.db

Frontend (.env.local)

NEXT_PUBLIC_API_URL=http://localhost:3000

Миграция данных

Для импорта событий из старого Python бэкенда можно использовать API:

# Пример импорта события
curl -X POST http://localhost:3000/api/events \
  -H "Content-Type: application/json" \
  -d '{"title":"Новый год","emoji":"🎄","month":1,"day":1}'

🚢 Production

Все приложения

pnpm build
pnpm --filter @home-service/backend start:prod
pnpm --filter @home-service/frontend start

Backend отдельно

pnpm --filter @home-service/backend build
pnpm --filter @home-service/backend start:prod

Frontend отдельно

pnpm --filter @home-service/frontend build
pnpm --filter @home-service/frontend start

🛠️ Разработка

Создание миграции

pnpm --filter @home-service/backend exec drizzle-kit generate

Применение миграций

Миграции применяются автоматически при старте приложения.

Работа с Turborepo

Кеширование: Turborepo автоматически кеширует результаты сборок. При повторном запуске pnpm build без изменений файлов, сборка завершится мгновенно.

Очистка кеша:

rm -rf .turbo
# или
pnpm clean

Лицензия

MIT