Initial commit

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-15 13:57:10 +08:00
commit 8679200f41
1897 changed files with 257900 additions and 0 deletions
@@ -0,0 +1,156 @@
+# 亚模块、更新红点、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`，否则保存失败。