beervid-app-cli 0.2.0 → 0.2.1

package/README.md

@@ -19,17 +19,25 @@ beervid --help
 git clone <repo-url> ~/.claude/skills/beervid-app-cli
 ```
 
-## 环境变量
+## 配置
 
 ```bash
+# 方式一：通过 config 命令持久化（推荐）
+beervid config --app-key "your-api-key"
+
+# 方式二：通过环境变量（优先级高于 config）
 export BEERVID_APP_KEY="your-api-key"
 export BEERVID_APP_BASE_URL="https://open.beervid.ai"  # 可选，有默认值
+
+# 查看当前配置
+beervid config --show
 ```
 
 ## 功能概览
 
 | 命令 | 功能 |
 |------|------|
+| `beervid config` | 设置/查看全局配置（APP_KEY、BASE_URL） |
 | `beervid get-oauth-url` | 获取 TT/TTS OAuth 授权链接 |
 | `beervid get-account-info` | 查询账号信息 |
 | `beervid upload` | 上传视频（支持本地文件和 URL） |
@@ -64,4 +72,4 @@ beervid publish-tts-flow --creator-id open_user_abc --file ./video.mp4 --interac
 beervid publish-tts-flow --creator-id open_user_abc --file ./video.mp4 --product-id prod_123 --product-title "Widget"
 ```
 
-详细用法见 [SKILL.md](./SKILL.md)。如需查看完整 API 参考，请在仓库源码中阅读 `references/api-reference.md`。
+详细用法见 [SKILL.md](./SKILL.md)。完整 API 参考见 [references/api-reference.md](./references/api-reference.md)。

package/SKILL.md

@@ -5,20 +5,18 @@ description: >
   不同于 BEERVID 自身应用内部的 API。当用户需要以第三方应用身份调用 BEERVID 平台接口、开发 TikTok 视频发布/上传/数据统计功能、
   处理 TT/TTS 账号授权绑定、查询商品列表、或涉及 openApiGet/openApiPost/openApiUpload 相关代码时，使用此 skill。
   包括：账号 OAuth 授权、视频上传与发布（普通/挂车）、发布状态轮询、视频数据查询、TTS 商品查询等完整业务流程。
-  即使用户只是提到"发布视频"、"绑定账号"、"查询视频数据"、"挂车发布"、"第三方应用"、"APP_KEY"等关键词，也应触发此 skill。
+  当用户在 BEERVID 项目上下文中提到"发布视频"、"绑定账号"、"查询视频数据"、"挂车发布"、"BEERVID 第三方应用"、"BEERVID_APP_KEY"等关键词时，应触发此 skill。
 ---
 
 # BEERVID 第三方应用 Open API 集成开发指南
 
-> **版本:** `0.1.0`  |  **Node.js:** `>=20.0.0`
-
 本 skill 专用于 **BEERVID 面向第三方应用开放的 Open API**，覆盖 6 大能力模块。
 
 > **与 BEERVID 内部 API 的区别：** BEERVID 平台有两套 API 体系：
 >
 > - **第三方应用 Open API（本 skill）**：面向外部开发者，通过 `BEERVID_APP_KEY` 认证，API 路径前缀 `/api/v1/open/`，用于第三方应用集成 TikTok 视频发布、账号管理等能力。
 > - **BEERVID 内部 API**：BEERVID 自身产品使用的接口，认证方式和接口设计不同，不在本 skill 覆盖范围内。
->   详细的请求/响应示例和错误码说明见 `references/api-reference.md`。
+>   详细的请求/响应示例和错误码说明见 [`references/api-reference.md`](./references/api-reference.md)。
 
 ## 环境配置
 
