llm-content-creator 0.1.0

package/src/domain/repositories/TaskRepository.ts

@@ -0,0 +1,271 @@
+/**
+ * TaskRepository 接口
+ *
+ * 定义任务数据访问层的契约
+ */
+
+import type { Task } from '../entities/Task.js';
+import { TaskStatus, ExecutionMode } from '../entities/Task.js';
+
+// 重新导出 Task 类型，方便其他模块使用
+export type { Task };
+
+/**
+ * 创建任务输入参数
+ */
+export interface CreateTaskInput {
+  id?: string;
+  userId?: string;
+  mode: ExecutionMode;
+  topic: string;
+  requirements: string;
+  hardConstraints?: {
+    minWords?: number;
+    maxWords?: number;
+    keywords?: string[];
+  };
+  idempotencyKey?: string;
+}
+
+/**
+ * 查询任务列表的过滤器
+ */
+export interface TaskFilter {
+  userId?: string;
+  status?: TaskStatus;
+  mode?: ExecutionMode;
+  startDate?: Date;
+  endDate?: Date;
+}
+
+/**
+ * 分页参数
+ */
+export interface Pagination {
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * 分页结果
+ */
+export interface PaginatedResult<T> {
+  data: T[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+/**
+ * 创建任务参数（简化版本，用于 SQLite/Memory Repository）
+ */
+export interface TaskCreateParams {
+  id: string;
+  traceId?: string;
+  mode: string;
+  type: string;
+  topic: string;
+  requirements: string;
+  hardConstraints?: any;
+  maxRetries?: number;
+  priority?: number;
+}
+
+/**
+ * 更新任务参数（简化版本，用于 SQLite/Memory Repository）
+ */
+export interface TaskUpdateParams {
+  status?: string;
+  currentStep?: string;
+  errorMessage?: string;
+  retryCount?: number;
+  workerId?: string;
+  startedAt?: string;
+  completedAt?: string;
+  version?: number;
+}
+
+/**
+ * 任务列表过滤器（简化版本，用于 SQLite/Memory Repository）
+ */
+export interface TaskListFilters {
+  status?: string;
+  workerId?: string;
+  type?: string;
+  limit?: number;
+  offset?: number;
+  sortBy?: string;
+  sortOrder?: 'ASC' | 'DESC';
+}
+
+/**
+ * TaskRepository 接口
+ */
+export interface ITaskRepository {
+  /**
+   * 创建任务
+   *
+   * @param input - 创建任务输入参数
+   * @returns 创建的任务
+   */
+  create(input: CreateTaskInput): Promise<Task>;
+
+  /**
+   * 根据 taskId 查询任务
+   *
+   * @param taskId - 任务 ID
+   * @returns 任务或 null
+   */
+  findById(taskId: string): Promise<Task | null>;
+
+  /**
+   * 根据 idempotencyKey 查询任务
+   *
+   * @param idempotencyKey - 幂等键
+   * @returns 任务或 null
+   */
+  findByIdempotencyKey(idempotencyKey: string): Promise<Task | null>;
+
+  /**
+   * 根据 userId 查询任务列表
+   *
+   * @param userId - 用户 ID
+   * @param pagination - 分页参数
+   * @returns 任务列表
+   */
+  findByUserId(userId: string, pagination?: Pagination): Promise<Task[]>;
+
+  /**
+   * 查询任务列表（支持过滤和分页）
+   *
+   * @param filter - 过滤条件
+   * @param pagination - 分页参数
+   * @returns 任务列表
+   */
+  findMany(filter?: TaskFilter, pagination?: Pagination): Promise<Task[]>;
+
+  /**
+   * 统计任务数量
+   *
+   * @param filter - 过滤条件
+   * @returns 任务数量
+   */
+  count(filter?: TaskFilter): Promise<number>;
+
+  /**
+   * 更新任务状态（带乐观锁）
+   *
+   * @param taskId - 任务 ID
+   * @param status - 新状态
+   * @param version - 当前版本号
+   * @returns 是否更新成功
+   */
+  updateStatus(taskId: string, status: TaskStatus, version: number): Promise<boolean>;
+
+  /**
+   * 更新当前步骤（带乐观锁）
+   *
+   * @param taskId - 任务 ID
+   * @param step - 当前步骤名称
+   * @param version - 当前版本号
+   * @returns 是否更新成功
+   */
+  updateCurrentStep(taskId: string, step: string, version: number): Promise<boolean>;
+
+  /**
+   * Worker 抢占任务（乐观锁）
+   *
+   * 只有状态为 pending 且版本号匹配的任务才能被抢占
+   *
+   * @param taskId - 任务 ID
+   * @param workerId - Worker ID
+   * @param version - 当前版本号
+   * @returns 是否抢占成功
+   */
+  claimTask(taskId: string, workerId: string, version: number): Promise<boolean>;
+
+  /**
+   * 增加重试计数（带乐观锁）
+   *
+   * @param taskId - 任务 ID
+   * @param type - 重试类型（text/image）
+   * @param version - 当前版本号
+   * @returns 是否更新成功
+   */
+  incrementRetryCount(
+    taskId: string,
+    type: 'text' | 'image',
+    version: number
+  ): Promise<boolean>;
+
+  /**
+   * 保存 State 快照（带乐观锁）
+   *
+   * @param taskId - 任务 ID
+   * @param snapshot - State 快照对象
+   * @param version - 当前版本号
+   * @returns 是否更新成功
+   */
+  saveStateSnapshot(taskId: string, snapshot: object, version: number): Promise<boolean>;
+
+  /**
+   * 标记任务完成（带乐观锁）
+   *
+   * @param taskId - 任务 ID
+   * @param version - 当前版本号
+   * @returns 是否更新成功
+   */
+  markAsCompleted(taskId: string, version: number): Promise<boolean>;
+
+  /**
+   * 标记任务失败（带乐观锁）
+   *
+   * @param taskId - 任务 ID
+   * @param errorMessage - 错误信息
+   * @param version - 当前版本号
+   * @returns 是否更新成功
+   */
+  markAsFailed(taskId: string, errorMessage: string, version: number): Promise<boolean>;
+
+  /**
+   * 释放 Worker 占用（用于任务崩溃时）
+   *
+   * @param taskId - 任务 ID
+   * @param workerId - Worker ID（用于验证）
+   * @param version - 当前版本号
+   * @returns 是否释放成功
+   */
+  releaseWorker(taskId: string, workerId: string, version: number): Promise<boolean>;
+
+  /**
+   * 软删除任务
+   *
+   * @param taskId - 任务 ID
+   * @returns 是否删除成功
+   */
+  softDelete(taskId: string): Promise<boolean>;
+
+  /**
+   * 永久删除任务
+   *
+   * @param taskId - 任务 ID
+   * @returns 是否删除成功
+   */
+  delete(taskId: string): Promise<boolean>;
+
+  /**
+   * 获取待处理任务队列（用于 Worker 获取任务）
+   *
+   * @param limit - 获取数量限制
+   * @returns 待处理任务列表
+   */
+  getPendingTasks(limit?: number): Promise<Task[]>;
+
+  /**
+   * 获取 Worker 的活跃任务
+   *
+   * @param workerId - Worker ID
+   * @returns 活跃任务列表
+   */
+  getActiveTasksByWorker(workerId: string): Promise<Task[]>;
+}

package/src/domain/workflow/CheckpointManager.ts

@@ -0,0 +1,283 @@
+/**
+ * CheckpointManager - 检查点管理器
+ *
+ * 负责工作流状态的保存和恢复：
+ * - 每个 Node 执行完成后保存 State 到数据库
+ * - 崩溃后从数据库恢复 State
+ * - 支持断点续传
+ */
+
+import type { WorkflowState } from './State.js';
+import { StateSnapshotManager } from './State.js';
+import { PostgresTaskRepository } from '../../infrastructure/database/PostgresTaskRepository.js';
+import { createLogger } from '../../infrastructure/logging/logger.js';
+
+const logger = createLogger('CheckpointManager');
+
+/**
+ * 检查点信息
+ */
+export interface Checkpoint {
+  taskId: string;
+  stepName: string;
+  state: Partial<WorkflowState>;
+  timestamp: Date;
+}
+
+/**
+ * 检查点管理器
+ */
+export class CheckpointManager {
+  private taskRepo: PostgresTaskRepository;
+  private checkpoints: Map<string, Checkpoint> = new Map();
+
+  constructor(taskRepo?: PostgresTaskRepository) {
+    this.taskRepo = taskRepo || new PostgresTaskRepository();
+  }
+
+  /**
+   * 保存检查点
+   *
+   * @param taskId - 任务 ID
+   * @param stepName - 步骤名称
+   * @param state - 当前工作流状态
+   */
+  async saveCheckpoint(
+    taskId: string,
+    stepName: string,
+    state: WorkflowState
+  ): Promise<void> {
+    try {
+      logger.debug('Saving checkpoint', {
+        taskId,
+        stepName,
+      });
+
+      // 创建检查点快照（只保存必要字段）
+      const snapshot = StateSnapshotManager.createCheckpoint(state);
+
+      // 保存到数据库（使用 State 快照）
+      await this.taskRepo.saveStateSnapshot(
+        taskId,
+        snapshot,
+        state.version
+      );
+
+      // 同时保存到内存（快速访问）
+      this.checkpoints.set(taskId, {
+        taskId,
+        stepName,
+        state: snapshot,
+        timestamp: new Date(),
+      });
+
+      logger.info('Checkpoint saved', {
+        taskId,
+        stepName,
+        keys: Object.keys(snapshot),
+      });
+    } catch (error) {
+      logger.error('Failed to save checkpoint', {
+        taskId,
+        stepName,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      // 不抛出错误，避免影响主流程
+    }
+  }
+
+  /**
+   * 加载检查点
+   *
+   * @param taskId - 任务 ID
+   * @returns 检查点快照，如果不存在则返回 null
+   */
+  async loadCheckpoint(taskId: string): Promise<Checkpoint | null> {
+    try {
+      logger.debug('Loading checkpoint', { taskId });
+
+      // 先从内存查找
+      const memoryCheckpoint = this.checkpoints.get(taskId);
+      if (memoryCheckpoint) {
+        logger.info('Checkpoint loaded from memory', {
+          taskId,
+          stepName: memoryCheckpoint.stepName,
+        });
+        return memoryCheckpoint;
+      }
+
+      // 从数据库加载
+      const task = await this.taskRepo.findById(taskId);
+      if (!task || !task.stateSnapshot) {
+        logger.warn('No checkpoint found', { taskId });
+        return null;
+      }
+
+      // 创建检查点
+      const checkpoint: Checkpoint = {
+        taskId,
+        stepName: task.currentStep || 'unknown',
+        state: task.stateSnapshot,
+        timestamp: task.updatedAt,
+      };
+
+      // 保存到内存
+      this.checkpoints.set(taskId, checkpoint);
+
+      logger.info('Checkpoint loaded from database', {
+        taskId,
+        stepName: checkpoint.stepName,
+      });
+
+      return checkpoint;
+    } catch (error) {
+      logger.error('Failed to load checkpoint', {
+        taskId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return null;
+    }
+  }
+
+  /**
+   * 删除检查点
+   *
+   * @param taskId - 任务 ID
+   */
+  async removeCheckpoint(taskId: string): Promise<void> {
+    logger.debug('Removing checkpoint', { taskId });
+
+    // 从内存删除
+    this.checkpoints.delete(taskId);
+
+    // 数据库中的 State 会在任务完成时自动清理
+  }
+
+  /**
+   * 清理所有检查点（内存）
+   */
+  clearAll(): void {
+    logger.info('Clearing all checkpoints from memory', {
+      count: this.checkpoints.size,
+    });
+
+    this.checkpoints.clear();
+  }
+
+  /**
+   * 获取所有检查点信息
+   *
+   * @returns 所有检查点的列表
+   */
+  getAllCheckpoints(): Checkpoint[] {
+    return Array.from(this.checkpoints.values());
+  }
+
+  /**
+   * 检查是否有检查点
+   *
+   * @param taskId - 任务 ID
+   * @returns 是否存在检查点
+   */
+  hasCheckpoint(taskId: string): boolean {
+    return this.checkpoints.has(taskId);
+  }
+
+  /**
+   * 从检查点恢复状态
+   *
+   * @param taskId - 任务 ID
+   * @param initialState - 初始状态（如果无检查点）
+   * @returns 恢复后的状态
+   */
+  async restoreState(
+    taskId: string,
+    initialState: WorkflowState
+  ): Promise<WorkflowState> {
+    logger.debug('Restoring state from checkpoint', { taskId });
+
+    const checkpoint = await this.loadCheckpoint(taskId);
+
+    if (!checkpoint) {
+      logger.info('No checkpoint found, using initial state', { taskId });
+      return initialState;
+    }
+
+    // 合并初始状态和检查点状态
+    const restoredState: WorkflowState = {
+      ...initialState,
+      ...checkpoint.state,
+      // 确保关键字段不被覆盖
+      taskId: initialState.taskId,
+      mode: initialState.mode,
+      topic: initialState.topic,
+      requirements: initialState.requirements,
+      hardConstraints: initialState.hardConstraints,
+    };
+
+    logger.info('State restored from checkpoint', {
+      taskId,
+      stepName: checkpoint.stepName,
+      currentStep: restoredState.currentStep,
+    });
+
+    return restoredState;
+  }
+
+  /**
+   * 验证检查点完整性
+   *
+   * @param checkpoint - 检查点
+   * @returns 是否有效
+   */
+  validateCheckpoint(checkpoint: Checkpoint): boolean {
+    if (!checkpoint.taskId) {
+      logger.warn('Invalid checkpoint: missing taskId');
+      return false;
+    }
+
+    if (!checkpoint.stepName) {
+      logger.warn('Invalid checkpoint: missing stepName', {
+        taskId: checkpoint.taskId,
+      });
+      return false;
+    }
+
+    if (!checkpoint.state || Object.keys(checkpoint.state).length === 0) {
+      logger.warn('Invalid checkpoint: empty state', {
+        taskId: checkpoint.taskId,
+      });
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * 获取检查点统计信息
+   *
+   * @returns 统计信息
+   */
+  getStats(): {
+    totalCount: number;
+    checkpointsByStep: Record<string, number>;
+  } {
+    const checkpoints = this.getAllCheckpoints();
+    const checkpointsByStep: Record<string, number> = {};
+
+    for (const checkpoint of checkpoints) {
+      checkpointsByStep[checkpoint.stepName] =
+        (checkpointsByStep[checkpoint.stepName] || 0) + 1;
+    }
+
+    return {
+      totalCount: checkpoints.length,
+      checkpointsByStep,
+    };
+  }
+}
+
+/**
+ * 检查点管理器单例
+ */
+export const checkpointManager = new CheckpointManager();