huangguo_server/91迭代后端技术方案.md

91迭代后端技术方案

适用分支：feat/91-iteration

本文覆盖本次迭代的后端整体改造。短视频环形队列的底层细节另见 SHORT_VIDEO_RECOMMENDATION_BACKEND_TECH_DESIGN.md，前端对接以 短视频推荐接口.md 为准。

1. 总体架构

本次不新增独立服务、Kafka Topic、MQ、Redis实例、端口或操作系统crontab，继续使用现有三个发布单元：

• app：App/H5接口、推荐读取、观看次数、付费引导、AI女友等。
• web：亚模块、付费引导、评论Banner、VIP A/B等管理接口。
• skd：短视频推荐分刷新与全局队列构建。

数据存储沿用MongoDB与Redis。观看次数消费、AI女友上下分和VIP实验发布使用MongoDB事务，生产MongoDB必须支持事务。

2. 短视频全局推荐

2.1 推荐分

视频增加单调递增的真实互动计数和每日计算分：

recommendScore = recommendLikeCount
               + recommendCollectCount * 2
               + recommendCommentCount * 3
               + recommendShareCount * 5

真实互动成功新增时进入累计：点赞、收藏每次从未激活变为激活时增加， 评论每次成功发布时增加；取消或删除不回退，不计入 fake* 数据。 分享按用户+视频+北京自然日去重，可选 eventId 用于跨日重试幂等。

SKD使用Mongo游标固定高水位分批扫描，有界worker并发计算和BulkWrite。历史数据不依赖一次性推荐分脚本：刷新时对每项真实计数取 max(推荐累计, 历史真实计数, 0)，并写入 recommendInitialized=true。生产首次写入量受 maxInitializationWrites 保护。

2.2 队列构建

候选仅包含当前审核通过、newsType=SHORT、未删除、recoWeight!=-1、未被亚模块配置排除的视频。

• 新视频：按审核通过时间计算24小时，从高分池排除。
• 每块：严格17条高分+3条新视频，新视频不足时用高分补足。
• 去重：同一队列中视频不重复，尾块不足20条保留实际数量。
• 定时：SKD启动时及默认每10分钟做健康检查；当天队列健康时不重复生成，缺失或不健康才重建。

新队列通过临时building key分批Pipeline写入，验证完整后原子切换 current。版本为 YYYYMMDD-<revision>，切版后新的offset Hash天然使全体用户从起点开始。

2.3 请求侧环形消费

推荐接口不使用pageNumber计算服务端位置。每个用户的下一读取位置存在当前版本的Redis Hash中，队尾按取模回绕。

读取使用 Reserve -> Mongo分批校验/补位 -> Commit 协议：

• Reserve阶段不立即推进offset，同一用户并发请求由15秒租约串行化。
• 只按实际扫描前缀Commit，查询失败或取消时Abort。
• 只有客户端显式传入、Trim后非空且不超过128字节的 X-Request-ID 才对应commit receipt，解决“Redis已提交但HTTP响应丢失”的重试幂等； 中间件自动生成并回传的request ID不参与此业务幂等。
• Mongo按有界批次取数，扫描量受队列长度、scanMultiplier和 maxBatches 共同限制，避免失效视频导致无界扫描。

主接口 /api/app/recommend/vid/list 和兼容接口 /api/app/vid/module/short/all 复用同一队列服务。只有尚未成功Reserve、返回的 QueueVersion 为空且非请求取消类故障时， 才使用原随机Set降级。Reserve成功后的Mongo校验或Commit失败会Abort并返回错误， 不再切到随机集；请求取消或超时在两个入口中保留返回空成功结果的兼容分支。

3. 首页随机刷新与亚模块治理

module_conf 增加稳定能力字段，前端不再根据可编辑标题判断：

• haiJiaoStyle.sortRules[].refreshMode=RANDOM_TOP_N
• randomCandidateN=30
• onlineAt/offlineAt
• excludeLatest/excludeRecommend
• searchOnlyWhenInactive

历史 val=2 在没有新字段时由后端兼容归一为随机刷新。新刷新接口从热门候选前30条中随机返回，refreshToken 保证同一次重试顺序稳定。

亚模块元数据使用15秒进程内不可变快照和singleflight。管理后台变更后会清理共享缓存和当前进程快照； 其他App进程最多延迟约15秒生效。excludeLatest 和 excludeRecommend 分别只控制“最新”和“推荐”场景。只有当亚模块当前失效且 searchOnlyWhenInactive=true 时，才拦截搜索以外的普通入口、分享和直接详情； 搜索结果签发10分钟、绑定UID和视频ID的 searchAccessToken，详情接口校验后放行。

