增强validator和打印区别

docs/ecm_sync_followup_plan.md

@@ -0,0 +1,111 @@
+# 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`
+
+例如：
+
+```text
+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. 不把副作用字段强行纳入完全一致比较。