LiftPlatform

Цифровая платформа управления лифтовым оборудованием — реестр, ТО, инциденты, контракты, SLA, аналитика и AI-модуль.

Содержание

• Возможности
• Технологии
• Быстрый старт
• Структура проекта
• Скрипты
• Переменные окружения
• Роли и доступ
• AI-модуль (Gemini)
• Документация
• Метрики

Возможности

Модуль	Описание
Реестр лифтов	40+ полей, QR-коды, PDF-паспорт, ИТС-оценка, мягкое удаление
Обслуживание	6 типов ТО, state machine статусов, назначение техников, cron-автосоздание
Инциденты	4 уровня критичности, workflow, комментарии, привязка к лифтам
Заявки жителей	Публичная форма, QR, спам-защита (honeypot + rate limit + дубликаты), AI-триаж
Контракты	Привязка лифтов, SLA, оповещение об истечении
Документы	Загрузка/скачивание, magic bytes валидация, привязка к лифтам/организациям
SLA-мониторинг	Автоматическая проверка по cron, эскалация, email-уведомления
Аналитика	Дашборд с KPI, экспорт в Excel, графики
AI-модуль	Авто-триаж, предиктивное обслуживание, чат-ассистент, маршрутизация, голосовой ввод
Уведомления	SSE real-time, in-app, email (5 шаблонов)
Аудит	Логирование всех действий с IP и деталями
i18n	Русский, казахский, английский
PWA	Offline-режим, IndexedDB очередь, background sync
WhatsApp	Опциональная интеграция (шлюз)

Технологии

Категория	Стек
Runtime	Node.js 22, Next.js 16.1.6 (App Router, standalone)
Frontend	React 19, TypeScript 5 (strict), Tailwind CSS 4, lucide-react
Backend	API Routes, Middleware (JWT + RBAC + security headers + rate limiting)
Database	PostgreSQL 16, raw SQL через pg (repository pattern, без ORM)
Auth	JWT (jose) + Argon2 + RBAC (6 ролей, 27 permissions)
Validation	Zod 4
AI	Google Gemini 2.0 Flash (@google/genai)
Testing	Vitest 4 (84 тестов, 12 файлов)
Deploy	Docker + Docker Compose, multi-stage build (~150MB image)
CI	GitHub Actions (lint → typecheck → test → build)

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

Docker (рекомендуется)

git clone <repo-url> && cd lift-platform
cp .env.example .env
# Отредактируйте .env — обязательно: NEXTAUTH_SECRET, POSTGRES_PASSWORD, CRON_SECRET
docker compose up -d
# → http://localhost:3091

Локальная разработка

# Требования: Node.js 22+, PostgreSQL 16+
npm install

# Создайте БД и примените миграции:
createdb -U postgres lift_platform
npm run migrate

# Запуск dev-сервера:
npm run dev
# → http://localhost:3090

Демо-аккаунты

Email	Пароль	Роль
admin@liftplatform.kz	admin123	admin
master@liftservice.kz	admin123	technician
manager@liftservice.kz	admin123	org_admin
director@zhilkomfort.kz	admin123	manager
inspector@liftplatform.kz	admin123	inspector

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

src/
├── app/
│   ├── (app)/                 # Авторизованные страницы (49 pages)
│   │   ├── dashboard/         # Главная с KPI
│   │   ├── elevators/         # Реестр лифтов (CRUD + паспорт + ИТС)
│   │   ├── maintenance/       # Техобслуживание
│   │   ├── incidents/         # Инциденты + комментарии
│   │   ├── resident-requests/ # Заявки жителей (менеджер)
│   │   ├── contracts/         # Контракты
│   │   ├── organizations/     # Организации
│   │   ├── users/             # Пользователи
│   │   ├── ai/                # AI-модуль (прогнозы, чат, маршруты)
│   │   ├── analytics/         # Аналитика + Excel
│   │   ├── reports/           # Отчёты
│   │   ├── technician/        # Кабинет техника
│   │   ├── inspector/         # Режим обходчика (QR-сканер)
│   │   ├── whatsapp/          # WhatsApp-шлюз
│   │   └── audit-log/         # Журнал действий
│   ├── (public)/              # Публичные страницы (без авторизации)
│   │   ├── request/           # Форма заявки от жителя
│   │   └── request/status/    # Проверка статуса заявки
│   ├── api/                   # REST API (71 эндпоинт)
│   └── login/                 # Авторизация
├── components/                # React компоненты (22)
├── lib/
│   ├── ai/                    # AI-сервисы (Gemini integration)
│   ├── auth/                  # JWT + RBAC
│   ├── db/                    # Подключение к БД + репозитории (17 файлов)
│   ├── email/                 # SMTP + шаблоны
│   ├── i18n/                  # Интернационализация (ru/kz/en)
│   ├── pdf/                   # PDF-генерация
│   ├── services/              # Бизнес-логика (service layer)
│   └── workflows/             # State machines (статусы)
├── middleware.ts               # JWT, RBAC, headers, rate limiting
tests/
├── api/                       # API тесты (8 файлов)
└── lib/                       # Unit тесты (4 файла)
prisma/
├── schema.sql                 # Основная схема
└── migration-*.sql            # Инкрементальные миграции (17 файлов)

