# 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. 不把副作用字段强行纳入完全一致比较。