feat(api): upload duplicate pre-check endpoint (checkUploadDuplicates)

「上传查重前置到入队前」Task 1：POST /v1/uploads/duplicates/check 只读批量
查重预检——用户点上传（确认入队）时刻预判服务端历史重复（跨设备/重装/改名
均可查到），不再等任务在上传中心以 PHOTO_DUPLICATE 失败才暴露。

- 契约纯增量：/uploads/duplicates/check + UploadDuplicateCheck(Item|Request|
  Duplicate|Response) schemas；regen openapi.d.ts。
- 判定谓词与 init ③.5 服务端查重逐字一致：同 albumId + uploaderId=当前用户
  + bytes 相等 + visibility != 'deleted'（filename 刻意不参与），保证「预检
  即真相」；命中条目按请求下标逐项返回（同 bytes 多请求条目各一条）。
- 权限链同 init（canView 404 防枚举 / canUpload 403 / 相册空值兜底 404），
  刻意不校验 uploadEnabled：只读预览，init 真正入队时仍按开关 409 兜底。
- 查询走 idx_photos_dedup：请求条目去重字节集一次 findMany，内存建
  bytes→最早 uploadedAt 映射后按请求下标回射。
- items 1..500（minItems/maxItems + 嵌套逐项校验，越界 400）。
- e2e 追加 describe 7 用例：命中含双条目同 bytes/未命中/uploaderId 隔离/
  deleted 不命中/非成员 404/items 边界 400/未认证 401。

契约 lint ✅ · contracts+api typecheck ✅ · api 单测 56/56 ✅ ·
uploads e2e 28/28 ✅

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

services/api/src/uploads/dto.ts

@@ -1,11 +1,18 @@
 // services/api/src/uploads/dto.ts —— 上传端点入参 DTO（Task 18；sourceDeviceId
-// 为 P3 Task 3 契约增补）。校验约束对齐契约 UploadInitRequest：
+// 为 P3 Task 3 契约增补；查重预检 DuplicateCheckRequestDto 为「上传查重前置到
+// 入队前」Task 1 增补）。校验约束对齐契约 UploadInitRequest：
 //   · contentType 限白名单枚举（image/heic 暂定，G2 真机验证）；
 //   · bytes ≥ 1（契约 minimum）；上限 UPLOAD_MAX_BYTES 是环境相关量，逐请求
 //     惰性读取，故在服务层校验（同 filename 扩展名白名单与 categoryId 属主校验）；
 //   · clientTaskId/filename/albumId/categoryId 列宽对齐 db-cn schema
 //     （VarChar 128/255/64/64）；sourceDeviceId 8-64（A19 设备来源语义）。
