Files

T

rootandClaude Opus 5 8679200f41 Initial commit

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-15 13:57:10 +08:00

13 KiB

Raw Blame History

短视频推荐接口

本文仅提供前端联调需要的接口变更。公共请求头、登录态、签名、加密及错误处理均沿用现有项目。

一、App/H5接口

1. 短视频推荐列表

修改现有接口：

GET /api/app/recommend/vid/list?pageNumber=1&pageSize=20

请求：

字段	类型	说明
`pageNumber`	int	沿用现有传参
`pageSize`	int	固定传20

响应：

{
  "vInfos": [],
  "totalPages": 100,
  "hasNext": true,
  "queueVersion": "20260724"
}

新增字段：

字段	类型	说明
`hasNext`	bool	是否可以继续加载，以该字段为准
`queueVersion`	string	推荐队列版本，仅用于日志排查

前端不上传已看视频ID或offset，不再使用 totalPages 判断结束。

短视频分享时，现有接口补传视频ID：

POST /api/app/share/output

{
  "content": "分享链接",
  "videoID": "短视频ID"
}

videoID 用于累计真实分享推荐分；旧客户端不传仍可正常生成分享内容，但不会累计本次分享分。

2. 免费观看次数

修改现有接口：

GET /api/app/vid/user/count?vid={videoId}

响应增加：

{
  "isCan": true,
  "watchCount": 2,
  "totalWatchCount": 3
}

字段	类型	说明
`watchCount`	uint64	当前剩余免费观看次数
`totalWatchCount`	uint64	免费观看总次数，本次新增

传或不传 vid 时都返回 totalWatchCount。

3. 模块配置

修改现有接口：

GET /api/app/modules/list

排序项增加：

{
  "val": 2,
  "name": "热门推荐",
  "refreshMode": "RANDOM_TOP_N",
  "randomCandidateN": 30
}

前端只根据 refreshMode 判断随机刷新，禁止匹配 name 或硬编码 val。

枚举：

DEFAULT
RANDOM_TOP_N

兼容说明：后台历史数据没有 refreshMode 时，后端会把稳定排序值 val=2 归一为 RANDOM_TOP_N；标题即使配置错误也不会影响刷新功能。

4. 亚模块热门随机刷新

新增接口：

GET /api/app/vid/module/{subModuleId}/refresh

请求：

字段	类型	必填	说明
`moduleSort`	int	是	当前排序项的 `val`
`pageSize`	int	否	最大30
`refreshToken`	string	是	每次刷新生成UUID

响应：

{
  "allVideoInfo": [],
  "candidateCount": 30,
  "hasNext": true,
  "refreshMode": "RANDOM_TOP_N",
  "refreshToken": "uuid"
}

候选池未变化时，同一个 refreshToken 重试会得到相同顺序；用户主动再次下拉时必须生成新的 refreshToken。candidateCount 是本次实际进入候选池的视频数，可能小于30。hasNext 表示候选池中是否还有本次未返回的视频，即 candidateCount > allVideoInfo.length。

5. 亚模块受限视频

搜索结果中的视频增加：

{
  "searchAccessTicket": "short-lived-ticket"
}

从搜索进入详情时携带：

GET /api/app/vid/info?id={videoId}&searchAccessTicket={ticket}

从搜索进入播放时继续携带 searchAccessTicket。非搜索来源不传。

6. 首页更新红点

新增接口：

GET /api/app/content/update-markers

响应：

{
  "homeLatestAt": "2026-07-24T08:00:00Z",
  "todayLatestAt": "2026-07-24T08:00:00Z",
  "modules": [
    {
      "moduleId": "moduleId",
      "latestAt": "2026-07-24T08:00:00Z"
    }
  ]
}

前端在本地保存最后查看时间并判断红点。

7. AI女友V2

入口展示继续读取：

GET /api/app/ping/v

当 data.aiGirlFriend=true 时展示入口。点击后调用：

POST /api/app/aimatev2/url

无需请求体，成功返回：

{
  "url": "https://example.com/ai"
}

前端打开 data.url。用户关闭页面或返回 App 后，调用：

GET /api/app/mine/wallet

