feat(ov): idempotent batched likes and realtime broadcast

P2 Task 7（点赞批次端点 + ov 实时网关）：
- interactions 模块（仅 ov 装配）：POST /public/albums/{token}/photos/
  {photoId}/likes——相册不可见/照片未发布 404、delta 1..20 与
  sessionId/batchId 1..64 校验 400；单事务 like_batches 唯一插入
  （P2002=幂等重试，batchAccepted=true 不重加）→ photos_ov.likeTotal/
  countVersion 原子自增回读 → outbox_stat_events(kind=likes) 兜底；
  Redis ov（REDIS_URL_OV）INCRBY+TTL 会话/IP 双窗口限流（默认
  500/2000，超限 429 RATE_LIMITED），幂等重试先于限流不耗额度
- 过期批次重放边界（24h 清理后的 batchId 重插会再次计入）：接受该
  边界——无永久账本可查（保留全量批次行违背清理策略），会话/IP 窗口
  上限即重放天然封顶（同一 sessionId 重放挤占自身额度），偏差已在
  likes.service 头注释登记，Task 8 统计侧按清理后语义处理
- realtime：ContractWsAdapter（契约 {type,...} 帧分发，ws 与 HTTP 同
  端口挂 /v1/realtime）+ RealtimeGateway 相册房间模型——subscribe 逐
  相册校验 isAlbumVisibleOv，失败回 error 帧且连接保持；应用层 ping→
  pong 回显 ts；传输层 HEARTBEAT_MS 周期 ping 踢死连接；点赞提交经
  EventEmitter2（单进程，多实例 Redis pub/sub 登记 P5）触发
  likes.burst 500ms 合并窗（delta 聚合、originBatchIds 供客户端过滤
  自身批次）；sync-inbox 应用事务提交后发 OV_PHOTO_APPLIED →
  photo.published/hidden/deleted 按房间广播（stale/duplicate/暂存/
  缺席即撤下不转发）
- 契约：REALTIME_WS_PATH、ServerMessage 增 error 帧（穷尽锁 7 成员
  + 类型测试）、LIKE_SESSION_WINDOW_DELTA/LIKE_IP_WINDOW_DELTA/
  LIKE_BURST_MERGE_MS 常量与 .env.example
- e2e（likes-realtime.e2e-spec.ts，6 用例）：A09 三批累加/幂等重试/
  outbox 行、小额度 429、ping/pong+幽灵 token error 帧连接保持、
  A10 双房间隔离（先证非空调订）、合并窗单 burst（delta 求和+双
  originBatchIds）、cn 隐藏→房间收 photo.hidden+隐藏后点赞 404；
  凡进程内起 AppOvModule 的 spec（sync×2/public-ov/emergency）补装
  ContractWsAdapter 与生产 main-ov 一致——api e2e 168（162+6）

Co-Authored-By: Claude Code <noreply@anthropic.com>

packages/contracts/src/__tests__/realtime.test.ts

@@ -63,6 +63,16 @@ describe('ServerMessage', () => {
     expect(pong.type).toBe('pong');
   });
 
