Add business-log helpers for human-readable activity reports

Introduce shared session totals, time formatting, and friendly reason helpers used by operational attendance/user/template logs

BusinessLogging.cs

@@ -0,0 +1,87 @@
+using System;
+using System.Globalization;
+using System.IO;
+using System.Text;
+
+namespace HikvisionAttendanceService;
+
+/// <summary>Running totals for the end-of-run business SUMMARY block.</summary>
+internal sealed class BizSessionTotals
+{
+    public int MachinesProcessed;
+    public int MachinesConnected;
+    public int MachinesFailed;
+    public int AttendanceInserted;
+    public int AttendanceFailed;
+    public int UsersAdded;
+    public int UsersUpdated;
+    public int UsersRemoved;
+    public int TemplatesSaved;
+    public int TemplatesFailed;
+    public DateTime StartedAt = DateTime.Now;
+
+    public string FormatSummaryBlock()
+    {
+        var duration = DateTime.Now - StartedAt;
+        var sb = new StringBuilder();
+        sb.AppendLine("================================================");
+        sb.AppendLine();
+        sb.AppendLine("SUMMARY");
+        sb.AppendLine();
+        sb.AppendLine("Machines Processed : " + MachinesProcessed);
+        sb.AppendLine("Machines Connected : " + MachinesConnected);
+        sb.AppendLine("Machines Failed : " + MachinesFailed);
+        sb.AppendLine();
+        sb.AppendLine("Attendance Inserted : " + AttendanceInserted);
+        sb.AppendLine("Attendance Failed : " + AttendanceFailed);
+        sb.AppendLine();
+        sb.AppendLine("Users Added : " + UsersAdded);
+        sb.AppendLine("Users Updated : " + UsersUpdated);
+        sb.AppendLine("Users Removed : " + UsersRemoved);
+        sb.AppendLine();
+        sb.AppendLine("Templates Saved : " + TemplatesSaved);
+        sb.AppendLine("Templates Failed : " + TemplatesFailed);
+        sb.AppendLine();
+        sb.AppendLine("Duration : " + duration.ToString(@"hh\:mm\:ss", CultureInfo.InvariantCulture));
+        sb.AppendLine();
+        sb.AppendLine("================================================");
+        return sb.ToString();
+    }
+}
+
+internal enum BizChannel
+{
+    Attendance,
+    UserSync,
+    Template,
+    Unreachable
+}
+
+internal static class BizFriendlyReasons
+{
+    public static string FromStage(ConnectivityFailureStage stage, string? detail = null)
+    {
+        switch (stage)
+        {
+            case ConnectivityFailureStage.InvalidIp:
+                return "Invalid IP address.";
+            case ConnectivityFailureStage.PingFailed:
+                return "Device is not responding to network requests.";
+            case ConnectivityFailureStage.TcpPortClosed:
+                return "TCP Port 8000 is closed.";
+            case ConnectivityFailureStage.SdkLoginTimeout:
+                return "Network timeout.";
+            case ConnectivityFailureStage.InvalidCredentials:
+                return "Incorrect username or password.";
+            case ConnectivityFailureStage.SdkRejected:
+                return "Device refused the SDK connection.";
+            default:
+                if (!string.IsNullOrWhiteSpace(detail))
+                    return detail!.Trim();
+                return "Device is powered off or unreachable.";
+        }
+    }
+
+    public static string FormatTime(DateTime dt) =>
+        dt.ToString("M/d/yyyy h:mm:ss tt", CultureInfo.InvariantCulture);
+}