Merge pull request #55 from junotb/refactor/2026-02-15-2

refactor: LessonFeedback 제거 및 ScheduleFeedback·lesson 구조로 전환

Author: junotb

README.md

@@ -0,0 +1,88 @@
+# 1:1 Course Registration System (LMS)
+
+1:1 과외·튜터링 기반 Learning Management System (LMS). 높은 동시성을 고려한 수강 신청 및 수업 관리 Monorepo입니다.
+
+## 프로젝트 배경
+
+이전 시스템에서는 튜터 가용성을 **사전 생성된 Time Block(행) INSERT** 방식으로 관리했습니다. 이 접근은 다음 위험을 내포했으며, 현 프로젝트에서 이를 해결하고자 합니다.
+
+- **스토리지 급증**: 튜터 수 × 시간슬롯 × 기간에 비례해 행 수가 선형 증가 (예: 1,000명 × 16개월 ≈ 2,300만 행)
+- **동기화 위험**: 근무조건·휴식·오버타임·수업·공휴일 등 진실 소스가 분산되어 있어, 변경 시 재동기화가 누락되면 불일치 발생
+- **오래된 데이터**: 강사가 근무시간을 10~17시로 변경했는데, 가용 슬롯은 9~18시 기준으로 노출 → 잘못된 예약 또는 기회 손실
+- **가용 기간 계속 넓히기 부담**: 16개월치 가용 슬롯을 앞으로 밀어가며 유지하는 배치에 의존, 실패 시 공백
+- **동시성·재계산 비용**: 대량 UPDATE와 예약 트랜잭션 경합, 재배치 시 DB 부하 급증
+
+본 프로젝트는 **TeacherAvailability(가용 시간)·TeacherTimeOff(휴무)·Schedule(수업)** 기반으로 가용성을 조회 시점에 계산하는 모델을 채택하여, 사전 INSERT·동기화·가용 기간 유지 배치 의존을 줄이고 일관성을 확보합니다.
+
+## 프로젝트 성과
+
+| 구분 | 이전 시스템 | 이번 프로젝트 |
+|------|-------------|---------------|
+| **스토리지** | 튜터 수 × 슬롯 × 기간에 비례해 수백만 행 증가 | 가용 시간·휴무·수업만 저장, 행 수 최소화 |
+| **동기화** | 근무조건·휴식·수업 등 다수 소스 재동기화 필요 | 조회 시점 계산으로 재동기화 불필요 |
+| **오래된 데이터** | 강사 근무시간 변경 후 재배치 미실행 시 가용 슬롯이 구버전 유지 | 조회 시점에 TeacherAvailability 기준 계산으로 항상 최신 가용성 노출 |
+| **가용 기간 유지** | 16개월치를 앞으로 밀어가는 배치 유지, 실패 시 공백 | 기간 제한 없이 필요 시점 계산 |
+| **동시성** | 대량 UPDATE와 예약 트랜잭션 경합 | Redis 분산 락으로 수강 신청 경합만 관리 |
+| **운영** | 재배치·일별 확장 배치 의존 | 관련 배치 제거로 운영 부담 감소 |
+
+## 프로젝트 구조
+
+```
+next-java-lms/
+├── api/          # Spring Boot 백엔드 (Java 21)
+├── web/          # Next.js 프론트엔드 (React 19)
+└── docs/         # 프로젝트 문서
+```
+
+## Tech Stack
+
+| 구분 | 기술 |
+|------|------|
+| Backend | Spring Boot 3.3.3, Java 21, JPA, PostgreSQL |
+| Frontend | Next.js 15.5, React 19, TypeScript |
+| 인증 | Better-Auth (Web), Session (API) |
+| 동시성 | Redis (Redisson Distributed Lock) |
+| API 문서 | SpringDoc OpenAPI (Swagger) |
+
+## 사전 요구사항
+
+- **Java 21** (JDK)
+- **Node.js 20+** (LTS 권장)
+- **PostgreSQL** 14+
+- **Redis** 7+
+- **Gradle** (Wrapper 포함)
+
+## 빠른 시작
+
+### 1. 백엔드 실행
+
+```bash
+cd api
+./gradlew bootRun
+```
+
+- API: `http://localhost:8080`
+- Swagger UI: `http://localhost:8080/swagger-ui.html`
+
+### 2. 프론트엔드 실행
+
+```bash
+cd web
+npm install
+npm run dev
+```
+
+- Web: `http://localhost:3000`
+
+### 3. 환경 변수
+
+- `api/`: `.env` 또는 시스템 환경 변수 (`DB_URL`, `REDIS_URL`, `CORS_ALLOWED_ORIGINS` 등)
+- `web/`: `.env.local` (Better-Auth, API URL 등)
+
+## 주요 기능
+
+- **관리자**: 강좌·사용자·수업 일정 관리
+- **강사**: 대시보드, 수업 예정 조회, 가용 시간·휴무 설정
+- **학생**: 수강 신청, 대시보드, 수업방 진입
+- **수업 피드백**: 녹화본 업로드, AI 피드백 (VTT, Google Gemini)
+

