@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

package/skills/cosmic-build/skills/cosmic-meta-api/scripts/_core/validators.py

@@ -71,14 +71,10 @@ _VALUE_ONLY_KEYS = {"basedataNumber", "billEntityId", "comboOptions", "comboItem
 _WRONG_NAME_ALIASES = {"displayName", "fieldName", "label"}
 
 # --- modify on entity+field/entity: deprecated per modify-vs-property.md v2 ---
-# modifyMeta modify on field/entity properties is unreliable due to two failure modes:
-#   1. Silent no-op: camelCase/PascalCase naming mismatch (mustInput vs MustInput)
-#   2. NPE: hypothesized index-rebuild null-key NPE on certain property combinations
-# Exception: comboItems.* / comboOptions paths have dedicated backend Handler support
-# (see api-summary.md executeUpdate → applyFieldUpdate, and metaop-spec.md §6.3).
-# Note: comboItems.* through modifyMeta still carries NPE risk; do_quickfield_add_option
-# now uses proactive setComboItems (Property API) with write-after-read verification
-# instead of modifyMeta, avoiding both failure modes entirely.
+# 附件处理器对未知 path 或不适用类型只 warning 后返回；白名单 mustInput 本身有支持。
+# 原 combo NPE 缺完整堆栈，不能宣称已定位或通过改道根治。
+# comboItems/comboOptions 的全量、add/remove 有专用分支，须先验证真实输入形状。
+# quickfield 使用 Property API 并独立回读；这不证明历史脏 Items 已被修复。
 _COMBO_PATH_PREFIXES = ("comboItems", "comboOptions")
 
 # --- bizWord / bizName Format (A8/A9) ---
@@ -293,6 +289,10 @@ def _check_add(op_item, prefix, target, value, extra, element_type,
     elif element_type == "field":
         ft = value.get("fieldType", "")
 
+        # applyAddField 直接强转 Boolean，不能发送字符串形式的必录值。
+        if "mustInput" in value and not isinstance(value["mustInput"], bool):
+            errors.append(f"{prefix}: mustInput 必须是 Boolean，不能是字符串或 null")
+
         # ── A7: fieldType spelling ──
         if ft and not ft.endswith("Field"):
             errors.append(
@@ -368,18 +368,17 @@ def _check_add(op_item, prefix, target, value, extra, element_type,
 
         # ── V1 / A11: ComboField-like options ──
         if ft in _COMBO_LIKE_TYPES:
-            opts = value.get("comboOptions") or value.get("items")
-            if not opts:
-                errors.append(
-                    f"{prefix}: {ft} missing comboOptions or items (at least one required)"
-                )
-            elif isinstance(opts, list):
-                for oi, opt in enumerate(opts):
-                    if isinstance(opt, dict):
-                        if "label" not in opt or "value" not in opt:
-                            errors.append(
-                                f"{prefix}: comboOptions[{oi}] missing label or value key"
-                            )
+            # fillComboFieldItems 优先读 items；不能只校验另一个同义输入。
+            supplied = [(key, value[key]) for key in ("items", "comboOptions") if key in value]
+            if not supplied:
+                errors.append(f"{prefix}: {ft} missing comboOptions or items (at least one required)")
+            for key, opts in supplied:
+                if not isinstance(opts, list) or not opts:
+                    errors.append(f"{prefix}: {key} 必须是非空数组")
+                    continue
+                _check_combo_items(opts, f"{prefix}.{key}", errors)
+            if len(supplied) == 2 and supplied[0][1] != supplied[1][1]:
+                errors.append(f"{prefix}: items 与 comboOptions 内容冲突，只提供一种选项输入")
 
         # ── V4: FlexField requires flexType ──
         if ft == "FlexField" and value.get("flexType") is None:
@@ -417,9 +416,43 @@ def _check_add(op_item, prefix, target, value, extra, element_type,
             )
 
 
+def _check_combo_items(value, prefix, errors, remove=False):
+    """在调用处理器前拒绝空项和空身份，不把 null 转成合法字符串。"""
+    rows = [value] if remove and isinstance(value, str) else value
+    if not isinstance(rows, list):
+        errors.append(f"{prefix}: comboItems 必须是数组（remove 也可用单个字符串）")
+        return
+    seen = set()
+    for index, row in enumerate(rows):
+        if remove and not isinstance(row, (dict, str)):
+            errors.append(f"{prefix}: comboItems[{index}] 删除项必须是字符串或含 value 的对象；数字用对象包裹")
+            continue
+        key = row.get("value") if isinstance(row, dict) else row if remove else None
+        if not isinstance(key, (str, int, float)) or isinstance(key, bool) or not str(key).strip():
+            errors.append(f"{prefix}: comboItems[{index}].value 必须是非空标量，不能缺失或为 null")
+            continue
+        if str(key) in seen:
+            errors.append(f"{prefix}: comboItems[{index}] 重复 value={key!r}")
+        seen.add(str(key))
+        if not remove:
+            # 服务端优先消费非 null label；不能用 caption 掩盖实际被读取的空名称。
+            label = row.get("label") if row.get("label") is not None else row.get("caption")
+            if not isinstance(label, str) or not label.strip():
+                errors.append(f"{prefix}: comboItems[{index}] 实际使用的 label 或 caption 必须是非空字符串")
+
+
 def _check_modify(op_item, prefix, target, value, extra, errors):
     """Level 1: modify operation validation (S5 + S5a field/entity-property deprecation)."""
     path = op_item.get("path")
+    if path is not None and (not isinstance(path, str) or not path.strip()):
+        errors.append(f"{prefix}: modify.path 必须是非空字符串；Map 形式应省略 path")
+        return
+    if isinstance(path, str) and any(path == p or path.startswith(p + ".") for p in _COMBO_PATH_PREFIXES):
+        if path not in {"comboItems", "comboOptions", "comboItems.add", "comboOptions.add",
+                        "comboItems.remove", "comboOptions.remove"}:
+            errors.append(f"{prefix}: 未支持的 combo 属性路径 {path!r}")
+            return
+        _check_combo_items(value, prefix, errors, remove=path.endswith(".remove"))
     # S5: modify requires path or Map expansion
     if path is None and not isinstance(value, dict):
         errors.append(
@@ -427,13 +460,8 @@ def _check_modify(op_item, prefix, target, value, extra, errors):
         )
 
     # S5a: modify on entity+field/entity is deprecated per modify-vs-property.md v2.
-    # Two failure modes make modifyMeta modify unreliable for field/entity properties:
-    #   1. Silent no-op: modifyMeta whitelist uses camelCase (mustInput) but Property API
-    #      uses PascalCase (MustInput). Non-whitelist properties silently succeed but
-    #      have no effect (see usage-guide.md §6).
-    #   2. NPE: index-rebuild null-key NPE on certain property combinations.
-    # Exception: comboItems.* / comboOptions paths have dedicated backend Handler support
-    # (but still carry NPE risk; do_quickfield_add_option uses proactive setComboItems instead).
+    # 未知属性或不适用类型可能静默返回；普通属性使用契约映射并独立回读。
+    # combo 专用分支保留，但先执行上面的输入门禁；原 NPE 的具体抛出点仍未证实。
     tree_type = target.get("treeType")
     element_type = target.get("elementType")
     if tree_type == "entity" and element_type in ("field", "entity"):
@@ -446,7 +474,7 @@ def _check_modify(op_item, prefix, target, value, extra, errors):
             errors.append(
                 f"{prefix}: modify on entity+{element_type} is deprecated for property changes "
                 f"(modify-vs-property.md v2). Reason: modifyMeta modify on field/entity properties "
-                f"is unreliable — silent no-op (camelCase/PascalCase naming mismatch) or NPE. "
+                f"未知 path 或不适用类型可能静默无效；原 NPE 抛出位置尚未证实。 "
                 f"Use Property API instead:\n"
                 f"  setProperties --formNumber <form> --elementKey {field_key} --input '{{\"MustInput\": true}}'\n"
                 f"  setComplexProperty --formNumber <form> --elementKey {field_key} --complexType Features --input '...'\n"