Скрипты

Команда	Описание
npm run dev	Dev-сервер (http://localhost:3090)
npm run build	Production build
npm run start	Запуск production
npm run lint	ESLint проверка
npm run typecheck	TypeScript strict check
npm run test	Запуск тестов (Vitest)
npm run test:watch	Тесты в watch-режиме
npm run migrate	Применить миграции БД
npm run migrate:status	Статус миграций

Переменные окружения

См. .env.example — полный список.

Переменная	Обязательная	Описание
DATABASE_URL	✅	PostgreSQL connection string
NEXTAUTH_SECRET	✅	JWT signing secret (HS256)
CRON_SECRET	✅	Secret для SLA/AI cron-задач
SMTP_ENABLED	—	Email уведомления (true/false)
SMTP_HOST/USER/PASS	—	SMTP сервер
WA_ENABLED	—	WhatsApp интеграция
AI_ENABLED	—	AI-модуль (Gemini)
GEMINI_API_KEY	—	Google Gemini API key
LOG_LEVEL	—	debug / info / warn / error

Роли и доступ

Роль	Описание	Ключевые возможности
admin	Администратор	Полный доступ, управление пользователями, аудит
org_admin	Админ организации	CRUD в рамках своей организации
manager	Менеджер	Заявки жителей, аналитика, контракты
technician	Техник	ТО, инциденты, AI-чат, кабинет техника
inspector	Инспектор	Осмотры, QR-сканер, кросс-организационный доступ
viewer	Наблюдатель	Только просмотр

AI-модуль (Gemini)

Интеграция с Google Gemini 2.0 Flash для 5 функций:

Функция	Описание	Триггер
Авто-триаж	Классификация приоритета/категории заявок, определение дубликатов	Автоматически при создании заявки
Предиктивное обслуживание	Оценка рисков для каждого лифта (0-100)	Cron (ежедневно) или вручную
AI-ассистент	Чат с контекстом из БД (лифты, ТО, инциденты)	Страница /ai/chat
Умная маршрутизация	Оптимизация маршрутов техников	Cron (ежедневно) или вручную
Голосовой ввод	Транскрипция + извлечение данных из WhatsApp voice	Через WA-gateway

Активация:

AI_ENABLED=true
GEMINI_API_KEY=your-key

Cron для AI-задач:

0 7 * * * curl -X POST -H 'X-Cron-Secret: ...' http://localhost:3091/api/ai/cron

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

Документ	Описание
CHANGELOG.md	История версий
docs/PRD.md	Требования к продукту
docs/api/API-SPEC.md	API спецификация (71 endpoint)
docs/DATABASE.md	Схема БД (35 таблиц)
docs/DEVELOPMENT.md	Руководство разработчика
docs/DEPLOYMENT.md	Деплой и эксплуатация
docs/architecture/	ADR (архитектурные решения)
CONTRIBUTING.md	Правила участия в разработке
SECURITY.md	Политика безопасности

Метрики

Показатель	Значение
Файлы TypeScript/TSX	216
Строки кода	~31,000
API endpoints	71
Страницы	49
Компоненты	22
Таблицы БД	35
Миграции SQL	17
Тесты	84 (Vitest)
Языки (i18n)	3 (ru, kz, en)
RBAC permissions	27

Лицензия

MIT