pig-farm-controller/internal/infra/transport/transport.go

package transport

import (
	"context"
	"time"

	"git.huangwc.com/pig/pig-farm-controller/internal/infra/transport/proto"
)

// Communicator 用于其他设备通信
type Communicator interface {
	// Send 用于发送一条单向数据(不等待回信)
	// 成功时，它返回一个包含 MessageID 的 SendResult，以便调用方追踪。
	Send(ctx context.Context, address string, payload []byte) (*SendResult, error)
}

// SendResult 包含了 SendGo 方法成功执行后返回的结果。
type SendResult struct {
	// MessageID 是通信服务为此次发送分配的唯一标识符。
	// 调用方需要保存此 ID，以便后续关联 ACK 等事件。
	MessageID string

	// AcknowledgedAt 记录设备确认收到下行消息的时间。
	// 并非所有发送实现都会同步返回收到时间
	AcknowledgedAt *time.Time

	// ReceivedSuccess 表示设备是否成功接收到下行消息。
	// 并非所有发送实现都会同步返回是否送达
	ReceivedSuccess *bool
}

// Listener 用于监听其他设备发送过来的数据
type Listener interface {
	// Listen 用于开始监听其他设备发送过来的数据
	Listen(ctx context.Context) error

	// Stop 用于停止监听
	Stop(ctx context.Context) error
}

// UpstreamHandler 定义了处理所有来源的上行数据的统一协约。
// 任何实现了上行消息监听的基础设施（如串口、MQTT客户端），都应该在收到消息后调用此接口的实现者。
// 这样，基础设施层只负责“接收和解析”，而将“业务处理”的控制权交给了上层。
type UpstreamHandler interface {
	// HandleInstruction 处理来自设备的、已解析为Instruction的业务指令。
	HandleInstruction(ctx context.Context, sourceAddr string, instruction *proto.Instruction) error

	// HandleStatus 处理非业务指令的设备状态更新，例如信号强度、电量等。
	HandleStatus(ctx context.Context, sourceAddr string, status map[string]interface{}) error

	// HandleAck 处理对下行指令的确认（ACK）事件。
	HandleAck(ctx context.Context, sourceAddr string, deduplicationID string, acknowledged bool, eventTime time.Time) error
}