first commit

2026-03-09 16:31:42 +08:00
commit 4a9c444b10
486 changed files with 52479 additions and 0 deletions
@@ -0,0 +1,291 @@
+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,
+)
+
+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）
+    """
+    # 类变量：默认配置（子类可覆盖）
+    default_config: StrategyConfig = StrategyConfig()
+    # 类变量：schema 类型（子类必须设置）
+    schema: Type[T] = None  # type: ignore
+    # 类变量：是否默认跳过同步（子类可覆盖）
+    default_skip_sync: 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
+        # 统一由 Pipeline 注入 runtime；未注入时在执行阶段显式报错
+        self.sm_runtime: Optional[StateMachineRuntime] = 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._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._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._validate_config()
+        logger.info(f"[{self.node_type}] Applied preset: {preset_name}")
+
+    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)
+
+