admin/manure-removal-owen
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

create PROJECT_KNOWLEDGE.md via Claude

Browse Source
This commit is contained in:
admin
2026-05-03 10:39:14 +00:00
parent 802671f443
commit 39d91cedce
1 changed files with 271 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PROJECT_KNOWLEDGE.md
+271
View File
@@ -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*