## 백엔드 코드 리뷰 규칙

이 문서는 `[DSP-BE] 개발 가이드`와 `NXL_개발표준정의서(BE)_v1.6`의 공통 기준을 `ju-hong-e` 리뷰 프롬프트용으로 재구성한 규칙이다.

문서 간 충돌이 있으면 아래 우선순위를 따른다.

1. 현재 프로젝트 구현 계약
2. `[DSP-BE] 개발 가이드`
3. `NXL_개발표준정의서(BE)`

### 언어

- 모든 답변은 한국어로 작성한다.

### 리뷰 우선순위

- 아래 순서로 문제가 있는지 먼저 확인한다.
  1. 계층 책임 위반
  2. API 계약 위반
  3. 예외/응답/트랜잭션 위반
  4. 개인정보/로그/보안 위반
  5. 명명/패키지/포맷팅 위반

### 아키텍처 / 계층 책임

- Controller는 요청/응답 매핑과 위임만 담당하고, 비즈니스 로직을 직접 구현하지 않는지 체크한다.
- Service는 단일 책임 원칙을 지키며 비즈니스 흐름과 조합을 담당하는지 체크한다.
- DTO는 계층 간 전달 객체로만 사용하고, 비즈니스 로직이나 영속성 책임이 섞이지 않는지 체크한다.
- Entity를 외부 응답 모델로 직접 노출하지 않는지 체크한다.
- Repository는 영속성 접근 책임만 가지는지 체크한다.
- 복잡한 쿼리 로직이 Controller나 Service에 직접 박혀 있지 않은지 체크한다.

### 패키지 / 명명 규칙

- 프로젝트/모듈 명이 조직 표준 케밥 표기법과 현재 저장소 관례를 크게 벗어나지 않는지 체크한다.
- 패키지는 영문 소문자만 사용하고, 도메인 기준으로 구성하는지 체크한다.
- 패키지명에 camelCase, 대문자, 언더스코어, 불필요한 하이픈이 섞여 있지 않은지 체크한다.
- 역할 패키지(`controller`, `service`, `domain`, `infrastructure`)가 책임에 맞게 분리되어 있는지 체크한다.
- 클래스명은 PascalCase인지 체크한다.
- 메서드명은 lowerCamelCase이며 동사로 시작하는지 체크한다.
- Boolean 메서드/변수는 `is`, `has`, `can` 접두사를 우선하는지 체크한다.
- 약어도 일반 Camel/Pascal 규칙을 따르는지 체크한다. 예: `HttpUrlConnection`
- DTO/Entity/Repository/Controller/Service 접미사가 역할에 맞게 사용되는지 체크한다.
- 메서드명에 한글을 사용하지 않는지 체크한다. 단, 테스트 메서드는 프로젝트 관례에 따라 예외 가능성을 고려한다.
- 숫자만 다른 클래스/메서드명을 관성적으로 늘리지 않았는지 체크한다.

### Controller 규칙

- `@RestController` 기반 응답 구조를 사용하고 있는지 체크한다.
- `@RequestBody`, `@ModelAttribute`, `@RequestParam` 사용이 입력 형태와 맞는지 체크한다.
- `@GetMapping`에서는 `@RequestParam` 중심, `@PostMapping`에서는 `@RequestBody` 중심 규칙을 무너뜨리지 않았는지 체크한다.
- 입력 파라미터 수신 방식을 근거 없이 혼용하지 않았는지 체크한다.
- Controller에서 서비스 호출 외의 직접 DB 접근, 복잡한 분기, 데이터 조합이 없는지 체크한다.
- 요청/응답 모델이 명확히 분리되어 있는지 체크한다.
- 응답 계약이 프로젝트 공통 래퍼(`ApiResponse` 등)와 맞는지 체크한다.
- 조회/등록/수정/삭제 URI와 메서드 조합이 현재 프로젝트 API 규칙과 일치하는지 체크한다.

### Service 규칙

- `@RequiredArgsConstructor` + `final` 필드 기반 생성자 주입을 사용하는지 체크한다.
- 필드 주입을 사용하지 않는지 체크한다.
- Service가 단일 책임을 유지하고 있는지 체크한다.
- Service 내부에서 다른 계층 책임까지 과도하게 끌어안지 않는지 체크한다.
- 불필요한 내부 클래스, 과도한 static 유틸 패턴, 임시성 네이밍이 없는지 체크한다.
- API/앱 하위 호환성이 필요한 변경이라면 버저닝 또는 계약 유지 근거가 있는지 체크한다.

### DTO / Entity / Repository / MyBatis / JPA

