precis-cli 0.1.7__tar.gz → 0.1.8__tar.gz

{precis_cli-0.1.7/precis_cli.egg-info → precis_cli-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: precis-cli
-Version: 0.1.7
+Version: 0.1.8
 Summary: Precis - 可配置数据校验工具 CLI（校验 CSV/Excel/JSON 数据质量）
 Author: Precis Team
 License: Apache-2.0

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/api/dependencies.py

@@ -36,6 +36,7 @@
 
 # backend/app/api/dependencies.py
 import os
+from urllib.parse import quote, unquote
 
 from fastapi import Depends, Header, HTTPException
 
@@ -65,6 +66,44 @@ class ProjectStore:
         self.project_path = project_path
 
 
+def _decode_header_path(value: str) -> str:
+    """还原 HTTP header 携带的非 ASCII 路径。
+
+    两种线上契约并存，按特征识别、互不干扰：
+
+    1. GUI 契约（axios/fetch）：前端在出口处对路径做 encodeURIComponent（纯
+       ASCII 百分号转义）。浏览器 XHR/fetch 的 header 值只接受 ByteString
+       （ISO-8859-1），中文原值会被 XHR 直接拒绝；axios 1.18 的
+       toByteStringHeaderValue 还会把 latin1 之外的字符静默删除——不转义的
+       中文路径会以"删字后的错误路径"上线且无从在服务端还原。判定是否为
+       规范转义串用 round-trip 校验（quote(unquote(v)) == v），字面上含 % 的
+       合法路径通常不会被误解码（例外：字面 "%XX" 恰为合法 UTF-8 转义序列
+       的路径会被还原，随后走校验链报错而非指向任意目录）。round-trip 的
+       转义集必须与 encodeURIComponent 的不转义集对齐：JS 保留
+       `!'()*` 五字符原样上线，校验端 quote 的 safe 集须包含它们，否则含
+       括号/感叹号的中文路径（如 `D:/项目(备份)`）契约判定必败，被契约 2
+       原样放行后以百分号串走校验链 400/404。
+    2. TUI/脚本契约（reqwest FromBytes、curl 等）：UTF-8 原始字节按 obs-text
+       上线。ASGI 服务器把 header 字节按 latin-1 解码成乱码，latin-1 与字节流
+       双射，编码回字节再按 UTF-8 解码即可无损还原；非 UTF-8 字节保持原值，
+       交由后续校验链正常报错。
+    """
+    # 契约 1：规范百分号转义（GUI）。safe 集对齐 encodeURIComponent 的保留集
+    # （`!'()*`），Python quote 恒不转义字母数字与 `_.-~`，两者已一致
+    if "%" in value:
+        try:
+            decoded = unquote(value, errors="strict")
+        except UnicodeDecodeError:
+            decoded = None
+        if decoded is not None and decoded != value and quote(decoded, safe="!'()*") == value:
+            return decoded
+    # 契约 2：UTF-8 原始字节（TUI/脚本）
+    try:
+        return value.encode("latin-1").decode("utf-8")
+    except (UnicodeEncodeError, UnicodeDecodeError):
+        return value
+
+
 async def get_project_config_path(
     x_project_config_path: str = Header(..., description="项目根目录的绝对路径（须含 project.precis.yaml）"),
 ) -> str:
@@ -121,6 +160,9 @@ def _validate_project_root(raw_path: str | None) -> str:
     """
     if not raw_path:
         raise HTTPException(status_code=400, detail="X-Project-Config-Path header 不能为空。")
+    # 还原 header 编码乱码（见 _decode_header_path）：中文路径经 UTF-8 上线、
+    # latin-1 解码后 isdir 必失败，必须先还原再做后续校验
+    raw_path = _decode_header_path(raw_path)
     # 步骤1：先校验原始输入是否为绝对路径
     # 在 Windows 下，os.path.abspath 会把相对路径（如 "../project"）解析成绝对路径，
     # 导致后续 isabs 检查无法拒绝相对路径。因此必须在规范化之前先做判断。

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/api/models/full_validation.py

@@ -438,6 +438,12 @@ class FullValidationErrorItem(BaseModel):
     source_sheet: str | None = Field(
         default=None, description="配置文件内定义的 Excel Sheet 名（可选）"
     )  # schema 配置中 source.sheet 定义的 Excel 工作表名称，可选
+    error_code: str | None = Field(
+        default=None, description="稳定错误码（UPPER_SNAKE），供前端映射 i18n key 按当前语言渲染"
+    )  # 与 message 同时给出：message 为后端默认语言的兜底文案
+    error_params: dict | None = Field(
+        default=None, description="错误码对应的插值参数（JSON 标量），如 {column: 'Total'}"
+    )  # 供前端 t(key, params) 插值
 
 
 class ValidationPassedItem(BaseModel):

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/api/models/validation.py

@@ -257,6 +257,12 @@ class ValidationErrorRow(BaseModel):
     error_message: str | None = Field(
         None, description="错误信息"
     )  # 校验失败的具体错误描述，如"值不在允许列表中"，可选
+    error_code: str | None = Field(
+        None, description="稳定错误码（UPPER_SNAKE），供前端映射 i18n key 按当前语言渲染"
+    )  # 与 error_message 同时给出：message 为后端默认语言的兜底文案
+    error_params: dict | None = Field(
+        None, description="错误码对应的插值参数（JSON 标量），如 {column: 'Total', row: 1}"
+    )  # 供前端 t(key, params) 插值
 
 
 class ValidationResult(BaseModel):

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/api/routers/ai/hardware.py

@@ -117,7 +117,11 @@ def diagnose_hardware() -> HardwareDiagnoseResponse:
         import subprocess
 
         result = subprocess.run(
-            ["nvidia-smi", "--query-gpu=name,memory.total", "--format=csv,noheader"], capture_output=True, text=True
+            ["nvidia-smi", "--query-gpu=name,memory.total", "--format=csv,noheader"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",  # 中文 Windows 下 text=True 默认按 GBK 解码会乱码/抛错
         )
         if result.returncode == 0:
             for line in result.stdout.strip().split("\n"):

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/api/routers/ai/utils.py

@@ -138,12 +138,19 @@ def expand_paths(
 
     数据文件类型：.xlsx, .xls, .csv, .json, .jsonl
     """
+    # 还原 header 线上编码（GUI 契约 percent-encode / TUI 原始 UTF-8 字节，见
+    # app.api.dependencies._decode_header_path）：前端出口统一转义后，未解码的
+    # 百分号串作 base 解析相对路径会全 miss，中文项目下静默返回空列表
+    from app.api.dependencies import _decode_header_path
+
+    base_path = _decode_header_path(x_project_config_path) if x_project_config_path else None
+
     result = []
     seen = set()
 
     for raw_path in paths:
         # 1. 解析为绝对路径
-        path = _resolve_path(raw_path, x_project_config_path)
+        path = _resolve_path(raw_path, base_path)
 
         # 2. 如果是目录，递归展开
         if os.path.isdir(path):

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/api/routers/core/data_sources.py

@@ -86,7 +86,7 @@ def load_workspace_config(project_root: str) -> dict[str, Any]:
         }
 
     try:
