增加ping指令并获取带版本号的响应

internal/domain/device/device_service.go

@@ -4,6 +4,7 @@ import (
 	"context"
 
 	"git.huangwc.com/pig/pig-farm-controller/internal/infra/models"
+	"git.huangwc.com/pig/pig-farm-controller/internal/infra/transport/proto"
 )
 
 // 设备行为
@@ -21,6 +22,26 @@ var (
 	MethodSwitch Method = "switch" // 启停指令
 )
 
+// SendOptions 包含了发送通用指令时的可选参数。
+type SendOptions struct {
+	// NotTrackable 如果为 true，则指示本次发送无需被追踪。
+	// 这将阻止系统为本次发送创建 device_command_logs 记录。
+	// 默认为 false，即需要追踪。
+	NotTrackable bool
+}
+
+// SendOption 是一个函数类型，用于修改 SendOptions。
+// 这是实现 "Functional Options Pattern" 的核心。
+type SendOption func(*SendOptions)
+
+// WithoutTracking 是一个公开的选项函数，用于明确指示本次发送无需追踪。
+// 调用方在发送 Ping 等无需响应确认的指令时，应使用此选项。
+func WithoutTracking() SendOption {
+	return func(opts *SendOptions) {
+		opts.NotTrackable = true
+	}
+}
+
 // Service 抽象了一组方法用于控制设备行为
 type Service interface {
 
@@ -29,6 +50,10 @@ type Service interface {
 
 	// Collect 用于发起对指定区域主控下的多个设备的批量采集请求。
 	Collect(ctx context.Context, areaControllerID uint32, devicesToCollect []*models.Device) error
+
+	// Send 是一个通用的发送方法，用于将一个标准的指令载荷发送到指定的区域主控。
+	// 它负责将载荷包装成顶层指令、序列化、调用底层发送器，并默认记录下行命令日志。
+	Send(ctx context.Context, areaControllerID uint32, payload proto.InstructionPayload, opts ...SendOption) error
 }
 
 // 设备操作指令通用结构(最外层)

internal/domain/device/general_device_service.go

@@ -20,6 +20,7 @@ import (
 type GeneralDeviceService struct {
 	ctx                   context.Context
 	deviceRepo            repository.DeviceRepository
+	areaControllerRepo    repository.AreaControllerRepository
 	deviceCommandLogRepo  repository.DeviceCommandLogRepository
 	pendingCollectionRepo repository.PendingCollectionRepository
 	comm                  transport.Communicator
@@ -29,6 +30,7 @@ type GeneralDeviceService struct {
 func NewGeneralDeviceService(
 	ctx context.Context,
 	deviceRepo repository.DeviceRepository,
+	areaControllerRepo repository.AreaControllerRepository,
 	deviceCommandLogRepo repository.DeviceCommandLogRepository,
 	pendingCollectionRepo repository.PendingCollectionRepository,
 	comm transport.Communicator,
@@ -36,6 +38,7 @@ func NewGeneralDeviceService(
 	return &GeneralDeviceService{
 		ctx:                   ctx,
 		deviceRepo:            deviceRepo,
+		areaControllerRepo:    areaControllerRepo,
 		deviceCommandLogRepo:  deviceCommandLogRepo,
 		pendingCollectionRepo: pendingCollectionRepo,
 		comm:                  comm,
@@ -249,3 +252,70 @@ func (g *GeneralDeviceService) Collect(ctx context.Context, areaControllerID uin
 	logger.Debugf("成功将采集请求 (CorrelationID: %s) 发送到设备 %s", correlationID, networkID)
 	return nil
 }
+
+// Send 实现了 Service 接口，用于发送一个通用的指令载荷。
+// 它将载荷包装成顶层指令，然后执行查找网络地址、序列化、发送和记录日志的完整流程。
+func (g *GeneralDeviceService) Send(ctx context.Context, areaControllerID uint32, payload proto.InstructionPayload, opts ...SendOption) error {
+	serviceCtx, logger := logs.Trace(ctx, g.ctx, "Send")
+
+	// 1. 应用选项
+	options := &SendOptions{}
+	for _, opt := range opts {
+		opt(options)
+	}
+
+	// 2. 查找区域主控以获取 NetworkID
+	areaController, err := g.areaControllerRepo.FindByID(serviceCtx, areaControllerID)
+	if err != nil {
+		return fmt.Errorf("发送通用指令失败：无法找到ID为 %d 的区域主控: %w", areaControllerID, err)
+	}
+
+	// 3. 将载荷包装进顶层 Instruction 结构体
+	instruction := &proto.Instruction{
+		Payload: payload,
+	}
+
+	// 4. 序列化指令
+	message, err := gproto.Marshal(instruction)
+	if err != nil {
+		return fmt.Errorf("序列化通用指令失败: %w", err)
+	}
+
+	// 5. 发送指令
+	networkID := areaController.NetworkID
+	sendResult, err := g.comm.Send(serviceCtx, networkID, message)
+	if err != nil {
+		return fmt.Errorf("发送通用指令到 %s 失败: %w", networkID, err)
+	}
+
+	// 6. 始终创建 DeviceCommandLog 记录，但根据选项设置其初始状态
+	logRecord := &models.DeviceCommandLog{
+		MessageID: sendResult.MessageID,
+		DeviceID:  areaController.ID, // 将日志与区域主控关联
+		SentAt:    time.Now(),
+	}
+
+	if options.NotTrackable {
+		// 对于无需追踪的指令，直接标记为已完成
+		now := time.Now()
+		logRecord.AcknowledgedAt = &now
+		logRecord.ReceivedSuccess = true
+		logger.Infow("成功发送一个无需追踪的通用指令，并记录为已完成日志", "networkID", networkID, "MessageID", sendResult.MessageID)
+	} else {
+		// 对于需要追踪的指令，记录其发送结果，等待异步确认
+		if sendResult.AcknowledgedAt != nil {
+			logRecord.AcknowledgedAt = sendResult.AcknowledgedAt
+		}
+		if sendResult.ReceivedSuccess != nil {
+			logRecord.ReceivedSuccess = *sendResult.ReceivedSuccess
+		}
+		logger.Infow("成功发送通用指令，并创建追踪日志", "networkID", networkID, "MessageID", sendResult.MessageID)
+	}
+
+	if err := g.deviceCommandLogRepo.Create(serviceCtx, logRecord); err != nil {
+		// 记录日志失败是一个需要关注的问题，但可能不应该中断主流程。
+		logger.Errorw("创建通用指令的日志失败", "MessageID", sendResult.MessageID, "error", err)
+	}
+
+	return nil
+}