ecm_sync_system/docs/collection_query_and_upgrade_plan.md

Collection 查询现状与升级方案

1. 当前实现梳理

核心代码：

• sync_state_machine/common/collection.py
• sync_state_machine/common/binding.py
• sync_state_machine/datasource/datasource.py
• sync_state_machine/sync_system/strategy_ops/*.py

1.1 DataCollection 当前内存结构

DataCollection 目前核心是两张索引：

• _nodes: Dict[node_id, SyncNode]
• _data_id_to_node_id: Dict[data_id, node_id]

特点：

• node_id 查找是 O(1)
• data_id 反查 node 是 O(1)
• 其他查询（按状态/动作/绑定状态/业务字段）目前主要依赖遍历

1.2 查询路径

A. 通用筛选 filter(...)

• 先取 _nodes.values()
• 可按 node_type 过滤
• 可按 node_filter（节点顶层属性）过滤
• 可按 filter（node.data 内字段）过滤

复杂度：最差接近 O(N)

B. 状态筛选 filter_by_state_ids(...)

• 先调用 filter(node_type=...)
• 对每个候选节点，根据状态机配置逐条匹配 binding_status/action/status/data_id_exist
• state_ids 多个时，执行多次匹配

复杂度：约 O(N * |state_ids|)

1.3 调用热点

在 pipeline 中，以下路径高频调用状态筛选：

• bind 阶段（S00）
• create 阶段（S06）
• update 阶段（S07）
• delete 检查（S09）

对应代码：

• sync_state_machine/datasource/datasource.py 的 _sync_nodes
• sync_state_machine/sync_system/strategy_ops/bind_ops.py

1.4 BindingManager 当前查询

BindingManager 当前结构：

• _bindings: Dict[node_type, Dict[local_id, remote_id]]

其中：

• get_remote_id：O(1)
• get_local_id：当前是遍历同类型全部绑定，O(K)

当绑定数量很大时，get_local_id 会成为热点。

---

2. 本次已修正项

2.1 filter(data_filter) 查询中的不必要深拷贝

原实现在 filter 的 data 过滤里每个节点调用 node.get_data()，会触发深拷贝，数据量大时会产生明显 CPU/内存开销。

已改为只读访问 node.data：

• 不改变返回语义
• 降低过滤时的对象复制成本

变更文件：

• sync_state_machine/common/collection.py

2.2 类型标注修正

node_filter 的注解从 callable 修正为 Callable[[SyncNode], bool]，增强类型可读性和 IDE 体验。

---

3. 升级方案（针对三类目标）

目标：

1. 查询性能
2. 架构明确
3. 内存数据不过多

阶段 0（当前）

• 保持现有语义，先完成可观测性：记录各查询调用次数和耗时（尤其 filter_by_state_ids 与 get_local_id）

阶段 1（低风险，优先）

1. 查询性能

• 新增二级内存索引（不替换现有结构，仅并行维护）：
  • by_node_type: Dict[str, Set[node_id]]
  • by_status: Dict[SyncStatus, Set[node_id]]
  • by_action: Dict[SyncAction, Set[node_id]]
  • by_binding_status: Dict[BindingStatus, Set[node_id]]
  • by_type_status_action: Dict[(node_type,status,action), Set[node_id]]
• filter_by_state_ids 先用组合索引缩小候选，再做状态机细匹配

2. 架构明确

• 增加查询层接口（例如 CollectionQueryEngine），将“筛选逻辑”与“存储结构”分离
• 业务侧只依赖查询接口，不直接依赖 _nodes

3. 内存控制

• 新增按需字段索引，仅为高频字段建立（如 project_id/company_id/contract_id）
• 索引集采用 set[node_id]，避免复制节点对象

阶段 2（中风险）

1. 查询性能

• BindingManager 增加反向索引：
  • remote_to_local: Dict[node_type, Dict[remote_id, local_id]]
• 将 get_local_id 从 O(K) 降至 O(1)

2. 架构明确

• 统一节点写路径（add/update/delete）触发索引增量更新
• 明确“不允许绕过 Collection 写入节点”

3. 内存控制

• 增加可配置的“弱索引模式”：在低内存场景关闭部分次级索引

阶段 3（可选，较高风险）

1. 查询性能

• 引入 SQLite 热查询表（内存 SQLite 或磁盘 SQLite）承接复杂组合查询
• 保留内存索引作为热点路径，DB 作为补充查询后端

2. 架构明确

• 形成分层：
  • 热路径：内存索引
  • 冷路径：SQLite 查询
  • 归档：持久化 DB

3. 内存控制

• 支持“分批加载 + 分批同步 + checkpoint”
• 将非活跃节点转冷存储，只在命中时回载

---

4. 启动/重置语义说明（避免误判）

当前默认不是每次全清空：

• 启动会先加载持久化，再执行 E01 归并清理
• 仅在 persist.wipe_on_start=true 时会在启动前删除持久化 DB

因此若做“分批/多轮 pipeline”，建议：

• 保持 wipe_on_start=false
• 通过显式 checkpoint 与增量范围控制保证状态一致性

---

5. 结论

短期最优路径：

• 先完成阶段 1 + 阶段 2（低/中风险），通常能解决大部分查询性能问题
• 再根据压测结果决定是否进入阶段 3（SQL 化冷查询）

这条路线兼顾：

• 速度（热路径仍在内存）
• 清晰性（查询层解耦）
• 内存边界（按需索引 + 分批加载）