-        with open(config_path, encoding="utf-8") as f:
+        with open(config_path, encoding="utf-8-sig") as f:
             return yaml.safe_load(f) or {}
     except Exception as e:
         raise HTTPException(

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/api/routers/core/reporting.py

@@ -223,7 +223,7 @@ def get_reporting_config(store: ProjectStore = Depends(get_project_store)) -> Re
         )
     try:
         # 读取并解析 YAML 配置文件
-        with open(config_path, encoding="utf-8") as f:
+        with open(config_path, encoding="utf-8-sig") as f:
             config_data = yaml.safe_load(f)
         return ReportingConfig(**config_data)
     except Exception as e:

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/api/routers/preview/header_row.py

@@ -106,7 +106,7 @@ def handle_header_row_changed(
 
             if os.path.exists(schema_path):
                 try:
-                    with open(schema_path, encoding="utf-8") as f:
+                    with open(schema_path, encoding="utf-8-sig") as f:
                         schema_content = yaml.safe_load(f)
 
                     if "header_row" not in schema_content:

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/api/routers/project/helpers.py

@@ -67,7 +67,7 @@ def _load_yaml_file(path: str) -> dict:
     if not os.path.isfile(path):
         return {}
     try:
-        with open(path, encoding="utf-8") as f:
+        with open(path, encoding="utf-8-sig") as f:
             return yaml.safe_load(f) or {}
     except yaml.YAMLError:
         return {}

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/api/routers/projects/open.py

@@ -36,7 +36,7 @@ def _get_project_name(project_path: str) -> str:
     """从 project.precis.yaml 中读取项目名称，失败时返回目录名。"""
     manifest_path = os.path.join(project_path, "project.precis.yaml")
     try:
-        with open(manifest_path, encoding="utf-8") as f:
+        with open(manifest_path, encoding="utf-8-sig") as f:
             manifest = yaml.safe_load(f)
         if isinstance(manifest, dict):
             project = manifest.get("project", {})

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/api/routers/projects/scan.py

@@ -69,7 +69,7 @@ def scan_projects(
 def _parse_project(project_path: str, manifest_path: str) -> ProjectInfo | None:
     """解析单个项目的 manifest 文件获取元信息。"""
     try:
-        with open(manifest_path, encoding="utf-8") as f:
+        with open(manifest_path, encoding="utf-8-sig") as f:
             manifest = yaml.safe_load(f)
     except Exception:
         return None

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/api/routers/validation/common.py

@@ -189,11 +189,14 @@ def execute_dataframe_validation(
     )
 
     # 将原始错误行列表转换为标准化的 ValidationErrorRow 对象列表
+    # error_code/error_params 透传给前端，供按当前语言渲染错误文案
     error_rows = [
         ValidationErrorRow(
             row_index=err.get("row_index", 0),
             cell_value=str(err.get("cell_value", "")),
             error_message=err.get("error_message"),
+            error_code=err.get("error_code"),
+            error_params=err.get("error_params"),
         )
         for err in result.error_rows
     ]

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/api/services/full_validation_response_builder.py

@@ -150,6 +150,9 @@ class FullValidationResponseBuilder:
                     source_path=err.get("source_path"),
                     source_file=err.get("source_file"),
                     source_sheet=err.get("source_sheet"),
+                    # i18n：稳定错误码 + 插值参数透传，message 保留兜底文案
+                    error_code=err.get("error_code"),
+                    error_params=err.get("error_params"),
                 )
             )
 

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/cli/shared_services/config_ops.py

