# 配方和制品格式 v1

以 [`examples/shop/recipe.json`](../examples/shop/recipe.json) 为完整示例。列和表名必须是小写 ASCII 字母、下划线和数字，第一位不能是数字，最长 63 字符。

| 字段 | 定义 |
| --- | --- |
| `version` | 必须为 `1`。 |
| `schema` | 同一个 PostgreSQL schema；源与目标都使用这个名字。 |
| `tables` | 要读取的表。每项包含 `name`、列白名单 `columns`、按次序声明的主键 `key`，以及所有 `foreign_keys`。 |
| `foreign_keys` | `columns` 指本表列；`parent` 指配方内的父表；`references` 必须与父表主键完全一致。 |
| `roots` | `table` 和 `keys`，键采用 PostgreSQL 的规范文本表示：例如 `[["eu", "42"]]`。 |
| `follow` | `from`、`child` 和子表 `foreign_keys` 中的 `foreign_key` 下标（从零开始）。只有根和通过这些边进入的记录会继续向下扩展。 |
| `masks` | `table`、`column`、`value`，替换值为 PostgreSQL 可接受的文本或 JSON `null`。主外键列不可遮盖。 |
| `max_rows` | 每份制品最多含多少行。达到限制后如果还需要更多行，采集失败。 |

采集把白名单内的 PostgreSQL 值编码成文本，SQL `NULL` 保持为 JSON `null`。这样 64 位整数不会经 JSON 浮点数转换。主外键支持 `smallint`、`integer`、`bigint`、`text`、`varchar` 和 `uuid`，文本键需要确定性排序规则。首版拒绝分区表、继承表、RLS、生成列及 identity 列被纳入选列、指向非主键的外键和配方之外的外键。无实际关系的普通 `NULL` 可保留；复合外键任一项 `NULL`，按 `MATCH SIMPLE` 不要求父行。

目标数据库名必须匹配 `moonbranch_[a-z0-9_]+`，目标表为空并已完成迁移。用户触发器和重写规则必须禁用或不存在。跨表循环的边若要求在父行尚未存在时插入，需要可延迟的外键；其他约束仍然由 PostgreSQL 验证。常量遮盖可能与唯一约束或检查约束冲突；此时恢复失败。选列之外的值由应用迁移的默认值或空值决定。应用若会向使用 `serial` 的表继续插入，须自行把序列推进到合适位置。

制品为 `{"format":"moonbranch/v1","sha256":"…","payload":{"spec":…, "data":…}}`。摘要输入为对 `payload` 调用 `JSON.stringify` 后的 UTF-8 字节。固定同一版本的配方、数据和 PostgreSQL 类型输出时，行按主键文本元组排序并保持配方列顺序，两次捕获可以生成相同字节。不要重排 payload 的键。
