README: описание сервиса, архитектура, команды, эндпоинты

Добавлен файл pravila.md (адаптация под IoT)
2026-05-11 07:28:42 +04:00 · 2026-05-11 07:22:08 +04:00
2 changed files with 170 additions and 0 deletions
@@ -0,0 +1,99 @@
+# Правила работы агента
+
+## ⛔⛔⛔ DOCKER — ОБЯЗАТЕЛЬНЫЙ ПОРЯДОК ПЕРЕД КАЖДЫМ BUILD
+
+1. УВЕЛИЧИТЬ ТЕГ в `deployments/k8s/iot-console.yaml` (vX.Y.Z → vX.Y.Z+1)
+2. rsync на ВМ
+3. ПРОВЕРИТЬ что файлы на ВМ новые (grep ключевой строки)
+4. docker build с НОВЫМ тегом
+5. docker push с НОВЫМ тегом
+6. kubectl apply (не rollout restart — apply подтягивает новый тег)
+
+**НИКОГДА не делать `docker build` со старым тегом — под не перетянет образ (imagePullPolicy: IfNotPresent)**
+
+## Файловая система (актуально)
+
+1. Все файлы редактируются локально: `~/IoT`
+2. После любых изменений — обязательно rsync на ВМ:
+   rsync -az \
+     -e "ssh -i ~/.ssh/naeel_vm_id_ed25519 -o StrictHostKeyChecking=no -o ConnectTimeout=10" \
+     ~/IoT/ \
+     naeel@5.172.178.213:~/terra/IoT/
+
+3. Git (add/commit/push) выполнять ЛОКАЛЬНО в ~/IoT
+4. Docker, kubectl и другие инфраструктурные команды — только через SSH на ВМ
+5. Перед запуском любой команды на ВМ обязательно убедиться, что синхронизация (rsync) выполнена
+6. SCP, sshfs, remote_dev и маунты больше НЕ используются
+7. Только rsync для синхронизации
+
+Пример:
+1. Редактируешь локально
+2. rsync на ВМ
+3. Выполняешь команды через SSH на ВМ
+
+## SSH
+
+Все команды — только через SSH на ВМ. Локально — только читать и редактировать файлы.
+
+```bash
+ssh -i ~/.ssh/naeel_vm_id_ed25519 -o StrictHostKeyChecking=no -o ConnectTimeout=10 naeel@5.172.178.213 'КОМАНДА'
+```
+
+Запрещено локально: `go`, `docker`, `kubectl`, `helm`, `terraform`, `curl/wget`, `git push/pull`, любые скрипты проекта.
+
+## Документация
+
+- `doc/thinking/` — лог рассуждений агента (обязательно)
+- `doc/progress.md` — трекер задач
+- Старые файлы `doc/` не перезаписывать — новое в новых файлах с датой
+
+## Git
+
+⛔⛔⛔ АБСОЛЮТНОЕ ПРАВИЛО:
+- Git — ТОЛЬКО ЛОКАЛЬНО в `~/IoT`. НИКОГДА через SSH на VM.
+- Разрешены ТОЛЬКО две операции: `git commit` и `git push`.
+- ЗАПРЕЩЕНО: git pull, git fetch, git rebase, git merge, git reset, git stash, git checkout — что угодно кроме commit и push.
+- Если push отклонён — СТОП, доложить пользователю. Не лезть в pull/merge/rebase самостоятельно.
+
+Версионирование тегами: `vMAJOR.MINOR.PATCH`
+- Patch — любое изменение кода
+- Minor — новая фича / компонент
+- Major — breaking change
+
+```bash
+git tag vX.Y.Z && git push origin vX.Y.Z
+```
+
+## ⛔ ТЕРМИНАЛЬНЫЙ БУФЕР — НИКОГДА НЕ ЧИТАТЬ СТАРЫЙ
+
+**АБСОЛЮТНОЕ ПРАВИЛО:**
+- get_terminal_output из старых сессий — МУСОР. Там старые прогоны.
+- Всегда запускать новую команду через SSH и читать её вывод напрямую.
+- НИКОГДА не читать буфер терминала из предыдущей сессии как актуальные данные.
+- Актуальный результат — только из команды, которая была запущена СЕЙЧАС.
+
+## ⛔ ДОКУМЕНТАЦИЯ ТЕСТ-ПРОГОН�ОВ — В РЕАЛЬНОМ ВРЕМЕНИ
+
+**Правила:**
+1. Перед запуском `run_all.sh` — создать файл `test-results/YYYY-MM-DD_HH-MM.log` и записать в него метку времени и что запускается.
+2. Запускать `run_all.sh 2>&1 | tee ~/terra/IoT/test-results/YYYY-MM-DD_HH-MM.log` — вывод пишется сразу в файл и отображается в терминале.
+3. После завершения — rsync лога локально. Лог остаётся как документация.
+4. Папка `test-results/` в репозитории — `.gitignore` не добавлять, логи коммитить.
+
+**Формат запуска:**
+```bash
+LOG="test-results/$(date +%Y-%m-%d_%H-%M).log"
+ssh -i ~/.ssh/naeel_vm_id_ed25519 -o StrictHostKeyChecking=no naeel@5.172.178.213 \
+  "bash ~/terra/IoT/scripts/run_all.sh 2>&1 | tee ~/terra/IoT/${LOG}"
+rsync -az -e "ssh -i ~/.ssh/naeel_vm_id_ed25519 -o StrictHostKeyChecking=no" \
+  naeel@5.172.178.213:~/terra/IoT/test-results/ ~/IoT/test-results/
+```
+
+**Никогда не разбираться с результатами по памяти / буферу / чату. Только лог.**
+
+## ⛔ РУЧНЫЕ ПАТЧИ — ЗАПРЕЩЕНЫ
+
+- НИКОГДА не применять ручные патчи (`kubectl patch`, `kubectl apply` отдельных полей, `python -c` замены в yaml и т.д.) без явного указания.
+- Все изменения — только через код (Helm chart, YAML, Go-код) + сборка + деплой.
+- Ручной патч слетает при следующем helm upgrade/redeploy → регрессия.
+- Исключение: только если пользователь явно написал "примени ручной патч".
@@ -0,0 +1,71 @@
+# IoT Managed Service
+
+## Назначение
+
+IoT Managed Service — это облачный сервис для управления IoT-устройствами, сбора и хранения телеметрии, а также интеграции с внешними системами через MQTT, Kafka и REST API.
+
+Сервис автоматизирует регистрацию устройств, выдачу credentials, сбор телеметрии и предоставляет REST-интерфейс для управления и мониторинга.
+
+---
+
+## Архитектура
+
+- **IoT Device** — физическое устройство, подключающееся по MQTT
+- **EMQX** — брокер MQTT, делегирует auth/ACL в iot-operator
+- **iot-mqtt-bridge** — подписка на все топики, проксирует в Kafka
+- **Kafka** — очередь событий телеметрии
+- **iot-kafka-consumer** — сохраняет телеметрию в per-tenant Postgres
+- **IoT Postgres** — база данных для хранения телеметрии
+- **REST API** — управление устройствами, получение телеметрии
+
+---
+
+## Основные компоненты
+
+| Компонент         | Назначение                        |
+|-------------------|-----------------------------------|
+| iot-operator      | REST API, контроллер CRD          |
+| iot-mqtt-bridge   | MQTT → Kafka                      |
+| iot-kafka-consumer| Kafka → Postgres                  |
+| iot-postgres      | Хранение телеметрии               |
+| EMQX              | MQTT брокер                       |
+
+---
+
+## Основные команды и эндпоинты
+
+### Публичные
+- `GET /console` — IoT Console (SPA)
+- `GET /iot-admin` — страница администратора
+
+### JWT (namespace)
+- `POST /v1/namespaces/{ns}/iot/devices` — создать устройство
+- `GET /v1/namespaces/{ns}/iot/devices` — список устройств
+- `GET /v1/namespaces/{ns}/iot/devices/{name}` — получить устройство + пароль
+- `DELETE /v1/namespaces/{ns}/iot/devices/{name}` — удалить устройство
+- `PATCH /v1/namespaces/{ns}/iot/devices/{name}` — обновить (enabled)
+- `GET /v1/namespaces/{ns}/iot/telemetry` — получить телеметрию
+
+### Внутренние (без JWT)
+- `POST /internal/mqtt/auth` — MQTT auth для EMQX
+- `POST /internal/mqtt/acl` — MQTT ACL для EMQX
+
+### Админ
+- `GET /iot-admin/stats` — статистика (PG, Kafka, pods)
+
+---
+
+## Быстрый старт
+
+1. Развернуть EMQX, iot-mqtt-bridge, event-dispatcher, iot-kafka-consumer, iot-postgres (см. deployments/k8s/)
+2. Зарегистрировать устройство через REST API или CRD
+3. Подключить устройство к MQTT (логин/пароль выдаются автоматически)
+4. Телеметрия автоматически попадёт в Postgres и доступна через REST API
+
+---
+
+## Документация
+- doc/architecture/overview.md — архитектура
+- doc/api/endpoints.md — список эндпоинтов
+- doc/deployment.md — деплой и инженерные детали
+- examples/README.md — пример E2E цепочки
Author	SHA1	Message	Date
“Naeel”	561506ed91	README: описание сервиса, архитектура, команды, эндпоинты	2026-05-11 07:28:42 +04:00
“Naeel”	bac2f93a25	Добавлен файл pravila.md (адаптация под IoT)	2026-05-11 07:22:08 +04:00