Merge pull request #591 from code-zero-to-one/feat/class

질문답변, 학습 여정 맵, 빌더 피드 작업

Author: HA-SEUNG-JEONG

.claude/rules/api-live-schema-check.md

@@ -0,0 +1,58 @@
+# Live API Schema Auto-Check
+
+Whenever a task touches any of the following files, **automatically** fetch and verify the live Swagger schema — no user prompt required:
+
+- `src/types/api/*.types.ts`
+- `src/hooks/queries/**/*.ts`
+- `src/api/client/*.ts`
+
+## When to Run
+
+Trigger this check at task start (before writing code), not after:
+
+- Adding or modifying a DTO interface
+- Adding or modifying a query/mutation hook
+- Reviewing a component that calls an API hook
+
+## How to Fetch
+
+Use `ctx_execute` (never `WebFetch` — blocked by hook):
+
+```javascript
+const res = await fetch('https://test-api.zeroone.it.kr/v3/api-docs');
+const api = await res.json();
+const schemas = api.components?.schemas ?? {};
+const paths = api.paths ?? {};
+```
+
+SpringDoc wraps all responses in `BaseResponse<T>` — the actual DTO is in `content.$ref`. Navigate through the wrapper to reach the real fields. When a schema has a circular `content.$ref` pointing to itself, drill into the path's `responses['200'].content['application/json'].examples` instead — the examples contain the actual field structure.
+
+## What to Compare
+
+For every DTO type being touched:
+
+| Check | How |
+|---|---|
+| Field names | Compare frontend interface keys vs backend schema properties |
+| Field types | `string`/`number`/`boolean`/`array` alignment |
+| Optionality | `?` in frontend vs `required[]` array in backend schema |
+| New fields | Backend fields absent from frontend interface → add them |
+| Removed fields | Frontend fields absent from backend → flag to user |
+| Enum values | Frontend union type vs backend `enum` array |
+
+## Reporting Format
+
+```
+DTO 비교: CourseCurriculumLessonResponse
+  ✅ lessonId, order, title, isFree, locked, estimatedMinutes
+  ❌ 누락: viewCount (backend: integer) → 추가 필요
+  ❌ 제거됨: legacyField (frontend에만 존재)
+```
+
+Report mismatches **before writing any code**. Do not silently skip unmatched fields.
+
+## Staging URLs
+
+- API docs JSON: `https://test-api.zeroone.it.kr/v3/api-docs`
+- Swagger UI:    `https://test-api.zeroone.it.kr/swagger-ui/index.html`
+- API base:      `https://test-api.zeroone.it.kr`

e2e/class/journey-map.spec.ts

@@ -13,6 +13,7 @@ const COURSE_ID = 1;
 const LESSON_FREE_ID = 101;
 const LESSON_LOCKED_ID = 102;
 const LESSON_OPTION_ID = 103;
+const LESSON_UNLOCKED_ID = 104;
 const LESSON_FREE_TITLE = '기초 세팅';
 const LESSON_OPTION_TITLE = 'Option 보너스';
 const PAGE_PATH = '/class/vibe-intro/home';
@@ -135,11 +136,73 @@ function makeCurriculum(): { content: CourseCurriculumResponse } {
   };
 }
 
