feat(historian): SQL Server backend skeleton - schema DDL, locked bootstrapper, options, connection/mapper/tag-catalog helpers, status consts, env-gated fixture

Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
2026-10-09 12:52:15 -04:00
parent ff7c6c531a
commit 17962d4233
19 changed files with 1187 additions and 0 deletions
@@ -0,0 +1,105 @@
+using System.Data;
+using Microsoft.Data.SqlClient.Server;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer;
+
+/// <summary>One sample bound for a <c>SampleRow</c> TVP.</summary>
+/// <param name="TimeUtc">Source timestamp (UTC, full tick precision).</param>
+/// <param name="Value">Typed value.</param>
+/// <param name="StatusCode">OPC UA status code (stored bit-for-bit as int).</param>
+internal readonly record struct SqlSampleRow(DateTime TimeUtc, HistorianValue Value, uint StatusCode);
+
+/// <summary>The (ValueKind, NumValue, IntValue, StrValue) column quad for a value.</summary>
+internal readonly record struct SampleColumns(byte ValueKind, double? NumValue, long? IntValue, string? StrValue);
+
+/// <summary>
+///     HistorianValue ⇄ column mapping (spec §4) and the <c>SqlDataRecord</c> TVP builders. Mapping:
+///     Double → Num; Int64 → Int + Num(double); Boolean → Int 0/1 + Num 0/1; String → Str; DateTime → Int (ticks);
+///     Empty → all NULL.
+/// </summary>
+internal static class SampleRowMapper
+{
+    private static readonly SqlMetaData[] SampleMeta =
+    [
+        new("SourceTimeUtc", SqlDbType.DateTime2, 0, 7),
+        new("ValueKind", SqlDbType.TinyInt),
+        new("NumValue", SqlDbType.Float),
+        new("IntValue", SqlDbType.BigInt),
+        new("StrValue", SqlDbType.NVarChar, SqlMetaData.Max),
+        new("StatusCode", SqlDbType.Int),
+    ];
+
+    private static readonly SqlMetaData[] TimeMeta = [new("T", SqlDbType.DateTime2, 0, 7)];
+
+    /// <summary>Splits a value into its column quad.</summary>
+    /// <param name="v">Typed value.</param>
+    /// <returns>The columns to store.</returns>
+    public static SampleColumns ToColumns(HistorianValue v) => v.Kind switch
+    {
+        HistorianValueKind.Double => new((byte)v.Kind, v.Number, null, null),
+        HistorianValueKind.Int64 => new((byte)v.Kind, v.Number, v.Integer, null),
+        HistorianValueKind.Boolean => new((byte)v.Kind, v.Integer != 0 ? 1d : 0d, v.Integer != 0 ? 1L : 0L, null),
+        HistorianValueKind.String => new((byte)v.Kind, null, null, v.Text ?? ""),
+        HistorianValueKind.DateTime => new((byte)v.Kind, null, v.Integer, null),
+        _ => new((byte)HistorianValueKind.Empty, null, null, null),
+    };
+
+    /// <summary>Rebuilds a value from stored columns.</summary>
+    /// <param name="valueKind">ValueKind column.</param>
+    /// <param name="num">NumValue column (null = NULL).</param>
+    /// <param name="integer">IntValue column (null = NULL).</param>
+    /// <param name="str">StrValue column (null = NULL).</param>
+    /// <returns>The typed value; an unknown kind yields <see cref="HistorianValue.Empty"/>.</returns>
+    public static HistorianValue FromColumns(byte valueKind, double? num, long? integer, string? str) => (HistorianValueKind)valueKind switch
+    {
+        HistorianValueKind.Double => HistorianValue.FromDouble(num ?? 0d),
+        HistorianValueKind.Int64 => HistorianValue.FromInt64(integer ?? 0L),
+        HistorianValueKind.Boolean => HistorianValue.FromBoolean((integer ?? 0L) != 0),
+        HistorianValueKind.String => HistorianValue.FromString(str ?? ""),
+        HistorianValueKind.DateTime => new HistorianValue(HistorianValueKind.DateTime, 0d, integer ?? 0L, null),
+        _ => HistorianValue.Empty,
+    };
+
+    /// <summary>Stores a uint status bit-for-bit in the int column.</summary>
+    /// <param name="status">Status code.</param>
+    /// <returns>Same bits as int.</returns>
+    public static int ToDbStatus(uint status) => unchecked((int)status);
+
+    /// <summary>Reads the int status column back to a uint code.</summary>
+    /// <param name="dbStatus">Column value.</param>
+    /// <returns>Same bits as uint.</returns>
+    public static uint FromDbStatus(int dbStatus) => unchecked((uint)dbStatus);
+
+    /// <summary>Builds <c>SampleRow</c> TVP records (datetime2(7); never a DataTable). Lazy; enumerate once.</summary>
+    /// <param name="rows">Samples; must be time-unique (the TVP has a PK on time) and non-empty when bound.</param>
+    /// <returns>Records for <see cref="SqlHistorianConnection.AddStructured"/>.</returns>
+    public static IEnumerable<SqlDataRecord> ToSampleRecords(IEnumerable<SqlSampleRow> rows)
+    {
+        foreach (var r in rows)
+        {
+            var c = ToColumns(r.Value);
+            var rec = new SqlDataRecord(SampleMeta);
+            rec.SetDateTime(0, DateTime.SpecifyKind(r.TimeUtc, DateTimeKind.Utc));
+            rec.SetByte(1, c.ValueKind);
+            if (c.NumValue is { } n) rec.SetDouble(2, n); else rec.SetDBNull(2);
+            if (c.IntValue is { } i) rec.SetInt64(3, i); else rec.SetDBNull(3);
+            if (c.StrValue is { } s) rec.SetString(4, s); else rec.SetDBNull(4);
+            rec.SetInt32(5, ToDbStatus(r.StatusCode));
+            yield return rec;
+        }
+    }
+
+    /// <summary>Builds <c>TimeRow</c> TVP records (datetime2(7)). Lazy; enumerate once.</summary>
+    /// <param name="timesUtc">Distinct UTC times; non-empty when bound.</param>
+    /// <returns>Records for <see cref="SqlHistorianConnection.AddStructured"/>.</returns>
+    public static IEnumerable<SqlDataRecord> ToTimeRecords(IEnumerable<DateTime> timesUtc)
+    {
+        foreach (var t in timesUtc)
+        {
+            var rec = new SqlDataRecord(TimeMeta);
+            rec.SetDateTime(0, DateTime.SpecifyKind(t, DateTimeKind.Utc));
+            yield return rec;
+        }
+    }
+}