api/README.md

@@ -0,0 +1,76 @@
+# API (Backend)
+
+Spring Boot 기반 REST API. 1:1 수강 신청, 수업 관리, 수업 피드백 등을 처리합니다.
+
+## Tech Stack
+
+| 항목 | 기술 |
+|------|------|
+| Framework | Spring Boot 3.3.3 |
+| Language | Java 21 |
+| Build | Gradle (Kotlin DSL) |
+| DB | PostgreSQL (Production), H2 (Test) |
+| ORM | JPA / Hibernate |
+| Security | Spring Security + 커스텀 인증 필터 |
+| Concurrency | Redisson (Distributed Lock) |
+| API Docs | SpringDoc OpenAPI (Swagger) |
+| Utils | Lombok, Commons Lang3 |
+
+## 프로젝트 구조
+
+```
+api/src/main/java/org/junotb/api/
+├── auth/           # 세션·인증
+├── common/         # 예외 처리, Security Filter
+├── config/         # Security, Web, Redis, OpenAPI
+├── course/         # 강좌
+├── dashboard/      # 강사/학생 대시보드
+├── lesson/         # 수업방(세션) API
+├── registration/   # 수강 신청
+├── schedule/       # 수업 일정
+├── schedulefeedback/ # 수업 피드백 (녹화·AI)
+├── teacher/        # 강사 설정·가용 시간
+├── user/           # 사용자 관리
+└── LmsApplication.java
+```
+
+## 실행 방법
+
+```bash
+# Gradle Wrapper 사용
+./gradlew bootRun
+
+# 특정 포트 지정
+PORT=8081 ./gradlew bootRun
+```
+
+## 환경 변수
+
+| 변수 | 설명 | 기본값 |
+|------|------|--------|
+| `PORT` | 서버 포트 | 8080 |
+| `DB_URL` | PostgreSQL 연결 URL | jdbc:postgresql://localhost:5432/java_lms_db |
+| `DB_USERNAME` | DB 사용자 | postgres |
+| `DB_PASSWORD` | DB 비밀번호 | password |
+| `REDIS_URL` | Redis URL | redis://localhost:6379 |
+| `CORS_ALLOWED_ORIGINS` | CORS 허용 Origin | http://localhost:3000 |
+| `GOOGLE_GEMINI_API_KEY` | Gemini API 키 (AI 피드백) | - |
+| `FFMPEG_PATH` | FFmpeg 실행 경로 | ffmpeg |
+| `VIDEO_PROCESSOR_ENABLED` | 비디오 처리 활성화 | true |
+
+## API 문서
+
+- Swagger UI: `http://localhost:8080/swagger-ui.html`
+- OpenAPI JSON: `http://localhost:8080/v3/api-docs`
+
+## 테스트
+
+```bash
+./gradlew test
+```
+
+## 아키텍처
+
+- **Layered**: Controller → Service → Repository
+- **DTO**: Request/Response 분리, Entity 직접 반환 금지
+- **Concurrency**: 수강 신청 시 Redis 분산 락 또는 DB 비관적 락

api/src/main/java/org/junotb/api/config/SecurityConfig.java

