Metadata-Version: 2.4
Name: precis-cli
Version: 0.1.4
Summary: Precis - 可配置数据校验工具 CLI（校验 CSV/Excel/JSON 数据质量）
Author: Precis Team
License: Apache-2.0
Project-URL: Homepage, https://github.com/AirSaiga/Precis
Project-URL: Repository, https://github.com/AirSaiga/Precis
Project-URL: Bug Tracker, https://github.com/AirSaiga/Precis/issues
Project-URL: Discussions, https://github.com/AirSaiga/Precis/discussions
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: <3.14,>=3.12
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.12.0
Requires-Dist: pandas<3.0,>=2.2.0
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: xlrd>=2.0.1
Requires-Dist: SQLAlchemy>=2.0.48
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: ruamel.yaml>=0.19.0
Requires-Dist: rich>=13.0.0
Requires-Dist: readchar>=4.2.0
Requires-Dist: cryptography>=44.0.0
Requires-Dist: simpleeval>=1.0.0
Requires-Dist: filelock>=3.12.0
Provides-Extra: api
Requires-Dist: fastapi!=0.136.3,>=0.135.0; extra == "api"
Requires-Dist: uvicorn>=0.42.0; extra == "api"
Requires-Dist: email-validator>=2.3.0; extra == "api"
Requires-Dist: uritemplate>=4.2.0; extra == "api"
Requires-Dist: python-multipart>=0.0.26; extra == "api"
Requires-Dist: cryptography>=44.0.0; extra == "api"
Provides-Extra: ai
Requires-Dist: openai>=1.6.0; extra == "ai"
Requires-Dist: aiohttp>=3.9.0; extra == "ai"
Requires-Dist: psutil>=5.9.6; extra == "ai"
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.30.0; extra == "mcp"
Provides-Extra: completion
Requires-Dist: pyreadline3>=0.1.8; sys_platform == "win32" and extra == "completion"
Provides-Extra: full
Requires-Dist: precis-cli[ai,api,completion,mcp]; extra == "full"
Provides-Extra: dev
Requires-Dist: precis-cli[ai,api,mcp]; extra == "dev"
Requires-Dist: debugpy>=1.8.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"

# Precis 后端 / Precis Backend

> **Alpha** — 核心功能已成型，接口可能调整。

FastAPI + CLI + 核心校验引擎，采用三层分离架构。

完整项目说明请见 [根目录 README.md](../README.md)。

---

## 架构

```
backend/app/
├── api/                    # API 层
│   ├── main.py             # FastAPI 应用入口（路由注册、中间件、CORS）
│   ├── dependencies.py     # 依赖注入
│   ├── middleware/          # 中间件
│   ├── models/             # 请求/响应 Pydantic 模型
│   ├── routers/            # 路由定义
│   │   ├── core/           # 核心路由（项目、工作区）
│   │   ├── project/        # V2 项目 CRUD（Schema、Constraint、Regex、Transform）
│   │   ├── validation/     # 校验执行与历史
│   │   ├── preview/        # 数据预览
│   │   └── ai/             # AI 配置生成
│   └── services/           # API 层服务
├── cli/                    # 交互式命令行（shell/ REPL、start 启动器、__main__）
├── shared/                 # 三层分离架构
│   ├── core/               # 框架级基础设施
│   │                       # 文件 I/O、配置解析（YAML）、数据加载
│   ├── domain/             # 纯业务领域逻辑（无 I/O 依赖）
│   │   ├── constraints/    # 10 种约束类型定义（not_null.py、unique.py 等，每种一个文件）
│   │   ├── transforms/     # 22 种转换类型定义（string_split.py、math_expr.py 等，每种一个文件）
│   │   ├── data_types.py   # 数据类型定义（string/integer/float/decimal/boolean/date）
│   │   ├── dataset_schema.py # Schema 模型
│   │   ├── expression_system.py # 表达式求值系统
│   │   └── schema/         # Schema 相关领域逻辑
│   └── services/           # 应用服务（编排 core 和 domain）
│       ├── validation/     # 校验引擎（两阶段流水线）
│       │   ├── executor.py # ValidationExecutor 主编排器
│       │   ├── engine.py   # 校验执行引擎
│       │   ├── data_loader.py # 数据加载
│       │   ├── loader.py   # 配置加载
│       │   ├── resolver.py # 数据源解析
│       │   ├── extractors.py # 派生列提取（regex）
│       │   ├── history.py  # 校验历史持久化
│       │   ├── dag/        # 转换 DAG 执行
│       │   ├── validators/ # 各类型校验器（每种约束一个文件）
│       │   └── types.py    # 校验类型定义
│       ├── ai/             # AI 服务
│       ├── llm/            # LLM 集成（OpenAI / Ollama）
│       ├── preview/        # 数据预览服务
│       ├── diff/           # 配置差异比较
│       └── hardware.py     # 硬件检测
└── start_server.py         # 服务器启动入口
```

### 关键约定

- `domain/` 不得导入 `core/` 或 `services/`，保持纯净
- API 路由在 `api/routers/`，请求/响应模型在 `api/models/`
- 路由注册入口：`api/main.py`
- 所有请求通过 `X-Project-Config-Path` header 标识当前项目
- 校验类接口约定"永远返回 200、结果看 body"；配置文件损坏（如清单 YAML 语法错误/空文件）返回 422 并附说明
- 打包模式下 `Origin: null` 跨域请求须携带 `X-Precis-Auth` 头（值来自 Electron 注入的 `PRECIS_API_TOKEN`，见 `api/middleware/token_auth.py`）；未配置 token 时中间件直通，`PRECIS_ALLOW_NULL_ORIGIN=1` 为旧的全局放行兼容开关

---

## 校验引擎（两阶段流水线）

```
阶段 1: 数据加载与预处理
  ├── DataSourceResolver → 解析文件路径
  ├── DataLoader → 加载 Excel/CSV/JSON
  ├── process_dataframe → 类型转换、格式检查
  ├── extractors → 派生列提取（regex）
  └── Transform DAG → 拓扑排序执行 transform 链

阶段 2: 约束校验
  └── 逐约束调用 validate()，聚合错误
        （validators/ 下每种类型一个：not_null.py, unique.py, foreign_key.py ...）
```

---

## 开发命令

```bash
# 安装
python -m venv .venv
pip install -e ".[dev]"

# 运行
python -m uvicorn app.api.main:app --reload --port 18000

# 代码检查
python -m ruff check .              # lint（不自动修复）
python -m ruff check --fix .        # lint 自动修复
python -m ruff format .             # 格式化
python -m mypy .                    # 类型检查

# 测试
python -m pytest                    # 运行全部测试

# CLI
python -B -m app.cli
```

---

## 配置文件格式（V2 YAML）

| 文件类型 | 命名 | 说明 |
|---------|------|------|
| 项目清单 | `project.precis.yaml` | 索引所有 Schema/Constraint/Regex/Transform 资源 |
| Schema | `*.schema.yaml` | 表结构定义（列、数据类型、内嵌约束） |
| Constraint | `*.constraint.yaml` | 独立约束（refs + params 分离设计） |
| Regex | `*.regex.yaml` | 正则节点（引用模式或直接模式） |
