beervid-app-cli 0.2.3 → 0.2.4

package/dist/cli.mjs

@@ -151,6 +151,28 @@ function rethrowIfProcessExit(error) {
     throw error;
   }
 }
+function getRawOptionValues(rawArgs, optionName) {
+  const values = [];
+  const prefix = `${optionName}=`;
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if (arg === optionName) {
+      const next = rawArgs[i + 1];
+      if (typeof next === "string" && !next.startsWith("-")) {
+        values.push(next);
+        i++;
+      }
+      continue;
+    }
+    if (arg.startsWith(prefix)) {
+      values.push(arg.slice(prefix.length));
+    }
+  }
+  return values;
+}
+function getRawOptionValue(rawArgs, optionName) {
+  return getRawOptionValues(rawArgs, optionName).at(-1);
+}
 
 // src/commands/oauth.ts
 function register(cli2) {
@@ -186,8 +208,9 @@ function register(cli2) {
 // src/commands/account.ts
 function register2(cli2) {
   cli2.command("get-account-info", "\u67E5\u8BE2 TikTok \u8D26\u53F7\u4FE1\u606F").option("--type <type>", "\u8D26\u53F7\u7C7B\u578B: TT \u6216 TTS").option("--account-id <id>", "\u8D26\u53F7 ID").action(async (options) => {
-    if (!options.type || !options.accountId) {
-      const missing = [!options.type && "--type", !options.accountId && "--account-id"].filter(Boolean).join(", ");
+    const accountId = getRawOptionValue(cli2.rawArgs, "--account-id");
+    if (!options.type || !accountId) {
+      const missing = [!options.type && "--type", !accountId && "--account-id"].filter(Boolean).join(", ");
       console.error(`\u7F3A\u5C11\u5FC5\u586B\u53C2\u6570: ${missing}
 `);
       console.error("\u7528\u6CD5: beervid get-account-info --type <TT|TTS> --account-id <id>");
@@ -201,7 +224,7 @@ function register2(cli2) {
     try {
       const data = await openApiPost("/api/v1/open/account/info", {
         accountType,
-        accountId: options.accountId
+        accountId
       });
       printResult(data);
     } catch (err) {
@@ -256,19 +279,20 @@ function register3(cli2) {
         process.exit(1);
       }
       const uploadType = (options.type ?? "normal").toLowerCase();
+      const creatorId = getRawOptionValue(cli2.rawArgs, "--creator-id");
       if (!VALID_UPLOAD_TYPES.includes(uploadType)) {
         console.error("\u9519\u8BEF: --type \u5FC5\u987B\u4E3A normal \u6216 tts");
         process.exit(1);
       }
-      if (uploadType === "tts" && !options.creatorId) {
+      if (uploadType === "tts" && !creatorId) {
         console.error("\u9519\u8BEF: TTS \u4E0A\u4F20\u6A21\u5F0F\u9700\u8981 --creator-id \u53C2\u6570");
         process.exit(1);
       }
       try {
         let data;
         if (uploadType === "tts") {
-          console.log(`TTS \u4E0A\u4F20\u6A21\u5F0F\uFF0CcreatorUserOpenId: ${options.creatorId}`);
-          data = await uploadTtsVideo(options.file, options.creatorId, options.token);
+          console.log(`TTS \u4E0A\u4F20\u6A21\u5F0F\uFF0CcreatorUserOpenId: ${creatorId}`);
+          data = await uploadTtsVideo(options.file, creatorId, options.token);
         } else {
           console.log("\u666E\u901A\u4E0A\u4F20\u6A21\u5F0F");
           data = await uploadNormalVideo(options.file, options.token);
@@ -293,6 +317,10 @@ function register4(cli2) {
   }).option("--caption <text>", "\u89C6\u9891\u63CF\u8FF0/\u6587\u6848\uFF08\u53EF\u9009\uFF09").action(
     async (options) => {
       const publishType = (options.type ?? "normal").toLowerCase();
+      const businessId = getRawOptionValue(cli2.rawArgs, "--business-id");
+      const creatorId = getRawOptionValue(cli2.rawArgs, "--creator-id");
+      const fileId = getRawOptionValue(cli2.rawArgs, "--file-id");
+      const productId = getRawOptionValue(cli2.rawArgs, "--product-id");
       if (!VALID_PUBLISH_TYPES.includes(publishType)) {
         console.error("\u9519\u8BEF: --type \u5FC5\u987B\u4E3A normal \u6216 shoppable");
         process.exit(1);
@@ -301,9 +329,9 @@ function register4(cli2) {
         let data;
         if (publishType === "shoppable") {
           const missing = [
-            !options.creatorId && "--creator-id",
-            !options.fileId && "--file-id",
-            !options.productId && "--product-id",
+            !creatorId && "--creator-id",
+            !fileId && "--file-id",
+            !productId && "--product-id",
             !options.productTitle && "--product-title"
           ].filter(Boolean);
           if (missing.length > 0) {
@@ -325,17 +353,17 @@ function register4(cli2) {
           data = await openApiPost(
             "/api/v1/open/tts/shoppable-video/publish",
             {
-              creatorUserOpenId: options.creatorId,
-              fileId: options.fileId,
+              creatorUserOpenId: creatorId,
+              fileId,
               title: options.caption ?? "",
-              productId: options.productId,
+              productId,
               productTitle
             }
           );
           console.log("\n\u53D1\u5E03\u6210\u529F\uFF08\u6302\u8F66\u89C6\u9891\u7ACB\u5373\u5B8C\u6210\uFF09:");
         } else {
           const missing = [
-            !options.businessId && "--business-id",
+            !businessId && "--business-id",
             !options.videoUrl && "--video-url"
           ].filter(Boolean);
           if (missing.length > 0) {
@@ -350,14 +378,14 @@ function register4(cli2) {
           data = await openApiPost(
             "/api/v1/open/tiktok/video/publish",
             {
-              businessId: options.businessId,
+              businessId,
               videoUrl: options.videoUrl,
               caption: options.caption ?? ""
             }
           );
           console.log("\n\u53D1\u5E03\u5DF2\u63D0\u4EA4\uFF08\u9700\u8F6E\u8BE2\u72B6\u6001\uFF09:");
           console.log(
-            `\u63D0\u793A: \u4F7F\u7528 beervid poll-status --business-id ${options.businessId} --share-id ${data.shareId} \u8F6E\u8BE2\u8FDB\u5EA6`
+            `\u63D0\u793A: \u4F7F\u7528 beervid poll-status --business-id ${businessId} --share-id ${data.shareId} \u8F6E\u8BE2\u8FDB\u5EA6`
           );
         }
         printResult(data);
@@ -377,10 +405,12 @@ function sleep(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 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 businessId = getRawOptionValue(cli2.rawArgs, "--business-id");
+      const shareId = getRawOptionValue(cli2.rawArgs, "--share-id");
+      if (!businessId || !shareId) {
         const missing = [
-          !options.businessId && "--business-id",
-          !options.shareId && "--share-id"
+          !businessId && "--business-id",
+          !shareId && "--share-id"
         ].filter(Boolean);
         console.error(`\u7F3A\u5C11\u5FC5\u586B\u53C2\u6570: ${missing.join(", ")}
 `);
@@ -399,14 +429,14 @@ function register5(cli2) {
       }
       try {
         console.log(`\u5F00\u59CB\u8F6E\u8BE2\u53D1\u5E03\u72B6\u6001 (\u95F4\u9694 ${intervalSec}s, \u6700\u591A ${maxPolls} \u6B21)`);
-        console.log(`businessId: ${options.businessId}`);
-        console.log(`shareId: ${options.shareId}
+        console.log(`businessId: ${businessId}`);
+        console.log(`shareId: ${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
+            businessId,
+            shareId
           });
           const status = data.status ?? data.Status ?? "UNKNOWN";
           const postIds = data.post_ids ?? [];
@@ -423,7 +453,7 @@ function register5(cli2) {
             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`
+              `\u63D0\u793A: \u4F7F\u7528 beervid query-video --business-id ${businessId} --item-ids ${postIds[0]} \u67E5\u8BE2\u6570\u636E`
             );
             printResult(data);
             process.exit(0);
@@ -452,11 +482,13 @@ function register5(cli2) {
 // src/commands/query-video.ts
 function register6(cli2) {
   cli2.command("query-video", "\u67E5\u8BE2\u89C6\u9891\u7EDF\u8BA1\u6570\u636E").option("--business-id <id>", "TT \u8D26\u53F7 businessId\uFF08\u5FC5\u586B\uFF09").option("--item-ids <ids>", "\u89C6\u9891 ID\uFF0C\u652F\u6301\u91CD\u590D\u4F20\u53C2\u6216\u9017\u53F7\u5206\u9694\uFF08\u5FC5\u586B\uFF09").action(
-    async (options) => {
-      if (!options.businessId || !options.itemIds) {
+    async () => {
+      const businessId = getRawOptionValue(cli2.rawArgs, "--business-id");
+      const rawItemIdArgs = getRawOptionValues(cli2.rawArgs, "--item-ids");
+      if (!businessId || rawItemIdArgs.length === 0) {
         const missing = [
-          !options.businessId && "--business-id",
-          !options.itemIds && "--item-ids"
+          !businessId && "--business-id",
+          rawItemIdArgs.length === 0 && "--item-ids"
         ].filter(Boolean);
         console.error(`\u7F3A\u5C11\u5FC5\u586B\u53C2\u6570: ${missing.join(", ")}
 `);
@@ -465,7 +497,7 @@ function register6(cli2) {
         );
         process.exit(1);
       }
-      const itemIds = (Array.isArray(options.itemIds) ? options.itemIds : [options.itemIds]).flatMap((value) => value.split(",")).map((id) => id.trim()).filter(Boolean);
+      const itemIds = rawItemIdArgs.flatMap((value) => value.split(",")).map((id) => id.trim()).filter(Boolean);
       if (itemIds.length === 0) {
         console.error("\u9519\u8BEF: --item-ids \u4E0D\u80FD\u4E3A\u7A7A");
         process.exit(1);
@@ -474,7 +506,7 @@ function register6(cli2) {
         console.log(`\u67E5\u8BE2 ${itemIds.length} \u4E2A\u89C6\u9891\u7684\u6570\u636E...
 `);
         const data = await openApiPost("/api/v1/open/tiktok/video/query", {
-          businessId: options.businessId,
+          businessId,
           itemIds
         });
         const list = data.videoList ?? data.videos ?? [];
@@ -771,12 +803,12 @@ var VALID_PRODUCT_TYPES = ["shop", "showcase", "all"];
 function register7(cli2) {
   cli2.command("query-products", "\u67E5\u8BE2 TTS \u5546\u54C1\u5217\u8868").option("--creator-id <id>", "TTS \u8D26\u53F7 creatorUserOpenId\uFF08\u5FC5\u586B\uFF09").option("--product-type <type>", "\u5546\u54C1\u6765\u6E90: shop / showcase / all\uFF08\u9ED8\u8BA4 all\uFF09").option("--page-size <n>", "\u6BCF\u9875\u6570\u91CF\uFF08\u9ED8\u8BA4 20\uFF09").option("--cursor <cursor>", "\u5206\u9875\u6E38\u6807\uFF08\u9996\u9875\u4E0D\u4F20\uFF09").action(
     async (options) => {
-      if (!options.creatorId) {
+      const creatorId = getRawOptionValue(cli2.rawArgs, "--creator-id");
+      if (!creatorId) {
         console.error("\u7F3A\u5C11\u5FC5\u586B\u53C2\u6570: --creator-id\n");
         console.error("\u7528\u6CD5: beervid query-products --creator-id <id>");
         process.exit(1);
       }
-      const creatorId = options.creatorId;
       const productType = (options.productType ?? "all").toLowerCase();
       const pageSize = parseInt(options.pageSize ?? "20", 10);
       const cursor = options.cursor ?? "";
@@ -845,9 +877,10 @@ function parsePositiveInt(value, optionName, defaultValue) {
 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 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 businessId = getRawOptionValue(cli2.rawArgs, "--business-id");
+      if (!businessId || !options.file) {
         const missing = [
-          !options.businessId && "--business-id",
+          !businessId && "--business-id",
           !options.file && "--file"
         ].filter(Boolean);
         console.error(`\u7F3A\u5C11\u5FC5\u586B\u53C2\u6570: ${missing.join(", ")}
@@ -870,28 +903,14 @@ function register8(cli2) {
         console.log("1/4 \u6B63\u5728\u4E0A\u4F20\u89C6\u9891...");
         const upload = await uploadNormalVideo(options.file, options.token);
         console.log("2/4 \u6B63\u5728\u53D1\u5E03\u89C6\u9891...");
-        const publish = await publishNormalVideo(
-          options.businessId,
-          upload.fileUrl,
-          options.caption
-        );
+        const publish = await publishNormalVideo(businessId, upload.fileUrl, options.caption);
         console.log("3/4 \u6B63\u5728\u8F6E\u8BE2\u53D1\u5E03\u72B6\u6001...");
-        const status = await pollNormalVideoStatus(
-          options.businessId,
-          publish.shareId,
-          intervalSec,
-          maxPolls
-        );
+        const status = await pollNormalVideoStatus(businessId, publish.shareId, intervalSec, maxPolls);
         const videoId = status.postIds[0] ?? null;
         let query = null;
         if (status.finalStatus === "PUBLISH_COMPLETE" && videoId) {
           console.log("4/4 \u6B63\u5728\u67E5\u8BE2\u89C6\u9891\u6570\u636E...");
-          const queryResult = await queryVideoWithRetry(
-            options.businessId,
-            videoId,
-            queryIntervalSec,
-            queryMaxAttempts
-          );
+          const queryResult = await queryVideoWithRetry(businessId, videoId, queryIntervalSec, queryMaxAttempts);
           query = queryResult.query;
           for (const warning of queryResult.warnings) {
             console.warn(warning.message);
@@ -952,9 +971,11 @@ function buildManualProduct(productId, productTitle, matchedProduct) {
 function register9(cli2) {
   cli2.command("publish-tts-flow", "\u6267\u884C TTS \u5B8C\u6574\u53D1\u5E03\u6D41\u7A0B\uFF1A\u67E5\u5546\u54C1\u3001\u9009\u5546\u54C1\u3001\u4E0A\u4F20\u3001\u53D1\u5E03").option("--creator-id <id>", "TTS \u8D26\u53F7 creatorUserOpenId\uFF08\u5FC5\u586B\uFF09").option("--file <path>", "\u89C6\u9891\u6587\u4EF6\u8DEF\u5F84\u6216 URL\uFF08\u5FC5\u586B\uFF09").option("--caption <text>", "\u89C6\u9891\u6807\u9898/\u6587\u6848\uFF08\u53EF\u9009\uFF09").option("--token <token>", "\u5DF2\u6709\u4E0A\u4F20\u51ED\u8BC1\uFF08\u53EF\u9009\uFF09").option("--product-type <type>", "\u5546\u54C1\u6765\u6E90: shop / showcase / all\uFF08\u9ED8\u8BA4 all\uFF09").option("--page-size <n>", "\u6BCF\u9875\u6570\u91CF\uFF08\u9ED8\u8BA4 20\uFF09").option("--max-product-pages <n>", "\u5546\u54C1\u626B\u63CF\u6700\u5927\u9875\u6570\uFF08\u9ED8\u8BA4 5\uFF09").option("--product-id <id>", "\u624B\u52A8\u6307\u5B9A\u5546\u54C1 ID").option("--product-title <title>", "\u624B\u52A8\u6307\u5B9A\u5546\u54C1\u6807\u9898").option("--interactive", "\u4EA4\u4E92\u5F0F\u9009\u62E9\u5546\u54C1").action(
     async (options) => {
-      if (!options.creatorId || !options.file) {
+      const creatorId = getRawOptionValue(cli2.rawArgs, "--creator-id");
+      const productId = getRawOptionValue(cli2.rawArgs, "--product-id");
+      if (!creatorId || !options.file) {
         const missing = [
-          !options.creatorId && "--creator-id",
+          !creatorId && "--creator-id",
           !options.file && "--file"
         ].filter(Boolean);
         console.error(`\u7F3A\u5C11\u5FC5\u586B\u53C2\u6570: ${missing.join(", ")}
@@ -969,11 +990,11 @@ function register9(cli2) {
         console.error("\u9519\u8BEF: --product-type \u5FC5\u987B\u4E3A shop\u3001showcase \u6216 all");
         process.exit(1);
       }
-      if (options.productId && options.interactive) {
+      if (productId && options.interactive) {
         console.error("\u9519\u8BEF: --product-id \u4E0E --interactive \u4E0D\u80FD\u540C\u65F6\u4F7F\u7528");
         process.exit(1);
       }
-      if (options.productTitle && !options.productId) {
+      if (options.productTitle && !productId) {
         console.error("\u9519\u8BEF: --product-title \u9700\u8981\u4E0E --product-id \u4E00\u8D77\u4F7F\u7528");
         process.exit(1);
       }
@@ -987,13 +1008,13 @@ function register9(cli2) {
         console.log("\u5F00\u59CB\u6267\u884C TTS \u5B8C\u6574\u53D1\u5E03\u6D41\u7A0B...");
         let selectedProduct;
         let queriedProducts = null;
-        if (options.productId && options.productTitle) {
+        if (productId && options.productTitle) {
           console.log("1/4 \u5DF2\u624B\u52A8\u6307\u5B9A\u5546\u54C1\uFF0C\u8DF3\u8FC7\u5546\u54C1\u67E5\u8BE2...");
-          selectedProduct = buildManualProduct(options.productId, options.productTitle);
+          selectedProduct = buildManualProduct(productId, options.productTitle);
         } else {
           console.log("1/4 \u6B63\u5728\u67E5\u8BE2\u5546\u54C1\u5217\u8868...");
           const productPool = await fetchProductPool(
-            options.creatorId,
+            creatorId,
             productType,
             pageSize,
             maxProductPages
@@ -1007,10 +1028,8 @@ function register9(cli2) {
               `\u4EE5\u4E0B\u5546\u54C1\u6E90\u8BF7\u6C42\u5931\u8D25: ${productPool.summary.failedSources.join(", ")}\uFF0C\u5546\u54C1\u6C60\u53EF\u80FD\u4E0D\u5B8C\u6574`
             );
           }
-          if (options.productId) {
-            const matchedProduct = productPool.products.find(
-              (product) => product.id === options.productId
-            );
+          if (productId) {
+            const matchedProduct = productPool.products.find((product) => product.id === productId);
             const resolvedTitle = matchedProduct?.title;
             if (!resolvedTitle) {
               console.error(
@@ -1018,7 +1037,7 @@ function register9(cli2) {
               );
               process.exit(1);
             }
-            selectedProduct = buildManualProduct(options.productId, resolvedTitle, matchedProduct);
+            selectedProduct = buildManualProduct(productId, resolvedTitle, matchedProduct);
           } else if (options.interactive) {
             if (productPool.products.length === 0) {
               console.error("TTS \u5B8C\u6574\u53D1\u5E03\u6D41\u7A0B\u5931\u8D25: \u5F53\u524D\u5546\u54C1\u6C60\u4E3A\u7A7A\uFF0C\u65E0\u6CD5\u9009\u62E9\u5546\u54C1");
@@ -1043,10 +1062,10 @@ function register9(cli2) {
           }
         }
         console.log("3/4 \u6B63\u5728\u4E0A\u4F20\u6302\u8F66\u89C6\u9891...");
-        const upload = await uploadTtsVideo(options.file, options.creatorId, options.token);
+        const upload = await uploadTtsVideo(options.file, creatorId, options.token);
         console.log("4/4 \u6B63\u5728\u53D1\u5E03\u6302\u8F66\u89C6\u9891...");
         const publishResult = await publishTtsVideo(
-          options.creatorId,
+          creatorId,
           upload.videoFileId,
           selectedProduct.id,
           selectedProduct.title,
@@ -1111,7 +1130,7 @@ function register10(cli2) {
 
 // src/cli.ts
 var cli = cac("beervid");
-var cliVersion = true ? "0.2.3" : pkg.version;
+var cliVersion = true ? "0.2.4" : pkg.version;
 register10(cli);
 register(cli);
 register2(cli);

package/docs/database-schema.md

@@ -0,0 +1,231 @@
+# 数据表字段建议
+
+> 本文档为接入 BEERVID 第三方应用 Open API 的后端系统提供数据库表结构设计建议。
+> 以 SQL DDL 呈现，兼顾 MySQL 和 PostgreSQL 语法。
+
+## 总览
+
+接入 BEERVID Open API 通常需要持久化以下实体：
+
+| 表名 | 作用 | 关联 API |
+|------|------|----------|
+| `beervid_accounts` | 存储 TT/TTS 授权账号信息 | OAuth 回调、`account/info` |
+| `beervid_videos` | 视频发布记录与状态追踪 | `publish`、`poll-status`、`query-video` |
+| `beervid_products` | TTS 商品缓存 | `products/query` |
+
+---
+
+## 1. 账号表 `beervid_accounts`
+
+存储通过 OAuth 授权绑定的 TT/TTS 账号。
+
+```sql
+CREATE TABLE beervid_accounts (
+  id              BIGINT PRIMARY KEY AUTO_INCREMENT,
+
+  -- 账号标识
+  account_type    VARCHAR(8)   NOT NULL COMMENT 'TT 或 TTS',
+  account_id      VARCHAR(128) NOT NULL COMMENT 'OAuth 回调返回的 ttAbId 或 ttsAbId',
+
+  -- TT 账号专用：即 businessId，所有 TT 操作的入参
+  business_id     VARCHAR(128) DEFAULT NULL COMMENT 'TT 业务 ID（= ttAbId）',
+
+  -- TTS 账号专用：即 creatorUserOpenId，所有 TTS 操作的入参
+  creator_user_open_id VARCHAR(128) DEFAULT NULL COMMENT 'TTS 用户 OpenId（= ttsAbId）',
+
+  -- 账号详情（来自 POST /api/v1/open/account/info）
+  username        VARCHAR(256) DEFAULT NULL,
+  display_name    VARCHAR(256) DEFAULT NULL,
+  seller_name     VARCHAR(256) DEFAULT NULL COMMENT 'TTS 账号的卖家名称',
+  profile_url     TEXT         DEFAULT NULL COMMENT '头像 URL',
+  followers_count INT          DEFAULT 0,
+  access_token    VARCHAR(512) DEFAULT NULL COMMENT '访问令牌',
+
+  -- 业务归属
+  app_user_id     BIGINT       DEFAULT NULL COMMENT '你方系统的用户 ID（多对一关系）',
+
+  -- 状态
+  status          VARCHAR(32)  DEFAULT 'ACTIVE' COMMENT 'ACTIVE / EXPIRED / REVOKED',
+
+  -- 时间
+  authorized_at   TIMESTAMP    DEFAULT CURRENT_TIMESTAMP COMMENT 'OAuth 授权时间',
+  deleted_at      TIMESTAMP    DEFAULT NULL COMMENT '软删除时间',
+  created_at      TIMESTAMP    DEFAULT CURRENT_TIMESTAMP,
+  updated_at      TIMESTAMP    DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- 索引
+  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)
+);
+```
+
+### 关键说明
+
+| 字段 | 来源 | 备注 |
+|------|------|------|
+| `account_id` | OAuth 回调参数 `ttAbId` 或 `ttsAbId` | 唯一标识，与 `account_type` 组成唯一键 |
+| `business_id` | 等同于 `ttAbId` | TT 账号的所有操作（发布、轮询、查数据）都以此为入参 |
+| `creator_user_open_id` | 等同于 `ttsAbId` | TTS 账号的所有操作（上传、发布、查商品）都以此为入参 |
+| `access_token` | `account/info` 返回 | 按需存储，用于特殊场景 |
+| `app_user_id` | 你方系统 | 一个用户可绑定多个 TT/TTS 账号 |
+
+---
+
+## 2. 视频表 `beervid_videos`
+
+记录每次视频发布的全生命周期。
+
+```sql
+CREATE TABLE beervid_videos (
+  id              BIGINT PRIMARY KEY AUTO_INCREMENT,
+
+  -- 关联账号
+  account_id      BIGINT       NOT NULL COMMENT '关联 beervid_accounts.id',
+  publish_type    VARCHAR(16)  NOT NULL COMMENT 'NORMAL 或 SHOPPABLE',
+
+  -- 发布前：上传信息
+  file_url        TEXT         DEFAULT NULL COMMENT '普通上传返回的 fileUrl',
+  video_file_id   VARCHAR(128) DEFAULT NULL COMMENT 'TTS 上传返回的 videoFileId',
+  file_name       VARCHAR(256) DEFAULT NULL,
+  file_size       BIGINT       DEFAULT NULL COMMENT '文件大小（字节）',
+  caption         TEXT         DEFAULT NULL COMMENT '视频描述/文案',
+
+  -- 发布后：追踪 ID
+  share_id        VARCHAR(128) DEFAULT NULL COMMENT '普通发布返回，用于轮询',
+  video_id        VARCHAR(128) DEFAULT NULL COMMENT 'TikTok 视频 ID',
+
+  -- TTS 挂车专用
+  product_id      VARCHAR(128) DEFAULT NULL COMMENT '关联商品 ID',
+  product_title   VARCHAR(64)  DEFAULT NULL COMMENT '关联商品标题（≤29字符）',
+
+  -- 发布状态
+  publish_status  VARCHAR(32)  DEFAULT 'PENDING'
+    COMMENT 'PENDING / PROCESSING_DOWNLOAD / PUBLISH_COMPLETE / FAILED / TIMEOUT',
+  fail_reason     TEXT         DEFAULT NULL COMMENT '失败原因',
+  poll_count      INT          DEFAULT 0   COMMENT '已轮询次数',
+  last_polled_at  TIMESTAMP    DEFAULT NULL COMMENT '最后一次轮询时间',
+
+  -- 视频数据统计（来自 query-video）
+  video_views     INT          DEFAULT NULL,
+  likes           INT          DEFAULT NULL,
+  comments        INT          DEFAULT NULL,
+  shares          INT          DEFAULT NULL,
+  share_url       TEXT         DEFAULT NULL,
+  thumbnail_url   TEXT         DEFAULT NULL,
+  data_synced_at  TIMESTAMP    DEFAULT NULL COMMENT '最后一次数据同步时间',
+
+  -- 幂等控制
+  idempotency_key VARCHAR(128) DEFAULT NULL COMMENT '发布请求的稳定幂等键，防止重复发布',
+
+  -- 时间
+  deleted_at      TIMESTAMP    DEFAULT NULL COMMENT '软删除时间',
+  created_at      TIMESTAMP    DEFAULT CURRENT_TIMESTAMP,
+  updated_at      TIMESTAMP    DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- 索引
+  KEY idx_account (account_id),
+  KEY idx_share_id (share_id),
+  KEY idx_video_id (video_id),
+  KEY idx_publish_status (publish_status),
+  UNIQUE KEY uk_idempotency (idempotency_key),
+  KEY idx_status_poll (publish_status, last_polled_at)
+    COMMENT '轮询定时任务：查找需要继续轮询的记录'
+);
+```
+
+### 关键说明
+
+| 字段 | 用途 |
+|------|------|
+| `share_id` | 普通视频发布返回，用于后续 `poll-status` 轮询 |
+| `video_id` | 挂车发布直接返回；普通发布从轮询结果 `post_ids[0]` 获取 |
+| `publish_status` | 核心状态字段，定时任务依据此字段扫描待轮询记录 |
+| `idempotency_key` | 建议使用你方业务侧稳定唯一值，如 `publish_request_id`、草稿 ID 或客户端 requestId；不要拼接时间戳 |
+| `idx_status_poll` | 复合索引，加速"查找所有 PROCESSING_DOWNLOAD 且距上次轮询超过 N 秒"的查询 |
+
+---
+
+## 3. 商品缓存表 `beervid_products`
+
+缓存 TTS 商品数据，减少重复查询。
+
+```sql
+CREATE TABLE beervid_products (
+  id                  BIGINT PRIMARY KEY AUTO_INCREMENT,
+
+  -- 商品标识
+  product_id          VARCHAR(128) NOT NULL COMMENT 'BEERVID 商品 ID',
+  creator_user_open_id VARCHAR(128) NOT NULL COMMENT '所属 TTS 账号',
+
+  -- 商品信息
+  title               VARCHAR(256) NOT NULL,
+  price_amount        VARCHAR(32)  DEFAULT NULL,
+  price_currency      VARCHAR(8)   DEFAULT NULL,
+  images              JSON         DEFAULT NULL COMMENT '商品图片 URL 数组（已解析）',
+  sales_count         INT          DEFAULT 0,
+  brand_name          VARCHAR(256) DEFAULT NULL,
+  shop_name           VARCHAR(256) DEFAULT NULL,
+  source              VARCHAR(16)  DEFAULT NULL COMMENT 'shop 或 showcase',
+
+  -- 状态
+  review_status       VARCHAR(32)  DEFAULT NULL COMMENT 'APPROVED / PENDING / REJECTED',
+  inventory_status    VARCHAR(32)  DEFAULT NULL COMMENT 'IN_STOCK / OUT_OF_STOCK',
+
+  -- 缓存管理
+  cached_at           TIMESTAMP    DEFAULT CURRENT_TIMESTAMP COMMENT '首次缓存时间',
+  refreshed_at        TIMESTAMP    DEFAULT CURRENT_TIMESTAMP COMMENT '最后刷新时间',
+  deleted_at          TIMESTAMP    DEFAULT NULL COMMENT '软删除时间',
+
+  -- 索引
+  UNIQUE KEY uk_product_creator (product_id, creator_user_open_id),
+  KEY idx_creator (creator_user_open_id),
+  KEY idx_review_inventory (review_status, inventory_status)
+    COMMENT '过滤可发布商品：APPROVED + IN_STOCK',
+  KEY idx_sales (creator_user_open_id, sales_count DESC)
+    COMMENT '按销量排序选择商品'
+);
+```
+
+### 关键说明
+
+| 字段 | 备注 |
+|------|------|
+| `images` | 存储已解析的图片 URL 数组（非 BEERVID 原始格式），解析方法见 SKILL.md |
+| `review_status` + `inventory_status` | 筛选可发布商品：仅 `APPROVED` + `IN_STOCK` 可用于挂车发布 |
+| `refreshed_at` | 缓存淘汰依据，建议超过 24 小时重新拉取 |
+| `deleted_at` | 若采用 `docs/tts-product-cache.md` 中的全量替换方案，需要用它标记旧缓存失效 |
+
+---
+
+## ER 关系
+
+```
+┌─────────────────────┐       ┌──────────────────────┐
+│  beervid_accounts   │ 1   N │   beervid_videos     │
+│                     │───────│                      │
+│  id (PK)            │       │  account_id (FK)     │
+│  account_type       │       │  publish_type        │
+│  business_id        │       │  share_id            │
+│  creator_user_open_id│      │  video_id            │
+│  app_user_id        │       │  publish_status      │
+└─────────────────────┘       └──────────────────────┘
+         │ 1
+         │ N
+┌─────────────────────┐
+│  beervid_products   │
+│                     │
+│  creator_user_open_id│
+│  product_id         │
+│  title              │
+│  sales_count        │
+└─────────────────────┘
+```
+
+## 补充建议
+
+1. **软删除**：本文示例已将 `deleted_at` 纳入推荐表结构；如果你不采用软删除，也要同步调整 `docs/tts-product-cache.md` 中依赖该字段的 SQL
+2. **审计日志**：高敏感操作（发布、授权）建议独立记录操作日志表
+3. **分库分表**：如视频表数据量大，可按 `account_id` 分片
+4. **PostgreSQL 用户**：将 `AUTO_INCREMENT` 替换为 `GENERATED ALWAYS AS IDENTITY`，`JSON` 替换为 `JSONB`