ecm_sync_system/docs/ecm_sync_followup_plan.md

ECM Sync Follow-up Plan

目标

本轮先落两件事：

1. 项目聚合读取接口，降低同步读取请求数。
2. 增强现有 validate，让 strategy 可以直接复用 schema diff validator，并输出聚合日志。

第三件事作为下一步：在 backend 里为 data mapping 增加静态样本测试，绕开 pipeline，直接验证本地样本和远程样本在 sync schema 层是否足够一致。

当前结论

1. 项目聚合读取接口

现有按业务拆散的读取方式请求数过高，不适合大规模同步。

本轮改为提供统一项目聚合接口，最小聚合范围：

• project
• project_detail_data
• preparation
• production
• contract

目标：

• 以项目为同步分片单位。
• 减少绝大多数项目级 fan-out 请求。
• 保持写入侧业务流程不变，只优化读取侧接口粒度。

接口返回的数据仍然基于现有 service 组装，不新增业务含义。

2. validate 增强方案

现有 validate 主要停留在 schema 校验，缺少可读的聚合 diff 输出。

本轮新增 schema diff validator，原则：

• 仍以现有 sync schema 为比较中心。
• 支持按 schema 聚合。
• 支持忽略字段配置。
• 支持输出字段级聚合统计。
• 可以被 strategy 直接引用，也可以脱离 pipeline 单独调用。

建议输出格式：

• field_name
• mismatch_count / total_count
• schema_refs
• sample local/remote

例如：

ProjectDiff
code 12/30 [ProjectResponseBase, ProjectBaseInfoUpdate] sample[project-1]=""/"012A"

3. data mapping 静态测试

下一步在 depm backend 中做静态 mapping 测试，目标不是验证整条 pipeline，而是验证 mapping 本身。

测试输入：

• 本地数据静态文件
• 远程数据静态文件

要求：

• 本地样本通过本地 data_mapping 转成 sync schema。
• 远程样本直接按 sync schema 校验。
• 忽略掉少量必须动态生成或动态获取的字段。
• 通过统一 validator 输出字段级 diff 报告。

这类测试应当绕开推送系统，通过手工配对样本来验证 mapping，而不是混在 pipeline 里排查。

已落地项

项目聚合接口

backend 中新增项目同步聚合读取接口，按项目统一返回：

• project
• project_detail_data
• preparation
• production
• contract

schema diff validator

同步引擎新增可独立调用的 schema diff validator：

• 支持忽略顶层字段
• 支持忽略列表元素内特定子字段
• 支持输出字段级 mismatch 聚合统计
• strategy 在 update diff 阶段直接复用该 validator

下一步

先做

1. 为 project 建第一批静态样本。
2. 用统一 validator 对本地样本和远程样本做 schema 层比较。
3. 只在 validator 配置里维护少量 ignore 字段，不额外引入 contract 文件。

暂不做

1. 不引入 schema 外的独立契约系统。
2. 不为所有 domain 一次性补齐静态样本。
3. 不把副作用字段强行纳入完全一致比较。