- DTO 이름이 `RequestDto`, `ResponseDto`, `Dto` 등 역할 접미사를 일관되게 사용하는지 체크한다.
- DTO가 `Map`, `Object`, 비정형 구조 남발 없이 명시적 타입으로 정의되어 있는지 체크한다.
- 서비스/비즈니스 컴포넌트의 input/output, 계층 간 전달 객체가 `Map` 대신 DTO를 사용하고 있는지 체크한다.
- Lombok `@Data`를 무분별하게 사용하지 않는지 체크한다.
- 생성자 인자가 많거나 의미가 불명확한 DTO 생성에 빌더 또는 팩토리 메서드가 필요한지 체크한다.
- 개인정보 필드가 있는 DTO에 `@ToString`을 그대로 사용해 민감정보를 노출하지 않는지 체크한다.
- Entity는 `@Entity`, `@Table`, `@Column` 등 매핑 의도가 명확한지 체크한다.
- Entity에 불필요한 setter, 외부 계층용 응답 로직, 과도한 변환 로직이 섞여 있지 않은지 체크한다.
- Repository 인터페이스가 `JpaRepository` 등 표준 방식에 맞게 정의되어 있는지 체크한다.
- 쿼리가 복잡할 때 QueryDSL, Native Query, MyBatis 사용 이유가 설명 가능한지 체크한다.
- MyBatis 사용 시 Mapper 이름, SQL ID, XML 위치가 일관적인지 체크한다.
- MyBatis `INSERT` SQL에서 필요한 `jdbcType` 지정이 누락되지 않았는지 체크한다.

### API / URL 규칙

- URI는 영문 소문자 중심인지 체크한다.
- 파일 확장자, 트레일링 슬래시, 불필요한 언더스코어 사용이 없는지 체크한다.
- 리소스명은 명사형 중심인지 체크한다.
- 프로젝트 가이드에 맞는 `get/post/put/delete` 세그먼트 및 도메인 경로 규칙을 따르는지 체크한다.
- 사내 표준상 GET/POST만 허용하는 프로젝트인지, 조회 `GET + /get`, 등록 `POST + /post`, 수정 `POST + /put`, 삭제 `POST + /delete` 관례를 따라야 하는지 확인하고 위반 여부를 체크한다.
- 민감정보 조회, 대용량 조회, 웹서버 로그 노출 우려가 있는 경우 조회도 POST를 선택할 수 있음을 고려했는지 체크한다.
- 일반적인 REST 이론만으로 현재 프로젝트 URI 표준을 임의 변경하지 않았는지 체크한다.
- 목록 자원에 `-list` 또는 복수형 규칙을 일관되게 적용하는지 체크한다.

### 예외 / 응답 / HTTP Status

- 예외를 `try-catch`로 의미 없이 삼키지 않는지 체크한다.
- 비즈니스 예외와 시스템 예외를 구분하는지 체크한다.
- `BusinessException`, `DspException` 또는 프로젝트 공통 예외 체계를 일관되게 사용하는지 체크한다.
- 범용 `Exception`만 던지지 않고 의미 있는 하위 예외 또는 공통 예외 클래스를 사용하는지 체크한다.
- 리스트 단순 조회에서 데이터 없음과 실제 오류를 구분하는지 체크한다.
- 프로젝트 계약상 HTTP 200 + 내부 오류 코드/메시지 체계를 쓰는 경우, 이를 임의로 4xx/5xx 중심 계약으로 섞지 않았는지 체크한다.
- 사내 표준상 2xx, 4xx 중심 상태코드를 쓰는 프로젝트라면 그 계약을 벗어나지 않았는지 체크한다.
- 예외 메시지와 오류 코드는 계층을 넘길 때 의미가 유지되는지 체크한다.

### 트랜잭션

- 트랜잭션이 서비스 메서드 경계에 위치하는지 체크한다.
- 조회 전용 메서드에 `@Transactional(readOnly = true)` 적용이 필요한지 체크한다.
- CheckedException 롤백이 필요한데 `rollbackFor`가 빠져 있지 않은지 체크한다.
- 전파 속성(`REQUIRES_NEW`, `MANDATORY` 등)을 이유 없이 남용하지 않는지 체크한다.
- 한 트랜잭션에 무관한 작업을 과도하게 묶지 않는지 체크한다.
- CheckedException과 UncheckedException의 롤백 차이를 이해하지 못한 코드가 없는지 체크한다.

### Java 코딩 / 주석

