feat(api): usage summary with threshold alerts

P4a Task 5（A23 后台侧）：用量统计与阈值告警后端全链。

- cn 迁移（校对手决 utf8mb4_0900_bin）：usage_thresholds 单行配置表
  （迁移内种子行，storageBytes/perAlbumBytes BigInt?，null=维度停用）+
  usage_alerts 告警账本（kind storage|perAlbum、albumId?、resolvedAt?
  索引）。「同 kind+albumId 活跃告警唯一」为应用级约束（MySQL 无部分
  唯一索引）：评估事务以单行配置 FOR UPDATE 作串行化锚点闭合竞态。
- 共享核心 packages/db-cn/src/usage.ts：computeUsageAggregates（非
  deleted 口径实时 SUM：photos groupBy + 变体 JOIN raw）+ evaluateUsage
  （storage/perAlbum 两维超阈 ensure、回落/停用 resolve、去重）+
  evaluateUsageSafe（自开事务、失败仅记日志不拖垮业务主流程）。api 与
  worker 共用（放置原因见文件头）。
- api：GET /admin/usage/summary（相册聚合 + totals + 阈值 + 告警：活跃
  在前、近期解除补位，合计 100）与 PUT /admin/usage/thresholds（缺省
  保持/显式 null 清除 + 契约「即刻重新评估」）；仅 admin。BigInt 运输
  决策：库内 BIGINT、JSON 出入口 Number() 收敛（2^53≈9PB 上限，DTO 以
  MAX_SAFE_INTEGER 拒绝超界输入杜绝静默失真）。
- 检查点（提交后评估）：worker 发布事务后（仅真实 published）、worker
  水印任务完成后、api photos 可见性迁移（PATCH/软删除）与批量隐藏后、
  阈值 PUT 后。
- tests：usage e2e +6（汇总数学/降序/标题、403/401、400 校验矩阵、
  perAlbum 告警产生-去重-上调解除、storage 告警-null 清除解除、hidden
  计入+deleted 回落且穿过 api 检查点）；两侧 reset 增补 usage 表截断 +
  单行重种。全量回归：api e2e 214/214、api 单测 51/51、worker 单测
  14/14 + e2e 13/13。

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

services/api/src/admin/admin.module.ts

@@ -1,12 +1,15 @@
-// services/api/src/admin/admin.module.ts —— 管理辅助域模块（P1b Task 4）。
-// 装配 UsersLookupController/UsersLookupService；仅依赖 @Global 的 PrismaService
-// （SessionGuard 同样只依赖 Prisma），无需导入其他功能模块。
+// services/api/src/admin/admin.module.ts —— 管理辅助域模块（P1b Task 4 起步；
+// P4a Task 5 增补用量统计/阈值告警端点）。装配 UsersLookupController/
+// UsersLookupService 与 UsageController/UsageService；均仅依赖 @Global 的
+// PrismaService（SessionGuard 同样只依赖 Prisma），无需导入其他功能模块。
 import { Module } from '@nestjs/common';
+import { UsageController } from './usage.controller';
+import { UsageService } from './usage.service';
 import { UsersLookupController } from './users-lookup.controller';
 import { UsersLookupService } from './users-lookup.service';
 
 @Module({
-  controllers: [UsersLookupController],
-  providers: [UsersLookupService],
+  controllers: [UsersLookupController, UsageController],
+  providers: [UsersLookupService, UsageService],
 })
 export class AdminModule {}

services/api/src/admin/usage.controller.ts

@@ -0,0 +1,42 @@
+// services/api/src/admin/usage.controller.ts —— /admin/usage 端点（P4a Task 5，
+// A23 后台侧）。方法名与契约 operationId 一一对应（getUsageSummary/
+// updateUsageThresholds，tag [admin]）。控制器级 SessionGuard：两端点全需认证；
+// admin 判定在服务层（AuthUser.role，403 AUTH_FORBIDDEN）。控制器只做认证用户
+// 与 DTO 透传；DTO 值导入（emitDecoratorMetadata 设计期元数据）。
+import {
+  Body,
+  Controller,
+  Get,
+  Put,
+  Req,
+  UseGuards,
+} from '@nestjs/common';
+import { userOf } from '../albums/albums.controller';
+import { AuthenticatedRequest, SessionGuard } from '../auth/session.guard';
+import { UsageThresholdsUpdateDto } from './usage.dto';
+import {
+  UsageService,
+  type UsageSummaryResponse,
+  type UsageThresholdsResponse,
+} from './usage.service';
+
+@Controller('admin/usage')
+@UseGuards(SessionGuard)
+export class UsageController {
+  constructor(private readonly usageService: UsageService) {}
+
+  /** 用量汇总：按相册聚合 + 阈值 + 告警列表。 */
+  @Get('summary')
+  getUsageSummary(@Req() req: AuthenticatedRequest): Promise<UsageSummaryResponse> {
+    return this.usageService.summary(userOf(req));
+  }
+
+  /** 阈值部分更新（缺省保持、null 清除）+ 即刻重新评估。 */
+  @Put('thresholds')
+  updateUsageThresholds(
+    @Body() dto: UsageThresholdsUpdateDto,
+    @Req() req: AuthenticatedRequest,
+  ): Promise<UsageThresholdsResponse> {
+    return this.usageService.updateThresholds(userOf(req), dto);
+  }
+}

