beervid-app-cli 0.2.5 → 0.2.7

package/skills/beervid-app-cli/SKILL.md

@@ -83,6 +83,14 @@ interface OpenApiResponse<T> {
 - 发布挂车视频时依赖商品信息
 - 发布后通常立即完成，不走 TT 的轮询链路
 
+### TT / TTS 关联场景
+
+- TTS 账号本身不支持视频数据查询。
+- 如果同一达人既要挂车发布，又要查询视频播放/点赞/评论等数据，必须同时完成 TTS 授权和 TT 授权。
+- 官方当前没有提供 `uno_id` 之类可直接打通 TT/TTS 的关联字段。
+- 当前推荐在两边授权完成后，调用 `account/info` 拉取账号详情，并以 `username` 作为你方系统内的关联键。
+- 关联完成后，发布挂车继续使用 `creatorUserOpenId`，查询视频数据使用对应 TT 账号的 `businessId`。
+
 ## 六类核心能力
 
 只保留能力定位，详细接口说明去看引用文档：
@@ -102,7 +110,7 @@ interface OpenApiResponse<T> {
 
 ```text
 获取 TT OAuth URL
-  -> 用户授权回调得到 ttAbId
+  -> 用户授权回调，从 `state` JSON 中解析得到 ttAbId
   -> ttAbId 作为 businessId 持久化
   -> 获取上传凭证
   -> 上传普通视频，拿到 fileUrl
@@ -116,7 +124,7 @@ interface OpenApiResponse<T> {
 
 ```text
 获取 TTS OAuth URL
-  -> 用户授权回调得到 ttsAbId
+  -> 用户授权回调，从 `state` JSON 中解析得到 ttsAbId
   -> ttsAbId 作为 creatorUserOpenId 持久化
   -> 查询商品，得到 productId + productTitle
   -> 获取上传凭证
@@ -124,22 +132,39 @@ interface OpenApiResponse<T> {
   -> 发布挂车视频
 ```
 
+### 同一达人既要挂车发布又要查视频数据
+
+```text
+先授权 TTS
+  -> 得到 ttsAbId -> 持久化为 creatorUserOpenId
+  -> 调用 account/info -> 记录 TTS username
+
+再授权 TT
+  -> 得到 ttAbId -> 持久化为 businessId
+  -> 调用 account/info -> 记录 TT username
+
+用 username 在你方系统中建立 TT <-> TTS 关联
+  -> 挂车发布时使用 creatorUserOpenId
+  -> 视频查数时使用 businessId
+```
+
 ## 关键参数链路
 
 这是主文件里最值得保留的部分，因为它决定了接口如何串起来：
 
 | 参数                     | 含义                 | 产出来源                                           |
 | ------------------------ | -------------------- | -------------------------------------------------- |
-| `businessId`             | TT 账号业务 ID       | OAuth 回调参数 `ttAbId`                            |
-| `creatorUserOpenId`      | TTS 账号 OpenId      | OAuth 回调参数 `ttsAbId`                           |
+| `businessId`             | TT 账号业务 ID       | OAuth 回调 `state` JSON 中的 `ttAbId`              |
+| `creatorUserOpenId`      | TTS 账号 OpenId      | OAuth 回调 `state` JSON 中的 `ttsAbId`             |
 | `accountId`              | 平台账号 ID          | 即 `ttAbId` 或 `ttsAbId`，用于查询账号详情         |
+| `username`               | 账号用户名           | `account/info` 返回；当前推荐作为 TT/TTS 关联键    |
 | `uploadToken`            | 上传凭证             | `upload-token/generate` 返回                       |
 | `fileUrl`                | 普通上传后的视频 URL | `file-upload` 返回                                 |
 | `videoFileId` / `fileId` | TTS 视频文件 ID      | `file-upload/tts-video` 返回                       |
 | `shareId`                | TT 普通发布追踪 ID   | `tiktok/video/publish` 返回                        |
 | `videoId`                | TikTok 视频 ID       | TTS 发布直接返回；TT 从状态查询 `post_ids[0]` 获取 |
 | `productId`              | 商品 ID              | `tts/products/query` 返回的商品列表                |
-| `productTitle`           | 商品标题             | 同上，最多 29 字符，超出应先截断                   |
+| `productTitle`           | 商品标题             | 同上，最多 30 字符，超出应先截断                   |
 | `itemIds`                | 视频 ID 数组         | 来源于 `videoId`，用于查询视频数据                 |
 
 ```text
@@ -173,8 +198,9 @@ creatorUserOpenId -> upload-tts-video -> fileId -> shoppable-publish -> videoId
 ### 常见业务约束
 
 - TT 普通视频发布后需要轮询；只有 `PUBLISH_COMPLETE` 且 `post_ids` 非空才算成功完成；TTS 挂车视频通常不需要
-- 仅 TT 授权账号可查询视频数据
-- `productTitle` 最多 29 字符，超出时应提前截断
+- 仅 TT 授权账号可查询视频数据；TTS-only 账号不能查数
+- 如果同一达人既要 TTS 挂车发布又要查视频数据，必须额外授权 TT；当前推荐以 `username` 关联 TT/TTS，不能依赖官方 `uno_id`
+- `productTitle` 最多 30 字符，超出时应提前截断
 - 商品图片字段可能是特殊字符串格式，解析细节见 [`docs/tts-product-cache.md`](./docs/tts-product-cache.md)
 - 视频查询接口可能同时返回 camelCase 与 snake_case 字段，兼容细节见 [`references/api-reference.md`](./references/api-reference.md)
 
@@ -209,7 +235,7 @@ export BEERVID_APP_BASE_URL="https://open.beervid.ai"
 | `beervid upload`           | 上传视频              | `--file`, `--type tts`, `--creator-id`, `--token`                            |
 | `beervid publish`          | 发布普通或挂车视频    | `--type normal                                                               | shoppable` 加对应业务参数 |
 | `beervid poll-status`      | 轮询 TT 发布状态      | `--business-id`, `--share-id`, `--interval`, `--max-polls`                   |
-| `beervid query-video`      | 查询视频数据          | `--business-id`, `--item-ids`                                                |
+| `beervid query-video`      | 查询视频数据          | `--business-id`, `--item-ids`, `--cursor`, `--max-count`                     |
 | `beervid query-products`   | 查询 TTS 商品         | `--creator-id`, `--product-type`, `--cursor`                                 |
 | `beervid publish-tt-flow`  | 执行 TT 完整发布流程  | `--business-id`, `--file`, `--caption`                                       |
 | `beervid publish-tts-flow` | 执行 TTS 完整发布流程 | `--creator-id`, `--file`, `--interactive`, `--product-id`, `--product-title` |
@@ -247,6 +273,7 @@ beervid poll-status --business-id=biz_12345 --share-id share_abc123
 
 # 查询视频数据
 beervid query-video --business-id=biz_12345 --item-ids 7123456789012345678
+beervid query-video --business-id=biz_12345 --cursor 0 --max-count 20
 
 # 查询商品
 beervid query-products --creator-id=open_user_abc
@@ -266,6 +293,13 @@ beervid publish-tts-flow --creator-id=open_user_abc --file https://example.com/v
 
 ## 读哪份文档
 
+### 快速开始
+
+如果你是第一次接触 BEERVID Open API，从这里开始：
+
+- **5 分钟快速上手**：[`QUICKSTART.md`](./QUICKSTART.md) - 从零到发布第一个视频
+- **常见问题**：[`FAQ.md`](./FAQ.md) - 快速查找常见问题的答案
+
 ### 接口细节
 
 当你需要以下内容时，直接读取 [`references/api-reference.md`](./references/api-reference.md)：
@@ -286,9 +320,18 @@ beervid publish-tts-flow --creator-id=open_user_abc --file https://example.com/v
 - TTS 商品缓存：[`docs/tts-product-cache.md`](./docs/tts-product-cache.md)
 - 重试与幂等：[`docs/retry-and-idempotency.md`](./docs/retry-and-idempotency.md)
 
+### 运维与优化
+
+生产环境部署和优化指南：
+
+- **性能与限流**：[`docs/performance-and-limits.md`](./docs/performance-and-limits.md) - API 限流策略、并发控制、性能优化
+- **安全最佳实践**：[`docs/security-best-practices.md`](./docs/security-best-practices.md) - API Key 安全、OAuth 安全、生产环境检查清单
+- **故障排查**：[`docs/troubleshooting.md`](./docs/troubleshooting.md) - 常见错误及解决方案、调试技巧
+- **测试指南**：[`docs/testing-guide.md`](./docs/testing-guide.md) - 单元测试、集成测试、Mock 数据
+
 ### 示例工程
 
-当用户需要“可运行参考实现”时，按技术栈读取：
+当用户需要”可运行参考实现”时，按技术栈读取：
 
 - 纯脚本示例：[`example/standard/README.md`](./example/standard/README.md)
 - Express 示例：[`example/express/README.md`](./example/express/README.md)

package/skills/beervid-app-cli/docs/database-schema.md

@@ -35,6 +35,7 @@ CREATE TABLE beervid_accounts (
 
   -- 账号详情（来自 POST /api/v1/open/account/info）
   username        VARCHAR(256) DEFAULT NULL,
+  link_username   VARCHAR(256) DEFAULT NULL COMMENT '推荐的 TT/TTS 关联键（建议存归一化后的 username）',
   display_name    VARCHAR(256) DEFAULT NULL,
   seller_name     VARCHAR(256) DEFAULT NULL COMMENT 'TTS 账号的卖家名称',
   profile_url     TEXT         DEFAULT NULL COMMENT '头像 URL',
@@ -57,7 +58,8 @@ CREATE TABLE beervid_accounts (
   UNIQUE KEY uk_account (account_type, account_id),
   KEY idx_app_user (app_user_id),
   KEY idx_business_id (business_id),
-  KEY idx_creator_user_open_id (creator_user_open_id)
+  KEY idx_creator_user_open_id (creator_user_open_id),
+  KEY idx_link_username (link_username)
 );
 ```
 
@@ -68,9 +70,17 @@ CREATE TABLE beervid_accounts (
 | `account_id` | OAuth 回调参数 `ttAbId` 或 `ttsAbId` | 唯一标识，与 `account_type` 组成唯一键 |
 | `business_id` | 等同于 `ttAbId` | TT 账号的所有操作（发布、轮询、查数据）都以此为入参 |
 | `creator_user_open_id` | 等同于 `ttsAbId` | TTS 账号的所有操作（上传、发布、查商品）都以此为入参 |
+| `link_username` | `account/info` 返回的 `username` 归一化后保存 | 当前推荐用作 TT/TTS 的关联键；官方暂无 `uno_id` |
 | `access_token` | `account/info` 返回 | 按需存储，用于特殊场景 |
 | `app_user_id` | 你方系统 | 一个用户可绑定多个 TT/TTS 账号 |
 
+### TT / TTS 关联建议
+
+- 同一达人如果既授权了 TTS，又授权了 TT，建议保存为两条账号记录。
+- 官方当前没有提供 `uno_id` 这类 TT/TTS 强关联字段。
+- 推荐额外维护 `link_username`，例如保存 `LOWER(TRIM(username))` 后的值，作为当前最稳妥的软关联键。
+- 真正调用接口时不要使用 `link_username` 替代业务 ID；TT 继续使用 `business_id`，TTS 继续使用 `creator_user_open_id`。
+
 ---
 
 ## 2. 视频表 `beervid_videos`
@@ -98,7 +108,7 @@ CREATE TABLE beervid_videos (
 
   -- TTS 挂车专用
   product_id      VARCHAR(128) DEFAULT NULL COMMENT '关联商品 ID',
-  product_title   VARCHAR(64)  DEFAULT NULL COMMENT '关联商品标题（≤29字符）',
+  product_title   VARCHAR(64)  DEFAULT NULL COMMENT '关联商品标题（≤30字符）',
 
   -- 发布状态
   publish_status  VARCHAR(32)  DEFAULT 'PENDING'

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

@@ -16,16 +16,24 @@
 2. **用户跳转授权**：将用户重定向到返回的 URL
 3. **接收回调**：用户授权后，TikTok 回调你的服务器
 
-> **说明**：获取到的授权链接中通常已经包含 `state` 参数。
-> 如果你需要附加自定义安全字段，做法不是新增一个 `state` 参数，而是解析现有 `state`，在其 JSON 中追加字段后再写回授权链接。
+> **说明**：获取到的授权链接中**不一定**携带 `state` 参数。
+> - 如果链接中已经包含 `state`，它的值一定是一个 JSON 字符串。你可以解析该 JSON，在其中追加自定义字段后再写回。
+> - 如果链接中没有 `state`，而你需要透传参数（例如防 CSRF 的安全 token），应自行构造一个 JSON 对象作为 `state` 的值追加到授权链接上。
 
 ---
 
 ## 回调参数
 
-OAuth 授权完成后，回调 URL 会携带以下关键参数：
+OAuth 授权完成后，回调 URL 会携带 `state` 查询参数，其值是一个 **JSON 字符串**。业务字段包含在这个 JSON 内部：
 
-| 账号类型 | 回调参数 | 含义 | 后续用途 |
+```
+回调 URL 示例：
+https://your-app.com/callback?state={"ttAbId":"xxx","code":"yyy",...}
+```
+
+从 `state` JSON 中提取的关键字段：
+
+| 账号类型 | 字段 | 含义 | 后续用途 |
 |----------|----------|------|----------|
 | TT | `ttAbId` | TT 账号的 businessId | 所有 TT 操作的入参 |
 | TTS | `ttsAbId` | TTS 账号的 creatorUserOpenId | 所有 TTS 操作的入参 |
@@ -33,11 +41,46 @@ OAuth 授权完成后，回调 URL 会携带以下关键参数：
 > **重要**：`ttAbId` 就是后续所有 TT API 的 `businessId`，`ttsAbId` 就是所有 TTS API 的 `creatorUserOpenId`。
 > 这两个值必须可靠持久化，丢失意味着需要用户重新授权。
 
+## TT / TTS 账号关联建议
+
+如果同一达人既要做 TTS 挂车发布，又要查询视频数据，建议按下面方式建模：
+
+- TTS 授权和 TT 授权分别落成两条独立账号记录，不要混存成一条。
+- 回调阶段先持久化 `ttAbId` / `ttsAbId`，再异步调用 `account/info` 补全账号详情。
+- 官方当前没有提供 `uno_id` 这类可直接打通 TT/TTS 的稳定字段。
+- 当前推荐使用 `account/info` 返回的 `username` 作为关联键，在你方系统里建立 TT 和 TTS 的软关联。
+- 业务调用时不要把 `username` 当接口入参；挂车发布仍使用 `creatorUserOpenId`，视频查数仍使用 `businessId`。
+
+### 解析 state 中的回调字段
+
+```typescript
+interface OAuthCallbackState {
+  ttAbId?: string
+  ttsAbId?: string
+  code?: string
+  [key: string]: unknown  // 可能包含你之前追加的自定义字段
+}
+
+function parseCallbackState(stateParam: string): OAuthCallbackState {
+  try {
+    const parsed = JSON.parse(stateParam) as unknown
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as OAuthCallbackState
+    }
+    throw new Error('state 不是合法 JSON 对象')
+  } catch {
+    throw new Error('state 解析失败')
+  }
+}
+```
+
 ---
 
-## 获取授权链接后如何向已有 State 追加自定义字段
+## 获取授权链接后如何设置或追加 State
 
-如果获取到的授权链接里已经自带 `state`，并且它的值是一个 JSON 字符串，可以在拿到 OAuth URL 后解析这个 JSON，再把你方的安全 token 追加进去：
+授权链接中**可能包含也可能不包含** `state` 参数：
+- 如果已包含 `state`，其值是一个 JSON 字符串，可以解析后追加字段再写回。
+- 如果未包含 `state`，而你需要透传参数，应自行构造一个 JSON 对象设置为 `state`。
 
 ```typescript
 function tryParseJsonObject(value: string): Record<string, unknown> | null {
@@ -52,25 +95,25 @@ function tryParseJsonObject(value: string): Record<string, unknown> | null {
   }
 }
 
-function appendTokenToOAuthUrlState(
+function setOrAppendStateToken(
   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 对象')
-  }
+  let nextState: Record<string, unknown>
 
-  const nextState = {
-    ...parsedState,
-    customStateToken,
+  if (rawState) {
+    // 链接中已有 state，解析后追加字段
+    const parsedState = tryParseJsonObject(rawState)
+    if (!parsedState) {
+      throw new Error('授权链接中的 state 不是可追加字段的 JSON 对象')
+    }
+    nextState = { ...parsedState, customStateToken }
+  } else {
+    // 链接中没有 state，自行构造 JSON
+    nextState = { customStateToken }
   }
 
   url.searchParams.set('state', JSON.stringify(nextState))
@@ -80,7 +123,7 @@ function appendTokenToOAuthUrlState(
 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)
+  return setOrAppendStateToken(rawUrl, customStateToken)
 }
 
 async function getTtsOAuthUrlWithState(userId: string): Promise<string> {
@@ -88,7 +131,7 @@ async function getTtsOAuthUrlWithState(userId: string): Promise<string> {
   const data = await openApiGet<{ crossBorderUrl: string }>(
     '/api/v1/open/thirdparty-auth/tts-url'
   )
-  return appendTokenToOAuthUrlState(data.crossBorderUrl, customStateToken)
+  return setOrAppendStateToken(data.crossBorderUrl, customStateToken)
 }
 ```
 
@@ -108,7 +151,7 @@ function parseCustomStateToken(state: string): string {
 ```
 
 > **说明**：字段名 `customStateToken` 只是示例，你也可以改成 `token`、`nonce`、`appState` 等业务上更合适的名字。
-> 如果授权链接里的 `state` 不是 JSON 对象，就不要按这个示例直接 `JSON.parse`；应改为使用平台允许的编码方式，或采用你当前链路已有的透传机制。
+> 无论链接中原先是否携带 `state`，你设置的 `state` 值都应该是一个 JSON 对象。
 
 ---
 
@@ -178,35 +221,44 @@ async function consumeStateNonce(nonce: string): Promise<boolean> {
 ```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')
+  const stateParam = url.searchParams.get('state')
 
-  // ① 验证 State Token
-  if (!state) {
+  // ① 解析 state JSON，提取回调字段
+  if (!stateParam) {
     return new Response('缺少 state 参数', { status: 400 })
   }
 
-  let statePayload: { userId: string; nonce: string }
+  let stateObj: OAuthCallbackState
   try {
-    statePayload = verifyStateToken(state)
-  } catch (err) {
-    return new Response('授权链接已过期，请重新发起授权', { status: 403 })
+    stateObj = parseCallbackState(stateParam)
+  } catch {
+    return new Response('state 解析失败', { status: 400 })
   }
 
-  // ② 一次性消费检查
-  const isFirstUse = await consumeStateNonce(statePayload.nonce)
-  if (!isFirstUse) {
-    return new Response('该授权回调已处理过，请勿重复提交', { status: 409 })
+  const { ttAbId, ttsAbId } = stateObj
+
+  // ② 验证你方追加的自定义安全字段（如果有）
+  if (stateObj.customStateToken) {
+    let statePayload: { userId: string; nonce: string }
+    try {
+      statePayload = verifyStateToken(stateObj.customStateToken)
+    } 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',
     })
   }
@@ -216,21 +268,19 @@ async function handleOAuthCallback(req: Request): Promise<Response> {
       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)
 }
 ```
@@ -245,6 +295,7 @@ async function handleOAuthCallback(req: Request): Promise<Response> {
 - 回调请求应快速响应，避免用户长时间等待
 - 头像同步等操作允许延迟几秒完成
 - 即使同步失败，授权本身已成功
+- 如果要关联同一达人的 TT / TTS 账号，建议在这里同步并持久化 `username`
 
 ```typescript
 async function syncAccountInfoAsync(
@@ -258,6 +309,7 @@ async function syncAccountInfoAsync(
 
   await updateAccount(accountId, {
     username: data.username,
+    linkUsername: data.username?.trim().toLowerCase(),
     displayName: data.displayName,
     sellerName: data.sellerName,
     profileUrl: data.profileUrl,

package/skills/beervid-app-cli/docs/performance-and-limits.md

@@ -0,0 +1,153 @@
+# 性能优化与限流说明
+
+本文档只保留与 BEERVID Open API 接入直接相关的性能建议，重点关注限流、分页、轮询和批量调用。
+
+## 目录
+
+1. [限流处理](#限流处理)
+2. [分页与批量查询](#分页与批量查询)
+3. [TT 发布轮询](#tt-发布轮询)
+4. [上传与文件处理](#上传与文件处理)
+5. [实践建议](#实践建议)
+
+---
+
+## 限流处理
+
+### 1. 遇到 `429` 时做退避重试
+
+当前仓库的 `openApiPost` / `openApiGet` 在失败时会抛出 `Error.message`，所以建议按错误消息判断是否命中了限流：
+
+```typescript
+function isRateLimitError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error)
+  return message.includes('(code: 429)') || message.includes('Too Many Requests')
+}
+
+async function retryWithBackoff<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn()
+    } catch (error) {
+      if (isRateLimitError(error) && i < maxRetries - 1) {
+        const delayMs = Math.pow(2, i) * 1000
+        await sleep(delayMs)
+        continue
+      }
+      throw error
+    }
+  }
+
+  throw new Error('Max retries exceeded')
+}
+```
+
+### 2. 非幂等发布不要无脑重试
+
+- `query-products`、`query-video`、`poll-status` 这类读操作适合退避重试
+- 上传和发布动作要区分对待
+- 对于 `publish` / `publish-tt-flow` / `publish-tts-flow`，优先保证幂等控制，再决定是否补偿重试
+
+---
+
+## 分页与批量查询
+
+### 1. `query-products` 的 `pageSize` 最大为 `20`
+
+OpenAPI 已明确商品查询每页最多 `20` 条，当前 CLI 也已按这个范围校验：
+
+```bash
+beervid query-products --creator-id open_user_abc --page-size 20
+```
+
+如果需要拉更多商品，使用分页游标继续查：
+
+```bash
+beervid query-products --creator-id open_user_abc --cursor <next-cursor>
+```
+
+### 2. `query-video` 支持分页
+
+视频查询现在支持：
+
+- 不传 `itemIds`，按账号查询视频列表
+- 传 `--cursor`
+- 传 `--max-count`（10-20）
+
+```bash
+beervid query-video --business-id biz_123 --cursor 0 --max-count 20
+beervid query-video --business-id biz_123 --item-ids 7123,7124
+```
+
+### 3. 批量查询时按 20 条一批拆分
+
+```typescript
+function chunk<T>(array: T[], size: number): T[][] {
+  return Array.from(
+    { length: Math.ceil(array.length / size) },
+    (_, i) => array.slice(i * size, (i + 1) * size)
+  )
+}
+
+for (const batch of chunk(videoIds, 20)) {
+  await openApiPost('/api/v1/open/tiktok/video/query', {
+    businessId,
+    itemIds: batch,
+  })
+}
+```
+
+---
+
+## TT 发布轮询
+
+### 1. `poll-status` 只在 TT 普通发布链路里使用
+
+推荐链路：
+
+1. `publish`
+2. 拿到 `shareId`
+3. `poll-status`
+4. 当 `status === PUBLISH_COMPLETE` 且 `post_ids` 非空时，再去 `query-video`
+
+### 2. 轮询间隔不要压太短
+
+当前 CLI 默认：
+
+- `--interval 5`
+- `--max-polls 60`
+
+这套默认值已经覆盖大多数场景；如果你在服务端自己实现轮询任务，也建议保持秒级而不是毫秒级高频轮询。
+
+---
+
+## 上传与文件处理
+
+### 1. 优先上传本地文件，远程 URL 会多一次下载
+
+当前 CLI 的 `--file` 同时支持本地路径和 URL，但传 URL 时会先下载再上传：
+
+```bash
+beervid upload --file ./video.mp4
+beervid upload --file https://example.com/video.mp4
+```
+
+如果你已经在服务端拿到了文件内容，优先走本地文件/内存文件上传，减少链路耗时。
+
+### 2. 大文件场景加超时与进度监控
+
+如果你不是直接用 CLI，而是自己封装上传，至少补这两项：
+
+- 请求超时
+- 上传进度日志
+
+当前项目里如果需要上传进度，仍然推荐优先用 XHR 而不是裸 `fetch`。
+
+---
+
+## 实践建议
+
+- 把所有 Open API 调用都收口到统一 client 层，方便集中做超时、重试和日志
+- 读接口优先重试，写接口优先幂等
+- 商品查询和视频查询一律按分页参数设计，不要默认一次拉完全部数据
+- TT 轮询结果只有在 `post_ids` 真正返回后，才进入后续查数链路