docs: 컴파일 오류 예방 지침, 로컬 JDK 17 빌드 검증 스크립트 및 .geminirules 추가

2026-10-02 13:43:40 +09:00
parent 54620ff5a0
commit f41f33545a
3 changed files with 84 additions and 0 deletions
@@ -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]을 먼저 제시하고 사용자 승인을 대기합니다.
@@ -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 ..
@@ -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 완료 여부 확인