|
|
@@ -0,0 +1,117 @@
|
|
|
+# 数据规则 M3A 阶段验收总结
|
|
|
+
|
|
|
+日期：2026-07-23
|
|
|
+分支：`codex/data-rule-execution-m3a-m5`
|
|
|
+实施范围：数据规则可信契约、服务端 Schema/数据集绑定、类型化表达式、SQLGlot 真实执行垂直链路。
|
|
|
+
|
|
|
+## 1. 阶段结论
|
|
|
+
|
|
|
+M3A 通过验收。平台已经具备“受限但真实可执行”的 SQL 规则能力：
|
|
|
+
|
|
|
+1. 自然语言生成的 RuleSpec 必须规范化为 V2，旧 V1 只允许读取迁移，不能作为新规则写入。
|
|
|
+2. 表达式使用平台自有闭合 AST，具备函数白名单、字段类型检查、复杂度限制和后端能力判断。
|
|
|
+3. Schema Snapshot 由服务端可信元数据目录生成并计算 Hash，发布接口不再接受客户端自报 Schema Hash。
|
|
|
+4. DataFlow 发布固定规则和 Schema 语义，但物理表、数据源和方言仍在 Data Factory 部署阶段绑定。
|
|
|
+5. PostgreSQL/MySQL SQL 由固定版本 SQLGlot 通过 AST 编译，参数值不通过字符串拼接进入 SQL。
|
|
|
+6. 绑定计划在 M3A 只保存为 `compiled`；生产仓储不存在通过调用方自报证据提升为 `published` 的接口。
|
|
|
+7. Runner 只执行 `published` 计划，并校验 RuleVersion、Schema Snapshot、DatasetBinding、编译器版本和计划 Hash。
|
|
|
+8. SQL 首期只开放经过证明的同源、精确唯一键 `upsert`；其它写入模式、整数除法、不可排序字段去重和无安全契约的质量读取均失败关闭。
|
|
|
+
|
|
|
+## 2. 已落地能力
|
|
|
+
|
|
|
+### 2.1 可信运行契约
|
|
|
+
|
|
|
+- `SchemaSnapshot`、`DatasetBinding`、`ExecutionPlanV2` 均为闭合 JSON。
|
|
|
+- 拒绝凭据、连接串、内联查询、Python/序列化对象和未知后端操作。
|
|
|
+- Schema Hash 必须与规范化字段内容一致。
|
|
|
+- PostgreSQL/MySQL 标识符按 UTF-8 字节长度提前校验。
|
|
|
+
|
|
|
+### 2.2 服务端 Schema 与物理绑定
|
|
|
+
|
|
|
+- 默认 Schema 目录复用现有 Neo4j `BusinessDomain -> DataMeta` 治理图。
|
|
|
+- 稳定引用采用 `bd:<stable-domain-key>:<revision>`，缺失、歧义或版本不匹配时失败关闭。
|
|
|
+- 物理 DatasetBinding 只保存数据源 UID、对象引用、方言、访问/写入模式和 Schema Snapshot ID，不保存凭据。
|
|
|
+
|
|
|
+### 2.3 类型化规则表达式
|
|
|
+
|
|
|
+- 支持受限字面量、字段、括号、白名单函数、比较、逻辑和有限算术。
|
|
|
+- 新建规则只接受 RuleSpec V2；旧 V1 使用独立只读迁移入口。
|
|
|
+- 非整数小数以精确十进制字面量保存，避免二进制浮点提前损失精度。
|
|
|
+- 发布前依据规则自己的 `input_schema_ref` 对服务端字段执行类型检查。
|
|
|
+- 编译器目标必须属于表达式能力交集；没有安全后端时拒绝发布。
|
|
|
+
|
|
|
+### 2.4 SQL 编译与执行
|
|
|
+
|
|
|
+- 固定依赖 `sqlglot==30.13.0`，MIT License。
|
|
|
+- 支持 PostgreSQL/MySQL 严格方言编译和闭合 AST 校验。
|
|
|
+- 编译、持久化和 Runner 三处共同验证规范 RuleVersion/Schema/Binding/Compiler Hash。
|
|
|
+- MySQL upsert 要求配置键恰好对应单列主键/唯一键，并拒绝其它唯一索引可能触发的错误合并。
|
|
|
+- 事务结果区分 `committed`、`not_committed` 和 `unknown`。
|
|
|
+- 去重补充稳定字段排序；JSON、binary 等未证明可排序类型直接拒绝。
|
|
|
+
|
|
|
+## 3. 验收证据
|
|
|
+
|
|
|
+### 3.1 数据库迁移
|
|
|
+
|
|
|
+本地 Docker PostgreSQL 从 `20260723_120` 升级至 `20260723_130` 成功。`130` 仅允许执行计划状态：
|
|
|
+
|
|
|
+- `compiled`
|
|
|
+- `published`
|
|
|
+- `revoked`
|
|
|
+
|
|
|
+`tested` 和正式发布证据状态由 M4 Task 7 实现。
|
|
|
+
|
|
|
+### 3.2 M3A 聚焦验收
|
|
|
+
|
|
|
+覆盖执行契约、SchemaResolver、表达式、RuleSpec、发布服务、SQL 编译器、Runner、真实控制面 PostgreSQL 和 PostgreSQL/MySQL 规则执行：
|
|
|
+
|
|
|
+```text
|
|
|
+148 passed in 1.41s
|
|
|
+```
|
|
|
+
|
|
|
+其中真实数据库验收包括：
|
|
|
+
|
|
|
+- PostgreSQL 规则编译、写入、重复 upsert、篡改拒绝；
|
|
|
+- MySQL 规则编译、写入、重复 upsert；
|
|
|
+- MySQL 非唯一键和额外唯一索引目标拒绝，目标表零写入；
|
|
|
+- PostgreSQL 控制面原子发布及 `compiled` 逻辑计划落库。
|
|
|
+
|
|
|
+### 3.3 全量回归
|
|
|
+
|
|
|
+```text
|
|
|
+501 passed, 26 skipped, 59 subtests passed in 4.19s
|
|
|
+```
|
|
|
+
|
|
|
+### 3.4 本地运行环境
|
|
|
+
|
|
|
+验收时健康：
|
|
|
+
|
|
|
+- backend
|
|
|
+- frontend
|
|
|
+- runner
|
|
|
+- PostgreSQL
|
|
|
+- source PostgreSQL
|
|
|
+- source MySQL
|
|
|
+- MinIO
|
|
|
+- Neo4j
|
|
|
+- n8n
|
|
|
+
|
|
|
+Kestra 仍为 `Exited (1)`，属于 M5 数据工厂投产阶段的明确待解决项，不影响 M3A 编译器/Runner 直接实库验收。
|
|
|
+
|
|
|
+## 4. 阶段边界与遗留风险
|
|
|
+
|
|
|
+- M3A 不提供生产计划发布接口；正式 `compiled -> tested -> published` 必须使用 M4 的服务器运行证据。
|
|
|
+- SQL 质量检查仍失败关闭，待 M3B 证据模型和 M4 发布门禁完成后开放。
|
|
|
+- SQL 当前只支持同源精确唯一键 upsert；跨源、多节点和 Parquet 制品由 M3B 实现。
|
|
|
+- Neo4j 业务域必须具备稳定英文键和明确 revision/version；不满足时 Schema 解析拒绝。
|
|
|
+- SQL 方言的 collation、timezone、regex、rounding 能力必须在部署绑定中由服务器证明。
|
|
|
+
|
|
|
+## 5. 下一阶段
|
|
|
+
|
|
|
+进入 M3B：
|
|
|
+
|
|
|
+1. 增加 Polars 闭合 Lazy Plan 编译与执行。
|
|
|
+2. 建立 MinIO/Parquet 摘要绑定制品。
|
|
|
+3. 完成跨 PostgreSQL/MySQL 的多节点数据交接。
|
|
|
+4. 写入规则运行、违规样本、隔离行和制品血缘证据。
|
|
|
+
|
马小龙