@minto-ai/huoshan-tts/src/handler/components/serial-handler.ts

借助“火山引擎在线语音合成API”实现浏览器端“文本转语音

import type { SerialTaskExecuteContext, SerialTaskItem } from '../types'
import { getUuid } from '@minto-ai/tools'
import { BaseHandler } from '../core'
import { SerialHandlerStatus, SerialTaskItemStatus } from '../types'

/**
 * 串行任务处理器 - 按顺序处理队列中的任务
 *
 * 特点：
 * - 使用先进先出(FIFO)队列管理待处理任务
 * - 支持任务执行前的自定义条件检查
 * - 实现完整的生命周期管理（激活、待机、执行、成功、销毁）
 * - 可与其他处理器组成处理链
 *
 * 使用场景：
 * - 需要顺序执行的任务处理
 * - 资源有限需要排队执行的场景
 * - 需要严格控制执行顺序的业务流程
 */
abstract class SerialHandler<O, R> extends BaseHandler<O, R> {
  /**
   * 待处理任务队列
   */
  protected taskQueue: Array<SerialTaskItem<O>> = []

  /**
   * 当前处理器状态
   */
  public handlerStatus: SerialHandlerStatus = SerialHandlerStatus.OFFLINE

  /**
   * 获取待处理任务数量
   */
  public get taskQueueLength(): number {
    return this.taskQueue.length
  }

  constructor() {
    super()
  }

  /**
   * 检查任务执行条件
   * 子类可重写此方法，实现自定义的任务执行前置条件检查
   *
   * @returns {boolean} - 当满足执行条件时返回 true，否则返回 false
   */
  public executePreCheck(): boolean {
    return true
  }

  /**
   * 触发处理器激活行为（空闲状态 => 激活状态）
   */
  public triggerHandlerActive(): void {
    this.setHandlerStatus(SerialHandlerStatus.ACTIVE)
    this.onActive()
    this.triggerHandlerPending()
  }

  /**
   *  触发处理器待机行为（激活状态 => 待执行状态   执行状态 => 待执行状态）
   */
  public triggerHandlerPending(): void {
    this.setHandlerStatus(SerialHandlerStatus.PENDING)
  }

  /**
   * 触发处理器执行行为（激活状态 => 执行状态）
   */
  public triggerHandlerExecute(): void {
    this.setHandlerStatus(SerialHandlerStatus.EXECUTING)
    const taskItem = this.taskQueue.shift()

    Promise.resolve().then(() => {
      const { isFirstExecute } = this
      if (isFirstExecute) {
        this.isFirstExecute = false
        this.onBeforeFirstExecute()
      }

      let isLastExecute = false

      if (this.isHandleDataAcceptedComplete && !this.taskQueueLength) {
        isLastExecute = true
      }

      const context = {
        taskItem,
        isFirstExecute,
        isLastExecute,
      } as SerialTaskExecuteContext<O, R>

      this.execute(context)
    })
  }

  /**
   * 触发处理器成功行为（执行状态 => 成功状态）
   */
  public triggerHandlerCompleted(): void {
    this.setHandlerStatus(SerialHandlerStatus.COMPLETED)
    if (this.nextHandler) {
      this.nextHandler.handle(null)
      this.nextHandler.isHandleDataAcceptedComplete = true
    }
    this.onCompleted()
  }

  /**
   * 触发处理器销毁行为（待机状态 => 销毁状态）
   */
  public triggerHandlerFinish(): void {
    this.taskQueue = []
    this.isFirstExecute = true
    this.isHandleDataAcceptedComplete = false
    this.setHandlerStatus(SerialHandlerStatus.FINISH)
    this.onFinish()
  }

  /**
   * 触发应用被销毁行为
   */
  public triggerAppFinish(): void {
    this.executeController?.$bus.emit('_appFinish')
  }

  /**
   * 任务完成后的回调函数。
   */
  public taskCompletedCallback(): void {
    if (this.taskQueueLength) {
      this.triggerHandlerExecute()
    }
    else {
      if (this.isHandleDataAcceptedComplete) {
        this.triggerHandlerCompleted()
        if (this.isLastHandler) {
          this.triggerAppFinish()
        }
      }
      else {
        this.triggerHandlerPending()
      }
    }
  }

  public handle(original: O | null): void {
    this.taskQueue.push({
      uuid: getUuid(),
      original,
      status: SerialTaskItemStatus.PENDING,
    })

    if (!this.executePreCheck()) {
      this.triggerHandlerPending()
      return
    }

    if (this.equalHandlerStatus(SerialHandlerStatus.PENDING)) {
      this.triggerHandlerExecute()
    }
  }
}

export default SerialHandler