chore: 릴리즈 — 검색 화면 API 4건

package.json

@@ -48,6 +48,7 @@
     "@nestjs/jwt": "^11.0.2",
     "@nestjs/passport": "^11.0.5",
     "@nestjs/platform-express": "11.2.1",
+    "@nestjs/schedule": "^6.1.3",
     "@nestjs/serve-static": "^5.0.5",
     "@nestjs/swagger": "^11.4.7",
     "@prisma/client": "^6.19.3",

prisma/migrations/20260830181501_add_search_keyword_rank_snapshot/migration.sql

@@ -0,0 +1,13 @@
+-- CreateTable
+CREATE TABLE `search_keyword_rank_snapshot` (
+    `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+    `ranked_at` DATETIME(3) NOT NULL,
+    `rank` SMALLINT UNSIGNED NOT NULL,
+    `keyword` VARCHAR(200) NOT NULL,
+    `search_count` INTEGER UNSIGNED NOT NULL,
+    `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+
+    INDEX `idx_search_keyword_rank_snapshot_ranked_at`(`ranked_at`),
+    UNIQUE INDEX `uk_search_keyword_rank_snapshot`(`ranked_at`, `rank`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

prisma/migrations/20260830183130_add_banner_placement_search/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE `banner` MODIFY `placement` ENUM('HOME_MAIN', 'HOME_SUB', 'CATEGORY', 'STORE', 'SEARCH') NOT NULL DEFAULT 'HOME_MAIN';

prisma/schema.prisma

@@ -90,6 +90,7 @@ enum BannerPlacement {
   HOME_SUB
   CATEGORY
   STORE
+  SEARCH // 검색 진입 화면 인기 검색어 아래 배너 슬롯(figma search 05)
 }
 
 enum BannerLinkType {
@@ -1246,6 +1247,27 @@ model SearchEvent {
   @@map("search_event")
 }
 
+/**
+ * 인기 검색어 시간별 스냅샷(검색 진입 화면 TOP10 + 순위 변동).
+ * 매시 정각 크론이 직전 24h SearchEvent를 keyword별 집계해 TOP20을 저장한다.
+ * 불변 로그 성격이라 soft-delete(deleted_at)를 두지 않는다(보관 무제한 — 사용자 확정).
+ */
+model SearchKeywordRankSnapshot {
+  id BigInt @id @default(autoincrement()) @db.UnsignedBigInt
+
+  // 정각(시 단위 절삭) 기준 시각. 같은 ranked_at은 1회만 생성(멱등)
+  ranked_at    DateTime @db.DateTime(3)
+  rank         Int      @db.UnsignedSmallInt
+  keyword      String   @db.VarChar(200)
+  search_count Int      @db.UnsignedInt
+
+  created_at DateTime @default(now()) @db.DateTime(3)
+
+  @@unique([ranked_at, rank], map: "uk_search_keyword_rank_snapshot")
+  @@index([ranked_at], map: "idx_search_keyword_rank_snapshot_ranked_at")
+  @@map("search_keyword_rank_snapshot")
+}
+
 /**
  * =========================
  * 12) Banner

prisma/seed.ts

@@ -11,6 +11,7 @@
  */
 import { PrismaClient } from '@prisma/client';
 
+import { seedBanners } from './seed/banners';
 import { seedCategories } from './seed/categories';
 import { seedCustomDrafts } from './seed/custom-drafts';
 import { resetSeedScope } from './seed/idempotent';
@@ -19,6 +20,7 @@ import { seedOrders } from './seed/orders';
 import { seedRecentViews } from './seed/recent-views';
 import { seedRegions } from './seed/regions';
 import { seedReviews } from './seed/reviews';
+import { seedSearchEvents } from './seed/search-events';
 import { seedSearchHistory } from './seed/search-history';
 import { seedStores } from './seed/stores';
 import { seedUsers } from './seed/users';
@@ -67,6 +69,12 @@ async function main(): Promise<void> {
     log('검색 히스토리 시드 중...');
     await seedSearchHistory(prisma, { users });
 
+    log('검색 이벤트 + 인기 검색어 스냅샷 시드 중...');
+    await seedSearchEvents(prisma, { users });
+
+    log('배너 시드 중...');
+    await seedBanners(prisma);
+
     log('완료. 발급된 테스트 계정:');
     for (const u of users) {
       const status =

prisma/seed/banners.ts

@@ -0,0 +1,20 @@
+/**
+ * 배너 시드(검색 진입 화면 SEARCH 지면 1건).
+ * title을 SEED_BANNER_TITLE_PREFIX로 시작시켜 resetSeedScope가 자기 영역만 정리한다.
+ * 링크는 NONE — 시드 매장/상품 FK에 묶이지 않아 재시드 순서와 무관하다.
+ */
+import type { PrismaClient } from '@prisma/client';
+
+import { SEED_BANNER_TITLE_PREFIX } from './idempotent';
+
+export async function seedBanners(prisma: PrismaClient): Promise<void> {
+  await prisma.banner.create({
+    data: {
+      placement: 'SEARCH',
+      title: `${SEED_BANNER_TITLE_PREFIX}검색 진입 배너`,
+      image_url: 'https://picsum.photos/seed/caquick-search/750/220',
+      link_type: 'NONE',
+      sort_order: 0,
+    },
+  });
+}

prisma/seed/idempotent.ts

@@ -4,6 +4,7 @@
  * 시드는 다음 식별자들로만 자기 영역을 구분한다:
  *   - 유저 이메일: SEED_USER_EMAIL_PREFIX (`seed-user-`)
  *   - 매장 이름:    SEED_STORE_NAME_PREFIX (`[SEED] `)
+ *   - 배너 제목:    SEED_BANNER_TITLE_PREFIX (`[SEED] `)
  *
  * 정리 시 위 prefix에 매칭되는 row와 그 종속 데이터(주문/리뷰/찜/...)를
  * 삭제한 뒤 다시 삽입하므로, 수동으로 만든 다른 데이터는 보존된다.
@@ -12,8 +13,14 @@ import type { PrismaClient } from '@prisma/client';
 
 export const SEED_USER_EMAIL_PREFIX = 'seed-user-';
 export const SEED_STORE_NAME_PREFIX = '[SEED] ';
+export const SEED_BANNER_TITLE_PREFIX = '[SEED] ';
 
 export async function resetSeedScope(prisma: PrismaClient): Promise<void> {
+  // 배너(링크 NONE, FK 없음)
+  await prisma.banner.deleteMany({
+    where: { title: { startsWith: SEED_BANNER_TITLE_PREFIX } },
+  });
+
   const seedUsers = await prisma.account.findMany({
     where: { email: { startsWith: SEED_USER_EMAIL_PREFIX } },
     select: { id: true },
@@ -116,6 +123,11 @@ export async function resetSeedScope(prisma: PrismaClient): Promise<void> {
       where: { account_id: { in: userIds } },
     });
 
+    // 검색 집계 이벤트(시드 유저 소유분만) — 스냅샷은 파생 캐시라 seedSearchEvents가 전량 재생성
+    await prisma.searchEvent.deleteMany({
+      where: { account_id: { in: userIds } },
+    });
+
     // 카트
     const userCarts = await prisma.cart.findMany({
       where: { account_id: { in: userIds } },

prisma/seed/search-events.ts

@@ -0,0 +1,86 @@
+/**
+ * 검색 집계 이벤트 + 인기 검색어 스냅샷 시드(검색 진입 화면 검증용).
+ *
+ * - 이벤트는 시드 유저 소유(account_id)로만 만들어 resetSeedScope가 유저 기준으로 정리한다.
+ * - 스냅샷은 시드가 쓰는 두 정각(직전·현재)만 지우고 재생성한다 — 다른 시각대의
+ *   기존 스냅샷은 시드 데이터가 아니므로 보존한다(릴리즈 리뷰 반영).
+ *   순위 변동 UP/DOWN/SAME/NEW가 모두 보이도록 구성.
+ */
+import type { PrismaClient } from '@prisma/client';
+
+import type { SeededUser } from './users';
+
+const HOUR_MS = 60 * 60 * 1000;
+
+const PREVIOUS_RANKING = [
+  '과일 케이크',
+  '생일 케이크',
+  '크리스마스',
+  '3d',
+  '강아지 케이크',
+  '생화 케이크',
+  '떡 케이크',
+  '연인',
+  '미니 케이크',
+  '기념일 케이크',
+  '레터링 케이크',
+] as const;
+
+/** 현재 정각 기준 순위(검색 횟수 desc). 직전 대비 UP/DOWN/SAME/NEW 혼합. */
+const CURRENT_RANKING: { keyword: string; count: number }[] = [
+  { keyword: '생일 케이크', count: 12 }, // 2 → 1 UP
+  { keyword: '과일 케이크', count: 11 }, // 1 → 2 DOWN
+  { keyword: '크리스마스', count: 9 }, // SAME
+  { keyword: '3d', count: 8 }, // SAME
+  { keyword: '강아지 케이크', count: 7 }, // SAME
+  { keyword: '생화 케이크', count: 6 }, // SAME
+  { keyword: '떡 케이크', count: 5 }, // SAME
+  { keyword: '연인', count: 4 }, // SAME
+  { keyword: '미니 케이크', count: 3 }, // SAME
+  { keyword: '도넛', count: 2 }, // NEW
+  { keyword: '기념일 케이크', count: 1 }, // 10 → 11 DOWN
+];
+
+export async function seedSearchEvents(
+  prisma: PrismaClient,
+  ctx: { users: SeededUser[] },
+): Promise<void> {
+  const user1 = ctx.users[0];
+  if (!user1) throw new Error('seedUsers must run before seedSearchEvents');
+
+  const now = Date.now();
+  const rankedAt = new Date(Math.floor(now / HOUR_MS) * HOUR_MS);
+  const previousAt = new Date(rankedAt.getTime() - HOUR_MS);
+
+  // 현재 정각 스냅샷 윈도우([rankedAt-24h, rankedAt)) 안에 count만큼 이벤트를 심는다
+  await prisma.searchEvent.createMany({
+    data: CURRENT_RANKING.flatMap(({ keyword, count }) =>
+      Array.from({ length: count }, (_, i) => ({
+        account_id: user1.id,
+        keyword,
+        context: 'GLOBAL' as const,
+        created_at: new Date(rankedAt.getTime() - (i + 1) * 10 * 60 * 1000),
+      })),
+    ),
+  });
+
+  await prisma.searchKeywordRankSnapshot.deleteMany({
+    where: { ranked_at: { in: [previousAt, rankedAt] } },
+  });
+  await prisma.searchKeywordRankSnapshot.createMany({
+    data: [
+      ...PREVIOUS_RANKING.map((keyword, i) => ({
+        ranked_at: previousAt,
+        rank: i + 1,
+        keyword,
+        search_count: PREVIOUS_RANKING.length - i,
+      })),
+      ...CURRENT_RANKING.map(({ keyword, count }, i) => ({
+        ranked_at: rankedAt,
+        rank: i + 1,
+        keyword,
+        search_count: count,
+      })),
+    ],
+  });
+}

src/app.module.ts

@@ -11,6 +11,7 @@ import {
 } from '@nestjs/common';
 import { ConfigModule, ConfigService } from '@nestjs/config';
 import { GraphQLModule } from '@nestjs/graphql';
+import { ScheduleModule } from '@nestjs/schedule';
 import { ServeStaticModule } from '@nestjs/serve-static';
 import type { Request, Response } from 'express';
 
@@ -23,6 +24,7 @@ import s3Config from '@/config/s3.config';
 import { AuthModule } from '@/features/auth/auth.module';
 import { PickupModule } from '@/features/pickup';
 import { RegionModule } from '@/features/region';
+import { SearchModule } from '@/features/search/search.module';
 import { SellerModule } from '@/features/seller/seller.module';
 import { StoreModule } from '@/features/store';
 import { SystemModule } from '@/features/system/system.module';
@@ -56,6 +58,8 @@ import { PrismaModule } from '@/prisma';
     AuthGlobalModule,
     GraphqlGlobalModule,
     StorageModule,
+    // 인기 검색어 스냅샷 크론(SearchModule) 활성화
+    ScheduleModule.forRoot(),
     GraphQLModule.forRootAsync<ApolloDriverConfig>({
       driver: ApolloDriver,
       inject: [ConfigService],
@@ -90,6 +94,7 @@ import { PrismaModule } from '@/prisma';
     AuthModule,
     PickupModule,
     RegionModule,
+    SearchModule,
     StoreModule,
     UserModule,
     SellerModule,

src/common/utils/search-keyword.spec.ts

@@ -0,0 +1,77 @@
+import { BadRequestException } from '@nestjs/common';
+
+import {
+  normalizeSearchKeyword,
+  parseSearchKeyword,
+  SEARCH_KEYWORD_MAX_LENGTH,
+  splitSearchWords,
+} from '@/common/utils/search-keyword';
+
+describe('search-keyword utils', () => {
+  describe('normalizeSearchKeyword', () => {
+    it('앞뒤 공백을 제거하고 연속 공백을 하나로 축약한다', () => {
+      expect(normalizeSearchKeyword('  딸기   케이크\t\n')).toEqual({
+        ok: true,
+        keyword: '딸기 케이크',
+      });
+    });
+
+    it('1글자 검색어를 허용한다', () => {
+      expect(normalizeSearchKeyword('a')).toEqual({ ok: true, keyword: 'a' });
+    });
+
+    it('공백만 있으면 EMPTY로 거절한다', () => {
+      expect(normalizeSearchKeyword('   ')).toEqual({
+        ok: false,
+        reason: 'EMPTY',
+      });
+    });
+
+    it('길이는 코드 포인트 기준이다(이모지 200개는 허용, 201개는 거절)', () => {
+      expect(
+        normalizeSearchKeyword('😀'.repeat(SEARCH_KEYWORD_MAX_LENGTH)).ok,
+      ).toBe(true);
+      expect(
+        normalizeSearchKeyword('😀'.repeat(SEARCH_KEYWORD_MAX_LENGTH + 1)),
+      ).toEqual({ ok: false, reason: 'TOO_LONG' });
+    });
+
+    it('정규화 후 200자를 넘으면 TOO_LONG으로 거절한다', () => {
+      const raw = 'a'.repeat(SEARCH_KEYWORD_MAX_LENGTH + 1);
+      expect(normalizeSearchKeyword(raw)).toEqual({
+        ok: false,
+        reason: 'TOO_LONG',
+      });
+      expect(
+        normalizeSearchKeyword(`  ${'a'.repeat(SEARCH_KEYWORD_MAX_LENGTH)}  `)
+          .ok,
+      ).toBe(true);
+    });
+  });
+
+  describe('splitSearchWords', () => {
+    it('공백 기준으로 나누고 중복 단어를 제거한다', () => {
+      expect(splitSearchWords('딸기 케이크 딸기')).toEqual(['딸기', '케이크']);
+    });
+
+    it('단어 하나면 그대로 반환한다', () => {
+      expect(splitSearchWords('레터링')).toEqual(['레터링']);
+    });
+  });
+
+  describe('parseSearchKeyword', () => {
+    it('정규화된 검색어와 단어 목록을 함께 돌려준다', () => {
+      expect(parseSearchKeyword(' 딸기  케이크 ')).toEqual({
+        keyword: '딸기 케이크',
+        words: ['딸기', '케이크'],
+      });
+    });
+
+    it('빈 검색어·길이 초과는 400', () => {
+      expect(() => parseSearchKeyword(' ')).toThrow(BadRequestException);
+      expect(() => parseSearchKeyword('a'.repeat(201))).toThrow(
+        BadRequestException,
+      );
+    });
+  });
+});