ecm_sync_system/docs/sync_issue_analysis_20260305.md

# 同步问题分析（2026-03-05）

## 背景

- 同步方式：先用 `working_local_datasource/filtered` 初始化远程数据库，再基于 `run_profiles/jsonl_to_api.yaml` 执行 `jsonl -> api` 同步。
- 本文基于日志 `test_results/sync_state_machine/simple_pipeline_sm_20260305_102926.log` 与状态库 `test_results/sync_state_machine/simple_pipeline_sm.db`。

## 总体结果

- Pipeline 统计：`loaded=311, synced=204, failed=8, post_check_passed=True, mismatch_types=4`
- 不一致类型：`company`, `construction_task`, `material`, `contract_settlement`
- 其中失败（`failed=8`）全部集中在 `contract_settlement` 的 `UPDATE` 阶段。

## 自动绑定问题

> 注：本轮日志已降噪，自动绑定明细多数为 debug 级；以下结论来自 sqlite 状态库查询。

### 非 normal 绑定状态

1. `local.construction_task_detail` 1 条 `dep_err`
   - 错误：依赖 `parent_id -> construction_task` 未找到
   - 现象：`depends=[parent_id:construction_task data_id=... -> not_found]`
   - 结论：这是明确的依赖绑定失败（上游父节点缺失或 data_id 不可达）。

2. `local.project_detail_data` 2 条 `warning`
   - 错误：`未匹配到候选节点且不允许创建`
   - 结论：策略配置不允许创建，且自动匹配未命中，属于预期拦截，不是执行异常。

除上述 3 条外，主要业务类型绑定状态均为 `normal`。

## 更新后仍不一致（按类型）

### 1) company（1/1 不一致）

- 差异字段：`city_name`, `province_name`, `parent_name`
- 模式：本地有值，远端为 `None`
- 结论：远端 list 返回字段缺失/置空，导致 post-check 一定失败。

### 2) construction_task（12/32 不一致）

- 典型残留字段：
  - `status`
  - `complete_quantity`, `complete_rate`
  - `actual_complete_date`, `statistic_date`, `delay_days`
  - `plan_node`（特别是 `is_audit` 值）
- 模式：远端回读为 `None`/`0.0`/默认值，而本地有业务值。
- 结论：该类字段主要受后端计算/回写策略影响，当前 update API 无法完全收敛到本地口径。

### 3) material（3/20 不一致）

- 典型残留字段：
  - `complete_quantity`, `complete_rate`
  - `actual_start_date`, `status`, `delay_days`
  - `plan_node.is_audit`
- 模式与 construction_task 一致：部分字段被后端默认化或不回写。
- 结论：属于“可更新字段集合与回读字段集合不一致”导致的残留差异。

### 4) contract_settlement（34/34 不一致，最严重）

- 全量普遍差异：`contract_type`（本地 `None`，远端有值如 `DP/GP/...`）
- 伴随差异：`complete_price`, `contract_price`, `actual_start_date`, `plan_complete_date`, `plan_node`, `status` 等
- 执行结果（remote）：`UPDATE SUCCESS=1, FAILED=8, SKIPPED=25`
- 8 条失败统一报错：`API error: 计划节点时间必须 晚于计划开始时间`
- 结论：
  - 一部分差异来自字段语义不一致（如 `contract_type`）
  - 一部分差异来自计划节点 API 校验失败，导致更新无法落库
  - 因此该类型短期内无法靠重跑自动收敛

## 根因归类

### A. 后端返回口径与本地模型口径不一致

- 典型：`company` 的名称类字段、`construction/material` 的状态/累计/统计字段。

### B. 更新 schema/API 覆盖范围有限

- 某些字段在 response 中存在，但不在 update schema 或后端 update 逻辑中生效。

### C. 计划节点约束导致更新失败

- `contract_settlement` 明确出现计划节点时间校验失败，直接阻断更新。

### D. 依赖链局部断裂

- `construction_task_detail` 存在 parent 依赖找不到，导致绑定 `dep_err`。

## 建议优先级（不改代码版）

