# 亚模块、更新红点、AI 女友接口

本文只列 App/H5 需要对接的服务端字段。接口沿用现有登录鉴权和统一响应结构，业务数据位于 `data`。

## 1. 亚模块列表

```http
GET /api/app/modules/list
```

后端只返回当前已启用且处于上下架时间范围内的亚模块。亚模块对象新增：

```json
{
  "id": "66a000000000000000000001",
  "moduleName": "示例模块",
  "onlineAt": "2026-07-27T08:00:00Z",
  "offlineAt": "2026-08-27T08:00:00Z",
  "excludeLatest": true,
  "excludeRecommend": true,
  "searchOnlyWhenInactive": true
}
```

- `onlineAt`、`offlineAt` 为空表示不限制。
- App 无需自行判断时间，也不要缓存已经下架的亚模块。
- 亚模块失效后，普通列表、模块/专题入口、分享页和直接视频详情均不可访问；搜索结果仍可访问。

## 2. 首页及亚模块更新红点

```http
GET /api/app/content/update-markers
```

返回：

```json
{
  "code": 200,
  "data": {
    "homeLatestAt": "2026-07-27T08:10:00Z",
    "todayLatestAt": "2026-07-27T08:10:00Z",
    "modules": [
      {
        "moduleId": "66a000000000000000000001",
        "latestAt": "2026-07-27T08:05:00Z"
      }
    ]
  }
}
```

- `homeLatestAt`：主页“最新”内容最近审核通过时间。
- `todayLatestAt`：“今日更新”最近审核通过时间；“今日”按 UTC+8 自然日计算。
- `modules[].latestAt`：该亚模块视频最近审核通过时间；动漫、漫画等媒体取最近新增或子集更新时间。
- 没有内容时对应时间为 `null`。
- 客户端保存各入口的本地 `lastReadAt`。当 `latestAt > lastReadAt` 时显示红点，用户点击入口后更新本地已读时间。

## 3. 搜索专属视频访问

视频关键字搜索和片库搜索的每个视频对象新增：

```json
{
  "id": "66b000000000000000000001",
  "searchAccessToken": "短时效凭证"
}
```

从搜索结果进入视频详情时原样传回：

```http
GET /api/app/vid/info?videoID=66b000000000000000000001&searchAccessToken=短时效凭证
```

- 普通视频详情可不传 `searchAccessToken`。
- 凭证与当前用户、视频绑定，有效期 10 分钟。
- 仅搜索可见的视频未传、传错或凭证过期时，接口按内容不存在处理。

## 4. AI 女友入口

App 从现有启动配置判断入口是否展示：

```http
GET /api/app/ping/v
```

使用字段 `aiGirlFriend`：

```json
{
  "aiGirlFriend": true
}
```

`aiGirlFriend=true` 时展示入口。点击入口后调用：

```http
POST /api/app/aimatev2/url
```

无需请求体。成功响应：

```json
{
  "code": 200,
  "data": {
    "url": "https://example.com/ai"
  }
}
```

前端打开 `data.url`。该接口会先处理上一次未结算余额，再把用户主钱包的可用金币上分到 AI 女友；换算比例为 `10金币=1元`，前端不参与金额换算。

用户关闭 AI 女友页面或返回 App 后，调用现有钱包接口刷新余额：

```http
GET /api/app/mine/wallet
```

钱包接口会先尝试把 AI 女友剩余余额下分回主钱包，然后返回最新钱包数据；响应结构不变。历史别名 `GET /api/app/mine/qianbao` 同步支持，但新代码统一使用 `/mine/wallet`。

旧 `/api/app/aimate/*` 接口仅为旧客户端保留，新版 App/H5 不再调用 `login`、`getBalance`、`currencys` 或 `exchange`，也不再直接使用 `ping/v` 返回的 `aiMateH5`。

## 5. 管理后台配置

管理后台沿用现有接口：

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

新增请求字段：

```json
{
  "onlineAt": "2026-07-27T08:00:00Z",
  "offlineAt": "2026-08-27T08:00:00Z",
  "excludeLatest": true,
  "excludeRecommend": true,
  "searchOnlyWhenInactive": true
}
```

编辑时清空时间限制：

```json
{
  "id": "66a000000000000000000001",
  "clearOnlineAt": true,
  "clearOfflineAt": true
}
```

`offlineAt` 必须晚于 `onlineAt`，否则保存失败。