# BE 문서 요약

## 목적

- 이 문서는 `ju-hong-e`의 BE 코드 리뷰 규칙을 만들기 위해 참고한 문서를 요약한 정리본이다.
- 실제 프롬프트에 바로 넣을 규칙은 `review-rules.md`를 사용하고, 이 문서는 왜 그런 규칙이 나왔는지 설명하는 참고 문서로 사용한다.

## 참고 문서

### 1. `[DSP-BE] 개발 가이드.pdf`

- 프로젝트 맞춤형 백엔드 개발 가이드
- 주요 범위
  - 표준 개발/배포 환경
  - 패키지/클래스/메서드 명명 규칙
  - API URI 규칙
  - Java/Spring 백엔드 구조
  - Controller, Service, DTO, Entity, Repository, MyBatis, JPA 규칙
  - Logging, Exception, Http Status, Transaction
  - 이벤트 처리, Redis Pub/Sub
  - Spotless, 환경설정 키 규칙, 개발 사이트

### 2. `NXL_개발표준정의서(BE)_v1.6.txt`

- 전사 표준 문서
- 원본 `docx`를 사전에 텍스트로 변환한 파일
- `cp949/euc-kr` 계열로 디코딩하면 본문을 읽을 수 있어, 이번 정리에서는 이 파일을 NXL 표준의 주 참고본으로 사용했다.
- 직접 확인한 범위
  - 표준 개발/개발환경
  - 프레임워크/라이브러리 정보
  - 프로젝트/패키지/클래스/메서드/변수/상수/Enum/Mapper 명명 규칙
  - 서비스 URL 표준
  - Java/Application/SQL/주석/트랜잭션 규칙
  - 개인정보 마스킹/암호화 규칙
  - Logging / Exception / HTTP Status 규칙

### 3. `NXL_개발표준정의서(BE)_v1.6.xml`

- 파일명은 `xml`이지만, 실제로는 Word 복합 문서/DRM 메타데이터가 섞인 바이너리 컨테이너에 가깝다.
- 리뷰 규칙 정리용 본문 소스로는 활용하지 않았다.

## 문서 해석 우선순위

- 프로젝트 리뷰 규칙을 만들 때는 `[DSP-BE] 개발 가이드.pdf`를 우선 적용한다.
- 전사 표준과 프로젝트 가이드가 충돌하지 않는 범위에서는 `NXL_개발표준정의서(BE)`의 일반 원칙을 보조 근거로 사용한다.
- 프로젝트에 이미 존재하는 API 응답 계약, URL 패턴, 예외 처리 규약이 있으면 그 구현 관성을 우선한다.
- 개발환경/프레임워크 버전 정보는 문서 간 차이가 있으므로, 리뷰 룰에서는 하드 체크 항목으로 승격하지 않는다.
  - 예: NXL 표준은 `OpenJDK 1.8`, `Spring Boot 2.7` 중심
  - 예: 프로젝트 가이드는 더 최신 스택 기준

## 핵심 요약

### 아키텍처 / 계층 역할

- Controller는 요청/응답 매핑과 위임에 집중하고, 비즈니스 로직을 직접 담지 않는다.
- Service는 단일 책임 원칙에 따라 비즈니스 조합과 흐름 제어를 담당한다.
- DTO는 순수 전달 객체로 사용하고, Entity를 외부 응답에 직접 노출하지 않는다.
- JPA 사용 시 Entity/Repository 책임을 명확히 분리한다.
- 복잡한 영속성 조회는 QueryDSL, Native Query, MyBatis를 상황에 맞게 제한적으로 사용한다.

### 명명 / 패키지 구조

- 프로젝트명은 케밥 표기법을 기준으로 하며, 업무코드/기능코드/상세구분 조합 구조를 사용한다.
- 패키지는 영문 소문자, 도메인 기반, 역할 기준 세분화(`controller`, `service`, `domain`, `infrastructure`)를 따른다.
- 플랫폼 대상/비대상에 따라 기본 패키지 예시가 `com.hanwhalife.nxl...`, `com.hanwhalife...`로 구분된다.
- 클래스는 PascalCase, 메서드는 lowerCamelCase를 사용한다.
- 약어도 일반 Pascal/Camel 규칙을 따른다. 예: `HttpUrlConnection`
- Boolean 메서드는 `is`, `has`, `can` 접두사를 우선한다.
- DTO/Entity/Repository는 역할 접미사(`RequestDto`, `ResponseDto`, `Entity`, `Repository`)를 일관되게 사용한다.
- 메서드명은 영문 동사로 시작하고, 숫자는 불가피할 때만 마지막에 사용한다.

### API / URL

