JSON Schema · 错误码全集（四段式）· 连接器 SDK · 14 条决策记录
schema/job.schema.json 覆盖全部字段，CI 用 scripts/validate_schema.py 校验示例；编辑器和 AI 助手都能直接读它。
| 规则 | 怎么落地 |
|---|---|
| 未知字段报错 | additionalProperties: false（打错字比报错更危险） |
| 凭证禁止明文 | dsn 只匹配 ^(env:|file:) |
| interval 必须有水位列 | if frequency=interval → required incremental_column |
| 时长/体积格式统一 | 30s / 5m / 5GB 的正则约束 |
代码在 internal/core/codes.go，测试保证：编号唯一、类别与首位数字一致、Message ≤40 个汉字、每条 1–3 步可执行动作、必带风险。
| 类别 | 例子 | 运行时行为 |
|---|---|---|
| E1xxx | E1001 源库没开变更流水 · E1005 已有实例在跑 · E1006 视图做不了实时 | 停在这里等人做；退出码 3 |
| E2xxx | E2001 目标连接被重置 · E2002 源库超时 | 5s/20s/60s 退避，≤3 次 |
| E3xxx | E3001 进度与变更流水接不上 · E3002 状态表版本太新 | 不可恢复，停 |
| E4xxx | E4001 字典外的类型（已兜底）· E4002 解码器不一致 | 我们的 bug，停并引导提 issue |
五个文件、读侧 8 个方法、写侧 5 个方法，三条硬要求：
auto / costly / blocked）。Apply(ctx, events, position) 位点与数据同事务 —— 接口上强制，想省也省不掉。建表规则 8 条（默认 utf8mb4、索引延后建、分区不复制、自增值同步后重置序列…）与验收五条（能续跑、断线不重不丢、最低版本补偿正确、不删别的实例对象、矩阵跑过）都在文档里。
每条写「选了什么 / 为什么 / 代价」。改设计前先读，避免把踩过的坑再踩一遍。
| # | 决策 | 代价 |
|---|---|---|
| 1 | 位点与数据同事务 | 目标库必须可写；MQ sink 只能至少一次 |
| 3 | 背压暂停读不暂停 ack | 源端 WAL 堆积，需要 guard 阈值 |
| 5 | 能力运行时探测 | 每个版本都要真机矩阵 |
| 7 | 不拒绝只提示 | 用户可能选到会出问题的组合 |
| 8 | job_key 指纹做身份 | 改范围＝新任务，要重新初始化 |
| 10 | 不做文档站 | 提示文案成本高，每条都要写四段 |
| 12 | verify 三级、L1 只做可加统计 | L1 漏“值互换”，要靠抽样兜底 |
| 检查 | 内容 |
|---|---|
| build | gofmt / vet / build / test（4 个包带断言：类型字典 15、状态机 17、身份 4、错误码 2 组） |
| testmatrix | 每个连接器必须交 testmatrix.yaml |
| schema | 示例配置必须通过 JSON Schema |
设计已经收口可以开 M1：只做 PG→PG 闭环