@@ -149,7 +147,7 @@ async function openApiUpload<T>(
 **状态流转：**
 
 ```
-PROCESSING_DOWNLOAD → PUBLISH_COMPLETE（成功，携带 post_ids）
+PROCESSING_DOWNLOAD → PUBLISH_COMPLETE（仅当携带非空 post_ids 时才算完成）
                     → FAILED（失败，携带 reason）
 ```
 
@@ -264,7 +262,7 @@ OAuth 回调
   1. 获取上传凭证      POST /api/v1/open/upload-token/generate
   2. 上传视频文件      POST /api/v1/open/file-upload（返回 fileUrl）
   3. 发布视频          POST /api/v1/open/tiktok/video/publish（返回 shareId）
-  4. 轮询发布状态      POST /api/v1/open/tiktok/video/status（直到 PUBLISH_COMPLETE）
+  4. 轮询发布状态      POST /api/v1/open/tiktok/video/status（直到 PUBLISH_COMPLETE 且返回非空 post_ids）
   5. 拉取视频数据      POST /api/v1/open/tiktok/video/query（获取播放量等）
 ```
 
@@ -285,7 +283,7 @@ OAuth 回调
   4. 发布挂车视频      POST /api/v1/open/tts/shoppable-video/publish（立即完成）
 ```
 
-详细的请求/响应示例见 → `references/api-reference.md`
+详细的请求/响应示例见 → [`references/api-reference.md`](./references/api-reference.md)
 
 ## CLI 命令
 
@@ -302,6 +300,16 @@ export BEERVID_APP_KEY="your-api-key"
 export BEERVID_APP_BASE_URL="https://open.beervid.ai"  # 可选，有默认值
 ```
 
+> **注意：** 当参数值以 `-` 开头时（如 `businessId`、`creatorUserOpenId`），必须使用 `=` 连接选项名和值，否则 CLI 会将其误判为选项标志：
+>
+> ```bash
+> # 正确
+> beervid publish-tt-flow --business-id=-0006dmtMOdKRY...
+>
+> # 错误 — 会报 "Unknown option `-0`"
+> beervid publish-tt-flow --business-id -0006dmtMOdKRY...
+> ```
+
 ### 命令一览
 
 | 命令                       | 功能                           | 核心参数                                            |
@@ -382,7 +390,7 @@ beervid publish --type shoppable \
 #### 轮询发布状态
 
 ```bash
-# 默认每 3 秒轮询一次，最多 60 次
+# 默认每 5 秒轮询一次，最多 60 次
 beervid poll-status --business-id biz_12345 --share-id share_abc123
 
 # 自定义间隔和次数

package/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "BEERVID App CLI"
+  short_description: "BEERVID third-party Open API CLI skill"
+  default_prompt: "Use $beervid-app-cli to implement or troubleshoot BEERVID third-party Open API flows for OAuth, TikTok publishing, status polling, and product queries."
+
+policy:
+  allow_implicit_invocation: true

package/dist/cli.mjs

@@ -371,12 +371,11 @@ function register4(cli2) {
 }
 
 // src/commands/poll-status.ts
-var TERMINAL_STATUSES = ["PUBLISH_COMPLETE", "FAILED"];
 function sleep(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 function register5(cli2) {
-  cli2.command("poll-status", "\u8F6E\u8BE2\u666E\u901A\u89C6\u9891\u53D1\u5E03\u72B6\u6001").option("--business-id <id>", "TT \u8D26\u53F7 businessId\uFF08\u5FC5\u586B\uFF09").option("--share-id <id>", "\u53D1\u5E03\u65F6\u8FD4\u56DE\u7684 shareId\uFF08\u5FC5\u586B\uFF09").option("--interval <sec>", "\u8F6E\u8BE2\u95F4\u9694\u79D2\u6570\uFF08\u9ED8\u8BA4 3\uFF09").option("--max-polls <n>", "\u6700\u5927\u8F6E\u8BE2\u6B21\u6570\uFF08\u9ED8\u8BA4 60\uFF09").action(
+  cli2.command("poll-status", "\u8F6E\u8BE2\u666E\u901A\u89C6\u9891\u53D1\u5E03\u72B6\u6001").option("--business-id <id>", "TT \u8D26\u53F7 businessId\uFF08\u5FC5\u586B\uFF09").option("--share-id <id>", "\u53D1\u5E03\u65F6\u8FD4\u56DE\u7684 shareId\uFF08\u5FC5\u586B\uFF09").option("--interval <sec>", "\u8F6E\u8BE2\u95F4\u9694\u79D2\u6570\uFF08\u9ED8\u8BA4 5\uFF09").option("--max-polls <n>", "\u6700\u5927\u8F6E\u8BE2\u6B21\u6570\uFF08\u9ED8\u8BA4 60\uFF09").action(
     async (options) => {
       if (!options.businessId || !options.shareId) {
         const missing = [
@@ -388,7 +387,7 @@ function register5(cli2) {
         console.error("\u7528\u6CD5: beervid poll-status --business-id <id> --share-id <id>");
         process.exit(1);
       }
-      const intervalSec = parseInt(options.interval ?? "3", 10);
+      const intervalSec = parseInt(options.interval ?? "5", 10);
       const maxPolls = parseInt(options.maxPolls ?? "60", 10);
       if (Number.isNaN(intervalSec) || intervalSec <= 0) {
         console.error("\u9519\u8BEF: --interval \u5FC5\u987B\u4E3A\u5927\u4E8E 0 \u7684\u6574\u6570");
@@ -403,35 +402,43 @@ function register5(cli2) {
         console.log(`businessId: ${options.businessId}`);
         console.log(`shareId: ${options.shareId}
 `);
+        let lastStatus = "UNKNOWN";
         for (let i = 1; i <= maxPolls; i++) {
           const data = await openApiPost("/api/v1/open/tiktok/video/status", {
             businessId: options.businessId,
             shareId: options.shareId
           });
           const status = data.status ?? data.Status ?? "UNKNOWN";
+          const postIds = data.post_ids ?? [];
+          lastStatus = status;
           console.log(`[${i}/${maxPolls}] \u72B6\u6001: ${status}`);
-          if (TERMINAL_STATUSES.includes(status)) {
+          if (status === "FAILED") {
             console.log("");
-            if (status === "PUBLISH_COMPLETE") {
-              console.log("\u53D1\u5E03\u6210\u529F!");
-              if (data.post_ids && data.post_ids.length > 0) {
-                console.log(`\u89C6\u9891 ID: ${data.post_ids[0]}`);
-                console.log(
-                  `\u63D0\u793A: \u4F7F\u7528 beervid query-video --business-id ${options.businessId} --item-ids ${data.post_ids[0]} \u67E5\u8BE2\u6570\u636E`
-                );
-              }
-            } else {
-              console.log(`\u53D1\u5E03\u5931\u8D25: ${data.reason ?? "\u672A\u77E5\u539F\u56E0"}`);
-            }
+            console.log(`\u53D1\u5E03\u5931\u8D25: ${data.reason ?? "\u672A\u77E5\u539F\u56E0"}`);
+            printResult(data);
+            process.exit(1);
+          }
+          if (status === "PUBLISH_COMPLETE" && postIds.length > 0) {
+            console.log("");
+            console.log("\u53D1\u5E03\u6210\u529F!");
+            console.log(`\u89C6\u9891 ID: ${postIds[0]}`);
+            console.log(
+              `\u63D0\u793A: \u4F7F\u7528 beervid query-video --business-id ${options.businessId} --item-ids ${postIds[0]} \u67E5\u8BE2\u6570\u636E`
+            );
             printResult(data);
-            process.exit(status === "PUBLISH_COMPLETE" ? 0 : 1);
+            process.exit(0);
           }
           if (i < maxPolls) {
             await sleep(intervalSec * 1e3);
           }
         }
-        console.error(`
-\u8D85\u8FC7\u6700\u5927\u8F6E\u8BE2\u6B21\u6570 (${maxPolls})\uFF0C\u72B6\u6001\u4ECD\u672A\u7EC8\u7ED3`);
+        if (lastStatus === "PUBLISH_COMPLETE") {
+          console.error(`
+\u8D85\u8FC7\u6700\u5927\u8F6E\u8BE2\u6B21\u6570 (${maxPolls})\uFF0C\u72B6\u6001\u4E3A PUBLISH_COMPLETE \u4F46 post_ids \u4ECD\u4E3A\u7A7A`);
+        } else {
+          console.error(`
+\u8D85\u8FC7\u6700\u5927\u8F6E\u8BE2\u6B21\u6570 (${maxPolls})\uFF0C\u4ECD\u672A\u62FF\u5230 post_ids`);
+        }
         process.exit(2);
       } catch (err) {
         rethrowIfProcessExit(err);
@@ -636,7 +643,6 @@ function register7(cli2) {
 import { createInterface } from "readline/promises";
 import { stdin as input, stdout as output } from "process";
 var MAX_PRODUCT_TITLE_LENGTH2 = 29;
-var TERMINAL_STATUSES2 = ["PUBLISH_COMPLETE", "FAILED"];
 function sleep2(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
@@ -662,18 +668,32 @@ async function publishTtsVideo(creatorId, fileId, productId, productTitle, capti
   return { publish, productTitle: normalizedTitle };
 }
 async function pollNormalVideoStatus(businessId, shareId, intervalSec, maxPolls) {
+  let lastData = null;
+  let lastStatus = "UNKNOWN";
   for (let i = 1; i <= maxPolls; i++) {
     const data = await openApiPost("/api/v1/open/tiktok/video/status", {
       businessId,
       shareId
     });
+    lastData = data;
     const status = data.status ?? data.Status ?? "UNKNOWN";
-    if (TERMINAL_STATUSES2.includes(status)) {
+    const postIds = data.post_ids ?? [];
+    lastStatus = status;
+    if (status === "FAILED") {
       return {
         pollCount: i,
         finalStatus: status,
         reason: data.reason ?? null,
-        postIds: data.post_ids ?? [],
+        postIds,
+        raw: data
+      };
+    }
+    if (status === "PUBLISH_COMPLETE" && postIds.length > 0) {
+      return {
+        pollCount: i,
+        finalStatus: status,
+        reason: data.reason ?? null,
+        postIds,
         raw: data
       };
     }
@@ -684,9 +704,9 @@ async function pollNormalVideoStatus(businessId, shareId, intervalSec, maxPolls)
   return {
     pollCount: maxPolls,
     finalStatus: "TIMEOUT",
-    reason: `\u8D85\u8FC7\u6700\u5927\u8F6E\u8BE2\u6B21\u6570 (${maxPolls})\uFF0C\u72B6\u6001\u4ECD\u672A\u7EC8\u7ED3`,
+    reason: lastStatus === "PUBLISH_COMPLETE" ? `\u8D85\u8FC7\u6700\u5927\u8F6E\u8BE2\u6B21\u6570 (${maxPolls})\uFF0C\u72B6\u6001\u4E3A PUBLISH_COMPLETE \u4F46 post_ids \u4ECD\u4E3A\u7A7A` : `\u8D85\u8FC7\u6700\u5927\u8F6E\u8BE2\u6B21\u6570 (${maxPolls})\uFF0C\u4ECD\u672A\u62FF\u5230 post_ids`,
     postIds: [],
-    raw: null
+    raw: lastData
   };
 }
 function normalizeVideoQuery(data) {
@@ -894,7 +914,7 @@ function parsePositiveInt(value, optionName, defaultValue) {
   return parsed;
 }
 function register8(cli2) {
-  cli2.command("publish-tt-flow", "\u6267\u884C TT \u5B8C\u6574\u53D1\u5E03\u6D41\u7A0B\uFF1A\u4E0A\u4F20\u3001\u53D1\u5E03\u3001\u8F6E\u8BE2\u3001\u67E5\u8BE2\u6570\u636E").option("--business-id <id>", "TT \u8D26\u53F7 businessId\uFF08\u5FC5\u586B\uFF09").option("--file <path>", "\u89C6\u9891\u6587\u4EF6\u8DEF\u5F84\u6216 URL\uFF08\u5FC5\u586B\uFF09").option("--caption <text>", "\u89C6\u9891\u63CF\u8FF0/\u6587\u6848\uFF08\u53EF\u9009\uFF09").option("--token <token>", "\u5DF2\u6709\u4E0A\u4F20\u51ED\u8BC1\uFF08\u53EF\u9009\uFF09").option("--interval <sec>", "\u8F6E\u8BE2\u95F4\u9694\u79D2\u6570\uFF08\u9ED8\u8BA4 3\uFF09").option("--max-polls <n>", "\u6700\u5927\u8F6E\u8BE2\u6B21\u6570\uFF08\u9ED8\u8BA4 60\uFF09").option("--query-interval <sec>", "\u89C6\u9891\u6570\u636E\u67E5\u8BE2\u91CD\u8BD5\u95F4\u9694\u79D2\u6570\uFF08\u9ED8\u8BA4 5\uFF09").option("--query-max-attempts <n>", "\u89C6\u9891\u6570\u636E\u67E5\u8BE2\u6700\u5927\u91CD\u8BD5\u6B21\u6570\uFF08\u9ED8\u8BA4 3\uFF09").action(
+  cli2.command("publish-tt-flow", "\u6267\u884C TT \u5B8C\u6574\u53D1\u5E03\u6D41\u7A0B\uFF1A\u4E0A\u4F20\u3001\u53D1\u5E03\u3001\u8F6E\u8BE2\u3001\u67E5\u8BE2\u6570\u636E").option("--business-id <id>", "TT \u8D26\u53F7 businessId\uFF08\u5FC5\u586B\uFF09").option("--file <path>", "\u89C6\u9891\u6587\u4EF6\u8DEF\u5F84\u6216 URL\uFF08\u5FC5\u586B\uFF09").option("--caption <text>", "\u89C6\u9891\u63CF\u8FF0/\u6587\u6848\uFF08\u53EF\u9009\uFF09").option("--token <token>", "\u5DF2\u6709\u4E0A\u4F20\u51ED\u8BC1\uFF08\u53EF\u9009\uFF09").option("--interval <sec>", "\u8F6E\u8BE2\u95F4\u9694\u79D2\u6570\uFF08\u9ED8\u8BA4 5\uFF09").option("--max-polls <n>", "\u6700\u5927\u8F6E\u8BE2\u6B21\u6570\uFF08\u9ED8\u8BA4 60\uFF09").option("--query-interval <sec>", "\u89C6\u9891\u6570\u636E\u67E5\u8BE2\u91CD\u8BD5\u95F4\u9694\u79D2\u6570\uFF08\u9ED8\u8BA4 5\uFF09").option("--query-max-attempts <n>", "\u89C6\u9891\u6570\u636E\u67E5\u8BE2\u6700\u5927\u91CD\u8BD5\u6B21\u6570\uFF08\u9ED8\u8BA4 3\uFF09").action(
     async (options) => {
       if (!options.businessId || !options.file) {
         const missing = [
@@ -908,7 +928,7 @@ function register8(cli2) {
         );
         process.exit(1);
       }
-      const intervalSec = parsePositiveInt(options.interval, "--interval", 3);
+      const intervalSec = parsePositiveInt(options.interval, "--interval", 5);
       const maxPolls = parsePositiveInt(options.maxPolls, "--max-polls", 60);
       const queryIntervalSec = parsePositiveInt(options.queryInterval, "--query-interval", 5);
       const queryMaxAttempts = parsePositiveInt(
@@ -946,11 +966,6 @@ function register8(cli2) {
           );
           query = queryResult.query;
           warnings.push(...queryResult.warnings);
-        } else if (status.finalStatus === "PUBLISH_COMPLETE") {
-          warnings.push({
-            code: "VIDEO_ID_MISSING",
-            message: "\u53D1\u5E03\u6210\u529F\uFF0C\u4F46\u72B6\u6001\u7ED3\u679C\u4E2D\u672A\u8FD4\u56DE videoId\uFF0C\u5DF2\u8DF3\u8FC7\u89C6\u9891\u6570\u636E\u67E5\u8BE2"
-          });
         }
         const result = {
           flowType: "tt",
@@ -1172,6 +1187,7 @@ function register10(cli2) {
 
 // src/cli.ts
 var cli = cac("beervid");
+var cliVersion = true ? "0.2.1" : pkg.version;
 register10(cli);
 register(cli);
 register2(cli);
@@ -1183,7 +1199,7 @@ register7(cli);
 register8(cli);
 register9(cli);
 cli.help();
-cli.version("1.0.0");
+cli.version(cliVersion);
 if (process.argv.slice(2).length === 0) {
   cli.outputHelp();
   process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beervid-app-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "BEERVID App CLI — TikTok video publish, account auth, and data query",
   "type": "module",
   "engines": {
@@ -11,6 +11,8 @@
   },
   "files": [
     "dist/",
+    "agents/",
+    "references/",
     "SKILL.md",
     "README.md"
   ],

package/references/api-reference.md

@@ -0,0 +1,605 @@
+# BEERVID 第三方应用 Open API — 请求/响应参考
+
+> 本文档包含 BEERVID 面向第三方应用开放的所有端点的详细请求参数、响应结构和错误码示例。
+> API 路径统一前缀：`/api/v1/open/`，认证方式：`X-API-KEY` 请求头。
+
+## 目录
+
+1. [账号授权](#1-账号授权)
+2. [视频上传](#2-视频上传)
+3. [视频发布](#3-视频发布)
+4. [发布状态查询](#4-发布状态查询)
+5. [视频数据查询](#5-视频数据查询)
+6. [TTS 商品查询](#6-tts-商品查询)
+7. [错误码速查表](#7-错误码速查表)
+
+---
+
+## 1. 账号授权
+
+### GET /api/v1/open/thirdparty-auth/tt-url
+
+获取 TikTok 普通账号 OAuth 授权链接。
+
+**请求：** 无参数
+
+**响应：**
+```json
+{
+  "code": 0,
+  "success": true,
+  "message": "ok",
+  "data": "https://www.tiktok.com/v2/auth/authorize?client_key=..."
+}
+```
+
+**调用示例：**
+```typescript
+const { data: url } = await openApiGet<string>('/api/v1/open/thirdparty-auth/tt-url')
+// url = "https://www.tiktok.com/v2/auth/authorize?client_key=..."
+```
+
+---
+
+### GET /api/v1/open/thirdparty-auth/tts-url
+
+获取 TikTok Shop 账号 OAuth 授权链接（跨境）。
+
+**请求：** 无参数
+
+**响应：**
+```json
+{
+  "code": 0,
+  "success": true,
+  "message": "ok",
+  "data": {
+    "crossBorderUrl": "https://services.tiktokshop.com/open/authorize?..."
+  }
+}
+```
+
+**调用示例：**
+```typescript
+const { data } = await openApiGet<{ crossBorderUrl: string }>('/api/v1/open/thirdparty-auth/tts-url')
+const url = data.crossBorderUrl
+```
+
+---
+
+### POST /api/v1/open/account/info
+
+查询已授权账号的详细信息。
+
+**请求：**
+```json
+{
+  "accountType": "TT",
+  "accountId": "7281234567890"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `accountType` | `'TT' \| 'TTS'` | 是 | 账号类型 |
+| `accountId` | `string` | 是 | 平台返回的账号 ID |
+
+**响应：**
+```json
+{
+  "code": 0,
+  "success": true,
+  "data": {
+    "accountType": "TT",
+    "accountId": "7281234567890",
+    "username": "creator_name",
+    "displayName": "Creator Display Name",
+    "sellerName": "",
+    "profileUrl": "https://p16-sign.tiktokcdn.com/...",
+    "followersCount": 15000,
+    "accessToken": "act.xxx...",
+    "ext": {}
+  }
+}
+```
+
+| 响应字段 | 类型 | 说明 |
+|---------|------|------|
+| `accountType` | `string` | 账号类型 |
+| `accountId` | `string` | 账号 ID |
+| `username` | `string` | 用户名 |
+| `displayName` | `string` | 显示名称 |
+| `sellerName` | `string` | 卖家名称（TTS 账号） |
+| `profileUrl` | `string` | 头像 URL |
+| `followersCount` | `number` | 粉丝数 |
+| `accessToken` | `string` | 访问令牌 |
+| `ext` | `Record<string, unknown>` | 扩展字段 |
+
+**调用示例：**
+```typescript
+const { data: accountInfo } = await openApiPost<AccountInfo>(
+  '/api/v1/open/account/info',
+  { accountType: 'TT', accountId: '7281234567890' }
+)
+```
+
+---
+
+## 2. 视频上传
+
+### POST /api/v1/open/upload-token/generate
+
+生成视频上传凭证。
+
+**请求：** 无 body
+
+**响应：**
+```json
+{
+  "code": 0,
+  "success": true,
+  "data": {
+    "uploadToken": "upt.xxx...",
+    "expiresIn": 1800,
+    "message": ""
+  }
+}
+```
+
+| 响应字段 | 类型 | 说明 |
+|---------|------|------|
+| `uploadToken` | `string` | 上传凭证 |
+| `expiresIn` | `number` | 过期时间（秒） |
+
+---
+
+### POST /api/v1/open/file-upload
+
+上传普通视频文件（TT 账号使用）。
+
+**请求：** `multipart/form-data`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file` | `File` | 是 | 视频文件 |
+
+**请求头：** `X-UPLOAD-TOKEN`（值为上传凭证接口返回的 `uploadToken`）
+
+**响应：**
+```json
+{
+  "code": 0,
+  "success": true,
+  "data": {
+    "fileUrl": "https://cdn.beervid.ai/uploads/xxx.mp4",
+    "fileName": "video.mp4",
+    "fileSize": 15728640,
+    "contentType": "video/mp4"
+  }
+}
+```
+
+| 响应字段 | 类型 | 说明 |
+|---------|------|------|
+| `fileUrl` | `string` | 上传后的视频 URL，用于后续发布 |
+| `fileName` | `string` | 文件名 |
+| `fileSize` | `number` | 文件大小（字节） |
+| `contentType` | `string` | MIME 类型 |
+
+---
+
+### POST /api/v1/open/file-upload/tts-video
+
+上传挂车视频文件（TTS 账号使用）。
+
+**请求：** `multipart/form-data`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file` | `File` | 是 | 视频文件 |
+
+**Query 参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `creatorUserOpenId` | `string` | 是 | TTS 账号的 OpenId |
+
+**响应：**
+```json
+{
+  "code": 0,
+  "success": true,
+  "data": {
+    "videoFileId": "vf_abc123def456",
+    "md5": "d41d8cd98f00b204e9800998ecf8427e",
+    "uploadType": "tts"
+  }
+}
+```
+
+| 响应字段 | 类型 | 说明 |
+|---------|------|------|
+| `videoFileId` | `string` | 视频文件 ID，用于后续挂车发布 |
+| `md5` | `string` | 文件 MD5 |
+| `uploadType` | `string` | 上传类型标识 |
+
+**注意：** 普通上传返回 `fileUrl`，TTS 上传返回 `videoFileId`，两者用于不同的发布端点。
+
+---
+
+## 3. 视频发布
+
+### POST /api/v1/open/tiktok/video/publish
+
+发布普通 TikTok 视频。
+
+**请求：**
+```json
+{
+  "businessId": "biz_12345",
+  "videoUrl": "https://cdn.beervid.ai/uploads/xxx.mp4",
+  "caption": "Check out this amazing video! #viral"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `businessId` | `string` | 是 | TT 账号的 businessId |
+| `videoUrl` | `string` | 是 | 上传后获得的视频 URL |
+| `caption` | `string` | 否 | 视频描述/文案 |
+
+**响应：**
+```json
+{
+  "code": 0,
+  "success": true,
+  "data": {
+    "shareId": "share_abc123",
+    "status": "PROCESSING_DOWNLOAD",
+    "message": ""
+  }
+}
+```
+
+**后续：** 使用返回的 `shareId` 轮询 `/api/v1/open/tiktok/video/status` 获取发布进度。
+
+---
+
+### POST /api/v1/open/tts/shoppable-video/publish
+
+发布挂车视频（TTS 账号，带商品链接）。
+
+**请求：**
+```json
+{
+  "creatorUserOpenId": "open_user_abc",
+  "fileId": "vf_abc123def456",
+  "title": "Amazing product review",
+  "productId": "prod_789",
+  "productTitle": "Premium Widget Pro"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `creatorUserOpenId` | `string` | 是 | TTS 账号 OpenId |
+| `fileId` | `string` | 是 | 上传返回的 `videoFileId` |
+| `title` | `string` | 否 | 视频标题 |
+| `productId` | `string` | 是 | 商品 ID |
+| `productTitle` | `string` | 是 | 商品标题（**最多 29 字符**，超出应截断） |
+
+**响应：**
+```json
+{
+  "code": 0,
+  "success": true,
+  "data": {
+    "videoId": "vid_xyz789",
+    "status": "PUBLISH_COMPLETE",
+    "message": ""
+  }
+}
+```
+
+**注意：** 挂车视频发布后立即完成（`PUBLISH_COMPLETE`），无需轮询状态。
+
+---
+
+## 4. 发布状态查询
+
+### POST /api/v1/open/tiktok/video/status
+
+查询普通视频的发布进度（仅 TT 普通视频需要，TTS 挂车视频无需轮询）。
+
+**请求：**
+```json
+{
+  "businessId": "biz_12345",
+  "shareId": "share_abc123"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `businessId` | `string` | 是 | TT 账号的 businessId |
+| `shareId` | `string` | 是 | 发布时返回的 shareId |
+
+**响应 — 处理中：**
+```json
+{
+  "code": 0,
+  "success": true,
+  "data": {
+    "status": "PROCESSING_DOWNLOAD"
+  }
+}
+```
+
+**响应 — 发布成功：**
+```json
+{
+  "code": 0,
+  "success": true,
+  "data": {
+    "status": "PUBLISH_COMPLETE",
+    "post_ids": ["7123456789012345678"]
+  }
+}
+```
+
+**响应 — 发布失败：**
+```json
+{
+  "code": 0,
+  "success": true,
+  "data": {
+    "status": "FAILED",
+    "reason": "Video format not supported"
+  }
+}
+```
+
+**状态值说明：**
+
+| 状态 | 含义 | 是否终态 |
+|------|------|---------|
+| `PROCESSING_DOWNLOAD` | 视频处理中 | 否，继续轮询 |
+| `PUBLISH_COMPLETE` | 发布接口已完成；当 `post_ids` 非空时可视为成功完成 | 条件成立时是 |
+| `FAILED` | 发布失败 | 是 |
+
+**注意：** 如果返回 `PUBLISH_COMPLETE` 但 `post_ids` 为空，应继续轮询，直到拿到 `post_ids` 或达到超时上限。
+
+**成功后：** `post_ids[0]` 即为 TikTok 上的视频 ID，可用于后续数据查询。
+
+---
+
+## 5. 视频数据查询
+
+### POST /api/v1/open/tiktok/video/query
+
+批量查询视频统计数据（播放量、点赞、评论、分享等）。
+
+**请求：**
+```json
+{
+  "businessId": "biz_12345",
+  "itemIds": ["7123456789012345678", "7123456789012345679"]
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `businessId` | `string` | 是 | TT 账号的 businessId |
+| `itemIds` | `string[]` | 是 | 视频 ID 数组 |
+
+**响应（新版格式 — camelCase）：**
+```json
+{
+  "code": 0,
+  "success": true,
+  "data": {
+    "videoList": [
+      {
+        "itemId": "7123456789012345678",
+        "thumbnailUrl": "https://p16-sign.tiktokcdn.com/...",
+        "shareUrl": "https://www.tiktok.com/@user/video/...",
+        "videoViews": 52300,
+        "likes": 1200,
+        "comments": 89,
+        "shares": 45
+      }
+    ]
+  }
+}
+```
+
+**响应（旧版格式 — snake_case）：**
+```json
+{
+  "code": 0,
+  "success": true,
+  "data": {
+    "videos": [
+      {
+        "item_id": "7123456789012345678",
+        "thumbnail_url": "https://...",
+        "share_url": "https://...",
+        "video_views": 52300,
+        "likes": 1200,
+        "comments": 89,
+        "shares": 45
+      }
+    ]
+  }
+}
+```
+
+**字段对照表：**
+
+| 数据项 | 新版字段 | 旧版字段 | 类型 |
+|--------|---------|---------|------|
+| 视频列表 | `videoList` | `videos` | `array` |
+| 视频 ID | `itemId` | `item_id` | `string` |
+| 缩略图 | `thumbnailUrl` | `thumbnail_url` | `string` |
+| 分享链接 | `shareUrl` | `share_url` | `string` |
+| 播放量 | `videoViews` | `video_views` | `number` |
+| 点赞数 | `likes` | `likes` | `number` |
+| 评论数 | `comments` | `comments` | `number` |
+| 分享数 | `shares` | `shares` | `number` |
+
+**兼容写法示例：**
+```typescript
+const list = data.videoList ?? data.videos ?? []
+const video = list[0]
+if (video) {
+  const itemId = video.itemId ?? video.item_id
+  const views = video.videoViews ?? video.video_views ?? 0
+  const thumbnailUrl = video.thumbnailUrl ?? video.thumbnail_url
+  const shareUrl = video.shareUrl ?? video.share_url
+}
+```
+
+**约束：** 仅拥有 TT 授权的账号才可查询视频数据。TTS-only 账号无此能力。
+
+---
+
+## 6. TTS 商品查询
+
+### POST /api/v1/open/tts/products/query
+
+查询创作者的店铺/橱窗商品列表，用于挂车发布时选择商品。
+
+**请求：**
+```json
+{
+  "creatorUserOpenId": "open_user_abc",
+  "productType": "shop",
+  "pageSize": 20,
+  "pageToken": ""
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `creatorUserOpenId` | `string` | 是 | TTS 账号 OpenId |
+| `productType` | `'shop' \| 'showcase'` | 是 | 商品来源类型 |
+| `pageSize` | `number` | 是 | 每页数量（建议 20） |
+| `pageToken` | `string` | 否 | 分页游标（首页留空） |
+
+**响应：**
+```json
+{
+  "code": 0,
+  "success": true,
+  "data": [
+    {
+      "productType": "shop",
+      "products": [
+        {
+          "id": "prod_123",
+          "title": "Premium Widget Pro",
+          "price": { "amount": "29.99", "currency": "USD" },
+          "images": ["{height=200, url=https://img.tiktokcdn.com/xxx.jpg, width=200}"],
+          "addedStatus": "ADDED",
+          "reviewStatus": "APPROVED",
+          "inventoryStatus": "IN_STOCK",
+          "brandName": "WidgetCo",
+          "shopName": "Widget Store",
+          "salesCount": 1500,
+          "source": "shop"
+        }
+      ],
+      "totalCount": 45,
+      "nextPageToken": "eyJ..."
+    }
+  ]
+}
+```
+
+**商品字段说明：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | `string` | 商品 ID，发布时传入 `productId` |
+| `title` | `string` | 商品标题，发布时传入 `productTitle`（注意 29 字符限制） |
+| `price` | `object` | 价格信息 |
+| `images` | `string[]` | 商品图片（特殊格式，需解析） |
+| `addedStatus` | `string` | 添加状态 |
+| `reviewStatus` | `string` | 审核状态 |
+| `inventoryStatus` | `string` | 库存状态 |
+| `salesCount` | `number` | 销量 |
+| `nextPageToken` | `string \| null` | 下一页游标（`null` 表示最后一页） |
+
+**图片 URL 提取：**
+
+商品图片返回特殊格式，需正则解析：
+```typescript
+// 原始格式: "{height=200, url=https://img.tiktokcdn.com/xxx.jpg, width=200}"
+function extractImageUrl(imageStr: string): string {
+  const match = imageStr.match(/url=([^,}]+)/)
+  return match?.[1]?.trim() ?? ''
+}
+```
+
+**分页游标处理：**
+
+建议同时查询 `shop` 和 `showcase` 两种类型，使用复合游标管理分页状态：
+```typescript
+// 编码游标
+function encodeCursor(shopToken?: string, showcaseToken?: string): string {
+  return btoa(JSON.stringify({ shopToken: shopToken ?? '', showcaseToken: showcaseToken ?? '' }))
+}
+
+// 解码游标
+function decodeCursor(cursor: string): { shopToken: string; showcaseToken: string } {
+  return JSON.parse(atob(cursor))
+}
+```
+
+**去重合并：** 同一商品可能同时出现在 shop 和 showcase 中，应按 `id` 去重。
+
+---
+
+## 7. 错误码速查表
+
+### Open API 层
+
+所有端点共用的响应 `code` 字段：
+
+| code | 含义 | 处理方式 |
+|------|------|---------|
+| `0` | 成功 | 正常处理 `data` 字段 |
+| 非零 | 业务错误 | 读取 `message` 获取错误详情 |
+
+### 常见业务错误场景
+
+| 场景 | 建议 HTTP 状态码 | 建议 code | 示例 message |
+|------|-----------------|-----------|-------------|
+| 缺少必填参数 | 400 | 400 | `"accountId 为必填项"` |
+| 参数值非法 | 400 | 400 | `"publishType 非法"` |
+| 账号未授权 | 403 | 403 | `"该账号未授权普通视频发布"` |
+| OAuth 授权过期 | 403 | 403 | `"授权已过期或无效，请重新授权"` |
+| State Token 用户不匹配 | 403 | 403 | `"授权用户不匹配，请重新登录后授权"` |
+| 资源不存在 | 404 | 404 | `"TikTok 账号不存在"` |
+| Open API 调用失败 | 500 | 500 | `"Open API 错误 [/api/v1/open/xxx]: Bad request (code: 40001)"` |
+| 上传凭证获取失败 | 500 | 500 | `"获取上传凭证失败"` |
+| API 成功但本地存储失败 | 200 | 200 | `"视频已提交至 TikTok，但本地记录保存失败"`（附 `dbSaved: false`） |
+
+### 客户端上传错误
+
+| 错误消息 | 原因 | 处理建议 |
+|---------|------|---------|
+| `上传失败，响应解析失败` | 服务端返回非 JSON 内容 | 检查上传 URL 和凭证是否正确 |
+| `上传失败，状态码: {status}` | HTTP 非 2xx | 检查认证头和文件格式 |
+| `上传失败` | API 返回 `code !== 0` | 查看 `message` 获取具体原因 |
+| `上传成功但未返回可用结果` | 响应中既无 `fileUrl` 也无 `videoFileId` | API 异常，需排查 |
+| `上传失败，网络错误` | 网络连接中断 | 提示用户检查网络后重试 |
+| `Upload aborted` | 用户取消或页面卸载 | 正常行为，无需处理 |
+
+### 队列重试建议
+
+| 参数 | 建议值 | 说明 |
+|------|--------|------|
+| 最大重试次数 | 3 | 超过后停止重试并记录日志 |
+| 重试间隔 | 2 秒 | 固定间隔或指数退避均可 |
+| 超限处理 | acknowledge | 防止消息无限重投 |