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
@@ -111,16 +111,61 @@ public static class S7TagDefinitionFactory
    }

    /// <summary>
-    ///     Deploy-time inspection (05/CONV-2): warns on a present-but-invalid <c>dataType</c> (silently
-    ///     defaulted by the lenient runtime) and on a structurally unparseable TagConfig (a silent
-    ///     <c>BadNodeIdUnknown</c> at runtime). Empty when clean or not an equipment-tag object. Never throws.
+    ///     The <c>TagConfig</c> key carrying the S7 data type. Shared with the AdminUI authoring model so
+    ///     "does the blob declare a type?" is asked of one spelling, not two (Gitea #551).
    /// </summary>
+    public const string DataTypeKey = "dataType";
+
+    /// <summary>
+    ///     The RawPath handed to <see cref="FromTagConfig"/> during inspection — the mapper only copies it
+    ///     onto <see cref="S7TagDefinition.Name"/> and never validates it.
+    /// </summary>
+    private const string InspectionRawPath = "(inspect)";
+
+    /// <summary>
+    ///     <b>The single authority on whether an S7 blob DECLARES a data type</b>, consulted by
+    ///     <see cref="Inspect"/> and by the AdminUI's <c>S7TagConfigModel.Validate</c> alike.
+    ///     <para>
+    ///         S7 is the one driver in the fleet whose reader <b>requires the key to be present</b>
+    ///         (<see cref="FromTagConfig"/> refuses a blob without it, where every sibling falls back to a
+    ///         default), so a hand-authored / CSV / API blob that omits it used to pass both gates and die
+    ///         at the driver with <c>BadNodeIdUnknown</c> — Gitea #551 item 2.
+    ///     </para>
+    ///     <para>
+    ///         Presence is judged on the KEY, not on the value: a non-string token
+    ///         (<c>"dataType": 8</c>) satisfies the presence check and is then treated as absent by
+    ///         <see cref="TagConfigJson.TryReadEnumStrict{TEnum}"/>, so the blob is ACCEPTED as
+    ///         <see cref="S7DataType.Int16"/>. Judging the value here would make this gate stricter than
+    ///         the reader.
+    ///     </para>
+    /// </summary>
+    /// <param name="root">The TagConfig root object.</param>
+    /// <returns><see langword="true"/> when the blob carries a <c>dataType</c> key of any kind.</returns>
+    public static bool DeclaresDataType(JsonElement root) => root.TryGetProperty(DataTypeKey, out _);
+
+    /// <summary>
+    ///     Deploy-time inspection (05/CONV-2): warns for a blob <see cref="FromTagConfig"/> would
+    ///     <b>reject</b> — a structurally unparseable or non-object document, an absent / non-string /
+    ///     blank <c>address</c>, an <b>absent</b> <c>dataType</c> (see <see cref="DeclaresDataType"/>), a
+    ///     present-but-invalid <c>dataType</c> (the runtime enum read is STRICT since R2-11 Phase C, so a
+    ///     typo rejects the tag), or an out-of-range <c>stringLength</c> on a <c>String</c> tag. Such a tag
+    ///     is skipped by the driver and reads <c>BadNodeIdUnknown</c> forever. Empty when the mapper accepts
+    ///     the blob, when it is blank, or when it is not an equipment-tag object. Never throws.
+    /// </summary>
+    /// <remarks>
+    ///     <b>The verdict comes from <see cref="FromTagConfig"/>, not from a mirror</b> (Gitea #551) — see
+    ///     <c>ModbusTagDefinitionFactory.Inspect</c>'s remarks for the full argument.
+    /// </remarks>
    /// <param name="reference">The equipment tag's TagConfig JSON.</param>
    /// <returns>The warnings; empty when clean.</returns>
    public static IReadOnlyList<string> Inspect(string reference)
    {
        var warnings = new List<string>();
        if (string.IsNullOrWhiteSpace(reference) || reference[0] != '{') return warnings;
+
+        // The accept gate: whatever the driver reads draws nothing.
+        if (FromTagConfig(reference, InspectionRawPath, out _)) return warnings;
+
        try
        {
            using var doc = JsonDocument.Parse(reference);
@@ -130,16 +175,67 @@ public static class S7TagDefinitionFactory
                warnings.Add("S7 TagConfig root is not a JSON object — the tag will not resolve (BadNodeIdUnknown).");
                return warnings;
            }
-            var w = TagConfigJson.DescribeInvalidEnum<S7DataType>(root, "dataType");
-            if (w is not null) warnings.Add(w);
+
+            DescribeRejection(root, warnings);
        }
        catch (JsonException)
        {
            warnings.Add("S7 TagConfig is not valid JSON — the tag will not resolve (BadNodeIdUnknown).");
+            return warnings;
        }
+
+        if (warnings.Count == 0)
+        {
+            warnings.Add(
+                "S7 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 addrEl) || addrEl.ValueKind != JsonValueKind.String)
+        {
+            warnings.Add(
+                "S7 TagConfig has no string 'address' (e.g. DB1.DBW0, M0.0, I0.0, QD4) — the driver will "
+                + "skip this tag and it will read BadNodeIdUnknown.");
+        }
+        else if (string.IsNullOrWhiteSpace(addrEl.GetString()))
+        {
+            warnings.Add("S7 TagConfig has a blank 'address' — the tag will not resolve (BadNodeIdUnknown).");
+        }
+
+        if (!DeclaresDataType(root))
+        {
+            warnings.Add(
+                "S7 TagConfig has no 'dataType' — the S7 reader REQUIRES the key to be present (unlike its "
+                + "sibling drivers, which default it), so the driver will skip this tag and it will read "
+                + "BadNodeIdUnknown. Valid: " + string.Join(", ", Enum.GetNames<S7DataType>()) + ".");
+        }
+
+        if (TagConfigJson.DescribeInvalidEnum<S7DataType>(root, DataTypeKey) is { } w) warnings.Add(w);
+
+        if (TagConfigJson.TryReadEnumStrict(root, DataTypeKey, S7DataType.Int16, out var dataType)
+            && dataType == S7DataType.String)
+        {
+            var stringLength = ReadInt(root, "stringLength");
+            if (stringLength < 0 || stringLength > MaxStringLength)
+            {
+                warnings.Add(
+                    $"S7 String tag has a 'stringLength' of {stringLength} — an S7 string is 0–"
+                    + $"{MaxStringLength} characters, so the tag is rejected (BadNodeIdUnknown).");
+            }
+        }
+    }
+
    private static int ReadInt(JsonElement o, string name)
        => o.TryGetProperty(name, out var e) && e.ValueKind == JsonValueKind.Number
           && e.TryGetInt32(out var v) ? v : 0;