# DataTest 架构

## 设计原则

1. 需求是聚合根，文档、Metadata、案例、结果、指标和报告都绑定需求版本。
2. 必须先获取真实 Metadata，再生成和校验测试案例。
3. AI 只生成结构化草稿，确定性引擎负责安全校验、执行和断言。
4. SwiftUI、CLI 和 MCP 共用同一个核心服务，避免行为分叉。
5. 数据源、SQL 方言、指标采集器和断言均采用可替换边界。

## 组件

```text
SwiftUI ─┐
CLI ─────┼→ DataTestService → Storage
MCP ─────┘         │          → SQLiteDataSource
                   ├──────────→ DeterministicExecutor
                   └──────────→ CodexCLIAdapter
```

### Storage

`app.sqlite` 保存需求版本、ETL 任务、Metadata 快照、案例版本、运行结果、结构化失败分析、指标和 Agent 调用审计。原始文档以及报告作为 artifact 保存，数据库记录路径和哈希。

### Data source adapter

当前 `SQLiteDataSource` 将 `source.sqlite` 和 `target.sqlite` 分别附加为 `ods` 与 `dwd`。连接启用 `query_only`，Metadata 查询封装在适配器内部。

### Case validation

执行前必须同时通过：案例名称、表字段存在性、只读 SQL、断言完整性以及审核状态校验。Agent 不能向运行工具提交临时 SQL。

### AI adapter

Codex CLI 使用 JSON Schema 输出结构化结果。内部调用使用临时会话、不加载用户配置，并启用只读沙箱，避免继承 DataTest MCP 后递归调用。失败分析绑定具体运行结果、需求版本和同版本 Metadata；Agent 只提供调查结论，确定性执行器仍然独占测试状态判定。

### MCP

MCP Server 使用 STDIO JSON-RPC。只读工具带有只读标记；运行、AI 生成和报告生成属于非破坏性写操作。

## 扩展路径

后续数据源适配器至少需要实现：

- Metadata 获取
- 方言和标识符规则
- 只读会话
- SQL 执行与取消
- 查询超时
- 查询计划与性能指标
- 分区、批次及数据新鲜度指标

Hive、Impala 和 Spark 专属能力不在 SQLite 中模拟，未实现的能力必须明确返回 `UNSUPPORTED`。