@@ -371,7 +371,7 @@ def set_config_value_in_file(project_path: str, filename: str, key_path: str, va
     yaml_parser.preserve_quotes = True
 
     try:
-        with open(config_path, encoding="utf-8") as f:
+        with open(config_path, encoding="utf-8-sig") as f:
             data = yaml_parser.load(f)
     except RuamelYAMLError as e:
         return False, f"YAML 解析失败: {e}"
@@ -482,7 +482,7 @@ def load_config_content(project_path: str, filename: str) -> dict | str:
     if not config_path:
         return f"配置文件不存在: {filename}"
     try:
-        with open(config_path, encoding="utf-8") as f:
+        with open(config_path, encoding="utf-8-sig") as f:
             content = yaml.safe_load(f)
             if content:
                 return content if isinstance(content, dict) else str(content)

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/shared/core/io/yaml.py

@@ -162,7 +162,9 @@ def read_yaml(path: Path) -> dict[str, Any]:
     :raises FileNotFoundError: 当指定路径的文件不存在时抛出
     :raises yaml.YAMLError: 当 YAML 格式错误时抛出
     """
-    with open(path, encoding="utf-8") as f:
+    # utf-8-sig：兼容记事本等编辑器保存的"UTF-8 带 BOM"（BOM 若混入会被
+    # yaml 误认Control Character抛错）；无 BOM 时解码行为与 utf-8 完全一致
+    with open(path, encoding="utf-8-sig") as f:
         return cast(dict[str, Any], yaml.safe_load(f))
 
 

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/shared/core/project/constraint/registry.py

@@ -100,6 +100,10 @@ CONSTRAINT_TYPE_ALIASES: dict[str, str] = {
     # 日期逻辑约束别名
     "datelogic": "DateLogic",
     "date_logic": "DateLogic",
+    # 字符集约束别名
+    "charset": "Charset",
+    # 复合约束别名
+    "composite": "Composite",
 }
 
 

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/shared/core/reporter/reporters/__init__.py

@@ -27,7 +27,7 @@
 
 输入示例:
     从外部导入所需的报告器:
-    from backend.app.shared.core.reporter.reporters import (
+    from app.shared.core.reporter.reporters import (
         Reporter,           # 抽象基类，用于自定义报告器
         LocalFileReporter,  # 本地文件报告器
         EmailReporter,      # 邮件报告器

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/shared/domain/constraints/allowed_values.py

@@ -141,6 +141,8 @@ class AllowedValuesConstraint(Constraint):
             errors.append(
                 {
                     "error_type": "ConstraintConfigError",
+                    "error_code": "ALLOWED_VALUES_TABLE_NOT_FOUND",
+                    "error_params": {"table": self.table},
                     "table": self.table,
                     "column": self.column,
                     "message": f"允许值约束失败: 表 '{self.table}' 不在数据集中。",
@@ -155,6 +157,8 @@ class AllowedValuesConstraint(Constraint):
             errors.append(
                 {
                     "error_type": "ConstraintConfigError",
+                    "error_code": "ALLOWED_VALUES_COLUMN_NOT_FOUND",
+                    "error_params": {"column": self.column, "table": self.table},
                     "table": self.table,
                     "column": self.column,
                     "message": f"允许值约束失败: 列 '{self.column}' 在表 '{self.table}' 中不存在。",
@@ -194,6 +198,8 @@ class AllowedValuesConstraint(Constraint):
             row_index = int(index) if index is not None else 0
             error: dict[str, Any] = {
                 "error_type": "AllowedValuesViolation",
+                "error_code": "ALLOWED_VALUES_NOT_PERMITTED",
+                "error_params": {"value": str(value), "allowed": str(self.allowed_values)},
                 "table": self.table,
                 "row_index": row_index,
                 "column": self.column,

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/shared/domain/constraints/charset.py

@@ -149,6 +149,8 @@ class CharsetConstraint(Constraint):
             errors.append(
                 {
                     "error_type": "ConstraintConfigError",
+                    "error_code": "CHARSET_TABLE_NOT_FOUND",
+                    "error_params": {"table": self.table},
                     "table": self.table,
                     "column": self.column,
                     "message": f"字符集约束失败: 表 '{self.table}' 不在数据集中。",
@@ -163,6 +165,8 @@ class CharsetConstraint(Constraint):
             errors.append(
                 {
                     "error_type": "ConstraintConfigError",
+                    "error_code": "CHARSET_COLUMN_NOT_FOUND",
+                    "error_params": {"column": self.column, "table": self.table},
                     "table": self.table,
                     "column": self.column,
                     "message": f"字符集约束失败: 列 '{self.column}' 在表 '{self.table}' 中不存在。",
@@ -186,6 +190,11 @@ class CharsetConstraint(Constraint):
             errors.append(
                 {
                     "error_type": "ConstraintConfigError",
+                    "error_code": "CHARSET_INVALID_MODE",
+                    "error_params": {
+                        "charset_mode": self.charset_mode,
+                        "valid_modes": ", ".join(sorted(valid_modes)),
+                    },
                     "table": self.table,
                     "column": self.column,
                     "message": (
@@ -216,6 +225,12 @@ class CharsetConstraint(Constraint):
                 errors.append(
                     {
                         "error_type": "CharsetViolation",
+                        "error_code": "CHARSET_INVALID_CHARACTER",
+                        "error_params": {
+                            "value": cell_value_str,
+                            "charset_mode": self.charset_mode,
+                            "charset_name": charset_name,
+                        },
                         "table": self.table,
                         "row_index": int(index) if index is not None else 0,
                         "column": self.column,

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/shared/domain/constraints/composite.py

@@ -138,6 +138,8 @@ class CompositeConstraint(Constraint):
                 final_errors = [
                     {
                         "error_type": "CompositeConstraint",
+                        "error_code": "COMPOSITE_ANY_ALL_FAILED",
+                        "error_params": {"total": len(sub_results)},
                         "message": (
                             f"复合约束（logic=any）要求至少一个子约束通过，但全部 {len(sub_results)} 个子约束均失败"
                         ),
@@ -151,6 +153,8 @@ class CompositeConstraint(Constraint):
                 final_errors = [
                     {
                         "error_type": "CompositeConstraint",
+                        "error_code": "COMPOSITE_NONE_HAS_PASSED",
+                        "error_params": {"passed": passed_count},
                         "message": (f"复合约束（logic=none）要求全部子约束失败，但有 {passed_count} 个子约束通过"),
                         "table": self.table,
                     }

{precis_cli-0.1.7 → precis_cli-0.1.8}/app/shared/domain/constraints/conditional.py

@@ -352,6 +352,8 @@ class ConditionalConstraint(Constraint):
             errors.append(
                 {
                     "error_type": "ConstraintConfigError",
+                    "error_code": "CONDITIONAL_TABLE_NOT_FOUND",
+                    "error_params": {"table": self.table},
                     "table": self.table,
                     "column": self.then_column,
                     "message": f"条件约束失败: 表 '{self.table}' 不在数据集中。",
@@ -366,6 +368,8 @@ class ConditionalConstraint(Constraint):
             errors.append(
                 {
                     "error_type": "ConstraintConfigError",
+                    "error_code": "CONDITIONAL_COLUMN_NOT_FOUND",
+                    "error_params": {"column": self.then_column, "table": self.table},
                     "table": self.table,
                     "column": self.then_column,
                     "message": f"条件约束失败: 列 '{self.then_column}' 不在表 '{self.table}' 中。",
@@ -382,6 +386,8 @@ class ConditionalConstraint(Constraint):
                 errors.append(
                     {
                         "error_type": "ConstraintConfigError",
+                        "error_code": "CONDITIONAL_REF_COLUMN_NOT_FOUND",
+                        "error_params": {"column": ref_col, "table": self.table},
                         "table": self.table,
                         "column": ref_col,
                         "message": f"条件约束失败: 引用列 '{ref_col}' 不在表 '{self.table}' 中。",
@@ -406,6 +412,13 @@ class ConditionalConstraint(Constraint):
                         errors.append(
                             {
                                 "error_type": "ConstraintConfigError",
+                                "error_code": "CONDITIONAL_THEN_THRESHOLD_NOT_NUMERIC",
+                                "error_params": {
+                                    "operator": _then_op,
+                                    "threshold": str(_then_threshold),
+                                    "column": self.then_column,
+                                    "table": self.table,
+                                },
                                 "table": self.table,
                                 "column": self.then_column,
                                 "message": (
@@ -494,6 +507,8 @@ class ConditionalConstraint(Constraint):
                 errors.append(
                     {
                         "error_type": "ConstraintConfigError",
+                        "error_code": "CONDITIONAL_UNKNOWN_IF_LOGIC",
+                        "error_params": {"if_logic": self.if_logic},
                         "table": self.table,
                         "message": f"条件约束失败: 未知的 if_logic '{self.if_logic}'，支持的值为: and, or。",
                     }
@@ -506,6 +521,8 @@ class ConditionalConstraint(Constraint):
                 errors.append(
                     {
                         "error_type": "ConstraintConfigError",
+                        "error_code": "CONDITIONAL_IF_COLUMN_NOT_FOUND",
+                        "error_params": {"column": missing, "table": self.table},
                         "table": self.table,
                         "column": missing,
                         "message": f"条件约束失败: 列 '{missing}' 不在表 '{self.table}' 中。",
@@ -516,6 +533,8 @@ class ConditionalConstraint(Constraint):
                 errors.append(
                     {
                         "error_type": "ConstraintConfigError",
+                        "error_code": "CONDITIONAL_INVALID_IF_CONDITION",
+                        "error_params": {"detail": str(e)},
                         "table": self.table,
                         "message": f"条件约束失败: {e}",
                     }
@@ -540,6 +559,8 @@ class ConditionalConstraint(Constraint):
                 errors.append(
                     {
                         "error_type": "ConstraintConfigError",
+                        "error_code": "CONDITIONAL_IF_COLUMN_NOT_FOUND",
+                        "error_params": {"column": self.if_column, "table": self.table},
                         "table": self.table,
                         "column": self.if_column,
                         "message": f"条件约束失败: 列 '{self.if_column}' 不在表 '{self.table}' 中。",
@@ -552,6 +573,8 @@ class ConditionalConstraint(Constraint):
                 errors.append(
                     {
                         "error_type": "ConstraintConfigError",
+                        "error_code": "CONDITIONAL_IF_VALUE_MISSING",
+                        "error_params": {"if_column": self.if_column},
                         "table": self.table,
                         "column": self.if_column,
                         "message": (
@@ -580,6 +603,8 @@ class ConditionalConstraint(Constraint):
                 errors.append(
                     {
                         "error_type": "Timeout",
+                        "error_code": "CONDITIONAL_TIMEOUT",
+                        "error_params": {"processed": i, "total": len(triggered_dict)},
                         "stage": "constraint",
                         "table": self.table,
                         "message": (
@@ -619,6 +644,12 @@ class ConditionalConstraint(Constraint):
                 errors.append(
                     {
                         "error_type": "ConditionalViolation",
+                        "error_code": "CONDITIONAL_THEN_VIOLATION",
+                        "error_params": {
+                            "column": self.then_column,
+                            "value": str(value_to_check),
+                            "condition": self._condition_str,
+                        },
                         "table": self.table,
                         "row_index": row_index,
                         "value": {**if_value_payload, self.then_column: value_to_check},