-import { IsBoolean,
+// DuplicateCheckRequestDto 对齐契约 UploadDuplicateCheckRequest：
+//   · items 1..500（minItems/maxItems，嵌套条目逐项校验）；
+//   · 条目 filename 1..255 / bytes ≥ 1（同 UploadInitRequest 语义）。
+import { Type } from 'class-transformer';
+import { ArrayMaxSize,
+  ArrayMinSize,
+  IsBoolean,
   IsIn,
   IsInt,
   IsNotEmpty,
@@ -14,6 +21,7 @@ import { IsBoolean,
   MaxLength,
   Min,
   MinLength,
+  ValidateNested,
 } from 'class-validator';
 import { UPLOAD_CONTENT_TYPES, type UploadContentType } from './support';
 
@@ -61,3 +69,33 @@ export class UploadInitRequestDto {
   @IsBoolean()
   force?: boolean;
 }
+
+/** 契约 UploadDuplicateCheckRequest.items 单批上限（maxItems:500）。 */
+export const DUPLICATE_CHECK_MAX_ITEMS = 500;
+
+/** 契约 UploadDuplicateCheckItem（查重预检请求条目，与 init 入参同形）。 */
+export class DuplicateCheckItemDto {
+  /** 仅元数据：查重谓词不使用（与 init ③.5 查重一致）。 */
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  filename!: string;
+
+  @IsInt()
+  @Min(1)
+  bytes!: number;
+}
+
+/** 契约 UploadDuplicateCheckRequest（批量查重预检）。 */
+export class DuplicateCheckRequestDto {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(64)
+  albumId!: string;
+
+  @ArrayMinSize(1)
+  @ArrayMaxSize(DUPLICATE_CHECK_MAX_ITEMS)
+  @ValidateNested({ each: true })
+  @Type(() => DuplicateCheckItemDto)
+  items!: DuplicateCheckItemDto[];
+}

services/api/src/uploads/uploads.controller.ts

@@ -1,5 +1,6 @@
 // services/api/src/uploads/uploads.controller.ts —— /uploads 端点（Task 18 起；
-// Task 19 增补 listUploads/renewUploadCredential/completeUpload）。方法名与契约
+// Task 19 增补 listUploads/renewUploadCredential/completeUpload；查重预检
+// checkUploadDuplicates 为「上传查重前置到入队前」Task 1 增补）。方法名与契约
 // operationId 一一对应。控制器级 SessionGuard：端点全需认证。职责：透传认证
 // 用户 + 查询参数规整（parseLimit/parseCursor 用 shared/pagination，同契约 bounds）。
 // 注意 DTO 必须值导入（非 import type）：@Body 参数类型经 emitDecoratorMetadata
@@ -22,10 +23,11 @@ import { AuthenticatedRequest, SessionGuard } from '../auth/session.guard';
 import { UploadsService } from './uploads.service';
 import type {
   UploadCompleteResponse,
+  UploadDuplicateCheckResponse,
   UploadInitResponse,
   UploadSessionListResponse,
 } from './uploads.service';
-import { UploadInitRequestDto } from './dto';
+import { UploadInitRequestDto, DuplicateCheckRequestDto } from './dto';
 
 @Controller('uploads')
 @UseGuards(SessionGuard)
@@ -55,6 +57,20 @@ export class UploadsController {
     );
   }
 
+  /**
+   * 查重预检（只读批量）：判定谓词与 init ③.5 服务端查重逐字一致（见 service
+   * checkDuplicates）。声明于 :uploadId 参数路由之前（静态段路由，无实际冲突，
+   * 仅保持「具体路径先于参数路径」的可读惯例）。
+   */
+  @Post('duplicates/check')
+  @HttpCode(HttpStatus.OK)
+  checkUploadDuplicates(
+    @Body() dto: DuplicateCheckRequestDto,
+    @Req() req: AuthenticatedRequest,
+  ): Promise<UploadDuplicateCheckResponse> {
+    return this.uploadsService.checkDuplicates(userOf(req), dto);
+  }
+
   /** 续签：仅 pending 会话；返回结构同 initUpload（credential 为新值）。 */
   @Post(':uploadId/renew')
   @HttpCode(HttpStatus.OK)

services/api/src/uploads/uploads.service.ts

@@ -27,6 +27,8 @@
 //     被清理也不受影响）后直接回显当前 processingState——不重复 job/audit/入队。
 //   · 权限逐次校验（A02）：renew/complete 每次调用都重查成员权——被移除成员
 //     的下一次请求即刻 403（会话/照片 ID 均已持有也不放行）。
+//   · checkDuplicates（「上传查重前置到入队前」Task 1）：只读批量查重预检，
+//     谓词与 init ③.5 逐字一致；不校验 uploadEnabled（只读预览，init 兜底）。
 import { Inject, Injectable, HttpStatus } from '@nestjs/common';
 import { ErrorCodes } from '@photo/contracts';
 import type { components } from '@photo/contracts';
@@ -52,7 +54,7 @@ import {
   PHOTO_PROCESS_QUEUE,
   type PhotoProcessQueueProducer,
 } from './queue.provider';
-import type { UploadInitRequestDto } from './dto';
+import type { UploadInitRequestDto, DuplicateCheckRequestDto } from './dto';
 import {
   albumUploadDisabled,
   cuidLikeId,
@@ -73,7 +75,11 @@ export type UploadCompleteResponse =
   components['schemas']['UploadCompleteResponse'];
 export type UploadSessionListResponse =
   components['schemas']['UploadSessionList'];
+export type UploadDuplicateCheckResponse =
+  components['schemas']['UploadDuplicateCheckResponse'];
 type UploadSessionRecord = components['schemas']['UploadSessionRecord'];
+type UploadDuplicateCheckDuplicate =
+  components['schemas']['UploadDuplicateCheckDuplicate'];
 
 type SessionRow = {
   id: string;
@@ -538,4 +544,78 @@ export class UploadsService {
       hasMore: nextCursor !== null,
     };
   }
+
+  /**
+   * 查重预检（「上传查重前置到入队前」Task 1）：只读批量——用户点上传（确认
+   * 入队）时刻预判服务端历史重复，跨设备/重装/改名均可查到。判定谓词与 init
+   * ③.5 服务端查重**逐字一致**（同 albumId + uploaderId=当前用户 + bytes 相等
+   * + visibility != 'deleted'；filename 刻意不参与），保证「预检即真相」——
+   * 预检不命中的条目走 init 不会被 409 PHOTO_DUPLICATE 拦截。
+   * 权限链同 init（①可见性 404 / ②成员权 403 / ③相册行空值兜底 404），但
+   * **刻意不校验 uploadEnabled**：预检是只读预览，相册关闭上传时客户端仍可
+   * 查询历史重复（init 在真正入队时仍按开关 409 兜底，语义不变）。
+   * 实现：请求条目去重字节集一次 findMany（idx_photos_dedup 覆盖
+   * albumId+uploaderId+bytes），内存建 bytes→最早 uploadedAt 映射（force 允许
+   * 的同 bytes 多行取最早），再按请求下标逐条回射——两个请求条目共享同一命中
+   * bytes 时各返回一条（duplicates 按请求下标升序）。
+   */
+  async checkDuplicates(
+    user: AuthUser,
+    dto: DuplicateCheckRequestDto,
+  ): Promise<UploadDuplicateCheckResponse> {
+    // ① 相册可见性：不可见（含不存在）统一 404，防 id 枚举（同 init）。
+    if (!(await this.permissions.canViewAlbum(user, dto.albumId))) {
+      throw albumNotFound();
+    }
+    // ② 上传成员权（P1a：可见即成员，此分支不可达；viewer 角色出现时启用 403）。
+    if (!(await this.permissions.canUploadToAlbum(user, dto.albumId))) {
+      throw albumForbidden('无该相册的上传权限');
+    }
+    // ③ 相册行存在性兜底（admin 对不存在 id 权限恒真，须由空值兜底同码 404）。
+    //    刻意不读 uploadEnabled：见方法头注释。
+    const album = await this.prisma.albums.findUnique({
+      where: { id: dto.albumId },
+      select: { id: true },
+    });
+    if (album === null) {
+      throw albumNotFound();
+    }
+
+    const distinctBytes = [...new Set(dto.items.map((item) => item.bytes))];
+    const rows = await this.prisma.photos.findMany({
+      where: {
+        albumId: dto.albumId,
+        uploaderId: user.id,
+        bytes: { in: distinctBytes },
+        visibility: { not: 'deleted' },
+      },
+      select: { bytes: true, uploadedAt: true },
+    });
+    const earliest = new Map<number, Date>();
+    for (const row of rows) {
+      // bytes>0 的行只会经 complete 落定（同事务写 uploadedAt）；null 仅理论
+      // 形状（直改库等），跳过不参与映射——谓词命中与否不受影响（uploadedAt
+      // 只是回显元数据）。
+      if (row.uploadedAt === null) {
+        continue;
+      }
+      const known = earliest.get(row.bytes);
+      if (known === undefined || row.uploadedAt < known) {
+        earliest.set(row.bytes, row.uploadedAt);
+      }
+    }
+
+    const duplicates: UploadDuplicateCheckDuplicate[] = [];
+    dto.items.forEach((item, index) => {
+      const hit = earliest.get(item.bytes);
+      if (hit !== undefined) {
+        duplicates.push({
+          index,
+          bytes: item.bytes,
+          uploadedAt: hit.toISOString(),
+        });
+      }
+    });
+    return { duplicates };
+  }
 }

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

@@ -948,3 +948,202 @@ describe('uploads renew & complete & history (e2e)', () => {
     expect(tooLong.body.code).toBe(ErrorCodes.VALIDATION_FAILED);
   });
 });