1. **先处理 contract_settlement 的计划节点校验失败**
   - 这是唯一明确执行失败来源（8 条），修复后可显著降低不一致。

2. **明确“应比对字段白名单”与“只读/回写字段”**
   - 对 `construction_task/material/company` 区分“业务必须一致字段”与“后端派生/可忽略字段”。

3. **修复依赖断裂样本**
   - 针对 `construction_task_detail` 的 `parent_id` 失配，核对父节点是否在过滤阶段被裁掉或 data_id 不一致。

4. **针对 `project_detail_data` 的 warning 决策**
   - 确认是否允许创建；若业务上应存在，需调整策略配置。

---

如果需要，我可以基于本文再拆成一份“可执行排障清单”（按 SQL/API/配置三条线），每条给出具体核对命令与验收标准。

## 外部后端实现核对结论（只分析，不改代码）

以下结论来自对 `GroupSideProjectManagementSystem` 后端 `third-v2` 路由、schema、operation、service 的实现阅读。

### 1) company 名称字段为何会空

- `/company/list` 并非直接返回库里的 `city_name/province_name/parent_name`，而是服务层在查询后“二次计算”这三个字段。
- 计算依赖两张映射：
  - 行政区映射（`province/city code -> name`）
  - 公司映射（`parent_id -> parent_name`）
- 如果编码不在映射中、或 `parent_id` 未命中，最终会返回 `None`/空字符串。
- 因此该类差异并不一定是“推送失败”，更像是“回读时依赖映射补全失败或口径不一致”。

### 2) construction_task/material 的 plan_node 差异为何顽固

- 在 `third-v2` 的 `PlanUpdate` schema 中，存在 `model_validator`：会先自动清理边界节点（等于 `plan_start_date` 或 `plan_complete_date` 的首尾节点）。
- 随后在 operation 的 `push(plan)` 中，又会把边界节点重新插回库里，并且统一写入 `is_audit=True`。
- 这意味着：
  - 请求入参和最终落库结构并不完全一致；
  - 如果本地源数据不含边界节点，或 `is_audit` 口径不同，post-check 很容易出现稳定残差。

### 3) contract_settlement 为何最严重（34/34 + 8条失败）

- 计划更新接口的业务规则是“开始时间与合同金额来自合同表”，不是来自推送体：
  - `plan_start_date` 强制取合同 `sign_date`
  - `contract_price` 强制取合同 `total_price`
- 即便推送体带了这两个值，也会在 operation 中被覆盖。
- 同时仍有严格校验：计划节点必须晚于开始时间、早于结束时间、数量递增等；不满足直接 400。
- 这正对应日志里的 8 条失败（计划节点时间校验）与大量更新后不一致（字段被后端覆盖到“合同口径”）。

### 4) list 回读与单条回读口径不一致（会放大不一致）

- 多个类型的 `get_by_id` 会裁掉 `plan_node` 首尾节点，但 `get_list_by_project_id` 通常返回主表原始节点（含首尾）。
- 同步系统做 post-check 用的是 list 拉取结果时，这种“单条/列表口径不一致”会放大 plan_node 相关差异。

### 5) status/complete_rate/delay_days 等字段为何容易残留差异

- 这些字段主要由明细驱动的主表同步逻辑计算并回写，不是 plan/base update 的直接输入字段。
- 因此“推送成功”并不等价于“这些派生字段立即与源数据一致”。

## 建议（仍不改代码）

1. **先按后端口径预处理结算计划数据**
   - 以合同 `sign_date/total_price` 作为 settlement 比对基准和推送基准；
   - 推送前先做节点时间边界校验，避免 400。

2. **对 plan_node 建立统一比较口径**
   - 在 post-check 里对 construction/material/settlement 统一做“边界节点归一化 + `is_audit` 口径归一化”后再比较。

3. **区分“业务真差异”与“后端派生差异”**
   - 对 `status/complete_rate/delay_days/actual_*` 这类派生字段设为可选比对或延迟比对。

4. **company 名称字段先做映射可用性核查**
   - 重点核对 `province/city` 编码是否在后端行政区字典可解析、`parent_id` 是否可命中公司映射。