learning 모듈

책임: 커리큘럼 구조, 본강의 영상 재생, 수강권 활성화, 진도 추적, 학생 정보 조회/수정.

의존:

• identity — 로그인 사용자 컨텍스트 (대부분의 엔드포인트가 인증 필요)
• catalog — course 메타데이터
• commerce — 결제 완료 시 enrollment 활성화 (이벤트 수신자)

관련 DB 테이블:

• course, unit, lesson — 커리큘럼 구조 (기존)
• lecture_apply — 수강 신청/활성화 레코드
• lecture_progress — 레슨 단위 진도 로그
• lecture_progress_total — 사용자+코스 단위 진도 집계
• member — 학생 정보 (읽기)

현재 UI 상태: 강의실의 뼈대는 DB 연동을 마쳤다.

• 커리큘럼 · 강의 영상 — src/lib/curriculum.ts 가 unit · lesson 을 읽는다. /my-class/online(36 레슨) · /my-class/tec-online(56 레슨) 의 표와 영상 모달, /my-class/lecture-video/[unit]/[lesson] 이 모두 여기서 나온다. 화면에 있던 units · videoData 배열은 없앴다.

  • 이관하며 TESOL UNIT2 의 첫 레슨("What makes a Good Teacher?")이 화면 목록에서 빠져 있던 버그가 드러나 함께 고쳐졌다. 원본 _lib/_exam.php:83 기준 3 개가 맞다.

• Quiz 칸 — quiz_result 를 읽어 점수 링크 또는 다음 차수 응시 버튼을 그린다(원본 myOnlineClass.php:113~135).

• 성적표 — /my-class/result-of-course · /my-class/tec-result-of-course 가 getCourseResult() 로 계산한다. 통과한 유닛만 점수가 잡히고 Unit Total 은 그 평균이다(원본 resultOfCourse.php:99~143).

• 학생 정보 — /my-class/student-information · /my-class/tec-student-information 이 src/lib/student.ts 로 member 를 읽는다. 입학확인증 행은 결제+준비완료, 스캔본 행은 거기에 사이버승인+합격까지 만족해야 보인다(원본 studentInformation.php:87,98). 비밀번호·이름 변경 폼은 원본에도 있던 목업이라 그대로 두고, 동작하지 않는다는 안내만 붙였다.

남은 하드코딩:

• course-outline — 원본(courseOutline.php)도 정적 HTML 이고, 이 화면의 본체인 카테고리("언어 듣기" 등)와 교재 이미지 파일명이 DB 에 없다. 유닛·레슨명만 DB 로 바꾸면 한 화면이 두 소스로 쪼개지므로 그대로 두었다. 현재 값은 DB(36 레슨)와 일치한다.
• 진도(lecture_progress) — 데이터는 55,060 건 있지만 원본에서도 수강생 화면이 쓰지 않는다. 관리자 화면(admin/member/timeline_detail.php)과 통계 전용이다. 수강생 쪽에 붙이려면 영상 시청 추적을 새로 만드는 일이 된다.

예상 API 엔드포인트

수강 목록

GET /api/learning/my-classes

로그인 사용자가 현재 수강 가능한 강의 목록.

• Auth: 필수 (member)
• Query: 없음
• Response:

  {
    items: Array<{
      courseCode: string;   // 'TESOL' | 'TEC' | 'PHONICS' | 'TEACHING'
      courseName: string;
      isActive: boolean;    // lecture_apply.status 기반
      startedAt: string | null;
      endsAt: string | null;
      professor: string;    // 하드코딩 메타 or 별도 테이블
      unitCount: number;
      progressPct: number;  // 0..100 from lecture_progress_total
    }>
  }
  

• 쿼리 대상: lecture_apply WHERE member_id= AND status IN ('active','pending')
• 대체 대상 페이지: /my-class (현재 하드코딩된 classes 배열)

커리큘럼/강의 구조

GET /api/learning/courses/[courseCode]/outline

특정 강의의 단원+레슨 아웃라인 (수강생용).

• Auth: 필수. lecture_apply 로 수강권 검증.
• Response:

  {
    course: { code, name, name_kr };
    units: Array<{
      unitNumber: number;
      title: string;
      lessons: Array<{
        lessonNumber: number;
        title: string;
        durationSec?: number;
      }>;
    }>;
  }
  

• 대체 대상: /my-class/course-outline (현재 courseUnits 하드코딩)

GET /api/learning/courses/[courseCode]/units

모듈/유닛 목록 (간략). course outline 의 경량 버전.

• Response: { units: Array<{ unitNumber, title, lessonCount }> }
• 대체 대상: /my-class/online (현재 units 하드코딩)

레슨 영상 재생

GET /api/learning/lessons/[lessonId]

개별 레슨 상세 (Vimeo 영상 URL 포함).

• Auth: 필수. lesson → unit → course → lecture_apply 체인으로 수강권 검증.
• Response:

  {
    id: number;
    title: string;
    content: string | null;
    vimeoId: string | null;
    vimeoUrl: string | null;
    unitNumber: number;
    lessonNumber: number;
  }
  

• 주의: vimeo_url 은 expiring signed URL 방식으로 감싸는 것을 권장 (도메인 제한만으로는 부족).

진도 추적

POST /api/learning/progress

레슨 시청 진도 업데이트.

• Auth: 필수
• Body:

  {
    lessonId: number;
    watchedSec: number;
    completed: boolean;   // 사용자가 명시적 "완료" 체크 or 일정 비율 이상
  }
  

• Response: { ok: true, progressPct: number }
• 사이드이펙트:
  • lecture_progress INSERT/UPDATE (lesson 단위)
  • lecture_progress_total UPSERT (course 단위 집계 재계산)

GET /api/learning/progress/me?courseCode=TESOL

특정 강의의 내 진도 상세.

• Auth: 필수
• Response:

  {
    totalLessons: number;
    completedLessons: number;
    progressPct: number;
    perUnit: Array<{ unitNumber: number; completed: number; total: number }>;
  }
  

수강 등록

POST /api/learning/enrollments

수강권 활성화. 보통 commerce 모듈의 결제 완료 훅에서 내부 호출.

• Auth: 필수 (내부 서비스 토큰 or 세션)
• Body:

  {
    memberId: number;
    courseCode: string;
    source: 'payment' | 'admin' | 'free';
    orderId?: number;    // commerce.order 참조
    periodDays?: number; // 기본 365
  }
  

• Response: { enrollmentId: number, activeUntil: string }
• 사이드이펙트: lecture_apply INSERT, notification 모듈에 "수강 시작" 이벤트 발행

학생 정보

GET /api/learning/student-info/me

/my-class/student-information 페이지용 집계 데이터.

• Auth: 필수
• Response:

  {
    profile: {
      loginId: string;
      name: string;
      email: string;
      phone: string;
    };
    enrollments: Array<{
      courseCode: string;
      examPeriod: { start: string; end: string };
      paid: boolean;
      passed: boolean;
      passedAt: string | null;
      certificateIssued: boolean;
    }>;
  }
  

• 대체 대상: /my-class/student-information (현재 personalInfo 하드코딩)
• 쿼리 대상: member + lecture_apply + (commerce.payment) + (assessment.quiz_result) 조인

PATCH /api/learning/student-info/me/password

비밀번호 변경. /my-class/student-information 페이지의 비밀번호 폼에서 호출.

• Auth: 필수
• Body: { current: string, next: string }
• 사이드이펙트: member.pw 업데이트, bcrypt 해싱, notification 에 "비밀번호 변경" 이벤트 발행