beervid-app-cli 0.2.2 → 0.2.4

package/docs/retry-and-idempotency.md

@@ -0,0 +1,295 @@
+# 失败重试与幂等建议
+
+> 本文档分析 BEERVID Open API 各接口的幂等性，提供重试策略和幂等键设计的最佳实践。
+
+## 各 API 幂等性分析
+
+> **幂等**：同一请求多次执行，结果与执行一次相同，不产生副作用。
+
+| API | 端点 | 幂等性 | 安全重试 | 说明 |
+|-----|------|--------|----------|------|
+| 获取 OAuth URL | `GET tt-url / tts-url` | ✅ 天然幂等 | ✅ | 每次返回新 URL，但不产生副作用 |
+| 查询账号信息 | `POST account/info` | ✅ 天然幂等 | ✅ | 只读查询 |
+| 获取上传凭证 | `POST upload-token/generate` | ❌ 非幂等 | ✅ | 每次返回新 token，但旧 token 仍有效 |
+| 视频上传 | `POST file-upload` | ⚠️ 条件幂等 | ⚠️ | 同文件重复上传会产生不同 fileUrl |
+| 普通视频发布 | `POST video/publish` | ❌ 非幂等 | ❌ | 重复调用可能发布多个视频 |
+| 挂车视频发布 | `POST shoppable-video/publish` | ❌ 非幂等 | ❌ | 同上 |
+| 轮询发布状态 | `POST video/status` | ✅ 天然幂等 | ✅ | 只读查询 |
+| 查询视频数据 | `POST video/query` | ✅ 天然幂等 | ✅ | 只读查询 |
+| 查询商品列表 | `POST products/query` | ✅ 天然幂等 | ✅ | 只读查询 |
+
+### 关键结论
+
+| 场景 | 风险 | 防护手段 |
+|------|------|----------|
+| **视频发布重试** | 🔴 高风险 — 重复发布产生多条视频 | 必须客户端幂等保护 |
+| **视频上传重试** | 🟡 中风险 — 产生冗余文件但不影响业务 | 建议 MD5 去重 |
+| **查询类重试** | 🟢 低风险 — 只读操作无副作用 | 可放心重试 |
+
+---
+
+## 重试策略
+
+### 推荐：指数退避 + 抖动
+
+```typescript
+interface RetryOptions {
+  maxRetries: number     // 最大重试次数
+  baseDelay: number      // 基础延迟（毫秒）
+  maxDelay: number       // 最大延迟（毫秒）
+  jitterFactor: number   // 抖动因子 (0-1)
+}
+
+const DEFAULT_RETRY: RetryOptions = {
+  maxRetries: 3,
+  baseDelay: 1000,    // 1 秒
+  maxDelay: 30000,    // 30 秒
+  jitterFactor: 0.5,  // ±50% 随机抖动
+}
+
+function calculateDelay(attempt: number, options: RetryOptions): number {
+  // 指数退避：1s → 2s → 4s → 8s → ...
+  const exponentialDelay = Math.min(
+    options.baseDelay * Math.pow(2, attempt - 1),
+    options.maxDelay
+  )
+
+  // 加入随机抖动，避免多客户端同时重试的"惊群"
+  const jitter = exponentialDelay * options.jitterFactor * (Math.random() * 2 - 1)
+  return Math.max(0, exponentialDelay + jitter)
+}
+
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = DEFAULT_RETRY,
+  shouldRetry?: (error: Error) => boolean
+): Promise<T> {
+  let lastError: Error | null = null
+
+  for (let attempt = 1; attempt <= options.maxRetries + 1; attempt++) {
+    try {
+      return await fn()
+    } catch (err) {
+      lastError = err as Error
+
+      // 判断是否可重试
+      if (attempt > options.maxRetries) break
+      if (shouldRetry && !shouldRetry(lastError)) break
+
+      const delay = calculateDelay(attempt, options)
+      console.warn(`第 ${attempt} 次失败，${(delay / 1000).toFixed(1)}s 后重试: ${lastError.message}`)
+      await new Promise(r => setTimeout(r, delay))
+    }
+  }
+
+  throw lastError
+}
+```
+
+### 可重试条件
+
+```typescript
+function isRetryableError(error: Error): boolean {
+  const message = error.message
+
+  // 网络错误：可重试
+  if (message.includes('fetch failed') || message.includes('ECONNRESET')) return true
+
+  // 5xx 服务端错误：可重试
+  if (/HTTP 5\d\d/.test(message)) return true
+
+  // 超时：可重试
+  if (message.includes('timeout') || message.includes('ETIMEDOUT')) return true
+
+  // 429 限流：可重试（通常需要更长等待）
+  if (message.includes('429') || message.includes('rate limit')) return true
+
+  // 4xx 客户端错误：通常不可重试（参数错误、权限不足等）
+  if (/HTTP 4\d\d/.test(message)) return false
+
+  // Open API 业务错误：通常不可重试
+  if (message.includes('Open API 错误')) return false
+
+  return false
+}
+```
+
+### 各场景推荐配置
+
+| 场景 | maxRetries | baseDelay | 说明 |
+|------|-----------|-----------|------|
+| 查询类（只读） | 3 | 1s | 安全重试，快速回复 |
+| 上传凭证获取 | 3 | 2s | 凭证有效期 30 分钟，有充裕时间 |
+| 视频上传 | 2 | 5s | 大文件上传耗时，间隔适当加大 |
+| 视频发布 | **0** | — | **不重试**，使用幂等机制保护 |
+| 队列消费 | 3 | 2s | 配合 acknowledge 限制总重试次数 |
+
+---
+
+## 幂等键设计
+
+### 发布幂等
+
+发布是最需要幂等保护的操作。推荐方案：
+
+```typescript
+// 生成幂等键
+function generatePublishIdempotencyKey(
+  accountId: string,
+  publishRequestId: string  // 由你方业务生成，并在重试时复用
+): string {
+  return `publish:${accountId}:${publishRequestId}`
+}
+```
+
+`publishRequestId` 应该是一次“发布意图”的稳定标识，例如：
+
+- 你方数据库里的发布草稿 ID
+- 前端首次点击发布时生成的 `clientRequestId`
+- 业务单号 / 任务 ID
+
+关键点是：**首次提交和后续重试必须使用同一个值**。不要把时间戳、当前分钟窗口这类会变化的值拼进幂等键，否则跨时间窗口重试时会失去防重效果。
+
+### 数据库层幂等
+
+```typescript
+async function publishWithIdempotency(params: PublishParams): Promise<PublishResult> {
+  const idempotencyKey = generatePublishIdempotencyKey(
+    params.accountId,
+    params.publishRequestId
+  )
+
+  // ① 检查是否已有记录
+  const existing = await db.findVideoByIdempotencyKey(idempotencyKey)
+  if (existing) {
+    console.log('检测到重复发布请求，返回已有记录')
+    return existing
+  }
+
+  // ② 先创建记录（占位）
+  const record = await db.createVideo({
+    ...params,
+    idempotencyKey,
+    publishStatus: 'PENDING',
+  })
+
+  try {
+    // ③ 调用 BEERVID API
+    const result = await openApiPost('/api/v1/open/tiktok/video/publish', {
+      businessId: params.businessId,
+      videoUrl: params.fileUrl,
+      caption: params.caption,
+    })
+
+    // ④ 更新记录
+    await db.updateVideo(record.id, {
+      shareId: result.shareId,
+      publishStatus: 'PROCESSING_DOWNLOAD',
+    })
+
+    return result
+  } catch (err) {
+    // ⑤ 发布失败，标记记录
+    await db.updateVideo(record.id, {
+      publishStatus: 'FAILED',
+      failReason: (err as Error).message,
+    })
+    throw err
+  }
+}
+```
+
+> **不要只用 `fileUrl` / `videoFileId` 当幂等键。**
+> 同一个素材在业务上可能允许被多次发布；真正应该唯一的是“这一次发布请求”。
+
+### 上传幂等（MD5 去重）
+
+```typescript
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+
+function computeFileMD5(filePath: string): string {
+  const buffer = readFileSync(filePath)
+  return createHash('md5').update(buffer).digest('hex')
+}
+
+async function uploadWithDedup(filePath: string): Promise<UploadResult> {
+  const md5 = computeFileMD5(filePath)
+
+  // 检查是否已上传过
+  const existing = await db.findUploadByMD5(md5)
+  if (existing && existing.fileUrl) {
+    console.log('文件已上传过，复用已有 URL')
+    return existing
+  }
+
+  // 执行上传
+  const result = await uploadNormalVideo(filePath)
+
+  // 记录上传结果
+  await db.saveUploadRecord({
+    md5,
+    fileUrl: result.fileUrl,
+    fileName: filePath,
+  })
+
+  return result
+}
+```
+
+---
+
+## 队列消费的幂等处理
+
+```typescript
+interface QueueMessage {
+  messageId: string     // 消息唯一 ID
+  body: unknown
+  deliveryCount: number // 投递次数
+}
+
+async function handleMessage(message: QueueMessage): Promise<void> {
+  // ① 投递次数检查
+  if (message.deliveryCount > 3) {
+    console.error(`消息 ${message.messageId} 已投递 ${message.deliveryCount} 次，放弃处理`)
+    await queue.acknowledge(message)  // 丢弃，防止无限重投
+    return
+  }
+
+  // ② 消息去重（基于 messageId）
+  const processed = await redis.get(`msg:${message.messageId}`)
+  if (processed) {
+    console.log(`消息 ${message.messageId} 已处理过，跳过`)
+    await queue.acknowledge(message)
+    return
+  }
+
+  try {
+    // ③ 业务处理
+    await processBusinessLogic(message.body)
+
+    // ④ 标记已处理
+    await redis.set(`msg:${message.messageId}`, '1', 'EX', 86400)  // 24h 过期
+    await queue.acknowledge(message)
+  } catch (err) {
+    // ⑤ 处理失败：不 acknowledge，让消息重新投递
+    console.error(`消息处理失败: ${err.message}，等待重投`)
+  }
+}
+```
+
+---
+
+## 完整策略速查表
+
+| 操作 | 安全重试 | 幂等保护 | 重试策略 | 幂等方案 |
+|------|----------|----------|----------|----------|
+| 获取 OAuth URL | ✅ | 不需要 | 3 次 / 1s 退避 | — |
+| 查询账号信息 | ✅ | 不需要 | 3 次 / 1s 退避 | — |
+| 获取上传凭证 | ✅ | 不需要 | 3 次 / 2s 退避 | — |
+| 视频上传 | ⚠️ | 建议 | 2 次 / 5s 退避 | MD5 去重 |
+| 普通视频发布 | ❌ | **必须** | 不重试 | 数据库幂等键 |
+| 挂车视频发布 | ❌ | **必须** | 不重试 | 数据库幂等键 |
+| 轮询发布状态 | ✅ | 不需要 | 3 次 / 1s 退避 | — |
+| 查询视频数据 | ✅ | 不需要 | 3 次 / 1s 退避 | — |
+| 查询商品列表 | ✅ | 不需要 | 3 次 / 1s 退避 | — |

