feat(contracts,api): UI-01 cover, preview, scope=own and embed config extensions

契约扩展（全部可选/可空，旧客户端零感知）+ cn/ov 实现 + e2e 权限矩阵：
- AlbumSummary += cover（kind=cover state=effective 最新行的短期签名 URL，
  列表/详情按页批量组装非 N+1；未配置为 null）
- AdminPhoto += preview{thumb,browse}（变体齐备且未删除才签发；隐藏仅
  admin/owner；协作者仅自己上传，scope=own 服务端过滤 uploaderId，
  成员资格逐请求裁决）
- listAlbumPhotos += scope=all|own（缺省 all 行为不变：仅 owner/admin，
  协作者 403；own 任何有效成员）
- EmbedSlotSettings += imageFit/offsetX/offsetBottom/zIndex（cn PATCH 校验
  → slot-state 投影 → ov 公开回读；settings 为 Json 列免迁移，读侧
  normalizeStoredSettings 兜旧形状默认值）
- Flutter 模型同步（SignedUrl/PhotoPreview/AlbumPhotoScope，可空容错）

e2e：ui01-contracts 9 例（封面选取/字节取回/N+1 计数断言、preview 权限
矩阵、scope 过滤与 403/404/400）+ embed ⑨ 配置链路；全量 e2e 257 通过。

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

services/api/src/albums/albums.service.ts

@@ -13,12 +13,18 @@
 //     映射，P1a 规模下先查成员 albumId 集再 id IN ——成员相册数为个位到十位级，
 //     不构成规模问题；若 P5 需要，可换 $queryRaw 子查询，接口不变）。
 //     排序 createdAt DESC, id DESC（稳定决胜），游标经 shared/cursor 键集推进。
+//   · 封面摘要（UI-01）：AlbumSummary.cover = album_assets kind=cover、
+//     state=effective 的最新一行的短期签名 URL（未配置为 null）。列表按页
+//     一次 findMany 批量取（orderBy createdAt/id DESC 后每相册取首行，同
+//     banner「新行生效」替换语义），presign 为 SigV4 本地计算——两者都不随
+//     相册数放大，杜绝逐相册 N+1。
 // 响应映射严格契约 camelCase（DB snake 列名 → AlbumSummary/Album 形状）。
 import { randomBytes } from 'node:crypto';
-import { HttpStatus, Injectable } from '@nestjs/common';
+import { HttpStatus, Inject, Injectable } from '@nestjs/common';
 import { ErrorCodes } from '@photo/contracts';
 import type { components } from '@photo/contracts';
 import type { Prisma } from '@photo/db-cn';
+import type { StoragePort } from '@photo/storage';
 import { ApiException } from '../api-exception';
 import type { AuthUser } from '../auth/session.guard';
 import { PrismaService } from '../prisma/prisma.service';
@@ -28,6 +34,8 @@ import {
   keysetWhereDesc,
 } from '../shared/cursor';
 import { buildAlbumUpdatedPayload } from '../sync/payloads';
