beervid-app-cli 0.2.3 → 0.2.5

package/skills/beervid-app-cli/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 ──── │                   │
+ │ ←── 完成 ── │                   │                   │
+```

package/skills/beervid-app-cli/docs/tts-product-cache.md

@@ -0,0 +1,256 @@
+# TTS 商品缓存建议
+
+> 本文档描述如何设计 TTS 商品的本地缓存策略，减少对 BEERVID API 的重复请求，同时保证商品数据的时效性。
+
+## 为什么需要缓存
+
+挂车发布流程需要先查商品列表再选择商品。如果每次发布都实时查询：
+- **延迟高**：商品分页查询可能需要多次 API 调用（shop + showcase，多页）
+- **重复浪费**：同一创作者的商品列表短时间内不会频繁变化
+- **配额风险**：高频调用可能触发 API 限流
+
+---
+
+## 缓存策略总览
+
+```
+┌──────────────┐     ┌────────────────┐     ┌────────────────┐
+│ 发布请求      │────→│ 本地商品缓存    │────→│ 选择商品        │
+│              │     │ (beervid_products)│   │ 进入发布流程    │
+└──────────────┘     └────────────────┘     └────────────────┘
+                            │
+                     缓存过期或为空？
+                            │
+                            ▼
+                     ┌────────────────┐
+                     │ BEERVID API    │
+                     │ products/query │
+                     │ 全量拉取刷新    │
+                     └────────────────┘
+```
+
+---
+
+## 缓存刷新策略
+
+### 推荐方案：惰性刷新 + 定期预热
+
+| 策略 | 触发时机 | 说明 |
+|------|----------|------|
+| **惰性刷新** | 用户发起发布且缓存过期 | 实时拉取商品，写入缓存后继续发布流程 |
+| **定期预热** | Cron 定时任务 | 后台定期刷新活跃账号的商品缓存 |
+| **手动刷新** | 用户主动触发 | 提供"刷新商品列表"按钮 |
+
+### 缓存过期时间建议
+
+| 场景 | 过期时间 | 理由 |
+|------|----------|------|
+| 常规使用 | 24 小时 | 商品列表变化频率低 |
+| 高频发布 | 6 小时 | 需要更新商品状态（库存、审核） |
+| 交互式选择 | 1 小时 | 用户正在浏览商品，需要较新数据 |
+
+---
+
+## 全量拉取实现
+
+商品查询需要同时查询 `shop` 和 `showcase` 两种来源，按 `id` 去重合并。
+
+以下示例默认采用 [`docs/database-schema.md`](./database-schema.md) 中包含 `deleted_at` 的软删除表结构。
+
+```typescript
+async function refreshProductCache(
+  creatorId: string,
+  pageSize: number = 20,
+  maxPages: number = 5
+): Promise<void> {
+  const allProducts = new Map<string, Product>()
+
+  for (const productType of ['shop', 'showcase'] as const) {
+    let pageToken = ''
+    let page = 0
+
+    while (page < maxPages) {
+      page++
+      const data = await openApiPost('/api/v1/open/tts/products/query', {
+        creatorUserOpenId: creatorId,
+        productType,
+        pageSize,
+        pageToken,
+      })
+
+      const groups = Array.isArray(data) ? data : [data]
+      for (const group of groups) {
+        for (const product of group.products ?? []) {
+          if (!allProducts.has(product.id)) {
+            allProducts.set(product.id, {
+              ...product,
+              images: (product.images ?? []).map(extractImageUrl),
+              source: product.source ?? productType,
+            })
+          }
+        }
+
+        // 更新分页游标
+        if (group.nextPageToken === null || group.nextPageToken === undefined) {
+          pageToken = '' // 已是最后一页
+          break
+        }
+        pageToken = group.nextPageToken
+      }
+
+      if (!pageToken) break
+    }
+  }
+
+  // 写入数据库：全量替换该创作者的商品缓存
+  await db.transaction(async (tx) => {
+    // 软删除旧数据
+    await tx.execute(
+      'UPDATE beervid_products SET deleted_at = NOW() WHERE creator_user_open_id = ? AND deleted_at IS NULL',
+      [creatorId]
+    )
+
+    // 插入新数据
+    for (const product of allProducts.values()) {
+      await tx.execute(`
+        INSERT INTO beervid_products
+          (product_id, creator_user_open_id, title, price_amount, price_currency,
+           images, sales_count, brand_name, shop_name, source,
+           review_status, inventory_status, cached_at, refreshed_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NOW(), NOW())
+        ON DUPLICATE KEY UPDATE
+          title = VALUES(title),
+          price_amount = VALUES(price_amount),
+          images = VALUES(images),
+          sales_count = VALUES(sales_count),
+          review_status = VALUES(review_status),
+          inventory_status = VALUES(inventory_status),
+          refreshed_at = NOW(),
+          deleted_at = NULL
+      `, [
+        product.id, creatorId, product.title,
+        product.price?.amount, product.price?.currency,
+        JSON.stringify(product.images), product.salesCount,
+        product.brandName, product.shopName, product.source,
+        product.reviewStatus, product.inventoryStatus,
+      ])
+    }
+  })
+}
+```
+
+---
+
+## 商品图片 URL 解析
+
+BEERVID API 返回的商品图片格式为非标准字符串：
+
+```
+{height=200, url=https://img.tiktokcdn.com/xxx.jpg, width=200}
+```
+
+**必须在入库前解析为标准 URL**，否则前端无法直接使用：
+
+```typescript
+function extractImageUrl(imageStr: string): string {
+  const match = imageStr.match(/url=([^,}]+)/)
+  return match?.[1]?.trim() ?? ''
+}
+
+// 使用
+const images = (product.images ?? []).map(extractImageUrl).filter(Boolean)
+// 结果: ["https://img.tiktokcdn.com/xxx.jpg"]
+```
+
+> **建议**：将解析后的 URL 数组以 JSON 格式存入数据库的 `images` 字段。
+
+---
+
+## 分页游标管理
+
+如果单次拉取（maxPages 限制）未能获取所有商品，需要持久化游标以支持增量拉取：
+
+```typescript
+interface CreatorCacheState {
+  creatorId: string
+  lastRefreshedAt: Date
+  shopPageToken: string | null    // null = 已拉完
+  showcasePageToken: string | null
+  totalProductsCached: number
+}
+
+// 判断是否需要刷新
+function needsRefresh(state: CreatorCacheState, ttlMs: number): boolean {
+  if (!state.lastRefreshedAt) return true
+  return Date.now() - state.lastRefreshedAt.getTime() > ttlMs
+}
+
+// 判断是否有未拉取的页
+function hasMorePages(state: CreatorCacheState): boolean {
+  return state.shopPageToken !== null || state.showcasePageToken !== null
+}
+```
+
+---
+
+## 查询缓存时的筛选
+
+发布挂车视频时，不是所有商品都可用。需要筛选：
+
+```sql
+-- 查询可发布商品（按销量降序）
+SELECT * FROM beervid_products
+WHERE creator_user_open_id = ?
+  AND deleted_at IS NULL
+  AND (review_status = 'APPROVED' OR review_status IS NULL)
+  AND (inventory_status = 'IN_STOCK' OR inventory_status IS NULL)
+ORDER BY sales_count DESC
+LIMIT 20;
+```
+
+如果你不采用软删除，可以去掉 `deleted_at IS NULL` 条件，并在刷新缓存时改成物理删除或全量覆盖。
+
+---
+
+## 定期预热设计
+
+```typescript
+// 每 6 小时执行一次
+cron.schedule('0 */6 * * *', async () => {
+  // 查找活跃账号（最近 7 天有发布行为的 TTS 账号）
+  const activeCreators = await db.query(`
+    SELECT DISTINCT a.creator_user_open_id
+    FROM beervid_accounts a
+    JOIN beervid_videos v ON v.account_id = a.id
+    WHERE a.account_type = 'TTS'
+      AND a.status = 'ACTIVE'
+      AND v.created_at > NOW() - INTERVAL 7 DAY
+  `)
+
+  for (const creator of activeCreators) {
+    try {
+      await refreshProductCache(creator.creator_user_open_id)
+      console.log(`商品缓存已刷新: ${creator.creator_user_open_id}`)
+    } catch (err) {
+      console.error(`商品缓存刷新失败: ${creator.creator_user_open_id}`, err.message)
+    }
+
+    // 防止 API 限流：每个账号间隔 2 秒
+    await new Promise(r => setTimeout(r, 2000))
+  }
+})
+```
+
+---
+
+## 缓存要点速查
+
+| 要点 | 建议 |
+|------|------|
+| 刷新触发 | 惰性（发布时检查过期）+ 定期预热（Cron 6h） |
+| 过期时间 | 常规 24h，高频发布 6h |
+| 数据源 | 同时查 shop + showcase，按 id 去重 |
+| 图片存储 | 入库前解析为标准 URL，JSON 数组格式 |
+| 可用性筛选 | review_status=APPROVED + inventory_status=IN_STOCK |
+| 分页 | 首次全量拉取，持久化游标支持增量 |
+| 并发安全 | 刷新操作加分布式锁，防止多实例重复拉取 |

package/skills/beervid-app-cli/example/express/README.md

@@ -0,0 +1,58 @@
+# Express 后端集成示例
+
+使用 Express 框架集成 BEERVID Open API 的后端服务示例，包含 OAuth 回调处理、TT/TTS 完整发布流程。
+
+## 前置条件
+
+- Node.js ≥ 20
+- BEERVID APP_KEY
+
+## 安装
+
+```bash
+cd example/express
+npm install
+```
+
+## 配置
+
+```bash
+export BEERVID_APP_KEY="your-api-key"
+# 可选
+export BEERVID_APP_BASE_URL="https://open.beervid.ai"
+export PORT=3000
+```
+
+## 运行
+
+```bash
+npx tsx server.ts
+```
+
+服务启动后访问 `http://localhost:3000`。
+
+## API 路由
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/oauth/tt` | 获取 TT OAuth URL 并重定向 |
+| GET | `/oauth/tts` | 获取 TTS OAuth URL 并重定向 |
+| GET | `/oauth/callback` | OAuth 回调处理 |
+| POST | `/api/publish/tt` | TT 完整发布流程（含后台轮询） |
+| POST | `/api/publish/tts` | TTS 完整发布流程 |
+| GET | `/api/status/:shareId` | 查询发布状态 |
+| GET | `/api/products/:creatorId` | 查询商品列表 |
+
+## 请求示例
+
+```bash
+# TT 完整发布
+curl -X POST http://localhost:3000/api/publish/tt \
+  -H "Content-Type: application/json" \
+  -d '{"businessId": "biz_123", "videoUrl": "https://cdn.beervid.ai/uploads/xxx.mp4", "caption": "My video"}'
+
+# TTS 完整发布
+curl -X POST http://localhost:3000/api/publish/tts \
+  -H "Content-Type: application/json" \
+  -d '{"creatorId": "open_user_abc", "videoFileId": "vf_abc123", "productId": "prod_789", "productTitle": "Widget"}'
+```

package/skills/beervid-app-cli/example/express/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "beervid-example-express",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "start": "tsx server.ts",
+    "dev": "tsx watch server.ts"
+  },
+  "dependencies": {
+    "express": "^5.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}