-function makeJourneyMap(lessons: CourseJourneyMapLessonResponse[]): {
+function makeCurriculumWithBadges(): { content: CourseCurriculumResponse } {
+  return {
+    content: {
+      courseId: COURSE_ID,
+      durationDays: 30,
+      totalChapters: 1,
+      totalLessons: 3,
+      chapters: [
+        {
+          chapterId: 10,
+          order: 1,
+          chapterNumber: 1,
+          title: '시작하기',
+          description: null,
+          estimatedMinutes: 54,
+          lessons: [
+            {
+              lessonId: LESSON_FREE_ID,
+              order: 1,
+              title: LESSON_FREE_TITLE,
+              description: null,
+              isFree: true,
+              locked: false,
+              estimatedMinutes: 18,
+            },
+            {
+              lessonId: LESSON_LOCKED_ID,
+              order: 2,
+              title: '심화 레슨',
+              description: null,
+              isFree: false,
+              locked: true,
+              estimatedMinutes: 18,
+            },
+            {
+              lessonId: LESSON_UNLOCKED_ID,
+              order: 3,
+              title: '결제 완료 레슨',
+              description: null,
+              isFree: false,
+              locked: false,
+              estimatedMinutes: 18,
+            },
+          ],
+        },
+      ],
+    },
+  };
+}
+
+type JourneyLessonInput = Omit<
+  CourseJourneyMapLessonResponse,
+  'chapterId' | 'chapterNumber' | 'estimatedMinutes'
+> &
+  Partial<
+    Pick<
+      CourseJourneyMapLessonResponse,
+      'chapterId' | 'chapterNumber' | 'estimatedMinutes'
+    >
+  >;
+
+function makeJourneyMap(lessons: JourneyLessonInput[]): {
   content: {
     courseId: number;
     courseTitle: string;
     viewerStatus: string;
+    learnerCount: number;
     lessons: CourseJourneyMapLessonResponse[];
   };
 } {
@@ -148,7 +211,13 @@ function makeJourneyMap(lessons: CourseJourneyMapLessonResponse[]): {
       courseId: COURSE_ID,
       courseTitle: '바이브 코딩 인트로',
       viewerStatus: 'FREE_ENROLLED',
-      lessons,
+      learnerCount: 24,
+      lessons: lessons.map((l) => ({
+        chapterId: 1,
+        chapterNumber: 1,
+        estimatedMinutes: 18,
+        ...l,
+      })),
     },
   };
 }
@@ -471,6 +540,77 @@ test.describe('시작하기 내비게이션 @auth', () => {
   });
 });
 
+// ─── Chunk 4: 커리큘럼 레슨 카드 배지 렌더링 ──────────────────────────────────
+
+test.describe('커리큘럼 레슨 카드 배지 렌더링 @auth', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.route(/\/courses\//, async (route) => {
+      const url = route.request().url();
+      if (url.includes('/courses/vibe-intro/curriculum')) {
+        await route.fulfill({ json: makeCurriculumWithBadges() });
+      } else if (/\/courses\/\d+\/journey-map/.test(url)) {
+        await route.fulfill({
+          json: makeJourneyMap([
+            {
+              lessonId: LESSON_FREE_ID,
+              order: 1,
+              title: LESSON_FREE_TITLE,
+              isFree: true,
+              status: 'IN_PROGRESS',
+              isAccessible: true,
+            },
+            {
+              lessonId: LESSON_LOCKED_ID,
+              order: 2,
+              title: '심화 레슨',
+              isFree: false,
+              status: 'LOCKED',
+              isAccessible: false,
+            },
+            {
+              lessonId: LESSON_UNLOCKED_ID,
+              order: 3,
+              title: '결제 완료 레슨',
+              isFree: false,
+              status: 'IN_PROGRESS',
+              isAccessible: true,
+            },
+          ]),
+        });
+      } else if (/\/courses\/\d+\/progress/.test(url)) {
+        await route.fulfill({ json: makeProgress(0) });
+      } else if (url.includes('/courses/vibe-intro')) {
+        await route.fulfill({ json: makeCourseDetail() });
+      } else {
+        await route.continue();
+      }
+    });
+    await gotoAndWaitForData(page);
+  });
+
+  test('isFree=true → 무료 배지 표시', async ({ page }) => {
+    await expect(page.getByText('무료').first()).toBeVisible();
+  });
+
+  test('isFree=false, isAccessible=false → 잠금 배지 표시', async ({
+    page,
+  }) => {
+    await expect(page.getByRole('img', { name: '잠금' })).toBeVisible();
+  });
+
+  test('isFree=false, isAccessible=true → 잠금 해제 배지 표시', async ({
+    page,
+  }) => {
+    await expect(page.getByRole('img', { name: '잠금 해제' })).toBeVisible();
+  });
+
+  test('세 배지 동시 렌더링 — 상호 배타적', async ({ page }) => {
+    await expect(page.getByText('무료').first()).toBeVisible();
+    await expect(page.getByRole('img', { name: '잠금' })).toBeVisible();
+    await expect(page.getByRole('img', { name: '잠금 해제' })).toBeVisible();
+  });
+});
+
 test.describe('건너뛰기 내비게이션 @auth', () => {
   test('Option bonus 건너뛰기 → 다른 accessible 레슨으로 이동', async ({
     page,