Data Synchronization Platform - Requirements Baseline
1. 文档目的与边界
1.1 目的
本文定义船岸数据同步平台 V1 的业务问题、能力范围、质量属性和验收口径，是 PoC、架构决策、研发拆分和验收的共同基线。
本文不是完整产品选型报告、接口定义或数据模型设计。第 8 节只记录已确认的技术与部署约束；组件版本、协议参数、服务拆分、数据库表和事务实现由选型报告、PoC、ADR 与详细设计确定，且不得反向扩大本文定义的 V1 范围。
1.2 术语
| 术语 | 定义 |
|---|---|
| 业务数据库 | 业务系统实际读写的 MySQL 数据库；同步平台不拥有业务规则，只按已发布同步规则读取变更并应用变更。 |
| 节点（Node） | 纳入平台身份、配置和状态管理的独立站点；V1 中包括船端节点和一个岸端站点。 |
| 船端 | 受弱网、断网和资源约束影响，运行本地业务数据库与同步客户端的边缘节点。 |
| 岸端 | 运行管理平面、岸端数据平面及目标业务数据库的中心站点。 |
| 管理平面（Control Plane） | 负责节点、规则、发布、审批、审计、指标查询和运维操作的能力；它不直接承载未确认的业务事件正文。“管理平面”和“控制面”在本文中同义。 |
| 数据平面（Data Plane） | 负责变更采集、事件队列、规则执行、船岸传输、目标应用、冲突处理和结果确认的能力。 |
| 同步客户端（Sync Client） | 部署在船端的数据平面运行单元，负责消费本地 CDC 事件、持久化平台状态、船岸传输和下行命令应用；数据库日志采集由 CDC 组件负责。本文不使用“Agent”“Relay”指代该组件。 |
| 岸端数据平面 | 岸端负责上行接收、目标应用、岸端 CDC 消费、冲突裁决和可靠下行的运行能力；不限定服务拆分方式。 |
| CDC（Change Data Capture） | 从业务数据库变更日志中持续提取已提交的行级新增、更新和删除的采集能力；CDC 本身不负责船岸传输、冲突裁决或目标应用。 |
| CDC 采集组件 | 实现 CDC 能力并把原始数据库变更写入 CDC 事件队列的运行组件；具体产品不属于本需求基线。 |
| CDC 原始事件 | CDC 采集组件输出的、仍带有具体产品格式和源位点的消息；它不是平台对外的标准变更事件。 |
| CDC 事件队列 | 用于持久保存数据库变更事件的独立事件流基础设施。船端队列承载离线积压，岸端队列承载岸端本地变更；具体产品和协议由技术选型确定。 |
| 同步规则（Rule） | 针对源表、目标表和方向定义的过滤、映射、转换、冲突、窗口和传输策略的版本化契约。 |
| 变更事件（Change Event） | 对一条业务记录新增、更新或删除的标准化描述。 |
| 源端 / 目标端 | 对某条同步规则而言，产生业务变更的一端是源端，接收并应用变更的一端是目标端；同一条双向规则在不同方向分别确定源端和目标端。 |
| 上行 / 下行 | 从船端到岸端称为上行，从岸端到船端称为下行；方向以传输链路为准，不等同于业务数据库的读写方向。 |
| 初始装载（Snapshot Load） | 为规则建立目标端基线而执行的一次受控数据集复制；它不是 CDC 采集组件建立日志消费基线的内部快照。 |
| 增量同步（Incremental Sync） | 初始装载起始位点之后持续产生的变更事件传输和应用过程。 |
| 数据集窗口 | 由业务时间字段定义的、目标端应收敛到的数据范围，例如最近 30 天。 |
| 业务时间 | 业务记录中表达业务发生或生效时间的字段；不得用 CDC 采集时间、网络发送时间或接收时间替代。 |
| 队列分区位点 | 某个 CDC 事件队列分区中的单调位置，用于读取顺序和回放；具体字段名称随队列产品变化。 |
| 队列消费者提交位点（Consumer Offset） | 队列消费者向底层事件队列提交的下一读取位置；它只代表消费者提交进度，不代表事件已发送、已接收或已获得终态处理结果。 |
| 源数据库位点 | CDC 采集组件在源数据库日志中的位置，用于恢复采集和诊断；它不等于队列分区位点。 |
| 平台检查点（Platform Checkpoint） | 针对一个明确处理契约的来源分区，已连续获得该契约终态结果的位置，用于恢复和受控清理。岸端本地 CDC 事件的契约终态可以是“已生成可靠下行命令”，船端下行命令另有命令处理结果和命令交付检查点；接收确认和底层队列消费位点均不能替代平台检查点。 |
| 接收确认（Receive Acknowledgement） | 表示接收方已可靠保存事件或命令并可在故障后继续处理，不表示目标业务效果已经完成。 |
| 事件处理结果（Event Result） | 对一个标准变更事件在当前处理契约上的不可再变化结果。船端上行事件由岸端返回 APPLIED、CONFLICT_RECORDED、REJECTED 或 EXPIRED_APPROVED；岸端本地 CDC 事件在可靠下行命令创建后返回 FORWARDED。FORWARDED 不表示船端已应用；CONFLICT_RECORDED 不终结对应冲突实例。 |
| 下行命令处理结果（Command Result） | 船端对岸端下行命令给出的结果：COMMAND_APPLIED、COMMAND_ALREADY_APPLIED、COMMAND_CONFLICT_REPORTED 或 COMMAND_REJECTED；临时失败不属于终态，命令结果与生成命令的源事件结果独立。 |
| 冲突 | 两个可写端在未观察到对方变更的情况下修改同一业务记录，且同步规则无法安全自动合并的情况。 |
| 冲突实例 | 岸端为一组不可安全合并的变更证据创建的唯一、可审计生命周期对象；它可以在上行事件已经得到 CONFLICT_RECORDED 后继续等待裁决。 |
| 裁决 | 岸端基于规则或人工决定冲突结果，并将可验证结果通知相关节点的过程。 |
| 业务效果 | 目标业务数据库因同步事件或命令产生的最终可观察结果；重复传输可以重复处理，但不得重复产生业务效果。 |
| 幂等 | 对同一事件或命令执行一次或多次，目标业务数据库的最终业务效果相同，且不会创建重复冲突或人工任务。 |
| 回环 / 防环 | 远端应用写入被本地 CDC 再次采集后，能够识别为已同步来源并只推进平台状态、不再次生成反向同步事件的机制。 |
| 积压（Backlog） | 已被采集或生成但尚未完成相应终态处理的事件、命令或快照工作量；必须注明统计方向、规则和状态。 |
| 有效确认吞吐 | 在允许传输时间窗内，按已获得终态处理结果的有效载荷字节数除以有效传输时间计算的吞吐，不包含重试浪费流量。 |
| ETA（Estimated Time of Arrival） | 基于剩余工作量、有效确认吞吐、限速和未来可用时间窗估算的完成时间；样本不足或净排空速率不为正时必须显示为区间或不可可靠预测。 |
| 终态 | 不需要继续等待同一处理步骤才能改变的结果状态；临时网络错误、租约超时和待裁决均不是事件处理终态。 |
| 规则版本 | 同步规则的一份不可变配置快照；事件和命令必须记录产生或处理时使用的规则版本。 |
| 生效版本 | 节点当前实际执行的、已通过本地校验并原子切换成功的规则版本；候选、已批准但未分发版本不属于生效版本。 |
| 过期不再投递 | 对单向历史积压执行的、经审批的终态处置；表示平台明确不再把该积压发送到目标端，不表示目标端已应用。 |
| 可靠下行命令 | 岸端为船端生成并持久保存、可重试、可去重且带前置版本条件的变更或裁决指令。 |
| 业务消息基础设施 | 已承载其他业务消息流的消息代理、队列、存储和运维资源的统称；平台不得默认与其共享关键资源。 |
| PoC（Proof of Concept） | 为验证技术可行性、容量、兼容性或恢复语义而执行的有限范围实验；PoC 结论未固化前不构成生产参数。 |
| ADR（Architecture Decision Record） | 记录一个架构决策、上下文、备选方案、结论和影响的版本化文档。 |
| OCI 镜像 | 遵循 Open Container Initiative 格式的容器镜像；镜像体积目标只适用于同步客户端，不自动代表完整船端离线交付包体积。 |
| 最终一致性 | 在持续重试、规则不变且资源最终可用的条件下，源端和目标端最终收敛到规则允许的同一结果；不保证任意时刻相同。 |
| 至少一次传输 | 一个事件或命令可能因重试被传输多次，但接收方必须通过幂等键消除重复业务效果。 |
| 版本基线 | 变更产生时记录的目标记录版本；目标应用只有在当前版本仍等于该基线时才可直接写入，否则形成冲突证据。 |
| 终态处理 | 将事件或命令从可重试处理中转为一个不可再等待同一处理步骤的结果；冲突裁决本身仍可在事件终态之后继续。 |
| 行过滤 | 基于源表当前记录字段判断一条记录是否属于规则数据集的条件；不允许调用外部服务或执行任意脚本。 |
| 字段映射 | 将源表字段按规则映射到目标表字段的关系；未声明的字段不得隐式推断。 |
| 确定性转换 | 相同输入、规则版本和上下文始终产生相同输出，且不访问外部状态的值转换。 |
| 队列配额 | 对全部待处理数据或单条规则设置的数量、字节数或磁盘使用上限；配额触发不等于删除数据。 |
| 传输时间窗 | 按节点本地时区定义允许网络传输的时间段；采集和本地持久化不因窗口关闭而停止。 |
| 规则优先级 | 积压竞争带宽时的调度权重；不改变同一规则内的源端顺序，也不改变业务裁决结果。 |
本基线中使用的常见缩写和度量：MySQL 8.0 指 V1 业务数据库版本范围；CDC 指变更数据捕获；API 指应用程序接口；TLS 指传输层安全；OCI 指开放容器规范镜像格式；PoC 和 ADR 的含义见上表；P95 指观测样本中 95% 的请求或事件不超过的延迟；KiB/s 指每秒 1024 字节；GiB 指 1024^3 字节。未在本基线定义的产品名、协议名、字段名和状态码不得被当作需求术语使用。
1.3 目标问题
船端与岸端之间存在高延迟、低带宽、频繁中断，且可能连续数月离线。平台需要让业务系统离线期间继续本地写入，并在网络恢复后依据可配置规则补传、应用、裁决和追踪变更。
V1 的目标是可靠解决船端与岸端之间关系型业务数据的最终一致同步。平台不是数据库原生复制、通用 ETL、消息队列、数据湖或跨组织数据交换产品。
2. 产品定位
平台由数据平面和管理平面组成：
- 数据平面负责变更采集、持久化、双向传输、远端应用和冲突处置。
- 管理平面负责节点、规则、配置版本、状态、告警、审计和人工裁决。
平台提供按表配置的最终一致同步能力，不提供跨船岸数据库分布式事务、严格串行化或业务领域状态机的正确性保证。
3. V1 范围
3.1 V1 必须交付
| 编号 | 能力 | 范围与验收口径 |
|---|---|---|
| FR-001 | 节点接入 | 支持一个岸端和多个船端注册、身份认证、心跳、版本及同步客户端状态上报。 |
| FR-002 | 业务数据库 | 支持 MySQL 8.0 业务数据库的行级变更采集与应用；PostgreSQL 业务数据库仅完成可行性验证，不作为 V1 上线承诺。岸端 PostgreSQL 平台状态库不属于本条业务数据库支持范围。 |
| FR-003 | 同步方向 | 每条规则可配置船到岸、岸到船或双向；船端和岸端本地业务写入均须进入对应方向的数据平面，同一记录在同一方向只能由一条生效规则处理。 |
| FR-004 | 同步对象 | 支持具有稳定主键的业务表的 INSERT、UPDATE 和 DELETE。 |
| FR-005 | 初始装载 | 支持受控快照装载及其后的增量衔接；过程可暂停、恢复、重试并显示初始化状态。 |
| FR-006 | 弱网恢复 | 支持本地持久化、确认、指数退避重试、检查点恢复和断网后自动补传。 |
| FR-007 | 规则 | 支持表级方向、列选择、单表行过滤、字段一对一映射及预定义的简单值转换。 |
| FR-008 | 双向防环 | 已应用的远端变更不得被当作新的本地变更再次反向传输。 |
| FR-009 | 冲突裁决 | 支持岸端优先、最后写入优先和人工处理；岸端是裁决结果的唯一权威来源。 |
| FR-010 | 管理与观测 | 管理端可查看节点、规则版本、接收确认、事件处理结果、下行命令处理结果、平台检查点、队列消费位点、延迟、积压、失败、冲突和审计。 |
| FR-011 | 配置发布 | 规则版本化发布；节点校验后原子切换，支持回退至上一生效版本。 |
| FR-012 | 带宽治理 | 支持节点级上下行独立限速、规则优先级、传输时间窗与队列配额，并支持版本化发布与回退。 |
| FR-013 | 窗口化同步与积压预测 | 支持按规则定义业务时间窗口、可同步数据集和历史积压处置策略；管理端可统计待同步量并预测完成时间。 |
| FR-014 | 处理结果与恢复 | 对每个上行事件提供可查询的终态事件处理结果，对每个下行命令提供可查询的处理结果；岸端或船端重启后，已接收但未终态的事件或命令能够恢复处理且不得重复产生业务效果。 |
| FR-015 | 轻量容器化部署 | 船端同步客户端以精简 OCI 镜像和离线交付包为默认交付物，支持离线导入、启动、覆盖升级、失败回退和卸载；岸端同时支持 Docker Compose 与 Kubernetes 部署。 |
| FR-016 | CDC 队列隔离 | 船端和岸端均应使用独立的 CDC 采集与事件队列，承载平台变更事件和离线积压；不得默认占用既有业务消息基础设施。任何复用必须完成容量、故障域、性能和运维影响评估并经审批。 |
3.2 明确不在 V1
- PostgreSQL、Oracle、SQL Server、MariaDB、MongoDB、Redis、ClickHouse 等生产级支持。
- DDL 同步，包括建表、删表、列变更、索引、触发器、函数、存储过程和视图。
- 多表 Join、聚合、任意 SQL、脚本执行、复杂数据清洗或通用 ETL。
- 船对船、边缘节点网状拓扑、跨数据中心多活和任意多级级联。
- 自动在线升级、灰度发布、远程执行任意命令和数据库运维。
- 自定义代码插件、用户自定义冲突脚本、CRDT 或版本向量。
- 数据仓库、数据血缘、主数据管理、数据质量治理和消息订阅平台。
3.3 V1 业务前提
接入表必须同时满足以下条件；否则不得配置为 V1 同步规则：
- 有不可变、非空且全局唯一的主键；复合主键须在 PoC 中验证。
- 删除可由变更采集准确获得，或业务采用已确认的软删除约定。
- 双向表具有业务确认的冲突策略；涉及状态机、库存、余额或累计值的表默认不允许双向同步。
- 行过滤仅引用源表当前行字段，且过滤字段变更时的目标端语义已经明确。
- 同一规则的源端与目标端表结构兼容；字段映射不能隐式掩盖类型截断、精度丢失或语义变化。
- 源库变更日志保留期覆盖 CDC 组件停止采集的最长恢复时间；船岸离线积压由 CDC 事件队列承担。同步账户采用最小必要权限。
- 使用数据集窗口的规则指定业务语义明确、可索引且两端一致的业务时间字段；不得以事件采集时间替代业务时间。
- 船端必须为独立 CDC 事件队列提供磁盘、访问控制、监控和备份/恢复能力，并与既有业务消息基础设施隔离资源配额、数据目录和故障处置。平台不得通过共享消息代理、共享磁盘水位或保留策略影响既有业务流量。
4. 核心行为
4.1 一致性、确认与检查点
平台提供最终一致性。数据平面采用“至少一次传输、目标端幂等应用”的语义：网络重试可产生重复投递，但同一变更不得重复产生业务效果。
上行处理分为“接收确认”和“终态事件处理结果”两个层次。接收确认表示岸端已可靠保存该变更以便恢复处理，不表示业务数据已经同步完成。船端来源事件只有收到 APPLIED、CONFLICT_RECORDED、REJECTED 或 EXPIRED_APPROVED 后，船端才能连续推进该上行契约的平台检查点和清理可清理的本地积压；岸端来源事件在返回 FORWARDED 后推进岸端生成下行命令这一契约的检查点。进入冲突后，冲突证据由岸端独立持久化并继续其裁决生命周期。
下行命令由船端返回独立的命令处理结果。船端发现前置版本不一致时只报告冲突证据，不自行裁决；岸端可靠记录证据后才可把相应下行处理纳入连续平台检查点。
任何未获得终态处理结果的事件或命令都必须保留在可恢复存储中。平台检查点与队列消费位点必须分别记录。管理端必须区分“待发送”“已接收待处理”“已生成下行命令”“已应用”“已记录冲突”“冲突待裁决”“已拒绝”和“审批后不再投递”；只有 APPLIED、COMMAND_APPLIED 和 COMMAND_ALREADY_APPLIED 可表述为对应目标端业务应用成功。
4.2 变更事件最小信息
实现可调整序列化格式，但变更事件至少应表达以下信息：
| 信息 | 用途 |
|---|---|
| 事件标识 | 全局唯一，用于去重与审计。 |
| 原始节点标识 | 标识业务写入来源，用于防环和追踪。 |
| 规则标识与版本 | 标识处理该变更的同步契约。 |
| 源端顺序或位点 | 支持顺序处理、检查点恢复和诊断。 |
| 表与主键 | 定位业务记录。 |
| 操作类型 | 标识新增、更新或删除。 |
| 变更前后值 | 满足规则处理、应用、过滤和审计需要。 |
| 变更基线版本 | 用于判断变更是否基于当前记录状态产生。 |
| 业务发生时间 | 用于业务诊断和已明确允许的冲突策略；不以网络到达时间替代。 |
| 追踪标识 | 串联一次同步链路的诊断信息。 |
数据库 CDC 工具的原始消息格式不得成为管理 API 或规则 API 的对外契约。平台必须在 CDC 采集组件与同步客户端之间提供版本化适配边界；标准事件、规则和管理 API 必须与具体 CDC 产品和消息格式解耦。V1 的数据库采集范围为 MySQL 8.0，具体采集产品由技术选型报告确定。
4.3 快照与增量衔接
建立规则时必须记录可验证的起始位置。规则初始化快照完成后，只处理该位置之后的增量变更；实现必须避免快照与增量之间形成数据缺口或无界重复。采集组件建立自身 CDC 基线的过程，与平台规则初始化快照必须分别记录状态和位点。
快照期间业务写入可继续进行，但规则状态必须显示为“初始化中”，不得声明为已同步完成。
4.4 过滤、映射与转换
处理顺序固定为：行过滤、列选择与字段映射、值转换。删除处理必须使用足够的历史信息，使记录不会因源端当前行已不存在而遗留在目标端。
V1 转换仅限无外部依赖、无副作用、确定性的单字段转换，例如时区规范化、枚举映射和格式规范化。转换失败必须进入可查询失败状态，不能静默丢弃或以空值替换。
4.5 双向同步与冲突裁决
双向同步仅对明确标记为可双向的表开放。船端和岸端 CDC 组件分别采集本地业务写入并写入各自的 CDC 事件队列。船端同步客户端负责消费船端队列、持久化平台状态、船岸传输、远端变更的幂等应用和状态上报；岸端数据平面负责消费岸端队列、认证、事件处理结果、冲突检测、裁决和可靠下行。船端不得在离线或重试时自行判定冲突胜负。
每个冲突必须由岸端创建唯一的冲突实例，并保存双方变更证据、适用规则版本、状态、裁决结果和审计信息。重复投递、重试或服务重启不得创建重复冲突实例或重复人工任务。
冲突裁决的业务状态如下：
| 状态 | 含义 | 下一状态 |
|---|---|---|
已检测 | 双方变更证据已保存，尚未开始裁决。 | 自动裁决中、等待人工、已取消 |
自动裁决中 | 正在依据已配置策略计算结果。 | 已裁决、等待人工 |
等待人工 | 自动策略未配置、不可判定或规则要求人工处理。 | 已裁决、已取消 |
已裁决 | 裁决结果及其依据已固化，等待通知相关节点。 | 已通知 |
已通知 | 裁决结果已进入可靠下行处理，等待相关节点确认。 | 已确认、已过期 |
已确认 | 相关节点已幂等处理裁决，冲突终态。 | 无 |
已过期 | 裁决处理前发现任一端产生未纳入证据的新写入，旧裁决不再安全。 | 以新证据创建新的冲突实例 |
已取消 | 经授权取消且未对业务记录产生裁决效果，冲突终态。 | 无 |
岸端优先仅在岸端当前记录仍属于冲突证据集合时可自动执行。最后写入优先基于规则指定的业务更新时间字段；时间相同必须采用确定性排序。无法验证策略前提、字段缺失或记录发生后续修改时，必须进入等待人工或已过期，不能猜测结果。
裁决结果必须可去重、可验证且仅在不覆盖裁决后新产生本地写入的条件下应用。若节点发现裁决已过期，必须报告岸端并由岸端基于新证据处理，不得强制覆盖。
4.6 受限带宽治理
船端同步客户端必须按节点分别控制上行和下行速率。限流只能延后传输，不得丢弃已持久化且未获得终态事件处理结果的变更。
每条规则必须配置优先级。带宽受限或积压时优先传输高优先级规则，并保证低优先级规则在允许时间窗内获得可恢复的传输机会。优先级不得改变同一规则内的源端顺序。
规则可配置传输时间窗。窗口外可暂停低优先级网络传输，但仍持续采集和本地持久化；高优先级规则是否绕过窗口必须显式配置。时间窗使用节点本地时区，时间校准异常必须产生告警。
本地队列必须具有总配额和每规则配额。达到预警和硬阈值时必须分别告警和执行预定义降级动作。V1 的降级动作仅可暂停低优先级传输或阻止新增规则发布，不得自动删除未获得终态事件处理结果的变更；危及节点稳定性时必须进入显式受阻状态并通知运维。
同一主键的多个未发送更新可在不改变最终业务效果、删除语义和审计关联的前提下合并。INSERT 后在发送前发生 DELETE 可抵消。事件合并不适用于双向冲突、人工处理或要求逐条审计的规则。
二进制附件、图片、文件和超出规则阈值的大字段不随 V1 行级同步默认传输；业务表仅同步元数据或引用。对象传输能力须作为独立需求立项。
4.7 数据集窗口与积压预测
当离线时间和积压量超过可接受恢复窗口时，规则可定义滚动数据集窗口，例如仅同步业务发生时间最近 15 天或 30 天的数据。窗口长度、时区、边界包含方式和允许未来时间偏差均属于规则版本。
数据集窗口定义的是目标端应收敛到的业务记录范围，不是无条件丢弃旧变更。启用窗口、修改窗口或离线恢复后，目标端必须按规则收敛到窗口内应存在的记录。记录自然滑出窗口后是否在目标端删除必须显式配置，默认不删除。双向规则使用数据集窗口须通过 PoC 验证后才能发布。
未获得终态事件处理结果的历史积压，仅在单向规则具有已审批的“过期不再投递”策略时才可标记为不再投递。该策略必须明确业务时间字段、过期阈值、目标端处理方式和业务责任人。处置前必须统计事件数与字节数，生成告警和审计，并与正常待传及已应用数据分开显示；不得静默删除或标记为已同步。
管理端必须按节点、方向、规则和优先级展示待处理事件数、待传原始字节数、压缩后估算字节数、最早与最新业务时间、窗口外不再投递的数据量、队列占用、有效确认吞吐和失败原因，并标注采样时间与估算口径。
ETA 应基于待传估算字节数、可用时间窗、配置限速和近期有效确认吞吐计算。链路中断、吞吐样本不足或积压增长时，必须显示预测区间或“不可可靠预测”，不能输出虚假的确定完成时间。
5. 管理平面边界
5.1 平台负责
- 节点身份、状态、同步客户端版本和最后心跳。
- 同步规则的创建、校验、审批状态、版本、发布、回退和生效反馈。
- 同步进度、事件处理结果、积压、失败、冲突和审计记录的查询。
- 人工冲突裁决的授权、记录和结果追踪。
- 告警所需指标与事件输出。
5.2 平台不负责
- 替代业务系统的用户、组织、权限或领域权限模型。
- 修复不兼容表结构、修复业务数据质量或自动裁决业务领域语义。
- 控制面短时不可用不得停止已生效规则的数据平面运行；同步客户端必须按本地最后生效规则继续运行。控制面恢复后再补传状态和处理结果。
- 保存敏感业务明文用于监控展示；管理端默认展示元数据、脱敏样例和经授权的审计证据。
6. 安全与合规
| 编号 | 要求 |
|---|---|
| NFR-001 | 节点与岸端间的传输必须使用 TLS；证书或令牌的签发、轮换和吊销方式须在设计阶段确定。 |
| NFR-002 | 节点身份与人员身份分离；节点仅可获取自身规则、上报自身状态和传输被授权数据。 |
| NFR-003 | 规则变更、发布、回退、人工裁决和高权限查询必须产生不可篡改的审计事件。 |
| NFR-004 | 敏感列默认不进入同步；例外须经规则审批明确列出。日志、指标、失败记录和审计证据不得记录敏感明文。 |
| NFR-005 | 运行账户采用最小权限，不得使用数据库管理员账户进行日常采集或写入。 |
7. 性能、可靠性与容量目标
以下为 V1 验收目标，不是对任意数据模型和网络环境的无条件承诺。测试数据模型、网络条件、硬件规格和计算口径必须在 PoC 前冻结。
| 编号 | 指标 | V1 目标 |
|---|---|---|
| NFR-101 | 节点规模 | 支持至少 1,000 个船端节点接入一个岸端管理平面。 |
| NFR-102 | 日常延迟 | 网络可用、无积压且约定负载下，P95 端到端同步延迟不超过 10 秒。 |
| NFR-103 | 离线恢复 | 船岸链路连续离线 7 天后，在未终态数据仍由 CDC 事件队列或可靠下行存储保留的前提下可自动恢复；无数据丢失、无重复业务效果。更长离线期按数据集窗口与积压处置策略执行。 |
| NFR-104 | 初始装载 | 单表 100 万行初始装载可恢复、可观测；实际完成时间按 PoC 中冻结的数据大小和链路带宽验收。 |
| NFR-105 | 传输效率 | 支持持续增量的批量传输和可配置压缩；批次大小、压缩算法与阈值由 PoC 决定。 |
| NFR-106 | 管理平面隔离 | 管理 API 或控制台短时不可用不影响已生效规则的采集、排队和数据传输；共享平台数据库或岸端数据平面不可用时允许传输暂停，但必须可恢复且不得误报接收成功。 |
| NFR-107 | 可观测性 | 每条规则可查询事件处理结果、延迟、最后成功应用时间、检查点、积压、重试次数、失败原因和配置版本。 |
| NFR-108 | 带宽可控 | 在配置的上下行速率上限下，任意连续 5 分钟窗口的平均传输速率不得超过对应上限；允许突发量由 PoC 固化。 |
| NFR-109 | 积压保护 | 队列达到预警阈值时 1 分钟内产生告警；达到硬阈值时执行规则定义的降级动作，未获终态事件处理结果的变更不得自动删除。 |
| NFR-110 | 积压可见性 | 队列状态稳定后 5 分钟内，管理端展示的待处理事件数与字节数相对 CDC 事件队列及同步客户端状态索引计算值的误差不超过 5%，并标注统计时间与估算口径。 |
| NFR-111 | ETA 透明性 | ETA 必须展示有效吞吐、观测窗口、待传估算字节数和可用传输时间窗；样本不足或积压增长时必须降级为区间或不可预测。 |
| NFR-112 | 幂等与恢复 | 同一变更、冲突或裁决结果重复传输，以及任一节点重启后恢复处理，均不得产生重复业务写入、重复冲突实例或重复人工任务。 |
| NFR-113 | 船端增量交付体积 | 同步客户端 OCI 镜像应保持精简，目标压缩体积不超过 50 MiB。完整船端离线交付包体积由 PoC 测量并冻结上限；采集组件、事件队列、同步客户端、Compose、脚本和校验清单须分别列账，不得隐藏新增交付成本。 |
| NFR-114 | 船端运行依赖 | 同步客户端不得引入与其职责无关的重量级运行时；CDC 采集组件和事件队列作为独立运行单元交付，具体技术由选型报告确定。 |
| NFR-115 | 船端增量资源 | 同步客户端在日常负载下内存目标不超过 128 MiB、平均 CPU 不超过单核 10%；CDC 采集组件和事件队列的 CPU、内存、磁盘和 I/O 增量单独计量，并验证不得影响既有业务消息基础设施的服务目标。 |
| NFR-116 | 岸端并发规模 | 支持 1,000 个已注册船端同时上传、拉取事件处理结果或发送心跳；在冻结的事件大小与负载模型下，岸端可在 Kubernetes 中水平扩展且 P95 请求延迟满足 PoC 基线。 |
| NFR-117 | Kubernetes 就绪 | 岸端提供版本化 Kubernetes manifests 或 Helm Chart，支持健康检查、滚动升级、资源限制、配置/密钥注入、持久卷声明和多副本部署；V1 不强制依赖特定云厂商服务。 |
吞吐量不以脱离环境的单一 TPS 承诺。PoC 必须同时报告在线节点数、并发传输节点数、每秒变更数、平均事件大小、批次大小、端到端延迟、请求延迟、资源使用率、网络占用、限流等待时间和积压恢复预测时间。
8. 技术与部署约束
- MySQL CDC 必须使用经过验证的采集组件，支持行级新增、更新、删除、快照、事务边界和位点恢复；不得为追求单一语言重复开发数据库日志解析、快照和位点恢复。原始采集消息须在平台边界内转换为标准事件。
- 船端与岸端 CDC 事件队列必须独立于既有业务消息基础设施，具备持久化、分区顺序、受控保留、回放、容量监控和故障恢复能力；具体产品、协议和部署方式由技术选型报告及 PoC 固化，改变隔离边界必须通过专项 ADR 和影响评估。
- 船端弱网同步客户端和岸端服务优先采用 Go，以获得较小增量镜像和适合高并发 I/O 的服务端实现；若改用其他语言，必须通过 ADR 证明交付体积、资源和并发能力。
- 所有运行单元优先容器化。船端使用精简 OCI 镜像和 Docker Compose（或兼容 Compose 的运行时）部署；岸端提供可重复的 Docker Compose 环境，并以 Kubernetes 作为生产部署和未来扩展的优先方向。
- 容器镜像必须采用多阶段构建、非 root 用户、只读根文件系统（确有写入需求的目录使用挂载卷）和固定镜像摘要；不得将证书、密钥或运行数据打入镜像。
- 船端必须具备本地持久化能力，不能依赖持续可用的岸端消息系统。
- 限流必须在数据平面生效，不能仅依赖容器、主机或网络设备的静态限速。
- 捕获、标准化、路由、传输、应用、规则管理和观测必须模块化；替换某个数据库采集组件不得改变平台事件契约。
- 除本节已冻结的技术约束外，组件版本、传输协议、压缩参数、服务拆分和管理后台技术栈由选型报告、PoC 与 ADR 固化。
- Docker Compose 保留为开发、测试和单机部署基线；Kubernetes 是岸端 V1 生产部署的交付目标，两者使用同一组镜像和配置语义。
9. 验收场景
| 场景 | 操作 | 通过条件 |
|---|---|---|
| AC-001 单向增量 | 船端对受控表执行新增、更新、删除。 | 岸端按规则应用；检查点连续推进；每个变更仅产生一次业务效果。 |
| AC-002 断网恢复 | 断开网络 7 天等效时长，期间持续写入后恢复网络。 | 未获终态事件处理结果的变更自动补传；无丢失、无重复业务效果；可查询重试与恢复过程。 |
| AC-003 快照衔接 | 快照执行期间持续向源表写入。 | 目标端最终包含快照前后应同步数据；无缺口；初始化状态和起始位置可查询。 |
| AC-004 防环 | 对双向表从船端产生一条变更。 | 岸端应用后不被反向规则再次作为新的业务变更传回。 |
| AC-005 自动冲突 | 船岸离线期间修改同一主键记录。 | 岸端按选定策略得到确定结果，并保存双方证据和裁决审计。 |
| AC-006 人工冲突 | 配置人工处理规则并制造冲突。 | 业务记录不被静默覆盖；待处理项可查询、裁决并形成审计。 |
| AC-007 裁决过期 | 裁决通知前，船端再次修改同一记录。 | 旧裁决不覆盖新写入，状态标记为已过期，并以新证据创建冲突实例。 |
| AC-008 处理结果恢复 | 重复发送同一上行事件或下行命令，并在岸端或船端处理期间重启。 | 可查询唯一终态事件处理结果和下行命令处理结果；恢复后不重复写业务数据，不重复创建冲突或人工任务。 |
| AC-009 配置回退 | 发布合法新规则后回退。 | 节点报告生效版本；回退后新变更按旧规则处理，历史变更可追踪原规则版本。 |
| AC-010 敏感数据 | 配置敏感列排除并触发失败重试。 | 目标表、日志、指标、失败记录和审计证据均不包含该列明文。 |
| AC-011 带宽限速与优先级 | 在 128 KiB/s 上行链路下持续产生高、低优先级变更。 | 任意连续 5 分钟平均速率不超过上限；高优先级在约定时延内送达，低优先级可见、可恢复且不丢失。 |
| AC-012 时间窗与积压保护 | 为低优先级规则配置时间窗和队列配额，持续写入直至超过阈值。 | 窗口外不发送低优先级变更；预警和硬阈值告警可查询；不自动删除未获终态事件处理结果的变更。 |
| AC-013 事件合并 | 对同一主键在发送前连续更新，并制造 INSERT 后 DELETE。 | 允许的更新被合并且目标最终状态正确；抵消不传输，原始关联可审计。 |
| AC-014 滚动窗口同步 | 配置单向规则仅同步最近 30 天数据，源端同时存在窗口内外记录并持续写入。 | 目标端收敛至规则定义的数据集；窗口外数据未被计为已同步；窗口边界和规则版本可查询。 |
| AC-015 过期积压处置 | 产生超过窗口的未处理单向积压，并执行已审批的过期不再投递策略。 | 处置前统计数量和字节数，产生告警和审计；该数据单独显示，未标记为已同步。 |
| AC-016 积压与 ETA | 在 128 KiB/s 限速和已知传输时间窗下形成至少 10 GiB 积压。 | 管理端展示待传字节、有效吞吐和 ETA；暂停链路或让积压增长时 ETA 降级为预测区间或不可可靠预测。 |
| AC-017 船端离线部署与回退 | 在无外网和无法连接岸端的环境导入镜像包，执行首次启动、覆盖升级、模拟升级失败和卸载。 | 离线包完整可校验；镜像与配置/队列分离；失败后恢复上一镜像且既有队列、检查点和证书不丢失。 |
| AC-018 千节点并发 | 1,000 个模拟船端同时上传批次、拉取结果并发送心跳，包含断线后集中重连。 | 无数据丢失或重复业务效果；服务可水平扩展；错误率、P95 延迟、CPU、内存和数据库压力符合冻结的 PoC 基线。 |
| AC-019 Kubernetes 滚动升级 | 岸端以不少于 3 个副本运行，在持续同步流量下执行滚动升级、单 Pod 终止和扩缩容。 | 服务持续可用；未确认请求可安全重试；无重复业务效果；健康检查、资源限制和扩缩容状态可观测。 |
| AC-020 CDC 队列与离线积压 | 通过选定的 CDC 采集组件获取 MySQL 快照及增量，断开船岸链路并在独立事件队列累积至少 10 GiB 数据后恢复，同时向既有业务消息基础设施持续施加基线负载。 | CDC 无缺口；同步客户端从平台检查点恢复；底层队列位点、平台检查点、事件处理结果和岸端业务数据可对账；既有业务消息基础设施的服务目标不因测试退化。 |
10. PoC 决策门
PoC 不仅验证“能同步”，还必须回答以下问题；未通过时不得进入生产研发：
| 编号 | 待验证项 | 决策产物 |
|---|---|---|
| POC-001 | 选定的 CDC 采集组合能否捕获 MySQL 删除、事务边界、位点与快照衔接。 | 捕获与恢复测试报告。 |
| POC-002 | 船端目标硬件能否保存 7 天离线积压并可控恢复。 | 容量模型、资源报告和保留策略。 |
| POC-003 | HTTPS 批量传输能否满足至少一次传输、终态事件处理结果和幂等应用。 | 故障注入测试与事件去重设计。 |
| POC-004 | 双向防环、自动裁决、人工裁决、裁决过期和重试能否稳定复现并审计。 | 冲突矩阵和状态机演示记录。 |
| POC-005 | PostgreSQL 是否具备与 MySQL 同等的关键能力。 | 独立可行性结论；未通过则延后支持。 |
| POC-006 | 选定技术组合是否满足运营维护成本和团队技能约束。 | ADR：组件、边界、替换策略和不采用理由。 |
| POC-007 | 限流、优先级、时间窗和队列配额在卫星等效链路下是否可预测协同工作。 | 链路压测报告：实际速率、优先级时延、积压曲线、恢复时间和降级行为。 |
| POC-008 | 数据集窗口在快照、增量、窗口滑动和积压过期后能否保持目标端语义正确。 | 覆盖窗口边界、删除语义和恢复过程的对账报告与 ADR。 |
| POC-009 | 大积压的字节统计和 ETA 在限速、时窗、波动网络下是否足够准确且不会误导运维。 | 至少 10 GiB 积压压测报告：估算误差、吞吐样本、ETA 预测与实际恢复时间对比。 |
| POC-010 | Go 船端同步客户端在目标操作系统、容器运行时和硬件上能否满足镜像体积、依赖、资源、离线升级和回退要求。 | 镜像与离线包清单、体积与资源报告，以及导入/启动/升级/回退/卸载测试记录。 |
| POC-011 | 岸端在 1,000 个船端并发传输和集中重连时能否保持稳定处理与水平扩展。 | 容量模型、压测报告、扩容曲线、瓶颈分析和生产容量建议。 |
| POC-012 | 岸端 Kubernetes 部署在滚动升级、Pod 驱逐、节点故障和水平扩缩容时能否保持同步语义。 | Kubernetes 故障与升级演练报告、容量指标和恢复时间。 |
| POC-013 | 选定的 CDC 采集组件与独立事件队列能否满足协议兼容性、数月保留、100 GiB 级积压、磁盘水位、恢复吞吐和既有业务消息基础设施隔离要求。 | 兼容矩阵、资源隔离方案、分区/保留策略、容量模型、故障恢复、积压回放和既有业务消息基础设施对照压测报告。 |
11. 待业务确认的问题
- 首批同步表清单、每表方向、主键、数据分级、日均变更量、最大离线时长和最大积压量。
- 每张双向表的业务更新时间字段、时钟来源、冲突策略、自动裁决授权边界和人工裁决 SLA。
- 允许的最大数据陈旧度、恢复窗口和变更日志保留窗口。
- 行过滤因归属字段变更发生迁移时，目标端删除和新归属端新增的业务语义。
- 船端硬件、磁盘配额、网络带宽、同步客户端升级窗口和安全证书生命周期。
- 敏感数据分类、脱敏要求、审计保留期限和告警接收责任。
- 各节点上行/下行带宽上限、可用传输时段、各优先级规则最大可接受延迟和积压处置责任。
- 可合并变更的业务表清单及逐条审计要求；附件和大字段阈值及独立传输需求。
- 需要按 15 天、30 天或其他窗口同步的表清单、业务时间字段、时区和窗口外记录的保留/删除语义。
- 允许过期不再投递的单向数据类别、审批人、审计保留期，以及历史数据的离线归档或人工导入方案。
- ETA 的运维使用场景、可接受误差、有效吞吐观测窗口和链路不可预测时的处置流程。
- 船端目标操作系统与 CPU 架构、已认证容器运行时、允许的镜像/离线包/磁盘/内存/CPU 上限和离线升级介质。
- 岸端 1,000 个并发船端的事件频率、批次大小、重连峰值、Kubernetes 集群环境、可用区部署和容量冗余目标。
- 船端既有业务消息基础设施的服务目标、资源与故障域边界，以及独立 CDC 采集组件和事件队列可用的 CPU、内存、磁盘、端口、运维责任和升级窗口。
12. 架构原则（ADR 输入）
- 优先复用成熟 CDC 与同步组件；自研仅覆盖成熟组件无法满足的业务控制面或明确缺口。
- 平台事件模型、规则模型和管理 API 独立于具体数据库与 CDC 产品。
- 按表定义同步契约，并将方向、过滤、映射、转换、冲突、窗口和规则版本作为同一可审计单元。
- 弱网恢复、终态事件处理结果、可观测性、幂等应用和防环属于数据平面核心能力，不可作为后续补丁。
- 控制面故障不得使已生效数据平面停止；配置变更必须显式、版本化并可回退。
- 对无法由平台通用解决的业务冲突，保留证据并交由业务规则或人工处理，不伪造自动正确性。
- 先保护关键业务时效，再消化低优先级积压；带宽、磁盘和时间窗口策略必须显式配置、可观测且不得以静默丢数换取稳定性。
- 数据集窗口定义目标端需要收敛的范围；任何放弃历史传输的决定必须可审批、可统计、可审计，并与成功应用明确区分。
- 冲突检测、裁决和回放必须由可恢复状态机驱动；岸端拥有唯一裁决权，船端只接受可验证、可去重且不过期的裁决结果。
- 容器化是默认交付方式；船端优先减少镜像体积和外部运行时依赖，岸端以 Kubernetes 为生产扩展方向并优先支持高并发 I/O、水平扩展和可预测资源占用。
- 优先使用经过验证的 CDC 采集与事件队列基础设施；具体产品由技术选型报告和 PoC 决定。平台自研范围聚焦弱网同步、规则、事件处理结果、窗口、ETA 和冲突裁决，不重复开发数据库日志解析和通用消息代理。