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 图片包列表

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	否	是	分页游标

调用示例：

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

4.2 解锁图片包

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

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

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 内容与解锁

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

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

{
  "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 仓库中的临时桥接脚本：

database/private-zoom-bridge.sql

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

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 将在发布前固化到发布记录。