refactor: add durable transfer planning checkpoints

app/db/oper/transferpending.py

@@ -1,5 +1,5 @@
 from datetime import datetime
-from typing import List, Optional, Tuple
+from typing import Any, List, Optional, Tuple
 
 from app.db.base import DbOper
 from app.db.models.transferpending import TransferPending
@@ -32,7 +32,9 @@ class TransferPendingOper(DbOper):
         )
 
     def stage_admit(self, *, task_id: str, storage: str, src_path: str,
-                    state: str, now_time: str) -> Optional[TransferPending]:
+                    state: str, now_time: str, input_version: int = 1,
+                    planning_input: Optional[dict[str, Any]] = None,
+                    input_fingerprint: Optional[str] = None) -> Optional[TransferPending]:
         """
         在当前会话中暂存一条持久接纳记录。
 
@@ -42,6 +44,9 @@ class TransferPendingOper(DbOper):
         :param src_path: 源文件路径
         :param state: 持久状态
         :param now_time: 当前时间
+        :param input_version: 规划输入格式版本
+        :param planning_input: 版本化规划输入 JSON
+        :param input_fingerprint: 规划输入规范 JSON 指纹
         :return: 接纳记录
         """
         return self._execute_sync_write(
@@ -52,6 +57,9 @@ class TransferPendingOper(DbOper):
                 src_path=src_path,
                 state=state,
                 now_time=now_time,
+                input_version=input_version,
+                planning_input=planning_input,
+                input_fingerprint=input_fingerprint,
             )
         )
 
@@ -71,6 +79,22 @@ class TransferPendingOper(DbOper):
             )
         ) or []
 
+    def list_by_states(self, *, states: tuple[str, ...],
+                       limit: Optional[int] = 5000) -> List[TransferPending]:
+        """
+        使用当前会话列出多个可恢复状态的记录。
+        :param states: 允许恢复的状态集合
+        :param limit: 单次读取上限
+        :return: ORM 接纳记录列表
+        """
+        return self._execute_sync_query(
+            lambda session: TransferPending.list_by_states(
+                session,
+                states=states,
+                limit=limit,
+            )
+        ) or []
+
     def get_by_identity(self, *, storage: str,
                         src_path: str) -> Optional[TransferPending]:
         """
@@ -87,6 +111,72 @@ class TransferPendingOper(DbOper):
             )
         )
 
+    def get_by_task_id(self, *, task_id: str) -> Optional[TransferPending]:
+        """
+        使用当前会话按稳定任务标识查询接纳记录。
+        :param task_id: 稳定任务标识
+        :return: 接纳记录
+        """
+        return self._execute_sync_query(
+            lambda session: TransferPending.get_by_task_id(
+                session,
+                task_id=task_id,
+            )
+        )
+
+    def stage_checkpoint_plan(
+            self,
+            *,
+            task_id: str,
+            input_fingerprint: str,
+            checkpoint_version: int,
+            checkpoint_payload: dict[str, Any],
+            source_states: tuple[str, ...],
+            target_state: str,
+            now_time: str,
+    ) -> int:
+        """
+        在当前会话中以输入指纹为条件暂存完整计划检查点。
+        :param task_id: 稳定任务标识
+        :param input_fingerprint: 规划输入规范 JSON 指纹
+        :param checkpoint_version: 检查点格式版本
+        :param checkpoint_payload: 完整有序计划 JSON
+        :param source_states: 允许执行 CAS 的起始状态
+        :param target_state: 检查点提交后的目标状态
+        :param now_time: 当前时间
+        :return: 更新的记录数
+        """
+        return self._execute_sync_write(
+            lambda session: TransferPending.checkpoint_plan(
+                session,
+                task_id=task_id,
+                input_fingerprint=input_fingerprint,
+                checkpoint_version=checkpoint_version,
+                checkpoint_payload=checkpoint_payload,
+                source_states=source_states,
+                target_state=target_state,
+                now_time=now_time,
+            )
+        )
+
+    def stage_record_planning_failure(self, *, task_id: str, error: str,
+                                      now_time: str) -> int:
+        """
+        在当前会话中记录规划失败并保持任务处于接纳态。
+        :param task_id: 稳定任务标识
+        :param error: 失败原因
+        :param now_time: 当前时间
+        :return: 更新的记录数
+        """
+        return self._execute_sync_write(
+            lambda session: TransferPending.record_planning_failure(
+                session,
+                task_id=task_id,
+                error=error,
+                now_time=now_time,
+            )
+        )
+
     def stage_record_enqueue_failure(self, *, task_id: str, error: str,
                                      now_time: str) -> int:
         """