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,126 @@
+# Правила работы агента в проекте IoT
+
+## ГЛАВНОЕ ПРАВИЛО
+
+**НЕ "СОВЕРШЕНСТВОВАТЬ" РАБОЧИЙ КОД БЕЗ ЯВНОГО УКАЗАНИЯ.**
+
+---
+
+## ЗАПРЕТ НА ВЫДУМКИ
+
+**КАТЕГОРИЧЕСКИ ЗАПРЕЩАЕТСЯ придумывать, догадываться или предполагать:**
+- значения параметров, которые не видны в коде или документации
+- допустимые значения enum/ролей/типов — если не взяты из реального источника
+- поведение API, провайдеров, библиотек — если не подтверждено кодом или документацией
+- любые факты о системе, которые агент "знает" из общих соображений
+
+**Если информации нет — спросить у пользователя. Не угадывать.**
+
+Если код работает — не трогать. Никаких:
+- рефакторингов "попутно"
+- улучшений стиля
+- добавления комментариев / docstring
+- переименований переменных
+- "пока уж заодно поправлю"
+
+Делай только то, о чём явно попросили. Ничего лишнего.
+
+---
+
+## О проекте
+
+IoT managed service — отдельная репа, вынесенная из sless.
+Go модуль: `gitea.services.ngcloud.ru/Nail/IoT`
+Репа: https://gitea.services.ngcloud.ru/Nail/IoT
+
+### Компоненты (3 бинарника из одного образа):
+1. **iot-operator** (`cmd/iot-operator/`) — controller-manager (IoTDevice CRD) + REST API на :9090
+2. **mqtt-bridge** (`cmd/mqtt-bridge/`) — MQTT (EMQX) → Kafka bridge
+3. **kafka-consumer** (`cmd/kafka-consumer/`) — Kafka → Postgres pipeline
+
+### Стек:
+- Go 1.25, controller-runtime v0.14, gorilla/mux
+- CRD: `iot.kube5s.ru/v1alpha1` (IoTDevice)
+- EMQX — MQTT брокер, Kafka — очередь телеметрии
+- PostgreSQL — per-tenant databases для телеметрии
+- Docker Hub: `naeel/iot-operator`
+
+### Структура:
+```
+cmd/iot-operator/    — точка входа (controller + API сервер)
+cmd/mqtt-bridge/     — MQTT→Kafka bridge
+cmd/kafka-consumer/  — Kafka→Postgres
+api/v1alpha1/        — CRD Go types (IoTDevice)
+controllers/         — IoTDevice reconciler
+internal/api/        — REST handlers, router, middleware, UI (go:embed)
+internal/storage/    — iotpg (per-tenant Postgres)
+config/crd/          — CRD YAML manifests
+deployments/k8s/     — k8s deployment YAMLs
+doc/                 — документация
+examples/            — примеры (Terraform, handler.py)
+```
+
+---
+
+## Комментарии в коде
+
+Комментарии — обязательны:
+- В начале каждого файла при создании или правке — дата и время изменения
+- На каждой функции/методе — краткое назначение
+- На нетривиальной логике — **почему** сделано именно так (не "что делает", а "зачем")
+
+Цель: любой агент в новом чате должен понять логику без дополнительных вопросов.
+
+---
+
+## Темп работы
+
+Не спешить. Перед каждым шагом — убедиться что предыдущий понят и согласован.
+
+---
+
+## Документация
+
+Всё важное фиксировать в `doc/`:
+- `doc/architecture/` — архитектура, стек, схемы
+- `doc/api/` — дизайн API
+- `doc/decisions/` — принятые решения с обоснованием
+- `doc/infrastructure/` — инфраструктура, кластер, сервисы
+- `doc/errors/` — ошибки и как решили
+- `doc/progress.md` — трекер задач
+
+Обновлять после каждого значимого изменения.
+
+---
+
+## Именование
+
+Имена должны быть **уникальными и осмысленными по всему проекту**:
+- имена файлов
+- имена функций/методов
+- имена переменных/констант
+- имена ресурсов (Terraform, Kubernetes и т.д.)
+
+Цель: чтобы поиск по проекту находил нужные сущности без неоднозначности, а имя сразу отражало назначение.
+
+Запрещены безликие и повторяющиеся имена вида `handler.py`, `handle`, `data`, `value`, `temp` без контекста.
+
+---
+
+## Лог мышления (обязательно)
+
+Каждый агент в каждом чате **обязан** вести лог своих рассуждений:
+- Папка: `doc/thinking/`
+- Файл: `ГГГГ-ММ-ДД.md` (по дате сессии)
+- В начале файла указать имя агента и модель
+- Если файл на текущую дату уже существует — дописывать в конец, добавив разделитель `---` и имя агента
+- Записывать **полный** ход мыслей: что анализирую, какие гипотезы, что нашёл, что отбросил, к чему пришёл, почему
+- Записывать **до** начала действий (план) и **после** (результат)
+
+Цель: пользователь должен видеть весь процесс рассуждений в читаемом виде.
+
+---
+
+## Git
+
+Коммитить и пушить после каждого завершённого этапа.