task-95: 错误提示、重试和终态刷新的轮询状态机

2026-08-30 23:11:11 +08:00
parent 5999b10643
commit b03aaab493
2 changed files with 277 additions and 0 deletions
@@ -0,0 +1,145 @@
+/**
+ * 轮询状态机（Task 95）。
+ *
+ * 收敛轮询 UI 的深色主题无关状态语义：错误提示（error）、重试（retry）、
+ * 终态刷新（markRefreshed）的有界状态转换。
+ *
+ * 状态流：idle → start → polling →(fail)→ retrying →(fail…)→ failed
+ *                └→ succeed → done（终态；仅刷新历史，不重复计数）
+ *
+ * 有界语义：
+ * - 重试次数有上限（maxAttempts），超过后进入 failed，不再重试；
+ * - 终态幂等：重复 succeed 不覆盖状态、不重复计数；markRefreshed 只计一次；
+ * - 未 start 时 fail/succeed 抛错；isTerminal 依赖抛错时调用失败但状态
+ *   零变更，恢复后可继续。
+ */
+export interface PollingStateMachineOptions {
+  /** 重试上限，必须为正整数，达到上限后失败不再重试 */
+  maxAttempts: number
+  /** 判定终态，默认 SUCCESS/FAILED；抛错时调用失败且状态不变 */
+  isTerminal?: (status: string) => boolean
+}
+
+export interface PollingStateMachine {
+  /** idle | polling | retrying | done | failed */
+  status: string
+  /** 是否仍在轮询（polling 或 retrying） */
+  retrying: boolean
+  attempts: number
+  errorCount: number
+  /** 最近一次终态状态字符串（未终态为空串） */
+  terminalStatus: string
+  /** 最近一次错误消息 */
+  lastError: string
+  /** 是否已刷新历史（终态后至多一次） */
+  refreshed: boolean
+  refreshCount: number
+  start: () => void
+  /** 记录一次失败；未超上限进入 retrying，超上限进入 failed */
+  fail: (message: string) => void
+  /** 记录一次成功；终态后重复调用幂等 */
+  succeed: (status: string) => void
+  /** 标记终态历史已刷新；仅 done/failed 后首个调用生效 */
+  markRefreshed: () => void
+  /** 已发生的重试序号列表 */
+  retries: () => number[]
+}
+
+export function createPollingStateMachine(options: PollingStateMachineOptions): PollingStateMachine {
+  if (typeof options !== 'object' || options == null) {
+    throw new Error('options 必须是对象')
+  }
+  if (!(options.maxAttempts > 0)) {
+    throw new Error('maxAttempts 必须为正数: ' + options.maxAttempts)
+  }
+  if (!Number.isInteger(options.maxAttempts)) {
+    throw new Error('maxAttempts 必须为整数: ' + options.maxAttempts)
+  }
+  const isTerminal = options.isTerminal ?? ((status: string) => status === 'SUCCESS' || status === 'FAILED')
+  if (typeof isTerminal !== 'function') {
+    throw new Error('isTerminal 必须是函数')
+  }
+
+  let status = 'idle'
+  let attempts = 0
+  let errorCount = 0
+  let terminalStatus = ''
+  let lastError = ''
+  let refreshCount = 0
+  const retrySequence: number[] = []
+
+  function start() {
+    if (status === 'done' || status === 'failed') return
+    status = 'polling'
+    attempts = 0
+  }
+
+  function fail(message: string) {
+    if (status === 'idle') {
+      throw new Error('未开始轮询')
+    }
+    if (status === 'done' || status === 'failed') return
+    attempts += 1
+    errorCount += 1
+    lastError = message
+    if (attempts >= options.maxAttempts) {
+      status = 'failed'
+    } else {
+      retrySequence.push(attempts)
+      status = 'retrying'
+    }
+  }
+
+  function succeed(terminal: string) {
+    if (status === 'idle') {
+      throw new Error('未开始轮询')
+    }
+    if (status === 'done' || status === 'failed') return
+    if (!isTerminal(terminal)) {
+      // 非终态响应：按一次失败计入，沿用重试语义
+      fail('非终态响应: ' + terminal)
+      return
+    }
+    attempts += 1
+    terminalStatus = terminal
+    status = 'done'
+  }
+
+  function markRefreshed() {
+    if (status !== 'done' && status !== 'failed') return
+    if (refreshCount > 0) return
+    refreshCount = 1
+  }
+
+  return {
+    get status() {
+      return status
+    },
+    get retrying() {
+      return status === 'polling' || status === 'retrying'
+    },
+    get attempts() {
+      return attempts
+    },
+    get errorCount() {
+      return errorCount
+    },
+    get terminalStatus() {
+      return terminalStatus
+    },
+    get lastError() {
+      return lastError
+    },
+    get refreshed() {
+      return refreshCount > 0
+    },
+    get refreshCount() {
+      return refreshCount
+    },
+    start,
+    fail,
+    succeed,
+    markRefreshed,
+    retries: () => [...retrySequence],
+  }
+}