precis-cli 0.1.3__py3-none-any.whl

app/shared/services/validation/report_export.py

@@ -0,0 +1,222 @@
+# 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 校验报告导出模块（P2-3 --report）
+
+功能概述:
+- 把 validate 的 JSON 契约 payload 导出为人类可分享的报告文件
+- HTML：自包含单文件（内联 CSS，无外部资源），违规明细表
+- Excel：openpyxl（backend 现有依赖），每张表一个 sheet，违规行标红
+
+设计说明:
+- 输入直接复用 `_build_json_payload` 的契约结构，保证
+  "stdout JSON / 报告文件" 两产物内容一致（验收口径）
+- 纯函数 + 显式路径参数，无隐藏 I/O；HTML 值经 html.escape 防注入
+"""
+
+from __future__ import annotations
+
+import html
+from pathlib import Path
+from typing import Any
+
+# 违规明细表的列头（HTML 与 Excel 共用口径）
+_REPORT_COLUMNS = ("表", "列", "行号", "值", "约束类型", "约束文件", "错误消息")
+
+
+def _error_row(entry: dict[str, Any]) -> list[str]:
+    """把契约错误条目转为报告行（None 统一展示为空串）。"""
+    message = entry.get("error_message") or ""
+    suggestion = entry.get("suggestion")
+    if suggestion:
+        # 修复建议拼进消息单元格，避免两种导出格式各加一列
+        message = f"{message}（建议：{suggestion}）"
+    return [
+        entry.get("table") or "",
+        entry.get("column") or "",
+        "" if entry.get("row_index") is None else str(entry["row_index"]),
+        "" if entry.get("cell_value") is None else str(entry["cell_value"]),
+        entry.get("constraint_type") or "",
+        entry.get("constraint_file") or "",
+        message,
+    ]
+
+
+def _summary_line(payload: dict[str, Any]) -> str:
+    """一句话概览：结论 + 检查数 + 耗时。"""
+    summary = payload.get("summary", {})
+    verdict = "通过" if payload.get("is_valid") else "发现违规"
+    return (
+        f"校验{verdict}：约束检查 {summary.get('constraints_total', 0)} 项，"
+        f"通过 {summary.get('constraints_passed', 0)} / 失败 {summary.get('constraints_failed', 0)}，"
+        f"耗时 {payload.get('duration_ms', 0)} ms"
+    )
+
+
+def export_html_report(payload: dict[str, Any], output_path: str | Path) -> Path:
+    """导出自包含 HTML 报告。
+
+    Args:
+        payload: validate JSON 契约 payload（_build_json_payload 输出）
+        output_path: 报告文件路径（.html）
+
+    Returns:
+        写入的文件路径
+
+    Raises:
+        OSError: 写文件失败
+    """
+    rows = payload.get("errors", [])
+    table_headers = "".join(f"<th>{html.escape(col)}</th>" for col in _REPORT_COLUMNS)
+    table_rows: list[str] = []
+    for index, entry in enumerate(rows, 1):
+        cells = "".join(f"<td>{html.escape(cell)}</td>" for cell in _error_row(entry))
+        row_class = "fail" if not payload.get("is_valid") else ""
+        table_rows.append(f'<tr class="{row_class}"><td class="idx">{index}</td>{cells}</tr>')
+    table_html = "".join(table_rows) if table_rows else '<tr><td colspan="8" class="empty">无违规记录</td></tr>'
+
+    tables_info = (
+        "、".join(
+            f"{t.get('name') or '?'}({t.get('rows') if t.get('rows') is not None else '?'} 行)"
+            for t in payload.get("tables", [])
+        )
+        or "无"
+    )
+
+    document = f"""<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<title>Precis 校验报告</title>
+<style>
+  body {{ font-family: "Segoe UI", "Microsoft YaHei", sans-serif; margin: 2rem; color: #1f2937; }}
+  h1 {{ font-size: 1.4rem; }}
+  .meta {{ color: #6b7280; margin-bottom: 1rem; }}
+  .verdict {{ display: inline-block; padding: 0.2rem 0.8rem; border-radius: 999px; font-weight: 600; }}
+  .verdict.pass {{ background: #d1fae5; color: #065f46; }}
+  .verdict.fail {{ background: #fee2e2; color: #991b1b; }}
+  table {{ border-collapse: collapse; width: 100%; font-size: 0.9rem; }}
+  th, td {{ border: 1px solid #d1d5db; padding: 0.4rem 0.6rem; text-align: left; vertical-align: top; }}
+  th {{ background: #f3f4f6; }}
+  tr.fail td {{ background: #fef2f2; }}
+  td.idx {{ color: #9ca3af; width: 2.5rem; }}
+  td.empty {{ text-align: center; color: #6b7280; padding: 2rem; }}
+</style>
+</head>
+<body>
+<h1>Precis 数据校验报告</h1>
+<p class="meta">
+  <span class="verdict {"pass" if payload.get("is_valid") else "fail"}">{"通过" if payload.get("is_valid") else "发现违规"}</span>
+  &nbsp;{_summary_line(payload)}
+  <br>数据表：{html.escape(tables_info)}
+</p>
+<table>
+<thead><tr><th>#</th>{table_headers}</tr></thead>
+<tbody>{table_html}</tbody>
+</table>
+</body>
+</html>
+"""
+    path = Path(output_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(document, encoding="utf-8")
+    return path
+
+
+def export_excel_report(payload: dict[str, Any], output_path: str | Path) -> Path:
+    """导出 Excel 报告（每张表一个 sheet，违规行标红）。
+
+    Sheet 组织：每张数据表一个 sheet（列出该表违规明细）；无表归属的错误
+    进入"汇总" sheet；另有"概览" sheet 记录结论与统计。
+
+    Args:
+        payload: validate JSON 契约 payload（_build_json_payload 输出）
+        output_path: 报告文件路径（.xlsx）
+
+    Returns:
+        写入的文件路径
+
+    Raises:
+        OSError: 写文件失败
+    """
+    from openpyxl import Workbook
+    from openpyxl.styles import Alignment, Font, PatternFill
+
+    red_fill = PatternFill(start_color="FFC7CE", end_color="FFC7CE", fill_type="solid")
+    header_font = Font(bold=True)
+
+    workbook = Workbook()
+    # 概览 sheet
+    overview = workbook.active
+    overview.title = "概览"
+    overview.append(["结论", "通过" if payload.get("is_valid") else "发现违规"])
+    for key, label in (
+        ("constraints_total", "约束检查总数"),
+        ("constraints_passed", "通过数"),
+        ("constraints_failed", "失败数"),
+    ):
+        overview.append([label, payload.get("summary", {}).get(key, 0)])
+    overview.append(["耗时(ms)", payload.get("duration_ms", 0)])
+    overview.append(["违规条数", len(payload.get("errors", []))])
+    overview.append(["数据表", ", ".join(str(t.get("name")) for t in payload.get("tables", []))])
+    for cell in overview[1]:
+        cell.font = header_font
+
+    # 按表分组违规条目（table 为空/None 的归入"汇总" sheet）
+    errors_by_table: dict[str, list[dict[str, Any]]] = {}
+    for entry in payload.get("errors", []):
+        key = entry.get("table") or "汇总"
+        errors_by_table.setdefault(key, []).append(entry)
+
+    sheet_names = {t.get("name") for t in payload.get("tables", []) if t.get("name")}
+    for name in sorted(sheet_names | set(errors_by_table.keys())):
+        # Excel sheet 名长度上限 31 字符，超长截断
+        sheet = workbook.create_sheet(title=name[:31])
+        sheet.append(list(_REPORT_COLUMNS))
+        for cell in sheet[1]:
+            cell.font = header_font
+            cell.alignment = Alignment(horizontal="center")
+        for entry in errors_by_table.get(name, []):
+            sheet.append(_error_row(entry))
+            for cell in sheet[sheet.max_row]:
+                cell.fill = red_fill
+        if not errors_by_table.get(name):
+            sheet.append(["（该表无违规）"])
+
+    path = Path(output_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    workbook.save(path)
+    return path
+
+
+def export_report(payload: dict[str, Any], output_path: str | Path) -> Path:
+    """按扩展名分派报告导出（.html/.htm → HTML；.xlsx → Excel）。
+
+    Args:
+        payload: validate JSON 契约 payload
+        output_path: 报告文件路径
+
+    Returns:
+        写入的文件路径
+
+    Raises:
+        ValueError: 扩展名不支持
+    """
+    suffix = Path(output_path).suffix.lower()
+    if suffix in (".html", ".htm"):
+        return export_html_report(payload, output_path)
+    if suffix == ".xlsx":
+        return export_excel_report(payload, output_path)
+    raise ValueError(f"不支持的报告格式: {suffix}（支持 .html / .xlsx）")

app/shared/services/validation/resolver.py

@@ -0,0 +1,180 @@
+# 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 数据源路径解析器
+
+功能概述:
+- 解析 manifest 中配置的第一个数据源目录（绝对/相对路径）
+- 根据 Schema source 定义解析文件路径
+- 自动发现匹配表名的数据文件（按扩展名优先级搜索）
+- 支持 Excel 多 sheet 场景的路径解析
+
+架构设计:
+- 单一职责模式: 只做路径解析，不涉及数据加载或校验
+- 从 ValidationExecutor 中提取，独立为可复用组件
+
+输入示例:
+    resolver = DataSourceResolver(project_root, manifest, schema_by_id)
+    data_dir = resolver.resolve_first_data_source()
+    file_path, sheet = resolver.resolve_source_path(data_dir, schema_file)
+
+输出示例:
+    data_dir = "/path/to/data"
+    file_path = "/path/to/data/users.xlsx"
+    sheet = "Sheet1"
+"""
+
+import logging
+import os
+
+from app.shared.core.project.manifest.types import ProjectManifestV2
+from app.shared.core.project.schema.types import TableSchemaFile
+from app.shared.core.utils.path_utils import normalize_to_posix
+
+logger = logging.getLogger(__name__)
+
+
+class DataSourceResolver:
+    """
+    @classdesc 数据源路径解析器
+
+    负责：
+    - 解析 manifest 中配置的第一个数据源目录
+    - 根据 Schema source 定义解析文件路径（绝对/相对）
+    - 自动发现匹配表名的数据文件（按扩展名优先级搜索）
+
+    设计决策：
+    - 从 ValidationExecutor 中提取，单一职责：只做路径解析，不涉及数据加载或校验
+    """
+
+    def __init__(
+        self,
+        project_root: str,
+        manifest: ProjectManifestV2,
+        schema_by_id: dict[str, TableSchemaFile],
+    ):
+        self.project_root = project_root
+        self.manifest = manifest
+        self._schema_by_id = schema_by_id
+
+    def resolve_first_data_source(self) -> str | None:
+        """
+        @methoddesc 解析 manifest 中配置的第一个数据源目录
+
+        返回第一个数据源对应的绝对路径。支持绝对路径和相对路径两种模式。
+
+        返回:
+            数据源目录的绝对路径，未配置或不存在则返回 None
+        """
+        if not self.manifest.data_sources:
+            return None
+
+        ds = self.manifest.data_sources[0]
+
+        if ds.mode == "absolute":
+            # 绝对路径模式：直接使用配置的路径
+            if os.path.isdir(ds.path):
+                return os.path.normpath(ds.path)
+            else:
+                logger.warning(f"[DataSourceResolver] 数据源目录不存在（绝对路径）: {ds.path}")
+                return None
+        else:
+            # 相对路径模式：基于项目根目录拼接
+            relative_path = os.path.join(self.project_root, ds.path)
+            if os.path.isdir(relative_path):
+                return os.path.normpath(relative_path)
+            else:
+                logger.warning(f"[DataSourceResolver] 数据源目录不存在（相对路径）: {relative_path}")
+                return None
+
+    def resolve_source_path(self, data_directory: str, schema_file: TableSchemaFile) -> tuple[str | None, str | None]:
+        """
+        @methoddesc 根据 Schema 定义解析数据源文件路径
+
+        按照以下优先级解析文件路径：
+        1. Schema 中显式配置的 source 路径（绝对文件或相对文件）
+        2. 自动发现：在数据目录中按表名搜索匹配的数据文件
+
+        参数:
+            data_directory: 数据文件搜索目录
+            schema_file: 表 Schema 定义文件
+
+        返回:
+            (文件路径, Sheet 名称) 元组，未找到则返回 (None, None)
+        """
+        # 提取 Sheet 名称
+        sheet_name = schema_file.sheet
+        if not sheet_name and schema_file.source:
+            sheet_name = schema_file.source.sheet
+
+        # 优先级 1：Schema 显式配置了 source 路径
+        if schema_file.source:
+            src = schema_file.source
+            if src.mode == "absolute_file":
+                return src.path, sheet_name
+
+            src_path = src.path
+            src_path_abs = os.path.normpath(os.path.join(self.project_root, src_path))
+
+            if os.path.isfile(src_path_abs):
+                return src_path_abs, sheet_name
+
+            # 处理路径中多余的项目目录前缀（如 data/users.xlsx 中的 data 部分）
+            data_dir_basename = os.path.basename(self.project_root)
+            src_path_parts = normalize_to_posix(src_path).split("/")
+            if len(src_path_parts) > 1 and src_path_parts[0] == data_dir_basename:
+                src_path_adjusted = "/".join(src_path_parts[1:])
+                adjusted_path = os.path.normpath(os.path.join(self.project_root, src_path_adjusted))
+                if os.path.isfile(adjusted_path):
+                    return adjusted_path, sheet_name
+
+            final_path = os.path.normpath(os.path.join(self.project_root, src_path))
+            return final_path, sheet_name
+
+        # 优先级 2：自动发现数据文件
+        table_name = schema_file.name or schema_file.id
+
+        # 如果指定了 Sheet 名称，说明是 Excel 文件，只搜索 Excel 扩展名
+        if sheet_name:
+            extensions = [".xlsx", ".xls"]
+        else:
+            extensions = [".xlsx", ".xls", ".csv", ".json", ".jsonl"]
+
+        # 确定搜索目录，优先使用 manifest 中配置的数据源目录
+        search_directory = data_directory
+        first_data_source = self.resolve_first_data_source()
+        if first_data_source:
+            search_directory = first_data_source
+
+        # 先在搜索目录根目录中查找
+        for ext in extensions:
+            file_path = os.path.join(search_directory, f"{table_name}{ext}")
+            if os.path.isfile(file_path):
+                return file_path, sheet_name
+
+        # 递归搜索子目录，跳过常见非数据目录
+        for root, dirs, files in os.walk(search_directory):
+            dirs[:] = [
+                d for d in dirs if not d.startswith(".") and d not in ["node_modules", "__pycache__", ".git", ".venv"]
+            ]
+
+            for ext in extensions:
+                file_name = f"{table_name}{ext}"
+                if file_name in files:
+                    file_path = os.path.join(root, file_name)
+                    return file_path, sheet_name
+
+        return None, None