photo-live/services/api/src/albums/albums.controller.ts

// services/api/src/albums/albums.controller.ts —— /albums 端点（Task 15；Task 16
// 增补 updateAlbum）。方法名与契约 operationId 一一对应（createAlbum/
// listAlbums/getAlbum/updateAlbum）。控制器级 SessionGuard：四端点全需认证
// （契约均有 bearerAuth、无 security: [] 例外）。职责仅剩：
//   · 透传认证用户（req.user，守卫挂载）；
//   · 查询参数规整（limit 1..100 整数、cursor 长度），非法 → 400
//     VALIDATION_FAILED，与 body 校验同一出口；
//   · 权限/可见性→HTTP 映射交由服务层抛 ApiException（404 ALBUM_NOT_FOUND）。
import {
  Body,
  Controller,
  Get,
  HttpStatus,
  Param,
  Patch,
  Post,
  Query,
  Req,
  UseGuards,
} from '@nestjs/common';
import { ErrorCodes } from '@photo/contracts';
import { ApiException } from '../api-exception';
import type { AuthUser } from '../auth/session.guard';
import { AuthenticatedRequest, SessionGuard } from '../auth/session.guard';
import {
  DEFAULT_ALBUM_PAGE_SIZE,
  MAX_ALBUM_PAGE_SIZE,
  type AlbumListResponse,
  type AlbumResponse,
  AlbumsService,
} from './albums.service';
import { AlbumCreateRequestDto, AlbumUpdateRequestDto } from './dto';
import { MAX_CURSOR_LENGTH } from '../shared/cursor';

/**
 * 守卫放行后提取 req.user；防御性兜底（守卫未挂载属装配错误，按未认证拒绝）。
 * members/categories 控制器（Task 17）复用同一判定，导出。
 */
export function userOf(req: AuthenticatedRequest): AuthUser {
  if (req.user === undefined) {
    throw new ApiException(
      ErrorCodes.AUTH_TOKEN_EXPIRED,
      'Session token is missing, invalid, or expired',
      HttpStatus.UNAUTHORIZED,
    );
  }
  return req.user;
}

/** limit 查询参数：缺省 20，须为 1..100 的十进制整数（契约 bounds）。导出供
 *  members 列表（Task 17，同契约 bounds）复用。 */
export function parseLimit(raw: string | undefined): number {
  if (raw === undefined || raw === '') {
    return DEFAULT_ALBUM_PAGE_SIZE;
  }
  if (!/^\d+$/.test(raw)) {
    throw new ApiException(
      ErrorCodes.VALIDATION_FAILED,
      'limit 必须是 1-100 的整数',
      HttpStatus.BAD_REQUEST,
    );
  }
  const limit = Number.parseInt(raw, 10);
  if (limit < 1 || limit > MAX_ALBUM_PAGE_SIZE) {
    throw new ApiException(
      ErrorCodes.VALIDATION_FAILED,
      'limit 必须是 1-100 的整数',
      HttpStatus.BAD_REQUEST,
    );
  }
  return limit;
}

/** cursor 查询参数：仅做长度规整（语义校验在服务层解码时）；导出供 members
 *  列表（Task 17）复用。 */
export function parseCursor(raw: string | undefined): string | undefined {
  if (raw === undefined || raw === '') {
    return undefined;
  }
  if (raw.length > MAX_CURSOR_LENGTH) {
    throw new ApiException(
      ErrorCodes.VALIDATION_FAILED,
      'cursor 不合法',
      HttpStatus.BAD_REQUEST,
    );
  }
  return raw;
}

@Controller('albums')
@UseGuards(SessionGuard)
export class AlbumsController {
  constructor(private readonly albumsService: AlbumsService) {}

  @Post()
  createAlbum(
    @Body() dto: AlbumCreateRequestDto,
    @Req() req: AuthenticatedRequest,
  ): Promise<AlbumResponse> {
    return this.albumsService.create(userOf(req).id, dto);
  }

  @Get()
  listAlbums(
    @Query('cursor') cursor: string | undefined,
    @Query('limit') limit: string | undefined,
    @Req() req: AuthenticatedRequest,
  ): Promise<AlbumListResponse> {
    return this.albumsService.list(
      userOf(req),
      parseCursor(cursor),
      parseLimit(limit),
    );
  }

  @Get(':albumId')
  getAlbum(
    @Param('albumId') albumId: string,
    @Req() req: AuthenticatedRequest,
  ): Promise<AlbumResponse> {
    return this.albumsService.get(userOf(req), albumId);
  }

  @Patch(':albumId')
  updateAlbum(
    @Param('albumId') albumId: string,
    @Body() dto: AlbumUpdateRequestDto,
    @Req() req: AuthenticatedRequest,
  ): Promise<AlbumResponse> {
    return this.albumsService.update(userOf(req), albumId, dto);
  }
}