precis-cli 0.1.3__py3-none-any.whl

app/shared/core/project/loader/types.py

@@ -0,0 +1,246 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+@fileoverview 项目加载器类型定义
+
+功能概述:
+- 定义项目加载过程中的核心数据类型
+- 提供 LoadingError、LoadedProject、LoadedRegexNode 等数据类
+
+架构设计:
+- 不可变数据类: LoadedProject、LoadedRegexNode 使用 frozen dataclass
+- 延迟导入: 通过 TYPE_CHECKING 避免循环依赖
+
+输入示例:
+    LoadedProject(
+        manifest_path=Path("project.precis.yaml"),
+        manifest=manifest,
+        schema_files={"users": schema_file},
+        ...
+    )
+
+输出示例:
+    loading_errors = project.loading_errors  # List[LoadingError]
+"""
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol
+
+# 直接导入 RegexNodeFile（类型明确，不会引起循环依赖）
+from ..regex.types import RegexNodeFile
+from ..transform.types import TransformFile
+
+# 仅在类型检查阶段导入，避免运行时循环导入问题
+if TYPE_CHECKING:
+    from ..constraint.types import ConstraintFile
+    from ..manifest.types import ProjectManifest
+    from ..manual_data.types import ManualDataFile
+    from ..schema.types import TableSchemaFile
+
+
+@dataclass
+class LoadingError:
+    """@classdesc 加载错误详情
+
+    当项目加载过程中出现文件不存在、解析失败、路径错误等问题时，
+    会创建该对象记录错误的详细信息，便于后续排查和展示。
+
+    字段说明:
+        - error_type: 错误类型标识（如 SchemaNotFound、SchemaParseError 等）
+        - file_path: 发生错误的文件绝对路径
+        - ref_id: 对应 manifest 中引用的 ID（可选）
+        - message: 人类可读的错误描述
+        - suggestion: 修复建议
+
+    === 面向 UI 的扩展字段（前后端契约） ===
+        - id: 稳定唯一 id，用于"忽略"持久化（localStorage 等）
+        - severity: 严重度 — blocker（阻塞） | warning（警告） | info（提示）
+        - title: 人类可读的短标题（中文 fallback，前端有 title_key 时优先用 i18n 渲染）
+        - description: 根因说明（中文 fallback，前端有 description_key 时优先用 i18n 渲染）
+        - fix_hint: 高亮显示的修复建议（中文 fallback，前端有 fix_hint_key 时优先用 i18n 渲染）
+        - actions: 可执行动作列表（open_file / copy / dismiss / auto_fix / navigate）
+                   每个 action 可携带 label_key 用于前端 i18n 渲染
+        - fix_api: 一键修复的 API 描述（method/path/body）— 仅在"安全操作"时填充
+        - context: 上下文数据（如可用表列表、当前值与期望值），用于前端渲染对比表
+
+    === i18n 字段（可选） ===
+        - title_key / description_key / fix_hint_key: i18n 键名，前端有该 key 时优先渲染
+        - message_params: 模板参数字典，用于 i18n 字符串插值（如 {"constraintId": "fk_x"}）
+    """
+
+    error_type: str  # SchemaNotFound, SchemaParseError, ConstraintNotFound, etc.
+    file_path: str  # 出错的文件路径
+    ref_id: str | None = None  # 引用ID
+    message: str = ""  # 错误信息
+    suggestion: str = ""  # 修复建议
+
+    # === 面向 UI 的扩展字段 ===
+    id: str = ""  # 稳定 id，用于"忽略"持久化
+    severity: str = "warning"  # blocker | warning | info
+    title: str = ""  # 人类可读短标题
+    description: str = ""  # 根因说明
+    fix_hint: str = ""  # 修复建议（突出显示）
+    actions: list[dict] = field(default_factory=list)  # 可执行动作列表
+    fix_api: dict | None = None  # 一键修复 API 描述
+    context: dict = field(default_factory=dict)  # 上下文数据（用于渲染对比表等）
+
+    # === i18n 渲染字段（可选，前端有 key 时优先使用） ===
+    title_key: str = ""  # i18n key，对应 title
+    description_key: str = ""  # i18n key，对应 description
+    fix_hint_key: str = ""  # i18n key，对应 fix_hint
+    message_params: dict = field(default_factory=dict)  # i18n 插值参数
+
+    def to_dict(self) -> dict:
+        """@methoddesc 将错误对象序列化为字典格式
+
+        便于转换为 JSON 返回给前端或写入日志。
+
+        返回值:
+            {
+                "error_type": ...,
+                "file_path": ...,
+                "ref_id": ...,
+                "message": ...,
+                "suggestion": ...,
+                "id": ...,
+                "severity": ...,
+                "title": ...,
+                "description": ...,
+                "fix_hint": ...,
+                "actions": ...,
+                "fix_api": ...,
+                "context": ...,
+                "title_key": ...,
+                "description_key": ...,
+                "fix_hint_key": ...,
+                "message_params": ...,
+            }
+        """
+        return {
+            "error_type": self.error_type,
+            "file_path": self.file_path,
+            "ref_id": self.ref_id,
+            "message": self.message,
+            "suggestion": self.suggestion,
+            "id": self.id,
+            "severity": self.severity,
+            "title": self.title,
+            "description": self.description,
+            "fix_hint": self.fix_hint,
+            "actions": self.actions,
+            "fix_api": self.fix_api,
+            "context": self.context,
+            "title_key": self.title_key,
+            "description_key": self.description_key,
+            "fix_hint_key": self.fix_hint_key,
+            "message_params": self.message_params,
+        }
+
+
+class SchemaBuilder(Protocol):
+    """@classdesc 运行时数据集 Schema 构建器协议（依赖注入用）
+
+    core 层的 load_project 不应直接依赖 services 层。通过此协议，
+    load_project 接收一个外部注入的构建器回调来完成
+    "core 文件对象 → domain 运行时对象" 的转换，
+    从而把层依赖方向保持为 services → core（而非 core → services）。
+
+    dataset_schema 的返回类型用 Any，使 core 层不静态依赖 domain。
+    具体实现由 services 层提供（见 services/project_loader.build_dataset_schema）。
+    """
+
+    def __call__(
+        self,
+        schema_files: dict[str, "TableSchemaFile"],
+        constraint_files: dict[str, "ConstraintFile"],
+        registries: dict[str, Any],
+    ) -> tuple[Any, list[str]]:
+        """构建运行时数据集 Schema。
+
+        :param schema_files: schema 配置文件字典
+        :param constraint_files: constraint 配置文件字典
+        :param registries: 表达式注册表等辅助对象
+        :return: (dataset_schema, 警告列表)
+        """
+        ...
+
+
+@dataclass(frozen=True)
+class LoadedProject:
+    """@classdesc 已加载项目的完整数据结构
+
+    该对象包含从 manifest 文件加载后的所有配置和运行时对象，
+    是项目加载流程的最终产物。
+
+    字段说明:
+        - manifest_path: manifest 文件路径
+        - manifest: manifest 原始数据对象
+        - schema_files: 所有 schema 配置文件的映射（table_id -> TableSchemaFile）
+        - constraint_files: 所有约束配置文件的映射（constraint_id -> ConstraintFile）
+        - regex_node_files: 所有正则节点配置文件的映射（regex_id -> RegexNodeFile）
+        - dataset_schema: 运行时的数据集 Schema（包含 TableSchema 和约束实例）
+        - warnings: 加载过程中的警告信息列表
+        - loading_errors: 加载过程中的错误信息列表
+        - constraint_source_files: 约束 ID -> 来源文件路径（相对 manifest 目录）映射。
+            独立约束文件为 constraint YAML 路径，schema 内嵌约束为 schema 文件路径。
+            供校验错误回溯 constraint_file（P0-3），模板展开产物不在映射中。
+    """
+
+    manifest_path: Path
+    manifest: "ProjectManifest"
+    schema_files: dict[str, "TableSchemaFile"]
+    constraint_files: dict[str, "ConstraintFile"]
+    regex_node_files: dict[str, RegexNodeFile]
+    dataset_schema: Any
+    transform_files: dict[str, TransformFile] | None = None
+    manual_data_files: dict[str, "ManualDataFile"] | None = None
+    warnings: list[str] | None = None
+    loading_errors: list[LoadingError] | None = None
+    constraint_source_files: dict[str, str] | None = None
+
+    def __post_init__(self) -> None:
+        # frozen=True 表示实例创建后不可变，因此必须通过 object.__setattr__ 来修改属性
+        if self.warnings is None:
+            object.__setattr__(self, "warnings", [])
+        if self.loading_errors is None:
+            object.__setattr__(self, "loading_errors", [])
+        if self.transform_files is None:
+            object.__setattr__(self, "transform_files", {})
+        if self.manual_data_files is None:
+            object.__setattr__(self, "manual_data_files", {})
+        if self.constraint_source_files is None:
+            object.__setattr__(self, "constraint_source_files", {})
+
+
+@dataclass(frozen=True)
+class LoadedRegexNode:
+    """@classdesc 已加载的正则表达式节点数据
+
+    将 RegexNodeFile 配置与编译后的正则模式、源表/列引用封装在一起。
+
+    字段说明:
+        - config: 原始的 RegexNodeFile 配置对象
+        - pattern: 编译后的正则表达式模式（re.Pattern）
+        - source_table: 该正则节点引用的源表 ID（可选）
+        - source_column: 该正则节点引用的源列 ID（可选）
+    """
+
+    config: RegexNodeFile
+    pattern: re.Pattern
+    source_table: str | None
+    source_column: str | None

app/shared/core/project/manifest/coverage.py

@@ -0,0 +1,391 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+@fileoverview 项目清单覆盖度检查模块
+
+功能概述:
+- 计算 project.precis.yaml 清单与实际磁盘文件的覆盖关系
+- 检测未入清单的资源（unlisted）和清单引用但缺失的资源（dangling）
+- 为前端提供清单一致性诊断数据
+
+架构设计:
+- 纯函数设计: compute_manifest_coverage 无副作用，仅读取文件系统
+- 数据类: CoverageRef、ManifestCoverage 使用 frozen dataclass 保证不可变性
+- 扫描策略: 分别扫描 schemas/、constraints/、regex/ 目录与清单比对
+
+输入示例:
+    manifest = ProjectManifestV2(
+        schemas=[SchemaRef(id="users", path="schemas/users.schema.yaml")],
+        constraints=[],
+        regex_nodes=[],
+    )
+    coverage = compute_manifest_coverage("/path/to/project", manifest)
+
+输出示例:
+    ManifestCoverage(
+        unlisted_schemas=[CoverageRef(id="orders", path="schemas/orders.schema.yaml")],
+        unlisted_constraints=[],
+        unlisted_regex_nodes=[],
+        dangling_schemas=[CoverageRef(id="old_users", path="schemas/old_users.schema.yaml")],
+        dangling_constraints=[],
+        dangling_regex_nodes=[],
+    )
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from app.shared.core.io.yaml import read_yaml
+from app.shared.core.project.manifest.types import ProjectManifestV2
+from app.shared.core.utils.path_utils import normalize_to_posix
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class CoverageRef:
+    """@classdesc 单个资源的覆盖度引用
+
+    用于标识一个具体的配置文件，包含资源 ID 和文件路径。
+
+    字段说明:
+        - id: 资源的唯一标识符（从文件名或文件内容中提取）
+        - path: 文件相对于项目根目录的路径
+
+    示例:
+        CoverageRef(id="users", path="schemas/users.schema.yaml")
+    """
+
+    id: str  # 资源唯一标识符
+    path: str  # 文件相对路径
+
+
+@dataclass(frozen=True)
+class ManifestCoverage:
+    """@classdesc 清单覆盖度结果
+
+    保存清单与实际磁盘文件的对比结果，分为两类：
+    - unlisted: 磁盘上有但清单中未引用的文件（遗漏配置）
+    - dangling: 清单中引用了但磁盘上缺失的文件（无效引用）
+
+    字段说明:
+        - unlisted_schemas: 未入清单的 schema 文件
+        - unlisted_constraints: 未入清单的 constraint 文件
+        - unlisted_regex_nodes: 未入清单的 regex 文件
+        - dangling_schemas: 引用但缺失的 schema 文件
+        - dangling_constraints: 引用但缺失的 constraint 文件
+        - dangling_regex_nodes: 引用但缺失的 regex 文件
+
+    示例:
+        ManifestCoverage(
+            unlisted_schemas=[CoverageRef(id="orders", path="schemas/orders.schema.yaml")],
+            unlisted_constraints=[],
+            unlisted_regex_nodes=[],
+            dangling_schemas=[CoverageRef(id="old_users", path="schemas/old_users.schema.yaml")],
+            dangling_constraints=[],
+            dangling_regex_nodes=[],
+        )
+    """
+
+    unlisted_schemas: list[CoverageRef]  # 磁盘存在但清单未引用的 schema
+    unlisted_constraints: list[CoverageRef]  # 磁盘存在但清单未引用的 constraint
+    unlisted_regex_nodes: list[CoverageRef]  # 磁盘存在但清单未引用的 regex
+    unlisted_transforms: list[CoverageRef]  # 磁盘存在但清单未引用的 transform
+    unlisted_manual_data: list[CoverageRef]  # 磁盘存在但清单未引用的 manual_data
+    dangling_schemas: list[CoverageRef]  # 清单引用但磁盘缺失的 schema
+    dangling_constraints: list[CoverageRef]  # 清单引用但磁盘缺失的 constraint
+    dangling_regex_nodes: list[CoverageRef]  # 清单引用但磁盘缺失的 regex
+    dangling_transforms: list[CoverageRef]  # 清单引用但磁盘缺失的 transform
+    dangling_manual_data: list[CoverageRef]  # 清单引用但磁盘缺失的 manual_data
+
+
+def compute_manifest_coverage(config_path: str, manifest: ProjectManifestV2) -> ManifestCoverage:
+    """@methoddesc 计算清单与实际磁盘文件的覆盖关系
+
+    本函数通过对比 manifest 中记录的文件引用与磁盘上实际存在的文件，
+    发现两类问题：
+    1. unlisted（未入清单）：磁盘上有配置文件，但 manifest 里没有引用它
+    2. dangling（悬空引用）：manifest 里引用了某个文件，但磁盘上找不到它
+
+    ============================================================================
+    处理流程
+    ============================================================================
+    1. 构建三个目录路径：schemas/、constraints/、regex/
+    2. 收集 manifest 中已引用的文件路径和 ID
+    3. 扫描磁盘目录，找出未入清单的文件（unlisted）
+    4. 遍历 manifest 引用，找出缺失的文件（dangling）
+    5. 组装并返回 ManifestCoverage 结果对象
+
+    ============================================================================
+    参数说明
+    ============================================================================
+    :param config_path: 项目根目录路径（manifest 所在目录）
+    :param manifest: 已加载的项目清单对象
+    :return: ManifestCoverage 覆盖度结果对象
+
+    ============================================================================
+    业务场景
+    ============================================================================
+    - 场景1: 项目健康检查
+      用户执行项目诊断时，系统调用此函数发现配置不一致问题。
+    - 场景2: 前端项目概览页面
+      前端展示项目配置完整性时，调用此接口获取统计数据。
+    """
+    # ============================================================================
+    # 第一步：构建三个资源目录的绝对路径
+    # ============================================================================
+    # 分别在项目根目录下查找 schemas、constraints、regex 子目录
+    schemas_dir = os.path.join(config_path, "schemas")
+    constraints_dir = os.path.join(config_path, "constraints")
+    regex_dir = os.path.join(config_path, "regex")
+    transforms_dir = os.path.join(config_path, "transforms")
+    manual_data_dir = os.path.join(config_path, "manual_data")
+
+    # ============================================================================
+    # 第二步：收集 manifest 中已引用的路径和 ID
+    # ============================================================================
+    # schema_paths 使用小写路径集合，用于不区分大小写的路径匹配
+    # 注意：schemas 使用 path 字段匹配，constraints 和 regex 使用 id 字段匹配
+    schema_paths = {normalize_to_posix(r.path or "").lower() for r in (manifest.schemas or [])}
+    constraint_ids = {r.id for r in (manifest.constraints or [])}
+    regex_ids = {r.id for r in (manifest.regex_nodes or [])}
+    transform_ids = {r.id for r in (manifest.transforms or [])}
+    manual_data_ids = {r.id for r in (manifest.manual_data or [])}
+
+    # ============================================================================
+    # 第三步：扫描 schemas 目录，找出未入清单的 schema 文件
+    # ============================================================================
+    # 遍历 schemas/ 目录下所有 .schema.yaml 结尾的文件
+    # 对于每个文件：
+    #   - 如果 manifest 中已引用（按路径匹配），跳过
+    #   - 否则，尝试读取文件内容获取真实的 id 字段
+    #   - 如果读取失败，使用文件名（去掉 .schema.yaml 后缀）作为 id
+    unlisted_schemas: list[CoverageRef] = []
+    if os.path.isdir(schemas_dir):
+        for filename in os.listdir(schemas_dir):
+            # 只处理 .schema.yaml 后缀的文件
+            if filename.lower().endswith(".schema.yaml"):
+                # 构建相对路径，统一使用正斜杠
+                rel_path = f"schemas/{filename}"
+                # 检查 manifest 中是否已引用该路径（不区分大小写）
+                if normalize_to_posix(rel_path).lower() in schema_paths:
+                    continue  # 已入清单，跳过
+                # 默认使用文件名（去掉 .schema.yaml）作为 id
+                rid = filename[:-12]
+                try:
+                    # 尝试读取文件内容，获取真实的 id 字段
+                    raw = read_yaml(Path(os.path.join(schemas_dir, filename)))
+                    file_id = raw.get("id") if isinstance(raw, dict) else None
+                    # 如果文件内 id 是有效的字符串，使用文件内的 id
+                    if isinstance(file_id, str) and file_id.strip():
+                        rid = file_id.strip()
+                except Exception as e:
+                    # 读取失败时记录警告，但仍使用文件名作为 id
+                    logger.warning(f"读取schema文件失败: {filename}, 错误: {e}")
+                # 将未入清单的 schema 添加到结果列表
+                unlisted_schemas.append(CoverageRef(id=rid, path=rel_path))
+    # 按 id 排序，保证输出结果稳定可预测
+    unlisted_schemas.sort(key=lambda r: r.id)
+
+    # ============================================================================
+    # 第四步：扫描 constraints 目录，找出未入清单的约束文件
+    # ============================================================================
+    # constraints 使用文件名（去掉 .constraint.yaml）作为 id，与 manifest 中的 id 匹配
+    unlisted_constraints: list[CoverageRef] = []
+    if os.path.isdir(constraints_dir):
+        for filename in os.listdir(constraints_dir):
+            if filename.lower().endswith(".constraint.yaml"):
+                # 从文件名中提取约束 id（去掉 .constraint.yaml 后缀）
+                rid = filename[:-16]
+                # 如果 manifest 中未引用该 id，则标记为未入清单
+                if rid not in constraint_ids:
+                    unlisted_constraints.append(CoverageRef(id=rid, path=f"constraints/{filename}"))
+    unlisted_constraints.sort(key=lambda r: r.id)
+
+    # ============================================================================
+    # 第五步：扫描 regex 目录，找出未入清单的正则文件
+    # ============================================================================
+    # regex 使用文件名（去掉 .regex.yaml）作为 id，与 manifest 中的 id 匹配
+    unlisted_regex_nodes: list[CoverageRef] = []
+    if os.path.isdir(regex_dir):
+        for filename in os.listdir(regex_dir):
+            if filename.lower().endswith(".regex.yaml"):
+                # 从文件名中提取 regex id（去掉 .regex.yaml 后缀）
+                rid = filename[:-11]
+                # 如果 manifest 中未引用该 id，则标记为未入清单
+                if rid not in regex_ids:
+                    unlisted_regex_nodes.append(CoverageRef(id=rid, path=f"regex/{filename}"))
+    unlisted_regex_nodes.sort(key=lambda r: r.id)
+
+    # ============================================================================
+    # 第五步扩展：扫描 transforms 目录，找出未入清单的 transform 文件
+    # ============================================================================
+    unlisted_transforms: list[CoverageRef] = []
+    if os.path.isdir(transforms_dir):
+        for filename in os.listdir(transforms_dir):
+            if filename.lower().endswith(".transform.yaml"):
+                rid = filename[: -len(".transform.yaml")]
+                if rid not in transform_ids:
+                    unlisted_transforms.append(CoverageRef(id=rid, path=f"transforms/{filename}"))
+    unlisted_transforms.sort(key=lambda r: r.id)
+
+    # ============================================================================
+    # 第五步扩展：扫描 manual_data 目录，找出未入清单的 manual_data 文件
+    # ============================================================================
+    unlisted_manual_data: list[CoverageRef] = []
+    if os.path.isdir(manual_data_dir):
+        for filename in os.listdir(manual_data_dir):
+            if filename.lower().endswith(".manual_data.yaml"):
+                rid = filename[: -len(".manual_data.yaml")]
+                if rid not in manual_data_ids:
+                    unlisted_manual_data.append(CoverageRef(id=rid, path=f"manual_data/{filename}"))
+    unlisted_manual_data.sort(key=lambda r: r.id)
+
+    # ============================================================================
+    # 第六步：检查 dangling schemas（清单引用但磁盘缺失）
+    # ============================================================================
+    # 遍历 manifest 中所有 schema 引用，检查对应的文件是否存在于磁盘
+    dangling_schemas: list[CoverageRef] = []
+    for schema_ref in manifest.schemas or []:
+        # 如果文件不存在，标记为悬空引用
+        if not os.path.isfile(os.path.join(config_path, schema_ref.path)):
+            dangling_schemas.append(CoverageRef(id=schema_ref.id, path=schema_ref.path))
+    dangling_schemas.sort(key=lambda r: r.id)
+
+    # ============================================================================
+    # 第七步：检查 dangling constraints（清单引用但磁盘缺失）
+    # ============================================================================
+    dangling_constraints: list[CoverageRef] = []
+    for constraint_ref in manifest.constraints or []:
+        if not os.path.isfile(os.path.join(config_path, constraint_ref.path)):
+            dangling_constraints.append(CoverageRef(id=constraint_ref.id, path=constraint_ref.path))
+    dangling_constraints.sort(key=lambda r: r.id)
+
+    # ============================================================================
+    # 第八步：检查 dangling regex nodes（清单引用但磁盘缺失）
+    # ============================================================================
+    dangling_regex_nodes: list[CoverageRef] = []
+    for regex_ref in manifest.regex_nodes or []:
+        if not os.path.isfile(os.path.join(config_path, regex_ref.path)):
+            dangling_regex_nodes.append(CoverageRef(id=regex_ref.id, path=regex_ref.path))
+    dangling_regex_nodes.sort(key=lambda r: r.id)
+
+    # ============================================================================
+    # 第八步扩展：检查 dangling transforms / manual_data（清单引用但磁盘缺失）
+    # ============================================================================
+    dangling_transforms: list[CoverageRef] = []
+    for transform_ref in manifest.transforms or []:
+        if not os.path.isfile(os.path.join(config_path, transform_ref.path)):
+            dangling_transforms.append(CoverageRef(id=transform_ref.id, path=transform_ref.path))
+    dangling_transforms.sort(key=lambda r: r.id)
+
+    dangling_manual_data: list[CoverageRef] = []
+    for manual_ref in manifest.manual_data or []:
+        if not os.path.isfile(os.path.join(config_path, manual_ref.path)):
+            dangling_manual_data.append(CoverageRef(id=manual_ref.id, path=manual_ref.path))
+    dangling_manual_data.sort(key=lambda r: r.id)
+
+    # ============================================================================
+    # 第九步：组装并返回覆盖度结果
+    # ============================================================================
+    return ManifestCoverage(
+        unlisted_schemas=unlisted_schemas,
+        unlisted_constraints=unlisted_constraints,
+        unlisted_regex_nodes=unlisted_regex_nodes,
+        unlisted_transforms=unlisted_transforms,
+        unlisted_manual_data=unlisted_manual_data,
+        dangling_schemas=dangling_schemas,
+        dangling_constraints=dangling_constraints,
+        dangling_regex_nodes=dangling_regex_nodes,
+        dangling_transforms=dangling_transforms,
+        dangling_manual_data=dangling_manual_data,
+    )
+
+
+def coverage_to_api_dict(coverage: ManifestCoverage) -> dict:
+    """@methoddesc 将 ManifestCoverage 对象转换为 API 响应字典
+
+    本函数将覆盖度检查结果转换为前端易用的字典格式，
+    包含一个 is_complete 标志和按类型分组的 unlisted/dangling 列表。
+
+    参数说明:
+        :param coverage: ManifestCoverage 覆盖度结果对象
+        :return: API 响应字典，结构如下:
+            {
+                "is_complete": bool,  # 是否完全覆盖（无任何问题）
+                "unlisted": {
+                    "schemas": [{"id": str, "path": str}, ...],
+                    "constraints": [...],
+                    "regex_nodes": [...],
+                },
+                "dangling": {
+                    "schemas": [...],
+                    "constraints": [...],
+                    "regex_nodes": [...],
+                },
+            }
+
+    示例:
+        >>> coverage = ManifestCoverage(
+        ...     unlisted_schemas=[CoverageRef(id="orders", path="schemas/orders.schema.yaml")],
+        ...     unlisted_constraints=[],
+        ...     unlisted_regex_nodes=[],
+        ...     dangling_schemas=[],
+        ...     dangling_constraints=[],
+        ...     dangling_regex_nodes=[],
+        ... )
+        >>> result = coverage_to_api_dict(coverage)
+        >>> result["is_complete"]
+        False
+        >>> len(result["unlisted"]["schemas"])
+        1
+    """
+    # is_complete 为 True 的条件：所有 unlisted 和 dangling 列表都为空
+    # 即没有任何遗漏配置，也没有任何无效引用
+    return {
+        "is_complete": not (
+            coverage.unlisted_schemas
+            or coverage.unlisted_constraints
+            or coverage.unlisted_regex_nodes
+            or coverage.unlisted_transforms
+            or coverage.unlisted_manual_data
+            or coverage.dangling_schemas
+            or coverage.dangling_constraints
+            or coverage.dangling_regex_nodes
+            or coverage.dangling_transforms
+            or coverage.dangling_manual_data
+        ),
+        # 未入清单的资源（磁盘有但清单未引用）
+        "unlisted": {
+            "schemas": [r.__dict__ for r in coverage.unlisted_schemas],
+            "constraints": [r.__dict__ for r in coverage.unlisted_constraints],
+            "regex_nodes": [r.__dict__ for r in coverage.unlisted_regex_nodes],
+            "transforms": [r.__dict__ for r in coverage.unlisted_transforms],
+            "manual_data": [r.__dict__ for r in coverage.unlisted_manual_data],
+        },
+        # 悬空引用的资源（清单引用但磁盘缺失）
+        "dangling": {
+            "schemas": [r.__dict__ for r in coverage.dangling_schemas],
+            "constraints": [r.__dict__ for r in coverage.dangling_constraints],
+            "regex_nodes": [r.__dict__ for r in coverage.dangling_regex_nodes],
+            "transforms": [r.__dict__ for r in coverage.dangling_transforms],
+            "manual_data": [r.__dict__ for r in coverage.dangling_manual_data],
+        },
+    }