docs: добавлены README.md

services/api/README.md

@@ -0,0 +1,40 @@
+# services/api
+
+## Назначение
+
+FastAPI‑сервис поверх TimescaleDB, который предоставляет REST‑доступ к аудио‑метрикам и агрегированным статистикам.
+
+## Основные endpoint’ы
+
+- `GET /api/v1/audio/latest?limit=100`
+  - Возвращает последние N точек `audio_data`.
+
+- `GET /api/v1/audio/range?from=<ts>&to=<ts>`
+  - Данные за заданный интервал, проверка `from < to`.
+
+- `GET /api/v1/stats/summary?period=1h`
+  - Агрегированная статистика (avg/max/min по dB, доминантная частота, процент тишины) по окну (`10s|1m|1h|6h|24h|7d|30d`).
+
+- `GET /api/v1/events/loud?threshold=-35&from=<ts>&to=<ts>`
+  - “Громкие” события, где `rms_db` выше порога, опционально с интервалом времени.
+
+- `GET /api/v1/export/csv?from=<ts>&to=<ts>`
+  - Экспорт диапазона в CSV: `time,rms_db,frequency_hz,is_silence`.
+
+- `GET /api/v1/health/live` / `ready`
+  - Примитивный healthcheck и проверка доступности БД.
+
+## Модель данных
+
+Таблица `audio_data` в TimescaleDB:
+
+```sql
+CREATE TABLE audio_data (
+    time TIMESTAMPTZ NOT NULL,
+    rms_db REAL CHECK (rms_db >= -50.0 AND rms_db <= 0.0),
+    frequency_hz INTEGER CHECK (frequency_hz >= 100 AND frequency_hz <= 8000),
+    is_silence BOOLEAN NOT NULL DEFAULT FALSE
+);
+```
+
+Плюс continuous aggregate `audio_data_1min` и политики retention/refresh.

services/collector/README.md

@@ -0,0 +1,34 @@
+# services/collector
+
+## Назначение
+
+Сервис, который читает бинарные пакеты с STM32 через USB CDC, валидирует и логирует их, пишет данные в TimescaleDB и рассылает в реальном времени по WebSocket.
+
+## Основные компоненты
+
+- `serial_reader.py` — асинхронное чтение порта `SERIAL_PORT` (`/dev/ttyACM0` по умолчанию), non‑blocking read, reconnect‑логика.
+- `protocol_parser.py` — парсер протокола: поиск SOF, проверка длины, CRC‑8/ATM, конвертация `rms_db_x10` → float.
+- `audio_validator.py` — проверка диапазонов: `rms_db ∈ [-50.0, 0.0]`, `frequency_hz ∈ [100, 8000]`, детекция и пометка тишины.
+- `db_writer.py` — batch‑запись в PostgreSQL/TimescaleDB (`audio_data`), батч по количеству/таймеру.
+- `ws_app.py` + `ws_manager.py` — WebSocket сервер, который бродкастит последние метрики всем подписчикам.
+- `monitor.py` — вывод статистики: пакетов/с, CRC‑ошибки, length‑ошибки, range‑ошибки.
+
+## Формат данных в WebSocket
+
+```json
+{
+  "time": "2025-12-25T19:00:00Z",
+  "rms_db": -18.5,
+  "freq_hz": 440
+}
+```
+
+Время берётся по хосту при приёме пакета, а не из MCU‑таймстампа, чтобы быть в одной временной зоне с БД.
+
+## Конфигурация
+
+Через переменные окружения (см. `.example.env` и `docker-compose.yml`):
+
+- `SERIAL_PORT`, `BAUDRATE`.
+- `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`.
+- `WS_HOST`, `WS_PORT` (по умолчанию `0.0.0.0:8000`, наружу проброшен как `8001`).