+import { STORAGE_PORT } from '../uploads/storage.provider';
+import { signedUrlTtlSeconds } from '../uploads/support';
 import type {
   AlbumCreateRequestDto,
   AlbumTransferRequestDto,
@@ -46,6 +54,7 @@ export type AlbumTranslationResponse =
 export type AlbumSummaryResponse = components['schemas']['AlbumSummary'];
 export type AlbumResponse = components['schemas']['Album'];
 export type AlbumListResponse = components['schemas']['AlbumList'];
+type SignedUrlResponse = components['schemas']['SignedUrl'];
 
 const PUBLIC_TOKEN_LENGTH = 24;
 const PUBLIC_TOKEN_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
@@ -97,6 +106,7 @@ function toTranslationResponse(
 function toSummaryResponse(
   album: AlbumRow,
   translations: AlbumTranslationRow[],
+  cover: SignedUrlResponse | null = null,
 ): AlbumSummaryResponse {
   return {
     id: album.id,
@@ -118,6 +128,9 @@ function toSummaryResponse(
     // P2 Task 9（A27 同步时间展示）：统计副本最近回传应用时刻；null=尚无回传。
     statsSyncedAt:
       album.statsSyncedAt === null ? null : album.statsSyncedAt.toISOString(),
+    // UI-01 封面摘要：未配置封面（无 effective cover 行）为 null；签名 URL
+    // 短期有效，过期经列表/详情重取刷新。
+    cover,
   };
 }
 
@@ -126,6 +139,7 @@ export class AlbumsService {
   constructor(
     private readonly prisma: PrismaService,
     private readonly permissions: PermissionsService,
+    @Inject(STORAGE_PORT) private readonly storage: StoragePort,
   ) {}
 
   /**
@@ -647,6 +661,29 @@ export class AlbumsService {
       }
     }
 
+    // UI-01 封面摘要：本页相册一次批量查询（kind=cover、state=effective，
+    // createdAt/id DESC 后每相册首行即最新 effective 行——同 banner 替换语义，
+    // cover 无 locale 偏好）。presign 为本地计算，循环不产生网络/查询放大。
+    const covers = await this.prisma.album_assets.findMany({
+      where: {
+        albumId: { in: page.map((a) => a.id) },
+        kind: 'cover',
+        state: 'effective',
+      },
+      orderBy: [{ createdAt: 'desc' }, { id: 'desc' }],
+      select: { albumId: true, objectKey: true },
+    });
+    const coverKeyByAlbum = new Map<string, string>();
+    for (const row of covers) {
+      if (!coverKeyByAlbum.has(row.albumId)) {
+        coverKeyByAlbum.set(row.albumId, row.objectKey);
+      }
+    }
+    const coverByAlbum = new Map<string, SignedUrlResponse>();
+    for (const [albumId, objectKey] of coverKeyByAlbum) {
+      coverByAlbum.set(albumId, await this.presign(objectKey));
+    }
+
     const last = page.at(-1);
     // 契约 CursorPageMeta 不变式：hasMore=true 当且仅当 nextCursor≠null——
     // 以 nextCursor 派生 hasMore，结构上保证两者成对（防御未来调用方绕过
@@ -659,7 +696,13 @@ export class AlbumsService {
           })
         : null;
     return {
-      items: page.map((a) => toSummaryResponse(a, byAlbumId.get(a.id) ?? [])),
+      items: page.map((a) =>
+        toSummaryResponse(
+          a,
+          byAlbumId.get(a.id) ?? [],
+          coverByAlbum.get(a.id) ?? null,
+        ),
+      ),
       nextCursor,
       hasMore: nextCursor !== null,
     };
@@ -710,7 +753,7 @@ export class AlbumsService {
       }
     }
     return {
-      ...toSummaryResponse(album, translations),
+      ...toSummaryResponse(album, translations, await this.latestCoverOf(albumId)),
       categories: categories.map((c) => ({
         id: c.id,
         albumId: c.albumId,
@@ -719,4 +762,26 @@ export class AlbumsService {
       })),
     };
   }
+
+  /**
+   * 相册最新生效封面（kind=cover、state=effective，createdAt/id DESC 首行）
+   * 的短期签名 URL；未配置封面返回 null。
+   */
+  private async latestCoverOf(
+    albumId: string,
+  ): Promise<SignedUrlResponse | null> {
+    const row = await this.prisma.album_assets.findFirst({
+      where: { albumId, kind: 'cover', state: 'effective' },
+      orderBy: [{ createdAt: 'desc' }, { id: 'desc' }],
+      select: { objectKey: true },
+    });
+    return row === null ? null : this.presign(row.objectKey);
+  }
+
+  /** 现签短期 GET 凭证（TTL 惰性读取；SigV4 本地计算无网络副作用）。 */
+  private async presign(objectKey: string): Promise<SignedUrlResponse> {
+    const ttl = signedUrlTtlSeconds();
+    const url = await this.storage.presignGet(objectKey, ttl);
+    return { url, expiresAt: new Date(Date.now() + ttl * 1000).toISOString() };
+  }
 }

services/api/src/embed-ov/embed-ov.service.ts

@@ -17,6 +17,9 @@
 //      （契约评审修正：含照片条数与最新发布时间——新照片发布必变，避免仅比对
 //      实体版本时新照片小版本导致 304 陈旧）；If-None-Match 匹配 → 304 无body
 //      （判定在控制器，服务只产出 body+ETag）。空照片列：后两元取 0 与空串。
+//   UI-01：响应携带 settings（ov 副本 JSON 经 normalizeStoredSettings 归一化
+//   ——缺字段（UI-01 前旧投影行）按契约默认值补齐，嵌入端据此应用后台配置）。
+//   设置变更必递增 configVersion（cn 管理面约定），ETag 随之变化，无需改四元组。
 import { HttpStatus, Inject, Injectable } from '@nestjs/common';
 import type { components } from '@photo/contracts';
 import {
@@ -30,6 +33,7 @@ import { OvPrismaService } from '../prisma-ov/ov-prisma.module';
 import { OvRedisService } from '../redis-ov/ov-redis.module';
 import { signedUrlTtlSeconds } from '../uploads/support';
 import { STORAGE_PORT_OV } from '../public-ov/storage-ov.provider';
+import { normalizeStoredSettings } from '../embed/embed.service';
 import type { StoragePort } from '@photo/storage';
 
 export type PublicEmbedSlotResponse = components['schemas']['PublicEmbedSlot'];
@@ -152,6 +156,8 @@ export class EmbedOvService {
       body: {
         slotToken,
         configVersion: slot.configVersion,
+        // UI-01：后台展示设置归一化全集（旧投影行缺字段 → 契约默认值）。
+        settings: normalizeStoredSettings(slot.settings),
         album: {
           publicToken: album.publicToken,
           title,

services/api/src/embed/dto.ts

@@ -4,6 +4,8 @@
 //   · name 1..64（VarChar(64) 列宽）；
 //   · settings 整体提交语义：创建可整体缺省（各字段按缺省值落库，服务层
 //     归一），提供时字段齐全——嵌套 DTO 无 @IsOptional，缺字段 400；
+//     UI-01 新增字段（imageFit/offsetX/offsetBottom/zIndex）例外：全部
+//     @IsOptional（旧客户端/旧 JSON 兼容），缺省由服务层按契约默认值归一；
 //   · albumId [string,'null']：非 null 绑定/换绑（≤64，绑定存在性校验在
 //     服务层事务内），null 解绑。@IsOptional 对 undefined/null 均跳过校验
 //     且 null 值保留在 DTO 上——服务层以 `!== undefined` 区分「未提交」与
@@ -35,6 +37,15 @@ const EMBED_SLOT_SIZES = ['sm', 'md'] as const;
 export const EMBED_INTERVAL_MS_MIN = 3000;
 export const EMBED_INTERVAL_MS_MAX = 30000;
 
+/** UI-01 新增字段枚举与边界（全部可选：缺省由服务层归一化为默认值）。 */
+const EMBED_SLOT_IMAGE_FITS = ['contain', 'cover'] as const;
+export const EMBED_OFFSET_X_MIN = 0;
+export const EMBED_OFFSET_X_MAX = 120;
+export const EMBED_OFFSET_BOTTOM_MIN = 0;
+export const EMBED_OFFSET_BOTTOM_MAX = 240;
+export const EMBED_Z_INDEX_MIN = 1;
+export const EMBED_Z_INDEX_MAX = 2147483000;
+
 export class EmbedSlotSettingsDto {
   @IsIn(EMBED_SLOT_POSITIONS)
   position!: (typeof EMBED_SLOT_POSITIONS)[number];
@@ -52,6 +63,34 @@ export class EmbedSlotSettingsDto {
 
   @IsBoolean()
   collapsedDefault!: boolean;
+
+  // —— UI-01 可选扩展（旧 JSON 兼容：缺省按默认值归一化落库）——
+
+  /** 图片适配方式；缺省 contain。 */
+  @IsOptional()
+  @IsIn(EMBED_SLOT_IMAGE_FITS)
+  imageFit?: (typeof EMBED_SLOT_IMAGE_FITS)[number];
+
+  /** 距宿主边缘水平偏移（0..120px）；缺省 16。 */
+  @IsOptional()
+  @IsInt()
+  @Min(EMBED_OFFSET_X_MIN)
+  @Max(EMBED_OFFSET_X_MAX)
+  offsetX?: number;
+
+  /** 距宿主底部垂直偏移（0..240px）；缺省 24。 */
+  @IsOptional()
+  @IsInt()
+  @Min(EMBED_OFFSET_BOTTOM_MIN)
+  @Max(EMBED_OFFSET_BOTTOM_MAX)
+  offsetBottom?: number;
+
+  /** 宿主页面层级；缺省 1000。 */
+  @IsOptional()
+  @IsInt()
+  @Min(EMBED_Z_INDEX_MIN)
+  @Max(EMBED_Z_INDEX_MAX)
+  zIndex?: number;
 }
 
 export class EmbedSlotCreateRequestDto {

services/api/src/embed/embed.service.ts

@@ -52,13 +52,17 @@ export type EmbedSlotSettingsResponse =
 const PUBLIC_TOKEN_LENGTH = 24;
 const PUBLIC_TOKEN_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
 
-/** 契约 EmbedSlotSettings 各字段缺省值（整体缺省时落库形态）。 */
+/** 契约 EmbedSlotSettings 各字段缺省值（整体缺省时落库形态；UI-01 新字段同列）。 */
 export const DEFAULT_EMBED_SLOT_SETTINGS: EmbedSlotSettingsResponse = {
   position: 'right',
   size: 'md',
   intervalMs: 5000,
   lang: 'auto',
   collapsedDefault: false,
+  imageFit: 'contain',
+  offsetX: 16,
+  offsetBottom: 24,
+  zIndex: 1000,
 };
 
 /**
@@ -82,7 +86,12 @@ function generatePublicToken(): string {
   return token;
 }
 
-/** 入参 settings → 归一化存储值（null/undefined=整体缺省 → 契约缺省值）。 */
+/**
+ * 入参 settings → 归一化存储值（null/undefined=整体缺省 → 契约缺省值）。
+ * UI-01 新字段可缺省（旧客户端兼容）：缺省按契约默认值归一，落库恒为全集
+ * ——旧存储行（无新字段）的读取侧归一在 embed-ov 公开响应完成（cn 管理
+ * 响应经本服务 toResponse 不做读归一，行由本函数写入即已全集）。
+ */
 function normalizeSettings(
   settings: EmbedSlotSettingsDto | null | undefined,
 ): EmbedSlotSettingsResponse {
@@ -95,6 +104,34 @@ function normalizeSettings(
     intervalMs: settings.intervalMs,
     lang: settings.lang,
     collapsedDefault: settings.collapsedDefault,
+    imageFit: settings.imageFit ?? DEFAULT_EMBED_SLOT_SETTINGS.imageFit,
+    offsetX: settings.offsetX ?? DEFAULT_EMBED_SLOT_SETTINGS.offsetX,
+    offsetBottom:
+      settings.offsetBottom ?? DEFAULT_EMBED_SLOT_SETTINGS.offsetBottom,
+    zIndex: settings.zIndex ?? DEFAULT_EMBED_SLOT_SETTINGS.zIndex,
+  };
+}
+
+/**
+ * 存储行 settings JSON → 归一化全集（readOnly 读取侧，cn 管理响应与 ov 公开
+ * 响应共用）：UI-01 前落库的旧行无新字段，缺字段按契约默认值补齐——响应
+ * 恒为全集（契约「响应中字段恒齐全」），不要求全量改写旧记录。
+ */
+export function normalizeStoredSettings(
+  stored: Prisma.JsonValue,
+): EmbedSlotSettingsResponse {
+  const row = (stored ?? {}) as Partial<EmbedSlotSettingsResponse>;
+  return {
+    position: row.position ?? DEFAULT_EMBED_SLOT_SETTINGS.position,
+    size: row.size ?? DEFAULT_EMBED_SLOT_SETTINGS.size,
+    intervalMs: row.intervalMs ?? DEFAULT_EMBED_SLOT_SETTINGS.intervalMs,
+    lang: row.lang ?? DEFAULT_EMBED_SLOT_SETTINGS.lang,
+    collapsedDefault:
+      row.collapsedDefault ?? DEFAULT_EMBED_SLOT_SETTINGS.collapsedDefault,
+    imageFit: row.imageFit ?? DEFAULT_EMBED_SLOT_SETTINGS.imageFit,
+    offsetX: row.offsetX ?? DEFAULT_EMBED_SLOT_SETTINGS.offsetX,
+    offsetBottom: row.offsetBottom ?? DEFAULT_EMBED_SLOT_SETTINGS.offsetBottom,
+    zIndex: row.zIndex ?? DEFAULT_EMBED_SLOT_SETTINGS.zIndex,
   };
 }
 
@@ -354,7 +391,8 @@ export class EmbedSlotsService {
       albumId: slot.albumId,
       albumTitle,
       configVersion: slot.configVersion,
-      settings: slot.settings as EmbedSlotSettingsResponse,
+      // 读取侧归一化：UI-01 前旧行缺新字段 → 契约默认值补齐（响应恒全集）。
+      settings: normalizeStoredSettings(slot.settings),
       updatedAt: slot.updatedAt.toISOString(),
     };
   }

services/api/src/photos/album-photos.controller.ts

@@ -22,7 +22,11 @@ import {
 import { userOf } from '../albums/albums.controller';
 import { AuthenticatedRequest, SessionGuard } from '../auth/session.guard';
 import { parseCursor, parseLimit } from '../shared/pagination';
-import { PhotoHideBatchDto, parseVisibilityFilter } from './dto';
+import {
+  PhotoHideBatchDto,
+  parseScopeFilter,
+  parseVisibilityFilter,
+} from './dto';
 import {
   PhotosService,
   type AdminPhotoListResponse,
@@ -37,12 +41,15 @@ export class AlbumPhotosController {
   /**
    * 管理照片列表：全部可见性状态可见（区别于公开列表仅 published），
    * (uploadedAt,id) 稳定倒序键集游标；条目内嵌 uploader 脱敏信息。
+   * scope=own（UI-01）：协作者显式查询自己上传（服务端过滤）；缺省 all
+   * 行为不变（仅 owner/admin）。
    */
   @Get()
   listAlbumPhotos(
     @Param('albumId') albumId: string,
     @Query('visibility') visibility: string | undefined,
     @Query('categoryId') categoryId: string | undefined,
+    @Query('scope') scope: string | undefined,
     @Query('cursor') cursor: string | undefined,
     @Query('limit') limit: string | undefined,
     @Req() req: AuthenticatedRequest,
@@ -51,6 +58,7 @@ export class AlbumPhotosController {
       visibility: parseVisibilityFilter(visibility),
       // 空串视为缺省（同公开列表 category 规整惯例）。
       categoryId: categoryId === '' ? undefined : categoryId,
+      scope: parseScopeFilter(scope),
       cursor: parseCursor(cursor),
       limit: parseLimit(limit),
     });

services/api/src/photos/dto.ts

@@ -1,6 +1,6 @@
 // services/api/src/photos/dto.ts —— 照片域入参规整（Task 24 起步：PATCH body；
 // P1b Task 4 增补：管理列表 visibility 查询参数；P4a Task 2 增补：批量隐藏
-// 请求体）。校验约束对齐契约：
+// 请求体；UI-01 增补：管理列表 scope 查询参数 all|own）。校验约束对齐契约：
 // PhotoVisibilityUpdateRequest.visibility 仅允许 hidden/published（enum 之外
 // 任何值 → 400 VALIDATION_FAILED）；deleted 只能经 DELETE 进入，不开放 PATCH
 // 直达（单向终态，见 photos.service 状态机）。
@@ -67,3 +67,28 @@ export function parseVisibilityFilter(
   }
   return raw as PhotoVisibility;
 }
+
+/** 契约 listAlbumPhotos scope 参数取值（UI-01：all=缺省既有行为；own=仅自己上传）。 */
+export const ALBUM_PHOTO_SCOPES = ['all', 'own'] as const;
+export type AlbumPhotoScope = (typeof ALBUM_PHOTO_SCOPES)[number];
+
+/**
+ * 管理列表 scope 查询参数（UI-01）：空串视为缺省（同 visibility 规整惯例，
+ * ?scope= 等同未提交= all）；非空须为 all|own，否则 400 VALIDATION_FAILED。
+ * 权限差异（collab 仅 own、all 仅 owner/admin）在服务层裁决。
+ */
+export function parseScopeFilter(
+  raw: string | undefined,
+): AlbumPhotoScope | undefined {
+  if (raw === undefined || raw === '') {
+    return undefined;
+  }
+  if (!(ALBUM_PHOTO_SCOPES as readonly string[]).includes(raw)) {
+    throw new ApiException(
+      ErrorCodes.VALIDATION_FAILED,
+      'scope 取值非法',
+      HttpStatus.BAD_REQUEST,
+    );
+  }
+  return raw as AlbumPhotoScope;
+}

services/api/src/photos/photos.module.ts

@@ -1,9 +1,12 @@
 // services/api/src/photos/photos.module.ts —— 照片管理模块（Task 24；P1b Task 4
-// 增补管理列表控制器）。装配：PhotosController/AlbumPhotosController/
-// PhotosService + PermissionsService（经 AlbumsModule 导入复用 A02 逐次权限
-// 判定；同 uploads 模块的装配先例）。
+// 增补管理列表控制器；UI-01 增补 StoragePort——管理列表 preview 现签）。
+// 装配：PhotosController/AlbumPhotosController/PhotosService +
+// PermissionsService（经 AlbumsModule 导入复用 A02 逐次权限判定；同 uploads
+// 模块的装配先例）+ storageProvider（与 AlbumsModule 同一 DI 模式：直接复用
+// provider 工厂而非 import UploadsModule，避免模块环）。
 import { Module } from '@nestjs/common';
 import { AlbumsModule } from '../albums/albums.module';
+import { storageProvider } from '../uploads/storage.provider';
 import { AlbumPhotosController } from './album-photos.controller';
 import { PhotosController } from './photos.controller';
 import { PhotosService } from './photos.service';
@@ -11,6 +14,6 @@ import { PhotosService } from './photos.service';
 @Module({
   imports: [AlbumsModule],
   controllers: [PhotosController, AlbumPhotosController],
-  providers: [PhotosService],
+  providers: [PhotosService, storageProvider],
 })
 export class PhotosModule {}

services/api/src/photos/photos.service.ts

@@ -15,6 +15,11 @@
 // 权限（§2 矩阵，A02 逐次校验）：canManagePhoto = admin 全部 / 相册 owner 全部 /
 // 协作者仅自己上传。404/403 映射：照片不存在或相册不可见（非成员）→ 404
 // PHOTO_NOT_FOUND（防枚举）；可见但无管理权（协作者对他人照片）→ 403。
+// UI-01 增补：listAlbumPhotos scope=own（协作者显式查询自己上传，服务端过滤
+// uploaderId，成员资格逐请求检查——沿用 canViewAlbum 逐次直查口径）+ 条目
+// preview（受权限管理的 thumb/browse 短期签名 URL；变体按页一次批量查询，
+// 逐张裁决：无 thumb/browse 变体、已删除 → null；隐藏 → 仅 admin/owner；
+// 无权签发不改变 PhotoRecord 本身——记录可见性与图片可见性分离）。
 // 每次真实状态迁移：条件更新（WHERE visibility=期望前态，并发下恰一人胜出）
 // + entityVersion 自增 + 事务内 outbox 事件（P2 副本按 entityVersion 单调消费）
 // + audit。幂等前态（同值 PATCH / 重复 DELETE）直接回显当前记录，不产生
@@ -22,10 +27,11 @@
 // P4a Task 5 检查点：可见性真实迁移（transition/hideBatch）提交后评估用量
 // 阈值告警（deleted 不计用量——软删除可能解除告警；hidden 仍计）。评估在
 // 自开事务执行且失败只记日志，绝不影响可见性操作本身（见 evaluateUsageSafe）。
-import { Injectable, Logger } from '@nestjs/common';
+import { Inject, Injectable, Logger } from '@nestjs/common';
 import { ErrorCodes, type components } from '@photo/contracts';
 import { evaluateUsageSafe } from '@photo/db-cn';
 import type { Prisma } from '@photo/db-cn';
+import type { StoragePort } from '@photo/storage';
 import type { AuthUser } from '../auth/session.guard';
 import { PermissionsService } from '../albums/permissions.service';
 import {
@@ -40,7 +46,13 @@ import {
   keysetWhereDesc,
 } from '../shared/cursor';
 import { buildPhotoPublishedPayload } from '../sync/payloads';
-import type { PhotoVisibility, PhotoVisibilityTarget } from './dto';
+import { STORAGE_PORT } from '../uploads/storage.provider';
+import { signedUrlTtlSeconds } from '../uploads/support';
+import type {
+  AlbumPhotoScope,
+  PhotoVisibility,
+  PhotoVisibilityTarget,
+} from './dto';
 import {
   photoForbidden,
   photoNotFound,
@@ -51,6 +63,8 @@ export type PhotoRecord = components['schemas']['PhotoRecord'];
 export type AdminPhotoListResponse = components['schemas']['AdminPhotoList'];
 export type BatchHideResult = components['schemas']['BatchHideResult'];
 export type BatchHideItem = components['schemas']['BatchHideItem'];
+export type PhotoPreviewResponse = components['schemas']['PhotoPreview'];
+type SignedUrlResponse = components['schemas']['SignedUrl'];
 
 type PhotoRow = Prisma.photosGetPayload<Prisma.photosDefaultArgs>;
 
@@ -81,6 +95,7 @@ export class PhotosService {
   constructor(
     private readonly prisma: PrismaService,
     private readonly permissions: PermissionsService,
+    @Inject(STORAGE_PORT) private readonly storage: StoragePort,
   ) {}
 
   /**
@@ -91,6 +106,12 @@ export class PhotosService {
    * （协作者）→ 403 AUTH_FORBIDDEN；admin 对幽灵 id 权限恒真，空相册兜底 404。
    * 排序 (uploadedAt,id) DESC 键集游标（shared/cursor）。
    *
+   * scope（UI-01）：缺省/'all'=上述既有行为（仅 owner/admin，协作者 403 不
+   * 变）；'own'=显式查询自己上传——任何有效成员可用（canViewAlbum 逐请求
+   * 直查成员行：被移除后下一次请求即刻 404），服务端追加 uploaderId 过滤；
+   * admin/owner 同样可用 own（过滤为自己上传的历史）。preview（UI-01）逐张
+   * 裁决见 previewOf。
+   *
    * 未完成上传（pending_upload、uploadedAt NULL）不入列表：uploadedAt 既是契约
    * 必返字段又是键集排序键——NULL 行既无法以契约形状返回（toPhotoRecord 的
    * new Date(0) 兜底会伪造 1970 时间轴），也无法参与键集谓词（SQL 对 NULL 的
@@ -102,14 +123,19 @@ export class PhotosService {
     query: {
       visibility?: PhotoVisibility;
       categoryId?: string;
+      scope?: AlbumPhotoScope;
       cursor?: string;
       limit: number;
     },
   ): Promise<AdminPhotoListResponse> {
+    const scope: AlbumPhotoScope = query.scope ?? 'all';
     if (!(await this.permissions.canViewAlbum(user, albumId))) {
       throw albumNotFound();
     }
-    if (!(await this.permissions.canManageAlbum(user, albumId))) {
+    // manager=admin/owner：全量可见 + 隐藏照片可签发预览。scope=all（缺省）
+    // 仅 manager（协作者 403，既有行为不变）；scope=own 任何有效成员可用。
+    const manager = await this.permissions.canManageAlbum(user, albumId);
+    if (scope === 'all' && !manager) {
       throw albumForbidden('仅创建者或管理员可访问管理列表');
     }
     // admin 对不存在 id 的 canView/canManage 恒真（非 admin 的可见成员行本身
@@ -151,6 +177,9 @@ export class PhotosService {
       ...(query.categoryId !== undefined
         ? { categoryId: query.categoryId }
         : {}),
+      // scope=own：服务端过滤（客户端传 uploaderId 不可信），与 canViewAlbum
+      // 同请求内裁决——权限撤销后下一次请求即刻失效。
+      ...(scope === 'own' ? { uploaderId: user.id } : {}),
     };
     if (decoded !== null) {
       Object.assign(where, keysetWhereDesc('uploadedAt', 'id', decoded));
@@ -173,23 +202,51 @@ export class PhotosService {
           });
     const userById = new Map(users.map((u) => [u.id, u]));
 
-    const items = page.flatMap((row) => {
+    // UI-01 preview：本页变体一次批量查询（photoId IN 页内 id 集，杜绝逐张
+    // N+1）；裁决在 previewOf（presign 为 SigV4 本地计算，无网络/查询放大）。
+    const variantRows =
+      page.length === 0
+        ? []
+        : await this.prisma.photo_variants.findMany({
+            where: { photoId: { in: page.map((p) => p.id) } },
+            select: { photoId: true, variant: true, objectKey: true },
+          });
+    const variantKeysByPhoto = new Map<
+      string,
+      { thumb?: string; browse?: string }
+    >();
+    for (const row of variantRows) {
+      const bucket = variantKeysByPhoto.get(row.photoId) ?? {};
+      if (row.variant === 'thumb') {
+        bucket.thumb = row.objectKey;
+      } else if (row.variant === 'browse') {
+        bucket.browse = row.objectKey;
+      }
+      variantKeysByPhoto.set(row.photoId, bucket);
+    }
+
+    const items: AdminPhotoListResponse['items'] = [];
+    for (const row of page) {
       const uploader = userById.get(row.uploaderId);
       // 用户行缺失（P1a 无用户删除，仅可能来自手工改库）：跳过而非 5xx（同
       // 成员列表先例，单条脏数据不拖垮整页）。
-      return uploader === undefined
-        ? []
-        : [
-            {
-              ...toPhotoRecord(row),
-              uploader: {
-                userId: uploader.id,
-                account: uploader.account,
-                displayName: uploader.displayName,
-              },
-            },
-          ];
-    });
+      if (uploader === undefined) {
+        continue;
+      }
+      items.push({
+        ...toPhotoRecord(row),
+        uploader: {
+          userId: uploader.id,
+          account: uploader.account,
+          displayName: uploader.displayName,
+        },
+        preview: await this.previewOf(
+          row,
+          variantKeysByPhoto.get(row.id),
+          manager,
+        ),
+      });
+    }
 
     const last = page.at(-1);
     const nextCursor =
@@ -203,6 +260,40 @@ export class PhotosService {
     return { items, nextCursor, hasMore: nextCursor !== null };
   }
 
+  /**
+   * UI-01 受权限管理的预览裁决：thumb 与 browse 变体齐备且未删除才签发；
+   * 隐藏照片仅 manager（admin/owner）签发——协作者即便自己上传（scope=own
+   * 可见记录）也不获得隐藏图 URL（「隐藏是运营动作」，与恢复发布同一权限
+   * 口径）。无变体（处理未完成/失败）与已删除返回 null，PhotoRecord 本身
+   * 不受影响（记录可见性与图片可见性分离）。签名短期有效，过期经列表重取。
+   */
+  private async previewOf(
+    row: PhotoRow,
+    keys: { thumb?: string; browse?: string } | undefined,
+    manager: boolean,
+  ): Promise<PhotoPreviewResponse | null> {
+    if (keys?.thumb === undefined || keys?.browse === undefined) {
+      return null;
+    }
+    if (row.visibility === 'deleted') {
+      return null;
+    }
+    if (row.visibility === 'hidden' && !manager) {
+      return null;
+    }
+    return {
+      thumb: await this.presign(keys.thumb),
+      browse: await this.presign(keys.browse),
+    };
+  }
+
+  /** 现签短期 GET 凭证（TTL 惰性读取；SigV4 本地计算无网络副作用）。 */
+  private async presign(objectKey: string): Promise<SignedUrlResponse> {
+    const ttl = signedUrlTtlSeconds();
+    const url = await this.storage.presignGet(objectKey, ttl);
+    return { url, expiresAt: new Date(Date.now() + ttl * 1000).toISOString() };
+  }
+
   /**
    * 批量隐藏（契约 hidePhotosBatch，P4a A16）：逐项处理、部分成功——单项失败
    * （不存在/已删除/状态不可切换）只标记该项 ok=false + code，不影响其余项。

services/api/test/albums.e2e-spec.ts

@@ -25,8 +25,9 @@ import { hashSessionToken } from '../src/auth/session.guard';
 import { API_PREFIX } from '../src/shared/constants';
 import { resetDb } from './reset';
 
-/** 契约 AlbumSummary 的必返字段全集（列表条目形状精确断言用）。 */
+/** 契约 AlbumSummary 的必返字段全集（列表条目形状精确断言用；UI-01 增 cover）。 */
 const ALBUM_SUMMARY_KEYS = [
+  'cover',
   'createdAt',
   'defaultLocale',
   'downloadEnabled',

services/api/test/embed.e2e-spec.ts

@@ -22,6 +22,8 @@
 //      版本直投生效（乱序收敛）；
 //   ⑧ 限速：压小窗口（EMBED_WINDOW_REQUESTS 惰性 env）→ 超额 429
 //      RATE_LIMITED（304 也消耗预算）。
+//   ⑨ UI-01 配置字段全链路：新字段创建/校验（越界/非法 400）/旧形状归一化
+//      → slot-state 投影 → ov 公开 settings 全集；旧投影行读取侧默认值归一。
 // 真实 MySQL×2 + MinIO（真实 JPEG 上传发布）+ HMAC 同步链路字节一致。
 import { randomBytes } from 'node:crypto';
 import { NestFactory } from '@nestjs/core';
@@ -281,12 +283,17 @@ describe('embed slots (e2e)', () => {
         },
       });
     expect(second.status).toBe(201);
+    // UI-01：旧形状提交（无新字段）→ 响应为归一化全集（新字段按默认值）。
     expect(second.body.settings).toEqual({
       position: 'left',
       size: 'sm',
       intervalMs: 8000,
       lang: 'zh-CN',
       collapsedDefault: true,
+      imageFit: 'contain',
+      offsetX: 16,
+      offsetBottom: 24,
+      zIndex: 1000,
     });
 
     // 校验失败：settings 缺字段 / intervalMs 越界 / 空 name。
@@ -748,6 +755,164 @@ describe('embed slots (e2e)', () => {
       }
     }
   });
+
+  it('⑨ UI-01 配置字段：cn 校验/归一化 → slot-state 投影 → ov 公开 settings', async () => {
+    // 清限速计数（⑧ 压窗残留不影响本用例；默认窗口 120/60s 内用不顶）。
+    const keys = await redisOv.keys('embed:window:*');
+    if (keys.length > 0) {
+      await redisOv.del(keys);
+    }
+
+    // 创建即带全量新字段 → cn 响应回显（admin 全集形状）。
+    const created = await request(cnBase)
+      .post('/v1/admin/embed-slots')
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({
+        name: 'UI01 配置位',
+        settings: {
+          position: 'left',
+          size: 'md',
+          intervalMs: 6000,
+          lang: 'auto',
+          collapsedDefault: true,
+          imageFit: 'cover',
+          offsetX: 40,
+          offsetBottom: 80,
+          zIndex: 5000,
+        },
+      });
+    expect(created.status).toBe(201);
+    const ui01SlotId = created.body.id as string;
+    const ui01Token = created.body.publicToken as string;
+    expect(created.body.settings).toEqual({
+      position: 'left',
+      size: 'md',
+      intervalMs: 6000,
+      lang: 'auto',
+      collapsedDefault: true,
+      imageFit: 'cover',
+      offsetX: 40,
+      offsetBottom: 80,
+      zIndex: 5000,
+    });
+
+    // 新字段校验：非法枚举/越界/非整数 → 400（老字段约束不回归）。
+    const validBase = {
+      position: 'left',
+      size: 'md',
+      intervalMs: 6000,
+      lang: 'auto',
+      collapsedDefault: true,
+      imageFit: 'cover',
+      offsetX: 40,
+      offsetBottom: 80,
+      zIndex: 5000,
+    } as Record<string, unknown>;
+    for (const bad of [
+      { imageFit: 'fill' },
+      { offsetX: 121 },
+      { offsetX: -1 },
+      { offsetX: 1.5 },
+      { offsetBottom: 241 },
+      { zIndex: 0 },
+      { zIndex: 2147483001 },
+    ]) {
+      const res = await request(cnBase)
+        .patch(`/v1/admin/embed-slots/${ui01SlotId}`)
+        .set('Authorization', `Bearer ${adminToken}`)
+        .send({ settings: { ...validBase, ...bad } });
+      expect(res.status).toBe(400);
+      expect(res.body.code).toBe(ErrorCodes.VALIDATION_FAILED);
+    }
+
+    // 旧形状整体替换（无新字段）→ 归一化落库（新字段回默认值）+ configVersion+1。
+    const legacyShape = {
+      position: 'left',
+      size: 'sm',
+      intervalMs: 6000,
+      lang: 'auto',
+      collapsedDefault: false,
+    };
+    const patched = await request(cnBase)
+      .patch(`/v1/admin/embed-slots/${ui01SlotId}`)
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({ settings: legacyShape });
+    expect(patched.status).toBe(200);
+    expect(patched.body.configVersion).toBe(2);
+    const normalizedFull = {
+      ...legacyShape,
+      imageFit: 'contain',
+      offsetX: 16,
+      offsetBottom: 24,
+      zIndex: 1000,
+    };
+    expect(patched.body.settings).toEqual(normalizedFull);
+
+    // 新字段显式 PATCH → 回显显式值。
+    const explicit = await request(cnBase)
+      .patch(`/v1/admin/embed-slots/${ui01SlotId}`)
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({
+        settings: {
+          ...legacyShape,
+          imageFit: 'cover',
+          offsetX: 8,
+          offsetBottom: 120,
+          zIndex: 999,
+        },
+      });
+    expect(explicit.status).toBe(200);
+    const explicitFull = {
+      ...legacyShape,
+      imageFit: 'cover',
+      offsetX: 8,
+      offsetBottom: 120,
+      zIndex: 999,
+    };
+    expect(explicit.body.settings).toEqual(explicitFull);
+
+    // 绑定相册 A → 排空发送器 → ov 公开响应 settings = 投影完整全集。
+    const bound = await request(cnBase)
+      .patch(`/v1/admin/embed-slots/${ui01SlotId}`)
+      .set('Authorization', `Bearer ${adminToken}`)
+      .send({ albumId: albumAId });
+    expect(bound.status).toBe(200);
+    await drainSender();
+    const feed = await getEmbed(ui01Token);
+    expect(feed.status).toBe(200);
+    expect(feed.body.settings).toEqual(explicitFull);
+    // 既有字段不回归：album/photos 照常返回。
+    expect(feed.body.album.publicToken).toBe(albumAToken);
+    expect(feed.body.photos.length).toBeGreaterThan(0);
+
+    // 旧形状存量投影行（UI-01 前 ov 副本）：直改副本 settings 模拟旧投影 →
+    // 公开响应按契约默认值归一（读取侧归一化，无需回填事件）。
+    await prismaOv.embed_slots_ov.update({
+      where: { slotToken: ui01Token },
+      data: {
+        settings: {
+          position: 'right',
+          size: 'md',
+          intervalMs: 5000,
+          lang: 'auto',
+          collapsedDefault: false,
+        },
+      },
+    });
+    const staleFeed = await getEmbed(ui01Token);
+    expect(staleFeed.status).toBe(200);
+    expect(staleFeed.body.settings).toEqual({
+      position: 'right',
+      size: 'md',
+      intervalMs: 5000,
+      lang: 'auto',
+      collapsedDefault: false,
+      imageFit: 'contain',
+      offsetX: 16,
+      offsetBottom: 24,
+      zIndex: 1000,
+    });
+  });
 });
 
 /** ETag 第二元：副本最新已发布照片的 publishedAt 毫秒（缺行 0）。 */

services/api/test/photos-admin.e2e-spec.ts

@@ -38,7 +38,8 @@ function makePublicToken(): string {
   return token;
 }
 
-/** 契约 PhotoRecord 必返字段 + 管理列表内嵌 uploader（形状精确断言用）。 */
+/** 契约 PhotoRecord 必返字段 + 管理列表内嵌 uploader（形状精确断言用；
+ * UI-01 增 preview——服务恒发（无权/无变体为 null），键恒在）。 */
 const ADMIN_PHOTO_KEYS = [
   'albumId',
   'bytes',
@@ -46,6 +47,7 @@ const ADMIN_PHOTO_KEYS = [
   'height',
   'likeCount',
   'photoId',
+  'preview',
   'processingState',
   'publishedAt',
   'shotAt',

services/api/test/ui01-contracts.e2e-spec.ts

@@ -0,0 +1,627 @@
+// services/api/test/ui01-contracts.e2e-spec.ts —— UI-01 Task 2 契约扩展 e2e：
+// cover 封面摘要 / preview 受权限预览 / scope=own 数据范围（真实 app + MySQL +
+// MinIO：签名 URL 实取回字节，N+1 用 Prisma 中间件计真实查询数）。覆盖：
+//   ① listAlbums cover：有封面 → url 短期签名且可取回真实字节；同 kind 多行
+//      取最新 effective（createdAt/id DESC 首行）；pending 行不计；无封面 →
+//      null；getAlbum 详情同形；批量组装无 N+1（6 相册单页，相册域 Prisma 查
+//      询数恒定：admin=3 albums+translations+album_assets / 非 admin=4 另加成
+//      员行查询，与封面相册数无关）；
+//   ② preview 权限矩阵（scope=all，owner/admin）：published 签发（thumb+browse
+//      可取回字节）；hidden 对 manager 签发；deleted / 无变体 → null（记录
+//      本身仍如实返回）；
+//   ③ scope=own：collab 仅见自己上传（服务端过滤，uploaderId 全等于本人）；
+//      自己的 hidden 行可见但 preview=null（隐藏签发仅 admin/owner）；owner
+//      scope=own 过滤为自己上传；旧请求（无 scope）owner 全量行为不变；
+//   ④ 权限边界：collab scope=all（缺省与显式）→ 403；被移除成员 scope=own →
+//      404（成员资格逐请求）；非成员跨相册 → 404；scope 非法值 → 400。
+import { randomBytes } from 'node:crypto';
+import { type INestApplication } from '@nestjs/common';
+import { Test } from '@nestjs/testing';
+import request from 'supertest';
+import {
+  PutObjectCommand,
+  S3Client,
+} from '@aws-sdk/client-s3';
+import { PrismaClient } from '@photo/db-cn';
+import { ErrorCodes } from '@photo/contracts';
+import { AppCnModule } from '../src/app-cn.module';
+import { hashSessionToken } from '../src/auth/session.guard';
+import { PrismaService } from '../src/prisma/prisma.service';
+import { API_PREFIX } from '../src/shared/constants';
+import { resetDb } from './reset';
+
+jest.setTimeout(120_000);
+
+/** 契约 pattern ^[0-9a-z]{20,32}$（同 albums.service 生成式口径）。 */
+function makePublicToken(): string {
+  const alphabet = '0123456789abcdefghijklmnopqrstuvwxyz';
+  const bytes = randomBytes(24);
+  let token = '';
+  for (let i = 0; i < 24; i++) {
+    token += alphabet[bytes[i] % alphabet.length];
+  }
+  return token;
+}
+
+/** 固定时间基（分钟偏移构造确定性 uploadedAt/createdAt 序列）。 */
+const T0 = Date.UTC(2026, 8, 20, 8, 0, 0);
+const atMinute = (m: number): Date => new Date(T0 + m * 60_000);
+
+describe('UI-01 契约扩展：cover / preview / scope=own (e2e)', () => {
+  let app: INestApplication;
+  let prisma: PrismaClient;
+  let s3: S3Client;
+
+  let ownerId: string;
+  let collabId: string;
+  let adminId: string;
+  let outsiderId: string;
+  let ownerToken: string;
+  let collabToken: string;
+  let adminToken: string;
+  let outsiderToken: string;
+
+  /** 主相册 A（owner + collab）：封面 + 全状态照片矩阵。 */
+  let albumAId: string;
+  /** 相册 B（owner 独有，无封面无照片）：无封面对照 + 跨册 404。 */
+  let albumBId: string;
+  /** 其余 4 个带封面相册（N+1 批量断言用，owner 名下）。 */
+  const fillerIds: string[] = [];
+
+  let coverOldAssetId: string;
+  let coverNewAssetId: string;
+  const coverOldBytes = Buffer.from([0x11, 0x12, 0x13, 0x14]);
+  const coverNewBytes = Buffer.from([0x21, 0x22, 0x23, 0x24, 0x25]);
+
+  let phPubC: string; // published / collab / 有变体
+  let phPubO: string; // published / owner / 有变体（字节取回断言用）
+  let phHidC: string; // hidden / collab / 有变体
+  let phHidO: string; // hidden / owner / 有变体
+  let phDelO: string; // deleted / owner / 有变体
+  let phNovarC: string; // unpublished / collab / 无变体
+
+  const pubOBrowseBytes = Buffer.from([0x31, 0x32, 0x33, 0x34, 0x35, 0x36]);
+
+  /** MinIO 实写对象（封面/预览可取回性）。 */
+  async function putObject(key: string, body: Buffer): Promise<void> {
+    await s3.send(
+      new PutObjectCommand({
+        Bucket: process.env.S3_BUCKET,
+        Key: key,
+        Body: body,
+        ContentType: 'image/jpeg',
+      }),
+    );
+  }
+
+  async function fetchBody(url: string): Promise<Buffer> {
+    const res = await fetch(url);
+    expect(res.status).toBe(200);
+    return Buffer.from(await res.arrayBuffer());
+  }
+
+  function listAlbums(token: string, query?: Record<string, string | number>) {
+    return request(app.getHttpServer())
+      .get(`/${API_PREFIX}/albums`)
+      .set('Authorization', `Bearer ${token}`)
+      .query(query ?? {});
+  }
+
+  function listPhotos(
+    token: string,
+    albumId: string,
+    query?: Record<string, string | number>,
+  ) {
+    return request(app.getHttpServer())
+      .get(`/${API_PREFIX}/albums/${albumId}/photos`)
+      .set('Authorization', `Bearer ${token}`)
+      .query(query ?? {});
+  }
+
+  beforeAll(async () => {
+    await resetDb();
+    const moduleRef = await Test.createTestingModule({
+      imports: [AppCnModule],
+    }).compile();
+    app = moduleRef.createNestApplication();
+    app.setGlobalPrefix(API_PREFIX);
+    await app.init();
+
+    prisma = new PrismaClient();
+    s3 = new S3Client({
+      endpoint: process.env.S3_ENDPOINT,
+      region: process.env.S3_REGION,
+      credentials: {
+        accessKeyId: process.env.S3_ACCESS_KEY as string,
+        secretAccessKey: process.env.S3_SECRET_KEY as string,
+      },
+      forcePathStyle: true,
+    });
+
+    const mkUser = (account: string, displayName: string, role = 'staff') =>
+      prisma.users.create({
+        data: { account, role, passwordHash: 'x', displayName },
+        select: { id: true },
+      });
+    ownerId = (await mkUser('u01-owner', '欧阳雯')).id;
+    collabId = (await mkUser('u01-collab', '程澜')).id;
+    adminId = (await mkUser('u01-admin', '艾管', 'admin')).id;
+    outsiderId = (await mkUser('u01-outsider', '韦外')).id;
+
+    const mkToken = async (userId: string): Promise<string> => {
+      const token = randomBytes(32).toString('hex');
+      await prisma.sessions.create({
+        data: {
+          userId,
+          tokenHash: hashSessionToken(token),
+          expiresAt: new Date(Date.now() + 3_600_000),
+        },
+      });
+      return token;
+    };
+    ownerToken = await mkToken(ownerId);
+    collabToken = await mkToken(collabId);
+    adminToken = await mkToken(adminId);
+    outsiderToken = await mkToken(outsiderId);
+
+    // 相册 A：owner + collab；zh-CN 翻译。
+    const albumA = await prisma.albums.create({
+      data: {
+        publicToken: makePublicToken(),
+        ownerId,
+        startAt: new Date(),
+        defaultLocale: 'zh-CN',
+      },
+      select: { id: true },
+    });
+    albumAId = albumA.id;
+    await prisma.album_translations.create({
+      data: { albumId: albumAId, locale: 'zh-CN', title: 'UI01 契约相册' },
+    });
+    await prisma.album_members.createMany({
+      data: [
+        { albumId: albumAId, userId: ownerId, role: 'owner', status: 'active' },
+        {
+          albumId: albumAId,
+          userId: collabId,
+          role: 'collaborator',
+          status: 'active',
+        },
+      ],
+    });
+
+    // 相册 B：owner 独有（无 collab）——无封面对照 + 跨册 404。
+    const albumB = await prisma.albums.create({
+      data: {
+        publicToken: makePublicToken(),
+        ownerId,
+        startAt: new Date(),
+        defaultLocale: 'zh-CN',
+      },
+      select: { id: true },
+    });
+    albumBId = albumB.id;
+    await prisma.album_translations.create({
+      data: { albumId: albumBId, locale: 'zh-CN', title: 'UI01 无封面相册' },
+    });
+    await prisma.album_members.create({
+      data: { albumId: albumBId, userId: ownerId, role: 'owner', status: 'active' },
+    });
+
+    // 4 个补充相册（带封面）：N+1 批量断言（单页 6 相册，5 有封面）。
+    for (let i = 0; i < 4; i++) {
+      const filler = await prisma.albums.create({
+        data: {
+          publicToken: makePublicToken(),
+          ownerId,
+          startAt: new Date(),
+          defaultLocale: 'zh-CN',
+        },
+        select: { id: true },
+      });
+      fillerIds.push(filler.id);
+      await prisma.album_translations.create({
+        data: { albumId: filler.id, locale: 'zh-CN', title: `UI01 补充 ${i}` },
+      });
+      await prisma.album_members.create({
+        data: {
+          albumId: filler.id,
+          userId: ownerId,
+          role: 'owner',
+          status: 'active',
+        },
+      });
+      const assetId = `u01assetfill${i}0000000000000`;
+      const key = `photo-live/dev/albums/${filler.id}/assets/${assetId}.jpg`;
+      await prisma.album_assets.create({
+        data: {
+          id: assetId,
+          albumId: filler.id,
+          kind: 'cover',
+          locale: null,
+          objectKey: key,
+          state: 'effective',
+          expectedBytes: 4,
+          contentType: 'image/jpeg',
+        },
+      });
+      await putObject(key, Buffer.from([0x41, 0x42, 0x43]));
+    }
+
+    // 相册 A 封面矩阵：pending 行（不计）→ 旧 effective 行 → 新 effective 行
+    //（最新生效胜出）。
+    coverOldAssetId = 'u01assetold00000000000000000';
+    coverNewAssetId = 'u01assetnew00000000000000000';
+    const coverOldKey = `photo-live/dev/albums/${albumAId}/assets/${coverOldAssetId}.jpg`;
+    const coverNewKey = `photo-live/dev/albums/${albumAId}/assets/${coverNewAssetId}.jpg`;
+    await prisma.album_assets.createMany({
+      data: [
+        {
+          id: 'u01assetpending0000000000000',
+          albumId: albumAId,
+          kind: 'cover',
+          locale: null,
+          objectKey: `photo-live/dev/albums/${albumAId}/assets/u01assetpending0000000000000.jpg`,
+          state: 'pending',
+          expectedBytes: 4,
+          contentType: 'image/jpeg',
+          createdAt: atMinute(50), // 最新但 pending → 不计
+        },
+        {
+          id: coverOldAssetId,
+          albumId: albumAId,
+          kind: 'cover',
+          locale: null,
+          objectKey: coverOldKey,
+          state: 'effective',
+          expectedBytes: 4,
+          contentType: 'image/jpeg',
+          createdAt: atMinute(10),
+        },
+        {
+          id: coverNewAssetId,
+          albumId: albumAId,
+          kind: 'cover',
+          locale: null,
+          objectKey: coverNewKey,
+          state: 'effective',
+          expectedBytes: 5,
+          contentType: 'image/jpeg',
+          createdAt: atMinute(20), // 最新 effective → 胜出
+        },
+        {
+          id: 'u01assetbanner000000000000',
+          albumId: albumAId,
+          kind: 'banner', // 非 cover kind → 不计
+          locale: null,
+          objectKey: `photo-live/dev/albums/${albumAId}/assets/u01assetbanner000000000000.jpg`,
+          state: 'effective',
+          expectedBytes: 4,
+          contentType: 'image/jpeg',
+          createdAt: atMinute(30),
+        },
+      ],
+    });
+    await putObject(coverOldKey, coverOldBytes);
+    await putObject(coverNewKey, coverNewBytes);
+
+    // 照片矩阵（album A；uploadedAt 递减稳定序）。
+    const seedPhoto = async (spec: {
+      id: string;
+      uploaderId: string;
+      visibility: string;
+      processingState: string;
+      uploadedAt: Date;
+      withVariants: boolean;
+    }): Promise<void> => {
+      await prisma.photos.create({
+        data: {
+          id: spec.id,
+          albumId: albumAId,
+          uploaderId: spec.uploaderId,
+          objectKey: `photo-live/dev/albums/${albumAId}/originals/${spec.id}.jpg`,
+          bytes: 9999,
+          width: 1600,
+          height: 1000,
+          uploadedAt: spec.uploadedAt,
+          publishedAt:
+            spec.visibility === 'unpublished' ? null : new Date(spec.uploadedAt),
+          processingState: spec.processingState,
+          visibility: spec.visibility,
+          entityVersion: 2,
+        },
+      });
+      if (!spec.withVariants) {
+        return;
+      }
+      await prisma.photo_variants.createMany({
+        data: (['thumb', 'browse'] as const).map((variant, i) => ({
+          photoId: spec.id,
+          variant,
+          objectKey: `photo-live/dev/albums/${albumAId}/variants/${spec.id}/1/${variant}.jpg`,
+          bytes: 100 + i,
+          version: 1,
+          width: variant === 'thumb' ? 320 : 1600,
+          height: variant === 'thumb' ? 200 : 1000,
+        })),
+      });
+    };
+
+    phPubC = 'u01-photo-pub-c';
+    phPubO = 'u01-photo-pub-o';
+    phHidC = 'u01-photo-hid-c';
+    phHidO = 'u01-photo-hid-o';
+    phDelO = 'u01-photo-del-o';
+    phNovarC = 'u01-photo-novar-c';
+    await seedPhoto({
+      id: phPubC,
+      uploaderId: collabId,
+      visibility: 'published',
+      processingState: 'ready',
+      uploadedAt: atMinute(60),
+      withVariants: true,
+    });
+    await seedPhoto({
+      id: phPubO,
+      uploaderId: ownerId,
+      visibility: 'published',
+      processingState: 'ready',
+      uploadedAt: atMinute(50),
+      withVariants: true,
+    });
+    await seedPhoto({
+      id: phHidC,
+      uploaderId: collabId,
+      visibility: 'hidden',
+      processingState: 'ready',
+      uploadedAt: atMinute(40),
+      withVariants: true,
+    });
+    await seedPhoto({
+      id: phHidO,
+      uploaderId: ownerId,
+      visibility: 'hidden',
+      processingState: 'ready',
+      uploadedAt: atMinute(30),
+      withVariants: true,
+    });
+    await seedPhoto({
+      id: phDelO,
+      uploaderId: ownerId,
+      visibility: 'deleted',
+      processingState: 'ready',
+      uploadedAt: atMinute(20),
+      withVariants: true,
+    });
+    await seedPhoto({
+      id: phNovarC,
+      uploaderId: collabId,
+      visibility: 'unpublished',
+      processingState: 'processing_failed',
+      uploadedAt: atMinute(10),
+      withVariants: false,
+    });
+
+    // 预览字节取回断言用：phPubO 的 browse 对象实写 MinIO。
+    await putObject(
+      `photo-live/dev/albums/${albumAId}/variants/${phPubO}/1/browse.jpg`,
+      pubOBrowseBytes,
+    );
+  });
+
+  afterAll(async () => {
+    await app.close();
+    await prisma.$disconnect();
+    await s3.destroy();
+  });
+
+  it('① listAlbums cover：最新 effective 胜出、pending/非 cover 不计、URL 可取回字节', async () => {
+    const res = await listAlbums(ownerToken);
+    expect(res.status).toBe(200);
+    const items = res.body.items as {
+      id: string;
+      cover: { url: string; expiresAt: string } | null;
+    }[];
+    expect(items).toHaveLength(6); // A + B + 4 filler（owner 全部可见）
+
+    const byId = new Map(items.map((item) => [item.id, item]));
+    // A：cover 非 null，签名 URL 实取回新 effective 行字节（非旧行/pending）。
+    const coverA = byId.get(albumAId)?.cover;
+    expect(coverA).not.toBeNull();
+    expect(coverA?.expiresAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    expect(await fetchBody(coverA!.url)).toEqual(coverNewBytes);
+    // B：无封面 → null（键在，值为 null；旧字段不受影响）。
+    expect(byId.get(albumBId)?.cover).toBeNull();
+    // filler：全部非 null。
+    for (const id of fillerIds) {
+      expect(byId.get(id)?.cover).not.toBeNull();
+    }
+  });
+
+  it('① getAlbum 详情：cover 同形（批量路径与单查路径一致）', async () => {
+    const res = await request(app.getHttpServer())
+      .get(`/${API_PREFIX}/albums/${albumAId}`)
+      .set('Authorization', `Bearer ${ownerToken}`);
+    expect(res.status).toBe(200);
+    expect(res.body.cover).not.toBeNull();
+    expect(await fetchBody(res.body.cover.url as string)).toEqual(coverNewBytes);
+
+    const resB = await request(app.getHttpServer())
+      .get(`/${API_PREFIX}/albums/${albumBId}`)
+      .set('Authorization', `Bearer ${ownerToken}`);
+    expect(resB.status).toBe(200);
+    expect(resB.body.cover).toBeNull();
+  });
+
+  it('① 批量无 N+1：6 相册（5 封面）单页列表 = 恒定 Prisma 查询数', async () => {
+    // Prisma 5 $use 无卸载钩子：只挂一次（纯计数透传，不改变行为），以
+    // 计数器清零分隔两次测量。只计相册域模型——SessionGuard 的 sessions
+    // 查询等基础设施流量不入断言（防守卫演进误伤本断言）。
+    const prismaService = app.get(PrismaService);
+    const ALBUM_DOMAIN_MODELS = new Set([
+      'albums',
+      'album_translations',
+      'album_assets',
+      'album_members',
+    ]);
+    let ops = 0;
+    prismaService.$use((params, next) => {
+      if (ALBUM_DOMAIN_MODELS.has(params.model as string)) {
+        ops += 1;
+      }
+      return next(params);
+    });
+
+    try {
+      const res = await listAlbums(ownerToken);
+      expect(res.status).toBe(200);
+      expect((res.body.items as unknown[]).length).toBe(6);
+      // owner：成员行 1 + albums 1 + translations 1 + album_assets 1 = 4。
+      // 封面相册数（5）不进入查询数——若退化为逐相册查封面（N+1）至少 +5。
+      expect(ops).toBe(4);
+
+      // admin 对照：无成员行查询，恒 3（与封面相册数无关）。
+      ops = 0;
+      const adminRes = await listAlbums(adminToken);
+      expect(adminRes.status).toBe(200);
+      expect((adminRes.body.items as unknown[]).length).toBe(6);
+      expect(ops).toBe(3);
+    } finally {
+      // 中间件无法卸载（Prisma 5），保留纯计数透传不影响后续用例；置回 0
+      // 仅为语义整洁。
+      ops = 0;
+    }
+  });
+
+  it('② owner scope=all（缺省）：preview 矩阵 + browse 字节取回', async () => {
+    const res = await listPhotos(ownerToken, albumAId);
+    expect(res.status).toBe(200);
+    const byId = new Map(
+      (res.body.items as { photoId: string; preview: unknown }[]).map(
+        (item) => [item.photoId, item.preview],
+      ),
+    );
+    expect(res.body.items).toHaveLength(6);
+    // published/hidden（含他人上传）对 manager 签发；deleted/无变体 null。
+    expect(byId.get(phPubC)).not.toBeNull();
+    expect(byId.get(phPubO)).not.toBeNull();
+    expect(byId.get(phHidC)).not.toBeNull();
+    expect(byId.get(phHidO)).not.toBeNull();
+    expect(byId.get(phDelO)).toBeNull();
+    expect(byId.get(phNovarC)).toBeNull();
+
+    // 签名 URL 实取回字节（thumb/browse 双通道，preview.browse 为浏览图）。
+    const previewO = byId.get(phPubO) as {
+      thumb: { url: string };
+      browse: { url: string };
+    };
+    expect(await fetchBody(previewO.browse.url)).toEqual(pubOBrowseBytes);
+  });
+
+  it('② admin scope=all：全部签发（他人 hidden 亦签）+ preview 形状', async () => {
+    const res = await listPhotos(adminToken, albumAId, { scope: 'all' });
+    expect(res.status).toBe(200);
+    const items = res.body.items as {
+      photoId: string;
+      preview: { thumb: { url: string; expiresAt: string }; browse: { url: string } } | null;
+    }[];
+    const byId = new Map(items.map((item) => [item.photoId, item.preview]));
+    expect(byId.get(phPubC)).not.toBeNull();
+    expect(byId.get(phHidC)).not.toBeNull(); // 他人 hidden 对 admin 签发
+    expect(byId.get(phHidO)).not.toBeNull();
+    expect(byId.get(phDelO)).toBeNull();
+    expect(byId.get(phNovarC)).toBeNull();
+    for (const item of items) {
+      if (item.preview !== null) {
+        expect(Object.keys(item.preview).sort()).toEqual(['browse', 'thumb']);
+        expect(item.preview.thumb.expiresAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+      }
+    }
+  });
+
+  it('③ collab scope=own：仅自己上传（服务端过滤）+ 自己 hidden 行 preview=null', async () => {
+    const res = await listPhotos(collabToken, albumAId, { scope: 'own' });
+    expect(res.status).toBe(200);
+    const items = res.body.items as {
+      photoId: string;
+      uploaderId: string;
+      preview: unknown;
+    }[];
+    expect(items.map((i) => i.photoId)).toEqual([phPubC, phHidC, phNovarC]);
+    for (const item of items) {
+      expect(item.uploaderId).toBe(collabId); // 服务端过滤，无 owner 照片
+    }
+    // 自己的 published/未完成处理照常签发；hidden 仅 admin/owner 签发 → null
+    //（记录仍可见，图片不可见）。
+    const byId = new Map(items.map((i) => [i.photoId, i.preview]));
+    expect(byId.get(phPubC)).not.toBeNull();
+    expect(byId.get(phHidC)).toBeNull();
+    expect(byId.get(phNovarC)).toBeNull();
+  });
+
+  it('③ owner scope=own：过滤为自己上传（collab 照片不入列表）', async () => {
+    const res = await listPhotos(ownerToken, albumAId, { scope: 'own' });
+    expect(res.status).toBe(200);
+    const ids = (res.body.items as { photoId: string }[]).map((i) => i.photoId);
+    expect(ids).toEqual([phPubO, phHidO, phDelO]);
+    // 组合过滤：scope=own + visibility=published。
+    const combined = await listPhotos(ownerToken, albumAId, {
+      scope: 'own',
+      visibility: 'published',
+    });
+    expect(combined.status).toBe(200);
+    expect(
+      (combined.body.items as { photoId: string }[]).map((i) => i.photoId),
+    ).toEqual([phPubO]);
+  });
+
+  it('④ collab scope=all（缺省与显式）→ 403；非成员任何 scope → 404；非法 scope → 400', async () => {
+    const implicit = await listPhotos(collabToken, albumAId);
+    expect(implicit.status).toBe(403);
+    expect(implicit.body.code).toBe(ErrorCodes.AUTH_FORBIDDEN);
+
+    const explicit = await listPhotos(collabToken, albumAId, { scope: 'all' });
+    expect(explicit.status).toBe(403);
+    expect(explicit.body.code).toBe(ErrorCodes.AUTH_FORBIDDEN);
+
+    // 非成员（outsider 对 A）任何 scope → 404（防枚举）。
+    for (const scope of ['own', 'all', undefined]) {
+      const res = await listPhotos(outsiderToken, albumAId, scope === undefined ? {} : { scope });
+      expect(res.status).toBe(404);
+      expect(res.body.code).toBe(ErrorCodes.ALBUM_NOT_FOUND);
+    }
+    // collab 对非成员相册 B → 404。
+    const cross = await listPhotos(collabToken, albumBId, { scope: 'own' });
+    expect(cross.status).toBe(404);
+    expect(cross.body.code).toBe(ErrorCodes.ALBUM_NOT_FOUND);
+
+    // scope 非法值 → 400；空串视为缺省（collab → 403，同缺省口径）。
+    const garbage = await listPhotos(ownerToken, albumAId, { scope: 'mine' });
+    expect(garbage.status).toBe(400);
+    expect(garbage.body.code).toBe(ErrorCodes.VALIDATION_FAILED);
+    const emptyScope = await listPhotos(collabToken, albumAId, { scope: '' });
+    expect(emptyScope.status).toBe(403);
+  });
+
+  it('④ 被移除成员 scope=own → 404（成员资格逐请求检查）', async () => {
+    // 基线：collab scope=own 可用（③ 已证，此处再验一次后移除）。
+    expect(
+      (await listPhotos(collabToken, albumAId, { scope: 'own' })).status,
+    ).toBe(200);
+    await prisma.album_members.deleteMany({
+      where: { albumId: albumAId, userId: collabId },
+    });
+    const removed = await listPhotos(collabToken, albumAId, { scope: 'own' });
+    expect(removed.status).toBe(404);
+    expect(removed.body.code).toBe(ErrorCodes.ALBUM_NOT_FOUND);
+    // 恢复成员（后续若有 spec 复用；本 spec 至此为止）。
+    await prisma.album_members.create({
+      data: {
+        albumId: albumAId,
+        userId: collabId,
+        role: 'collaborator',
+        status: 'active',
+      },
+    });
+  });
+});