box-nestjs-monorepo/apps/box-app-api/src/feature/ads/ad.controller.ts

// apps/box-app-api/src/feature/ads/ad.controller.ts
import { Controller, Get, Logger, Query } from '@nestjs/common';
import { AdService } from './ad.service';
import { GetAdPlacementQueryDto } from './dto/get-ad-placement.dto';
import { AdDto } from './dto/ad.dto';

@Controller('ads')
export class AdController {
  private readonly logger = new Logger(AdController.name);

  constructor(private readonly adService: AdService) {}

  /**
   * GET /ads/placement
   *
   * Example:
   *   /ads/placement?scene=home&slot=top&adType=BANNER
   *
   * Returns a single AdDto or null (if no suitable ad is found).
   * Your global response interceptor will wrap this into the standard envelope.
   */
  @Get('placement')
  async getAdForPlacement(
    @Query() query: GetAdPlacementQueryDto,
  ): Promise<AdDto | null> {
    const { scene, slot, adType, maxTries } = query;

    const maxTriesNum =
      maxTries != null ? Number.parseInt(maxTries, 10) || 3 : 3;

    const ad = await this.adService.getAdForPlacement({
      scene,
      slot,
      adType,
      maxTries: maxTriesNum,
    });

    // Optional logging for debugging / analytics:
    if (!ad) {
      this.logger.debug(
        `No ad returned for scene=${scene}, slot=${slot}, adType=${adType}`,
      );
    }

    // Let your global response interceptor wrap this into:
    // { status, code, data, error, timestamp, ... }
    return ad;
  }
}