beervid-app-cli 0.2.6 → 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

@@ -24,9 +24,16 @@
 
 ## 回调参数
 
-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 操作的入参 |
@@ -34,6 +41,39 @@ 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
@@ -181,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',
     })
   }
@@ -219,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)
 }
 ```
@@ -248,6 +295,7 @@ async function handleOAuthCallback(req: Request): Promise<Response> {
 - 回调请求应快速响应，避免用户长时间等待
 - 头像同步等操作允许延迟几秒完成
 - 即使同步失败，授权本身已成功
+- 如果要关联同一达人的 TT / TTS 账号，建议在这里同步并持久化 `username`
 
 ```typescript
 async function syncAccountInfoAsync(
@@ -261,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` 真正返回后，才进入后续查数链路

package/skills/beervid-app-cli/docs/security-best-practices.md

@@ -0,0 +1,132 @@
+# 安全最佳实践
+
+本文档只保留与 BEERVID Open API 接入直接相关的安全要求，避免掺入与当前 API 无关的通用后端模板内容。
+
+## 目录
+
+1. [API Key 使用](#api-key-使用)
+2. [OAuth 回调处理](#oauth-回调处理)
+3. [请求与日志](#请求与日志)
+4. [账号与 Token 存储](#账号与-token-存储)
+5. [上线前检查](#上线前检查)
+
+---
+
+## API Key 使用
+
+### 1. 不要硬编码 `BEERVID_APP_KEY`
+
+```typescript
+const apiKey = process.env.BEERVID_APP_KEY
+if (!apiKey) {
+  throw new Error('BEERVID_APP_KEY is required')
+}
+```
+
+### 2. 只在服务端保存和使用 API Key
+
+- 不要把 `BEERVID_APP_KEY` 下发到浏览器或移动端
+- 前端如果需要调用能力，应先请求你自己的后端，再由后端调用 Open API
+- CLI 场景下优先使用 `beervid config --app-key` 或环境变量，不要把 Key 写进代码仓库
+
+### 3. 区分不同环境的 Key
+
+- 测试、预发、生产环境分别使用独立 Key
+- 怀疑泄露时立即轮换 Key
+- 不要在日志、截图、报错信息里输出完整 Key
+
+---
+
+## OAuth 回调处理
+
+### 1. 校验并持久化 `state`
+
+BEERVID 的 TT / TTS OAuth 流程依赖回调 URL 中的 `state` 参数；你至少应做到：
+
+- 生成授权链接时为当前用户生成一次性 `state`
+- 回调时校验 `state` 是否存在、是否过期、是否已使用
+- 从 `state` 中提取 `ttAbId` / `ttsAbId` 后再落库
+
+推荐直接参考 [oauth-callback.md](./oauth-callback.md) 中的完整落地方式。
+
+### 2. 回调地址使用 HTTPS
+
+- 生产环境回调 URL 使用 HTTPS
+- 只在你自己控制的域名下接收回调
+- 不要把完整回调 URL 原样打进日志，避免把 `state` 暴露出去
+
+---
+
+## 请求与日志
+
+### 1. 统一通过服务端封装请求
+
+建议统一封装 `openApiGet`、`openApiPost`、`openApiUpload` 这类函数，集中处理：
+
+- `X-API-KEY` 注入
+- 基础地址拼接
+- 超时控制
+- 响应解包
+- 错误格式化
+
+### 2. 日志里只打印脱敏后的关键信息
+
+推荐记录：
+
+- 接口路径
+- 业务账号 ID（`businessId` / `creatorUserOpenId`）
+- `shareId` / `videoId`
+- Open API `code`、`message`
+
+不要记录：
+
+- 完整 API Key
+- 完整 access token
+- 完整 OAuth `state`
+- 含敏感 query 参数的原始 URL
+
+### 3. 对外错误信息保持收敛
+
+- 对用户返回“授权失效”“参数错误”“上传失败”这类业务级信息
+- 详细堆栈和 Open API 原始报错只保留在服务端日志中
+
+---
+
+## 账号与 Token 存储
+
+### 1. 只存必须的账号字段
+
+对当前项目来说，真正高频使用的字段通常是：
+
+- `accountType`
+- `accountId`
+- `businessId`
+- `creatorUserOpenId`
+- `username`
+- `displayName`
+- `sellerName`
+- `profileUrl`
+- `followersCount`
+
+### 2. `accessToken` 按需存储
+
+`account/info` 会返回 `accessToken`。如果你的业务不会直接使用它：
+
+- 可以不入库
+- 或仅短期缓存，不作为常规展示字段返回给前端
+
+如果必须持久化，至少做到：
+
+- 数据库字段与普通展示字段分开
+- 日志脱敏
+- 读取权限最小化
+
+---
+
+## 上线前检查
+
+- `BEERVID_APP_KEY` 仅存在于服务端环境变量或本地 CLI 配置中
+- OAuth 回调已校验 `state`，且 `ttAbId` / `ttsAbId` 已正确落库
+- 对外接口不会返回 API Key、access token、原始 `state`
+- Open API 请求封装已统一超时和错误处理
+- 业务日志里只保留脱敏后的账号 ID、`shareId`、`videoId`