- 의미 없는 `try-catch`, 빈 `catch`, 예외 로그만 남기고 정상 흐름처럼 숨기는 코드가 없는지 체크한다.
- 스프링 singleton 빈에 요청별 가변 상태를 담는 인스턴스 변수를 두지 않는지 체크한다.
- `import *`를 사용하지 않는지 체크한다.
- import, 들여쓰기, 중괄호, 띄어쓰기, 클래스 멤버 정렬이 프로젝트 포맷터와 충돌하지 않는지 체크한다.
- 제어문 한 줄 본문이라도 중괄호를 생략하지 않는지 체크한다.
- 메서드 상단에 사용하지도 않을 로컬 변수를 한꺼번에 미리 선언하는 패턴이 없는지 체크한다.
- `do..while` 사용이 정말 필요한지 체크한다.
- 클래스/메서드의 의도가 코드만으로 명확하지 않을 때 주석이나 문서화가 보강되어 있는지 체크한다.
- Swagger, 인터페이스, 오버라이드 등으로 설명이 대체되는 경우 불필요한 중복 주석을 강요하지 않는다.
- 주석 첫 문장이 역할 요약이 되도록 간결하게 작성되었는지 체크한다.
- 주석이 "무엇을 하는가"보다 "어떻게 구현했는가"만 장황하게 설명하지 않는지 체크한다.
- 불필요한 Javadoc 태그, 작성자명, 날짜, 변경이력 나열이 남아 있지 않은지 체크한다.
- 주석 처리된 죽은 코드, 오래된 TODO, 구현과 맞지 않는 주석이 남아 있지 않은지 체크한다.

### 로깅 / 개인정보 / 보안

- 로그 레벨이 목적에 맞는지 체크한다.
  - `DEBUG`: 개발 디버깅
  - `INFO`: 일반 흐름/운영 확인
  - `WARN`: 비즈니스 오류/검증 실패
  - `ERROR`: 시스템 오류/예상하지 못한 예외
- `System.out.println()` 등 비표준 출력으로 로그를 남기지 않는지 체크한다.
- 운영 코드에 불필요한 디버깅 로그가 남아 있지 않은지 체크한다.
- TRACE/DEBUG 로그는 필요한 경우 레벨 체크와 함께 사용하고 있는지 체크한다.
- Logger가 클래스 내부에서 일관된 방식(`private final`, `@Slf4j` 등)으로 선언되어 있는지 체크한다.
- 로그 호출 인자로 비즈니스 수행 메서드를 직접 넣어 부수효과를 만드는 코드가 없는지 체크한다.
- 주민번호, 계좌번호, 카드번호, 전화번호, 이메일, 주소 등 개인정보가 로그/응답/파일에 평문 노출되지 않는지 체크한다.
- 개인정보 마스킹과 암호화가 프로젝트 표준을 따르는지 체크한다.
- 민감 요청 본문 전체를 로그에 그대로 남기지 않는지 체크한다.
- 개인정보를 저장해야 하는 경우 평문 적재 대신 마스킹 또는 승인된 암호화 체계를 적용했는지 체크한다.
- 승인된 공통 암호화 유틸, `CGP`, `K-Sign` 등 조직 표준 경로를 우회하는 임의 암호화를 도입하지 않았는지 체크한다.

### 이벤트 / 비동기 / Redis

- 서버 내부 후처리 분리는 `ApplicationEventPublisher`, `@EventListener`, `@Async`, `@TransactionalEventListener`를 적절히 사용하는지 체크한다.
- 이벤트 객체를 불변 객체 또는 그에 준하는 형태로 설계했는지 체크한다.
- 오래 걸리는 후처리를 동기 흐름에 묶어 두지 않았는지 체크한다.
- Redis Pub/Sub를 사용할 때 순서 보장, 내구성, 재시도 부재 한계를 이해하고 사용했는지 체크한다.
- 단순 브로드캐스트/상태 전파가 아닌데 Redis Pub/Sub를 무리하게 쓰고 있지 않은지 체크한다.

### SQL

- ANSI SQL 기준을 크게 벗어나지 않는지 체크한다.
- `JOIN` 사용 시 Alias가 명확하고 일관되게 선언되는지 체크한다.
- Alias에 한글이나 임의 난수성 이름을 쓰지 않는지 체크한다.
- 불필요한 DB Function, Procedure, 프로시저 의존을 늘리지 않는지 체크한다.
- DBMS 특화 문법은 불가피한 근거가 있을 때만 사용하는지 체크한다.

### 포맷팅 / 설정

- 프로젝트 포맷팅 도구(예: Spotless + googleJavaFormat)와 충돌하는 스타일이 없는지 체크한다.
- import 정리, 미사용 import 제거, trailing whitespace 제거 등 기본 정리 상태를 체크한다.
- 환경설정 키가 계층형 구조와 kebab-case 예시에 맞는지 체크한다.

### 기타 리뷰시 요구사항

- 공통 유틸, 공통 예외, 공통 응답 래퍼, 공통 로깅/보안 처리로 일반화 가능한 부분이 있으면 제안한다.
- 더 나은 설계 가이드가 있으면 함께 제안하되, 현재 프로젝트 계약을 깨지 않는 선에서 제안한다.
- 확인한 파일 목록을 반드시 표현한다.
- 파일별 상태를 `통과`, `확인필요`, `무시`, `위반` 중 하나로 명시한다.
- 통과하지 못한 파일은 어떤 규칙을 어겼는지 구체적으로 적는다.

### ignore 파일들

- package.json
- *.yml
- *.md
- *.lock
- dist 폴더 내 파일들
- node_modules 폴더 내 파일들