后端会在获取 URL 时自动上分，并在查询钱包时先尝试下分；钱包响应结构不变。新版不再调用 /api/app/aimate/*，也不再直接使用 aiMateH5。

8. 获取付费引导

新增接口：

GET /api/app/payment/guide?scene={scene}&videoId={videoId}

场景：

HOME_NEW_USER
HOME_OLD_USER
VIDEO_PREVIEW_END
VIDEO_BACK
VIP_CENTER
VIP_CONTENT_UPDATE

响应：

{
  "show": true,
  "configId": "configId",
  "segment": "OLD_NEVER_PAID",
  "style": "BOTTOM_SHEET",
  "title": "查看完整影片",
  "description": "开通会员后可观看",
  "cover": "https://example.com/cover.jpg",
  "videoIds": ["videoId"],
  "productId": "productId",
  "durationSeconds": 7200,
  "action": {
    "type": "VIP_PRODUCT",
    "value": "productId"
  }
}

show=false 时不弹。播放5分钟、试看3秒和App活跃3分钟均由前端计时。

用户分层枚举：

NEW_NEVER_PAID
OLD_NEVER_PAID
PAID_UPGRADE
MAX_VIP
NORMAL
UNREGISTERED

未付费用户注册不足 24 小时按 NEW_NEVER_PAID 处理，达到 24 小时后按 OLD_NEVER_PAID 处理。免费观看次数不会改变该分层；次数用完时只关闭 HOME_NEW_USER_FREE_TRIAL 的展示。过期会员按 OLD_NEVER_PAID 处理；退款后会员权益已回收时同样按未付费处理。

9. 付费引导展示回执

新增接口：

POST /api/app/payment/guide/impression

请求：

{
  "configId": "configId",
  "scene": "VIP_CONTENT_UPDATE",
  "videoId": "videoId",
  "requestId": "uuid"
}

只有弹窗实际展示成功后调用。

回执成功后，同一用户、同一 configId、同一 scene 不再返回该引导。

10. 视频免费试看角标

所有视频列表对象增加：

{
  "showFreeTrialBadge": true,
  "freeTrialRemaining": 2,
  "canUseFreeTrial": true
}

前端直接根据 showFreeTrialBadge 展示角标，不自行组合判断条件。

11. 评论区Banner

新增接口：

GET /api/app/banner/list?scene=COMMENT_TOP

响应：

{
  "list": [
    {
      "id": "bannerId",
      "imageUrl": "https://example.com/banner.gif",
      "mediaType": "GIF",
      "linkType": "INTERNAL",
      "linkValue": "video://detail?id=videoId",
      "sort": 100
    }
  ]
}

枚举：

mediaType: IMAGE | GIF
linkType: INTERNAL | EXTERNAL | NONE

COMMENT_TOP 支持配置多条图片或 GIF，按 sort 从大到小返回，前端按返回顺序轮播。未启用或不在有效时间内的配置不会返回；没有有效配置时返回空数组。

12. VIP套餐及A/B

修改现有接口：

GET /api/app/vip/product

现有套餐字段保持不变，响应增加实验信息；每个套餐对象增加 badgeType、badgeText：

{
  "experimentId": "vip-card-202607-v1",
  "variant": "A",
  "defaultProductId": "productId",
  "list": [
    {
      "showType": 2,
      "position": "vip",
      "list": [
        {
          "productID": "productId",
          "productName": "全尊新人卡",
          "badgeType": "MOST_POPULAR",
          "badgeText": "最受欢迎"
        }
      ]
    }
  ],
  "integralList": [],
  "daichong": {},
  "isNewUser": true
}

角标枚举：

MOST_POPULAR   最受欢迎
NEW_USER_OFFER 新人特惠
空值或未知值    不展示

前端只按套餐对象的 badgeType 判断是否展示角标，显示内容使用 badgeText；不得通过套餐名称、sort、数组位置或默认套餐判断。基础配置与 A/B 配置的合并由后端完成，前端不处理配置优先级。前端下单时原样回传 experimentId 和 variant。实际价格以该接口和下单结果为准。

13. VIP卡片统计事件

新增接口：

POST /api/app/analytics/events

请求：

{
  "events": [
    {
      "eventId": "uuid",
      "eventName": "VIP_PRODUCT_IMPRESSION",
      "sessionId": "uuid",
      "occurredAt": "2026-07-24T08:00:00Z",
      "experimentId": "vip-card-202607-v1",
      "variant": "A",
      "productId": "productId"
    }
  ]
}

事件：

VIP_CARD_PAGE_VIEW
VIP_PRODUCT_IMPRESSION
VIP_CARD_CLOSE_WITHOUT_PURCHASE

曝光必须在UI实际展示后上报。

14. 创建订单

修改现有接口：

POST /api/app/mine/topay

新增非必填字段：

{
  "sourcePage": "VIDEO_BOTTOM_SHEET",
  "sourceRef": "videoId",
  "videoId": "videoId",
  "activityId": "activityId",
  "experimentId": "vip-card-202607-v1",
  "experimentVariant": "A",
  "sessionId": "uuid"
}

来源枚举：

HOME_USER_SEGMENT
VIDEO_BOTTOM_BANNER
VIDEO_BOTTOM_SHEET
VIP_CENTER
H5_ACTIVITY
UNKNOWN

15. 动漫漫画最新列表

修改现有接口：

GET /api/app/media/list?pageNumber=1&pageSize=20

媒体对象增加：

{
  "updateTime": "2026-07-24T08:00:00Z",
  "latestPublishedAt": "2026-07-24T08:00:00Z"
}

前端按后端返回顺序展示，不自行排序。

二、管理后台接口

1. 亚模块配置

修改现有：

POST /api/web/admin/module/conf/add
POST /api/web/admin/module/conf/edit

增加：

{
  "onlineAt": "2026-07-24T00:00:00Z",
  "offlineAt": "2026-08-24T00:00:00Z",
  "excludeLatest": true,
  "excludeRecommend": false,
  "searchOnlyWhenInactive": true,
  "haiJiaoStyle": {
    "sortRules": [
      {
        "val": 2,
        "name": "热门推荐",
        "refreshMode": "RANDOM_TOP_N",
        "randomCandidateN": 30
      }
    ]
  }
}

2. 付费引导配置

GET    /api/web/admin/payment-guide/list
POST   /api/web/admin/payment-guide/add
POST   /api/web/admin/payment-guide/edit
DELETE /api/web/admin/payment-guide/delete?id={id}

新增/编辑使用完整配置对象，编辑时必须带 id：

{
  "id": "编辑时必传，新增不传",
  "scene": "VIDEO_PREVIEW_END",
  "segments": ["OLD_NEVER_PAID"],
  "style": "BOTTOM_SHEET",
  "title": "查看完整影片",
  "description": "开通会员后可观看",
  "cover": "https://example.com/cover.jpg",
  "videoIds": ["videoId"],
  "productId": "productId",
  "durationSeconds": 7200,
  "action": {
    "type": "VIP_PRODUCT",
    "value": "productId"
  },
  "enable": true,
  "sort": 100,
  "startAt": "2026-07-24T00:00:00Z",
  "endAt": "2026-08-24T00:00:00Z"
}

startAt/endAt 可不传；编辑时不传表示清空时间限制。 segments 传空数组表示所有用户分层。已展示过的配置如果要重新触达用户，应新增配置生成新的 configId，不要直接复用原配置。

3. 评论Banner配置

GET    /api/web/admin/banner/list?scene=COMMENT_TOP
POST   /api/web/admin/banner/add
POST   /api/web/admin/banner/edit
DELETE /api/web/admin/banner/delete?id={id}

新增/编辑使用完整配置对象，编辑时必须带 id：

{
  "id": "编辑时必传，新增不传",
  "scene": "COMMENT_TOP",
  "imageUrl": "https://example.com/banner.gif",
  "mediaType": "GIF",
  "linkType": "INTERNAL",
  "linkValue": "video://detail?id=videoId",
  "sort": 100,
  "enable": true,
  "startAt": "2026-07-24T00:00:00Z",
  "endAt": "2026-08-24T00:00:00Z"
}

COMMENT_TOP 支持新增多条配置。每条配置独立设置图片/GIF、内外链、排序、启用状态及上下架时间；前端按 App 接口返回顺序轮播。

4. VIP卡片实验

GET  /api/web/admin/vip-card-experiment/current
POST /api/web/admin/vip-card-experiment/publish
POST /api/web/admin/vip-card-experiment/disable
GET  /api/web/admin/vip-card-experiment/statistics?experimentId={id}

发布请求中的每个变体增加套餐角标配置：

{
  "variantA": {
    "defaultProductId": "productId",
    "productIds": {
      "1": "第1张卡片的productId",
      "2": "第2张卡片的productId"
    },
    "productBadges": [
      {
        "productId": "productId",
        "badgeType": "MOST_POPULAR",
        "badgeText": "最受欢迎"
      }
    ]
  }
}

productIds 的 key 是从 1 开始且连续的卡片顺序，value 是商品ID；发布和查询接口均使用该结构。同一变体内排序号和商品ID都不能重复。App/H5 套餐接口保持旧版本的独立 position 分组和外层顺序：会员卡、预售卡仍分别返回；同一分组内严格按该数字顺序排列，不支持跨 position 穿插排序。同一变体最多配置一个 MOST_POPULAR；productId 必须属于该变体的 productIds。

5. 免费试看角标开关

复用现有系统配置接口，配置项：

freeTrialBadgeEnabled = true | false

6. 动漫漫画更新

复用现有接口：

POST /api/web/admin/media/update
POST /api/web/admin/media_content/create
POST /api/web/admin/media_content/update

列表响应增加：

{
  "contentUpdateTime": "2026-07-24T08:00:00Z",
  "latestPublishedAt": "2026-07-24T08:00:00Z"
}

7. 视频置顶排序

复用现有视频编辑接口。sort 放开0～99限制，并允许多个视频填写相同值。前端不需要交换或修改其他视频的排序号。

三、无需新增后端接口

金币支付半屏：复用现有支付接口。
播放页Banner放大：纯UI。
删除支付温馨提示：纯UI。
iOS搜索回车：纯客户端事件。

13 KiB Raw Blame History Unescape Escape

短视频推荐接口

一、App/H5接口

1. 短视频推荐列表

2. 免费观看次数

3. 模块配置

4. 亚模块热门随机刷新

5. 亚模块受限视频

6. 首页更新红点

7. AI女友V2

8. 获取付费引导

9. 付费引导展示回执

10. 视频免费试看角标

11. 评论区Banner

12. VIP套餐及A/B

13. VIP卡片统计事件

14. 创建订单

15. 动漫漫画最新列表

二、管理后台接口

1. 亚模块配置

2. 付费引导配置

3. 评论Banner配置

4. VIP卡片实验

5. 免费试看角标开关

6. 动漫漫画更新

7. 视频置顶排序

三、无需新增后端接口

13 KiB

Raw Blame History