services/api/src/admin/usage.dto.ts

@@ -0,0 +1,27 @@
+// services/api/src/admin/usage.dto.ts —— PUT /admin/usage/thresholds 入参 DTO
+// （P4a Task 5）。契约 UsageThresholdsUpdate：字段缺省=保持不变，显式 null=
+// 清除该阈值（维度停用）。class-validator @IsOptional 对 null 同样放行（值
+// 原样保留在 DTO 实例上），缺省/null/给值三态可辨。
+// BigInt 运输决策（对齐 packages/db-cn/src/usage.ts 文件头）：契约 int64 经
+// openapi-typescript 生成 number；库内 BIGINT。请求侧以 MAX_SAFE_INTEGER 为
+// 上界——超 2^53 的 JSON 数值在 JS 已失真，宁可 400 不静默落错值（真实照片
+// 库量级 ≪ 9PB，上界不构成实际限制）。
+import { IsInt, IsOptional, Max, Min } from 'class-validator';
+
+/** 契约 minimum: 0；上界见文件头（MAX_SAFE_INTEGER = 2^53-1）。 */
+const BYTES_MIN = 0;
+const BYTES_MAX = Number.MAX_SAFE_INTEGER;
+
+export class UsageThresholdsUpdateDto {
+  @IsOptional()
+  @IsInt()
+  @Min(BYTES_MIN)
+  @Max(BYTES_MAX)
+  storageBytes?: number | null;
+
+  @IsOptional()
+  @IsInt()
+  @Min(BYTES_MIN)
+  @Max(BYTES_MAX)
+  perAlbumBytes?: number | null;
+}

services/api/src/admin/usage.service.ts

