feat(payment): restore ezpay return orders

PAYWALL_API.md

@@ -0,0 +1,796 @@
+# 付费墙接口说明（PAYWALL_API）
+
+> 适用服务：`ai-boyfriend-unified`
+> 聊天接口路径：`POST /api/chat/send`
+> 历史接口路径：`GET /api/chat/history`
+> 私密解锁接口：`POST /api/chat/unlock-private`
+> WebSocket 路径：`/ws`
+> 字段命名：**camelCase**（与现有接口完全一致）
+> 文档语言：中文
+
+---
+
+## 总览：三个付费墙功能
+
+本文档覆盖三个会员限制功能，它们共用同一套「Elio 人设提示 + 是否展示开会员引导」的交互模式：
+
+| 功能 | 触发场景 | 限制对象 | 核心接口 | 核心字段 |
+|------|---------|---------|---------|---------|
+| ① 每日免费消息次数 | 用户发消息 | 注册非VIP（游客豁免） | `POST /api/chat/send` | `blocked` / `blockReason` / `blockDetail` |
+| ② 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 判定、订单接口、RabbitMQ 支付结果消费、VIP/DOL 发放逻辑已经写入后端。充值能否真正闭环取决于 `PAYMENT_SERVICE_URL`、`RABBITMQ_URL`、`orders` 表迁移以及支付服务 B 是否部署完成。若 B 未配置或不可用，聊天付费墙仍会返回 `showUpgrade=true`，但前端创建订单会失败，用户无法完成购买。
+
+---
+
+## 目录
+
+1. [设计原则与兼容性](#1-设计原则与兼容性)
+2. [功能①：每日免费消息次数](#2-功能每日免费消息次数)
+3. [功能②：AI 男友照片查看](#3-功能ai-男友照片查看)
+4. [功能③：私密消息查看](#4-功能私密消息查看)
+5. [POST /api/chat/send 完整响应结构](#5-post-apichatsend-完整响应结构)
+6. [WebSocket 事件](#6-websocket-事件)
+7. [支付服务与前端充值对接](#7-支付服务与前端充值对接)
+8. [前端接入清单](#8-前端接入清单)
+9. [当前未生效或依赖外部配置的内容](#9-当前未生效或依赖外部配置的内容)
+10. [通话与语音补充](#10-通话与语音补充)
+11. [Manager 图片上传错误码](#11-manager-图片上传错误码)
+12. [附录：图片意图关键词](#12-附录图片意图关键词)
+
+---
+
+## 1. 设计原则与兼容性
+
+1. **不新增聊天接口**：功能①②都复用现有 `POST /api/chat/send`，功能③复用 `GET /api/chat/history` 并新增一个 `POST /api/chat/unlock-private` 解锁接口。
+2. **响应结构固定**：付费墙相关字段在对应接口的**每一条**响应中都会出现（默认值 `false`/`null`），前端可稳定读取，不会"有时有有时没有"。
+3. **完全向后兼容**：所有现有字段原样保留，仅**新增**字段，不删改任何旧字段。
+4. **统一的展示判断字段 `showUpgrade`**：前端只需判断 `showUpgrade === true` 即展示"开通会员"引导，无需关心三个功能各自的内部逻辑。
+5. **Fail-safe**：所有付费墙逻辑失败时降级放行，不影响正常聊天。
+
+---
+
+## 2. 功能①：每日免费消息次数
+
+### 规则
+
+- 注册的非VIP用户每天最多免费发送 **30** 条消息（`FREE_DAILY_MSG_LIMIT=30`，按 UTC 日切）。
+- **游客不受限**；**VIP 不受限**。
+- 超限后，`POST /api/chat/send` 返回 `blocked=true`，`reply` 为空，前端据此弹开通会员提示。
+
+### 触发时的响应（data 字段）
+
+```json
+{
+  "mode": "http",
+  "reply": "",
+  "voiceUrl": "",
+  "audioUrl": "",
+  "intimacyChange": 0,
+  "newIntimacy": 0,
+  "relationshipStage": "密友",
+  "currentMood": "happy",
+  "messageId": "",
+  "isGuest": false,
+  "timestamp": 1780975180614,
+  "blocked": true,
+  "blockReason": "daily_limit",
+  "blockDetail": {
+    "type": "daily_msg_limit",
+    "usedToday": 30,
+    "limit": 30
+  },
+  "paywallTriggered": false,
+  "showUpgrade": false,
+  "imageType": null,
+  "imageUrl": null
+}
+```
+
+### 前端处理
+
+```
+if (data.blocked === true && data.blockReason === "daily_limit") {
+    展示"今日免费消息已用完，开通会员畅聊"引导 UI；
+    data.blockDetail 提供 usedToday / limit 供文案展示。
+}
+```
+
+> 注：每日限流当前用 `blocked/blockReason/blockDetail` 表达（沿用既有字段）。这与 `showUpgrade` 不冲突——限流场景 `showUpgrade=false`，前端通过 `blocked` 判断。
+
+---
+
+## 3. 功能②：AI 男友照片查看
+
+### 规则
+
+照片有两种触发方式：
+
+**(a) 用户主动索要**（如"发张照片"、"让我看看你"、"send me a photo"）：
+- **VIP** → 返回当天最接近当前时间的 Elio 日程图（`imageUrl` 有值，`imageType="elio_schedule"`）。
+- **非VIP**（含游客）→ 返回 Elio 升级提示，`showUpgrade=true`、`imageUrl=null`。
+
+**(b) Elio 主动发图**（无需用户索要）：
+- 普通聊天中，主生成模型判断"此刻适合发照片"（如夜晚、亲密氛围、用户在想念时），且用户为 **VIP**、当天主动照片配额未用完、当天确有日程图时，后端会在该条普通回复里**附带** `imageUrl`（HTTP）/ 推送 `image` 事件（WS）。
+- 非 VIP **静默不发、不打扰**（不弹升级提示）。
+- VIP 每天主动收图上限 **3 张**（`PHOTO_DAILY_LIMIT=3`，UTC 日切）。
+- 主动发图时 `paywallTriggered=false`、`showUpgrade=false`，前端只需照常渲染 `imageUrl` 即可。
+
+> 对前端而言协议不变：无论 (a) 还是 (b)，都通过同一个 `imageUrl` 字段（HTTP）或 `image` 事件（WS）拿到图片，直接渲染即可。
+
+### 响应字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `paywallTriggered` | bool | 本条是否触发图片付费墙 |
+| `showUpgrade` | bool | **前端是否展示开会员引导（核心判断字段）** |
+| `imageType` | string \| null | `null`=无图 / `"elio_schedule"`=Elio 日程图 |
+| `imageUrl` | string \| null | 图片公开 URL（VIP 有图时有值） |
+
+### 三种场景（data 字段示例）
+
+**A. 非VIP 请求图片（当前所有用户）：**
+```json
+{
+  "reply": "宝贝，我的照片只有会员才能看到哦……开通会员，我就把最近的照片发给你。😉",
+  "paywallTriggered": true,
+  "showUpgrade": true,
+  "imageType": null,
+  "imageUrl": null
+}
+```
+
+**B. VIP 请求图片 + 当天有图：**
+```json
+{
+  "reply": "嗯，你想看我……那就给你看一张。这是我今天下午的照片，你喜欢吗？",
+  "paywallTriggered": false,
+  "showUpgrade": false,
+  "imageType": "elio_schedule",
+  "imageUrl": "https://lehwkihwnlqkavhcspel.supabase.co/storage/v1/object/public/elio-schedules/schedules/42/a1b2c3d4.jpg"
+}
+```
+
+**C. VIP 请求图片 + 当天无图：**
+```json
+{
+  "reply": "今天还没拍什么好看的，等我有了好照片再发给你好不好？",
+  "paywallTriggered": false,
+  "showUpgrade": false,
+  "imageType": null,
+  "imageUrl": null
+}
+```
+
+> 上面仅列出付费墙字段，完整 data 结构见第 5 节。
+
+### 前端处理
+
+```
+1. 始终渲染 data.reply 为 Elio 文字气泡。
+2. if (data.showUpgrade) 展示开会员引导。
+3. if (data.imageUrl) 渲染图片（URL 可直接用于 <img src>，无需鉴权）。
+```
+
+---
+
+## 4. 功能③：私密消息查看
+
+### 规则
+
+- AI 回复中若包含私密/亲密/大尺度内容，后端**异步**判定并给该消息打标 `is_private=true`，生成模糊预告 `private_hint`。
+- 用户拉取历史时：
+  - **VIP** → 正常看到完整内容。
+  - **非VIP** → 私密消息内容被屏蔽，返回 `privateLocked=true` + `privateHint`，前端展示**锁定卡片**。
+- 非VIP 每天有 **1** 次免费解锁额度（`FREE_DAILY_PRIVATE_VIEWS=1`，UTC 日切）。
+- 解锁通过 `POST /api/chat/unlock-private` 完成；免费额度用尽则 `showUpgrade=true`，前端弹开通会员提示。
+
+### 4.1 GET /api/chat/history —— 历史含锁定标记
+
+每条消息（`data.messages[]`）字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `role` | string | `user` / `assistant` |
+| `content` | string | 消息内容；**私密且未解锁时为空字符串** |
+| `id` | string | 消息 ID（解锁时作为 messageId 传入） |
+| `created_at` | string | ISO8601 时间 |
+| `isPrivate` | bool \| null | 是否私密消息 |
+| `privateLocked` | bool \| null | **true = 当前用户无权查看，内容已锁定** |
+| `privateHint` | string \| null | 非会员看到的模糊预告文案 |
+
+`data` 顶层新增的配额状态字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `isVip` | bool | 当前用户是否 VIP |
+| `privateFreeLimit` | int | 每日免费查看上限（当前为 1） |
+| `privateUsedToday` | int | 今日已用次数 |
+| `privateCanViewFree` | bool | 今日是否还有免费额度（VIP 恒为 true） |
+
+**历史响应示例（非VIP，含一条锁定的私密消息）：**
+```json
+{
+  "messages": [
+    {
+      "role": "user",
+      "content": "今天好想你",
+      "id": "msg-1",
+      "created_at": "2026-06-09T03:00:00Z",
+      "isPrivate": false,
+      "privateLocked": false,
+      "privateHint": null
+    },
+    {
+      "role": "assistant",
+      "content": "",
+      "id": "msg-2",
+      "created_at": "2026-06-09T03:00:05Z",
+      "isPrivate": true,
+      "privateLocked": true,
+      "privateHint": "他好像想说什么悄悄话，解锁会员才能看到…"
+    }
+  ],
+  "total": 2,
+  "limit": 50,
+  "offset": 0,
+  "isVip": false,
+  "privateFreeLimit": 1,
+  "privateUsedToday": 0,
+  "privateCanViewFree": true
+}
+```
+
+### 4.2 POST /api/chat/unlock-private —— 解锁私密消息
+
+> 前端在用户点击锁定卡片时调用。**当前前端可暂不调用**，接口已就绪。
+
+**请求体：**
+```json
+{ "messageId": "msg-2" }
+```
+
+**响应 data 字段：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `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) 弹"开通会员查看更多私密消息"提示。
+```
+
+---
+
+## 5. POST /api/chat/send 完整响应结构
+
+`data` 字段的**全部字段**（现有 + 新增），所有 `/api/chat/send` 响应都包含：
+
+| 字段 | 类型 | 现有/新增 | 说明 |
+|------|------|----------|------|
+| `mode` | string | 现有 | `"http"` / `"websocket"` |
+| `reply` | string | 现有 | Elio 回复文本 |
+| `voiceUrl` | string | 现有 | 语音 URL（后台异步生成） |
+| `audioUrl` | string | 现有 | 兼容旧客户端 |
+| `intimacyChange` | int | 现有 | 亲密度变化（恒 0） |
+| `newIntimacy` | int | 现有 | 当前亲密度 |
+| `relationshipStage` | string | 现有 | 关系阶段 |
+| `currentMood` | string | 现有 | Elio 情绪 |
+| `messageId` | string | 现有 | 消息 ID |
+| `isGuest` | bool \| null | 现有 | 是否游客 |
+| `timestamp` | int | 现有 | Unix 毫秒时间戳 |
+| `blocked` | bool \| null | 现有 | 是否每日限流拦截（功能①） |
+| `blockReason` | string \| null | 现有 | `"daily_limit"` |
+| `blockDetail` | object \| null | 现有 | `{ type, usedToday, limit }` |
+| `paywallTriggered` | bool | 新增 | 是否触发图片付费墙（功能②） |
+| `showUpgrade` | bool | 新增 | **前端是否展示开会员引导** |
+| `imageType` | string \| null | 新增 | `null` / `"elio_schedule"` |
+| `imageUrl` | string \| null | 新增 | 图片公开 URL |
+
+---
+
+## 6. WebSocket 事件
+
+通过 `/ws` 连接时：
+
+### image 事件（VIP 有图时额外推送）
+```json
+{ "type": "image", "data": { "imageUrl": "https://.../schedules/42/xxx.jpg" } }
+```
+
+### paywall_status 事件（每次图片请求都推送）
+```json
+{
+  "type": "paywall_status",
+  "data": {
+    "paywallTriggered": true,
+    "showUpgrade": true,
+    "imageType": null,
+    "imageUrl": null
+  }
+}
+```
+
+文字回复（含升级提示）沿用现有整句推送机制，前端无需改动。
+
+---
+
+## 7. 支付服务与前端充值对接
+
+支付链路分三段：
+
+```text
+前端 -> 后端 A(ai-boyfriend-unified) -> 支付服务 B -> RabbitMQ -> 后端 A 发放权益 -> 前端刷新状态
+```
+
+### 7.1 后端 A 提供给前端的接口
+
+#### GET /api/payment/plans
+
+获取套餐列表，无需登录。前端在开通会员/充值弹窗中展示。
+
+响应 `data.plans[]` 字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `plan_id` | string | 前端创建订单时传入的套餐 ID |
+| `plan_name` | string | 展示名称 |
+| `order_type` | string | 传给支付服务 B 的订单类型 |
+| `amount_cents` | int | 金额，单位为分 |
+| `currency` | string | 当前为 `CNY` |
+| `vip_days` | int \| null | VIP 增加天数，`null` 表示永久或非 VIP 商品 |
+| `dol_amount` | int \| null | DOL 积分数量，VIP 商品为 `null` |
+
+当前套餐：
+
+| plan_id | plan_name | order_type | amount_cents | 发放内容 |
+|---|---|---:|---:|---|
+| `vip_monthly` | 月度会员 | `vip_monthly` | 999 | VIP +30 天 |
+| `vip_quarterly` | 季度会员 | `vip_quarterly` | 2499 | VIP +90 天 |
+| `vip_annual` | 年度会员 | `vip_annual` | 5999 | VIP +365 天 |
+| `vip_lifetime` | 永久会员 | `vip_lifetime` | 19999 | 永久 VIP |
+| `dol_100` | 100 DOL | `dol` | 600 | DOL +100 |
+| `dol_500` | 500 DOL | `dol` | 2800 | DOL +500 |
+
+#### POST /api/payment/create-order
+
+创建订单，需登录。
+
+```http
+POST /api/payment/create-order
+Authorization: Bearer <user_token>
+Content-Type: application/json
+```
+
+请求体：
+
+```json
+{
+  "planId": "vip_monthly",
+  "payChannel": "stripe",
+  "autoRenew": true
+}
+```
+
+字段说明：
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `planId` | 是 | 来自 `GET /api/payment/plans` 的 `plan_id` |
+| `payChannel` | 是 | 当前支持 `stripe` / `ezpay` |
+| `autoRenew` | 是 | 是否自动续费；DOL 和永久会员建议传 `false` |
+
+成功响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "orderId": "pay_abc123",
+    "payParams": {
+      "checkout_url": "https://pay.example.com/checkout/pay_abc123"
+    }
+  }
+}
+```
+
+`payParams` 是支付服务 B 返回给前端的拉起支付信息。对于 PayPal / Stripe Checkout / ezPay 这类浏览器跳转支付，B 必须在 `payParams` 内提供可直接打开的支付链接。
+
+前端读取支付链接的优先级：
+
+1. `payParams.checkout_url`
+2. `payParams.payment_url`
+3. `payParams.approval_url`
+4. `payParams.url`
+
+如果 B 使用 SDK 参数而不是跳转链接，也可以在 `payParams` 中返回 SDK 所需字段，但必须提前和前端约定字段名。后端 A 不解析 `payParams`，只做透传。
+
+错误：
+
+| 状态码 | 场景 |
+|---|---|
+| `400` | `planId` 无效，或 `payChannel` 不是 `stripe` / `ezpay` |
+| `401` | 未登录或 token 无效 |
+| `502` | `PAYMENT_SERVICE_URL` 未配置，或支付服务 B 创建订单失败 |
+| `500` | 后端 A 创建订单过程中发生未知错误 |
+
+#### GET /api/payment/order-status
+
+轮询订单状态，需登录。只能查询当前登录用户自己的订单。
+
+```http
+GET /api/payment/order-status?order_id=pay_abc123
+Authorization: Bearer <user_token>
+```
+
+响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "orderId": "pay_abc123",
+    "status": "pending",
+    "orderType": "vip_monthly",
+    "planId": "vip_monthly"
+  }
+}
+```
+
+`status` 取值：
+
+| status | 前端动作 |
+|---|---|
+| `pending` | 继续等待；建议每 3~5 秒轮询一次 |
+| `paid` | 停止轮询，刷新 VIP 状态或 DOL 余额 |
+| `failed` | 停止轮询，提示支付失败/取消 |
+
+#### GET /api/payment/vip-status
+
+查询当前用户 VIP 状态，需登录。
+
+```http
+GET /api/payment/vip-status
+Authorization: Bearer <user_token>
+```
+
+响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "isVip": true,
+    "vipExpiresAt": "2026-07-17T10:00:00+00:00"
+  }
+}
+```
+
+`vipExpiresAt=null` 表示永久会员。
+
+### 7.2 后端 A 调支付服务 B：创建订单
+
+后端 A 在收到前端 `create-order` 后，会调用支付服务 B：
+
+```http
+POST {PAYMENT_SERVICE_URL}/orders
+Authorization: Bearer {PAYMENT_SERVICE_API_KEY}
+Content-Type: application/json
+```
+
+请求体：
+
+```json
+{
+  "user_id": "用户 UUID",
+  "order_type": "vip_monthly",
+  "pay_channel": "stripe",
+  "automatic_renewal": true,
+  "amount_cents": 999,
+  "currency": "CNY"
+}
+```
+
+B 必须返回：
+
+```json
+{
+  "order_id": "pay_abc123",
+  "pay_params": {
+    "checkout_url": "https://pay.example.com/checkout/pay_abc123"
+  }
+}
+```
+
+约定：
+
+- `pay_params` 结构由支付服务 B 决定，后端 A 不解析，前端原样使用。
+- 浏览器跳转支付必须返回可打开的 URL，推荐统一使用 `pay_params.checkout_url`。
+- 当前 A/B 已确认支持的 `pay_channel` 是 `stripe` / `ezpay`；如果要接 PayPal，需要先由支付服务 B 的 `/orders` 支持 `paypal`，再把后端 A 的渠道校验和前端选项一起放开。
+- 后端 A 会把 `order_id`、`user_id`、`order_type`、`plan_id`、`status=pending` 写入本地 `orders` 表。
+- 发放什么权益由 A 侧 `plan_id` 决定，B 不需要知道 VIP 天数或 DOL 数量。
+
+### 7.3 支付服务 B 回传支付结果：RabbitMQ
+
+B 在支付成功或失败后，向 RabbitMQ 队列发布消息。
+
+| 项目 | 值 |
+|---|---|
+| 队列名 | 默认 `payment.events`，可通过 `RABBITMQ_QUEUE` 修改 |
+| 消息格式 | JSON UTF-8 |
+| 推荐属性 | durable queue + persistent message |
+
+消息体：
+
+```json
+{
+  "user_id": "用户 UUID",
+  "order_id": "pay_abc123",
+  "status": "success",
+  "info": ""
+}
+```
+
+字段：
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `user_id` | 是 | 当前订单所属用户 |
+| `order_id` | 是 | B 创建订单时返回给 A 的订单号 |
+| `status` | 是 | `success` / `fail` |
+| `info` | 否 | 失败原因或备注 |
+| `sign` | 视配置 | 如果 A 配置了 `PAYMENT_WEBHOOK_SECRET`，B 需要按双方约定签名 |
+
+A 收到消息后的行为：
+
+| status | A 侧处理 |
+|---|---|
+| `success` | 查本地订单 -> 按 `plan_id` 发放 VIP 或 DOL -> 订单置为 `paid` -> 推送 `payment_success` |
+| `fail` | 订单置为 `failed` -> 推送 `payment_failed` |
+
+幂等规则：同一订单已经是 `paid` 时，再收到 `success` 不会重复发放权益。
+
+### 7.4 支付 WebSocket 事件
+
+权益发放后，A 会通过 `/ws` 推送给在线用户。
+
+VIP 支付成功：
+
+```json
+{
+  "type": "payment_success",
+  "orderId": "pay_abc123",
+  "payType": "vip",
+  "planName": "月度会员",
+  "vipExpiresAt": "2026-07-17T10:00:00+00:00"
+}
+```
+
+DOL 支付成功：
+
+```json
+{
+  "type": "payment_success",
+  "orderId": "pay_def456",
+  "payType": "dol",
+  "planName": "100 DOL",
+  "dolAmount": 100,
+  "dolBalance": 350
+}
+```
+
+支付失败：
+
+```json
+{
+  "type": "payment_failed",
+  "orderId": "pay_abc123",
+  "info": "用户取消支付"
+}
+```
+
+### 7.5 环境变量
+
+```env
+PAYMENT_SERVICE_URL=https://pay.example.com
+PAYMENT_SERVICE_API_KEY=<A 调 B 的鉴权 key，可空>
+PAYMENT_SERVICE_TIMEOUT=10.0
+
+RABBITMQ_URL=amqp://user:pass@host:5672/vhost
+RABBITMQ_QUEUE=payment.events
+PAYMENT_WEBHOOK_SECRET=<MQ 消息签名密钥，可空>
+```
+
+---
+
+## 8. 前端接入清单
+
+### 8.1 触发开通会员入口
+
+前端需要在这些场景展示开通会员入口：
+
+- `POST /api/chat/send` 返回 `blocked=true` 且 `blockReason="daily_limit"`：每日免费消息用完。
+- `POST /api/chat/send` 返回 `showUpgrade=true`：照片付费墙或其他升级提示。
+- `POST /api/chat/unlock-private` 返回 `showUpgrade=true`：私密消息免费查看次数用完。
+- 用户主动点击会员中心/充值按钮。
+
+### 8.2 购买流程
+
+推荐流程：
+
+```text
+1. 打开升级弹窗
+2. GET /api/payment/plans 加载套餐
+3. 用户选择 planId、payChannel、autoRenew
+4. POST /api/payment/create-order
+5. 从 data.payParams 读取 checkout_url/payment_url/approval_url/url 并打开支付页，或按约定调用支付 SDK
+6. 每 3~5 秒 GET /api/payment/order-status?order_id=...
+7. 收到 paid 或 WebSocket payment_success 后停止轮询
+8. payType=vip 时调用 /api/payment/vip-status 并刷新本地会员状态
+9. payType=dol 时刷新用户资料或积分余额，使用最新 dolBalance
+```
+
+前端不应该自己推断权益是否发放成功，应以 `order-status=paid`、`payment_success` 或 `vip-status` 的后端结果为准。
+前端也不应该调用任何“确认支付成功”接口来改订单状态；订单状态只能由支付服务 B 接到支付通道回调后，通过 RabbitMQ 通知后端 A 更新。
+
+### 8.3 支付中状态
+
+创建订单后到支付结果返回前，按钮/弹窗应显示支付处理中，避免重复创建订单。用户关闭支付窗口时不要立即判定失败，继续轮询一小段时间或允许用户手动刷新状态。
+
+---
+
+## 9. 当前未生效或依赖外部配置的内容
+
+这些内容已经有后端代码或接口定义，但上线生效需要对应外部条件：
+
+| 功能 | 代码状态 | 生效条件 | 未满足时表现 |
+|---|---|---|---|
+| 付费墙展示 | 已接入聊天、图片、私密消息 | 无额外条件 | 非 VIP 返回 `blocked` 或 `showUpgrade` |
+| 创建订单 | 已有 `/api/payment/create-order` | 配置 `PAYMENT_SERVICE_URL`，支付服务 B 可访问，且 B 返回 `order_id` + 可拉起支付的 `pay_params` | 返回 502，或前端拿不到支付链接 |
+| 支付结果发放权益 | 已有 RabbitMQ 消费者 | 配置 `RABBITMQ_URL`，B 发布 `payment.events` 消息 | 订单停留 `pending`，VIP/DOL 不会到账 |
+| 订单轮询 | 已有 `/api/payment/order-status` | 执行 `database/payment-migration.sql` 创建 `orders` 表 | 查询不到订单或写入失败 |
+| VIP 解锁付费功能 | 已有 VIP 判定 | `users.is_vip=true` 且未过期，或永久会员 | 非 VIP 仍按限制处理 |
+| DOL 充值到账 | 已有 DOL 发放 | `users.dol_balance` 字段存在，B 回传成功 MQ | 前端不能只靠创建订单展示到账 |
+| 通话强制语音 | `/ws` 已支持 `call_text` / `call_audio` | TTS/STT 服务和前端通话 UI 接入 | STT/TTS 失败时返回 `call_error` 或无语音 |
+
+VIP 当前会解除/放宽的功能：
+
+- 每日免费消息次数限制。
+- 私密消息查看限制。
+- AI 男友照片查看和主动发图。
+- 语音/TTS 相关门控中需要 VIP 的普通语音回复。
+
+---
+
+## 10. 通话与语音补充
+
+近期 `/ws` 增加了通话消息类型，供前端通话 UI 使用：
+
+| type | 方向 | 说明 |
+|---|---|---|
+| `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` 进入聊天处理流程，目的是让通话场景生成可播放语音。普通文字聊天仍按原有语音门控和配额逻辑处理。
+
+---
+
+## 11. Manager 图片上传错误码
+
+用于 ai-boyfriend-Manager 后台 `POST/PUT /api/schedule` 的图片上传（运营管理员侧）。
+
+### 11.1 HTTP 400 — 格式不支持
+```json
+{ "detail": "不支持的文件格式 image/gif，仅允许 JPEG、PNG、WEBP" }
+```
+
+### 11.2 HTTP 400 — 文件过大（>10MB）
+```json
+{ "detail": "文件大小超过 10 MB 限制（当前 12582912 字节）" }
+```
+
+### 11.3 image_warning — 图片处理失败（非阻断，HTTP 200）
+
+图片通过校验但压缩/上传失败时不返回 500，而是 200 + `image_warning`，日程文字正常保存：
+```json
+{ "id": 42, "title": "苏州行", "image_url": null, "image_warning": "图片压缩失败：PIL 解码错误" }
+```
+
+| image_warning 示例 | 含义 |
+|---|---|
+| `"图片压缩失败：PIL 解码错误"` | 图片损坏或格式异常 |
+| `"图片上传失败：Storage 连接超时"` | Storage 网络异常 |
+| `"图片上传失败：权限不足"` | Bucket 权限配置错误 |
+| `"数据库写入 image_url 失败"` | 图片已传但 URL 未关联日程 |
+
+---
+
+## 12. 附录：图片意图关键词
+
+正则匹配，仅检测消息**前 600 字符**，大小写不敏感：
+
+| 语言 | 模式 |
+|------|------|
+| 中文 | `发.*照片`、`发.*图`、`让我看看你`、`给我看看你`、`你今天的照片`、`你最近的照片`、`你的照片`、`你的图片` |
+| 英文 | `send.*photo`、`send.*picture`、`show.*picture`、`let me see you`、`what do you look like` |
+
+---
+
+## 附：数据库迁移
+
+付费墙、支付、语音、图片功能依赖的库表迁移脚本：
+
+- `database/paywall-migration.sql` — users 会员字段（`is_vip`/`vip_expires_at`）、chat_messages 私密字段（`is_private`/`private_hint`）、`daily_private_unlocks` 表
+- `database/payment-migration.sql` — `orders` 表，用于本地订单状态、轮询和 MQ 回调发放权益
+- `database/migrate_elio_schedules_image_url.sql` — elio_schedules 表 `image_url` 列（功能②）
+- `database/voice-quota-migration.sql` — users 语音配额字段（`daily_voice_count`/`daily_voice_date`）
+- `database/photo-quota-migration.sql` — users 主动照片配额字段（`daily_photo_count`/`daily_photo_date`，Elio 主动发图日限）
+
+> 上线前需在 Supabase SQL Editor 执行以上脚本，并创建 `elio-schedules` 公开 Storage Bucket。
+> 若支付功能要闭环，必须确认 `orders` 表、`users.is_vip`、`users.vip_expires_at`、`users.dol_balance` 均已存在。

src/app/subscription/components/subscription-checkout-button.tsx

@@ -6,30 +6,45 @@
  */
 import { useEffect, useRef, useState } from "react";
 
+import { PendingPaymentOrderStorage } from "@/data/storage";
 import {
   usePaymentDispatch,
   usePaymentState,
 } from "@/stores/payment/payment-context";
+import { AppEnvUtil } from "@/utils";
 
 import { StripePaymentDialog } from "./stripe-payment-dialog";
 import { SubscriptionCtaButton } from "./subscription-cta-button";
 import styles from "./subscription-cta-button.module.css";
 
+const EZPAY_DEVELOPMENT_REDIRECT_DELAY_MS = 3000;
+
 export interface SubscriptionCheckoutButtonProps {
   /** 是否可用（未选套餐 / 未勾选协议 → false） */
   disabled?: boolean;
+  subscriptionType: "vip" | "voice";
 }
 
 export function SubscriptionCheckoutButton({
   disabled = false,
+  subscriptionType,
 }: SubscriptionCheckoutButtonProps) {
   const payment = usePaymentState();
   const paymentDispatch = usePaymentDispatch();
   const launchedNonceRef = useRef(0);
+  const ezpayRedirectTimeoutRef = useRef<number | null>(null);
   const [hiddenStripeClientSecret, setHiddenStripeClientSecret] = useState<
     string | null
   >(null);
 
+  useEffect(() => {
+    return () => {
+      if (ezpayRedirectTimeoutRef.current !== null) {
+        window.clearTimeout(ezpayRedirectTimeoutRef.current);
+      }
+    };
+  }, []);
+
   useEffect(() => {
     if (!payment.payParams || payment.launchNonce <= launchedNonceRef.current) {
       return;
@@ -43,6 +58,34 @@ export function SubscriptionCheckoutButton({
 
     const paymentUrl = getPaymentUrl(payment.payParams);
     if (paymentUrl) {
+      const isEzpay = isEzpayPayment(payment.payParams);
+
+      if (AppEnvUtil.isDevelopment() && isEzpay) {
+        if (ezpayRedirectTimeoutRef.current !== null) {
+          window.clearTimeout(ezpayRedirectTimeoutRef.current);
+        }
+
+        void redirectToEzpay({
+          orderId: payment.currentOrderId,
+          paymentUrl,
+          subscriptionType,
+          delayMs: EZPAY_DEVELOPMENT_REDIRECT_DELAY_MS,
+          setTimeoutId: (timeoutId) => {
+            ezpayRedirectTimeoutRef.current = timeoutId;
+          },
+        });
+        return;
+      }
+
+      if (isEzpay) {
+        void redirectToEzpay({
+          orderId: payment.currentOrderId,
+          paymentUrl,
+          subscriptionType,
+        });
+        return;
+      }
+
       window.location.href = paymentUrl;
       return;
     }
@@ -52,7 +95,13 @@ export function SubscriptionCheckoutButton({
       errorMessage:
         "Payment parameters did not include a supported URL or Stripe client secret.",
     });
-  }, [payment.launchNonce, payment.payParams, paymentDispatch]);
+  }, [
+    payment.currentOrderId,
+    payment.launchNonce,
+    payment.payParams,
+    paymentDispatch,
+    subscriptionType,
+  ]);
 
   const isLoading =
     payment.isCreatingOrder ||
@@ -70,6 +119,10 @@ export function SubscriptionCheckoutButton({
 
   const handleClick = () => {
     if (disabled || isLoading) return;
+    if (ezpayRedirectTimeoutRef.current !== null) {
+      window.clearTimeout(ezpayRedirectTimeoutRef.current);
+      ezpayRedirectTimeoutRef.current = null;
+    }
     setHiddenStripeClientSecret(null);
     paymentDispatch({ type: "PaymentCreateOrderSubmitted" });
   };
@@ -155,6 +208,46 @@ function getPaymentUrl(payParams: Record<string, unknown>): string | null {
   return null;
 }
 
+function isEzpayPayment(payParams: Record<string, unknown>): boolean {
+  const provider = payParams.provider;
+  return typeof provider === "string" && provider.toLowerCase() === "ezpay";
+}
+
+interface RedirectToEzpayInput {
+  orderId: string | null;
+  paymentUrl: string;
+  subscriptionType: "vip" | "voice";
+  delayMs?: number;
+  setTimeoutId?: (timeoutId: number) => void;
+}
+
+async function redirectToEzpay({
+  orderId,
+  paymentUrl,
+  subscriptionType,
+  delayMs = 0,
+  setTimeoutId,
+}: RedirectToEzpayInput): Promise<void> {
+  if (orderId) {
+    await PendingPaymentOrderStorage.setPendingOrder({
+      orderId,
+      payChannel: "ezpay",
+      subscriptionType,
+      createdAt: Date.now(),
+    });
+  }
+
+  if (delayMs > 0) {
+    const timeoutId = window.setTimeout(() => {
+      window.location.href = paymentUrl;
+    }, delayMs);
+    setTimeoutId?.(timeoutId);
+    return;
+  }
+
+  window.location.href = paymentUrl;
+}
+
 function getStripeClientSecret(
   payParams: Record<string, unknown>,
 ): string | null {

src/app/subscription/return/page.tsx

@@ -0,0 +1,86 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useRouter } from "next/navigation";
+
+import { MobileShell } from "@/app/_components/core";
+import { PendingPaymentOrderStorage } from "@/data/storage";
+import { ROUTES } from "@/router/routes";
+
+type ReturnStatus = "loading" | "missing";
+
+function buildSubscriptionUrl(subscriptionType: "vip" | "voice"): string {
+  if (subscriptionType === "voice") return `${ROUTES.subscription}?type=voice`;
+  return `${ROUTES.subscription}?type=vip`;
+}
+
+export default function SubscriptionReturnPage() {
+  const router = useRouter();
+  const [status, setStatus] = useState<ReturnStatus>("loading");
+
+  useEffect(() => {
+    let cancelled = false;
+
+    const redirectToSubscription = async () => {
+      const result = await PendingPaymentOrderStorage.getPendingOrder();
+      if (cancelled) return;
+
+      if (result.success && result.data !== null) {
+        router.replace(buildSubscriptionUrl(result.data.subscriptionType));
+        return;
+      }
+
+      setStatus("missing");
+    };
+
+    void redirectToSubscription();
+    return () => {
+      cancelled = true;
+    };
+  }, [router]);
+
+  return (
+    <MobileShell>
+      <div
+        style={{
+          minHeight: "60vh",
+          display: "flex",
+          flexDirection: "column",
+          alignItems: "center",
+          justifyContent: "center",
+          gap: "0.75rem",
+          padding: "2rem 1.5rem",
+          textAlign: "center",
+        }}
+      >
+        <h1 style={{ margin: 0, fontSize: "1.5rem", fontWeight: 600 }}>
+          Returning to subscription
+        </h1>
+        <p style={{ margin: 0, color: "#666", lineHeight: 1.5 }}>
+          {status === "loading"
+            ? "We are restoring your payment order."
+            : "No pending payment order was found. Please return to the subscription page."}
+        </p>
+        {status === "missing" ? (
+          <button
+            type="button"
+            onClick={() => router.replace(ROUTES.subscription)}
+            style={{
+              marginTop: "0.5rem",
+              padding: "0.75rem 1.5rem",
+              border: "none",
+              borderRadius: "12px",
+              background: "linear-gradient(135deg, #f96ADE, #f657A0)",
+              color: "white",
+              cursor: "pointer",
+              fontSize: "1rem",
+              fontWeight: 600,
+            }}
+          >
+            Back to subscription
+          </button>
+        ) : null}
+      </div>
+    </MobileShell>
+  );
+}

src/app/subscription/subscription-screen.tsx

@@ -20,6 +20,7 @@ import { Checkbox, MobileShell } from "@/app/_components/core";
 import { AppConstants } from "@/core/app_constants";
 import type { PaymentPlan } from "@/data/dto/payment";
 import { VIP_BENEFITS } from "@/data/constants/vip-benefits";
+import { PendingPaymentOrderStorage } from "@/data/storage";
 import {
   usePaymentDispatch,
   usePaymentState,
@@ -122,6 +123,7 @@ export function SubscriptionScreen({
   const payment = usePaymentState();
   const paymentDispatch = usePaymentDispatch();
   const refreshedPaidOrderRef = useRef<string | null>(null);
+  const resumedPendingOrderRef = useRef<string | null>(null);
 
   useEffect(() => {
     if (payment.status === "idle") {
@@ -136,6 +138,39 @@ export function SubscriptionScreen({
     userDispatch({ type: "UserFetch" });
   }, [payment.currentOrderId, payment.isPaid, userDispatch]);
 
+  useEffect(() => {
+    if (payment.status !== "ready") return;
+
+    let cancelled = false;
+
+    const resumePendingOrder = async () => {
+      const result = await PendingPaymentOrderStorage.getPendingOrderForType(
+        subscriptionType,
+      );
+      if (cancelled || !result.success || result.data === null) return;
+      if (payment.currentOrderId === result.data.orderId) return;
+      if (resumedPendingOrderRef.current === result.data.orderId) return;
+
+      resumedPendingOrderRef.current = result.data.orderId;
+      paymentDispatch({
+        type: "PaymentReturned",
+        orderId: result.data.orderId,
+      });
+    };
+
+    void resumePendingOrder();
+    return () => {
+      cancelled = true;
+    };
+  }, [payment.currentOrderId, payment.status, paymentDispatch, subscriptionType]);
+
+  useEffect(() => {
+    if (!payment.currentOrderId) return;
+    if (!payment.isPaid && payment.status !== "failed") return;
+
+    void PendingPaymentOrderStorage.clearPendingOrder();
+  }, [payment.currentOrderId, payment.isPaid, payment.status]);
+
   const plans = useMemo(
     () =>
       payment.plans
@@ -274,6 +309,7 @@ export function SubscriptionScreen({
           ) : (
             <SubscriptionCheckoutButton
               disabled={!canActivate}
+              subscriptionType={subscriptionType}
             />
           )}
         </div>

src/data/storage/index.ts

@@ -18,5 +18,6 @@ export * from "./chat/ichat_storage";
 export * from "./chat/local_chat_db";
 export * from "./chat/local_chat_storage";
 export * from "./chat/local_message";
+export * from "./payment/pending_payment_order_storage";
 export * from "./user/iuser_storage";
 export * from "./user/user_storage";

src/data/storage/payment/index.ts

@@ -0,0 +1,5 @@
+/**
+ * @file Payment storage barrel.
+ */
+
+export * from "./pending_payment_order_storage";

src/data/storage/payment/pending_payment_order_storage.ts

@@ -0,0 +1,52 @@
+"use client";
+
+import { z } from "zod";
+
+import { Result, type Result as ResultT, SpAsyncUtil } from "@/utils";
+
+import { StorageKeys } from "../storage_keys";
+
+const PendingPaymentOrderSchema = z.object({
+  orderId: z.string().min(1),
+  payChannel: z.literal("ezpay"),
+  subscriptionType: z.enum(["vip", "voice"]),
+  createdAt: z.number(),
+});
+
+export type PendingPaymentOrder = z.output<typeof PendingPaymentOrderSchema>;
+
+export class PendingPaymentOrderStorage {
+  private constructor() {}
+
+  static setPendingOrder(
+    order: PendingPaymentOrder,
+  ): Promise<ResultT<void>> {
+    return SpAsyncUtil.setJson(
+      StorageKeys.pendingPaymentOrder,
+      order,
+      PendingPaymentOrderSchema,
+    );
+  }
+
+  static getPendingOrder(): Promise<ResultT<PendingPaymentOrder | null>> {
+    return SpAsyncUtil.getJson(
+      StorageKeys.pendingPaymentOrder,
+      PendingPaymentOrderSchema,
+    );
+  }
+
+  static async getPendingOrderForType(
+    subscriptionType: PendingPaymentOrder["subscriptionType"],
+  ): Promise<ResultT<PendingPaymentOrder | null>> {
+    const result = await PendingPaymentOrderStorage.getPendingOrder();
+    if (Result.isErr(result)) return result;
+    if (result.data?.subscriptionType !== subscriptionType) {
+      return Result.ok(null);
+    }
+    return result;
+  }
+
+  static clearPendingOrder(): Promise<ResultT<void>> {
+    return SpAsyncUtil.remove(StorageKeys.pendingPaymentOrder);
+  }
+}

src/data/storage/storage_keys.ts

@@ -29,6 +29,9 @@ export const StorageKeys = {
   lastExternalBrowserDialogShown: "last_external_browser_dialog_shown",
   lastPwaEventReported: "last_pwa_event_reported",
   lastAppInfoReported: "last_app_info_reported",
+
+  // payment
+  pendingPaymentOrder: "pending_payment_order",
 } as const;
 
 export type StorageKey = (typeof StorageKeys)[keyof typeof StorageKeys];

src/stores/payment/payment-events.ts

@@ -10,6 +10,7 @@ export type PaymentEvent =
   | { type: "PaymentAutoRenewChanged"; autoRenew: boolean }
   | { type: "PaymentAgreementChanged"; agreed: boolean }
   | { type: "PaymentCreateOrderSubmitted" }
+  | { type: "PaymentReturned"; orderId: string }
   | { type: "PaymentRefreshVipStatus" }
   | { type: "PaymentLaunchFailed"; errorMessage: string }
   | { type: "PaymentErrorCleared" }

src/stores/payment/payment-machine.ts

@@ -300,6 +300,15 @@ export const paymentMachine = setup({
     },
   },
   on: {
+    PaymentReturned: {
+      target: ".pollingOrder",
+      actions: assign(({ event }) => ({
+        currentOrderId: event.orderId,
+        payParams: null,
+        orderStatus: "pending",
+        errorMessage: null,
+      })),
+    },
     PaymentLaunchFailed: {
       target: ".failed",
       actions: assign(({ event }) => ({