规范并补充日志内容

SHH.CameraService/GrpcImpls/ImageFactory/ImageMonitorController.cs

@@ -1,13 +1,22 @@
-using Microsoft.Extensions.Hosting;
+using Ayay.SerilogLogs;
+using Microsoft.Extensions.Hosting;
 using OpenCvSharp;
+using Serilog;
 using SHH.CameraSdk;        // 引用 SDK 核心
 using SHH.Contracts;
 using System.Diagnostics;
 
 namespace SHH.CameraService;
 
+/// <summary>
+/// 图像监控采集控制器 (流媒体分发引擎)
+/// <para>功能：监听全局图像采集总线，对图像进行实时 JPG 编码，并动态分发至云端、大屏等订阅目标。</para>
+/// <para>设计模式：发布-订阅模式 + 扇出 (Fan-out) 分发。</para>
+/// </summary>
 public class ImageMonitorController : BackgroundService
 {
+    private static ILogger _sysLog = Log.ForContext("SourceContext", LogModules.Core);
+
     // 注入所有注册的目标（云端、大屏等），实现动态分发
     private readonly IEnumerable<StreamTarget> _targets;
 
@@ -16,29 +25,35 @@ public class ImageMonitorController : BackgroundService
     // 如果您确实需要 100，请注意带宽压力。此处我保留您要求的 100，但建议未来调优。
     private readonly int[] _encodeParams = { (int)ImwriteFlags.JpegQuality, 100 };
 
+    /// <summary>
+    /// 构造函数
+    /// </summary>
+    /// <param name="targets"></param>
     public ImageMonitorController(IEnumerable<StreamTarget> targets)
     {
         _targets = targets;
     }
-
+    
+    /// <summary>
+    /// 启动后台服务：挂载事件总线
+    /// </summary>
     protected override Task ExecuteAsync(CancellationToken stoppingToken)
     {
-        Console.WriteLine("[StreamWorker] 启动流媒体采集引擎...");
+        _sysLog.Information("[Core] 启动流媒体采集引擎...");
 
         // =========================================================
         // 订阅逻辑：接入 "上帝模式" (God Mode)
         // =========================================================
-        // 理由：NetMQ 网关需要无差别地获取所有设备的图像。
+        // 理由：gRpc 需要无差别地获取所有设备的图像。
         GlobalStreamDispatcher.OnGlobalFrame += ProcessFrame;
-
-        //Console.WriteLine($"[StreamWorker] 已挂载至全局广播总线，正在监听 {GlobalStreamDispatcher.OnGlobalFrame?.GetInvocationList().Length ?? 0} 个订阅者...");
+        _sysLog.Information($"[StreamWorker] 已挂载至全局广播总线，正在监听帧信息.");
 
         var tcs = new TaskCompletionSource();
         stoppingToken.Register(() =>
         {
             // 停止时反注册，防止静态事件内存泄漏
             GlobalStreamDispatcher.OnGlobalFrame -= ProcessFrame;
-            Console.WriteLine("[StreamWorker] 已断开全局广播连接");
+            _sysLog.Information("[Core] 流媒体采集引擎已断开全局广播连接.");
             tcs.SetResult();
         });
 
@@ -46,9 +61,11 @@ public class ImageMonitorController : BackgroundService
     }
 
     /// <summary>
-    /// [回调函数] 处理每一帧图像
-    /// 注意：此方法运行在 SDK 的采集线程池中，必须极速处理，严禁阻塞！
+    /// [回调函数] 处理实时帧
+    /// <para>注意：此方法由 SDK 采集线程池触发，必须保持极速处理，严禁在内部执行 IO 等耗时阻塞操作。</para>
     /// </summary>
+    /// <param name="deviceId">设备唯一标识 ID</param>
+    /// <param name="frame">包含原始图像(InternalMat)和处理后图像(TargetMat)的帧数据</param>
     private void ProcessFrame(long deviceId, SmartFrame frame)
     {
         try
@@ -110,20 +127,22 @@ public class ImageMonitorController : BackgroundService
                 if (!ok)
                 {
                     // 如果这里打印，说明管道由于某种原因被关闭了（通常是程序正在退出）
-                    Console.WriteLine($"[DEBUG] 管道写入失败，目标: {target.Config.Name}");
+                    _sysLog.Warning($"[ImageMonitor] 管道写入失败，目标: {target.Config.Name}");
                 }
             }
         }
         catch (Exception ex)
         {
             // 极少发生的内存错误，打印日志但不抛出，避免崩溃 SDK 线程
-            Console.WriteLine($"[StreamWorker] 采集处理异常: {ex.Message}");
+            _sysLog.Error($"[ImageMonitor] 采集处理异常: {ex.Message}");
         }
     }
 
     /// <summary>
-    /// 辅助：OpenCV 内存编码
+    /// 调用 OpenCV 进行内存级图片编码
     /// </summary>
+    /// <param name="mat">待编码的 OpenCV Mat 矩阵</param>
+    /// <returns>JPG 字节数组</returns>
     private byte[] EncodeImage(Mat mat)
     {
         // ImEncode 将 Mat 编码为一维字节数组 (托管内存)