// services/api/src/public-ov/public-ov.controller.ts —— ov 公开端点
// （P2 Task 6）。路由/方法名与 cn public.controller 一一对应（契约同形：
// 路径前缀不变、部署域名区分），差异仅两处：
//   · 新增 sort 查询参数（latest|hot；hot 仅 ov 实现——cn 不感知，见契约
//     listPublicPhotos sort 描述）。非法取值 400 VALIDATION_FAILED（与
//     limit/cursor 同口径；locale 仍保持「非法值静默回退」的 Task 5 决策）；
//   · 服务层读 ov 副本（PublicOvService）。
// limit/cursor 规整直接复用 cn public.controller 的解析函数（缺省 30、1..60、
// cursor 长度上限）——两入口共享同一套校验源，杜绝漂移。匿名访问（无
// SessionGuard；认证由持有 publicToken 取代）。
import { Controller, Get, Param, Query } from '@nestjs/common';
// limit 规整复用 cn public.controller 的导出（同一校验源，杜绝两入口漂移）。
import { parsePublicPhotoLimit } from '../public/public.controller';
import { parseCursor } from '../shared/pagination';
import { validationFailed } from '../albums/support';
import {
  type PublicAlbumResponse,
  type PublicPhotoDetailResponse,
  type PublicPhotoListResponse,
  PublicOvService,
} from './public-ov.service';

/** sort 查询参数解析：缺省 latest；非法 → 400（见文件头口径说明）。 */
export function parsePublicPhotoSort(
  raw: string | undefined,
): 'latest' | 'hot' {
  if (raw === undefined || raw === '') {
    return 'latest';
  }
  if (raw === 'latest' || raw === 'hot') {
    return raw;
  }
  throw validationFailed('sort 必须是 latest 或 hot');
}

@Controller('public/albums')
export class PublicOvController {
  constructor(private readonly publicService: PublicOvService) {}

  /** 公开相册信息：locale 缺省/非法/无条目均按 defaultLocale 回退（200）。 */
  @Get(':token')
  getPublicAlbum(
    @Param('token') token: string,
    @Query('locale') locale: string | undefined,
  ): Promise<PublicAlbumResponse> {
    return this.publicService.getPublicAlbum(token, locale);
  }

  /**
   * 公开照片列表：latest=(publishedAt,photoId) 键集游标（缺省）；hot=点赞
   * 快照 offset 游标（30s 缓冲，服务层语义）。category 限本册分类。
   */
  @Get(':token/photos')
  listPublicPhotos(
    @Param('token') token: string,
    @Query('category') category: string | undefined,
    @Query('locale') locale: string | undefined,
    @Query('cursor') cursor: string | undefined,
    @Query('limit') limit: string | undefined,
    @Query('sort') sort: string | undefined,
  ): Promise<PublicPhotoListResponse> {
    return this.publicService.listPublicPhotos(token, {
      category,
      // locale 仅保证「不因非法值报 400」，列表无语言敏感字段，不向下传。
      cursor: parseCursor(cursor),
      limit: parsePublicPhotoLimit(limit),
      sort: parsePublicPhotoSort(sort),
    });
  }

  /**
   * 公开单图：深链定位；隐藏/删除/换册后的旧链接 404 PHOTO_NOT_PUBLIC。
   * 每次调用现签 thumb/browse（契约规定的过期刷新入口）。
   */
  @Get(':token/photos/:photoId')
  getPublicPhoto(
    @Param('token') token: string,
    @Param('photoId') photoId: string,
  ): Promise<PublicPhotoDetailResponse> {
    return this.publicService.getPublicPhoto(token, photoId);
  }
}