@@ -0,0 +1,177 @@
+// services/api/src/admin/usage.service.ts —— 用量汇总与阈值管理（P4a Task 5，
+// A23 后台侧）。契约权威：openapi /admin/usage/summary|thresholds
+// （getUsageSummary/updateUsageThresholds）。仅 admin（AuthUser.role，403
+// AUTH_FORBIDDEN）。
+// 聚合/评估核心在 @photo/db-cn usage.ts（worker 检查点共用）；本服务只做：
+//   · summary：聚合 + 相册标题（defaultLocale 解析）+ 阈值 + 告警列表
+//     （活跃在前、其后近期已解除，合计上限 100——契约「createdAt 倒序，含已
+//     解除」在「未解决优先呈现」运营语义下的落地）；
+//   · updateThresholds：单行 upsert（缺省字段保持不变、显式 null 清除）+ 契约
+//     「修改后即刻重新评估」——评估在 upsert 提交后自开事务执行（失败上抛：
+//     阈值已落库是事实，500 提示管理员重试；重试幂等）。
+import { HttpStatus, Injectable } from '@nestjs/common';
+import { ErrorCodes, type components } from '@photo/contracts';
+import {
+  computeUsageAggregates,
+  evaluateUsage,
+  USAGE_ALERTS_LIST_LIMIT,
+  USAGE_THRESHOLDS_SINGLETON_ID,
+} from '@photo/db-cn';
+import { ApiException } from '../api-exception';
+import type { AuthUser } from '../auth/session.guard';
+import { PrismaService } from '../prisma/prisma.service';
+import type { UsageThresholdsUpdateDto } from './usage.dto';
+
+export type UsageSummaryResponse = components['schemas']['UsageSummary'];
+export type UsageThresholdsResponse = components['schemas']['UsageThresholds'];
+export type UsageAlbumItem = components['schemas']['UsageAlbum'];
+export type UsageAlertItem = components['schemas']['UsageAlert'];
+
+function requireAdmin(user: AuthUser): void {
+  if (user.role !== 'admin') {
+    throw new ApiException(
+      ErrorCodes.AUTH_FORBIDDEN,
+      '仅管理员可管理用量阈值与查看用量统计',
+      HttpStatus.FORBIDDEN,
+    );
+  }
+}
+
+@Injectable()
+export class UsageService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  /** 用量汇总（实时 SUM + 阈值 + 告警；相册按 totalBytes 降序，同值按 id 稳定）。 */
+  async summary(user: AuthUser): Promise<UsageSummaryResponse> {
+    requireAdmin(user);
+    const [albums, translations, thresholds, aggregates] = await Promise.all([
+      this.prisma.albums.findMany({
+        select: { id: true, defaultLocale: true },
+        orderBy: { id: 'asc' },
+      }),
+      this.prisma.album_translations.findMany({
+        orderBy: { locale: 'asc' }, // 标题回退取序稳定
+      }),
+      this.prisma.usage_thresholds.findUnique({
+        where: { id: USAGE_THRESHOLDS_SINGLETON_ID },
+      }),
+      computeUsageAggregates(this.prisma),
+    ]);
+
+    const titlesByAlbum = new Map<string, Map<string, string>>();
+    for (const t of translations) {
+      let titles = titlesByAlbum.get(t.albumId);
+      if (titles === undefined) {
+        titles = new Map();
+        titlesByAlbum.set(t.albumId, titles);
+      }
+      titles.set(t.locale, t.title);
+    }
+
+    const albumItems: UsageAlbumItem[] = albums.map((album) => {
+      const agg = aggregates.perAlbum.get(album.id);
+      const titles = titlesByAlbum.get(album.id);
+      return {
+        albumId: album.id,
+        // defaultLocale 翻译缺失（脏数据）回退任一翻译，再回退空串——单册脏
+        // 数据不拖垮整页（同成员/照片列表先例）。
+        title: titles?.get(album.defaultLocale) ?? [...(titles?.values() ?? [])][0] ?? '',
+        photoCount: agg?.photoCount ?? 0,
+        originalBytes: agg?.originalBytes ?? 0,
+        variantBytes: agg?.variantBytes ?? 0,
+        totalBytes: agg?.totalBytes ?? 0,
+      };
+    });
+    albumItems.sort((a, b) => b.totalBytes - a.totalBytes || (a.albumId < b.albumId ? -1 : 1));
+
+    const activeAlerts = await this.prisma.usage_alerts.findMany({
+      where: { resolvedAt: null },
+      orderBy: [{ createdAt: 'desc' }, { id: 'desc' }],
+      take: USAGE_ALERTS_LIST_LIMIT,
+    });
+    // 已解除告警按「近期解除优先」补位（resolvedAt 倒序，合计不超上限）。
+    const resolvedAlerts =
+      activeAlerts.length >= USAGE_ALERTS_LIST_LIMIT
+        ? []
+        : await this.prisma.usage_alerts.findMany({
+            where: { resolvedAt: { not: null } },
+            orderBy: [{ resolvedAt: 'desc' }, { id: 'desc' }],
+            take: USAGE_ALERTS_LIST_LIMIT - activeAlerts.length,
+          });
+
+    return {
+      albums: albumItems,
+      totals: {
+        photoCount: aggregates.totals.photoCount,
+        totalBytes: aggregates.totals.totalBytes,
+      },
+      thresholds: {
+        storageBytes:
+          thresholds?.storageBytes == null ? null : Number(thresholds.storageBytes),
+        perAlbumBytes:
+          thresholds?.perAlbumBytes == null ? null : Number(thresholds.perAlbumBytes),
+      },
+      alerts: [...activeAlerts, ...resolvedAlerts].map(toUsageAlertItem),
+    };
+  }
+
+  /**
+   * 阈值更新（部分更新语义）+ 即刻重新评估（超阈产生新告警/阈值上调解除旧
+   * 告警）。评估事务在 upsert 提交后执行。
+   */
+  async updateThresholds(
+    user: AuthUser,
+    dto: UsageThresholdsUpdateDto,
+  ): Promise<UsageThresholdsResponse> {
+    requireAdmin(user);
+    const current = await this.prisma.usage_thresholds.findUnique({
+      where: { id: USAGE_THRESHOLDS_SINGLETON_ID },
+    });
+    const nextStorage =
+      dto.storageBytes === undefined
+        ? (current?.storageBytes ?? null)
+        : dto.storageBytes === null
+          ? null
+          : BigInt(dto.storageBytes);
+    const nextPerAlbum =
+      dto.perAlbumBytes === undefined
+        ? (current?.perAlbumBytes ?? null)
+        : dto.perAlbumBytes === null
+          ? null
+          : BigInt(dto.perAlbumBytes);
+
+    await this.prisma.usage_thresholds.upsert({
+      where: { id: USAGE_THRESHOLDS_SINGLETON_ID },
+      update: { storageBytes: nextStorage, perAlbumBytes: nextPerAlbum },
+      create: {
+        id: USAGE_THRESHOLDS_SINGLETON_ID,
+        storageBytes: nextStorage,
+        perAlbumBytes: nextPerAlbum,
+      },
+    });
+    await this.prisma.$transaction((tx) => evaluateUsage(tx));
+
+    return {
+      storageBytes: nextStorage === null ? null : Number(nextStorage),
+      perAlbumBytes: nextPerAlbum === null ? null : Number(nextPerAlbum),
+    };
+  }
+}
+
+function toUsageAlertItem(row: {
+  id: string;
+  kind: string;
+  albumId: string | null;
+  message: string;
+  createdAt: Date;
+  resolvedAt: Date | null;
+}): UsageAlertItem {
+  return {
+    id: row.id,
+    kind: row.kind as UsageAlertItem['kind'],
+    albumId: row.albumId,
+    message: row.message,
+    createdAt: row.createdAt.toISOString(),
+    resolvedAt: row.resolvedAt === null ? null : row.resolvedAt.toISOString(),
+  };
+}

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

