beervid-app-cli 0.2.3 → 0.2.5

package/skills/beervid-app-cli/docs/oauth-callback.md

@@ -0,0 +1,282 @@
+# OAuth 回调存储建议
+
+> 本文档描述接入 BEERVID OAuth 授权回调后，如何安全地处理回调参数、防止 CSRF 攻击、以及持久化账号信息。
+
+## 授权流程总览
+
+```
+┌─────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
+│  你的应用 │────→│ BEERVID  │────→│ TikTok   │────→│ 回调 URL  │
+│          │ ①  │ OAuth URL│ ②  │ 授权页面  │ ③  │ 你的服务器│
+└─────────┘     └──────────┘     └──────────┘     └──────────┘
+ 获取 URL          重定向           用户授权       收到回调参数
+```
+
+1. **获取 OAuth URL**：调用 `GET /api/v1/open/thirdparty-auth/tt-url` 或 `tts-url`
+2. **用户跳转授权**：将用户重定向到返回的 URL
+3. **接收回调**：用户授权后，TikTok 回调你的服务器
+
+> **说明**：获取到的授权链接中通常已经包含 `state` 参数。
+> 如果你需要附加自定义安全字段，做法不是新增一个 `state` 参数，而是解析现有 `state`，在其 JSON 中追加字段后再写回授权链接。
+
+---
+
+## 回调参数
+
+OAuth 授权完成后，回调 URL 会携带以下关键参数：
+
+| 账号类型 | 回调参数 | 含义 | 后续用途 |
+|----------|----------|------|----------|
+| TT | `ttAbId` | TT 账号的 businessId | 所有 TT 操作的入参 |
+| TTS | `ttsAbId` | TTS 账号的 creatorUserOpenId | 所有 TTS 操作的入参 |
+
+> **重要**：`ttAbId` 就是后续所有 TT API 的 `businessId`，`ttsAbId` 就是所有 TTS API 的 `creatorUserOpenId`。
+> 这两个值必须可靠持久化，丢失意味着需要用户重新授权。
+
+---
+
+## 获取授权链接后如何向已有 State 追加自定义字段
+
+如果获取到的授权链接里已经自带 `state`，并且它的值是一个 JSON 字符串，可以在拿到 OAuth URL 后解析这个 JSON，再把你方的安全 token 追加进去：
+
+```typescript
+function tryParseJsonObject(value: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(value) as unknown
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+function appendTokenToOAuthUrlState(
+  rawUrl: string,
+  customStateToken: string
+): string {
+  const url = new URL(rawUrl)
+  const rawState = url.searchParams.get('state')
+
+  if (!rawState) {
+    throw new Error('授权链接中缺少 state 参数')
+  }
+
+  const parsedState = tryParseJsonObject(rawState)
+  if (!parsedState) {
+    throw new Error('授权链接中的 state 不是可追加字段的 JSON 对象')
+  }
+
+  const nextState = {
+    ...parsedState,
+    customStateToken,
+  }
+
+  url.searchParams.set('state', JSON.stringify(nextState))
+  return url.toString()
+}
+
+async function getTtOAuthUrlWithState(userId: string): Promise<string> {
+  const customStateToken = generateStateToken(userId)
+  const rawUrl = await openApiGet<string>('/api/v1/open/thirdparty-auth/tt-url')
+  return appendTokenToOAuthUrlState(rawUrl, customStateToken)
+}
+
+async function getTtsOAuthUrlWithState(userId: string): Promise<string> {
+  const customStateToken = generateStateToken(userId)
+  const data = await openApiGet<{ crossBorderUrl: string }>(
+    '/api/v1/open/thirdparty-auth/tts-url'
+  )
+  return appendTokenToOAuthUrlState(data.crossBorderUrl, customStateToken)
+}
+```
+
+回调时再从 `state` JSON 中取回你追加的字段并校验：
+
+```typescript
+function parseCustomStateToken(state: string): string {
+  const parsed = tryParseJsonObject(state) as { customStateToken?: string } | null
+  if (!parsed) {
+    throw new Error('state 不是合法 JSON 对象')
+  }
+  if (!parsed.customStateToken) {
+    throw new Error('state 中缺少 customStateToken')
+  }
+  return parsed.customStateToken
+}
+```
+
+> **说明**：字段名 `customStateToken` 只是示例，你也可以改成 `token`、`nonce`、`appState` 等业务上更合适的名字。
+> 如果授权链接里的 `state` 不是 JSON 对象，就不要按这个示例直接 `JSON.parse`；应改为使用平台允许的编码方式，或采用你当前链路已有的透传机制。
+
+---
+
+## State Token 防 CSRF
+
+### 为什么需要
+
+OAuth 回调容易受到 CSRF 攻击——攻击者可以伪造回调请求，将恶意账号绑定到受害者系统。
+
+### 推荐方案：JWT 格式 State Token
+
+```typescript
+import jwt from 'jsonwebtoken'
+
+const STATE_SECRET = process.env.OAUTH_STATE_SECRET!
+
+// ① 生成 State Token（在获取 OAuth URL 时）
+function generateStateToken(userId: string): string {
+  return jwt.sign(
+    {
+      userId,        // 当前登录用户 ID
+      purpose: 'beervid-oauth',
+      nonce: crypto.randomUUID(),  // 一次性随机值
+    },
+    STATE_SECRET,
+    { expiresIn: '10m' }  // 短过期时间：10 分钟
+  )
+}
+
+// ② 验证 State Token（在回调中）
+function verifyStateToken(state: string): { userId: string; nonce: string } {
+  try {
+    const payload = jwt.verify(state, STATE_SECRET) as {
+      userId: string
+      purpose: string
+      nonce: string
+    }
+    if (payload.purpose !== 'beervid-oauth') {
+      throw new Error('Invalid state purpose')
+    }
+    return { userId: payload.userId, nonce: payload.nonce }
+  } catch {
+    throw new Error('State Token 验证失败：可能已过期或被篡改')
+  }
+}
+```
+
+### 一次性消费
+
+为防止重放攻击，State Token 应确保只使用一次：
+
+```typescript
+// 使用 Redis 记录已消费的 nonce
+const NONCE_TTL = 600  // 与 State Token 过期时间一致
+
+async function consumeStateNonce(nonce: string): Promise<boolean> {
+  // SET NX：仅当 key 不存在时设置成功
+  const result = await redis.set(`oauth:nonce:${nonce}`, '1', 'EX', NONCE_TTL, 'NX')
+  return result === 'OK'  // true = 首次使用，false = 已被消费
+}
+```
+
+---
+
+## 回调处理完整流程
+
+```typescript
+async function handleOAuthCallback(req: Request): Promise<Response> {
+  const url = new URL(req.url)
+  const state = url.searchParams.get('state')
+  const ttAbId = url.searchParams.get('ttAbId')
+  const ttsAbId = url.searchParams.get('ttsAbId')
+
+  // ① 验证 State Token
+  if (!state) {
+    return new Response('缺少 state 参数', { status: 400 })
+  }
+
+  let statePayload: { userId: string; nonce: string }
+  try {
+    statePayload = verifyStateToken(state)
+  } catch (err) {
+    return new Response('授权链接已过期，请重新发起授权', { status: 403 })
+  }
+
+  // ② 一次性消费检查
+  const isFirstUse = await consumeStateNonce(statePayload.nonce)
+  if (!isFirstUse) {
+    return new Response('该授权回调已处理过，请勿重复提交', { status: 409 })
+  }
+
+  // ③ 判断账号类型并持久化
+  if (ttAbId) {
+    await saveAccount({
+      accountType: 'TT',
+      accountId: ttAbId,
+      businessId: ttAbId,
+      appUserId: statePayload.userId,
+      status: 'ACTIVE',
+    })
+  }
+
+  if (ttsAbId) {
+    await saveAccount({
+      accountType: 'TTS',
+      accountId: ttsAbId,
+      creatorUserOpenId: ttsAbId,
+      appUserId: statePayload.userId,
+      status: 'ACTIVE',
+    })
+  }
+
+  // ④ 异步拉取账号详情（不阻塞回调响应）
+  const accountId = ttAbId || ttsAbId
+  const accountType = ttAbId ? 'TT' : 'TTS'
+
+  // 使用 fire-and-forget 或投递到消息队列
+  syncAccountInfoAsync(accountType, accountId!).catch((err) => {
+    console.error('异步同步账号信息失败（不影响授权结果）:', err.message)
+  })
+
+  // ⑤ 返回成功页面或重定向
+  return Response.redirect('/dashboard?oauth=success', 302)
+}
+```
+
+---
+
+## 异步账号信息同步
+
+授权回调只返回 `accountId`，详细信息（头像、粉丝数、用户名等）需要额外调用 `account/info` 接口获取。
+
+**为什么异步？**
+- 回调请求应快速响应，避免用户长时间等待
+- 头像同步等操作允许延迟几秒完成
+- 即使同步失败，授权本身已成功
+
+```typescript
+async function syncAccountInfoAsync(
+  accountType: 'TT' | 'TTS',
+  accountId: string
+): Promise<void> {
+  const data = await openApiPost('/api/v1/open/account/info', {
+    accountType,
+    accountId,
+  })
+
+  await updateAccount(accountId, {
+    username: data.username,
+    displayName: data.displayName,
+    sellerName: data.sellerName,
+    profileUrl: data.profileUrl,
+    followersCount: data.followersCount,
+    accessToken: data.accessToken,
+  })
+}
+```
+
+---
+
+## 安全要点速查
+
+| 要点 | 做法 |
+|------|------|
+| 防 CSRF | 使用 JWT State Token，回调时验证签名和过期时间 |
+| 防重放 | 一次性 nonce，Redis 记录已消费 |
+| 短过期 | State Token 有效期 10 分钟 |
+| 用户绑定 | State Token 中嵌入 userId，确保回调绑定到正确用户 |
+| 数据完整性 | 回调中立即持久化 accountId，异步补充详情 |
+| 失败容忍 | 异步同步失败不影响授权成功状态 |
+| HTTPS | 回调 URL 必须使用 HTTPS |

package/skills/beervid-app-cli/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 退避 | — |