# PROJECT_KNOWLEDGE.md — ACS Monitoring (СКУД + Датчики воды)

## Что это

ACS Monitoring — система мониторинга и контроля доступа на базе ESP32.

**Два направления:**
1. **Датчики воды** — мониторинг расхода воды, давления, утечек. ESP32-сенсоры → MQTT → backend → frontend.
2. **СКУД (контроль доступа)** — 15 дверей с Wiegand RFID. ESP32-контроллер на каждую дверь, управление через веб-панель.

---

## Сервер

| Параметр | Значение |
|---|---|
| IP | 77.222.43.248 |
| SSH | root@77.222.43.248 |
| Домен | acs.zeroday.su |
| OS | Ubuntu 24.04 |
| Node.js | v22.22.0 |
| Nginx | 1.24.0 |
| MCP коннектор | dev.zeroday.su (server-connector) |

---

## Пути на сервере

```
/var/www/acs-monitoring/
├── backend/
│   ├── src/
│   │   ├── index.ts               # точка входа, Express + MQTT
│   │   ├── api/                   # REST routes
│   │   │   ├── access-keys.ts     # СКУД: ключи доступа
│   │   │   ├── access.ts          # СКУД: журнал событий
│   │   │   ├── alerts.ts
│   │   │   ├── auth.ts            # JWT авторизация
│   │   │   ├── backups.ts
│   │   │   ├── dashboard.ts
│   │   │   ├── devices.ts         # СКУД: устройства (двери)
│   │   │   ├── dictionaries.ts
│   │   │   ├── discovery.ts       # обнаружение новых устройств
│   │   │   ├── employees.ts       # СКУД: сотрудники
│   │   │   ├── firmware.ts        # управление прошивками
│   │   │   ├── registration-station.ts  # станция регистрации карт
│   │   │   ├── sensors.ts         # датчики воды
│   │   │   ├── telegram.ts
│   │   │   ├── users.ts
│   │   │   └── water.ts           # данные расхода воды
│   │   ├── mqtt/
│   │   │   ├── index.ts           # MQTT клиент (mosquitto)
│   │   │   ├── handlers.ts        # обработчики датчиков воды
│   │   │   └── skud-handlers.ts   # обработчики СКУД
│   │   ├── database/              # pg pool, migrations
│   │   ├── middleware/            # JWT, CORS, rate limit
│   │   ├── services/
│   │   └── utils/
│   └── .env                       # переменные окружения
├── frontend/
│   ├── src/
│   │   ├── App.tsx                # роутинг (hash routing)
│   │   ├── pages/
│   │   │   ├── SCUD/              # страницы контроля доступа
│   │   │   │   ├── AccessLogPage.tsx    # журнал событий (группировка по дате, пагинация, CSV)
│   │   │   │   ├── AccessKeysPage.tsx   # RFID карты
│   │   │   │   ├── DevicesPage.tsx      # двери (open door, сеть, команды)
│   │   │   │   ├── EmployeesPage.tsx    # сотрудники
│   │   │   │   ├── FirmwarePage.tsx     # прошивки (OTA push, стабильная/бета)
│   │   │   │   └── DiscoveryPage.tsx    # поиск новых устройств
│   │   │   ├── Sensors/           # датчики воды
│   │   │   ├── Dashboard/
│   │   │   ├── Auth/
│   │   │   └── Admin/
│   │   └── services/
│   │       └── api.ts             # все API вызовы
│   └── dist/                      # собранный фронтенд (nginx)
├── firmware/
│   ├── door-controller-v2.0/      # Production СКУД прошивка
│   │   ├── door_controller_v2.ino
│   │   ├── config.h
│   │   ├── mqtt_handler.h
│   │   ├── web_config.h           # AP Mode web configurator
│   │   ├── wiegand_reader.h
│   │   ├── card_cache.h           # NVS кеш до 10,000 карт
│   │   ├── event_queue.h          # offline очередь до 500 событий
│   │   └── README.md
│   ├── water-sensor-v3.3.2/       # Последняя стабильная прошивка датчика воды
│   └── ota_module.ino
└── scripts/                       # bash скрипты
```

---

## PM2 процессы

```bash
pm2 list                           # все процессы
pm2 logs acs-monitoring --lines 50 # логи СКУД
pm2 restart acs-monitoring         # рестарт
```

> ⚠️ Сейчас `acs-monitoring` в статусе **stopped** (238+ рестартов). Вероятно упал по ошибке.

---

## База данных PostgreSQL

- **Хост**: localhost:5432
- **База**: acs_monitoring
- **Пользователь**: acs_user
- **Пароль**: в `/var/www/acs-monitoring/backend/.env`

### Таблицы