@@ -19,8 +19,12 @@
 // + entityVersion 自增 + 事务内 outbox 事件（P2 副本按 entityVersion 单调消费）
 // + audit。幂等前态（同值 PATCH / 重复 DELETE）直接回显当前记录，不产生
 // 第二次事件/审计（entityVersion 不动——副本侧按版本去重的不变量）。
-import { Injectable } from '@nestjs/common';
+// P4a Task 5 检查点：可见性真实迁移（transition/hideBatch）提交后评估用量
+// 阈值告警（deleted 不计用量——软删除可能解除告警；hidden 仍计）。评估在
+// 自开事务执行且失败只记日志，绝不影响可见性操作本身（见 evaluateUsageSafe）。
+import { 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 { AuthUser } from '../auth/session.guard';
 import { PermissionsService } from '../albums/permissions.service';
@@ -72,6 +76,8 @@ function toPhotoRecord(row: PhotoRow): PhotoRecord {
 
 @Injectable()
 export class PhotosService {
+  private readonly logger = new Logger(PhotosService.name);
+
   constructor(
     private readonly prisma: PrismaService,
     private readonly permissions: PermissionsService,
@@ -232,6 +238,17 @@ export class PhotosService {
     for (const photoId of photoIds) {
       results.push(await this.hideOne(user, albumId, photoId));
     }
+    // P4a Task 5 检查点：批量后评估一次（逐项不重复评估——隐藏不改存储，
+    // 检查点统一挂在可见性动作完成后；失败只记日志）。
+    await evaluateUsageSafe(this.prisma, (err) =>
+      this.logger.warn(
+        {
+          err: err instanceof Error ? err.message : String(err),
+          albumId,
+        },
+        '用量告警评估失败（批量隐藏后）',
+      ),
+    );
     return { results };
   }
 
@@ -483,6 +500,18 @@ export class PhotosService {
         target,
       );
     }
+    // P4a Task 5 检查点：真实迁移提交后评估（deleted 出存储口径、恢复发布回
+    // 计数口径都可能翻转告警状态）；上方败方/幂等路径无状态变化，不评估。
+    await evaluateUsageSafe(this.prisma, (err) =>
+      this.logger.warn(
+        {
+          err: err instanceof Error ? err.message : String(err),
+          photoId: photo.id,
+          target,
+        },
+        '用量告警评估失败（可见性迁移后）',
+      ),
+    );
     return toPhotoRecord(updatedRow);
   }
 }

services/api/test/reset.ts

@@ -14,7 +14,10 @@ import {
   ListObjectsV2Command,
   S3Client,
 } from '@aws-sdk/client-s3';
-import { PrismaClient } from '@photo/db-cn';
+import {
+  PrismaClient,
+  USAGE_THRESHOLDS_SINGLETON_ID,
+} from '@photo/db-cn';
 
 export const RESET_TABLES: readonly string[] = [
   // 照片与上传域 + outbox（Task 10）：均为扁平字符串外键（无 FK 约束），
@@ -24,6 +27,9 @@ export const RESET_TABLES: readonly string[] = [
   'photo_variants',
   'upload_sessions',
   'photos',
+  // 用量域（P4a Task 5）：告警账本先于阈值单行（重种在 resetDb 尾部）。
+  'usage_alerts',
+  'usage_thresholds',
   // 水印域（P4a Task 3）：任务/配置账本先于 albums（watermarkVersion 等位列
   // 随 albums 清零）。
   'watermark_jobs',
@@ -109,6 +115,11 @@ export async function resetDb(): Promise<void> {
     for (const table of RESET_TABLES) {
       await prisma.$executeRawUnsafe(`TRUNCATE TABLE ${table}`);
     }
+    // 用量阈值单行被 TRUNCATE 后重种（迁移同值种子；保证「单行恒存在」
+    // 不变量对后续 spec 成立——发布路径的评估检查点依赖它，缺行时兜底
+    // 视作双维停用，跨 spec 的阈值残留则被清除）。
+    await prisma.$executeRaw`INSERT INTO usage_thresholds (id, storageBytes, perAlbumBytes, updatedAt)
+      VALUES (${USAGE_THRESHOLDS_SINGLETON_ID}, NULL, NULL, CURRENT_TIMESTAMP(6))`;
   } finally {
     await prisma.$executeRawUnsafe('SET FOREIGN_KEY_CHECKS = 1');
     await prisma.$disconnect();

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

@@ -0,0 +1,418 @@
+// services/api/test/usage.e2e-spec.ts —— P4a Task 5 用量统计与阈值告警 e2e。
+// 真实 AppCnModule × MySQL（cn 单侧——用量域不涉 ov/同步/MinIO 对象）；照片
+// 直种 + 直改 bytes 伪造超阈（避免真实上传 GB 级对象），评估经 PUT thresholds
+// 的「即刻重新评估」契约语义触发。覆盖：
+//   ① 汇总形状与数学：相册聚合（原图/变体/合计/照片数）+ 全库 totals +
+//      totalBytes 降序 + 标题 defaultLocale 解析 + 缺省阈值 null/null；
+//   ② 访问控制：staff GET/PUT 403 AUTH_FORBIDDEN；未认证 401；
+//   ③ 入参校验：负值/小数/字符串/超 2^53 → 400 VALIDATION_FAILED；空体=全保持；
+//   ④ perAlbum 告警全链（A23）：直改 bytes 超阈 → PUT → summary 活跃告警
+//      （kind/albumId/message 含字节数与相册标题）→ 再次评估去重（活跃唯一）
+//      → 阈值上调 → resolvedAt 置位（后台可见已解除告警）；
+//   ⑤ storage 告警：全库 totals 超阈 → 活跃（albumId=null，message 含全库
+//      字节数）→ 显式 null 清除维度 → 旧告警解除；
+//   ⑥ 计数口径 + api 侧检查点：hidden 计入用量（PATCH 隐藏后 totals 不变，
+//      穿过可见性迁移检查点）；deleted 不计（API 软删除后 totals 回落，穿过
+//      软删除检查点）。
+import { randomBytes } from 'node:crypto';
+import { NestFactory } from '@nestjs/core';
+import { type NestExpressApplication } from '@nestjs/platform-express';
+import request from 'supertest';
+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 { configureApp } from '../src/shared/configure-app';
+import { resetDb } from './reset';
+
+jest.setTimeout(120_000);
+
+/** cuid 形状 ID（直种照片用，同 batch-ops 约定）。 */
+function cuidLike(alias: string): string {
+  return `c${Date.now().toString(36)}${alias}${randomBytes(6).toString('hex')}`;
+}
+
+describe('usage summary + threshold alerts (e2e)', () => {
+  let cnApp: NestExpressApplication;
+  let cnBase: string;
+  let prismaCn: PrismaClient;
+
+  let adminId: string;
+  let ownerAId: string;
+  let staffXId: string;
+  let adminToken: string;
+  let ownerAToken: string;
+  let staffXToken: string;
+
+  let albumAId: string;
+  let albumBId: string;
+
+  /** 直种照片 id（④ 超阈伪造与 ⑥ 软删除用）。 */
+  let pa1Id: string;
+  let pa4Id: string;
+
+  /** 直种照片（无真实对象：本 spec 只断言聚合/告警，不读图）。 */
+  async function seedPhoto(
+    alias: string,
+    albumId: string,
+    opts: {
+      bytes: number;
+      visibility: 'published' | 'hidden' | 'unpublished';
+      variants: { variant: 'thumb' | 'browse'; bytes: number }[];
+    },
+  ): Promise<string> {
+    const photoId = cuidLike(alias);
+    await prismaCn.photos.create({
+      data: {
+        id: photoId,
+        albumId,
+        uploaderId: ownerAId,
+        objectKey: `usage-test/originals/${photoId}.jpg`,
+        bytes: opts.bytes,
+        width: 800,
+        height: 600,
+        uploadedAt: new Date(),
+        publishedAt:
+          opts.visibility === 'unpublished' ? null : new Date(),
+        processingState: 'ready',
+        visibility: opts.visibility,
+        entityVersion: 2,
+      },
+    });
+    for (const v of opts.variants) {
+      await prismaCn.photo_variants.create({
+        data: {
+          photoId,
+          variant: v.variant,
+          objectKey: `usage-test/variants/${photoId}/${v.variant}.jpg`,
+          bytes: v.bytes,
+          version: 1,
+        },
+      });
+    }
+    return photoId;
+  }
+
+  function getSummary(token: string) {
+    return request(cnBase)
+      .get('/v1/admin/usage/summary')
+      .set('Authorization', `Bearer ${token}`);
+  }
+
+  function putThresholds(token: string, body: object) {
+    return request(cnBase)
+      .put('/v1/admin/usage/thresholds')
+      .set('Authorization', `Bearer ${token}`)
+      .send(body);
+  }
+
+  beforeAll(async () => {
+    await resetDb();
+
+    cnApp = await NestFactory.create<NestExpressApplication>(AppCnModule, {
+      rawBody: true,
+    });
+    configureApp(cnApp);
+    await cnApp.listen(0);
+    cnBase = await cnApp.getUrl();
+
+    prismaCn = new PrismaClient();
+
+    const mkUser = (account: string, role: 'staff' | 'admin') =>
+      prismaCn.users.create({
+        data: { account, role, passwordHash: 'x', displayName: account },
+        select: { id: true },
+      });
+    adminId = (await mkUser('usage-admin', 'admin')).id;
+    ownerAId = (await mkUser('usage-owner', 'staff')).id;
+    staffXId = (await mkUser('usage-staff-x', 'staff')).id;
+
+    const mkToken = async (userId: string): Promise<string> => {
+      const token = randomBytes(32).toString('hex');
+      await prismaCn.sessions.create({
+        data: {
+          userId,
+          tokenHash: hashSessionToken(token),
+          expiresAt: new Date(Date.now() + 3_600_000),
+        },
+      });
+      return token;
+    };
+    adminToken = await mkToken(adminId);
+    ownerAToken = await mkToken(ownerAId);
+    staffXToken = await mkToken(staffXId);
+
+    const mkAlbum = async (title: string) => {
+      const res = await request(cnBase)
+        .post('/v1/albums')
+        .set('Authorization', `Bearer ${ownerAToken}`)
+        .send({
+          translations: [{ locale: 'zh-CN', title }],
+          defaultLocale: 'zh-CN',
+          startAt: '2026-10-01T10:00:00.000Z',
+        });
+      expect(res.status).toBe(201);
+      return res.body.id as string;
+    };
+    albumAId = await mkAlbum('用量相册甲');
+    albumBId = await mkAlbum('用量相册乙');
+
+    // 相册 A：published(1000, thumb100+browse250) + hidden(500, browse50) +
+    // unpublished(300, 无变体) + published(200, 无变体——⑥ 软删除用)。
+    // 相册 B：published(100)。① 的期望值据此推算。
+    pa1Id = await seedPhoto('usagePa1', albumAId, {
+      bytes: 1000,
+      visibility: 'published',
+      variants: [
+        { variant: 'thumb', bytes: 100 },
+        { variant: 'browse', bytes: 250 },
+      ],
+    });
+    await seedPhoto('usagePa2', albumAId, {
+      bytes: 500,
+      visibility: 'hidden',
+      variants: [{ variant: 'browse', bytes: 50 }],
+    });
+    await seedPhoto('usagePa3', albumAId, {
+      bytes: 300,
+      visibility: 'unpublished',
+      variants: [],
+    });
+    pa4Id = await seedPhoto('usagePa4', albumAId, {
+      bytes: 200,
+      visibility: 'published',
+      variants: [],
+    });
+    await seedPhoto('usagePb1', albumBId, {
+      bytes: 100,
+      visibility: 'published',
+      variants: [],
+    });
+  });
+
+  afterAll(async () => {
+    await cnApp.close();
+    await prismaCn.$disconnect();
+  });
+
+  it('① 汇总形状与数学：相册聚合/totals/降序/标题/缺省阈值/空告警', async () => {
+    const res = await getSummary(adminToken);
+    expect(res.status).toBe(200);
+    expect(Object.keys(res.body).sort()).toEqual([
+      'albums',
+      'alerts',
+      'thresholds',
+      'totals',
+    ]);
+
+    // 相册条目按 totalBytes 降序（A 2400 > B 100）。
+    expect(res.body.albums).toHaveLength(2);
+    expect(res.body.albums[0]).toEqual({
+      albumId: albumAId,
+      title: '用量相册甲',
+      photoCount: 4,
+      originalBytes: 2000,
+      variantBytes: 400,
+      totalBytes: 2400,
+    });
+    expect(res.body.albums[1]).toEqual({
+      albumId: albumBId,
+      title: '用量相册乙',
+      photoCount: 1,
+      originalBytes: 100,
+      variantBytes: 0,
+      totalBytes: 100,
+    });
+
+    expect(res.body.totals).toEqual({ photoCount: 5, totalBytes: 2500 });
+    expect(res.body.thresholds).toEqual({
+      storageBytes: null,
+      perAlbumBytes: null,
+    });
+    expect(res.body.alerts).toEqual([]);
+  });
+
+  it('② 访问控制：staff 403；未认证 401', async () => {
+    const staffGet = await getSummary(staffXToken);
+    expect(staffGet.status).toBe(403);
+    expect(staffGet.body.code).toBe(ErrorCodes.AUTH_FORBIDDEN);
+
+    const staffPut = await putThresholds(staffXToken, {
+      perAlbumBytes: 1000,
+    });
+    expect(staffPut.status).toBe(403);
+    expect(staffPut.body.code).toBe(ErrorCodes.AUTH_FORBIDDEN);
+
+    const anon = await request(cnBase).get('/v1/admin/usage/summary');
+    expect(anon.status).toBe(401);
+    expect(anon.body.code).toBe(ErrorCodes.AUTH_TOKEN_EXPIRED);
+  });
+
+  it('③ 入参校验：负值/小数/字符串/超 2^53 → 400；空体 = 全保持', async () => {
+    for (const bad of [-1, 1.5, 'abc', 9007199254740992]) {
+      const res = await putThresholds(adminToken, { storageBytes: bad });
+      expect(res.status).toBe(400);
+      expect(res.body.code).toBe(ErrorCodes.VALIDATION_FAILED);
+    }
+    const negative = await putThresholds(adminToken, { perAlbumBytes: -5 });
+    expect(negative.status).toBe(400);
+    expect(negative.body.code).toBe(ErrorCodes.VALIDATION_FAILED);
+
+    // 空体：两维缺省=保持（仍为 null）。
+    const empty = await putThresholds(adminToken, {});
+    expect(empty.status).toBe(200);
+    expect(empty.body).toEqual({ storageBytes: null, perAlbumBytes: null });
+  });
+
+  it('④ perAlbum 告警：超阈产生（含字节数/标题）→ 去重 → 上调解除', async () => {
+    // 直改 DB 伪造超阈（避免上传 GB 级真实对象）。
+    await prismaCn.photos.update({
+      where: { id: pa1Id },
+      data: { bytes: 10_000_000 },
+    });
+    // 相册 A 合计 = 10_000_000 + 500 + 300 + 200（原图）+ 400（变体）= 10_001_400。
+
+    const put = await putThresholds(adminToken, { perAlbumBytes: 5_000_000 });
+    expect(put.status).toBe(200);
+    expect(put.body).toEqual({ storageBytes: null, perAlbumBytes: 5_000_000 });
+
+    const res = await getSummary(adminToken);
+    expect(res.status).toBe(200);
+    expect(res.body.thresholds).toEqual({
+      storageBytes: null,
+      perAlbumBytes: 5_000_000,
+    });
+    const active = res.body.alerts.filter(
+      (a: { resolvedAt: string | null }) => a.resolvedAt === null,
+    );
+    expect(active).toHaveLength(1);
+    expect(active[0].kind).toBe('perAlbum');
+    expect(active[0].albumId).toBe(albumAId);
+    expect(active[0].message).toContain('用量相册甲');
+    // 字面量经模板插值为无分隔符十进制（10001400 = 10_001_400）。
+    expect(active[0].message).toContain('10001400');
+    expect(active[0].message).toContain('5000000');
+
+    // 去重：再次评估（PUT storage 维度触发）不产生第二条活跃告警。
+    const reevaluate = await putThresholds(adminToken, {
+      storageBytes: 2_000_000_000,
+    });
+    expect(reevaluate.status).toBe(200);
+    expect(
+      await prismaCn.usage_alerts.count({
+        where: { kind: 'perAlbum', albumId: albumAId, resolvedAt: null },
+      }),
+    ).toBe(1);
+
+    // 阈值上调超过实际用量 → 旧告警 resolvedAt 置位，活跃清空。
+    const raise = await putThresholds(adminToken, { perAlbumBytes: 20_000_000 });
+    expect(raise.status).toBe(200);
+    expect(raise.body).toEqual({
+      storageBytes: 2_000_000_000,
+      perAlbumBytes: 20_000_000,
+    });
+    expect(
+      await prismaCn.usage_alerts.count({
+        where: { kind: 'perAlbum', resolvedAt: null },
+      }),
+    ).toBe(0);
+    const resolvedRow = await prismaCn.usage_alerts.findFirstOrThrow({
+      where: { kind: 'perAlbum', albumId: albumAId },
+    });
+    expect(resolvedRow.resolvedAt).not.toBeNull();
+    // summary 仍可见已解除告警（含 resolvedAt）。
+    const after = await getSummary(adminToken);
+    const resolvedShown = after.body.alerts.find(
+      (a: { kind: string }) => a.kind === 'perAlbum',
+    );
+    expect(resolvedShown.resolvedAt).not.toBeNull();
+  });
+
+  it('⑤ storage 告警：totals 超阈产生（albumId=null）→ null 清除维度解除', async () => {
+    // 全库 totals = 10_001_400 + 100（相册 B）= 10_001_500 > 5_000_000。
+    const put = await putThresholds(adminToken, { storageBytes: 5_000_000 });
+    expect(put.status).toBe(200);
+    expect(put.body).toEqual({
+      storageBytes: 5_000_000,
+      perAlbumBytes: 20_000_000,
+    });
+
+    const res = await getSummary(adminToken);
+    const active = res.body.alerts.filter(
+      (a: { resolvedAt: string | null }) => a.resolvedAt === null,
+    );
+    expect(active).toHaveLength(1);
+    expect(active[0].kind).toBe('storage');
+    expect(active[0].albumId).toBeNull();
+    // 全库 totals 10001500 = 10_001_500（无分隔符十进制）。
+    expect(active[0].message).toContain('10001500');
+    expect(active[0].message).toContain('5000000');
+
+    // 显式 null 清除维度（契约：清除后该维度停用）→ 活跃告警解除。
+    const clear = await putThresholds(adminToken, { storageBytes: null });
+    expect(clear.status).toBe(200);
+    expect(clear.body).toEqual({
+      storageBytes: null,
+      perAlbumBytes: 20_000_000,
+    });
+    expect(
+      await prismaCn.usage_alerts.count({
+        where: { kind: 'storage', resolvedAt: null },
+      }),
+    ).toBe(0);
+    const resolvedRow = await prismaCn.usage_alerts.findFirstOrThrow({
+      where: { kind: 'storage' },
+    });
+    expect(resolvedRow.resolvedAt).not.toBeNull();
+  });
+
+  it('⑥ 口径与 api 检查点：hidden 计入（PATCH 后不变）；deleted 不计（软删后回落）', async () => {
+    // 恢复 pa1 字节并清空两维阈值（后续断言回到可控基线）。
+    await prismaCn.photos.update({
+      where: { id: pa1Id },
+      data: { bytes: 1000 },
+    });
+    const reset = await putThresholds(adminToken, {
+      storageBytes: null,
+      perAlbumBytes: null,
+    });
+    expect(reset.body).toEqual({ storageBytes: null, perAlbumBytes: null });
+
+    // PATCH 隐藏（穿过可见性迁移检查点）：hidden 仍计用量——totals 不变。
+    const hide = await request(cnBase)
+      .patch(`/v1/photos/${pa1Id}`)
+      .set('Authorization', `Bearer ${ownerAToken}`)
+      .send({ visibility: 'hidden' });
+    expect(hide.status).toBe(200);
+    expect(hide.body.visibility).toBe('hidden');
+
+    const duringHidden = await getSummary(adminToken);
+    const albumADuring = (
+      duringHidden.body.albums as { albumId: string }[]
+    ).find((a) => a.albumId === albumAId);
+    expect(albumADuring).toMatchObject({
+      photoCount: 4,
+      originalBytes: 2000,
+      variantBytes: 400,
+      totalBytes: 2400,
+    });
+
+    // 软删除（穿过软删除检查点）：deleted 不计——相册 A 与全库回落。
+    const del = await request(cnBase)
+      .delete(`/v1/photos/${pa4Id}`)
+      .set('Authorization', `Bearer ${ownerAToken}`);
+    expect(del.status).toBe(204);
+
+    const after = await getSummary(adminToken);
+    const albumAAfter = (
+      after.body.albums as { albumId: string }[]
+    ).find((a) => a.albumId === albumAId);
+    expect(albumAAfter).toMatchObject({
+      photoCount: 3,
+      originalBytes: 1800,
+      variantBytes: 400,
+      totalBytes: 2200,
+    });
+    expect(after.body.totals).toEqual({ photoCount: 4, totalBytes: 2300 });
+  });
+});