diff --git a/PROJECT_KNOWLEDGE.md b/PROJECT_KNOWLEDGE.md new file mode 100644 index 0000000..a694bcd --- /dev/null +++ b/PROJECT_KNOWLEDGE.md @@ -0,0 +1,271 @@ +# 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*