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

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

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

---

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

**КАТЕГОРИЧЕСКИ ЗАПРЕЩАЕТСЯ придумывать, догадываться или предполагать:**
- значения параметров, которые не видны в коде или документации
- допустимые значения enum/ролей/типов — если не взяты из реального источника
- поведение API, провайдеров, библиотек — если не подтверждено кодом или документацией
- любые факты о системе, которые агент "знает" из общих соображений

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

Если код работает — не трогать. Никаких:
- рефакторингов "попутно"
- улучшений стиля
- добавления комментариев / docstring
- переименований переменных
- "пока уж заодно поправлю"

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

---

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

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

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

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

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

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

### Примеры

```bash
# 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

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