docs: copilot-instructions, архитектура, API, progress, decisions

2026-04-12 14:34:34 +03:00
parent 1a94241c62
commit e70c164203
5 changed files with 302 additions and 0 deletions
@@ -0,0 +1,66 @@
+# IoT Managed Service — Архитектура
+
+## Общая схема
+
+```
+IoT Device (MQTT CONNECT)
+    │ username="{ns}_{deviceId}", password=hex
+    ▼
+EMQX 5.5.1 (sless/emqx)
+    │ POST /internal/mqtt/auth → iot-operator:9090
+    │ POST /internal/mqtt/acl  → iot-operator:9090
+    ▼
+    │ MQTT PUBLISH → topic: "{ns}/telemetry/{deviceId}"
+    ▼
+iot-mqtt-bridge (cmd/mqtt-bridge)
+    │ подписка на "+/telemetry/+"
+    │ → Kafka topic "iot.telemetry"
+    ▼
+Kafka
+    ▼
+iot-kafka-consumer (cmd/kafka-consumer)
+    │ consumer group "iot-pg-consumer"
+    │ → per-tenant Postgres DB
+    ▼
+IoT Postgres (iot-postgres.sless.svc)
+    │ DB: tenant_{namespace}
+    │ Table: iot_telemetry
+    ▼
+REST API (iot-operator:9090)
+    │ GET /v1/namespaces/{ns}/iot/telemetry
+    ▼
+Пользователь (Terraform / UI Console)
+```
+
+## Компоненты
+
+| Компонент | Бинарник | Порт | Назначение |
+|-----------|----------|------|------------|
+| iot-operator | cmd/iot-operator | :9090 (API), :8081 (health) | Controller-manager + REST API |
+| mqtt-bridge | cmd/mqtt-bridge | — | MQTT→Kafka bridge |
+| kafka-consumer | cmd/kafka-consumer | — | Kafka→Postgres pipeline |
+
+## CRD
+
+- **IoTDevice** (`iot.kube5s.ru/v1alpha1`)
+  - Создание: пользователь через API / Terraform
+  - Controller генерирует MQTT credentials → k8s Secret
+  - Secret удаляется каскадно через OwnerReference
+
+## Хранение
+
+- **IoT Postgres** — отдельный от sless PG
+  - Management DB: `iot_platform` (таблица `tenant_credentials`)
+  - Per-tenant DB: `tenant_{namespace}` (таблица `iot_telemetry`)
+
+## Аутентификация
+
+- REST API (/v1/): Bearer JWT (middleware.Auth)
+- MQTT Auth (/internal/): вызывается EMQX, без JWT
+- Admin (/iot-admin/stats): ADMIN_STATS_TOKEN
+
+## Docker образ
+
+- `naeel/iot-operator` (Docker Hub)
+- Все 3 бинарника в одном образе
+- `command: ["/iot-operator"]` или `["/mqtt-bridge"]` или `["/kafka-consumer"]`