feat(sync): cn event coverage, bootstrap and outbox sender

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

services/sync/jest.config.cjs

@@ -0,0 +1,31 @@
+// services/sync/jest.config.cjs —— 单测配置（镜像 services/worker/jest.config.cjs
+// 约定；P2 Task 3 当前仅有 e2e，单测配置保留供后续 sender 单测落地，
+// passWithNoTests 让空单测包不挂 turbo test 门）。
+//   · maxWorkers 1：单进程串行（e2e 配置继承后共享同一 MySQL/MinIO，spec 间以
+//     api test/reset*.ts TRUNCATE + 前缀清理隔离，并行会互相清掉对方数据）；
+//   · setupFiles 经 test/load-env.ts 载入仓库根 .env（全仓库唯一 env 文件）；
+//   · @photo/contracts（ESM）/@photo/db-cn/@photo/db-ov/@photo/storage（CJS）
+//     经 moduleNameMapper 直指 TS 源码，ts-jest 以 CJS 编译，无需先 build 依赖
+//     包 dist；contracts 源码 NodeNext 风格 .js 后缀导入 → 映射回 .ts。
+/** @type {import('jest').Config} */
+module.exports = {
+  maxWorkers: 1,
+  testEnvironment: 'node',
+  rootDir: '.',
+  setupFiles: ['./test/load-env.ts'],
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', { tsconfig: 'tsconfig.json' }],
+  },
+  moduleNameMapper: {
+    '^@photo/contracts$': '<rootDir>/../../packages/contracts/src/index.ts',
+    '^@photo/db-cn$': '<rootDir>/../../packages/db-cn/src/index.ts',
+    // e2e 直连 ov 库断言副本（PrismaClient from '@photo/db-ov'）。
+    '^@photo/db-ov$': '<rootDir>/../../packages/db-ov/src/index.ts',
+    // 驱动 worker PublishService（上传即公开事务）需要 storage 适配器。
+    '^@photo/storage$': '<rootDir>/../../packages/storage/src/index.ts',
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  testMatch: ['<rootDir>/src/**/*.spec.ts', '<rootDir>/test/**/*.spec.ts'],
+  testPathIgnorePatterns: ['/node_modules/', '/dist/'],
+  passWithNoTests: true,
+};

services/sync/jest.e2e.config.cjs

@@ -0,0 +1,10 @@
+// services/sync/jest.e2e.config.cjs —— e2e（test/*.e2e-spec.ts，P2 Task 3
+// cn→ov 同步链路），复用单测配置仅切换 testMatch；隔离工具复用 api 包
+// test/reset.ts / test/reset-ov.ts（跨包按文件位置解析）。
+/** @type {import('jest').Config} */
+module.exports = {
+  // CJS 配置文件复用基础配置只能经 require（node10 互操作），局部豁免 lint 规则。
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  ...require('./jest.config.cjs'),
+  testMatch: ['<rootDir>/test/**/*.e2e-spec.ts'],
+};

services/sync/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@photo/sync",
+  "version": "0.1.0",
+  "private": true,
+  "description": "CN→OV outbox sender (轮询 outbox_events 推送 content-batches 到 ov 入口；P2 Task 3)",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "start": "tsc -p tsconfig.build.json && node dist/main.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "jest",
+    "test:e2e": "jest --config jest.e2e.config.cjs"
+  },
+  "dependencies": {
+    "@photo/contracts": "workspace:*",
+    "@photo/db-cn": "workspace:*",
+    "pino": "^10.0.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^10.4.6",
+    "@nestjs/core": "^10.4.6",
+    "@nestjs/platform-express": "^10.4.6",
+    "@photo/db-ov": "workspace:*",
+    "@photo/storage": "workspace:^",
+    "@types/jest": "^29.5.13",
+    "@types/node": "^22.10.0",
+    "@types/supertest": "^6.0.2",
+    "dotenv": "^16.4.5",
+    "jest": "^29.7.0",
+    "sharp": "^0.35.0",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.6.0"
+  }
+}

services/sync/src/main.ts

@@ -0,0 +1,128 @@
+// services/sync/src/main.ts —— sync 发送器进程入口（P2 Task 3）。构建产物
+// dist/main.js 由根 dev:sync / 生产启动命令运行；env 一律来自进程环境（根
+// dotenv-cli 注入），此处不读文件。循环：每 SYNC_PUSH_INTERVAL_MS 轮询一次
+// outbox（SYNC_BATCH_SIZE 一批，high 优先——见 sender.ts 排序说明；满批立即
+// 追下一轮，积压排空不被轮询间隔拖慢）。失败退避：连续失败按间隔 ×2^n 指数
+// 递增、60s 封顶，成功即归零。优雅退出：SIGINT/SIGTERM 停轮询（等待在飞
+// 一轮，fetch 超时已封顶 30s）后断开 Prisma。
+import { pino } from 'pino';
+import { PrismaClient } from '@photo/db-cn';
+import {
+  SYNC_BATCH_SIZE,
+  SYNC_INTERNAL_KEY_ENV,
+  SYNC_PUSH_INTERVAL_MS,
+} from '@photo/contracts';
+import { OutboxSender } from './sender';
+
+/** 失败退避封顶（对齐 SYNC_RECONCILE_INTERVAL_MS 量级：分钟级封顶足够）。 */
+const MAX_BACKOFF_MS = 60_000;
+/** 单次 HTTP 请求超时。 */
+const REQUEST_TIMEOUT_MS = 30_000;
+
+/** 读正整数 env（可覆盖契约默认值）；非法值回退默认并告警。 */
+function readIntEnv(
+  logger: { warn: (obj: object, msg: string) => void },
+  name: string,
+  fallback: number,
+): number {
+  const raw = process.env[name];
+  if (raw === undefined || raw === '') {
+    return fallback;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    logger.warn({ name, raw }, 'env 非正整数，回退契约默认值');
+    return fallback;
+  }
+  return parsed;
+}
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+async function main(): Promise<void> {
+  const logger = pino({ level: process.env.LOG_LEVEL ?? 'info' });
+  const intervalMs = readIntEnv(logger, 'SYNC_PUSH_INTERVAL_MS', SYNC_PUSH_INTERVAL_MS);
+  const batchSize = readIntEnv(logger, 'SYNC_BATCH_SIZE', SYNC_BATCH_SIZE);
+  const ovApiUrl = process.env.OV_API_URL ?? 'http://127.0.0.1:8081';
+  const internalKey = process.env[SYNC_INTERNAL_KEY_ENV] ?? '';
+  if (internalKey === '') {
+    // 与接收端 guard 同一取舍：密钥缺失宁可不可用，绝不裸推。
+    logger.error({ env: SYNC_INTERNAL_KEY_ENV }, '缺少内部同步密钥，发送器退出');
+    process.exit(1);
+  }
+
+  const prisma = new PrismaClient();
+  const sender = new OutboxSender({
+    prisma,
+    ovApiUrl,
+    internalKey,
+    batchSize,
+    timeoutMs: REQUEST_TIMEOUT_MS,
+    logger,
+  });
+  logger.info(
+    { ovApiUrl, intervalMs, batchSize },
+    'sync sender started',
+  );
+
+  let stopping = false;
+  let inFlight: Promise<void> | null = null;
+  const loop = async (): Promise<void> => {
+    let failureStreak = 0;
+    while (!stopping) {
+      try {
+        const stats = await sender.runOnce();
+        failureStreak = 0;
+        if (stats.picked > 0) {
+          logger.info(stats, 'outbox batch pushed');
+        }
+        if (stats.picked >= batchSize) {
+          continue; // 满批：积压未清，立即追下一轮
+        }
+      } catch (err) {
+        failureStreak += 1;
+        const backoffMs = Math.min(
+          intervalMs * 2 ** (failureStreak - 1),
+          MAX_BACKOFF_MS,
+        );
+        logger.error(
+          {
+            err: err instanceof Error ? err.message : String(err),
+            failureStreak,
+            backoffMs,
+          },
+          'outbox push failed（整批未标记，下轮重推）',
+        );
+        await sleep(backoffMs);
+        continue;
+      }
+      await sleep(intervalMs);
+    }
+  };
+  inFlight = loop();
+
+  const shutdown = (signal: string): void => {
+    if (stopping) return;
+    stopping = true;
+    logger.info({ signal }, 'sync sender shutting down');
+    void (async () => {
+      try {
+        // 等在飞一轮收尾（runOnce 各步均有界：HTTP 30s 超时 / DB 查询即回）。
+        await inFlight;
+        await prisma.$disconnect();
+      } catch (err) {
+        logger.error(
+          { err: err instanceof Error ? err.message : String(err) },
+          'sync sender 关闭异常',
+        );
+      } finally {
+        process.exit(0);
+      }
+    })();
+  };
+  process.once('SIGINT', () => shutdown('SIGINT'));
+  process.once('SIGTERM', () => shutdown('SIGTERM'));
+}
+
+void main();

