huangguo_server/91迭代配置改动点.md

91迭代配置改动点

适用分支：feat/91-iteration

本文只记录环境配置、后台业务配置和上线数据处理。账号、密钥及各环境真实配置值不得写入本文。

一、App运行配置

文件：config/app.json

新增根节点：

{
  "shortRecommend": {
    "enabled": true,
    "requestTimeoutMs": 3000,
    "maxBatches": 5,
    "scanMultiplier": 5,
    "keyTTLHours": 72
  },
  "laoSiJiAiMate": {
    "appId": "<按环境填写>",
    "apiKey": "<按环境填写，不得写入Git或文档>",
    "apiUrl": "<按环境填写>"
  }
}

字段说明：

字段	默认值/要求	说明
shortRecommend.enabled	未配置默认 true	是否使用全局短视频环形队列
requestTimeoutMs	默认 3000，范围 100～10000	App读取推荐队列超时
maxBatches	默认 5，范围 1～20	过滤失效视频时最多补取批次
scanMultiplier	默认 5，范围 1～20	单批候选扫描倍数
keyTTLHours	默认 72，有效范围 24～720	推荐队列、偏移等Redis键TTL
laoSiJiAiMate.*	三项必须完整	AI女友V2第三方配置，仅App使用

base.totalWatch 不再作为免费观看次数来源，请从 app 配置移除。非VIP免费观看总次数改为通过后端系统配置 sys_conf（gpCode=common）中的 totalWatchCount 控制。

二、SKD运行配置

文件：config/skd.json

新增根节点：

{
  "shortRecommend": {
    "enabled": true,
    "cron": "CRON_TZ=Asia/Shanghai 0 5/10 * * * ?",
    "keyTTLHours": 72,
    "maxInitializationWrites": 50000
  }
}

字段说明：

字段	默认值/要求	说明
enabled	未配置默认 true	是否注册推荐队列任务并在启动时补建
cron	每10分钟健康检查	当天队列健康时不会重复生成
keyTTLHours	默认 72	必须与App保持一致
maxInitializationWrites	生产未配置默认 50000；非生产默认 0	首次推荐分初始化写入保护；显式 0 表示关闭限制

正式发布前必须统计未初始化短视频数。若超过保护阈值，任务会在任何批量写入前终止；应选择提前初始化、提高阈值或经确认后显式关闭限制。

三、Web运行配置

config/web.json 没有新增字段。Web需要发布代码以提供管理后台配置接口，但不需要新增运行配置。

四、后台和数据库业务配置

这些数据不会随Jenkins代码发布从测试库迁移到生产库，各环境需要单独配置。

4.1 亚模块配置（module_conf）

新增字段：

• onlineAt、offlineAt
• excludeLatest
• excludeRecommend
• searchOnlyWhenInactive
• haiJiaoStyle.sortRules[].refreshMode
• haiJiaoStyle.sortRules[].randomCandidateN

历史热门排序 val=2 未配置刷新字段时，会兼容为 RANDOM_TOP_N、候选数 30，不依赖可编辑标题。

4.2 付费引导（payment_guide）

按环境配置场景、用户分层、样式、文案、套餐、跳转、启用状态和有效期。 场景新增 DISCOUNT_COUNTDOWN；该场景只配置卡片内容，固定2小时倒计时由前端在每次App冷启动时本地重新创建，后端不使用 durationSeconds 计算倒计时。 新增 HOME_NEW_USER_FREE_TRIAL，用于“首页新用户免费 X 次试看”，X 读取 totalWatchCount；旧 HOME_NEW_USER 保留兼容代码但不再向 App/Web 返回。HOME_NEW_USER_FREE_TRIAL 与 HOME_OLD_USER 共用系统配置 paymentGuideHomeEnabled 作为首页场景总开关。 VIP_CONTENT_UPDATE.videoLimit 未配置或为 0 时默认返回4条，最大20条。 曝光记录集合 payment_guide_impression 由程序自动写入，不需初始化。

4.3 评论区Banner（scene_banner）

场景固定为 COMMENT_TOP，配置图片/GIF、内外链、排序、启用状态和上下架时间。 没有默认Banner，测试环境数据不会自动进入生产。

4.4 VIP卡片A/B（vip_card_experiment）

按环境使用真实套餐ID配置：

• A/B流量比例
• 套餐列表与默认套餐
• skinKey
• productBadges
• uiConfig.backgroundImage
• uiConfig.badgeStyles
• 实验结束时间

默认没有启用实验；未发布实验时会员套餐接口保持原有返回。统计事件集合由程序自动写入。

4.5 系统配置（sys_conf）

• 新增 freeTrialBadgeEnabled=true：服务启动时自动补充，上线前确认最终开关值。
• 新增 totalWatchCount（int）：非VIP用户单日免费观看上限，可编辑/可查看，默认值 3。
  • 示例：把 totalWatchCount 设置为 3，则 totalWatchCount 返回 3。
• 新增 paymentGuideHomeEnabled=true（bool）：首页付费引导共用开关，同时控制 HOME_NEW_USER_FREE_TRIAL 和 HOME_OLD_USER，可在 Web 系统通用配置中查看和编辑。
• 复用 aiGirlFriend=true：AI女友V2启用条件之一。

五、历史数据处理

media 新增 latestPublishedAt，历史数据必须回填，否则动漫/漫画最新排序会受缺失值影响：

db.media.updateMany(
  {
    status: 1,
    isDelete: false,
    latestPublishedAt: { $exists: false }
  },
  [
    {
      $set: {
        latestPublishedAt: {
          $ifNull: [
            "$contentUpdateTime",
            {
              $ifNull: [
                "$updateTime",
                "$createdAt"
              ]
            }
          ]
        }
      }
    }
  ]
)

执行前后应分别统计缺失数量并抽样核对排序结果。该脚本需单独执行，代码发布不会自动回填。

六、基础设施与发布范围

• 不新增Kafka Topic、MQ、Redis实例、端口或操作系统crontab。
• 继续使用现有MongoDB和Redis。
• App/H5接口发布 BUILD_ITEM=app。
• 管理后台接口发布 BUILD_ITEM=web。
• 推荐队列生成任务发布 BUILD_ITEM=skd。
• 服务启动会自动创建新增集合和索引，需确认MongoDB账号具有建索引权限。
• Redis推荐队列、版本、用户偏移及红点缓存均由程序自动创建，无需手工初始化。

七、不属于本分支的配置

• 测试环境手工调整的 imv2.baseUrl、imv2.dynamicConfigDomain、imv2.socketUrl 是环境修复，不是 feat/91-iteration 新增配置。
• H.265相关配置属于其他开发分支，不计入本迭代配置改动。