# 91迭代配置改动点

适用分支：`feat/91-iteration`

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

## 一、App运行配置

文件：`config/app.json`

新增根节点：

```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`

新增根节点：

```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`，历史数据必须回填，否则动漫/漫画最新排序会受缺失值影响：

```javascript
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相关配置属于其他开发分支，不计入本迭代配置改动。