+  it('error 帧携带域码（subscribe 校验失败等场景）', () => {
+    const error: ServerMessage = { type: 'error', code: 'ALBUM_NOT_PUBLIC' };
+    if (error.type !== 'error') throw new Error('unreachable');
+    expect(error.code).toBe('ALBUM_NOT_PUBLIC');
+    // message 可选：缺省合法（客户端只应消费 code）。
+    // @ts-expect-error 非 error 分支没有 code
+    const absent = (burst as ServerMessage).code;
+    expect(absent).toBeUndefined();
+  });
+
   it('非法 type 在编译期被拒绝', () => {
     // @ts-expect-error type 必须严格属于联合成员
     const invalid: ServerMessage = { ...burst, type: 'likes.update' };
@@ -81,7 +91,7 @@ describe('ServerMessage', () => {
     expect(wrongTypes.type).toBe('likes.burst');
   });
 
-  it('type 联合与 6 个消息成员 1:1（穷尽锁定）', () => {
+  it('type 联合与 7 个消息成员 1:1（穷尽锁定）', () => {
     const exhaustive: Equal<
       ServerMessage['type'],
       | 'photo.published'
@@ -90,6 +100,7 @@ describe('ServerMessage', () => {
       | 'likes.burst'
       | 'stats.updated'
       | 'pong'
+      | 'error'
     > = true;
     expect(exhaustive).toBe(true);
   });
@@ -102,6 +113,7 @@ describe('ServerMessage', () => {
       { type: 'photo.deleted', photoId: 'p', albumId: 'a', entityVersion: 3 },
       { type: 'stats.updated', albumId: 'a', viewCount: 99, countVersion: 9 },
       { type: 'pong', ts: 1758187200000 },
+      { type: 'error', code: 'ALBUM_NOT_PUBLIC', message: '相册不存在或未公开' },
     ];
     const kinds = messages.map((m) => {
       switch (m.type) {
@@ -115,6 +127,8 @@ describe('ServerMessage', () => {
           return `stats:${m.viewCount}`;
         case 'pong':
           return `pong:${m.ts}`;
+        case 'error':
+          return `error:${m.code}`;
       }
     });
     expect(kinds).toEqual([
@@ -124,6 +138,7 @@ describe('ServerMessage', () => {
       'photo:3',
       'stats:99',
       'pong:1758187200000',
+      'error:ALBUM_NOT_PUBLIC',
     ]);
   });
 });

packages/contracts/src/constants.ts

@@ -20,5 +20,11 @@ export const STAT_RETURN_INTERVAL_MS = 60000;
 export const VISIT_WINDOW_MINUTES = 30;
 /** 点赞批次幂等窗口小时：窗口外 batchId 拒绝重放（返回权威 total，不加计）。 */
 export const LIKE_BATCH_WINDOW_HOURS = 24;
+/** 点赞基础限速：单 sessionId 滑窗（=幂等窗口）累计 delta 上限，超限 429。 */
+export const LIKE_SESSION_WINDOW_DELTA = 500;
+/** 点赞基础限速：来源 IP 滑窗累计 delta 上限（NAT 出口共享，宽于单会话）。 */
+export const LIKE_IP_WINDOW_DELTA = 2000;
+/** likes.burst 合并窗口毫秒（技术方案 §7 短窗合并；0=不合并逐批即时广播）。 */
+export const LIKE_BURST_MERGE_MS = 500;
 /** 浏览上报 requestId 保留分钟：过期 requestId 拒绝重放（≥ 去重窗口）。 */
 export const VISIT_REQUEST_TTL_MINUTES = 35;

packages/contracts/src/realtime.ts

@@ -6,6 +6,12 @@
 /** 心跳间隔（毫秒）：客户端周期发送 ping、服务端回 pong；超时无心跳的连接由服务端踢除。 */
 export const HEARTBEAT_MS = 20000;
 
+/**
+ * ov 入口 WS 网关挂载路径：与 HTTP 同端口（ov 8081），升级请求按本路径路由
+ * （services/api realtime 网关装饰器与 e2e/viewer 客户端共用，单一来源）。
+ */
+export const REALTIME_WS_PATH = '/v1/realtime';
+
 // ── server → client ──
 
 /** 照片发布：副本应用后向相册房间广播（ov 侧，下同）。 */
@@ -59,13 +65,26 @@ export interface PongMessage {
   ts: number;
 }
 
+/**
+ * 错误帧：客户端消息无法处理时的服务端应答（如 subscribe 的相册不存在/
+ * 不公开）。连接保持打开——客户端可修正后重发（如改订其它相册或等待恢复）。
+ */
+export interface RealtimeErrorMessage {
+  type: 'error';
+  /** 契约 ErrorCodes 域码（subscribe 校验失败 → ALBUM_NOT_PUBLIC 等）。 */
+  code: string;
+  /** 可读说明（可选，不承诺稳定性，客户端只应消费 code）。 */
+  message?: string;
+}
+
 export type ServerMessage =
   | PhotoPublishedMessage
   | PhotoHiddenMessage
   | PhotoDeletedMessage
   | LikesBurstMessage
   | StatsUpdatedMessage
-  | PongMessage;
+  | PongMessage
+  | RealtimeErrorMessage;
 
 // ── client → server ──