cozsweet-frontend-nextjs/docs/frontend-integration/2026-07-22-private-zoom-rename.md

# Private Zoom 全链路改名联调说明

- 日期：2026-07-22
- 目标环境：本地、`pre`、生产
- 当前状态：已实现待联调

## 1. 目标

原功能名称存在拼写错误。本次将前端、unified 后端、Manager、数据库、埋点和文档中的正式命名统一为 `Private Zoom`，并同步切换页面路由、API 路径和公开枚举值。

## 2. 环境地址

| 环境 | 前端 | API Base URL |
| --- | --- | --- |
| `pre` | `https://frontend-test.banlv-ai.com` | `https://proapi.banlv-ai.com` |
| 生产 | `https://cozsweet.com` | `https://api.banlv-ai.com` |

## 3. 前端影响

前端已完成以下修改：

- 页面路由统一为 `/private-zoom` 和 `/characters/{characterSlug}/private-zoom`。
- 外部入口参数统一为 `target=private-zoom`。
- 支付回跳参数统一为 `returnTo=private-zoom`。
- 类型、Repository、API client、XState actor、Provider 和资源目录统一使用 `privateZoom`、`PrivateZoom`、`private-zoom` 或 `private_zoom`。
- 埋点键统一为 `navigation.private_zoom`、`chat.open_private_zoom_from_avatar` 等新名称。
- 角色能力字段统一为 `capabilities.privateZoom`。

旧页面和旧查询参数不再作为正式入口保留。发布时必须让前后端属于同一个发布批次。

## 4. API 变更清单

所有接口都使用 `Authorization: Bearer <TOKEN>`，响应继续使用现有统一 envelope。请求与响应中未列出的业务字段保持原类型和含义。

| 方法 | 新路径 | 用途 |
| --- | --- | --- |
| `GET` | `/api/private-zoom/albums` | 查询付费图片包 |
| `POST` | `/api/private-zoom/albums/{albumId}/unlock` | 解锁图片包 |
| `GET` | `/api/private-zoom/moments` | 查询朋友圈式内容 |
| `POST` | `/api/private-zoom/moments/{momentId}/unlock` | 解锁单条内容 |
| `GET` | `/api/private-zoom/config` | 查询当前角色和用户解锁配置 |
| `GET` | `/api/private-zoom/diaries` | 查询关系日记 |
| `POST` | `/api/private-zoom/diaries/{diaryId}/seen` | 标记关系日记已读 |
| `POST` | `/api/private-zoom/diaries/{diaryId}/unlock` | 解锁关系日记 |

### 4.1 图片包列表

```http
GET /api/private-zoom/albums?characterId=elio&limit=20
Authorization: Bearer <TOKEN>
```

| 字段 | 位置 | 类型 | 必填 | 可为 `null` | 说明 |
| --- | --- | --- | --- | --- | --- |
| `characterId` | query | string | 是 | 否 | 角色 ID |
| `limit` | query | integer | 否 | 否 | `1-50`，默认 `20` |
| `cursor` | query | string | 否 | 是 | 分页游标 |

调用示例：

```bash
curl 'https://proapi.banlv-ai.com/api/private-zoom/albums?characterId=elio&limit=20' \
  -H 'Authorization: Bearer <TOKEN>'
```

### 4.2 解锁图片包

```http
POST /api/private-zoom/albums/{albumId}/unlock
Authorization: Bearer <TOKEN>
Content-Type: application/json
```

| 字段 | 位置 | 类型 | 必填 | 可为 `null` | 说明 |
| --- | --- | --- | --- | --- | --- |
| `albumId` | path | string | 是 | 否 | 图片包 ID |
| `expectedCost` | body | integer | 否 | 是 | 前端确认价格；与后端价格不一致时拒绝解锁 |

```bash
curl -X POST 'https://proapi.banlv-ai.com/api/private-zoom/albums/<ALBUM_ID>/unlock' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"expectedCost":320}'
```

### 4.3 Moments 内容与解锁

```http
GET /api/private-zoom/moments?characterId=elio&limit=20
POST /api/private-zoom/moments/{momentId}/unlock
```

解锁请求体与图片包一致，`expectedCost` 为可选整数。响应中的正式分类值同步改为：

```json
{
  "lockDetail": {
    "type": "private_zoom_moment",
    "reason": "private_zoom_moment"
  }
}
```

## 5. 其他公开值

