fix(tagconfig): close the four #551 residuals — accept-gate-first Inspect, three authoring rules, CSV/service gate, doc sweep

Gitea #551. 1. CSV import ran no driver-typed config gate. Its typed columns were always strictly parsed, but the free-form TagConfigJson column reached the database unread, so a CSV could author a tag the driver rejects — one that deploys green and reads BadNodeIdUnknown forever. RawTagCsvMapper.Parse now names the offending row in the staged review grid, and RawTreeService enforces the same gate on CreateTag/UpdateTag/ImportTags: a form cannot be the guarantee (the API and any future caller reach none of them, and this repo has no bUnit). A rejected import row is an ERROR — the batch inserts nothing and the row is named — never a skip. Note the brief's premise that manual entry rides ImportTagsAsync is wrong: RawManualTagEntryModal commits row-by-row via CreateTagAsync, which is why the gate had to land on all three write paths. 2/3. The seven pre-#549 Inspect methods ran a hand-list of DescribeInvalidEnum checks, so every rejection cause not on the list was invisible. They are now ACCEPT-GATE-FIRST (the MTConnect/Sql/OpcUaClient/Calculation shape): ask the driver's own reader for the verdict, then explain the refusal, with a catch-all so "the parse rejects but Inspect said nothing" is unreachable. That closes S7's absent dataType, AbCip members[], Modbus stringByteOrder and the type-dependent guards, plus causes the issue did not name (absent region/address/tagPath/symbolPath/topic, TwinCAT Structure, MQTT's Sparkplug tuple). FOCAS and MQTT keep advisories about ACCEPTED blobs, so they diagnose rather than return empty. Authoring half: ModbusTagConfigModel gains stringByteOrder; AbCipTagConfigModel asks the new AbCipTagDefinitionFactory.DescribeInvalidMember; S7TagConfigModel captures whether the SOURCE blob declared dataType and asks S7TagDefinitionFactory.DataTypeKey/DeclaresDataType. One authority per rule. 4. Doc sweep: the six factory Inspect summaries, EquipmentTagConfigInspector's class remarks and AdminOperationsActor's comment all claimed invalid enums are "silently defaulted by the lenient runtime" — false since R2-11 Phase C made the runtime reads strict. They describe rejections now.
2026-08-10 00:08:06 -04:00
parent b0d2fa30e3
commit 05b424788f
24 changed files with 1846 additions and 100 deletions
@@ -95,10 +95,33 @@ public static class FocasTagDefinitionFactory
    }

    /// <summary>
-    ///     Deploy-time inspection (05/CONV-2, 05/UNDER-1): warns on a present-but-invalid <c>dataType</c>
-    ///     (silently defaulted by the lenient runtime), on an authored <c>writable:true</c> (the FOCAS wire
-    ///     is read-only — <c>WriteAsync</c> always returns <c>BadNotWritable</c>), and on a structurally
-    ///     unparseable TagConfig. Empty when clean or not an equipment-tag object. Never throws.
+    ///     The RawPath handed to <see cref="FromTagConfig"/> during inspection — the mapper only copies it
+    ///     onto <see cref="FocasTagDefinition.Name"/> and never validates it.
+    /// </summary>
+    private const string InspectionRawPath = "(inspect)";
+
+    /// <summary>
+    ///     Deploy-time inspection (05/CONV-2, 05/UNDER-1). Two kinds of warning, and the distinction is
+    ///     load-bearing:
+    ///     <list type="bullet">
+    ///         <item>
+    ///             <b>Rejections</b> — a blob <see cref="FromTagConfig"/> would refuse: an unparseable or
+    ///             non-object document, an absent / non-string / blank <c>address</c>, or a
+    ///             present-but-invalid <c>dataType</c> (the runtime enum read is STRICT since R2-11 Phase C,
+    ///             so a typo rejects the tag). The driver skips such a tag and it reads
+    ///             <c>BadNodeIdUnknown</c> forever. These are diagnosed only when the mapper has actually
+    ///             refused, so this gate can never be stricter than the runtime (Gitea #551).
+    ///         </item>
+    ///         <item>
+    ///             <b>Advisories</b> — an <em>accepted</em> blob that still will not work: an unparseable
+    ///             FOCAS address (#540; the mapper only requires a non-blank string, the driver's own init
+    ///             then drops it) and an authored <c>writable:true</c> (the FOCAS wire is read-only, so
+    ///             <c>WriteAsync</c> always returns <c>BadNotWritable</c>). These run whether or not the
+    ///             blob parses, which is why FOCAS does not simply return empty on accept.
+    ///         </item>
+    ///     </list>
+    ///     Empty for a clean, accepted blob, for a blank one, or for one that is not an equipment-tag
+    ///     object. Never throws.
    /// </summary>
    /// <param name="reference">The equipment tag's TagConfig JSON.</param>
    /// <returns>The warnings; empty when clean.</returns>
