IoT/.github/copilot-instructions.md

Правила работы агента в проекте IoT

ГЛАВНОЕ ПРАВИЛО

НЕ "СОВЕРШЕНСТВОВАТЬ" РАБОЧИЙ КОД БЕЗ ЯВНОГО УКАЗАНИЯ.

---

ЗАПРЕТ НА ВЫДУМКИ

КАТЕГОРИЧЕСКИ ЗАПРЕЩАЕТСЯ придумывать, догадываться или предполагать:

• значения параметров, которые не видны в коде или документации
• допустимые значения enum/ролей/типов — если не взяты из реального источника
• поведение API, провайдеров, библиотек — если не подтверждено кодом или документацией
• любые факты о системе, которые агент "знает" из общих соображений

Если информации нет — спросить у пользователя. Не угадывать.

Если код работает — не трогать. Никаких:

• рефакторингов "попутно"
• улучшений стиля
• добавления комментариев / docstring
• переименований переменных
• "пока уж заодно поправлю"

Делай только то, о чём явно попросили. Ничего лишнего.

---

⚠️ ВЫПОЛНЕНИЕ КОМАНД — ТОЛЬКО НА УДАЛЁННОЙ МАШИНЕ

• Все команды (git, go, docker, kubectl, make и т.д.) выполнять ТОЛЬКО на удалённой машине через SSH.
• На локальной машине команды не запускать вообще.
• Если для задачи необходимо выполнить что-то локально — спросить явное разрешение у пользователя перед запуском.

Параметры удалённой машины

Параметр	Значение
Хост	5.172.178.213
Пользователь	naeel
SSH-ключ	~/.ssh/id_ed25519
Рабочий каталог	/home/naeel/terra/IoT

Шаблон команды

ssh -i ~/.ssh/id_ed25519 \
    -o StrictHostKeyChecking=no \
    -o ConnectTimeout=10 \
    naeel@5.172.178.213 \
    'cd /home/naeel/terra/IoT && <КОМАНДА>'

Примеры

# git статус
ssh -i ~/.ssh/id_ed25519 -o StrictHostKeyChecking=no -o ConnectTimeout=10 naeel@5.172.178.213 \
  'cd /home/naeel/terra/IoT && git status'

# commit + push
ssh -i ~/.ssh/id_ed25519 -o StrictHostKeyChecking=no -o ConnectTimeout=10 naeel@5.172.178.213 \
  'cd /home/naeel/terra/IoT && git add -A && git commit -m "..." && git push'

# сборка go
ssh -i ~/.ssh/id_ed25519 -o StrictHostKeyChecking=no -o ConnectTimeout=10 naeel@5.172.178.213 \
  'cd /home/naeel/terra/IoT && go build ./...'

Git / Gitea

• Remote: https://gitea.services.ngcloud.ru/Nail/IoT.git (HTTPS)
• SSH до Gitea недоступен с удалённой машины — использовать только HTTPS.
• Credentials сохранены на удалённой машине в ~/.git-credentials.

---

О проекте

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

Коммитить и пушить после каждого завершённого этапа.