strepsiades
339 lines
12 KiB
Python
339 lines
12 KiB
Python
import copy
|
||
from typing import TypeVar, Generic, Type, Dict, List, Optional, Any
|
||
from pydantic import BaseModel
|
||
import logging
|
||
from pathlib import Path
|
||
|
||
from ..common.collection import DataCollection
|
||
from ..common.binding import BindingManager
|
||
from ..common.sync_node import SyncNode
|
||
from .config import StrategyConfig, OrphanAction, UpdateDirection, ConfigPresets
|
||
from .strategy_ops import (
|
||
get_phase1_reset_defaults,
|
||
run_bind,
|
||
run_create,
|
||
run_delete,
|
||
run_phase2_cleanup,
|
||
run_update,
|
||
)
|
||
from ..engine import (
|
||
StateMachineConfig,
|
||
StateMachineRuntime,
|
||
)
|
||
from ..validation import SchemaDiffValidator
|
||
from .strategy_ops.compare_ops import normalized_data_for_compare
|
||
|
||
T = TypeVar("T", bound=BaseModel)
|
||
logger = logging.getLogger(__name__)
|
||
|
||
class BaseSyncStrategy(Generic[T]):
|
||
"""
|
||
同步策略基类。
|
||
纯逻辑层，不负责 IO 执行。
|
||
|
||
子类可以通过覆盖 default_config 来设置默认配置：
|
||
```python
|
||
class ProjectStrategy(DefaultSyncStrategy):
|
||
default_config = StrategyConfig(
|
||
auto_bind_fields=["name", "code"],
|
||
local_orphan_action=OrphanAction.CREATE_REMOTE
|
||
)
|
||
schema = ProjectResponse
|
||
```
|
||
|
||
跳过同步控制：
|
||
skip_sync: bool - 如果为 True，则跳过该类型的 bind/create/update/sync 阶段
|
||
数据仍会被加载，但不会执行任何同步操作
|
||
适用于只需要加载数据供其他类型引用的场景（如 supplier）
|
||
skip_post_check: bool - 如果为 True，则跳过该类型最终 post-check 的 reload 与一致性校验
|
||
"""
|
||
# 类变量：默认配置（子类可覆盖）
|
||
default_config: StrategyConfig = StrategyConfig()
|
||
# 类变量：schema 类型（子类必须设置）
|
||
schema: Type[T] = None # type: ignore
|
||
# 类变量：是否默认跳过同步（子类可覆盖）
|
||
default_skip_sync: bool = False
|
||
# 类变量：是否默认跳过 post-check（子类可覆盖）
|
||
default_skip_post_check: bool = False
|
||
|
||
def __init__(
|
||
self,
|
||
node_type: str,
|
||
local_collection: DataCollection,
|
||
remote_collection: DataCollection,
|
||
binding_manager: BindingManager,
|
||
):
|
||
if self.schema is None:
|
||
raise ValueError(f"{self.__class__.__name__} must define schema as a class variable")
|
||
|
||
self.node_type = node_type
|
||
self.local_collection = local_collection
|
||
self.remote_collection = remote_collection
|
||
self.binding_manager = binding_manager
|
||
# 复制类级别的默认配置到实例
|
||
self.config = self.default_config.model_copy(deep=True)
|
||
# 是否跳过同步（可运行时修改）
|
||
self.skip_sync = self.default_skip_sync
|
||
# 是否跳过 post-check（可运行时修改）
|
||
self.skip_post_check = self.default_skip_post_check
|
||
# 统一由 Pipeline 注入 runtime；未注入时在执行阶段显式报错
|
||
self.sm_runtime: Optional[StateMachineRuntime] = None
|
||
self._schema_diff_validator: Optional[SchemaDiffValidator] = None
|
||
|
||
# 配置逻辑校验
|
||
self._validate_config()
|
||
|
||
def ensure_runtime(self) -> StateMachineRuntime:
|
||
runtime = self.sm_runtime
|
||
if runtime is None:
|
||
cfg_path = Path(__file__).resolve().parents[1] / "config" / "node_state_machine.yaml"
|
||
runtime = StateMachineRuntime(StateMachineConfig.load(cfg_path))
|
||
self.sm_runtime = runtime
|
||
self.local_collection.set_state_machine_runtime(runtime)
|
||
self.remote_collection.set_state_machine_runtime(runtime)
|
||
return runtime
|
||
|
||
def _validate_config(self) -> None:
|
||
"""
|
||
校验配置的逻辑一致性。
|
||
|
||
规则：
|
||
- PUSH 模式：local_orphan_action 应为 CREATE_REMOTE，remote_orphan_action 应为 NONE
|
||
- PULL 模式：local_orphan_action 应为 NONE，remote_orphan_action 应为 CREATE_LOCAL
|
||
- NONE 模式：两者都应为 NONE
|
||
"""
|
||
direction = self.config.update_direction
|
||
local_action = self.config.local_orphan_action
|
||
remote_action = self.config.remote_orphan_action
|
||
|
||
# PUSH 模式检查
|
||
if direction == UpdateDirection.PUSH:
|
||
if local_action == OrphanAction.CREATE_LOCAL:
|
||
logger.warning(
|
||
f"[{self.node_type}] Config inconsistency: "
|
||
f"update_direction=PUSH but local_orphan_action=CREATE_LOCAL (本地创建)。"
|
||
f"应使用 CREATE_REMOTE (推送到远程)"
|
||
)
|
||
if remote_action == OrphanAction.CREATE_LOCAL:
|
||
logger.warning(
|
||
f"[{self.node_type}] Config inconsistency: "
|
||
f"update_direction=PUSH but remote_orphan_action=CREATE_LOCAL (本地创建)。"
|
||
f"PUSH 模式应设为 NONE 或 DELETE_REMOTE"
|
||
)
|
||
|
||
# PULL 模式检查
|
||
elif direction == UpdateDirection.PULL:
|
||
if local_action == OrphanAction.CREATE_REMOTE:
|
||
logger.warning(
|
||
f"[{self.node_type}] Config inconsistency: "
|
||
f"update_direction=PULL but local_orphan_action=CREATE_REMOTE (推送到远程)。"
|
||
f"PULL 模式应设为 NONE 或 DELETE_LOCAL"
|
||
)
|
||
if remote_action in {OrphanAction.CREATE_REMOTE, OrphanAction.DELETE_LOCAL}:
|
||
logger.warning(
|
||
f"[{self.node_type}] Config inconsistency: "
|
||
f"update_direction=PULL but remote_orphan_action={remote_action}。"
|
||
f"PULL 模式建议使用 CREATE_LOCAL 或 NONE"
|
||
)
|
||
|
||
# NONE 模式检查
|
||
elif direction == UpdateDirection.NONE:
|
||
if local_action != OrphanAction.NONE:
|
||
logger.warning(
|
||
f"[{self.node_type}] Config inconsistency: "
|
||
f"update_direction=NONE but local_orphan_action={local_action}。"
|
||
f"应设为 NONE"
|
||
)
|
||
if remote_action != OrphanAction.NONE:
|
||
logger.warning(
|
||
f"[{self.node_type}] Config inconsistency: "
|
||
f"update_direction=NONE but remote_orphan_action={remote_action}。"
|
||
f"应设为 NONE"
|
||
)
|
||
|
||
def set_config(self, config: StrategyConfig):
|
||
"""完全替换配置对象"""
|
||
self.config = config
|
||
self._schema_diff_validator = None
|
||
self._validate_config()
|
||
|
||
def update_config(self, **kwargs):
|
||
"""
|
||
临时修改部分配置项。
|
||
|
||
Example:
|
||
strategy.update_config(
|
||
local_orphan_action=OrphanAction.NONE,
|
||
update_direction=UpdateDirection.PULL
|
||
)
|
||
"""
|
||
valid_fields = type(self.config).model_fields
|
||
for key, value in kwargs.items():
|
||
if key in valid_fields:
|
||
setattr(self.config, key, value)
|
||
else:
|
||
logger.warning(f"[{self.node_type}] Unknown config key: {key}")
|
||
self._schema_diff_validator = None
|
||
# 更新配置后也要校验
|
||
self._validate_config()
|
||
|
||
def apply_preset(self, preset_name: str):
|
||
"""
|
||
应用配置预设。
|
||
|
||
Args:
|
||
preset_name: 预设名称，可选：first_sync, daily_sync, repair_sync, pull_only, push_only
|
||
|
||
Example:
|
||
strategy.apply_preset("first_sync")
|
||
"""
|
||
preset_config = ConfigPresets.get_preset(preset_name)
|
||
self.config = preset_config
|
||
self._schema_diff_validator = None
|
||
self._validate_config()
|
||
logger.info(f"[{self.node_type}] Applied preset: {preset_name}")
|
||
|
||
def get_schema_diff_validator(self) -> SchemaDiffValidator:
|
||
if self._schema_diff_validator is None:
|
||
self._schema_diff_validator = SchemaDiffValidator(
|
||
schema_name=self.schema.__name__,
|
||
ignore_fields=self.config.compare_ignore_fields,
|
||
ignore_list_item_fields=self.config.post_check_ignore_list_item_fields,
|
||
)
|
||
return self._schema_diff_validator
|
||
|
||
def reset_schema_diff_validator(self) -> None:
|
||
self.get_schema_diff_validator().reset()
|
||
|
||
def emit_schema_diff_report(self) -> None:
|
||
validator = self.get_schema_diff_validator()
|
||
if not validator.has_records():
|
||
return
|
||
for line in validator.format_summary_lines():
|
||
logger.info(f"[{self.node_type}] validate {line}")
|
||
|
||
def preprocess_compare_payload(self, payload: Dict[str, Any]) -> Dict[str, Any]:
|
||
return payload
|
||
|
||
def normalize_compare_payload(
|
||
self,
|
||
data: Optional[Dict[str, Any]],
|
||
data_id_map: Optional[Dict[str, str]] = None,
|
||
) -> Dict[str, Any]:
|
||
normalized = normalized_data_for_compare(
|
||
data,
|
||
data_id_map,
|
||
ignore_fields=set(self.config.compare_ignore_fields),
|
||
ignore_list_item_fields=self.config.post_check_ignore_list_item_fields,
|
||
)
|
||
return self.preprocess_compare_payload(copy.deepcopy(normalized))
|
||
|
||
async def bind(self, **kwargs):
|
||
"""进行绑定逻辑判定，设置 node.binding_status 和 node.action"""
|
||
raise NotImplementedError
|
||
|
||
async def create(self) -> List[SyncNode]:
|
||
"""准备 CREATE 操作"""
|
||
raise NotImplementedError
|
||
|
||
async def update(self) -> List[SyncNode]:
|
||
"""准备 UPDATE 操作"""
|
||
raise NotImplementedError
|
||
|
||
def _needs_update(
|
||
self,
|
||
source_node: SyncNode,
|
||
target_node: SyncNode,
|
||
resolved_data: Optional[Dict[str, Any]] = None,
|
||
data_id_map: Optional[Dict[str, str]] = None,
|
||
) -> bool:
|
||
from .strategy_ops.update_ops import default_needs_update
|
||
|
||
return default_needs_update(self, source_node, target_node, resolved_data, data_id_map)
|
||
|
||
@classmethod
|
||
def get_phase1_reset_defaults(cls) -> Dict[str, Any]:
|
||
return get_phase1_reset_defaults()
|
||
|
||
@classmethod
|
||
async def run_reset(
|
||
cls,
|
||
*,
|
||
node_types: List[str],
|
||
local_collection: DataCollection,
|
||
remote_collection: DataCollection,
|
||
binding_manager: BindingManager,
|
||
runtime: StateMachineRuntime,
|
||
) -> int:
|
||
"""
|
||
执行加载后的重置清理（僵尸 CREATE 节点清理）。
|
||
|
||
说明：
|
||
- `DataCollection.load_from_persistence()` 仅恢复持久化状态；
|
||
- 这里触发 E01：create_zombie -> S15（删除），其余 -> S00。
|
||
"""
|
||
return await run_phase2_cleanup(
|
||
node_types=node_types,
|
||
local_collection=local_collection,
|
||
remote_collection=remote_collection,
|
||
binding_manager=binding_manager,
|
||
runtime=runtime,
|
||
)
|
||
|
||
@classmethod
|
||
async def run_phase2_reset(
|
||
cls,
|
||
*,
|
||
node_types: List[str],
|
||
local_collection: DataCollection,
|
||
remote_collection: DataCollection,
|
||
binding_manager: BindingManager,
|
||
runtime: StateMachineRuntime,
|
||
) -> int:
|
||
"""兼容旧命名，等价于 `run_reset`。"""
|
||
return await cls.run_reset(
|
||
node_types=node_types,
|
||
local_collection=local_collection,
|
||
remote_collection=remote_collection,
|
||
binding_manager=binding_manager,
|
||
runtime=runtime,
|
||
)
|
||
|
||
|
||
class DefaultSyncStrategy(BaseSyncStrategy[T]):
|
||
"""
|
||
基于 STATE_DEFINITIONS.md 实现的标准化同步策略。
|
||
采用四阶段管线：核心状态 -> 依赖检查 -> 自动匹配 -> 动作映射。
|
||
"""
|
||
|
||
async def bind(self, **kwargs):
|
||
self.ensure_runtime()
|
||
await run_bind(self, **kwargs)
|
||
|
||
|
||
|
||
def _get_id_field_hints(self) -> Dict[str, str]:
|
||
"""
|
||
获取 ID 字段的 node_type 提示。
|
||
|
||
默认实现：从 depend_fields 中提取。
|
||
子类可以重写此方法提供更精确的映射。
|
||
|
||
Returns:
|
||
字段名到 node_type 的映射，例如 {"project_id": "project"}
|
||
"""
|
||
return dict(self.config.depend_fields) if self.config.depend_fields else {}
|
||
async def create(self) -> List[SyncNode]:
|
||
self.ensure_runtime()
|
||
return await run_create(self)
|
||
|
||
async def update(self) -> List[SyncNode]:
|
||
self.ensure_runtime()
|
||
return await run_update(self)
|
||
|
||
async def delete(self) -> List[SyncNode]:
|
||
self.ensure_runtime()
|
||
return await run_delete(self)
|
||
|
||
|