248 lines
6.2 KiB
Markdown
248 lines
6.2 KiB
Markdown
# 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+
|
||
|
||
### Установка
|
||
|
||
```bash
|
||
# Установить pnpm глобально (если еще не установлен)
|
||
npm install -g pnpm
|
||
|
||
# Установить все зависимости для всех пакетов
|
||
pnpm install
|
||
```
|
||
|
||
### Разработка
|
||
|
||
```bash
|
||
# Запустить все приложения в режиме разработки
|
||
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`
|
||
|
||
### Сборка
|
||
|
||
```bash
|
||
# Собрать все приложения (с кешированием через Turborepo)
|
||
pnpm build
|
||
|
||
# Собрать только backend
|
||
pnpm --filter @home-service/backend build
|
||
|
||
# Собрать только frontend
|
||
pnpm --filter @home-service/frontend build
|
||
```
|
||
|
||
### Другие команды
|
||
|
||
```bash
|
||
# Линтинг всех пакетов
|
||
pnpm lint
|
||
|
||
# Форматирование (для backend с Biome)
|
||
pnpm format
|
||
|
||
# Тестирование
|
||
pnpm test
|
||
|
||
# Очистка всех node_modules и кеша
|
||
pnpm clean
|
||
```
|
||
|
||
## API Endpoints
|
||
|
||
### GET /countdown
|
||
Главный endpoint для виджета Glance. Возвращает все события с расчетами.
|
||
|
||
**Ответ:**
|
||
```json
|
||
{
|
||
"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:**
|
||
```json
|
||
{
|
||
"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:
|
||
|
||
```bash
|
||
# Пример импорта события
|
||
curl -X POST http://localhost:3000/api/events \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"title":"Новый год","emoji":"🎄","month":1,"day":1}'
|
||
```
|
||
|
||
## 🚢 Production
|
||
|
||
### Все приложения
|
||
```bash
|
||
pnpm build
|
||
pnpm --filter @home-service/backend start:prod
|
||
pnpm --filter @home-service/frontend start
|
||
```
|
||
|
||
### Backend отдельно
|
||
```bash
|
||
pnpm --filter @home-service/backend build
|
||
pnpm --filter @home-service/backend start:prod
|
||
```
|
||
|
||
### Frontend отдельно
|
||
```bash
|
||
pnpm --filter @home-service/frontend build
|
||
pnpm --filter @home-service/frontend start
|
||
```
|
||
|
||
## 🛠️ Разработка
|
||
|
||
### Создание миграции
|
||
```bash
|
||
pnpm --filter @home-service/backend exec drizzle-kit generate
|
||
```
|
||
|
||
### Применение миграций
|
||
Миграции применяются автоматически при старте приложения.
|
||
|
||
### Работа с Turborepo
|
||
|
||
**Кеширование:**
|
||
Turborepo автоматически кеширует результаты сборок. При повторном запуске `pnpm build` без изменений файлов, сборка завершится мгновенно.
|
||
|
||
**Очистка кеша:**
|
||
```bash
|
||
rm -rf .turbo
|
||
# или
|
||
pnpm clean
|
||
```
|
||
|
||
## Лицензия
|
||
|
||
MIT
|