docs(plan): p2 implementation plan (approved, both review gaps fixed)
Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
浅念
@@ -0,0 +1,124 @@
|
||||
# P2 双地域仿真与互动 实施计划
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 交付海外观众服务（本地双实例仿真）：cn→ov 版本化内容同步（outbox/inbox、墓碑、补漏对账、高优先级下线）、海外紧急停用入口、点赞批次幂等 + WebSocket 实时气泡、浏览统计窗口去重、统计快照回传；viewer 切换 ov-api 并获得点赞/气泡/热门排序/浏览上报能力。
|
||||
|
||||
**Architecture:** ov 侧 = `services/api` 新增 ov-app 部署入口（:8081）+ ov Prisma schema（独立 MySQL `photo_ov`）+ WebSocket 网关；`services/sync` 承担 cn outbox 发送 / ov inbox 接收 / 双向对账与统计回传。全链路本地 compose 仿真（MySQL×2/Redis×2 以 profiles 启用 ov 侧）。对齐总纲 P2 与技术实施方案 §2A/§7-§8。
|
||||
|
||||
**Tech Stack:** 沿用 P1 全套；新增 `ws`（NestJS ws adapter）、内部同步接口服务间鉴权（HMAC 签名 + 时间戳，env 密钥）。
|
||||
|
||||
**对应验收（仿真级）:** A09 A10 A14 A21 A26 A27；A25 部分（本地直读语义）。
|
||||
|
||||
**依赖基线:** tag `p1`（b5145d6）。
|
||||
|
||||
**决策初值登记（D07/D11，按建议值先行，验收前可调）:**
|
||||
- D07：浏览去重窗口 30 分钟（env `VISIT_WINDOW_MINUTES=30`）；主办字段不纳入 P2。
|
||||
- D11：outbox 推送间隔 2s/批 100 条、高优先级即时；补漏对账每 5 分钟；统计回传每 60s 增量快照；中断恢复=水位重放。全部 env 可调。
|
||||
|
||||
---
|
||||
|
||||
## Task 1: ov 契约与决策初值
|
||||
|
||||
**Files:** Modify `packages/contracts/openapi.yaml`（+gen）、`src/constants.ts`、`.env.example`
|
||||
|
||||
- [ ] 契约新增：
|
||||
- **公开互动端点（ov 域，路径前缀不变，部署域名区分）**：`POST /public/albums/{token}/photos/{photoId}/likes`（匿名+限速；body {sessionId, batchId, delta 1..20} → 200 {total, countVersion, batchAccepted}；重复 batchId → 幂等返回已确认结果）；`POST /public/albums/{token}/visits`（body {visitorId, requestId} → 200 {viewCount, counted}）；likes 上限/限速语义写入 description
|
||||
- **WS 事件契约**（components 不适用——单独 `packages/contracts/src/realtime.ts`）：server→client 消息 `photo.published` / `photo.hidden` / `photo.deleted` / `likes.burst`{photoId, albumId, delta, total, countVersion, burstId, originBatchIds[]} / `stats.updated`{albumId, viewCount}；client→server `subscribe{albumToken, sinceVersion?}` / `unsubscribe`；心跳 ping/pong 20s
|
||||
- **内部同步接口**（tag internal，security: internalSyncKey 描述）：`POST /internal/sync/content-batches`（数组：{eventId, schemaVersion, entityType: album|category|photo|asset|slot-state(预留), entityId, albumId, entityVersion, tombstone?, priority, payload}）；`POST /internal/sync/stat-snapshots`（cn←ov 方向：数组 {photoId?, albumId, kind: likes|views, total, statVersion, source, confirmedAt}）；对账 `POST /internal/sync/reconcile`{entityType, sinceVersion, limit} → 缺失清单；全量快照 `POST /internal/sync/bootstrap`{albumId?}→{snapshotEventIds[]}（经对账通道分批拉取）
|
||||
- [ ] constants：SYNC 批量/间隔、VISIT_WINDOW_MINUTES、REALTIME 心跳等 env 键名与默认值入 `.env.example`
|
||||
- [ ] gen + lint + 全回归绿；Commit `feat(contracts): p2 realtime, likes, visits and internal sync contracts`
|
||||
|
||||
## Task 2: ov 数据层
|
||||
|
||||
**Files:** Create `packages/db-ov/`（mirror db-cn 模式：package/schema/src）；`services/api` ov 入口骨架 `src/main-ov.ts` + `app-ov.module.ts`；compose ov 侧 profile（mysql-ov 3307、redis-ov 6381，127.0.0.1 绑定）；`test/reset-ov.ts`（api 包共用，按连接串区分）
|
||||
|
||||
- [ ] ov schema：`albums_ov`（cn 副本：publicToken/状态/开关/翻译 JSON/分类 JSON/banner 对象键/版本）、`photos_ov`（photoId/albumId/分类/宽高/objectKeys/likeTotal/countVersion/visibility/版本/publishedAt）、`sync_inbox`（eventId 唯一、entityType/entityId/entityVersion、tombstone、payload、receivedAt/appliedAt）、`sync_state`（entityType+entityId → appliedVersion，水位表 per source）、`like_batches`（photoId+sessionId+batchId 唯一、delta、createdAt + 索引/清理窗口）、`album_stats`（albumId 主键 viewCount/updatedAt/statVersion）、`visit_sessions`（albumId+visitorId 唯一、lastCountedAt）、`visit_requests`（requestId 唯一、counted、createdAt）、`outbox_stat_events`（ov→cn 回传队列）
|
||||
- [ ] 迁移走固化校对手决流程；14→N 表全 bin 校对验证；健康检查 + /health
|
||||
- [ ] Commit `feat(ov): ov schema, entry skeleton and compose profile`
|
||||
|
||||
## Task 3: cn 事件补全 + sync 发送器（cn→ov）
|
||||
|
||||
**Files:** Create `services/sync/`（@photo/sync：sender + scheduler）；Modify `services/api/src/albums|photos|public`（事件补全）、`packages/db-cn/prisma/schema.prisma`（albums/categories/album_assets 增 `entityVersion` 列——迁移走校对手决流程）
|
||||
|
||||
- [ ] **cn 事件补全（评审缺口 1）**：albums 服务在 创建/更新（含开关、下线 status、translations 替换）时写 outbox `album.updated`（下线与 publicEnabled=false → 高优先级）；categories 增改删 → `category.*`（删除=tombstone）；assets complete 生效 → `asset.updated`；各表 entityVersion 条件自增（同 photos 模式：更新事务内 +1）；payload 携带 ov 所需展示字段（translations JSON、开关、banner 对象键、分类翻译）
|
||||
- [ ] **首次全量快照**：`POST /internal/sync/bootstrap`{albumId?}——对指定相册（或全部）生成当前快照事件序列（album→categories→assets→photos 含版本），ov 冷启动或新建副本时经对账通道拉取（§2A"首次全量快照携带水位"）
|
||||
- [ ] outbox 发送器：轮询 outbox_events（未 delivered）按优先级（高优先级=相册下线/照片隐藏删除 tombstone 类，即发）批量 HMAC 签名推送 content-batches → ov 返回 {acceptedEventIds, appliedWatermarks} → 回写 deliveredAt；失败退避重试，绝不丢失（deliveredAt 为空即重发）；eventId 幂等由 ov 保证
|
||||
- [ ] 集成测试：cn 发布照片→sender→ov inbox applied→photos_ov 出现；**相册更新（开关/翻译）→ albums_ov 副本同步**；重复推送→幂等；乱序版本→旧版本忽略；墓碑→副本删除且不被旧事件复活（A26 核心）；bootstrap 冷启动建全套副本
|
||||
- [ ] Commit `feat(sync): cn event coverage, bootstrap and outbox sender`
|
||||
|
||||
## Task 4: inbox 接收与对账（ov 侧）
|
||||
|
||||
**Files:** `services/api/src/sync-inbox/`（ov module）；sync 服务补漏调度
|
||||
|
||||
- [ ] inbox 端点（internal 鉴权）：事务内 eventId 唯一插入→entityVersion 比较（sync_state）→应用或忽略→依赖缺失（相册未到而照片先到）暂存不 applied、待依赖事件到达后补应用（或对账补取）；墓碑优先；applied 后应答
|
||||
- [ ] 对账：定时（5min）按 sync_state 水位向 cn 请求 reconcile 清单→拉缺失→重放；同步状态表供管理查询（延迟、积压——P4a 展示，本阶段出 API/DB）
|
||||
- [ ] 集成测试：断续中断（停 sender）→恢复后补齐；隐藏优先于发布乱序到达（先 photo.hidden 后 photo.published 旧版本→保持隐藏）
|
||||
- [ ] Commit `feat(sync): ov inbox with versioning, tombstones and reconciliation`
|
||||
|
||||
## Task 5: 海外紧急停用入口
|
||||
|
||||
- [ ] ov 侧 `POST /internal/emergency/disable`{albumToken|albumId, reason}（internal 鉴权）：ov DB 直接置 `albums_ov.emergency_disabled=true`（独立于同步版本——不被任何后续同步事件解除，解除仅经显式 enable 端点）；公开 API/WS 检查该标志；cn 侧不感知（文档化）；审计写 ov 侧日志文件（无 cn audit——登记偏差）
|
||||
- [ ] 测试：停用→ov 公开 404→cn 继续同步新照片（ov 保持屏蔽）→显式启用恢复
|
||||
- [ ] Commit `feat(ov): emergency disable channel independent of sync`
|
||||
|
||||
## Task 6: ov 公开读 API
|
||||
|
||||
- [ ] ov-app 实现 P1 同形公开三端点（album/photos 列表/单图）读 photos_ov 副本 + 最新/热门排序（sort=latest|hot，hot=likeTotal 排序短期快照——30s 缓冲快照表或内存缓存）+ banner 签名 URL（ov 侧持有 MinIO/OSS 只读凭证——本地同 MinIO）
|
||||
- [ ] viewer 切换：API base env `VITE_API_BASE`（dev 默认 ov :8081）；全 viewer e2e 迁移跑 ov 端（P1 套件保持绿=契约同形证明）
|
||||
- [ ] Commit `feat(ov): public read api on replicas with hot sorting`
|
||||
|
||||
## Task 7: 点赞与实时（ov）
|
||||
|
||||
- [ ] likes 端点：事务（like_batches 唯一插入→photos_ov.likeTotal 原子+delta、countVersion++→outbox_stat_events + 实时 burst 事件入队）；重复 batchId 幂等返回；基础限速（sessionId+IP 滑窗，Redis ov）；delta 越界 400；照片/相册非公开 404
|
||||
- [ ] WS 网关（NestJS ws adapter on ov）：subscribe 校验相册公开→加入相册房间；广播 likes.burst（短窗 500ms 合并、保留 originBatchIds 供自身过滤）、photo.*、stats.updated；心跳 20s 踢死链；断线客户端降级轮询（viewer 侧 Task 10）
|
||||
- [ ] （契约含 POST /internal/sync/bootstrap——Task 1 已列）集成测试：A09（连点累计、重复请求不加计）、A10（两相册隔离：房间不串）、A21 部分（合并广播 batch 过滤在后端侧验证 originBatchIds 正确性）
|
||||
- [ ] Commit `feat(ov): idempotent batched likes and realtime broadcast`
|
||||
|
||||
## Task 8: 浏览统计（ov）+ 去重数据清理
|
||||
|
||||
- [ ] visits 端点：事务（visit_requests requestId 唯一→visit_sessions 锁行/upsert→窗口判断（VISIT_WINDOW_MINUTES）→counted 则 album_stats.viewCount++、statVersion++→应答 {viewCount, counted}）；并发首访唯一（唯一约束+重试）；过期 requestId 拒绝；GET album 返回 viewCount（真实值，替换 P1 占位 null）
|
||||
- [ ] 上报排除规则落地：接口仅显式调用（列表/图片/WS 皆不触发——测试断言）；基础限速（sessionId 滑窗——去重本身为 P2 主缓解，登记）
|
||||
- [ ] **清理调度（评审缺口 2）**：ov 定时任务清理 `like_batches`/`visit_requests`/`visit_sessions` 超窗口数据（LIKE_BATCH_WINDOW 默认 24h、VISIT_REQUEST_TTL 同窗口；累计总数长期保留）；**过期批次拒绝重放**：likes 端点遇窗口外 batchId → 拒绝并返回当前权威 total（counted=false 语义），不得重新加计（测试：清理后重放旧 batchId 不加计）
|
||||
- [ ] 集成测试：A14 仿真级（窗口内刷新不重复、跨 requestId 重试幂等、新窗口再计、并发首访只加一次、过期重放拒绝）
|
||||
- [ ] Commit `feat(ov): windowed dedup visit counting with retention cleanup`
|
||||
|
||||
## Task 9: 统计回传（ov→cn）
|
||||
|
||||
- [ ] **cn 副本列迁移**（走校对手决流程）：`albums.view_count_replica` + `albums.stats_synced_at`（photos.like_count 已存在作副本位）
|
||||
- [ ] ov 定时（60s）聚合 outbox_stat_events→stat-snapshots（HMAC）→cn 接收端（internal）事务替换 cn 侧 photos.like_count 副本/album view 副本（仅更高 statVersion 替换，绝不相加）+ 回执确认→ov 清理队列；中断重发幂等（statVersion 比较）
|
||||
- [ ] cn 管理列表（listAlbumPhotos/albums）展示副本计数 + `statsSyncedAt`（A27：不重复累计、最终一致、展示同步时间）
|
||||
- [ ] 集成测试：A27 仿真级（重复回传不加计、乱序快照旧版本忽略、最终一致断言）
|
||||
- [ ] Commit `feat(sync): stat snapshot return path with version replacement`
|
||||
|
||||
## Task 10: viewer 互动化
|
||||
|
||||
- [ ] 点赞 UI：大图/列表点击→本地动画+计数即时、批次收集（500ms 或 5 张一批）提交 {sessionId(会话随机), batchId, delta}→确认校准（total 权威）；失败退避重试同 batchId；自身气泡过滤（originBatchIds 含己 batchId→抑制己部动画，他人照常）
|
||||
- [ ] 气泡：WS 连接（断线降级 8s 轮询列表页首校准 + likes 总数校准；不补播历史气泡）；气泡含被赞照片小缩略图+点击定位；页面不可见暂停动画（visibilitychange）；"减少动画"设置（localStorage，隐藏气泡仅保计数跳动）
|
||||
- [ ] 浏览上报：visitorId 跨标签共享（localStorage+BroadcastChannel 协调写、读回一致；不可用降级页面级随机）、页面可见且 album 加载成功后一次性 {visitorId, requestId(uuid 持久到 counted 确认为止)}、确认后更新显示
|
||||
- [ ] 热门/最新排序切换 UI（排序=快照语义：切换重新拉列表，当前浏览序列不变——对齐技术方案 §7）
|
||||
- [ ] Playwright：点赞累计+刷新校准、自身气泡不重复（同页点赞看他人模拟广播）、断线重连计数校准（断 WS→续）、排序切换、隐藏照片气泡/列表即时消失
|
||||
- [ ] Commit `feat(viewer): likes, bubbles, visit reporting and hot sorting`
|
||||
|
||||
## Task 11: 全链路集成测试（同步+互动）
|
||||
|
||||
- [ ] 场景套件（集成级，cn+ov+sync+worker 全起）：①上传→发布→同步→ov 可见→点赞→回传→cn 副本一致（A25 本地直读语义+A27）②隐藏→高优先级同步→ov 消失+WS 推送隐藏③sender 停机 30s（积压）→恢复→追平+对账无缺④墓碑后旧事件重放不复活（A26）⑤紧急停用→ov 屏蔽→cn 无感⑥并发点赞/浏览压力小样（50 并发）幂等
|
||||
- [ ] Commit `test(sync): cross-region simulation integration suite`
|
||||
|
||||
## Task 12: 回归门 + P2 验收记录
|
||||
|
||||
- [ ] 全量回归绿（P1 套件不降级 + 新增）；记录数字
|
||||
- [ ] `docs/plans/progress/P2-验收记录.md`（A09/A10/A14/A21/A26/A27 仿真级证据、D07/D11 实测建议值、偏差登记、P4a/P5 移交：真实地域部署/CDN/管理页同步状态展示/清理任务生产化）
|
||||
- [ ] 总纲 P2 行进度注记；`git tag p2`；Commit `docs: p2 acceptance record`
|
||||
|
||||
---
|
||||
|
||||
## 执行注意
|
||||
|
||||
- 沿用 P1 全部工程约定（校对手决、reset 隔离、turbo concurrency=1、maxWorkers=1、契约先行+gen、Co-Authored-By trailer、偏差登记）。
|
||||
- ov 入口与 cn 入口同一 services/api 代码库：模块按部署角色组织（sync-inbox/likes/visits/ws 仅 ov 装配；auth/albums/uploads 仅 cn 装配）——app-ov.module.ts 显式挑选。
|
||||
- 双数据库连接：PrismaService(cn) 已全局；新增 OvPrismaService 独立 provider（非 global，按模块注入）；测试 reset 区分两库。**env 键名明确**：`DATABASE_URL_OV`（mysql://...3307/photo_ov）、`REDIS_URL_OV`（redis://...6381）。
|
||||
- **偏差预登记（评审建议）**：ov 侧"确认资源可访问再设可见"的 head 探测在本地仿真不做（同 MinIO 必然可达），真实 OSS/CDN 探测随 G1/P5；cn 侧相册浏览数副本落新列 `albums.view_count_replica`（Task 9 迁移）。
|
||||
- 内部接口 HMAC：`X-Sync-Signature: hmacsha256(body, SYNC_INTERNAL_KEY)` + `X-Sync-Timestamp`（±300s 防重放）；key 仅 env。
|
||||
- WS 与 HTTP 同端口（ov 8081）；dev:sync / dev:ov 根脚本补齐。
|
||||
- 性能口径（P5 压测才硬性）：本阶段并发小样仅验语义正确性，不做容量结论。
|
||||
Reference in New Issue
Block a user