@@ -106,6 +129,11 @@ public static class FocasTagDefinitionFactory
    {
        var warnings = new List<string>();
        if (string.IsNullOrWhiteSpace(reference) || reference[0] != '{') return warnings;
+
+        // The accept gate: only a blob the driver REFUSES gets a rejection diagnosis. The advisories below
+        // apply either way — see the summary.
+        var accepted = FromTagConfig(reference, InspectionRawPath, out _);
+
        try
        {
            using var doc = JsonDocument.Parse(reference);
@@ -115,30 +143,72 @@ public static class FocasTagDefinitionFactory
                warnings.Add("FOCAS TagConfig root is not a JSON object — the tag will not resolve (BadNodeIdUnknown).");
                return warnings;
            }
-            var w = TagConfigJson.DescribeInvalidEnum<FocasDataType>(root, "dataType");
-            if (w is not null) warnings.Add(w);
-            // Gitea #540: an address the driver cannot parse is skipped at init and reads
-            // BadNodeIdUnknown forever, while driver health stays Healthy with zero errors. The
-            // AdminUI modal rejects it outright; this covers the paths that never touch the modal
-            // (CSV import, the API) by at least surfacing it on the deployment.
-            if (root.TryGetProperty("address", out var addr)
-                && addr.ValueKind == JsonValueKind.String
-                && addr.GetString() is { } address
-                && !string.IsNullOrWhiteSpace(address)
-                && FocasAddress.TryParse(address) is null)
-            {
-                warnings.Add(
-                    $"FOCAS address '{address.Trim()}' is not parseable (expected X0.0 / R100, " +
-                    "PARAM:1020, MACRO:500 or FIXED:Identity/SeriesNumber) — the driver will skip " +
-                    "this tag at startup and it will read BadNodeIdUnknown.");
-            }
-            if (root.TryGetProperty("writable", out var wr) && wr.ValueKind == JsonValueKind.True)
-                warnings.Add("FOCAS wire is read-only — an authored 'writable:true' still fails at the wire with BadNotWritable.");
+
+            if (!accepted) DescribeRejection(root, warnings);
+            DescribeAdvisories(root, warnings);
        }
        catch (JsonException)
        {
            warnings.Add("FOCAS TagConfig is not valid JSON — the tag will not resolve (BadNodeIdUnknown).");
+            return warnings;
        }
+
+        if (!accepted && warnings.Count == 0)
+        {
+            warnings.Add(
+                "FOCAS TagConfig was rejected by the driver's tag reader — the driver will skip this tag "
+                + "and it will read BadNodeIdUnknown.");
+        }
+
        return warnings;
    }
+
+    /// <summary>
+    ///     Explains why <see cref="FromTagConfig"/> refused an object-rooted blob, walking its checks in the
+    ///     same order. Runs only after the mapper has already refused, so it can never invent strictness.
+    /// </summary>
+    /// <param name="root">The TagConfig root object.</param>
+    /// <param name="warnings">The list to append warnings to.</param>
+    private static void DescribeRejection(JsonElement root, List<string> warnings)
+    {
+        if (!root.TryGetProperty("address", out var addr) || addr.ValueKind != JsonValueKind.String)
+        {
+            warnings.Add(
+                "FOCAS TagConfig has no string 'address' — the driver will skip this tag and it will read "
+                + "BadNodeIdUnknown.");
+        }
+        else if (string.IsNullOrWhiteSpace(addr.GetString()))
+        {
+            warnings.Add("FOCAS TagConfig has a blank 'address' — the tag will not resolve (BadNodeIdUnknown).");
+        }
+
+        if (TagConfigJson.DescribeInvalidEnum<FocasDataType>(root, "dataType") is { } w) warnings.Add(w);
+    }
+
+    /// <summary>
+    ///     Warnings about a blob the mapper ACCEPTS but the driver still cannot serve as authored — see the
+    ///     "advisories" bullet on <see cref="Inspect"/>.
+    /// </summary>
+    /// <param name="root">The TagConfig root object.</param>
+    /// <param name="warnings">The list to append warnings to.</param>
+    private static void DescribeAdvisories(JsonElement root, List<string> warnings)
+    {
+        // Gitea #540: an address the driver cannot parse is skipped at init and reads BadNodeIdUnknown
+        // forever, while driver health stays Healthy with zero errors. The AdminUI modal rejects it
+        // outright; this covers the paths that never touch the modal (CSV import, the API).
+        if (root.TryGetProperty("address", out var addr)
+            && addr.ValueKind == JsonValueKind.String
+            && addr.GetString() is { } address
+            && !string.IsNullOrWhiteSpace(address)
+            && FocasAddress.TryParse(address) is null)
+        {
+            warnings.Add(
+                $"FOCAS address '{address.Trim()}' is not parseable (expected X0.0 / R100, " +
+                "PARAM:1020, MACRO:500 or FIXED:Identity/SeriesNumber) — the driver will skip " +
+                "this tag at startup and it will read BadNodeIdUnknown.");
+        }
+
+        if (root.TryGetProperty("writable", out var wr) && wr.ValueKind == JsonValueKind.True)
+            warnings.Add("FOCAS wire is read-only — an authored 'writable:true' still fails at the wire with BadNotWritable.");
+    }
 }