home_automatization/services/device-control-service/README.md

device-control-service (Go)

Статус: реализован (MVP).

Зона ответственности:

• Предоставляет gRPC API (см. proto/device_control/device_control.proto: TurnOn, TurnOff, SetLevel → CommandResult) для отправки команд устройствам — вызывается из rule-engine-service (действия по срабатыванию правил).
• Тот же функционал доступен и по HTTP/JSON (internal/httpapi, POST /devices/{device_id}/turn-on|turn-off|set-level) — для Laravel (ручное управление из UI), см. «Архитектурные решения» почему не gRPC.
• Публикует команду в MQTT-топик устройства (devices/{device_id}/commands) и слушает подтверждения (devices/{device_id}/ack).
• Поддерживает паттерн Device Shadow в Redis: desired_state (чего хочет пользователь) против reported_state (что подтвердило устройство), плюс status и last_seen.
• Ведёт health-check горутиной-тикером: переводит устройство в offline, когда last_seen превышает таймаут, и публикует событие в RabbitMQ (device.status_changed) для будущего notification-service — как при уходе в офлайн, так и при возврате online.

Не входит в зону ответственности: решение о том, когда отправлять команду на основе показаний датчиков — это логика rule-engine-service. Этот сервис только исполняет команды и отслеживает состояние для той команды, что ему дали.

Архитектурные решения

• gRPC — не ждёт подтверждения устройства. CommandResult.success означает «desired_state обновлён и команда опубликована в MQTT», а не «устройство подтвердило выполнение». Это соответствует Device Shadow: мгновенный отклик в UI, даже если устройство офлайн или ответит с задержкой. reported_state обновляется позже, асинхронно, по приходу ack.
• last_seen обновляется и по телеметрии, и по ack. Сервис подписан на devices/+/telemetry только ради отметки «устройство живо» (сами данные телеметрии парсит и хранит ingest-service) — иначе датчики без исходящих команд (и, соответственно, без ack) никогда не считались бы online.
• Нет зависимости от PostgreSQL. Список известных устройств — это Redis Set (devices:known), который пополняется по мере поступления телеметрии/ack, а не выгружается из таблицы devices. Это удерживает сервис в границах MQTT+Redis+RabbitMQ+gRPC, как и в диаграмме архитектуры корневого README.
• HTTP рядом с gRPC, а не вместо. ТЗ подразумевало gRPC-вызов и от Laravel тоже, но grpc/grpc под PHP требует PECL-расширение, которое в Alpine компилируется мучительно долго (C-код, 10-20+ минут) и утяжеляет образ. internal/httpapi — тонкий транспорт поверх ТОГО ЖЕ server.Server (никакой логики не дублируется, просто JSON вместо Protobuf): диаграмма архитектуры в ТЗ и так допускала «HTTP/очередь» для Laravel→device-control. gRPC-контракт между Go-сервисами (rule-engine) не тронут.

Метрики

GET /metrics на том же порту, что и команды (DEVICE_CONTROL_HTTP_PORT) — не открывали отдельный порт ради этого. Счётчики/latency команд (TurnOn/TurnOff/SetLevel по action+outcome), MQTT-событий (telemetry/ack), переходов online/offline health-check.

Запуск

cd services/device-control-service
go test ./...
go build ./cmd/device-control-service

Конфигурация — через переменные окружения (секция device-control-service в корневом .env.example). proto/ — отдельный Go-модуль, подключается через replace в go.mod на относительный путь ../../proto.