| Таблица | Назначение |
|---|---|
| `devices` | ESP32 устройства (двери, датчики) |
| `employees` | Сотрудники |
| `access_keys` | RFID карты и RF брелоки |
| `access_events` | Журнал событий доступа |
| `device_commands` | Очередь команд устройствам |
| `device_discovery` | Обнаруженные новые устройства |
| `device_network_config` | Сетевые настройки устройств (static IP) |
| `firmware` | Версии прошивок |
| `firmware_updates` | История OTA обновлений |
| `sensors` | Датчики воды |
| `water_data` | Показания расхода воды |
| `pressure_data` | Данные давления |
| `electricity_data` | Электроэнергия (планируется) |
| `alerts` | Алерты системы |
| `users` | Пользователи веб-панели |
| `departments` | Отделы |
| `positions` | Должности |
| `telegram_settings` | Настройки Telegram уведомлений |

---

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

### Backend
- Node.js v22 + Express + TypeScript
- PostgreSQL + pg
- MQTT: Mosquitto (порт 1883, WS: 8883)
- Socket.IO — real-time обновления
- JWT авторизация
- PM2 (порт 3003)

### Frontend
- React 18 + Vite + TypeScript
- shadcn/ui (Card, Table, Dialog, Badge, Select, Input...)
- Lucide React иконки
- Hash routing (без React Router)
- Chart.js — графики

### ESP32 (СКУД — Door Controller v2.0)
- Arduino Framework
- WiFi (встроенная)
- PubSubClient (MQTT)
- ArduinoJson
- ArduinoOTA
- Preferences/NVS — хранение конфига и кеша карт

### ESP32 (Датчики воды — v3.5.x)
- Arduino Framework + SPIFFS (журналирование)
- MQTT с journal-first архитектурой
- NTP синхронизация времени
- OTA обновления

---

## Распиновка ESP32 (СКУД)

```
GPIO 26 ← Wiegand D0 (зелёный провод)
GPIO 27 ← Wiegand D1 (белый провод)
GPIO 25 → Relay IN  (управление замком)
GPIO 33 ← Кнопка выхода → GND
GPIO 32 → Buzzer (опционально)
GPIO  2   LED статус (встроенный)
VIN/5V  ← Mini560 OUT+ (5.0V!)
GND     ← Общий GND
```

---

## MQTT топики (СКУД)

| Топик | Направление | Описание |
|---|---|---|
| `skud/{device_id}/status` | ESP→Server | Heartbeat каждые 30 сек |
| `skud/{device_id}/access` | ESP→Server | Событие прохода |
| `skud/{device_id}/sync` | ESP↔Server | Синхронизация карт / batch offline событий |
| `devices/provision` | ESP→Server | Активация нового устройства |
| `skud/{device_id}/command` | Server→ESP | Команды (open_door, reboot, sync_cards...) |
| `skud/{device_id}/provision/ack` | Server→ESP | Ответ на provision |

---

## Команды устройствам (СКУД)

| Команда | Описание |
|---|---|
| `open_door` | Открыть дверь (+duration мс) |
| `close_door` | Закрыть дверь |
| `sync_cards` | Пересинхронизация кеша карт |
| `sync_time` | Синхронизация NTP |
| `reboot` | Перезагрузка |
| `factory_reset` | Сброс настроек |
| `set_door_duration` | Изменить время открытия |

---

## Переменные окружения (без секретов)

```env
PORT=3003
NODE_ENV=production
DB_HOST=localhost
DB_PORT=5432
DB_NAME=acs_monitoring
DB_USER=acs_user
DB_PASSWORD=<в .env на сервере>
MQTT_HOST=localhost
MQTT_PORT=1883
MQTT_WS_PORT=8883
JWT_SECRET=<в .env на сервере>
FRONTEND_URL=https://acs.zeroday.su
TELEGRAM_CHAT_ID=<опционально>
```

---

## Деплой

```bash
# Frontend — сборка и деплой
cd /var/www/acs-monitoring/frontend
npm run build
# nginx отдаёт из /var/www/acs-monitoring/frontend/dist/

# Backend — применить изменения
cd /var/www/acs-monitoring/backend
npm run build
pm2 restart acs-monitoring

# Логи
pm2 logs acs-monitoring --lines 100
```

---

## Hardware (1 дверь)

| Компонент | Модель | Примечание |
|---|---|---|
| Контроллер | ESP32 DevKit 30-pin Type-C | — |
| Считыватель | Wiegand RFID 26/34 bit | 12V питание |
| Реле | 5V 1-канальное | IN: GPIO 25 |
| Преобразователь | Mini560 (12V→5V) | Точно 5.0V! |
| БП | 12V 2A | — |
| АКБ | 12V 7Ah | Резерв питания 2-6 дней |
| Замок | Электромагнитный 12V | NO контакты реле |
| Кнопка | Кнопка выхода | GPIO 33 → GND |

**Стоимость 1 двери:** ~4 750 ₽  
**Стоимость 15 дверей:** ~71 250 ₽

---

*Обновлено: май 2026*