package/docs/tt-poll-task.md

@@ -0,0 +1,239 @@
+# TT 轮询任务建议
+
+> 本文档描述普通视频（TT）发布后的状态轮询策略设计。
+> 挂车视频（TTS）发布后立即完成，**不需要轮询**。
+
+## 为什么需要轮询
+
+TT 普通视频发布后，TikTok 需要处理视频转码和分发。API 返回的 `shareId` 只是提交凭证，真正的视频 ID（`post_ids`）需要通过持续查询 `/api/v1/open/tiktok/video/status` 获取。
+
+### 状态流转
+
+```
+                        ┌─── PUBLISH_COMPLETE（post_ids 非空）→ ✅ 完成
+PROCESSING_DOWNLOAD ────┤
+                        ├─── PUBLISH_COMPLETE（post_ids 为空）→ 继续轮询
+                        │
+                        └─── FAILED（携带 reason）→ ❌ 失败
+```
+
+> **注意**：`PUBLISH_COMPLETE` 但 `post_ids` 为空是正常的中间态，必须继续轮询直到拿到有值的 `post_ids`。
+
+---
+
+## 轮询间隔建议
+
+### 推荐策略：阶梯递增间隔
+
+根据经验，视频处理通常在 10-60 秒内完成，但复杂视频可能需要数分钟。推荐使用**阶梯递增间隔**而非固定间隔：
+
+```
+前 6 次（0-30s）：每 5 秒查询一次    → 覆盖大部分快速完成的场景
+第 7-12 次（30s-90s）：每 10 秒一次   → 中等耗时视频
+第 13 次起（90s+）：每 15 秒一次      → 长耗时视频，降低 API 压力
+最大轮询次数：60 次（约 12 分钟后超时）
+```
+
+```typescript
+function getPollingInterval(pollCount: number): number {
+  if (pollCount <= 6) return 5_000       // 前 30 秒：5s
+  if (pollCount <= 12) return 10_000     // 30-90 秒：10s
+  return 15_000                          // 90 秒之后：15s
+}
+```
+
+### 其他策略对比
+
+| 策略 | 优点 | 缺点 | 适用场景 |
+|------|------|------|----------|
+| 固定间隔（5s） | 简单 | API 压力大 | 低流量场景 |
+| 阶梯递增 | 平衡响应速度和 API 压力 | 代码稍复杂 | **推荐** |
+| 指数退避 | 最省 API 调用 | 后期间隔太长，用户体验差 | 后台任务 |
+| 自适应 | 最优 | 实现复杂 | 高流量场景 |
+
+---
+
+## 三层保障机制
+
+### 第一层：用户侧主动轮询
+
+用户在界面上点击"刷新状态"，前端调用后端接口，后端调用 BEERVID API。
+
+```typescript
+// 后端接口
+app.get('/api/videos/:videoRecordId/refresh-status', async (req, res) => {
+  const record = await db.findVideoById(req.params.videoRecordId)
+  if (!record || record.publishStatus === 'PUBLISH_COMPLETE') {
+    return res.json(record)
+  }
+
+  const data = await openApiPost('/api/v1/open/tiktok/video/status', {
+    businessId: record.businessId,
+    shareId: record.shareId,
+  })
+
+  const status = data.status ?? 'UNKNOWN'
+  const postIds = data.post_ids ?? []
+
+  await db.updateVideo(record.id, {
+    publishStatus: status,
+    videoId: postIds[0] ?? null,
+    failReason: data.reason ?? null,
+    pollCount: record.pollCount + 1,
+    lastPolledAt: new Date(),
+  })
+
+  res.json({ status, videoId: postIds[0], reason: data.reason })
+})
+```
+
+### 第二层：定时任务（Cron）
+
+后台定时扫描所有"未完成"记录，批量轮询状态。
+
+```typescript
+// 每 30 秒执行一次
+cron.schedule('*/30 * * * * *', async () => {
+  // 查找所有需要轮询的记录：
+  // 1. 状态为 PROCESSING_DOWNLOAD 或 PUBLISH_COMPLETE（但无 videoId）
+  // 2. 轮询次数未超限
+  // 3. 距离上次轮询至少 5 秒
+  const pendingVideos = await db.query(`
+    SELECT * FROM beervid_videos
+    WHERE publish_status IN ('PROCESSING_DOWNLOAD', 'PUBLISH_COMPLETE')
+      AND video_id IS NULL
+      AND poll_count < 60
+      AND (last_polled_at IS NULL OR last_polled_at < NOW() - INTERVAL 5 SECOND)
+    ORDER BY created_at ASC
+    LIMIT 20
+  `)
+
+  // 逐条轮询，单条失败不影响其他
+  for (const video of pendingVideos) {
+    try {
+      await pollAndUpdateSingle(video)
+    } catch (err) {
+      console.error(`轮询失败 [shareId=${video.shareId}]:`, err.message)
+    }
+  }
+})
+
+async function pollAndUpdateSingle(video: VideoRecord): Promise<void> {
+  const data = await openApiPost('/api/v1/open/tiktok/video/status', {
+    businessId: video.businessId,
+    shareId: video.shareId,
+  })
+
+  const status = data.status ?? 'UNKNOWN'
+  const postIds = data.post_ids ?? []
+  const isComplete = status === 'PUBLISH_COMPLETE' && postIds.length > 0
+  const isFailed = status === 'FAILED'
+
+  await db.updateVideo(video.id, {
+    publishStatus: isComplete ? 'PUBLISH_COMPLETE' : isFailed ? 'FAILED' : status,
+    videoId: postIds[0] ?? null,
+    failReason: data.reason ?? null,
+    pollCount: video.pollCount + 1,
+    lastPolledAt: new Date(),
+  })
+
+  // 完成后异步触发视频数据查询
+  if (isComplete && postIds[0]) {
+    syncVideoDataAsync(video.businessId, postIds[0]).catch(() => {})
+  }
+}
+```
+
+### 第三层：异步队列（可选，高流量场景）
+
+发布后投递消息到队列，由消费者异步轮询。适用于发布量大、需要隔离轮询负载的场景。
+
+```typescript
+// 发布后投递延迟消息
+async function publishAndEnqueue(businessId: string, videoUrl: string): Promise<void> {
+  const result = await openApiPost('/api/v1/open/tiktok/video/publish', {
+    businessId,
+    videoUrl,
+  })
+
+  await db.createVideo({ businessId, shareId: result.shareId, publishStatus: 'PROCESSING_DOWNLOAD' })
+
+  // 投递延迟消息：5 秒后首次检查
+  await queue.send('video-status-poll', {
+    businessId,
+    shareId: result.shareId,
+    attempt: 1,
+  }, { delaySeconds: 5 })
+}
+
+// 队列消费者
+async function handlePollMessage(message: PollMessage): Promise<void> {
+  const { businessId, shareId, attempt } = message
+
+  if (attempt > 60) {
+    await db.updateVideo(shareId, { publishStatus: 'TIMEOUT' })
+    return  // acknowledge，不再重投
+  }
+
+  const data = await openApiPost('/api/v1/open/tiktok/video/status', { businessId, shareId })
+  const status = data.status ?? 'UNKNOWN'
+  const postIds = data.post_ids ?? []
+
+  if (status === 'FAILED' || (status === 'PUBLISH_COMPLETE' && postIds.length > 0)) {
+    // 终态，更新并结束
+    await db.updateVideo(shareId, {
+      publishStatus: status,
+      videoId: postIds[0],
+      failReason: data.reason,
+    })
+    return
+  }
+
+  // 非终态，投递下一次延迟消息
+  const delay = getPollingInterval(attempt) / 1000
+  await queue.send('video-status-poll', {
+    businessId,
+    shareId,
+    attempt: attempt + 1,
+  }, { delaySeconds: delay })
+}
+```
+
+---
+
+## 超时处理
+
+当轮询次数达到上限时：
+
+1. **标记超时**：将 `publish_status` 设为 `TIMEOUT`
+2. **不立即放弃**：后续 Cron 可以用更低频率（如每 5 分钟）继续检查 TIMEOUT 记录
+3. **通知用户**：推送通知告知"视频处理超时，系统将继续在后台检查"
+4. **人工介入入口**：提供"手动重试轮询"的按钮
+
+---
+
+## 时序图
+
+```
+用户         你的后端           BEERVID API          TikTok
+ │             │                   │                   │
+ │ 发布视频 ──→│                   │                   │
+ │             │ publish ────────→ │                   │
+ │             │ ←── shareId ──── │                   │
+ │             │                   │                   │
+ │             │ save(PROCESSING)  │                   │
+ │             │                   │                   │
+ │             │ ── 5s 后 ──       │                   │
+ │             │ poll-status ────→ │ 查询 TikTok ────→│
+ │             │ ← PROCESSING ─── │ ← 处理中 ──────── │
+ │             │                   │                   │
+ │             │ ── 5s 后 ──       │                   │
+ │             │ poll-status ────→ │ 查询 TikTok ────→│
+ │             │ ← COMPLETE ───── │ ← 发布完成 ────── │
+ │             │   (post_ids)      │                   │
+ │             │                   │                   │
+ │             │ save(COMPLETE)    │                   │
+ │             │ query-video ────→ │                   │
+ │             │ ← 播放量 etc ──── │                   │
+ │ ←── 完成 ── │                   │                   │
+```