4. 更新红点

GET /api/app/content/update-markers 聚合首页最新、当日最新及各亚模块最后内容时间。视频取最近审核时间，动漫/漫画同时考虑子集更新时间；“当日”按UTC+8自然日计算。

返回结果在Redis缓存30秒，前端保存本地已读时间并自行判断红点，后端不保存每用户红点状态。

5. AI女友V2与钱包

POST /api/app/aimatev2/url 在用户级Redis锁内：

1. 先回收上一次第三方剩余金额。
2. 读取主钱包，按 10金币=1元 转换并请求第三方授权URL。
3. 授权URL成功后，在Mongo事务内扣减主钱包并写入 fund_transfer_log。

GET /api/app/mine/wallet 返回钱包前尝试将第三方余额下分回主钱包，保留不足1金币的换算余数供下次结算。 fund_transfer_log 记录上下分类型、金额、操作后余额和余数，用于审计和辅助状态排查； 它没有业务幂等唯一键，第三方上下分与本地Mongo事务也不是跨系统原子操作。

6. 付费引导与会员内容上新

payment_guide 按场景、用户分层、排序、启用状态和有效期选择配置。过期会员、已退款且权益回收的用户按未付费分层处理。注册不足24小时的未付费用户始终属于新用户分层；免费次数是否用完只控制 HOME_NEW_USER_FREE_TRIAL 的 show，不得影响其他场景的新老用户分层。

VIP_CONTENT_UPDATE 动态查询审核通过的最新VIP视频，排除免费区、金币视频、不可推荐和业务配置排除的亚模块，按 reviewAt desc, _id desc 返回。数量由 videoLimit 控制，默认4，最大20。

视频ID顺序生成 contentVersion。展示回执按“UID+配置+场景+内容版本”幂等记录到 payment_guide_impression；新内容产生新版本后可再次提示。

7. 评论区Banner

scene_banner 支持 COMMENT_TOP 场景的多张图片/GIF、内链/外链/无跳转、排序、启用和上下架时间。App端只返回当前有效数据，按 sort desc, updatedAt desc 轮播。历史每场景单条唯一索引需在模型初始化时删除，再创建查询索引。

8. VIP卡片A/B与下单归因

vip_card_experiment 保存A/B流量、套餐集合、默认套餐、角标文案、皮肤标识和 uiConfig。UID通过稳定哈希命中A或B，发布新实验时在事务内停用旧实验，唯一active-slot索引保证全局只有一个生效实验。

App套餐接口仅返回当前UID命中分组的：

• experimentId/variant/skinKey/defaultProductId
• uiConfig.backgroundImage（会员中心整页背景）
• uiConfig.badgeStyles（角标背景色和文字色）
• 每个套餐的 badgeType/badgeText

vip_card_analytics_event 使用唯一 eventId 幂等保存卡皮展示、套餐展示和无购买关闭事件，统计同时返回去重人数和次数。

下单增加 sourcePage/sourceRef/videoId/activityId/experimentId/experimentVariant/sessionId。sourcePage 允许任意非空值，Trim后最长128个Unicode字符，空值归一为 UNKNOWN。参与实验时，后端校验UID分组、套餐归属和会话ID，并在创建订单时固化归因，支付回调不重新分组。

9. 免费观看与试看角标

GET /api/app/vid/user/count 增加 totalWatchCount，值改为后端系统配置 sys_conf 的 totalWatchCount（gpCode=common）。新客户端通过 POST /api/app/vid/play/consume 消费次数：

• 在事务内写当日观看记录并扣减用户剩余次数。
• consumeKey=UID+视频+自然日 的唯一索引保证并发只扣1次。
• 遇到Mongo短暂事务冲突时最多有界重试5次，提交后再清理用户缓存。

当前实现边界：消费接口会校验审核、VIP/作者、免费区、金币和当日已看， 但没有限制 newsType=SP/SHORT。因此其他审核通过且同样非金币、非免费区的视频也可能消费次数； 若产品要求与角标资格完全一致，上线前需补充类型校验。

视频列表/详情增加 showFreeTrialBadge/freeTrialRemaining/canUseFreeTrial。后端在一次列表组装中复用用户上下文，不逐视频查用户或配置。只有同时满足以下条件时显示：