+
+// ── 查重预检（checkUploadDuplicates，「上传查重前置到入队前」计划 Task 1）──
+
+describe('uploads duplicates check (e2e)', () => {
+  let app: INestApplication;
+  let prisma: PrismaClient;
+
+  let memberAId: string;
+  let memberBId: string;
+  let memberAToken: string;
+  let outsiderToken: string;
+
+  let albumId: string;
+
+  /** memberA 既有可见照片字节数（固定 uploadedAt 供逐字段断言回显）。 */
+  const BYTES_A = 777_777;
+  const UPLOADED_AT_A = '2026-09-20T08:00:00.000Z';
+  /** memberB（同册协作者）照片字节数（uploaderId 隔离用例）。 */
+  const BYTES_B_OTHER = 888_888;
+  /** memberA 已软删除照片字节数（visibility=deleted 不参与查重）。 */
+  const BYTES_A_DELETED = 999_999;
+
+  const check = (token: string, body: object) =>
+    request(app.getHttpServer())
+      .post(`/${API_PREFIX}/uploads/duplicates/check`)
+      .set('Authorization', `Bearer ${token}`)
+      .send(body);
+
+  const item = (filename: string, bytes: number) => ({ filename, bytes });
+
+  /** 直种 photos 裸行：预检只读 photos 列，无变体/对象存储依赖。 */
+  const seedPhoto = (
+    uploaderId: string,
+    bytes: number,
+    options: { visibility?: string; uploadedAt?: Date } = {},
+  ) =>
+    prisma.photos.create({
+      data: {
+        albumId,
+        uploaderId,
+        objectKey: `photo-live/dev/albums/${albumId}/originals/dc-${uploaderId}-${bytes}-${Math.random().toString(36).slice(2, 8)}.jpg`,
+        bytes,
+        uploadedAt: options.uploadedAt ?? new Date(),
+        visibility: options.visibility ?? 'unpublished',
+      },
+      select: { id: true },
+    });
+
+  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();
+
+    const mkUser = (account: string) =>
+      prisma.users.create({
+        data: { account, passwordHash: 'x', displayName: account },
+        select: { id: true },
+      });
+    const ownerId = (await mkUser('dc-owner')).id;
+    memberAId = (await mkUser('dc-member-a')).id;
+    memberBId = (await mkUser('dc-member-b')).id;
+    const outsiderId = (await mkUser('dc-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;
+    };
+    const ownerToken = await mkToken(ownerId);
+    memberAToken = await mkToken(memberAId);
+    outsiderToken = await mkToken(outsiderId);
+
+    // 相册 fixture：owner 建 A（API 建册自动落 owner 成员行），A/B 为协作者。
+    const res = await request(app.getHttpServer())
+      .post(`/${API_PREFIX}/albums`)
+      .set('Authorization', `Bearer ${ownerToken}`)
+      .send({
+        translations: [
+          { locale: 'zh-CN', title: '查重预检相册' },
+          { locale: 'en', title: 'DupCheck' },
+        ],
+        defaultLocale: 'zh-CN',
+        startAt: '2026-12-01T02:00:00.000Z',
+      });
+    expect(res.status).toBe(201);
+    albumId = res.body.id as string;
+    await prisma.album_members.createMany({
+      data: [
+        { albumId, userId: memberAId, role: 'collaborator' },
+        { albumId, userId: memberBId, role: 'collaborator' },
+      ],
+    });
+
+    // memberA 既有可见照片（非 deleted，uploadedAt 固定）。
+    await seedPhoto(memberAId, BYTES_A, { uploadedAt: new Date(UPLOADED_AT_A) });
+    // memberB 同册照片：memberA 查同 bytes 不得命中（uploaderId 隔离）。
+    await seedPhoto(memberBId, BYTES_B_OTHER);
+    // memberA 已软删除照片：谓词 visibility != deleted，不得命中。
+    await seedPhoto(memberAId, BYTES_A_DELETED, { visibility: 'deleted' });
+  });
+
+  afterAll(async () => {
+    await app.close();
+    await prisma.$disconnect();
+  });
+
+  it('命中：既有可见照片同 bytes → 按请求下标逐项返回（两个同 bytes 条目各一条）', async () => {
+    const res = await check(memberAToken, {
+      albumId,
+      items: [
+        item('first.jpg', 111_111),
+        item('a.jpg', BYTES_A),
+        item('b.jpg', BYTES_A),
+      ],
+    });
+    expect(res.status).toBe(200);
+    expect(res.body.duplicates).toHaveLength(2);
+    // 命中子集按请求下标升序；每命中一个「请求条目」一条（index=1/2 共享命中）。
+    expect(res.body.duplicates[0]).toEqual({
+      index: 1,
+      bytes: BYTES_A,
+      uploadedAt: UPLOADED_AT_A,
+    });
+    expect(res.body.duplicates[1]).toEqual({
+      index: 2,
+      bytes: BYTES_A,
+      uploadedAt: UPLOADED_AT_A,
+    });
+  });
+
+  it('未命中字节数 → 空数组', async () => {
+    const res = await check(memberAToken, {
+      albumId,
+      items: [item('x.jpg', 111_111), item('y.png', 222_222)],
+    });
+    expect(res.status).toBe(200);
+    expect(res.body.duplicates).toEqual([]);
+  });
+
+  it('uploaderId 隔离：同册他人上传的同 bytes 照片不命中（谓词同 init ③.5）', async () => {
+    const res = await check(memberAToken, {
+      albumId,
+      items: [item('other.jpg', BYTES_B_OTHER)],
+    });
+    expect(res.status).toBe(200);
+    expect(res.body.duplicates).toEqual([]);
+  });
+
+  it('visibility=deleted 的照片不命中', async () => {
+    const res = await check(memberAToken, {
+      albumId,
+      items: [item('gone.jpg', BYTES_A_DELETED)],
+    });
+    expect(res.status).toBe(200);
+    expect(res.body.duplicates).toEqual([]);
+  });
+
+  it('非成员 → 404 ALBUM_NOT_FOUND（防枚举，同 init）', async () => {
+    const res = await check(outsiderToken, {
+      albumId,
+      items: [item('a.jpg', BYTES_A)],
+    });
+    expect(res.status).toBe(404);
+    expect(res.body.code).toBe(ErrorCodes.ALBUM_NOT_FOUND);
+  });
+
+  it('items 边界：空数组 → 400；501 项 → 400 VALIDATION_FAILED', async () => {
+    const empty = await check(memberAToken, { albumId, items: [] });
+    expect(empty.status).toBe(400);
+    expect(empty.body.code).toBe(ErrorCodes.VALIDATION_FAILED);
+
+    const overflow = await check(memberAToken, {
+      albumId,
+      items: Array.from({ length: 501 }, (_, i) => item(`f${i}.jpg`, 1_000_000 + i)),
+    });
+    expect(overflow.status).toBe(400);
+    expect(overflow.body.code).toBe(ErrorCodes.VALIDATION_FAILED);
+  });
+
+  it('未认证 → 401', async () => {
+    const res = await request(app.getHttpServer())
+      .post(`/${API_PREFIX}/uploads/duplicates/check`)
+      .send({ albumId, items: [item('a.jpg', BYTES_A)] });
+    expect(res.status).toBe(401);
+    expect(res.body.code).toBe(ErrorCodes.AUTH_TOKEN_EXPIRED);
+  });
+});