services/sync/src/sender.ts

@@ -0,0 +1,251 @@
+// services/sync/src/sender.ts —— cn→ov outbox 发送器（P2 Task 3）。
+// 单次推送 runOnce()：从 cn 库 outbox_events 取 deliveredAt 为空的事件一批，
+// 转内部同步线格式（openapi SyncEvent）后 HMAC 签名推送 ov 入口
+// POST /v1/internal/sync/content-batches；响应 acceptedEventIds 即「受理」锚点
+// （含幂等重复），据此回写 deliveredAt。
+//
+// 高优先级排序：**显式两段取数**（先 high 后其余，段内 occurredAt 升序）而非
+// ORDER BY priority DESC——'high' < 'normal'（字典序 h<n），DESC 反而把 normal
+// 排前；两段取数不依赖任何字符串序假设，新增优先级值也不失效。间隔轮询模型下
+// high 事件最坏等待一个 SYNC_PUSH_INTERVAL_MS（默认 2s，D11「high 不受间隔
+// 约束」的落地取舍：2s 上限可接受，专路即时唤醒属 YAGNI）。
+//
+// 失败语义：任一环节抛错则本 tick 整批不标记、下轮重推（eventId 幂等保证重试
+// 安全）；退避由 main 循环负责（指数递增封顶），本模块无内部重试。
+import type { PrismaClient } from '@photo/db-cn';
+import type { components } from '@photo/contracts';
+import {
+  type OutboxEvent,
+  SYNC_SIGNATURE_HEADER,
+  SYNC_TIMESTAMP_HEADER,
+  isTombstoneOutboxType,
+  signSyncBody,
+  syncEntityTypeOfOutboxType,
+} from '@photo/contracts';
+import type { Logger } from 'pino';
+
+/** openapi SyncEvent（线格式；payload 为实体类型相关载荷对象）。 */
+export type SyncEventWire = components['schemas']['SyncEvent'];
+
+/** ov content-batches 响应（openapi ContentBatchResponse）。 */
+interface ContentBatchResponse {
+  acceptedEventIds: string[];
+  applied: number;
+}
+
+/** outbox 行（发送器只读关心的列）。 */
+type OutboxRow = {
+  id: string;
+  type: string;
+  albumId: string;
+  photoId: string | null;
+  entityVersion: number;
+  priority: string;
+  payload: unknown;
+  occurredAt: Date;
+};
+
+export interface OutboxSenderOptions {
+  prisma: PrismaClient;
+  /** ov 入口基址（如 http://127.0.0.1:8081，不含路径）；端点路径本模块拼接。 */
+  ovApiUrl: string;
+  /** HMAC 密钥（与接收端 InternalSyncGuard 同一 SYNC_INTERNAL_KEY 值）。 */
+  internalKey: string;
+  /** 单批上限（默认契约 SYNC_BATCH_SIZE）。 */
+  batchSize?: number;
+  /** 单次 HTTP 超时毫秒（默认 30s）。 */
+  timeoutMs?: number;
+  logger?: Logger;
+}
+
+/** 单次 runOnce 的观测口径（main 循环打点；测试用于排空/排序判断）。 */
+export interface PushStats {
+  /** 本批取到的事件数（0 则跳过 HTTP）。 */
+  picked: number;
+  /** ov 受理的事件 ID 清单（含幂等重复；批内顺序即受理顺序）。 */
+  acceptedEventIds: string[];
+  /** ov 实际应用（新版本生效）的条数。 */
+  applied: number;
+}
+
+const DEFAULT_BATCH_SIZE = 100;
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** ov 侧 content-batches 端点路径（全局前缀 v1 + InternalSyncGuard 域）。 */
+const CONTENT_BATCHES_PATH = '/v1/internal/sync/content-batches';
+
+export class OutboxSender {
+  private readonly batchSize: number;
+  private readonly timeoutMs: number;
+  private readonly endpoint: string;
+
+  constructor(private readonly options: OutboxSenderOptions) {
+    this.batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    // 基址容错：吞并尾斜杠再拼路径，端点只此一处。
+    this.endpoint = `${options.ovApiUrl.replace(/\/+$/, '')}${CONTENT_BATCHES_PATH}`;
+  }
+
+  /** 单轮推送：取批 → 线格式 → 签名推送 → 按受理回写 deliveredAt。 */
+  async runOnce(): Promise<PushStats> {
+    const rows = await this.pickBatch();
+    if (rows.length === 0) {
+      return { picked: 0, acceptedEventIds: [], applied: 0 };
+    }
+    const events = rows.map((row) => this.toWireEvent(row));
+    const response = await this.push(events);
+    // 只标记 ov 明确受理的 eventId（且仍为未投递），幂等可重入。
+    if (response.acceptedEventIds.length > 0) {
+      await this.options.prisma.outbox_events.updateMany({
+        where: {
+          id: { in: response.acceptedEventIds },
+          deliveredAt: null,
+        },
+        data: { deliveredAt: new Date() },
+      });
+    }
+    this.options.logger?.debug(
+      {
+        picked: rows.length,
+        accepted: response.acceptedEventIds.length,
+        applied: response.applied,
+      },
+      'outbox batch pushed',
+    );
+    return {
+      picked: rows.length,
+      acceptedEventIds: response.acceptedEventIds,
+      applied: response.applied,
+    };
+  }
+
+  /**
+   * 两段取数（见文件头排序说明）：high 段占满批则不发第二查；两查之间存在
+   * 微小时序窗口（新事件落入两查之间）——对轮询器无害，下一轮补上。
+   */
+  private async pickBatch(): Promise<OutboxRow[]> {
+    const prisma = this.options.prisma;
+    const high = await prisma.outbox_events.findMany({
+      where: { deliveredAt: null, priority: 'high' },
+      orderBy: [{ occurredAt: 'asc' }, { id: 'asc' }],
+      take: this.batchSize,
+      // 只取发送器关心的列（payload JsonValue 原样透传）。
+      select: {
+        id: true,
+        type: true,
+        albumId: true,
+        photoId: true,
+        entityVersion: true,
+        priority: true,
+        payload: true,
+        occurredAt: true,
+      },
+    });
+    if (high.length >= this.batchSize) {
+      return high;
+    }
+    const rest = await prisma.outbox_events.findMany({
+      where: { deliveredAt: null, priority: { not: 'high' } },
+      orderBy: [{ occurredAt: 'asc' }, { id: 'asc' }],
+      take: this.batchSize - high.length,
+      select: {
+        id: true,
+        type: true,
+        albumId: true,
+        photoId: true,
+        entityVersion: true,
+        priority: true,
+        payload: true,
+        occurredAt: true,
+      },
+    });
+    return [...high, ...rest];
+  }
+
+  /**
+   * outbox 行 → SyncEvent 线格式。entityId 按实体类型取自不同位置：
+   * album → albumId 列；photo → photoId 列；category/asset → 载荷内的
+   * categoryId/assetId（outbox 表无此二列）。映射缺料抛错（fail-fast：
+   * 本轮不推、不标记，错误日志暴露；cn 侧发射器按构造保证不缺料）。
+   */
+  private toWireEvent(row: OutboxRow): SyncEventWire {
+    const type = row.type as OutboxEvent['type'];
+    const entityType = syncEntityTypeOfOutboxType(type);
+    const payload = (row.payload ?? {}) as Record<string, unknown>;
+    let entityId: string;
+    if (entityType === 'album') {
+      entityId = row.albumId;
+    } else if (entityType === 'photo') {
+      if (row.photoId === null) {
+        throw new Error(`outbox 事件 ${row.id}（${type}）缺 photoId，无法推导 entityId`);
+      }
+      entityId = row.photoId;
+    } else if (typeof payload.categoryId === 'string') {
+      entityId = payload.categoryId;
+    } else if (typeof payload.assetId === 'string') {
+      entityId = payload.assetId;
+    } else {
+      throw new Error(`outbox 事件 ${row.id}（${type}）载荷缺实体 ID，无法推导 entityId`);
+    }
+    const tombstone = isTombstoneOutboxType(type);
+    return {
+      eventId: row.id,
+      schemaVersion: 1,
+      entityType,
+      entityId,
+      albumId: row.albumId,
+      entityVersion: row.entityVersion,
+      // 线格式 tombstone 显式携带（生成类型必填：openapi-typescript 把带
+      // default 的属性渲染为非可选）。
+      tombstone,
+      priority: row.priority === 'high' ? 'high' : 'normal',
+      payload: payload as SyncEventWire['payload'],
+    };
+  }
+
+  /**
+   * 签名推送：同一 JSON.stringify 产物既作签名输入也作请求体（原始字节一致，
+   * 接收端 rawBody 验签才能通过——见 contracts/internal-sync.ts 头注）。
+   * 非 2xx / 响应形状异常均抛错（调用方整批重试）。
+   */
+  private async push(events: SyncEventWire[]): Promise<ContentBatchResponse> {
+    const rawBody = JSON.stringify({ batch: events });
+    const timestamp = Math.floor(Date.now() / 1000).toString();
+    let response: Response;
+    try {
+      response = await fetch(this.endpoint, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          [SYNC_TIMESTAMP_HEADER]: timestamp,
+          [SYNC_SIGNATURE_HEADER]: signSyncBody(this.options.internalKey, rawBody),
+        },
+        body: rawBody,
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (err) {
+      throw new Error(
+        `content-batches 请求失败（${this.endpoint}）：${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    if (!response.ok) {
+      const body = await response.text().catch(() => '');
+      throw new Error(
+        `content-batches 非 2xx（${this.endpoint}）：status=${response.status} body=${body.slice(0, 500)}`,
+      );
+    }
+    const data: unknown = await response.json();
+    if (
+      typeof data !== 'object' ||
+      data === null ||
+      !Array.isArray((data as ContentBatchResponse).acceptedEventIds) ||
+      !((data as ContentBatchResponse).acceptedEventIds as unknown[]).every(
+        (id) => typeof id === 'string',
+      ) ||
+      typeof (data as ContentBatchResponse).applied !== 'number'
+    ) {
+      throw new Error('content-batches 响应形状异常（acceptedEventIds/applied 缺失）');
+    }
+    return data as ContentBatchResponse;
+  }
+}

services/sync/test/load-env.ts

@@ -0,0 +1,7 @@
+// services/sync/test/load-env.ts
+// 全仓库唯一 env 加载机制（Jest 侧）：仓库根 .env（与 services/api 同约定）。
+// 开发/生产经根 dotenv-cli 注入；运行时代码只读 process.env。
+import { join } from 'node:path';
+import { config } from 'dotenv';
+
+config({ path: join(__dirname, '../../../.env') });

services/sync/test/sync.e2e-spec.ts

@@ -0,0 +1,787 @@
+// services/sync/test/sync.e2e-spec.ts —— P2 Task 3 cn→ov 同步链路 E2E。
+// ONE spec 串完整同步流：进程内起**两个真实 HTTP 入口**（cn=AppCnModule、
+// ov=AppOvModule，均 NestFactory rawBody:true + configureApp + listen(0)），
+// 发送器为生产 OutboxSender 实例（指向 ov 入口真实 URL），业务动作全走 cn
+// 公开 API（登录/建相册/分类/上传/complete），发布事务直驱 worker
+// PublishService（同 api full-chain e2e 模式，免 BullMQ 异步等待）。
+//
+// 覆盖（任务验收 8 场景）：
+//   ① 全链路复制：相册+分类+发布照片 → 排空发送器 → ov 副本齐备；
+//   ② 相册下线（publicEnabled=false）→ outbox high 优先 + 批内先于更早发生的
+//      normal 事件被受理；
+//   ③ 重复推送幂等：清 deliveredAt 模拟「推送成功未确认」重推 → 受理 applied=0；
+//   ④ 隐藏照片 → photos_ov.visibility=hidden；旧 published 以新 eventId 重放不
+//      复活（A26 版本单调）；同 eventId 重放受理不计应用；
+//   ⑤ bootstrap 空 ov → 快照事件入 outbox（eventCount/watermark）→ 排空 →
+//      副本反映**当前**状态（下线/隐藏仍在）；
+//   ⑥ 依赖暂存：ov 无相册行时 photo 事件 appliedAt=null 暂存，album 事件到达
+//      即回扫补应用；
+//   ⑦ HMAC 验签：缺头/错签/签名覆盖体不符/时间戳超窗 → 401 SYNC_AUTH_FAILED
+//      （ov content-batches + cn bootstrap 同一守卫）；
+//   ⑧ reconcile：按 entityType 返回当前状态清单（sinceVersion 过滤/升序）；
+//   ⑨ 乱序：v7 hidden 先应用、迟到的 v6 published 被版本比较拒绝（A26）。
+// 真实 MySQL×2 + MinIO（staging/originals/variants）+ HMAC 全链路字节一致。
+import { randomUUID } from 'node:crypto';
+import { NestFactory } from '@nestjs/core';
+import { type NestExpressApplication } from '@nestjs/platform-express';
+import request from 'supertest';
+import sharp from 'sharp';
+import { PrismaClient } from '@photo/db-cn';
+import { PrismaClient as OvPrismaClient } from '@photo/db-ov';
+import { ErrorCodes, signSyncBody } from '@photo/contracts';
+import {
+  createStorageFromEnv,
+  type MinioStorageAdapter,
+} from '@photo/storage';
+import { AppCnModule } from '../../api/src/app-cn.module';
+import { AppOvModule } from '../../api/src/app-ov.module';
+import { seedAdmin } from '../../api/src/scripts/seed-admin';
+import { configureApp } from '../../api/src/shared/configure-app';
+import { PublishService } from '../../worker/src/publish.service';
+import { resetDb } from '../../api/test/reset';
+import { resetOvDb } from '../../api/test/reset-ov';
+import { OutboxSender } from '../src/sender';
+
+jest.setTimeout(180_000);
+
+const ADMIN_ACCOUNT = process.env.ADMIN_ACCOUNT ?? 'admin';
+const ADMIN_PASSWORD = process.env.ADMIN_PASSWORD ?? 'admin-secret-change-me';
+const SYNC_KEY = process.env.SYNC_INTERNAL_KEY ?? 'dev-sync-secret-change-me';
+
+const CONTENT_BATCHES_PATH = '/v1/internal/sync/content-batches';
+const BOOTSTRAP_PATH = '/v1/internal/sync/bootstrap';
+const RECONCILE_PATH = '/v1/internal/sync/reconcile';
+
+/** 测试内生成真实 JPEG（同 api full-chain e2e；无二进制入库）。 */
+async function makeJpeg(
+  width: number,
+  height: number,
+  rgb: { r: number; g: number; b: number },
+): Promise<Buffer> {
+  return sharp({ create: { width, height, channels: 3, background: rgb } })
+    .jpeg({ quality: 85 })
+    .toBuffer();
+}
+
+/** 签名 POST（可注入坏签名/时间戳偏移/缺头，场景⑦专用）。 */
+interface SignOverrides {
+  signature?: string;
+  timestampOffsetSeconds?: number;
+  omitSignature?: boolean;
+  omitTimestamp?: boolean;
+}
+
+async function signedPost(
+  base: string,
+  path: string,
+  body: unknown,
+  overrides: SignOverrides = {},
+): Promise<Response> {
+  const raw = JSON.stringify(body);
+  const headers: Record<string, string> = { 'content-type': 'application/json' };
+  if (!overrides.omitTimestamp) {
+    headers['x-sync-timestamp'] = String(
+      Math.floor(Date.now() / 1000) + (overrides.timestampOffsetSeconds ?? 0),
+    );
+  }
+  if (!overrides.omitSignature) {
+    headers['x-sync-signature'] =
+      overrides.signature ?? signSyncBody(SYNC_KEY, raw);
+  }
+  return fetch(`${base}${path}`, { method: 'POST', headers, body: raw });
+}
+
+/** 线格式事件（openapi SyncEvent；测试内手工构造乱序/重放/暂存场景）。 */
+interface WireEvent {
+  eventId: string;
+  schemaVersion: 1;
+  entityType: 'album' | 'category' | 'photo' | 'asset';
+  entityId: string;
+  albumId: string;
+  entityVersion: number;
+  tombstone: boolean;
+  priority: 'normal' | 'high';
+  payload: Record<string, unknown>;
+}
+
+/** reconcile 清单元素（断言用形状）。 */
+interface ReconEvent {
+  eventId: string;
+  schemaVersion: number;
+  entityType: string;
+  entityId: string;
+  entityVersion: number;
+  payload: {
+    albumId?: string;
+    publicEnabled?: boolean;
+    visibility?: string;
+    entityVersion?: number;
+  };
+}
+
+describe('sync cn→ov (e2e)', () => {
+  let cnApp: NestExpressApplication;
+  let ovApp: NestExpressApplication;
+  let cnBase: string;
+  let ovBase: string;
+  let prismaCn: PrismaClient;
+  let prismaOv: OvPrismaClient;
+  let storage: MinioStorageAdapter;
+  let sender: OutboxSender;
+  let adminToken: string;
+
+  let albumId: string;
+  let publicToken: string;
+  let categoryId: string;
+  let photo1: { photoId: string; objectKey: string };
+  let photo2: { photoId: string; objectKey: string };
+  /** 场景②的 high 事件行 id（场景③复用）。 */
+  let offlineEventId: string;
+  /** photo2 的 published 载荷（场景⑨乱序重放用）。 */
+  let photo2PublishedPayload: Record<string, unknown>;
+
+  /** 排空发送器：循环 runOnce 直至无未投递事件（每轮整批推送）。 */
+  async function drainSender(): Promise<void> {
+    for (let round = 0; round < 20; round++) {
+      const stats = await sender.runOnce();
+      if (stats.picked === 0) {
+        return;
+      }
+    }
+    throw new Error('drainSender 超时：20 轮后 outbox 仍有未投递事件');
+  }
+
+  /** 上传全链路：init → presign PUT 实写 MinIO → complete → 直驱发布事务。 */
+  async function uploadAndPublish(
+    clientTaskId: string,
+    jpeg: Buffer,
+  ): Promise<{ photoId: string; objectKey: string }> {
+    const init = await request(cnBase)
+      .post('/v1/uploads')
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({
+        albumId,
+        clientTaskId,
+        filename: 'sync.jpg',
+        bytes: jpeg.length,
+        contentType: 'image/jpeg',
+        categoryId,
+      });
+    expect(init.status).toBe(201);
+    const { uploadId, photoId, credential } = init.body as {
+      uploadId: string;
+      photoId: string;
+      credential: { url: string; method: string; headers: Record<string, string> };
+    };
+    const put = await fetch(credential.url, {
+      method: credential.method,
+      headers: credential.headers,
+      body: new Uint8Array(jpeg),
+    });
+    expect(put.ok).toBe(true);
+    const done = await request(cnBase)
+      .post(`/v1/uploads/${uploadId}/complete`)
+      .set('Authorization', `Bearer ${adminToken}`);
+    expect(done.status).toBe(200);
+    expect(await new PublishService(prismaCn, storage).processPhoto(photoId)).toBe(
+      'published',
+    );
+    // init 响应的 objectKey 是 staging 键；complete 受控复制后正式键在 DB 行上
+    //（同 api full-chain e2e 的取值口径）。
+    const finalKey = (
+      await prismaCn.photos.findUniqueOrThrow({
+        where: { id: photoId },
+        select: { objectKey: true },
+      })
+    ).objectKey;
+    return { photoId, objectKey: finalKey };
+  }
+
+  /** 直推 ov content-batches（绕过发送器，构造乱序/重放/暂存场景）。 */
+  async function pushEvents(
+    events: WireEvent[],
+  ): Promise<{ acceptedEventIds: string[]; applied: number }> {
+    const res = await signedPost(ovBase, CONTENT_BATCHES_PATH, { batch: events });
+    expect(res.status).toBe(200);
+    return (await res.json()) as { acceptedEventIds: string[]; applied: number };
+  }
+
+  beforeAll(async () => {
+    expect(SYNC_KEY).not.toBe('');
+    await resetDb();
+    await resetOvDb();
+
+    cnApp = await NestFactory.create<NestExpressApplication>(AppCnModule, {
+      rawBody: true,
+    });
+    configureApp(cnApp);
+    await cnApp.listen(0);
+    cnBase = await cnApp.getUrl();
+
+    ovApp = await NestFactory.create<NestExpressApplication>(AppOvModule, {
+      rawBody: true,
+    });
+    configureApp(ovApp);
+    await ovApp.listen(0);
+    ovBase = await ovApp.getUrl();
+
+    prismaCn = new PrismaClient();
+    prismaOv = new OvPrismaClient();
+    storage = createStorageFromEnv();
+    sender = new OutboxSender({
+      prisma: prismaCn,
+      ovApiUrl: ovBase,
+      internalKey: SYNC_KEY,
+    });
+
+    await seedAdmin(prismaCn, ADMIN_ACCOUNT, ADMIN_PASSWORD);
+    const login = await request(cnBase).post('/v1/auth/password').send({
+      account: ADMIN_ACCOUNT,
+      password: ADMIN_PASSWORD,
+    });
+    expect(login.status).toBe(200);
+    adminToken = login.body.sessionToken as string;
+  });
+
+  afterAll(async () => {
+    await cnApp.close();
+    await ovApp.close();
+    await prismaCn.$disconnect();
+    await prismaOv.$disconnect();
+  });
+
+  it('① 全链路复制：建相册+分类+发布照片 → 发送器排空 → ov 副本齐备', async () => {
+    const album = await request(cnBase)
+      .post('/v1/albums')
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({
+        translations: [
+          { locale: 'zh-CN', title: '同步晚会', description: '端到端验收' },
+          { locale: 'en', title: 'Sync Gala' },
+        ],
+        defaultLocale: 'zh-CN',
+        startAt: '2026-10-01T10:00:00.000Z',
+      });
+    expect(album.status).toBe(201);
+    albumId = album.body.id as string;
+    publicToken = album.body.publicToken as string;
+
+    const category = await request(cnBase)
+      .post(`/v1/albums/${albumId}/categories`)
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({
+        sortOrder: 0,
+        translations: [
+          { locale: 'zh-CN', name: '主舞台' },
+          { locale: 'en', name: 'Main Stage' },
+        ],
+      });
+    expect(category.status).toBe(201);
+    categoryId = category.body.id as string;
+
+    photo1 = await uploadAndPublish(
+      'sync-a',
+      await makeJpeg(900, 600, { r: 180, g: 120, b: 60 }),
+    );
+    await drainSender();
+
+    // outbox：三类事件均已确认投递。
+    const albumEvent = await prismaCn.outbox_events.findFirstOrThrow({
+      where: { type: 'album.updated', albumId },
+    });
+    expect(albumEvent).toMatchObject({ entityVersion: 1, priority: 'normal' });
+    expect(albumEvent.deliveredAt).not.toBeNull();
+    expect(
+      await prismaCn.outbox_events.count({
+        where: { deliveredAt: null },
+      }),
+    ).toBe(0);
+
+    // ov：相册副本（标量 + 翻译 locale 升序 + 分类 JSON 元素）。
+    const albumReplica = await prismaOv.albums_ov.findUniqueOrThrow({
+      where: { albumId },
+    });
+    expect(albumReplica).toMatchObject({
+      publicToken,
+      publicEnabled: true,
+      defaultLocale: 'zh-CN',
+      entityVersion: 1,
+    });
+    expect(albumReplica.translations).toEqual([
+      { locale: 'en', title: 'Sync Gala', description: null, venue: null, address: null },
+      {
+        locale: 'zh-CN',
+        title: '同步晚会',
+        description: '端到端验收',
+        venue: null,
+        address: null,
+      },
+    ]);
+    expect(albumReplica.categories).toEqual([
+      {
+        id: categoryId,
+        sortOrder: 0,
+        translations: [
+          { locale: 'en', name: 'Main Stage' },
+          { locale: 'zh-CN', name: '主舞台' },
+        ],
+      },
+    ]);
+
+    // ov：照片副本（发布载荷全量：三键 + 尺寸 + publishedAt）。
+    const photoReplica = await prismaOv.photos_ov.findUniqueOrThrow({
+      where: { photoId: photo1.photoId },
+    });
+    expect(photoReplica).toMatchObject({
+      albumId,
+      originalObjectKey: photo1.objectKey,
+      visibility: 'published',
+      width: 900,
+      height: 600,
+      entityVersion: 2,
+    });
+    expect(photoReplica.thumbObjectKey).toContain(`/variants/${photo1.photoId}/`);
+    expect(photoReplica.browseObjectKey).toContain(`/variants/${photo1.photoId}/`);
+    expect(photoReplica.publishedAt).not.toBeNull();
+
+    // ov：版本账本。
+    for (const [entityType, entityId, appliedVersion] of [
+      ['album', albumId, 1],
+      ['category', categoryId, 1],
+      ['photo', photo1.photoId, 2],
+    ] as const) {
+      expect(
+        await prismaOv.sync_state.findUniqueOrThrow({
+          where: { entityType_entityId: { entityType, entityId } },
+        }),
+      ).toMatchObject({ appliedVersion, watermark: false });
+    }
+  });
+
+  it('② 相册下线 → high 优先事件先于更早发生的 normal 事件被受理', async () => {
+    // 先造一条更早发生的 normal 事件（photo2 发布），再下线相册（high）。
+    photo2 = await uploadAndPublish(
+      'sync-b',
+      await makeJpeg(800, 600, { r: 60, g: 130, b: 180 }),
+    );
+    const offline = await request(cnBase)
+      .patch(`/v1/albums/${albumId}`)
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({ publicEnabled: false });
+    expect(offline.status).toBe(200);
+    expect(offline.body).toMatchObject({ id: albumId, publicEnabled: false });
+
+    const highRow = await prismaCn.outbox_events.findFirstOrThrow({
+      where: { deliveredAt: null, priority: 'high' },
+    });
+    expect(highRow).toMatchObject({ type: 'album.updated', entityVersion: 2 });
+    offlineEventId = highRow.id;
+    const photo2Row = await prismaCn.outbox_events.findFirstOrThrow({
+      where: { deliveredAt: null, type: 'photo.published', photoId: photo2.photoId },
+    });
+
+    const stats = await sender.runOnce();
+    expect(stats.picked).toBe(2);
+    expect(stats.applied).toBe(2);
+    // 顺序断言：high（后发生）先于 normal（先发生）。
+    expect(stats.acceptedEventIds).toEqual([offlineEventId, photo2Row.id]);
+
+    expect(
+      await prismaOv.albums_ov.findUniqueOrThrow({ where: { albumId } }),
+    ).toMatchObject({ publicEnabled: false, entityVersion: 2 });
+    expect(
+      await prismaOv.photos_ov.findUniqueOrThrow({ where: { photoId: photo2.photoId } }),
+    ).toMatchObject({ visibility: 'published', entityVersion: 2 });
+  });
+
+  it('③ 重复推送幂等：重推已应用 eventId → 受理但 applied=0', async () => {
+    // 模拟「ov 已应用、cn 未收到确认」：清 deliveredAt 让发送器重推同一事件。
+    await prismaCn.outbox_events.update({
+      where: { id: offlineEventId },
+      data: { deliveredAt: null },
+    });
+    const stats = await sender.runOnce();
+    expect(stats.picked).toBe(1);
+    expect(stats.acceptedEventIds).toEqual([offlineEventId]);
+    expect(stats.applied).toBe(0);
+
+    const replica = await prismaOv.albums_ov.findUniqueOrThrow({
+      where: { albumId },
+    });
+    expect(replica).toMatchObject({ publicEnabled: false, entityVersion: 2 });
+    expect(
+      (await prismaCn.outbox_events.findUniqueOrThrow({
+        where: { id: offlineEventId },
+      })).deliveredAt,
+    ).not.toBeNull();
+  });
+
+  it('④ 隐藏照片 → photos_ov.hidden；旧 published 重放不复活（A26）', async () => {
+    const hide = await request(cnBase)
+      .patch(`/v1/photos/${photo1.photoId}`)
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({ visibility: 'hidden' });
+    expect(hide.status).toBe(200);
+
+    const hiddenRow = await prismaCn.outbox_events.findFirstOrThrow({
+      where: { type: 'photo.hidden', photoId: photo1.photoId },
+    });
+    expect(hiddenRow).toMatchObject({ entityVersion: 3, priority: 'high' });
+    await drainSender();
+
+    expect(
+      await prismaOv.photos_ov.findUniqueOrThrow({
+        where: { photoId: photo1.photoId },
+      }),
+    ).toMatchObject({ visibility: 'hidden', entityVersion: 3 });
+
+    // A26：旧 published（v2）换新 eventId 重放 → 版本比较拒绝，不复活。
+    const publishedRow = await prismaCn.outbox_events.findFirstOrThrow({
+      where: { type: 'photo.published', photoId: photo1.photoId },
+    });
+    const replayId = `e2e-${randomUUID()}`;
+    const replay = await pushEvents([
+      {
+        eventId: replayId,
+        schemaVersion: 1,
+        entityType: 'photo',
+        entityId: photo1.photoId,
+        albumId,
+        entityVersion: 2,
+        tombstone: false,
+        priority: 'normal',
+        payload: publishedRow.payload as Record<string, unknown>,
+      },
+    ]);
+    expect(replay).toEqual({ acceptedEventIds: [replayId], applied: 0 });
+    expect(
+      await prismaOv.photos_ov.findUniqueOrThrow({
+        where: { photoId: photo1.photoId },
+      }),
+    ).toMatchObject({ visibility: 'hidden', entityVersion: 3 });
+
+    // 同 eventId 重放：受理不计应用（eventId 幂等锚）。
+    const again = await pushEvents([
+      {
+        eventId: hiddenRow.id,
+        schemaVersion: 1,
+        entityType: 'photo',
+        entityId: photo1.photoId,
+        albumId,
+        entityVersion: 3,
+        tombstone: false,
+        priority: 'high',
+        payload: hiddenRow.payload as Record<string, unknown>,
+      },
+    ]);
+    expect(again).toEqual({ acceptedEventIds: [hiddenRow.id], applied: 0 });
+  });
+
+  it('⑤ bootstrap 空 ov → 快照入 outbox（eventCount/watermark）→ 副本反映当前状态', async () => {
+    await resetOvDb();
+    const boot = await signedPost(cnBase, BOOTSTRAP_PATH, { albumId });
+    expect(boot.status).toBe(200);
+    // 当前状态：album v2（下线）+ category v1 + photo1 hidden v3 + photo2 published v2。
+    expect(await boot.json()).toEqual({ eventCount: 4, watermark: 3 });
+    expect(
+      await prismaCn.outbox_events.count({ where: { deliveredAt: null } }),
+    ).toBe(4);
+
+    await drainSender();
+
+    expect(
+      await prismaOv.albums_ov.findUniqueOrThrow({ where: { albumId } }),
+    ).toMatchObject({ publicEnabled: false, entityVersion: 2 });
+    // photo1 当前为 hidden 且空 ov 上从无 published 副本 → 无行（缺席即撤下
+    // 语义），版本账本照常推进（旧 published 重放会被版本比较拒绝）。
+    expect(
+      await prismaOv.photos_ov.count({ where: { photoId: photo1.photoId } }),
+    ).toBe(0);
+    expect(
+      await prismaOv.sync_state.findUniqueOrThrow({
+        where: {
+          entityType_entityId: { entityType: 'photo', entityId: photo1.photoId },
+        },
+      }),
+    ).toMatchObject({ appliedVersion: 3, watermark: false });
+    expect(
+      await prismaOv.photos_ov.findUniqueOrThrow({
+        where: { photoId: photo2.photoId },
+      }),
+    ).toMatchObject({ visibility: 'published', entityVersion: 2 });
+    expect(await prismaOv.sync_state.count({ where: { watermark: false } })).toBe(
+      4,
+    );
+  });
+
+  it('⑥ 依赖暂存：相册缺失时 photo 暂存，album 到达后回扫补应用', async () => {
+    await resetOvDb();
+    const source = await prismaCn.outbox_events.findFirstOrThrow({
+      where: { type: 'photo.published', photoId: photo2.photoId },
+    });
+    photo2PublishedPayload = source.payload as Record<string, unknown>;
+
+    const stagedId = `e2e-${randomUUID()}`;
+    const stage = await pushEvents([
+      {
+        eventId: stagedId,
+        schemaVersion: 1,
+        entityType: 'photo',
+        entityId: photo2.photoId,
+        albumId,
+        entityVersion: 2,
+        tombstone: false,
+        priority: 'normal',
+        payload: photo2PublishedPayload,
+      },
+    ]);
+    expect(stage).toEqual({ acceptedEventIds: [stagedId], applied: 0 });
+    // 暂存：inbox 行在、appliedAt 为空、无副本投影、无版本账本。
+    expect(
+      await prismaOv.sync_inbox.findUniqueOrThrow({ where: { eventId: stagedId } }),
+    ).toMatchObject({ appliedAt: null, entityType: 'photo' });
+    expect(await prismaOv.photos_ov.count({ where: { albumId } })).toBe(0);
+    expect(
+      await prismaOv.sync_state.count({
+        where: { entityType: 'photo', entityId: photo2.photoId },
+      }),
+    ).toBe(0);
+
+    // album 事件到达：应用 + 回扫暂存（photo 补应用）。
+    const albumSource = await prismaCn.outbox_events.findFirstOrThrow({
+      where: { type: 'album.updated', albumId },
+      orderBy: { occurredAt: 'desc' },
+    });
+    const albumEventId = `e2e-${randomUUID()}`;
+    const unlock = await pushEvents([
+      {
+        eventId: albumEventId,
+        schemaVersion: 1,
+        entityType: 'album',
+        entityId: albumId,
+        albumId,
+        entityVersion: albumSource.entityVersion,
+        tombstone: false,
+        priority: 'normal',
+        payload: albumSource.payload as Record<string, unknown>,
+      },
+    ]);
+    expect(unlock).toEqual({
+      acceptedEventIds: [albumEventId],
+      applied: 2, // album 自身 + 回扫的 photo
+    });
+    expect(await prismaOv.albums_ov.count({ where: { albumId } })).toBe(1);
+    expect(
+      await prismaOv.photos_ov.findUniqueOrThrow({
+        where: { photoId: photo2.photoId },
+      }),
+    ).toMatchObject({ visibility: 'published', entityVersion: 2 });
+    expect(
+      (
+        await prismaOv.sync_inbox.findUniqueOrThrow({
+          where: { eventId: stagedId },
+        })
+      ).appliedAt,
+    ).not.toBeNull();
+  });
+
+  it('⑦ HMAC 验签：缺头/错签/签名体不符/时间戳超窗 → 401 SYNC_AUTH_FAILED', async () => {
+    const body = {
+      batch: [
+        {
+          eventId: `e2e-${randomUUID()}`,
+          schemaVersion: 1,
+          entityType: 'album',
+          entityId: 'hmac-probe',
+          albumId: 'hmac-probe',
+          entityVersion: 1,
+          tombstone: false,
+          priority: 'normal',
+          payload: {},
+        },
+      ],
+    };
+    const expectUnauthorized = async (res: Promise<Response>): Promise<void> => {
+      const settled = await res;
+      expect(settled.status).toBe(401);
+      expect(((await settled.json()) as { code: string }).code).toBe(
+        ErrorCodes.SYNC_AUTH_FAILED,
+      );
+    };
+
+    // 缺签名/时间戳头。
+    await expectUnauthorized(
+      signedPost(ovBase, CONTENT_BATCHES_PATH, body, {
+        omitSignature: true,
+        omitTimestamp: true,
+      }),
+    );
+    // 形状合法的错签。
+    await expectUnauthorized(
+      signedPost(ovBase, CONTENT_BATCHES_PATH, body, { signature: '0'.repeat(64) }),
+    );
+    // 签名覆盖体与实际请求体不符（验的是原始字节，非重序列化 body）。
+    await expectUnauthorized(
+      signedPost(ovBase, CONTENT_BATCHES_PATH, body, {
+        signature: signSyncBody(SYNC_KEY, '{"batch":[]}'),
+      }),
+    );
+    // 时间戳超窗（签名本身有效）。
+    await expectUnauthorized(
+      signedPost(ovBase, CONTENT_BATCHES_PATH, body, {
+        timestampOffsetSeconds: -400,
+      }),
+    );
+    // cn 侧端点同一守卫。
+    await expectUnauthorized(
+      signedPost(cnBase, BOOTSTRAP_PATH, {}, { omitSignature: true }),
+    );
+  });
+
+  it('⑧ reconcile：按 entityType 返回当前状态清单（sinceVersion 过滤、升序）', async () => {
+    const albumList = await signedPost(cnBase, RECONCILE_PATH, {
+      entityType: 'album',
+      sinceVersion: 0,
+      limit: 10,
+    });
+    expect(albumList.status).toBe(200);
+    const albumEvents = ((await albumList.json()) as { events: ReconEvent[] })
+      .events;
+    expect(albumEvents).toHaveLength(1);
+    expect(albumEvents[0]).toMatchObject({
+      eventId: `recon:album:${albumId}:2`,
+      schemaVersion: 1,
+      entityType: 'album',
+      entityId: albumId,
+      entityVersion: 2,
+      priority: 'normal',
+    });
+    expect(albumEvents[0].payload).toMatchObject({
+      albumId,
+      publicEnabled: false,
+      entityVersion: 2,
+    });
+
+    const photoList = await signedPost(cnBase, RECONCILE_PATH, {
+      entityType: 'photo',
+      albumId,
+      sinceVersion: 0,
+      limit: 10,
+    });
+    expect(photoList.status).toBe(200);
+    const photoEvents = ((await photoList.json()) as { events: ReconEvent[] })
+      .events;
+    // 升序：photo2 v2（published）→ photo1 v3（hidden）。
+    expect(
+      photoEvents.map((e) => [e.entityId, e.entityVersion]),
+    ).toEqual([
+      [photo2.photoId, 2],
+      [photo1.photoId, 3],
+    ]);
+    expect(photoEvents[1].payload.visibility).toBe('hidden');
+
+    // sinceVersion=当前版本 → 空（增量语义）。
+    const empty = await signedPost(cnBase, RECONCILE_PATH, {
+      entityType: 'album',
+      sinceVersion: 2,
+      limit: 10,
+    });
+    expect(((await empty.json()) as { events: unknown[] }).events).toEqual([]);
+  });
+
+  it('⑨ 乱序：v7 hidden 先应用、迟到的 v6 published 不复活（A26）', async () => {
+    const v7Id = `e2e-${randomUUID()}`;
+    const first = await pushEvents([
+      {
+        eventId: v7Id,
+        schemaVersion: 1,
+        entityType: 'photo',
+        entityId: photo2.photoId,
+        albumId,
+        entityVersion: 7,
+        tombstone: false,
+        priority: 'high',
+        payload: {
+          photoId: photo2.photoId,
+          albumId,
+          visibility: 'hidden',
+          entityVersion: 7,
+        },
+      },
+    ]);
+    expect(first).toEqual({ acceptedEventIds: [v7Id], applied: 1 });
+    expect(
+      await prismaOv.photos_ov.findUniqueOrThrow({
+        where: { photoId: photo2.photoId },
+      }),
+    ).toMatchObject({ visibility: 'hidden', entityVersion: 7 });
+
+    const v6Id = `e2e-${randomUUID()}`;
+    const second = await pushEvents([
+      {
+        eventId: v6Id,
+        schemaVersion: 1,
+        entityType: 'photo',
+        entityId: photo2.photoId,
+        albumId,
+        entityVersion: 6,
+        tombstone: false,
+        priority: 'normal',
+        payload: { ...photo2PublishedPayload, entityVersion: 6 },
+      },
+    ]);
+    expect(second).toEqual({ acceptedEventIds: [v6Id], applied: 0 });
+    expect(
+      await prismaOv.photos_ov.findUniqueOrThrow({
+        where: { photoId: photo2.photoId },
+      }),
+    ).toMatchObject({ visibility: 'hidden', entityVersion: 7 });
+  });
+
+  it('⑩ 分类更新/删除：category.updated 投影 upsert、墓碑移除元素', async () => {
+    const rename = await request(cnBase)
+      .patch(`/v1/categories/${categoryId}`)
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({
+        sortOrder: 5,
+        translations: [
+          { locale: 'zh-CN', name: '主舞台' },
+          { locale: 'en', name: 'Main Stage Renamed' },
+        ],
+      });
+    expect(rename.status).toBe(200);
+    const updatedRow = await prismaCn.outbox_events.findFirstOrThrow({
+      where: { type: 'category.updated', albumId },
+      orderBy: { occurredAt: 'desc' },
+    });
+    expect(updatedRow).toMatchObject({ entityVersion: 2, priority: 'normal' });
+    await drainSender();
+    let replica = await prismaOv.albums_ov.findUniqueOrThrow({
+      where: { albumId },
+    });
+    expect(replica.categories).toEqual([
+      {
+        id: categoryId,
+        sortOrder: 5,
+        translations: [
+          { locale: 'en', name: 'Main Stage Renamed' },
+          { locale: 'zh-CN', name: '主舞台' },
+        ],
+      },
+    ]);
+
+    const remove = await request(cnBase)
+      .delete(`/v1/categories/${categoryId}`)
+      .set('Authorization', `Bearer ${adminToken}`);
+    expect(remove.status).toBe(204);
+    const tombstoneRow = await prismaCn.outbox_events.findFirstOrThrow({
+      where: { type: 'category.deleted', albumId },
+    });
+    expect(tombstoneRow.entityVersion).toBe(3);
+    await drainSender();
+    replica = await prismaOv.albums_ov.findUniqueOrThrow({
+      where: { albumId },
+    });
+    expect(replica.categories).toEqual([]);
+  });
+});

services/sync/tsconfig.build.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "test", "**/*.spec.ts", "**/*.e2e-spec.ts"]
+}

services/sync/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "moduleResolution": "node10",
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "declaration": false,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "types": ["node", "jest"]
+  },
+  "include": ["src", "test"]
+}