# 任务日志增强设计文档

## 概述

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

## 日志规范

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

| 级别 | 用途 | 示例场景 |
|------|------|----------|
| `Info` | 正常流程节点 | 任务开始处理、命令下发成功、状态转换完成 |
| `Warn` | 需要关注但非错误 | 客户端断连重试、站台不可用、版本冲突 |
| `Error` | 异常/失败 | WMS 调用失败、命令发送失败、任务查询失败 |
| `Debug` | 详细信息 | 轮询操作、缓存读取（可选） |

### 日志输出方式

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

```csharp
// 标准日志写法
_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：

```csharp
// 辅助类接收 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);
}
```

## 需修正的日志语义问题

| 位置 | 原写法 | 修正后 |
|------|--------|--------|
| RobotTaskProcessor.SendSocketRobotPickAsync | QuartzLogger.Error (成功时) | QuartzLogger.Info |
| RobotClientManager.EnsureClientSubscribed | QuartzLogger.Info (异常时) | QuartzLogger.Error |
| RobotClientManager.OnRobotReceived | QuartzLogger.Warn (断连) | QuartzLogger.Info |

## 验收标准

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