@@ -35,7 +35,6 @@ public SecurityFilterChain securityFilterChain(HttpSecurity http, CorsConfigurat
                 .requestMatchers("/api/auth/refresh").authenticated() // 세션 갱신은 인증 필요
                 .requestMatchers(
                     "/api/auth/**", // 기타 인증 관련 엔드포인트는 허용
-                    "/api/dev/**",
                     "/swagger-ui/**",
                     "/v3/api-docs/**",
                     "/swagger-ui.html",

api/src/main/java/org/junotb/api/global/dev/DevController.java

@@ -4,9 +4,9 @@
 import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.junotb.api.lesson.dto.LessonAccessResponse;
-import org.junotb.api.lessonfeedback.LessonFeedbackService;
-import org.junotb.api.lessonfeedback.dto.LessonFeedbackResponse;
-import org.junotb.api.lessonfeedback.dto.VideoUploadResponse;
+import org.junotb.api.schedulefeedback.ScheduleFeedbackService;
+import org.junotb.api.schedulefeedback.dto.ScheduleFeedbackResponse;
+import org.junotb.api.schedulefeedback.dto.VideoUploadResponse;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
@@ -22,7 +22,7 @@
 public class LessonController {
 
     private final LessonService lessonService;
-    private final LessonFeedbackService lessonFeedbackService;
+    private final ScheduleFeedbackService scheduleFeedbackService;
 
     @GetMapping("/{scheduleId}/access")
     @Operation(summary = "입장 권한 확인", description = "해당 스케줄(수업)에 대한 입장 가능 여부와 역할을 반환합니다.")
@@ -51,17 +51,17 @@ public ResponseEntity<VideoUploadResponse> uploadVideo(
         @AuthenticationPrincipal String teacherId,
         @RequestParam("file") MultipartFile file
     ) throws IOException {
-        VideoUploadResponse response = lessonFeedbackService.uploadVideo(scheduleId, teacherId, file);
+        VideoUploadResponse response = scheduleFeedbackService.uploadVideo(scheduleId, teacherId, file);
         return ResponseEntity.status(HttpStatus.CREATED).body(response);
     }
 
     @GetMapping("/{scheduleId}/feedback")
     @Operation(summary = "수업 피드백 조회", description = "해당 수업의 강사 또는 수강생이 vttContent, feedbackContent 조회.")
-    public ResponseEntity<LessonFeedbackResponse> getFeedback(
+    public ResponseEntity<ScheduleFeedbackResponse> getFeedback(
         @PathVariable Long scheduleId,
         @AuthenticationPrincipal String userId
     ) {
-        LessonFeedbackResponse response = lessonFeedbackService.getFeedback(scheduleId, userId);
+        ScheduleFeedbackResponse response = scheduleFeedbackService.getFeedback(scheduleId, userId);
         return ResponseEntity.ok(response);
     }
 }

api/src/main/java/org/junotb/api/lesson/LessonController.java

@@ -90,7 +90,7 @@ private LessonAccessResponse buildAccessResponse(boolean allowed, String role, S
         String meetLink = schedule.getMeetLink() != null ? schedule.getMeetLink() : null;
         var c = schedule.getCourse();
         if (c == null) {
-            throw new IllegalStateException("수업은 반드시 강의(Course)와 연결되어 있어야 합니다.");
+            throw new IllegalStateException("수업은 반드시 강좌(Course)와 연결되어 있어야 합니다.");
         }
         CourseInLesson course = new CourseInLesson(c.getTitle(), c.getDescription());
         return new LessonAccessResponse(allowed, role != null ? role : "", scheduleResponse, meetLink, course);

api/src/main/java/org/junotb/api/lesson/LessonService.java

@@ -1,10 +1,10 @@
 package org.junotb.api.lesson.dto;
 
 /**
- * 수업방에서 표시하는 강의 요약 정보.
+ * 수업방에서 표시하는 강좌 요약 정보.
  *
- * @param title       강의 제목
- * @param description 강의 설명 (nullable)
+ * @param title       강좌 제목
+ * @param description 강좌 설명 (nullable)
  */
 public record CourseInLesson(
     String title,

api/src/main/java/org/junotb/api/lesson/dto/CourseInLesson.java

@@ -9,7 +9,7 @@
  * @param role      TEACHER | STUDENT
  * @param schedule  스케줄 정보
  * @param meetLink  Google Meet 링크 (강사가 등록한 경우). 수업방에서 링크 전달용.
- * @param course    강의 정보 (제목, 설명). 수업방 상단 표시용.
+ * @param course    강좌 정보 (제목, 설명). 수업방 상단 표시용.
  */
 public record LessonAccessResponse(
     boolean allowed,