diff --git a/.geminirules b/.geminirules new file mode 100644 index 0000000..2a21112 --- /dev/null +++ b/.geminirules @@ -0,0 +1,13 @@ +# Project Rules for SR-SYSTEM + +## 1. 언어 및 커밋 규칙 +- 사용자와의 대화는 한국어로 진행합니다. +- Git 커밋 메시지는 한국어로 작성합니다. + +## 2. Java / Backend 개발 및 빌드 원칙 +- **JDK 17 경로**: `C:\DEV\jdk\jdk-17.0.0.1` +- Java 코드 수정 후 커밋/푸시 전 반드시 `$env:JAVA_HOME = "C:\DEV\jdk\jdk-17.0.0.1"; cd backend; .\gradlew.bat compileJava -x test --no-daemon`를 실행하여 컴파일 에러 유무를 사전 검증합니다. +- Java 소스 작성 시 와일드카드 import 및 FQCN 인라인 작성을 피하고, 클래스 상단에 명시적으로 `import` 구문을 작성합니다. + +## 3. 선 계획 후 코딩 (Plan-First) +- 모든 수정 및 구현 요청에 대해 코드를 작성하기 전, 반드시 [ANALYSIS & PLAN]을 먼저 제시하고 사용자 승인을 대기합니다. diff --git a/check-backend.bat b/check-backend.bat new file mode 100644 index 0000000..008f2e6 --- /dev/null +++ b/check-backend.bat @@ -0,0 +1,22 @@ +@echo off +setlocal +echo =================================================== +echo [SR-SYSTEM] Backend Build Verification (JDK 17) +echo =================================================== + +set "JAVA_HOME=C:\DEV\jdk\jdk-17.0.0.1" +set "PATH=%JAVA_HOME%\bin;%PATH%" + +cd backend +call gradlew.bat compileJava -x test --no-daemon +if %ERRORLEVEL% neq 0 ( + echo [ERROR] compileJava failed with error code %ERRORLEVEL%! + cd .. + exit /b %ERRORLEVEL% +) + +echo. +echo =================================================== +echo [SUCCESS] Backend compileJava passed successfully! +echo =================================================== +cd .. diff --git a/docs/PREVENTION_GUIDE.md b/docs/PREVENTION_GUIDE.md new file mode 100644 index 0000000..fe2cf17 --- /dev/null +++ b/docs/PREVENTION_GUIDE.md @@ -0,0 +1,49 @@ +# SR-SYSTEM 개발 및 컴파일 오류 예방 지침 (Coding & Build Guidelines) + +## 1. 개요 및 배경 +최근 서비스 클래스(`DispatchHistoryService`, `TicketService`, `ReportService` 등) 간 알림 이벤트(`NotificationPublisher`, `NotificationEvent`) 연동 과정에서 `import` 선언 누락 및 FQCN(Full Qualified Class Name) 혼용으로 인한 Docker 배포 빌드 에러(`javac exit code: 1`)가 발생했습니다. + +본 지침은 이러한 컴파일/빌드 에러를 사전에 방지하고, 로컬 환경에서 신속하게 사전 검증을 마친 후 배포할 수 있도록 표준 작업 절차를 규정합니다. + +--- + +## 2. 코드 작성 원칙 (Coding Rules) + +### 2.1 Java Import 및 의존성 관리 +1. **명시적 Import 사용 (와일드카드 및 FQCN 지양)** + - 인라인 타입(예: `com.srsystem.listener.NotificationPublisher`) 작성을 지양하고, 파일 상단에 명시적인 `import` 문을 선언합니다. + - 와일드카드 import(`import com.srsystem.entity.*`) 대신 필요한 클래스를 개별 import합니다. +2. **새로운 클래스/DTO/Enum 참조 시 3단계 점검** + - ① 파일 상단 `import` 선언 확인 + - ② 클래스 내 필드 주입 및 생성자 파라미터 타입 일치 확인 + - ③ `@RequiredArgsConstructor` 사용 시 `final` 키워드 선언 확인 +3. **Repository 쿼리 메소드 명명 규칙 준수** + - Spring Data JPA 규칙(`findBy...And...IsNull` 등)과 Entity 필드명이 정확히 일치하는지 검증합니다. + +--- + +## 3. 로컬 빌드 사전 검증 절차 (Local Verification) + +### 3.1 로컬 JDK 17 환경 설정 +- **JDK 17 경로**: `C:\DEV\jdk\jdk-17.0.0.1` +- Spring Boot 3.x는 Java 17 이상이 필수이므로, 커밋/푸시 전 항상 해당 JDK로 컴파일 검증을 실행합니다. + +### 3.2 원클릭 검증 스크립트 실행 +- 프로젝트 루트에서 `check-backend.bat` 또는 아래 명령어를 실행하여 사전 빌드 검증을 완료합니다. +```powershell +$env:JAVA_HOME = "C:\DEV\jdk\jdk-17.0.0.1" +cd backend +.\gradlew.bat compileJava -x test --no-daemon +``` + +### 3.3 검증 완료 기준 +- `BUILD SUCCESSFUL` 확인 후 Git 커밋 & 푸시 진행 + +--- + +## 4. Git 커밋 및 배포 체크리스트 + +- [ ] 수정된 Java 파일들의 상단 `import` 누락 여부 확인 +- [ ] 로컬 JDK 17 기반 `compileJava` 또는 `bootJar` 성공 여부 확인 +- [ ] Git 커밋 메시지는 한글로 명확히 작성 (예: `fix: ...`, `feat: ...`) +- [ ] Docker 배포 트리거 전 push 완료 여부 확인