- URL은 영문 소문자 중심, 명사형 리소스 중심으로 설계한다.
- 파일 확장자, 트레일링 슬래시, 불필요한 언더스코어는 지양한다.
- 프로젝트 가이드상 `get/post/put/delete`를 URI 세그먼트에 포함하는 내부 표준이 존재하므로, 외부 REST 일반론보다 현재 프로젝트 계약을 우선 본다.
- 민감정보 조회, 대용량 조회, 웹서버 로그 노출 우려가 있으면 조회도 POST를 허용한다.
- NXL 표준은 GET/POST만 허용하고, 조회는 `GET + /get`, 등록은 `POST + /post`, 수정은 `POST + /put`, 삭제는 `POST + /delete` 패턴을 예시로 든다.
- 목록 자원은 `-list` 또는 복수형을 사용하도록 안내한다.

### 예외 / 응답 / 상태코드

- 비즈니스 예외와 시스템 예외를 분리한다.
- 예외를 무시하거나 의미 없이 삼키지 않는다.
- 리스트 단순 조회에서 데이터 없음은 빈 리스트 반환이 우선이고, 후속 비즈니스 처리에 영향이 있으면 예외를 검토한다.
- HTTP Status는 프로젝트 계약을 우선하며, 내부 오류 코드/메시지 체계를 임의로 바꾸지 않는다.
- NXL 표준은 2xx, 4xx 중심 상태코드 사용을 명시한다.

### 트랜잭션

- 트랜잭션은 서비스 메서드 단위로 관리한다.
- 조회 전용 메서드는 `@Transactional(readOnly = true)`를 우선 검토한다.
- CheckedException까지 롤백이 필요하면 `rollbackFor`를 명시한다.
- 전파 속성은 꼭 필요한 경우에만 사용한다.

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

- 로그 레벨은 의도에 맞게 구분한다.
  - `DEBUG`: 개발 디버깅
  - `INFO`: 일반 흐름/시작/종료/운영 확인 정보
  - `WARN`: 비즈니스 오류/검증 실패
  - `ERROR`: 시스템 오류/예상하지 못한 예외
- 주민번호, 계좌번호, 카드번호, 전화번호, 이메일, 주소 등은 로그/응답/저장 시 마스킹 또는 암호화를 준수해야 한다.
- 승인된 암호화 체계와 사내 표준 라이브러리 사용이 전제된다.

### 이벤트 / Redis

- 서버 내부 후처리 분리가 필요하면 `ApplicationEventPublisher`, `@EventListener`, `@Async`, `@TransactionalEventListener`를 활용한다.
- 이벤트 객체는 불변 객체를 우선한다.
- Redis Pub/Sub는 경량 브로드캐스트 용도에 적합하지만, 순서 보장/내구성/재시도 보장이 약하므로 무거운 업무 이벤트에는 신중해야 한다.

### 포맷팅 / 설정

- Java 포맷팅은 Spotless + googleJavaFormat 적용 예시가 있다.
- 환경설정 키는 계층형 구조를 유지하고, 예시상 kebab-case 키를 사용한다.
- 전사 표준 문서 기준으로 Java 코딩 표준에는 import, 들여쓰기, 중괄호, 띄어쓰기, 클래스 멤버 정렬, `try-catch`, 주석 작성 원칙, 트랜잭션 규칙이 포함된다.
- 스프링 빈에 요청별 가변 상태를 담는 인스턴스 변수 사용은 신중해야 하며, 리뷰 시 상태 공유 위험을 같이 확인하는 것이 적절하다.
- NXL 표준은 `import *` 금지, `System.out.println()` 금지, `Map` 기반 DTO 전달 금지, `@Data` 지양, 개인정보 DTO의 `@ToString` 금지 같은 구체 규칙을 포함한다.
- SQL 기준에는 ANSI SQL 준수, Alias 영문/숫자 사용, 불필요한 프로시저/함수 지양, MyBatis `namespace`/`SQL_ID` 규칙 준수 등이 포함된다.

## 리뷰 규칙으로 변환할 때의 해석 포인트

- 이 문서들의 목적은 “좋아 보이는 일반론”보다 “현재 조직/프로젝트 표준 위반 여부”를 잡는 것이다.
- 다만 환경 버전, 툴 버전, 일부 레거시 취향 규칙은 현재 프로젝트와 충돌할 수 있으므로 강제 규칙이 아니라 참고 수준으로만 반영하는 것이 적절하다.
- 따라서 리뷰 규칙은 아래 순서로 판단하도록 구성하는 것이 적절하다.
  1. 계층 책임 위반
  2. API 계약 위반
  3. 예외/트랜잭션/응답 처리 위반
  4. 개인정보/로그/보안 위반
  5. 명명/패키지/포맷팅 위반
