mkd/README.md

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

<div align="center">
<img width="1200" height="475" alt="GHBanner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" />
</div>

Веб-приложение для комплексного управления многоквартирными домами (МКД), включающее модули для управления объектами, финансами, кадрами, юридическими вопросами, 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. Установка зависимостей

```bash
npm install
```

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

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

```env
# 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):

```bash
sudo bash scripts/setup-postgres-ubuntu.sh
```

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

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

```bash
npm run dev
```

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

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

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

```bash
bash scripts/start-tmux.sh
```

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

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

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

```bash
npm run build
```

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

```bash
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](https://ai.studio/apps/drive/1jOVxm30BucP1pvw8ODxuHe3FC-Xaww9E)
- [Документация Doma AI API](https://developers.doma.ai/ru/docs/index)
- [Doma AI API Playground](https://condo.d.doma.ai/admin/api)