banlv/cozsweet-frontend-nextjs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(paywall): update private message unlock functionality and documentation

Browse Source
This commit is contained in:
chenhang
2026-06-23 17:53:48 +08:00
parent 05821d9a29
commit c8881a33c6
1 changed files with 153 additions and 178 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PAYWALL_API.md
+153 -178
View File
@@ -3,7 +3,7 @@
> 适用服务：`ai-boyfriend-unified` > 适用服务：`ai-boyfriend-unified`
> 聊天接口路径：`POST /api/chat/send` > 聊天接口路径：`POST /api/chat/send`
> 历史接口路径：`GET /api/chat/history` > 历史接口路径：`GET /api/chat/history`
> 私密解锁接口：`POST /api/chat/unlock-private` > 当前无单条私密消息解锁接口；VIP 自动查看全部私密消息
> WebSocket 路径：`/ws` > WebSocket 路径：`/ws`
> 字段命名：**camelCase**（与现有接口完全一致） > 字段命名：**camelCase**（与现有接口完全一致）
> 文档语言：中文 > 文档语言：中文
@@ -18,7 +18,7 @@
|------|---------|---------|---------|---------| |------|---------|---------|---------|---------|
| ① 每日免费消息次数 | 用户发消息 | 注册非VIP（游客豁免） | `POST /api/chat/send` | `blocked` / `blockReason` / `blockDetail` | | ① 每日免费消息次数 | 用户发消息 | 注册非VIP（游客豁免） | `POST /api/chat/send` | `blocked` / `blockReason` / `blockDetail` |
| ② AI 男友照片查看 | 用户请求发图 | 非VIP（含游客） | `POST /api/chat/send` | `paywallTriggered` / `showUpgrade` / `imageType` / `imageUrl` | | ② AI 男友照片查看 | 用户请求发图 | 非VIP（含游客） | `POST /api/chat/send` | `paywallTriggered` / `showUpgrade` / `imageType` / `imageUrl` |
| ③ 私密消息查看次数 | 查看被锁定的私密消息 | 非VIP（含游客） | `GET /api/chat/history` + `POST /api/chat/unlock-private` | `isPrivate` / `privateLocked` / `privateHint` / `showUpgrade` | | ③ 私密消息锁定 | 查看被锁定的私密消息 | 非VIP（含游客） | `GET /api/chat/history` | `isPrivate` / `privateLocked` / `privateHint` |
> **当前状态**：付费墙、VIP 判定、订单接口、RabbitMQ 支付结果消费、VIP/DOL 发放逻辑已经写入后端。充值能否真正闭环取决于 `PAYMENT_SERVICE_URL`、`RABBITMQ_URL`、`orders` 表迁移以及支付服务 B 是否部署完成。若 B 未配置或不可用，聊天付费墙仍会返回 `showUpgrade=true`，但前端创建订单会失败，用户无法完成购买。 > **当前状态**：付费墙、VIP 判定、订单接口、RabbitMQ 支付结果消费、VIP/DOL 发放逻辑已经写入后端。充值能否真正闭环取决于 `PAYMENT_SERVICE_URL`、`RABBITMQ_URL`、`orders` 表迁移以及支付服务 B 是否部署完成。若 B 未配置或不可用，聊天付费墙仍会返回 `showUpgrade=true`，但前端创建订单会失败，用户无法完成购买。
@@ -27,7 +27,7 @@
## 目录 ## 目录
1. [设计原则与兼容性](#1-设计原则与兼容性) 1. [设计原则与兼容性](#1-设计原则与兼容性)
2. [功能①：每日免费消息次数](#2-功能每日免费消息次数) 2. [功能①：免费消息次数限制](#2-功能免费消息次数限制)
3. [功能②：AI 男友照片查看](#3-功能ai-男友照片查看) 3. [功能②：AI 男友照片查看](#3-功能ai-男友照片查看)
4. [功能③：私密消息查看](#4-功能私密消息查看) 4. [功能③：私密消息查看](#4-功能私密消息查看)
5. [POST /api/chat/send 完整响应结构](#5-post-apichatsend-完整响应结构) 5. [POST /api/chat/send 完整响应结构](#5-post-apichatsend-完整响应结构)
@@ -35,7 +35,7 @@
7. [支付服务与前端充值对接](#7-支付服务与前端充值对接) 7. [支付服务与前端充值对接](#7-支付服务与前端充值对接)
8. [前端接入清单](#8-前端接入清单) 8. [前端接入清单](#8-前端接入清单)
9. [当前未生效或依赖外部配置的内容](#9-当前未生效或依赖外部配置的内容) 9. [当前未生效或依赖外部配置的内容](#9-当前未生效或依赖外部配置的内容)
10. [通话与语音补充](#10-通话与语音补充) 10. [Elio 回复语音字段](#10-elio-回复语音字段)
11. [Manager 图片上传错误码](#11-manager-图片上传错误码) 11. [Manager 图片上传错误码](#11-manager-图片上传错误码)
12. [附录：图片意图关键词](#12-附录图片意图关键词) 12. [附录：图片意图关键词](#12-附录图片意图关键词)
@@ -43,21 +43,22 @@
## 1. 设计原则与兼容性 ## 1. 设计原则与兼容性
1. **不新增聊天接口**：功能①②都复用现有 `POST /api/chat/send`，功能③复用 `GET /api/chat/history` 并新增一个 `POST /api/chat/unlock-private` 解锁接口。 1. **不新增聊天接口**：功能①②都复用现有 `POST /api/chat/send`，功能③只复用 `GET /api/chat/history`。
2. **响应结构固定**：付费墙相关字段在对应接口的**每一条**响应中都会出现（默认值 `false`/`null`），前端可稳定读取，不会"有时有有时没有"。 2. **响应结构固定**：付费墙相关字段在对应接口的**每一条**响应中都会出现（默认值 `false`/`null`），前端可稳定读取，不会"有时有有时没有"。
3. **完全向后兼容**：所有现有字段原样保留，仅**新增**字段，不删改任何旧字段。 3. **完全向后兼容**：所有现有字段原样保留，仅**新增**字段，不删改任何旧字段。
4. **统一的展示判断字段 `showUpgrade`**：前端只需判断 `showUpgrade === true` 即展示"开通会员"引导，无需关心三个功能各自的内部逻辑。 4. **升级引导判断**：图片付费墙用 `showUpgrade === true` 展示"开通会员"引导；消息次数限制沿用 `blocked === true` + `blockReason` 判断；私密消息只看 `privateLocked`。
5. **Fail-safe**：所有付费墙逻辑失败时降级放行，不影响正常聊天。 5. **Fail-safe**：所有付费墙逻辑失败时降级放行，不影响正常聊天。
--- ---
## 2. 功能①：每日免费消息次数 ## 2. 功能①：免费消息次数限制
### 规则 ### 规则
- 注册的非VIP用户每天最多免费发送 **30** 条消息（`FREE_DAILY_MSG_LIMIT=30`，按 UTC 日切）。 - 生产环境：游客每天最多免费发送 **30** 条消息，游客累计最多 **50** 条消息；注册的非 VIP 用户每天最多免费发送 **30** 条消息。
- **游客不受限**；**VIP 不受限**。 - 预发环境：上述数量为生产的 1/10，即游客每天 **3** 条、累计 **5** 条；注册非 VIP 每天 **3** 条。
- 超限后，`POST /api/chat/send` 返回 `blocked=true`，`reply` 为空，前端据此弹开通会员提示。 - **VIP 不受限**。
- 超限后，`POST /api/chat/send` 返回 `blocked=true`，`reply` 为空，前端据此弹开通会员提示。
### 触发时的响应（data 字段） ### 触发时的响应（data 字段）
@@ -75,7 +76,7 @@
"isGuest": false, "isGuest": false,
"timestamp": 1780975180614, "timestamp": 1780975180614,
"blocked": true, "blocked": true,
"blockReason": "daily_limit", "blockReason": "daily_limit",
"blockDetail": { "blockDetail": {
"type": "daily_msg_limit", "type": "daily_msg_limit",
"usedToday": 30, "usedToday": 30,
@@ -91,13 +92,18 @@
### 前端处理 ### 前端处理
``` ```
if (data.blocked === true && data.blockReason === "daily_limit") { if (data.blocked === true && data.blockReason === "daily_limit") {
展示"今日免费消息已用完，开通会员畅聊"引导 UI； 展示"今日免费消息已用完，开通会员畅聊"引导 UI；
data.blockDetail 提供 usedToday / limit 供文案展示。 data.blockDetail 提供 usedToday / limit 供文案展示。
} }
```
if (data.blocked === true && data.blockReason === "total_limit") {
> 注：每日限流当前用 `blocked/blockReason/blockDetail` 表达（沿用既有字段）。这与 `showUpgrade` 不冲突——限流场景 `showUpgrade=false`，前端通过 `blocked` 判断。 展示"游客免费消息已用完，注册或开通会员继续聊"引导 UI；
data.blockDetail 提供 usedTotal / limit 供文案展示。
}
```
> 注：消息次数限制当前用 `blocked/blockReason/blockDetail` 表达（沿用既有字段）。这与 `showUpgrade` 不冲突——限流场景 `showUpgrade=false`，前端通过 `blocked` 判断。
--- ---
@@ -175,151 +181,87 @@ if (data.blocked === true && data.blockReason === "daily_limit") {
--- ---
## 4. 功能③：私密消息查看 ## 4. 功能③：私密消息查看
### 规则 ### 规则
- AI 回复中若包含私密/亲密/大尺度内容，后端**异步**判定并给该消息打标 `is_private=true`，生成模糊预告 `private_hint`。 - AI 回复中若包含私密/亲密/大尺度内容，后端**异步**判定并给该消息打标 `is_private=true`，生成模糊预告 `private_hint`。
- 用户拉取历史时： - 用户拉取历史时：
- **VIP** → 正常看到完整内容。 - **VIP** → 所有历史私密消息直接返回完整内容；之前锁住的内容也会一起解开，后续也不再锁。
- **非VIP** → 私密消息内容被屏蔽，返回 `privateLocked=true` + `privateHint`，前端展示**锁定卡片**。 - **非VIP** → 私密消息内容被屏蔽，返回 `privateLocked=true` + `privateHint`，前端展示**锁定卡片**。
- 非VIP 每天有 **1** 次免费解锁额度（`FREE_DAILY_PRIVATE_VIEWS=1`，UTC 日切）。 - 当前产品**没有单条私密消息解锁流程**。是否展示完整内容，只取决于当前用户是不是 VIP。
- 解锁通过 `POST /api/chat/unlock-private` 完成；免费额度用尽则 `showUpgrade=true`，前端弹开通会员提示。
### 4.1 GET /api/chat/history —— 历史含锁定标记
### 4.1 GET /api/chat/history —— 历史含锁定标记
每条消息（`data.messages[]`）字段：
每条消息（`data.messages[]`）字段：
| 字段 | 类型 | 说明 |
| 字段 | 类型 | 说明 | |------|------|------|
|------|------|------| | `role` | string | `user` / `assistant` |
| `role` | string | `user` / `assistant` | | `type` | string | `text` / `voice`；有 Elio 语音地址时为 `voice` |
| `content` | string | 消息内容；**私密且未解锁时为空字符串** | | `content` | string | 消息内容；**非VIP查看私密消息时为空字符串** |
| `id` | string | 消息 ID（解锁时作为 messageId 传入） | | `id` | string | 消息 ID |
| `created_at` | string | ISO8601 时间 | | `created_at` | string | ISO8601 时间 |
| `isPrivate` | bool \| null | 是否私密消息 | | `audioUrl` | string \| null | Elio 语音播放 URL；用户文本消息为 `null` |
| `privateLocked` | bool \| null | **true = 当前用户无权查看，内容已锁定** | | `voiceUrl` | string \| null | 同 `audioUrl`，兼容旧字段 |
| `privateHint` | string \| null | 非会员看到的模糊预告文案 | | `isPrivate` | bool \| null | 是否私密消息 |
| `privateLocked` | bool \| null | **true = 当前用户无权查看，内容已锁定** |
`data` 顶层新增的配额状态字段： | `privateHint` | string \| null | 非会员看到的模糊预告文案 |
| 字段 | 类型 | 说明 | `data` 顶层建议前端只关心：
|------|------|------|
| `isVip` | bool | 当前用户是否 VIP | | 字段 | 类型 | 说明 |
| `privateFreeLimit` | int | 每日免费查看上限（当前为 1） | |------|------|------|
| `privateUsedToday` | int | 今日已用次数 | | `isVip` | bool | 当前用户是否 VIP |
| `privateCanViewFree` | bool | 今日是否还有免费额度（VIP 恒为 true） |
> 兼容旧版本客户端，后端可能仍返回 `privateFreeLimit`、`privateUsedToday`、`privateCanViewFree` 等旧字段；当前前端可以忽略。
**历史响应示例（非VIP，含一条锁定的私密消息）：**
```json **历史响应示例（非VIP，含一条锁定的私密消息）：**
{ ```json
"messages": [ {
{ "messages": [
"role": "user", {
"content": "今天好想你", "role": "user",
"id": "msg-1", "type": "text",
"created_at": "2026-06-09T03:00:00Z", "content": "今天好想你",
"isPrivate": false, "id": "msg-1",
"privateLocked": false, "created_at": "2026-06-09T03:00:00Z",
"privateHint": null "audioUrl": null,
}, "voiceUrl": null,
{ "isPrivate": false,
"role": "assistant", "privateLocked": false,
"content": "", "privateHint": null
"id": "msg-2", },
"created_at": "2026-06-09T03:00:05Z", {
"isPrivate": true, "role": "assistant",
"privateLocked": true, "type": "voice",
"privateHint": "他好像想说什么悄悄话，解锁会员才能看到…" "content": "",
} "id": "msg-2",
], "created_at": "2026-06-09T03:00:05Z",
"total": 2, "audioUrl": "https://.../audio/msg-2.mp3",
"limit": 50, "voiceUrl": "https://.../audio/msg-2.mp3",
"offset": 0, "isPrivate": true,
"isVip": false, "privateLocked": true,
"privateFreeLimit": 1, "privateHint": "他好像想说什么悄悄话，解锁会员才能看到…"
"privateUsedToday": 0, }
"privateCanViewFree": true ],
} "total": 2,
``` "limit": 50,
"offset": 0,
### 4.2 POST /api/chat/unlock-private —— 解锁私密消息 "isVip": false
}
> 前端在用户点击锁定卡片时调用。**当前前端可暂不调用**，接口已就绪。 ```
**请求体：** ### 4.2 前端处理
```json
{ "messageId": "msg-2" } ```
``` 拉取 history：
对每条 privateLocked===true 的消息，渲染为锁定卡片（展示 privateHint）。
**响应 data 字段：**
用户开通 VIP 后：
| 字段 | 类型 | 说明 | 重新拉取 history；
|------|------|------| 之前被锁住的私密消息会直接返回完整 content，不需要再调额外解锁接口。
| `unlocked` | bool | true = 已解锁，可显示 content | ```
| `content` | string \| null | 解锁成功时返回完整私密内容，否则 null |
| `showUpgrade` | bool | **true = 免费次数用尽，前端弹开通会员提示** |
| `paywallTriggered` | bool | 同 showUpgrade，业务语义标识 |
| `privateFreeLimit` | int | 每日免费查看上限 |
| `privateUsedToday` | int | 今日已用次数 |
| `reason` | string | `ok` / `quota_exceeded` / `not_private` / `not_found` |
**场景 1 — 非VIP 当日仍有免费额度（解锁成功，消耗 1 次）：**
```json
{
"unlocked": true,
"content": "（完整的私密回复内容…）",
"showUpgrade": false,
"paywallTriggered": false,
"privateFreeLimit": 1,
"privateUsedToday": 1,
"reason": "ok"
}
```
**场景 2 — 非VIP 当日免费额度已用尽（需开会员）：**
```json
{
"unlocked": false,
"content": null,
"showUpgrade": true,
"paywallTriggered": true,
"privateFreeLimit": 1,
"privateUsedToday": 1,
"reason": "quota_exceeded"
}
```
**场景 3 — VIP 用户（直接解锁，不消耗额度）：**
```json
{
"unlocked": true,
"content": "（完整的私密回复内容…）",
"showUpgrade": false,
"paywallTriggered": false,
"privateFreeLimit": 1,
"privateUsedToday": 0,
"reason": "ok"
}
```
**场景 4 — 消息不存在 / 非私密：**
```json
{ "unlocked": false, "content": null, "showUpgrade": false, "reason": "not_found" }
```
```json
{ "unlocked": true, "content": "（普通内容）", "showUpgrade": false, "reason": "not_private" }
```
### 前端处理
```
拉取 history：
对每条 privateLocked===true 的消息，渲染为锁定卡片（展示 privateHint）。
用户点击锁定卡片 → 调 POST /api/chat/unlock-private { messageId }：
if (resp.unlocked === true) 用 resp.content 替换卡片，显示完整内容；
else if (resp.showUpgrade === true) 弹"开通会员查看更多私密消息"提示。
```
--- ---
@@ -342,7 +284,7 @@ if (data.blocked === true && data.blockReason === "daily_limit") {
| `messageId` | string | 现有 | 消息 ID | | `messageId` | string | 现有 | 消息 ID |
| `isGuest` | bool \| null | 现有 | 是否游客 | | `isGuest` | bool \| null | 现有 | 是否游客 |
| `timestamp` | int | 现有 | Unix 毫秒时间戳 | | `timestamp` | int | 现有 | Unix 毫秒时间戳 |
| `blocked` | bool \| null | 现有 | 是否每日限流拦截（功能①） | | `blocked` | bool \| null | 现有 | 是否消息次数限流拦截（功能①） |
| `blockReason` | string \| null | 现有 | `"daily_limit"` / `"total_limit"` | | `blockReason` | string \| null | 现有 | `"daily_limit"` / `"total_limit"` |
| `blockDetail` | object \| null | 现有 | 每日限制：`{ type, usedToday, limit }`；游客总量限制：`{ type, usedTotal, limit }` | | `blockDetail` | object \| null | 现有 | 每日限制：`{ type, usedToday, limit }`；游客总量限制：`{ type, usedTotal, limit }` |
| `paywallTriggered` | bool | 新增 | 是否触发图片付费墙（功能②） | | `paywallTriggered` | bool | 新增 | 是否触发图片付费墙（功能②） |
@@ -687,7 +629,7 @@ PAYMENT_WEBHOOK_SECRET=<MQ 消息签名密钥，可空>
- `POST /api/chat/send` 返回 `blocked=true` 且 `blockReason="daily_limit"`：每日免费消息用完。 - `POST /api/chat/send` 返回 `blocked=true` 且 `blockReason="daily_limit"`：每日免费消息用完。
- `POST /api/chat/send` 返回 `showUpgrade=true`：照片付费墙或其他升级提示。 - `POST /api/chat/send` 返回 `showUpgrade=true`：照片付费墙或其他升级提示。
- `POST /api/chat/unlock-private` 返回 `showUpgrade=true`：私密消息免费查看次数用完。 - `GET /api/chat/history` 返回 `privateLocked=true`：这条私密消息当前只有 VIP 可见。
- 用户主动点击会员中心/充值按钮。 - 用户主动点击会员中心/充值按钮。
### 8.2 购买流程 ### 8.2 购买流程
@@ -727,7 +669,7 @@ PAYMENT_WEBHOOK_SECRET=<MQ 消息签名密钥，可空>
| 订单轮询 | 已有 `/api/payment/order-status` | 执行 `database/payment-migration.sql` 创建 `orders` 表 | 查询不到订单或写入失败 | | 订单轮询 | 已有 `/api/payment/order-status` | 执行 `database/payment-migration.sql` 创建 `orders` 表 | 查询不到订单或写入失败 |
| VIP 解锁付费功能 | 已有 VIP 判定 | `users.is_vip=true` 且未过期，或永久会员 | 非 VIP 仍按限制处理 | | VIP 解锁付费功能 | 已有 VIP 判定 | `users.is_vip=true` 且未过期，或永久会员 | 非 VIP 仍按限制处理 |
| DOL 充值到账 | 已有 DOL 发放 | `users.dol_balance` 字段存在，B 回传成功 MQ | 前端不能只靠创建订单展示到账 | | DOL 充值到账 | 已有 DOL 发放 | `users.dol_balance` 字段存在，B 回传成功 MQ | 前端不能只靠创建订单展示到账 |
| 通话强制语音 | `/ws` 已支持 `call_text` / `call_audio` | TTS/STT 服务和前端通话 UI 接入 | STT/TTS 失败时返回 `call_error` 或无语音 | | Elio 回复语音 | `POST /api/chat/send` 已返回 `voiceUrl` / `audioUrl` 字段；`GET /api/chat/history` 的消息项也返回 `type` / `audioUrl`；WS 模式会推 `voice_ready` | TTS 服务可用，且前端按字段播放 | HTTP 首包里通常为空，后台生成后写入 DB；稍后拉 history 可拿到 `audioUrl` |
VIP 当前会解除/放宽的功能： VIP 当前会解除/放宽的功能：
@@ -738,21 +680,54 @@ VIP 当前会解除/放宽的功能：
--- ---
## 10. 通话与语音补充 ## 10. Elio 回复语音字段
近期 `/ws` 增加了通话消息类型，供前端通话 UI 使用： 当前产品口径是 **Elio 可以发语音给用户，用户不需要发语音给 Elio**。因此聊天发送接口只需要前端传文字 `message`，不需要用户音频上传字段。
| type | 方向 | 说明 | ### 10.1 POST /api/chat/send 中的语音字段
|---|---|---|
| `call_start` | 前端 -> 后端 | 进入通话态 |
| `call_end` | 前端 -> 后端 | 结束通话态，后端返回 `call_ended` |
| `call_text` | 前端 -> 后端 | 前端已完成本地 STT，直接把文字发给后端 |
| `call_audio` | 前端 -> 后端 | 前端上传 base64 音频，后端 STT 后再进入 AI 回复 |
| `call_stt_result` | 后端 -> 前端 | 后端 STT 识别出的文字 |
| `call_stt_empty` | 后端 -> 前端 | 没识别到有效文字 |
| `call_error` | 后端 -> 前端 | 音频、STT 或通话处理错误 |
`call_text` 和 `call_audio` 会以 `force_voice=true` 进入聊天处理流程，目的是让通话场景生成可播放语音。普通文字聊天仍按原有语音门控和配额逻辑处理。 `POST /api/chat/send` 的 `data` 中包含：
| 字段 | 说明 |
|---|---|
| `voiceUrl` | Elio 回复语音 URL，新字段 |
| `audioUrl` | 兼容旧客户端，语义同 `voiceUrl` |
当前 HTTP 模式下，AI 回复文本会立即返回，TTS 语音在后台异步生成，所以首包里通常是：
```json
{
"reply": "AI 的回复内容",
"voiceUrl": "",
"audioUrl": ""
}
```
后台生成完成后会把语音地址写入 `chat_messages.voice_url`。`GET /api/chat/history` 会把这条消息返回为 `type="voice"`，并带 `audioUrl` / `voiceUrl`。因此前端若走 HTTP 首包，不能假设立刻拿到语音 URL；可以稍后刷新 history 获取。
语音消息对应的文字版不需要单独转写接口：
| 场景 | 前端直接读取的字段 |
|---|---|
| `POST /api/chat/send` 首包 | `reply` |
| `GET /api/chat/history` 单条消息 | `content` |
### 10.2 WebSocket 模式的语音事件
如果前端使用 WebSocket 模式，后端会在分句 TTS 生成完成后推送：
```json
{
"type": "voice_ready",
"index": 0,
"voiceUrl": "https://.../audio/xxx.mp3",
"audioUrl": "https://.../audio/xxx.mp3"
}
```
前端应优先使用 `voiceUrl` 播放，`audioUrl` 仅作为旧字段兼容。
> 注意：当前 `/api/chat/send` 请求体没有用户音频字段；用户侧语音输入不是当前需求，不需要额外转写字段或用户 `audioUrl`。
--- ---