| 使用位置 | 新值 | 类型 |
| --- | --- | --- |
| `/api/chat/unlock-private` 的 `lockType` 别名 | `private_zoom` | string enum |
| 日程导入 `contentType` 别名 | `private_zoom` | string enum，归一化为 `paid_content` |
| 外部入口 `target` | `private-zoom` | string enum |
| 支付回跳 `returnTo` | `private-zoom` | string enum |
| 锁定详情分类 | `private_zoom_moment` | string enum |

## 6. 数据库迁移

因为 `pre` 与生产当前共用 `https://dbapi.banlv-ai.com`，预发部署前先执行 unified 仓库中的临时桥接脚本：

```text
database/private-zoom-bridge.sql
```

桥接脚本会创建新表并在切换窗口内保持新旧解锁写入双向同步。生产前后端全部切换完成后，再执行最终迁移：

```text
database/private-zoom-migration.sql
```

迁移会在同一事务中完成：

- 将历史解锁表无损重命名；新旧表同时存在时先合并再删除旧表。
- 重命名关联约束、索引、策略和触发器。
- 合并 `users.preferences` 中历史解锁键，防止已解锁内容重新锁定。
- 把 `credit_ledger` 历史分类迁移到 `private_zoom` 和 `private_zoom_moment`。
- 定向迁移历史埋点键、页面 URL 和系统媒体路径，不改写用户聊天正文。
- 删除切换窗口使用的双写触发器和函数。
- 支持重复执行。

## 7. 兼容性与发布顺序

这是破坏性命名修正，不保留旧 API、旧页面路由或旧公开枚举作为正式兼容层。必须按以下顺序发布：

1. 备份数据库并记录当前 unified、前端和 Manager 版本。
2. 执行 `database/private-zoom-bridge.sql`，确认新旧表双向写入一致。
3. 部署 unified `pre`，验证所有 `/api/private-zoom/*` 接口。
4. 部署前端 `pre`，验证页面、外部入口、解锁和支付回跳。
5. Manager 更新后验证积分用途显示为新分类。
6. `pre` 验证通过后，先启动新生产后端并临时配置旧 API 到新 API 的 Nginx 转发。
7. 切换生产后端，再部署同批次生产前端；确认新前端只调用 `/api/private-zoom/*`。
8. 删除临时 Nginx 转发，执行 `database/private-zoom-migration.sql` 清理旧数据库对象。

## 8. 错误与界面状态

- `401`：Token 缺失或无效，前端进入现有登录恢复流程。
- `403`：游客访问仅注册用户可用的关系日记操作，展示现有注册引导。
- `404`：角色、图片包、内容或日记不存在，展示现有空状态或失效提示。
- `409`：`expectedCost` 与后端价格不同，刷新列表后重新确认。
- `402` 或业务余额不足错误：进入现有充值流程，并使用 `returnTo=private-zoom` 返回原角色页面。
- 网络失败：不修改本地解锁状态，保留重试入口。

## 9. 验收用例

1. `/characters/elio/private-zoom`、Maya 和 Nayeli 对应页面均可打开。
2. `GET /api/private-zoom/albums` 返回当前角色内容，角色之间不混用。
3. 已解锁历史记录在迁移后保持解锁状态，不重复扣积分。
4. 新解锁成功后刷新页面仍为已解锁状态。
5. 积分不足进入充值页后，回跳到原角色 `/private-zoom` 页面。
6. `target=private-zoom&character=nayeli` 进入 Nayeli 对应页面。
7. Manager 的积分用途不再出现旧分类。
8. 三个仓库执行旧命名残留扫描，结果为 `0`。

## 10. 当前测试证据

- unified：`316 passed`。
- 前端：TypeScript 类型检查通过；Vitest `639 passed`；ESLint 通过；契约测试 `4 passed`；生产构建通过并生成三个角色的 `/private-zoom` 页面。
- Manager：`75 passed`。
- PostgreSQL 16 临时库：升级、重复升级、回滚和再次升级全部通过；历史解锁、偏好键、积分账本、埋点、媒体路径和数据库对象名均通过断言，临时容器已删除。

## 11. 回滚影响

最终迁移执行前可直接恢复旧应用，桥接表会保留双向一致的数据。最终迁移执行后，回滚必须同时执行 unified 仓库中的 `database/private-zoom-rollback.sql`。回滚前应停止写入，先保存切换后的新增解锁记录，再执行逆向迁移并恢复旧应用版本。不得只恢复前端或只恢复 unified。

## 12. 待确认事项

- `pre` 浏览器真实联调和生产发布尚未执行。
- 生产镜像 ID 将在发布前固化到发布记录。