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 및 의존성 관리

명시적 Import 사용 (와일드카드 및 FQCN 지양)
- 인라인 타입(예: com.srsystem.listener.NotificationPublisher) 작성을 지양하고, 파일 상단에 명시적인 import 문을 선언합니다.
- 와일드카드 import(import com.srsystem.entity.*) 대신 필요한 클래스를 개별 import합니다.
새로운 클래스/DTO/Enum 참조 시 3단계 점검
- ① 파일 상단 import 선언 확인
- ② 클래스 내 필드 주입 및 생성자 파라미터 타입 일치 확인
- ③ @RequiredArgsConstructor 사용 시 final 키워드 선언 확인
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 또는 아래 명령어를 실행하여 사전 빌드 검증을 완료합니다.

$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 완료 여부 확인

2.5 KiB Raw Blame History