mkd/README.md

Центр управления жилым фондом (МКД)

Веб-приложение для комплексного управления многоквартирными домами (МКД), включающее модули для управления объектами, финансами, кадрами, юридическими вопросами, PR-деятельностью и офисной работой.

🚀 Возможности

Основные модули:

• 📊 Дашборд - Общая сводка и аналитика по всем направлениям
• 🏢 Объекты - Управление зданиями, характеристиками, осмотрами, планами работ
• 📝 Заявки - Реестр заявок жильцов, контроль качества, диспетчеризация
• 💰 Финансы - Управление счетами, платежами, дебиторской задолженностью, отчетностью
• 👥 HR - Управление персоналом, вакансиями, наймом, зарплатами
• ⚖️ Юридический - Договоры, судебные дела, взыскание долгов, доверенности
• 📢 PR - Управление событиями, обратной связью жильцов, SMM, негативными ситуациями
• 🏛️ Офис - Документооборот, управление помещениями, база знаний, закупки
• 🔧 Развитие - Технический аудит, маркетинговые кампании, работа с ОСС

Система ролей:

Приложение поддерживает различные роли пользователей с разными уровнями доступа:

• Директор - Полный доступ ко всем модулям
• Главный инженер - Дашборд, объекты, заявки, офис, развитие
• Мастер - Объекты, заявки
• Юрист - Дашборд, юридический, объекты, заявки
• Финансист - Дашборд, финансы, офис, объекты
• HR-менеджер - Дашборд, HR, офис
• PR-менеджер - Дашборд, PR, заявки

🛠️ Технологии

• React 19 - UI библиотека
• TypeScript - Типизация
• Vite - Сборщик и dev-сервер
• Tailwind CSS - Стилизация
• Lucide React - Иконки
• html2canvas & jsPDF - Экспорт в PDF

📋 Требования

• Node.js (рекомендуется версия 18+)

🚀 Установка и запуск

1. Установка зависимостей

npm install

2. Настройка переменных окружения

Создайте файл .env.local в корне проекта на основе .env.example:

# API Configuration
VITE_API_BASE_URL=http://localhost:4000/api

# Doma AI API Configuration
# URL API Doma AI (по умолчанию используется тестовый стенд)
VITE_DOMA_AI_API_URL=https://condo.d.doma.ai/admin/api

# Учетные данные для авторизации в Doma AI
# Используйте email и пароль ИЛИ телефон и пароль
VITE_DOMA_AI_EMAIL=your-email@example.com
VITE_DOMA_AI_PASSWORD=your-password
# ИЛИ используйте телефон:
# VITE_DOMA_AI_PHONE=+79991234567

Настройка интеграции с Doma AI (PRODUCTION):

1. Получите URL API вашего продакшн инстанса Doma AI (обычно: https://your-domain.doma.ai/admin/api)
2. Убедитесь, что у вас есть учетные данные для доступа к API
3. Укажите URL API и учетные данные в переменных окружения:
   • VITE_DOMA_AI_API_URL - URL вашего инстанса Doma AI
   • VITE_DOMA_AI_EMAIL / VITE_DOMA_AI_PHONE - учетные данные
   • VITE_DOMA_AI_PASSWORD - пароль
4. При первом запуске приложение автоматически авторизуется в Doma AI
5. Заявки будут автоматически загружаться из Doma AI в раздел "Заявки"

Для тестирования можно использовать тестовый стенд: https://condo.d.doma.ai/

3. (Ubuntu) Один раз настройте PostgreSQL

Логин и пароль БД заданы в backend/.env (логин: mkd_user, пароль: MkdUbuntu24Secure). Выполните в терминале (введёте пароль sudo):

sudo bash scripts/setup-postgres-ubuntu.sh

Затем в одном терминале: cd backend && npm start, в другом: npm run dev.

4. Запуск в режиме разработки

npm run dev

Приложение будет доступно по адресу: http://localhost:3000

4.1. Запуск в tmux (не зависит от SSH)

Бэкенд и фронт в tmux-сессиях back и front — после отключения SSH процессы продолжают работать.

bash scripts/start-tmux.sh

• Подключиться к логам: tmux attach -t back или tmux attach -t front
• Выйти из tmux без остановки: Ctrl+B, затем D
• Список сессий: tmux ls

Доступ снаружи (если открыты порты в файрволе): http://<IP-сервера>:3000 (фронт), http://<IP-сервера>:4000/api (API). На Ubuntu при необходимости: sudo ufw allow 3000 && sudo ufw allow 4000 && sudo ufw reload

5. Сборка для продакшена

npm run build

6. Просмотр production сборки

npm run preview

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

├── components/          # React компоненты
│   ├── applications/    # Модуль заявок
│   ├── building/        # Компоненты для работы со зданиями
│   ├── development/     # Модуль развития
│   ├── finance/         # Финансовый модуль
│   ├── hr/              # HR модуль
│   ├── legal/           # Юридический модуль
│   ├── objects/         # Компоненты объектов
│   ├── office/          # Офисный модуль
│   └── pr/              # PR модуль
├── services/            # Сервисы (API, storage, etc.)
├── types.ts             # TypeScript типы
├── constants.tsx        # Константы и моки
├── App.tsx              # Главный компонент
├── index.tsx            # Точка входа
└── vite.config.ts       # Конфигурация Vite

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

Vite конфигурация

Проект настроен для работы с прокси-сервером API:

• Dev сервер: http://localhost:3000
• API прокси: /api → https://n8n.iieasy.ru/

Настройки можно изменить в vite.config.ts.

📝 Особенности

• Локальное хранилище - Сохранение состояния выбранных зданий и активных вкладок
• Адаптивный дизайн - Поддержка мобильных устройств
• Система ролей - Контроль доступа на основе ролей пользователей
• Экспорт данных - Возможность экспорта отчетов в PDF
• Интеграция с Doma AI - Автоматическая синхронизация заявок через GraphQL API

🎯 Разработка

Добавление нового модуля

1. Создайте компонент модуля в components/
2. Добавьте навигационный элемент в constants.tsx
3. Добавьте обработку в App.tsx в функции renderContent()
4. Настройте права доступа в ROLE_ACCESS в App.tsx

Работа с типами

Все типы определены в types.ts. При добавлении новых сущностей обновите соответствующие типы.

📄 Лицензия

Проект разработан для внутреннего использования.

🔗 Ссылки

• AI Studio
• Документация Doma AI API
• Doma AI API Playground