@qingflow-tech/qingflow-cli 1.1.51 → 1.1.53

package/src/qingflow_mcp/builder_facade/views_extract.py

@@ -0,0 +1,592 @@
+"""ViewgraphInfo → 公开视图声明的反向编译器(round-trip 提取器,eval 与 `views get --schema-kind complete` 共用)。
+
+设计对称性:本模块的每个映射与 `service.py` 正向编译(`_hydrate_view_backend_payload` 族)一一对应;
+「提不出来」的配置面进入 coverage gaps,由调用方汇总进覆盖度报告(evaluation.md §6)。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .service import (
+    ASSOCIATED_RESOURCE_LIMIT_TYPE_ALL,
+    _coerce_any_int,
+    _coerce_positive_int,
+    _extract_view_button_entries,
+    _public_view_filter_groups_from_match_rules,
+    _public_visibility_from_member_auth,
+    _resolve_system_view_button_logical_id,
+)
+
+# 后端 viewgraphType → 公开 type(ViewUpsertPatch/PublicViewType)
+_VIEW_TYPE_BY_BACKEND = {
+    "tableView": "table",
+    "cardView": "card",
+    "boardView": "board",
+    "ganttView": "gantt",
+    "hierarchyView": "hierarchy",
+    "calendarView": "calendar",
+}
+
+# 后端 dataScope → 公开 data_permission.scope(与 _DATA_PERMISSION_SCOPE_MAP 对称)
+_DATA_SCOPE_TO_PUBLIC = {
+    "ALL": "all",
+    "ONESELF": "oneself",
+    "DEPT": "dept",
+    "SUBORDINATE": "subordinate",
+    "CUSTOM": "custom",
+}
+
+# 后端视图列中可直接引用的系统字段 ID。它们不需要出现在表单业务字段索引中。
+_SYSTEM_COLUMN_NAMES = {
+    0: "apply_num",
+    1: "apply_user",
+    2: "apply_time",
+    3: "update_time",
+    4: "current_node",
+    5: "current_status",
+    6: "current_user",
+    -1: "data_source",
+    -2: "user_dept",
+    -3: "audit_node",
+    -4: "audit_node_user",
+    -5: "audit_status",
+    -6: "audit_time",
+    -7: "timeout_time",
+    -8: "audit_table",
+    -18: "error_info",
+    -19: "delete_time",
+    -20: "deleter",
+    -21: "processing_node",
+    -22: "cc_node",
+    -23: "processing_time",
+    -24: "cc_time",
+    -25: "receive_time",
+    -30: "app_key",
+    -31: "ws_id",
+}
+
+# complete 契约不覆盖、读面存在的配置键(进入 SKIP 账本,evaluation.md §4.3)
+_UNCOVERED_READBACK_KEYS = (
+    "attachVisibleOnlyConfig",
+    "beingRemarkStatus",
+    "querySearchStatus",
+    "beingDefaultPrintTplStatus",
+    "usages",
+)
+
+
+def _gap(reason_path: str, kind: str, message: str, **details: Any) -> dict[str, Any]:
+    gap: dict[str, Any] = {"reason_path": reason_path, "kind": kind, "message": message}
+    if details:
+        gap["details"] = details
+    return gap
+
+
+def _extract_filters(
+    view_info: dict[str, Any],
+    *,
+    fields_by_que_id: dict[int, dict[str, Any]],
+    reason_path: str,
+    gaps: list[dict[str, Any]],
+) -> list[Any] | None:
+    """viewgraphLimit → filters。
+
+    简易模式(limitType=1):规则组是唯一真源(viewgraphLimitFormula 是后端从规则组派生的存储态,
+    提取时忽略);单组 → 扁平 [rule,...](组内 AND,向后兼容),多组 → 嵌套 [[rule,...],...]
+    (组间 OR、组内 AND,与 visible_when/root_filter 的嵌组形态对齐)。
+    公式模式(limitType!=1):用户手写公式串,规则组不含其语义,真不可表达 → gap。
+    """
+    limit_type = view_info.get("viewgraphLimitType")
+    if limit_type not in (None, 1):
+        gaps.append(
+            _gap(
+                f"{reason_path}",
+                "formula_filters",
+                "viewgraphLimitType!=1 (formula mode) is not expressible in v1alpha1; view is not extractable",
+                viewgraphLimitType=limit_type,
+            )
+        )
+        return None
+    groups = view_info.get("viewgraphLimit")
+    if not groups:
+        return None
+    raw_groups = [groups] if isinstance(groups, list) and all(isinstance(rule, dict) for rule in groups) else groups
+    if not isinstance(raw_groups, list) or any(
+        not isinstance(group, list) or not group or any(not isinstance(rule, dict) for rule in group)
+        for group in raw_groups
+    ):
+        gaps.append(_gap(reason_path, "unresolved_filter_rules", "filter groups contain an invalid or empty group"))
+        return None
+    public_groups = _public_view_filter_groups_from_match_rules(groups, fields_by_que_id=fields_by_que_id)
+    if [len(group) for group in public_groups] != [len(group) for group in raw_groups]:
+        gaps.append(_gap(reason_path, "unresolved_filter_rules", "filter rules could not be completely extracted"))
+        return None
+    normalized_groups: list[list[dict[str, Any]]] = []
+    for group_index, raw_rules in enumerate(public_groups):
+        normalized_group: list[dict[str, Any]] = []
+        for rule in raw_rules:
+            operator = str(rule.get("operator") or "")
+            if operator.startswith("judge_type:"):
+                gaps.append(
+                    _gap(
+                        f"{reason_path}[{group_index}]",
+                        "unsupported_operator",
+                        "filter operator not in the v1alpha1 operator set",
+                        operator=operator,
+                    )
+                )
+                continue
+            field_que_id = _coerce_positive_int(rule.get("que_id"))
+            if field_que_id is None or field_que_id not in fields_by_que_id:
+                gaps.append(
+                    _gap(
+                        f"{reason_path}[{group_index}]",
+                        "unresolved_filter_field",
+                        "filter rule que_id does not resolve to a form field",
+                        que_id=rule.get("que_id"),
+                    )
+                )
+                continue
+            entry: dict[str, Any] = {"que_id": field_que_id, "operator": operator}
+            if operator in {"is_empty", "not_empty"}:
+                entry["values"] = []
+            elif operator == "in" and not (rule.get("values") or []) and rule.get("value") is None:
+                # ANY 判型+空值 = "未选任何值"合法形态,judgeType 保真回写
+                entry["values"] = []
+            elif isinstance(rule.get("values"), list) and rule["values"]:
+                entry["values"] = rule["values"]
+            elif rule.get("value") is not None:
+                entry["values"] = [rule["value"]]
+            else:
+                gaps.append(
+                    _gap(
+                        f"{reason_path}[{group_index}]",
+                        "empty_filter_values",
+                        "filter rule has no resolvable values",
+                        rule=rule,
+                    )
+                )
+                continue
+            normalized_group.append(entry)
+        if normalized_group:
+            normalized_groups.append(normalized_group)
+    if not normalized_groups:
+        return None
+    # 单组 → 扁平(兼容既有声明);多组 → 嵌套(OR of AND)
+    return normalized_groups[0] if len(normalized_groups) == 1 else normalized_groups
+
+
+def _extract_sort(
+    view_info: dict[str, Any],
+    *,
+    fields_by_que_id: dict[int, dict[str, Any]],
+    reason_path: str,
+    gaps: list[dict[str, Any]],
+) -> list[dict[str, Any]] | None:
+    """viewgraphSorts + sortType → sort;defaultSort(含 queId=0 占位)不产出。"""
+    if str(view_info.get("sortType") or "").strip() != "customSort":
+        return None
+    sorts: list[dict[str, Any]] = []
+    for index, raw in enumerate(view_info.get("viewgraphSorts") or []):
+        if not isinstance(raw, dict):
+            continue
+        que_id = raw.get("queId")
+        if _coerce_positive_int(que_id) in (None, 0):
+            continue
+        parsed_sort = _coerce_positive_int(que_id)
+        if parsed_sort in (None, 0):
+            continue
+        if parsed_sort not in fields_by_que_id:
+            gaps.append(_gap(f"{reason_path}[{index}]", "unresolved_que_id", "sort queId not in form field schema", que_id=parsed_sort))
+            continue
+        sorts.append({"que_id": parsed_sort, "ascending": bool(raw.get("beingSortAscend", True))})
+    return sorts or None
+
+
+def _extract_buttons(
+    view_info: dict[str, Any],
+    *,
+    fields_by_que_id: dict[int, dict[str, Any]],
+    reason_path: str,
+    gaps: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """从完整按钮读面提取绑定；DTO 列表仅作为旧读面的回退。"""
+    bindings: list[dict[str, Any]] = []
+    entries, entry_source = _extract_view_button_entries(view_info)
+    if entry_source in {"buttonConfigVO", "buttonConfigDTOList"} and len(entries) != len(view_info[entry_source]):
+        gaps.append(_gap(reason_path, "unresolved_button_entry", "button list contains invalid entries"))
+    for index, raw in enumerate(entries):
+        button_type = str(raw.get("buttonType") or "").upper()
+        if not button_type and entry_source == "buttonConfigDTOList":
+            button_type = "CUSTOM" if raw.get("buttonId") is not None else "SYSTEM"
+        if button_type not in {"SYSTEM", "CUSTOM"}:
+            gaps.append(_gap(f"{reason_path}[{index}].button_type", "unresolved_button_type", "button type could not be resolved"))
+            continue
+        button_id = _coerce_positive_int(raw.get("buttonId"))
+        if button_type == "SYSTEM":
+            # 系统按钮会由后端重建；自定义按钮必须使用实体 ID，不能使用配置行 ID。
+            button_id = _resolve_system_view_button_logical_id(raw) or button_id or _coerce_positive_int(raw.get("id"))
+        if button_id is None:
+            gaps.append(_gap(f"{reason_path}[{index}].button_id", "button_without_id", "button binding has no resolvable button ID", button_type=button_type))
+            continue
+        unsupported = [key for key in ("targetFormId", "triggerAddDataConfig", "triggerLinkUrl", "triggerWingsConfig", "httpRequestConfig") if raw.get(key) not in (None, "", [], {})]
+        if button_type == "SYSTEM" and unsupported:
+            gaps.append(_gap(f"{reason_path}[{index}]", "unsupported_button_config", "button action configuration cannot be represented by a binding", keys=unsupported))
+            continue
+        binding: dict[str, Any] = {
+            "button_id": button_id,
+            "config_type": str(raw.get("configType") or "TOP"),
+        }
+        binding["button_type"] = button_type
+        for source_key, target in (
+            ("buttonText", "button_text"),
+            ("buttonIcon", "button_icon"),
+            ("backgroundColor", "background_color"),
+            ("textColor", "text_color"),
+            ("triggerAction", "trigger_action"),
+        ):
+            if raw.get(source_key) is not None:
+                binding[target] = raw.get(source_key)
+        if raw.get("stylePreset"):
+            binding["style_preset"] = raw.get("stylePreset")
+        binding["being_main"] = bool(raw.get("beingMain"))
+        if raw.get("printTpls"):
+            binding["print_tpls"] = raw.get("printTpls")
+        if raw.get("buttonFormula") is not None:
+            binding["button_formula"] = raw.get("buttonFormula")
+        binding["button_formula_type"] = raw.get("buttonFormulaType") or 1
+        if raw.get("buttonLimit"):
+            public_limits = _extract_filters(
+                {"viewgraphLimit": raw["buttonLimit"], "viewgraphLimitType": 1},
+                fields_by_que_id=fields_by_que_id,
+                reason_path=f"{reason_path}[{index}].button_limit",
+                gaps=gaps,
+            )
+            if public_limits and isinstance(public_limits[0], dict):
+                public_limits = [public_limits]
+            binding["button_limit"] = public_limits or []
+        bindings.append(binding)
+    return bindings
+
+
+def _optionally(target: dict[str, Any], key: str, value: Any) -> None:
+    if value is None:
+        return
+    if isinstance(value, str) and not value.strip():
+        return
+    target[key] = value
+
+
+def extract_complete_view_declaration(
+    view_info: dict[str, Any],
+    *,
+    fields_by_que_id: dict[int, dict[str, Any]],
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    """把后端 ViewgraphInfo(GET /view/{key}/viewConfig 的 data)反向编译为 complete 档声明。
+
+    返回 (declaration, coverage_gaps)。声明可再经 `views validate` 离线校验;
+    gaps 覆盖:v1alpha1 契约外的配置面(公式/OR 组/系统列/打印模板等)与解析失败项。
+    """
+    gaps: list[dict[str, Any]] = []
+    name_by_que_id: dict[int, str] = {}
+    for que_id, field in fields_by_que_id.items():
+        name = str(field.get("name") or "").strip() if isinstance(field, dict) else ""
+        if name:
+            name_by_que_id[que_id] = name
+
+    raw_type = str(view_info.get("viewgraphType") or "").strip()
+    view_type = _VIEW_TYPE_BY_BACKEND.get(raw_type)
+    if view_type is None:
+        gaps.append(_gap("type", "unsupported_view_type", "viewgraphType is not a public v1alpha1 type", viewgraphType=raw_type))
+        return {}, gaps
+
+    declaration: dict[str, Any] = {"type": view_type, "name": str(view_info.get("viewgraphName") or "").strip()}
+    view_key = str(view_info.get("viewgraphKey") or "").strip()
+    if view_key:
+        declaration["view_key"] = view_key
+
+    columns: list[int] = []
+    for index, que_id in enumerate(view_info.get("viewgraphQueIds") or []):
+        parsed = _coerce_any_int(que_id)
+        if parsed in _SYSTEM_COLUMN_NAMES:
+            columns.append(parsed)
+            continue
+        if parsed is None or parsed <= 0:
+            gaps.append(
+                _gap(f"columns[{index}]", "system_column", "unknown system column is not supported by the public contract", que_id=que_id)
+            )
+            continue
+        if parsed not in fields_by_que_id:
+            gaps.append(
+                _gap(f"columns[{index}]", "unresolved_que_id", "queId does not exist in the form field schema", que_id=parsed)
+            )
+            continue
+        columns.append(parsed)
+    if columns:
+        declaration["columns"] = columns
+    elif view_type in {"table", "card"}:
+        # table/card 至少要有一列；系统列也属于后端可展示列。
+        gaps.append(
+            _gap("columns", "no_resolvable_columns", "table/card view has no columns resolvable to field names; view is not extractable")
+        )
+        return {}, gaps
+
+    group_que_id = _coerce_positive_int(view_info.get("groupQueId"))
+    if view_type == "board":
+        if group_que_id and group_que_id not in fields_by_que_id:
+            gaps.append(_gap("group_que_id", "unresolved_que_id", "board group queId not in form field schema", que_id=group_que_id))
+            group_que_id = None
+        if group_que_id:
+            declaration["group_que_id"] = group_que_id
+        else:
+            gaps.append(
+                _gap("group_by", "unresolved_board_group", "board view groupQueId does not resolve; view is not extractable")
+            )
+            return {}, gaps
+
+    gantt_raw = view_info.get("viewgraphGanttConfigVO") if isinstance(view_info.get("viewgraphGanttConfigVO"), dict) else {}
+    if view_type == "gantt":
+        start_que_id = _coerce_positive_int(gantt_raw.get("startTimeQueId"))
+        end_que_id = _coerce_positive_int(gantt_raw.get("endTimeQueId"))
+        title_que_id = _coerce_positive_int(gantt_raw.get("titleQueId")) or _coerce_positive_int(view_info.get("titleQue"))
+        # 系统列(queId<=5)或已删字段的 queId 不在 fields_by_que_id——不可引用,丢弃+gap
+        if start_que_id and start_que_id not in fields_by_que_id:
+            gaps.append(_gap("gantt.start_que_id", "unresolved_que_id", "start queId not in form field schema", que_id=start_que_id))
+            start_que_id = None
+        if end_que_id and end_que_id not in fields_by_que_id:
+            gaps.append(_gap("gantt.end_que_id", "unresolved_que_id", "end queId not in form field schema", que_id=end_que_id))
+            end_que_id = None
+        if title_que_id and title_que_id not in fields_by_que_id:
+            gaps.append(_gap("gantt.title_que_id", "unresolved_que_id", "title queId not in form field schema", que_id=title_que_id))
+            title_que_id = None
+        if not (start_que_id and end_que_id):
+            # 契约要求 gantt 必须有 start/end;存量存在配置一半的视图(无起止字段),
+            # 判不可提取入账本,而非产出缺字段的非法声明
+            gaps.append(_gap("gantt", "unresolved_gantt_config", "gantt start/end fields do not resolve; view is not extractable"))
+            return {}, gaps
+        declaration["start_que_id"] = start_que_id
+        declaration["end_que_id"] = end_que_id
+        _optionally(declaration, "title_que_id", title_que_id)
+        gantt: dict[str, Any] = {}
+        _optionally(gantt, "title_que_id", title_que_id)
+        _optionally(gantt, "start_que_id", start_que_id)
+        _optionally(gantt, "end_que_id", end_que_id)
+        _optionally(gantt, "default_time_dimension", gantt_raw.get("defaultTimeDimension"))
+        groups: list[dict[str, Any]] = []
+        for raw_group in gantt_raw.get("ganttGroupVOList") or []:
+            if not isinstance(raw_group, dict):
+                continue
+            group_que = _coerce_positive_int(raw_group.get("groupQueId"))
+            if group_que:
+                entry: dict[str, Any] = {"que_id": group_que}
+                _optionally(entry, "ordinal", raw_group.get("ordinal"))
+                groups.append(entry)
+        if groups:
+            gantt["groups"] = groups
+        dependency_raw = gantt_raw.get("ganttDependencyVO") if isinstance(gantt_raw.get("ganttDependencyVO"), dict) else {}
+        if dependency_raw.get("dependencyQueId") is not None or dependency_raw.get("predecessorTaskQueId") is not None:
+            dependency: dict[str, Any] = {}
+            dep_que = _coerce_positive_int(dependency_raw.get("dependencyQueId"))
+            pred_que = _coerce_positive_int(dependency_raw.get("predecessorTaskQueId"))
+            if dep_que and pred_que:
+                dependency = {"dependency_que_id": dep_que, "predecessor_que_id": pred_que}
+                _optionally(dependency, "start_start_option_id", dependency_raw.get("startStartOptionId"))
+                _optionally(dependency, "start_end_option_id", dependency_raw.get("startEndOptionId"))
+                _optionally(dependency, "end_start_option_id", dependency_raw.get("endStartOptionId"))
+                _optionally(dependency, "end_end_option_id", dependency_raw.get("endEndOptionId"))
+                gantt["dependencies"] = [dependency]
+            else:
+                gaps.append(_gap("gantt.dependencies", "unresolved_gantt_dependency", "gantt dependency queIds do not resolve", raw=dependency_raw))
+        if gantt:
+            declaration["gantt"] = gantt
+
+    hierarchy_raw = view_info.get("viewgraphHierarchyConfigVO") if isinstance(view_info.get("viewgraphHierarchyConfigVO"), dict) else {}
+    if view_type == "hierarchy":
+        title_que = _coerce_positive_int(hierarchy_raw.get("titleQueId"))
+        children_que = _coerce_positive_int(hierarchy_raw.get("childrenQueId"))
+        if not (title_que and children_que):
+            gaps.append(_gap("hierarchy", "unresolved_hierarchy_config", "hierarchy title/children queIds do not resolve; view is not extractable"))
+            return {}, gaps
+        hierarchy: dict[str, Any] = {"title_que_id": title_que, "children_que_id": children_que}
+        root_groups = _public_view_filter_groups_from_match_rules(
+            hierarchy_raw.get("rootNodeFilter"), fields_by_que_id=fields_by_que_id
+        )
+        if root_groups:
+            hierarchy["root_filter"] = root_groups
+        declaration["hierarchy"] = hierarchy
+        _optionally(declaration, "title_que_id", title_que)
+
+    if view_type == "calendar":
+        calendar_raw = view_info.get("viewgraphCalendarConfigVO") if isinstance(view_info.get("viewgraphCalendarConfigVO"), dict) else {}
+        title_que = _coerce_positive_int(calendar_raw.get("titleQueId"))
+        date_que = _coerce_any_int(calendar_raw.get("dateQueId"))
+        color_que = _coerce_positive_int(calendar_raw.get("colorQueId"))
+        if title_que is None or title_que not in fields_by_que_id:
+            gaps.append(_gap("calendar.title_que_id", "unresolved_calendar_config", "calendar title queId does not resolve; view is not extractable", que_id=title_que))
+            return {}, gaps
+        if date_que is None or (date_que not in {2, 3} and date_que not in fields_by_que_id):
+            gaps.append(_gap("calendar.date_que_id", "unresolved_calendar_config", "calendar date queId does not resolve; view is not extractable", que_id=date_que))
+            return {}, gaps
+        calendar: dict[str, Any] = {"title_que_id": title_que, "date_que_id": date_que}
+        if color_que is not None:
+            if color_que not in fields_by_que_id:
+                gaps.append(_gap("calendar.color_que_id", "unresolved_que_id", "calendar color queId does not resolve", que_id=color_que))
+                return {}, gaps
+            calendar["color_que_id"] = color_que
+        declaration["calendar"] = calendar
+        declaration["title_que_id"] = title_que
+
+    if view_type in {"card", "board"}:
+        _optionally(declaration, "title_que_id", _coerce_positive_int(view_info.get("titleQue")))
+
+    if view_type == "card":
+        card: dict[str, Any] = {}
+        for raw_key, gap_key in (("titleQue", "title_que_id"), ("frontCoverQueId", "cover_que_id")):
+            raw_val = _coerce_positive_int(view_info.get(raw_key))
+            if raw_val and raw_val not in fields_by_que_id:
+                gaps.append(_gap(f"card.{gap_key}", "unresolved_que_id", f"card {gap_key} not in form field schema", que_id=raw_val))
+            else:
+                _optionally(card, gap_key, raw_val)
+        _optionally(card, "clipping_mode", view_info.get("clippingMode"))
+        _optionally(card, "image_adaption", view_info.get("beingImageAdaption"))
+        _optionally(card, "show_field_title", view_info.get("beingShowQueTitle"))
+        _optionally(card, "show_title", view_info.get("beingShowTitleQue"))
+        _optionally(card, "show_cover", view_info.get("beingShowCover"))
+        if group_que_id and group_que_id not in fields_by_que_id:
+            gaps.append(_gap("card.group_que_id", "unresolved_que_id", "card group queId not in form field schema", que_id=group_que_id))
+        else:
+            _optionally(card, "group_que_id", group_que_id)
+        _optionally(card, "group_color", view_info.get("beingGroupColor"))
+        if card:
+            declaration["card"] = card
+
+    filter_gap_count = len(gaps)
+    filters = _extract_filters(view_info, fields_by_que_id=fields_by_que_id, reason_path="filters", gaps=gaps)
+    if len(gaps) > filter_gap_count:
+        return {}, gaps
+    if filters is not None:
+        declaration["filters"] = filters
+
+    data_permission_type = str(view_info.get("dataPermissionType") or "").strip().upper()
+    data_scope = _DATA_SCOPE_TO_PUBLIC.get(str(view_info.get("dataScope") or "").strip().upper())
+    if data_permission_type or data_scope:
+        declaration["data_permission"] = {
+            "type": "config" if data_permission_type == "CONFIG" else "custom",
+            "scope": data_scope or "all",
+        }
+
+    sort = _extract_sort(view_info, fields_by_que_id=fields_by_que_id, reason_path="sort", gaps=gaps)
+    if sort is not None:
+        declaration["sort"] = sort
+
+    auth = view_info.get("auth")
+    if auth is not None:
+        visibility = _public_visibility_from_member_auth(auth)
+        # mode="specific" + 空 selectors 是合法形态(auth=2 但未配置成员);
+        # apply 回写 auth=2 + 空成员列表,语义保真,不降级。
+        declaration["visibility"] = visibility
+
+    button_gap_count = len(gaps)
+    buttons = _extract_buttons(view_info, fields_by_que_id=fields_by_que_id, reason_path="buttons", gaps=gaps)
+    if len(gaps) > button_gap_count:
+        return {}, gaps
+    if _extract_view_button_entries(view_info)[1] is not None:
+        declaration["buttons"] = buttons
+
+    if view_info.get("queryConditionStatus") is not None:
+        rows: list[list[str]] = []
+        for raw_row in view_info.get("queryCondition") or []:
+            if not isinstance(raw_row, dict):
+                continue
+            row_names: list[str] = []
+            for index, que_id in enumerate(raw_row.get("queIds") or []):
+                parsed = _coerce_positive_int(que_id)
+                if parsed and parsed in fields_by_que_id:
+                    row_names.append(parsed)
+            if row_names:
+                rows.append(row_names)
+        if view_info.get("queryConditionStatus") and not rows:
+            gaps.append(_gap("query_conditions", "unresolved_query_condition", "queryConditionStatus=true but no queIds resolve to field names"))
+        else:
+            declaration["query_conditions"] = {
+                "enabled": bool(view_info.get("queryConditionStatus")),
+                "exact": bool(view_info.get("queryConditionExact")),
+                "hide_before_query": bool(view_info.get("hideBeforeQueryCondition")),
+                "rows": rows,
+            }
+
+    asos_raw = view_info.get("asosChartConfig") if isinstance(view_info.get("asosChartConfig"), dict) else {}
+    asos_visible = view_info.get("asosChartVisible")
+    if asos_visible is not None or asos_raw:
+        associated: dict[str, Any] = {"visible": bool(asos_visible)}
+        if associated["visible"]:
+            limit_type = asos_raw.get("limitType")
+            if limit_type is not None:
+                associated["limit_type"] = "all" if int(limit_type) == ASSOCIATED_RESOURCE_LIMIT_TYPE_ALL else "select"
+            item_ids = [item for item in asos_raw.get("asosChartIdList") or [] if item is not None]
+            if item_ids:
+                associated["associated_item_ids"] = item_ids
+        declaration["associated_resources"] = associated
+
+    display: dict[str, Any] = {}
+    _optionally(display, "row_height", view_info.get("defaultRowHigh"))
+    _optionally(display, "pin_navigate", view_info.get("beingPinNavigate"))
+    _optionally(display, "remark", view_info.get("remark"))
+    if display:
+        declaration["display"] = display
+
+    record: dict[str, Any] = {}
+    for source, target in (
+        ("beingAuditRecordVisible", "audit_visible"),
+        ("beingDataLogVisible", "data_log_visible"),
+        ("beingQrobotRecordVisible", "qrobot_record_visible"),
+        ("beingWorkflowNodeFutureListVisible", "workflow_future_visible"),
+        ("beingCommentStatus", "comment"),
+    ):
+        if view_info.get(source) is not None:
+            record[target] = bool(view_info.get(source))
+    if record:
+        declaration["record"] = record
+
+    share: dict[str, Any] = {}
+    if view_info.get("beingNeedPass") is not None:
+        share["need_pass"] = bool(view_info.get("beingNeedPass"))
+    # 历史数据保全项(legacy_data_preserved):存量密码不符合当前安全策略(49603)——
+    # 视图配置本身合法,后端策略演进导致无法原样回写。提取不回传敏感值,
+    # apply 显式清空触发后端 isNotBlank(空)保留语义,原密码/开关零丢失。
+    # 这类不是失败,单列统计。
+    if view_info.get("beingNeedPass") and str(view_info.get("viewgraphPass") or "").strip():
+        gaps.append(_gap("share.password", "legacy_password_preserved", "legacy password not round-tripped (backend policy); original preserved via isNotBlank semantics"))
+    if view_info.get("beingForceLogin") is not None:
+        share["force_login"] = bool(view_info.get("beingForceLogin"))
+    if view_info.get("beingPrintStatus") is not None:
+        share["print_enabled"] = bool(view_info.get("beingPrintStatus"))
+    if share:
+        declaration["share"] = share
+
+    if view_info.get("printTpls"):
+        gaps.append(_gap("share.print", "print_templates", "printTpls details are deferred to v1alpha2", count=len(view_info.get("printTpls") or [])))
+    for key in _UNCOVERED_READBACK_KEYS:
+        value = view_info.get(key)
+        if value in (None, [], {}, "", False):
+            continue
+        if key == "querySearchStatus" and value is True and view_info.get("queryConditionStatus") is None:
+            continue
+        gaps.append(_gap(key, "uncovered_readback_key", "read-back key present in backend payload but outside the v1alpha1 contract", value_preview=str(value)[:80]))
+
+    return declaration, gaps
+
+
+def summarize_gaps(gaps: list[dict[str, Any]]) -> dict[str, int]:
+    """按 kind 聚合 coverage gaps,供覆盖度报告使用。"""
+    summary: dict[str, int] = {}
+    for gap in gaps:
+        summary[gap.get("kind") or "unknown"] = summary.get(gap.get("kind") or "unknown", 0) + 1
+    return summary
+
+
+__all__ = [
+    "extract_complete_view_declaration",
+    "summarize_gaps",
+]