plugin

type BaseConnection struct {
	// ConnectionKey 连接标识符，用于唯一标识一个连接
	// 必须全局唯一，用于多设备连接管理
	ConnectionKey string

	// ProtocolKey 协议驱动库标识，指定使用的通信协议
	// 如 "modbus", "bacnet", "mqtt" 等
	ProtocolKey string `json:"protocolKey"`

	// Enable 是否启用此连接
	// false表示禁用该连接，不会尝试建立通信
	Enable bool `json:"enable"`

	// Discover 是否支持设备发现
	// true表示该连接支持自动发现设备功能
	Discover bool `json:"discover"`

	// Virtual 是否为虚拟设备，虚拟设备不需要实际的物理连接
	// true表示设备为虚拟设备，常用于测试或模拟场景
	Virtual bool `json:"virtual"`
}

type Connector interface {
	// Encode 编码设备操作指令
	// 将读/写操作和点位数据编码为协议特定的数据格式
	// 参数:
	//   deviceId: 设备唯一标识符
	//   mode: 操作模式(ReadMode 读取模式 或 WriteMode 写入模式)
	//   values: 点位数据数组，可变参数，支持批量操作
	// 返回值:
	//   interface{}: 编码后的数据，具体格式取决于协议实现
	//   error: 编码过程中发生的错误
	//
	// 注意: 不是所有协议都支持编码功能，不支持时返回NotSupportEncode错误
	// 编码结果通常包含协议头部、地址信息、命令类型、数据等
	Encode(deviceId string, mode EncodeMode, values ...PointData) (res interface{}, err error)

	// Send 发送编码后的数据到设备
	// 将编码后的数据通过底层通信机制发送到目标设备
	// 参数:
	//   data: 通过Encode方法编码后的数据
	// 返回值:
	//   error: 发送过程中发生的错误
	//
	// 此方法应处理底层通信细节，如网络传输、串口通信等
	// 实现时应考虑超时处理、重试机制等
	Send(data interface{}) (err error)

	// Release 释放连接器占用的资源
	// 该方法用于清理连接器相关资源，如关闭连接、停止监听等
	// 返回值:
	//   error: 释放过程中发生的错误
	//
	// 注意: 调用此方法后，连接器将不再可用
	// 清理内容通常包括: 关闭连接、释放锁、通知等待的协程等
	Release() (err error)
}

type DeviceData struct {
	// ID 设备唯一标识符，用于区分不同的设备
	// 必须与系统中注册的设备ID一致
	ID string `json:"id"`

	// Values 设备点位值数组，包含设备上所有有效点位的数据
	// 每个元素为PointData结构，包含点位名称和值
	Values []PointData `json:"values"`

	// Events 设备相关事件数组，包含设备产生的各类事件
	// 事件可能包括设备状态变化、告警、连接状态等
	Events []event.Data `json:"events"`

	// ExportType 上报类型，标识数据的来源类型
	// 底层的变化上报和实时上报等同于RealTimeExport
	ExportType ExportType
}

type EncodeMode string

type ExportType string

type Plugin interface {
	// Initialize 初始化插件
	// 该方法在插件启动时被调用，用于执行必要的初始化操作
	// 参数:
	//   c: 设备配置信息，包含设备连接参数、协议设置、设备列表等
	//
	// 初始化内容通常包括:
	//   - 解析设备配置
	//   - 建立协议连接
	//   - 启动数据处理协程
	//   - 注册回调函数
	//   - 初始化内部数据结构
	Initialize(c config.DeviceConfig)

	// Connector 获取指定设备的连接器
	// 该方法返回一个连接器实例，用于与特定设备进行通信
	// 参数:
	//   deviceId: 设备唯一标识符
	// 返回值:
	//   Connector: 设备连接器实例，用于与设备进行数据交换
	//   error: 获取连接器过程中发生的错误
	//
	// 注意: 不是所有协议都支持此功能，不支持时返回NotSupportGetConnector错误
	// 实现此方法时应确保设备存在且连接器已正确初始化
	Connector(deviceId string) (connector Connector, err error)

	// Destroy 销毁插件并释放资源
	// 该方法在插件停止时被调用，用于执行清理操作
	// 返回值:
	//   error: 销毁过程中发生的错误
	//
	// 清理内容通常包括:
	//   - 关闭所有活动连接
	//   - 停止所有协程
	//   - 释放内存资源
	//   - 清理临时文件或缓存
	//   - 通知相关组件插件已停止
	Destroy() error
}

type PointData struct {
	// PointName 点位名称，唯一标识设备上的一个测量点或控制点
	// 必须与设备模型中定义的点位名称一致
	PointName string `json:"name"`

	// Value 点位值，可以是任意类型的数据，如数字、布尔值、字符串等
	// 值的类型应与点位定义的ValueType匹配
	Value interface{} `json:"value"`
}

type PointReadValue struct {
	// ID 设备 ID
	ID string `json:"id"`

	// PointName 点位名称
	PointName string `json:"pointName"`

	// Value 点位值
	Value interface{} `json:"value"`
}