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

refactor(private-zone): use canonical product name

Browse Source
This commit is contained in:
Codex
2026-07-23 10:53:41 +08:00
parent 4639acf232
commit 9ca56c2a04
103 changed files with 569 additions and 569 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/frontend-integration/2026-07-22-private-zoom-rename.md → docs/frontend-integration/2026-07-22-private-zone-rename.md
+45 -45
View File
@@ -1,4 +1,4 @@
# Private Zoom 全链路改名联调说明
# Private Zone 全链路改名联调说明
- 日期：2026-07-22
- 目标环境：本地、`pre`、生产
@@ -6,7 +6,7 @@
## 1. 目标
原功能名称存在拼写错误。本次将前端、unified 后端、Manager、数据库、埋点和文档中的正式命名统一为 `Private Zoom`，并同步切换页面路由、API 路径和公开枚举值。
原功能名称存在拼写错误。本次将前端、unified 后端、Manager、数据库、埋点和文档中的正式命名统一为 `Private Zone`，并同步切换页面路由、API 路径和公开枚举值。
## 2. 环境地址
@@ -19,12 +19,12 @@
前端已完成以下修改：
- 页面路由统一为 `/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`。
- 页面路由统一为 `/private-zone` 和 `/characters/{characterSlug}/private-zone`。
- 外部入口参数统一为 `target=private-zone`。
- 支付回跳参数统一为 `returnTo=private-zone`。
- 类型、Repository、API client、XState actor、Provider 和资源目录统一使用 `privateZone`、`PrivateZone`、`private-zone` 或 `private_zone`。
- 埋点键统一为 `navigation.private_zone`、`chat.open_private_zone_from_avatar` 等新名称。
- 角色能力字段统一为 `capabilities.privateZone`。
旧页面和旧查询参数不再作为正式入口保留。发布时必须让前后端属于同一个发布批次。
@@ -34,19 +34,19 @@
| 方法 | 新路径 | 用途 |
| --- | --- | --- |
| `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` | 解锁关系日记 |
| `GET` | `/api/private-zone/albums` | 查询付费图片包 |
| `POST` | `/api/private-zone/albums/{albumId}/unlock` | 解锁图片包 |
| `GET` | `/api/private-zone/moments` | 查询朋友圈式内容 |
| `POST` | `/api/private-zone/moments/{momentId}/unlock` | 解锁单条内容 |
| `GET` | `/api/private-zone/config` | 查询当前角色和用户解锁配置 |
| `GET` | `/api/private-zone/diaries` | 查询关系日记 |
| `POST` | `/api/private-zone/diaries/{diaryId}/seen` | 标记关系日记已读 |
| `POST` | `/api/private-zone/diaries/{diaryId}/unlock` | 解锁关系日记 |
### 4.1 图片包列表
```http
GET /api/private-zoom/albums?characterId=elio&limit=20
GET /api/private-zone/albums?characterId=elio&limit=20
Authorization: Bearer <TOKEN>
```
@@ -59,14 +59,14 @@ Authorization: Bearer <TOKEN>
调用示例：
```bash
curl 'https://proapi.banlv-ai.com/api/private-zoom/albums?characterId=elio&limit=20' \
curl 'https://proapi.banlv-ai.com/api/private-zone/albums?characterId=elio&limit=20' \
-H 'Authorization: Bearer <TOKEN>'
```
### 4.2 解锁图片包
```http
POST /api/private-zoom/albums/{albumId}/unlock
POST /api/private-zone/albums/{albumId}/unlock
Authorization: Bearer <TOKEN>
Content-Type: application/json
```
@@ -77,7 +77,7 @@ Content-Type: application/json
| `expectedCost` | body | integer | 否 | 是 | 前端确认价格；与后端价格不一致时拒绝解锁 |
```bash
curl -X POST 'https://proapi.banlv-ai.com/api/private-zoom/albums/<ALBUM_ID>/unlock' \
curl -X POST 'https://proapi.banlv-ai.com/api/private-zone/albums/<ALBUM_ID>/unlock' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{"expectedCost":320}'
@@ -86,8 +86,8 @@ curl -X POST 'https://proapi.banlv-ai.com/api/private-zoom/albums/<ALBUM_ID>/unl
### 4.3 Moments 内容与解锁
```http
GET /api/private-zoom/moments?characterId=elio&limit=20
POST /api/private-zoom/moments/{momentId}/unlock
GET /api/private-zone/moments?characterId=elio&limit=20
POST /api/private-zone/moments/{momentId}/unlock
```
解锁请求体与图片包一致，`expectedCost` 为可选整数。响应中的正式分类值同步改为：
@@ -95,8 +95,8 @@ POST /api/private-zoom/moments/{momentId}/unlock
```json
{
"lockDetail": {
"type": "private_zoom_moment",
"reason": "private_zoom_moment"
"type": "private_zone_moment",
"reason": "private_zone_moment"
}
}
```
@@ -105,24 +105,24 @@ POST /api/private-zoom/moments/{momentId}/unlock
| 使用位置 | 新值 | 类型 |
| --- | --- | --- |
| `/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 |
| `/api/chat/unlock-private` 的 `lockType` 别名 | `private_zone` | string enum |
| 日程导入 `contentType` 别名 | `private_zone` | string enum，归一化为 `paid_content` |
| 外部入口 `target` | `private-zone` | string enum |
| 支付回跳 `returnTo` | `private-zone` | string enum |
| 锁定详情分类 | `private_zone_moment` | string enum |
## 6. 数据库迁移
因为 `pre` 与生产当前共用 `https://dbapi.banlv-ai.com`，预发部署前先执行 unified 仓库中的临时桥接脚本：
```text
database/private-zoom-bridge.sql
database/private-zone-bridge.sql
```
桥接脚本会创建新表并在切换窗口内保持新旧解锁写入双向同步。生产前后端全部切换完成后，再执行最终迁移：
```text
database/private-zoom-migration.sql
database/private-zone-migration.sql
```
迁移会在同一事务中完成：
@@ -130,7 +130,7 @@ database/private-zoom-migration.sql
- 将历史解锁表无损重命名；新旧表同时存在时先合并再删除旧表。
- 重命名关联约束、索引、策略和触发器。
- 合并 `users.preferences` 中历史解锁键，防止已解锁内容重新锁定。
- 把 `credit_ledger` 历史分类迁移到 `private_zoom` 和 `private_zoom_moment`。
- 把 `credit_ledger` 历史分类迁移到 `private_zone` 和 `private_zone_moment`。
- 定向迁移历史埋点键、页面 URL 和系统媒体路径，不改写用户聊天正文。
- 删除切换窗口使用的双写触发器和函数。
- 支持重复执行。
@@ -140,13 +140,13 @@ database/private-zoom-migration.sql
这是破坏性命名修正，不保留旧 API、旧页面路由或旧公开枚举作为正式兼容层。必须按以下顺序发布：
1. 备份数据库并记录当前 unified、前端和 Manager 版本。
2. 执行 `database/private-zoom-bridge.sql`，确认新旧表双向写入一致。
3. 部署 unified `pre`，验证所有 `/api/private-zoom/*` 接口。
2. 执行 `database/private-zone-bridge.sql`，确认新旧表双向写入一致。
3. 部署 unified `pre`，验证所有 `/api/private-zone/*` 接口。
4. 部署前端 `pre`，验证页面、外部入口、解锁和支付回跳。
5. Manager 更新后验证积分用途显示为新分类。
6. `pre` 验证通过后，先启动新生产后端并临时配置旧 API 到新 API 的 Nginx 转发。
7. 切换生产后端，再部署同批次生产前端；确认新前端只调用 `/api/private-zoom/*`。
8. 删除临时 Nginx 转发，执行 `database/private-zoom-migration.sql` 清理旧数据库对象。
7. 切换生产后端，再部署同批次生产前端；确认新前端只调用 `/api/private-zone/*`。
8. 删除临时 Nginx 转发，执行 `database/private-zone-migration.sql` 清理旧数据库对象。
## 8. 错误与界面状态
@@ -154,34 +154,34 @@ database/private-zoom-migration.sql
- `403`：游客访问仅注册用户可用的关系日记操作，展示现有注册引导。
- `404`：角色、图片包、内容或日记不存在，展示现有空状态或失效提示。
- `409`：`expectedCost` 与后端价格不同，刷新列表后重新确认。
- `402` 或业务余额不足错误：进入现有充值流程，并使用 `returnTo=private-zoom` 返回原角色页面。
- `402` 或业务余额不足错误：进入现有充值流程，并使用 `returnTo=private-zone` 返回原角色页面。
- 网络失败：不修改本地解锁状态，保留重试入口。
## 9. 验收用例
1. `/characters/elio/private-zoom`、Maya 和 Nayeli 对应页面均可打开。
2. `GET /api/private-zoom/albums` 返回当前角色内容，角色之间不混用。
1. `/characters/elio/private-zone`、Maya 和 Nayeli 对应页面均可打开。
2. `GET /api/private-zone/albums` 返回当前角色内容，角色之间不混用。
3. 已解锁历史记录在迁移后保持解锁状态，不重复扣积分。
4. 新解锁成功后刷新页面仍为已解锁状态。
5. 积分不足进入充值页后，回跳到原角色 `/private-zoom` 页面。
6. `target=private-zoom&character=nayeli` 进入 Nayeli 对应页面。
5. 积分不足进入充值页后，回跳到原角色 `/private-zone` 页面。
6. `target=private-zone&character=nayeli` 进入 Nayeli 对应页面。
7. Manager 的积分用途不再出现旧分类。
8. 三个仓库执行旧命名残留扫描，结果为 `0`。
## 10. 当前测试证据
- unified：`316 passed`。
- 前端：TypeScript 类型检查通过；Vitest `639 passed`；ESLint 通过；契约测试 `4 passed`；生产构建通过并生成三个角色的 `/private-zoom` 页面。
- 前端：TypeScript 类型检查通过；Vitest `639 passed`；ESLint 通过；契约测试 `4 passed`；生产构建通过并生成三个角色的 `/private-zone` 页面。
- Manager：`75 passed`。
- PostgreSQL 16 临时库：升级、重复升级、回滚和再次升级全部通过；历史解锁、偏好键、积分账本、埋点、媒体路径和数据库对象名均通过断言，临时容器已删除。
- `pre`：unified `71da49b` 和前端 `35939e7` 已验证；新 API 已注册 `8` 条 `/api/private-zoom/*` 路径，旧 API 路径数量为 `0`；新页面返回 `200`，旧页面返回 `404`。
- `pre`：unified `71da49b` 和前端 `35939e7` 已验证；新 API 已注册 `8` 条 `/api/private-zone/*` 路径，旧 API 路径数量为 `0`；新页面返回 `200`，旧页面返回 `404`。
- 生产：unified 镜像 `ai-boyfriend-unified:prod-20260722-71da49b`（镜像 ID `sha256:755ef5741856d83d7d808e7df8ee259b6fa5fb94fe333b523ee280ed1d5f674b`）和前端镜像 `prod-35939e7` 已健康运行；Manager 当前版本为 `6eea005`。
- 生产接口：测试账号调用 `GET https://api.banlv-ai.com/api/private-zoom/config?characterId=elio` 返回 `200`，`success=true`；旧版 API 路径在所有公开 API 入口均返回 `404`。
- 生产接口：测试账号调用 `GET https://api.banlv-ai.com/api/private-zone/config?characterId=elio` 返回 `200`，`success=true`；旧版 API 路径在所有公开 API 入口均返回 `404`。
- 生产数据库：最终迁移已执行，旧表、桥接函数、桥接触发器、旧偏好键、旧积分分类和旧埋点值的残留数量均为 `0`。
## 11. 回滚影响
最终迁移执行前可直接恢复旧应用，桥接表会保留双向一致的数据。最终迁移执行后，回滚必须同时执行 unified 仓库中的 `database/private-zoom-rollback.sql`。回滚前应停止写入，先保存切换后的新增解锁记录，再执行逆向迁移并恢复旧应用版本。不得只恢复前端或只恢复 unified。
最终迁移执行前可直接恢复旧应用，桥接表会保留双向一致的数据。最终迁移执行后，回滚必须同时执行 unified 仓库中的 `database/private-zone-rollback.sql`。回滚前应停止写入，先保存切换后的新增解锁记录，再执行逆向迁移并恢复旧应用版本。不得只恢复前端或只恢复 unified。
## 12. 待确认事项