package iot

import "context"

// Provider 是可插拔的 IoT 设备来源。实现方持有设备状态，并为每种设备类型施加
// control_rules（capability 约束）——因此某类型支持的动作集合即其能力边界。
//
// 实现必须是并发安全的，因为 Manager 可能从多个 goroutine 并发调用
// List/Control/Status。
type Provider interface {
	// Name 返回稳定的 Provider 标识，用于日志，以及区分注册在同一 Manager 上的
	// 多个 Provider。
	Name() string
	// List 返回该 Provider 当前已知的全部设备。
	List(ctx context.Context) ([]Device, error)
	// Control 对指定设备施加 action（携带 params），并返回跃迁后的设备。
	// 设备未知时返回 ErrDeviceNotFound；设备类型不支持该动作时返回 ErrUnsupported。
	Control(ctx context.Context, deviceID, action string, params map[string]any) (*Device, error)
	// Status 返回指定设备的当前状态；设备未知时返回 ErrDeviceNotFound。
	Status(ctx context.Context, deviceID string) (*Device, error)
}