• freeTrialBadgeEnabled=true
• 已登录、非VIP、剩余次数大于0
• 普通/短视频VIP内容，非金币、非免费区、非用户自己发布

10. 动漫/漫画最新时间

media 增加 latestPublishedAt。媒体首次/重新上架、批量激活或成功新增子集时同步更新； 普通媒体元数据更新不改该时间。亚模块“最新”排序为：

latestPublishedAt desc,
contentUpdateTime desc,
createdAt desc,
_id desc

查询会追加旧时间字段作为后续排序键，但不等价于针对每条记录做 $ifNull 回退，新旧文档混排仍可能失序。因此上线时必须单独交付并执行 script/mongo/backfill_media_latest_published_at.js；该脚本不依赖服务启动，本次与文档包一起迁移。

11. 视频置顶

现有视频编辑接口的 liaoBaTopSort 取消0～99限制，允许重复值；保存时仅更新当前视频，不交换其他视频。置顶列表按 liaoBaTopSort desc, reviewAt desc, _id desc 稳定排序。

12. 数据模型、索引与缓存

新增Mongo集合：

• fund_transfer_log
• payment_guide
• payment_guide_impression
• scene_banner
• vip_card_experiment
• vip_card_analytics_event

关键索引：

• 推荐扫描：newsType, status, deleteAt, _id。Mongo读取和写入按有界批次执行， worker数有上限；但所有合格候选的精简快照会留在内存中再排序并组装17+3队列， 内存随候选量增长，上线前需用生产规模数据压测。
• 免费消费：user_act.consumeKey 部分唯一索引。
• 付费引导曝光：uid, configId, scene, contentVersion 唯一。
• VIP实验：experimentId 唯一、active-slot部分唯一、eventId 唯一。
• 订单归因：sourcePage, createdAt 复合索引，以及 experimentId, experimentVariant, productID, status 复合索引。
• AI资金日志：uid, category, createdAt desc。
• 媒体最新：模块、状态、删除标记与 latestPublishedAt/contentUpdateTime/createdAt/_id 复合索引。

关键Redis键：

recommend:short:current
recommend:short:queue:{version}
recommend:short:offset:{version}
recommend:short:meta:{version}
recommend:short:build-lock
recommend:short:reservation:{version}:{uid}
recommend:short:commit-receipt:{uid}:{receiptId}
content:update-markers:v1
redsync:ai-fund:{uid}

App与SKD的 keyTTLHours 必须一致。queue/meta 默认按发布时间+72小时过期， offset 使用meta记录的同一绝对过期时间；current 不设TTL， build-lock 固定10分钟，reservation 固定15秒，commit-receipt 固定30秒。

13. 发布与数据迁移

1. 核对 91迭代配置改动点.md，完成App、SKD运行配置和各环境业务配置。
2. 在低峰发布 web，确认新集合/索引初始化成功，再发布 app。
3. 统计未初始化推荐字段数量，根据生产量调整 maxInitializationWrites。
4. 发布 skd。可先使 skd.shortRecommend.enabled=true 生成队列，保持 app.shortRecommend.enabled=false 验证健康度，再开启App全局读取。
5. 单独执行媒体历史回填脚本；执行前后统计缺失数并抽样验证。
6. 逐项配置亚模块、付费引导、评论Banner、VIP A/B和免费试看开关；测试库数据不会自动迁移到生产。

推荐开关是服务实例级全局开关，不是按UID白名单灰度。影子验证应通过“SKD开、App关”完成。

14. 自测与验收

• 推荐：17+3比例、新视频不足、环形回绕、每日切版、同UID并发、超时重试、失效视频补位、降级。
• 亚模块：上下架边界、各入口排除、搜索token的UID/视频/过期校验、随机刷新重试稳定。
• 付费引导：全部用户分层、仅展示一次、内容版本变化、videoLimit 0/4/20/越界。
• VIP A/B：UID稳定分流、UI配置下发、事件去重、人/次统计、创建/支付/退款口径、下单归因。
• 免费观看：同UID+视频并发只扣1次，VIP/发布者/免费区/金币/当日已看分支，角标开关和剩余次数实时失效。
• AI女友：重复进入、重复返回钱包、余数处理、第三方失败、Mongo事务回滚和流水一致。
• 媒体：存量回填、新上架、子集更新、相同时间稳定排序与索引explain。

上线前应在接近生产数量级的数据上验证推荐全量扫描时间、BulkWrite批次、Redis发布耗时、接口P95/P99、Mongo连接池和Redis内存占用。