任务日志增强设计文档

概述

为 RobotJob、ConveyorLineNewJob、StackerCraneJob 三个模块添加完善的日志记录功能。

日志规范

日志级别定义（严格按语义）

日志输出方式

1. ILogger - 通过依赖注入或父类传递
2. QuartzLogger - 异步文件日志，同时记录

// 标准日志写法
_logger.LogInformation("消息内容");
QuartzLogger.Info("消息内容", source);

修改清单

RobotJob 模块

RobotJob.cs

• 状态：已有 ILogger，无需修改

RobotClientManager.cs

• 添加 ILogger<RobotClientManager>
• 修正断连日志：Warn → Info（客户端断开是正常流程）
• 添加 EnsureClientSubscribed 中的重试/不可用日志

RobotTaskProcessor.cs

• 添加 ILogger<RobotTaskProcessor>
• 修正 SendSocketRobotPickAsync：Error → Info（成功下发应记录 Info）
• 添加 HandleInboundTaskAsync 的 WMS 调用结果日志

RobotStateManager.cs

• 添加 ILogger<RobotStateManager>
• 构造函数的 GetOrCreateState 添加 Info 日志
• TryUpdateStateSafely 添加版本冲突 Warn 日志

RobotMessageHandler.cs

• 已有 ILogger，已有良好日志，保持不变

RobotWorkflowOrchestrator.cs

• 添加 ILogger<RobotWorkflowOrchestrator>
• ExecuteAsync 添加状态机决策日志（满足条件时记录 Info）
• HandlePickFinishedStateAsync 添加放货指令下发日志
• HandlePutFinishedStateAsync 添加取货指令下发日志

ConveyorLineNewJob 模块

CommonConveyorLineNewJob.cs

• 添加 ILogger<CommonConveyorLineNewJob>
• Execute 方法：
• 子设备数量为 0：Info
• Parallel.For 开始：Debug
• 命令为空跳过：Debug
• WCS_ACK 处理：Debug
• 检查托盘位置：Info
• PLC_STB 检查：Debug
• 无条码请求出库：Info
• 有任务号处理任务：Info
• 异常捕获：Error
• ProcessTaskState 方法：添加各状态分支的入口日志

ConveyorLineDispatchHandler.cs

• 添加 ILogger<ConveyorLineDispatchHandler>
• HeartBeat：Debug
• RequestInbound：Info（入库请求开始）
• RequestInNextAddress：Info（入库下一地址）
• ConveyorLineInFinish：Info（入库完成）
• RequestOutbound：Info（出库请求）
• RequestOutNextAddress：Info（出库下一地址）
• ConveyorLineOutFinish：Info（出库完成）

ConveyorLineTaskFilter.cs

• 添加 ILogger<ConveyorLineTaskFilter>
• QueryPendingTask：Debug
• QueryExecutingTask：Debug
• RequestWmsTask：Info（WMS 请求）

ConveyorLineTargetAddressSelector.cs

• 添加 ILogger<ConveyorLineTargetAddressSelector>
• HandleInboundNextAddress：Debug
• HandleOutboundNextAddress：Debug
• HandleDeviceRequest：Debug
• ProcessDeviceRequest：Debug

StackerCraneJob 模块

CommonStackerCraneJob.cs

• 添加 ILogger<CommonStackerCraneJob>
• Execute 方法：
• 参数无效：Warn
• 事件订阅：Info
• 任务完成检查：Debug
• 不可发送任务：Debug
• 任务选择结果：Info（选中任务号或无任务）
• 命令构建结果：Info
• 命令发送结果：Info
• 异常捕获：Error
• CommonStackerCrane_StackerCraneTaskCompletedEventHandler：Info
• LoadConfig 失败：Warn

StackerCraneTaskSelector.cs

• 添加 ILogger<StackerCraneTaskSelector>
• SelectTask：Info（任务选择开始、选择结果）
• TrySelectOutboundTask：Debug
• IsOutTaskStationAvailable：Info（站台可用/不可用）
• TryAddTaskFromWms：Info

StackerCraneCommandBuilder.cs

• 添加 ILogger<StackerCraneCommandBuilder>
• ConvertToStackerCraneTaskCommand：Info（命令类型、任务号）
• GetCommandType：Debug
• BuildInboundCommand：Info（入库命令构建）
• BuildOutboundCommand：Info（出库命令构建）
• BuildRelocationCommand：Info（移库命令构建）
• 地址解析失败：Error

ILogger 依赖传递方案

对于通过 new 直接实例化的辅助类，通过父类构造函数传入 ILogger：

// 辅助类接收 ILogger
public class RobotStateManager
{
    private readonly ILogger _logger;
    public RobotStateManager(ICacheService cache, ILogger<RobotStateManager> logger)
    {
        _logger = logger;
    }
}

// Job 在创建辅助类时传入自己的 logger
public RobotJob(..., ILogger<RobotJob> logger)
{
    _stateManager = new RobotStateManager(cache, logger);
}

需修正的日志语义问题

验收标准

1. 所有关键业务节点有 Info 日志
2. 异常情况有 Error 日志并包含异常信息
3. 需要关注的情况有 Warn 日志
4. 日志同时输出到 ILogger 和 QuartzLogger
5. 日志消息清晰，包含关键上下文（如任务号、设备编码）