Precis 后端 / Precis Backend

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

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

完整项目说明请见 根目录 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 ...）

开发命令

# 安装
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）