beervid-app-cli 0.2.2 → 0.2.4

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`

package/docs/oauth-callback.md

@@ -0,0 +1,282 @@
+# OAuth 回调存储建议
+
+> 本文档描述接入 BEERVID OAuth 授权回调后，如何安全地处理回调参数、防止 CSRF 攻击、以及持久化账号信息。
+
+## 授权流程总览
+
+```
+┌─────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
+│  你的应用 │────→│ BEERVID  │────→│ TikTok   │────→│ 回调 URL  │
+│          │ ①  │ OAuth URL│ ②  │ 授权页面  │ ③  │ 你的服务器│
+└─────────┘     └──────────┘     └──────────┘     └──────────┘
+ 获取 URL          重定向           用户授权       收到回调参数
+```
+
+1. **获取 OAuth URL**：调用 `GET /api/v1/open/thirdparty-auth/tt-url` 或 `tts-url`
+2. **用户跳转授权**：将用户重定向到返回的 URL
+3. **接收回调**：用户授权后，TikTok 回调你的服务器
+
+> **说明**：获取到的授权链接中通常已经包含 `state` 参数。
+> 如果你需要附加自定义安全字段，做法不是新增一个 `state` 参数，而是解析现有 `state`，在其 JSON 中追加字段后再写回授权链接。
+
+---
+
+## 回调参数
+
+OAuth 授权完成后，回调 URL 会携带以下关键参数：
+
+| 账号类型 | 回调参数 | 含义 | 后续用途 |
+|----------|----------|------|----------|
+| TT | `ttAbId` | TT 账号的 businessId | 所有 TT 操作的入参 |
+| TTS | `ttsAbId` | TTS 账号的 creatorUserOpenId | 所有 TTS 操作的入参 |
+
+> **重要**：`ttAbId` 就是后续所有 TT API 的 `businessId`，`ttsAbId` 就是所有 TTS API 的 `creatorUserOpenId`。
+> 这两个值必须可靠持久化，丢失意味着需要用户重新授权。
+
+---
+
+## 获取授权链接后如何向已有 State 追加自定义字段
+
+如果获取到的授权链接里已经自带 `state`，并且它的值是一个 JSON 字符串，可以在拿到 OAuth URL 后解析这个 JSON，再把你方的安全 token 追加进去：
+
+```typescript
+function tryParseJsonObject(value: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(value) as unknown
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+function appendTokenToOAuthUrlState(
+  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 对象')
+  }
+
+  const nextState = {
+    ...parsedState,
+    customStateToken,
+  }
+
+  url.searchParams.set('state', JSON.stringify(nextState))
+  return url.toString()
+}
+
+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)
+}
+
+async function getTtsOAuthUrlWithState(userId: string): Promise<string> {
+  const customStateToken = generateStateToken(userId)
+  const data = await openApiGet<{ crossBorderUrl: string }>(
+    '/api/v1/open/thirdparty-auth/tts-url'
+  )
+  return appendTokenToOAuthUrlState(data.crossBorderUrl, customStateToken)
+}
+```
+
+回调时再从 `state` JSON 中取回你追加的字段并校验：
+
+```typescript
+function parseCustomStateToken(state: string): string {
+  const parsed = tryParseJsonObject(state) as { customStateToken?: string } | null
+  if (!parsed) {
+    throw new Error('state 不是合法 JSON 对象')
+  }
+  if (!parsed.customStateToken) {
+    throw new Error('state 中缺少 customStateToken')
+  }
+  return parsed.customStateToken
+}
+```
+
+> **说明**：字段名 `customStateToken` 只是示例，你也可以改成 `token`、`nonce`、`appState` 等业务上更合适的名字。
+> 如果授权链接里的 `state` 不是 JSON 对象，就不要按这个示例直接 `JSON.parse`；应改为使用平台允许的编码方式，或采用你当前链路已有的透传机制。
+
+---
+
+## State Token 防 CSRF
+
+### 为什么需要
+
+OAuth 回调容易受到 CSRF 攻击——攻击者可以伪造回调请求，将恶意账号绑定到受害者系统。
+
+### 推荐方案：JWT 格式 State Token
+
+```typescript
+import jwt from 'jsonwebtoken'
+
+const STATE_SECRET = process.env.OAUTH_STATE_SECRET!
+
+// ① 生成 State Token（在获取 OAuth URL 时）
+function generateStateToken(userId: string): string {
+  return jwt.sign(
+    {
+      userId,        // 当前登录用户 ID
+      purpose: 'beervid-oauth',
+      nonce: crypto.randomUUID(),  // 一次性随机值
+    },
+    STATE_SECRET,
+    { expiresIn: '10m' }  // 短过期时间：10 分钟
+  )
+}
+
+// ② 验证 State Token（在回调中）
+function verifyStateToken(state: string): { userId: string; nonce: string } {
+  try {
+    const payload = jwt.verify(state, STATE_SECRET) as {
+      userId: string
+      purpose: string
+      nonce: string
+    }
+    if (payload.purpose !== 'beervid-oauth') {
+      throw new Error('Invalid state purpose')
+    }
+    return { userId: payload.userId, nonce: payload.nonce }
+  } catch {
+    throw new Error('State Token 验证失败：可能已过期或被篡改')
+  }
+}
+```
+
+### 一次性消费
+
+为防止重放攻击，State Token 应确保只使用一次：
+
+```typescript
+// 使用 Redis 记录已消费的 nonce
+const NONCE_TTL = 600  // 与 State Token 过期时间一致
+
+async function consumeStateNonce(nonce: string): Promise<boolean> {
+  // SET NX：仅当 key 不存在时设置成功
+  const result = await redis.set(`oauth:nonce:${nonce}`, '1', 'EX', NONCE_TTL, 'NX')
+  return result === 'OK'  // true = 首次使用，false = 已被消费
+}
+```
+
+---
+
+## 回调处理完整流程
+
+```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')
+
+  // ① 验证 State Token
+  if (!state) {
+    return new Response('缺少 state 参数', { status: 400 })
+  }
+
+  let statePayload: { userId: string; nonce: string }
+  try {
+    statePayload = verifyStateToken(state)
+  } 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',
+    })
+  }
+
+  if (ttsAbId) {
+    await saveAccount({
+      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)
+}
+```
+
+---
+
+## 异步账号信息同步
+
+授权回调只返回 `accountId`，详细信息（头像、粉丝数、用户名等）需要额外调用 `account/info` 接口获取。
+
+**为什么异步？**
+- 回调请求应快速响应，避免用户长时间等待
+- 头像同步等操作允许延迟几秒完成
+- 即使同步失败，授权本身已成功
+
+```typescript
+async function syncAccountInfoAsync(
+  accountType: 'TT' | 'TTS',
+  accountId: string
+): Promise<void> {
+  const data = await openApiPost('/api/v1/open/account/info', {
+    accountType,
+    accountId,
+  })
+
+  await updateAccount(accountId, {
+    username: data.username,
+    displayName: data.displayName,
+    sellerName: data.sellerName,
+    profileUrl: data.profileUrl,
+    followersCount: data.followersCount,
+    accessToken: data.accessToken,
+  })
+}
+```
+
+---
+
+## 安全要点速查
+
+| 要点 | 做法 |
+|------|------|
+| 防 CSRF | 使用 JWT State Token，回调时验证签名和过期时间 |
+| 防重放 | 一次性 nonce，Redis 记录已消费 |
+| 短过期 | State Token 有效期 10 分钟 |
+| 用户绑定 | State Token 中嵌入 userId，确保回调绑定到正确用户 |
+| 数据完整性 | 回调中立即持久化 accountId，异步补充详情 |
+| 失败容忍 | 异步同步失败不影响授权成功状态 |
+| HTTPS | 回调 URL 必须使用 HTTPS |