코드 컨벤션

파일 생성 규칙

새 기능은 가능하면 modules/{도메인명}Controller 단위로 패키지를 만들고 그 아래에 service, mapper, dto, vo를 필요한 만큼만 추가한다.
요청 검증이나 JSON 바인딩이 필요하면 form 패키지를 함께 만든다.
클래스명은 역할이 바로 드러나게 도메인명 + 역할 형식을 유지한다. 예: ApiService, ApiMapper, ApiVo
Mapper 인터페이스를 추가하면 같은 이름의 XML을 src/main/resources/mapper/{도메인경로} 아래 함께 만든다.
단순 예시 코드와 운영 코드는 섞지 말고 패키지로 분리한다.
설정성 클래스는 config 하위 역할별 패키지에 둔다. 예: config.jwt, config.exception, config.properties

Dto는 각 Controller 에서 Service, Mapper 로 전달하는 파라미터 성격의 값 객체로 정의한다.
Dto는 요청 처리에 필요한 저장, 수정, 로그 적재 같은 작업 파라미터를 담는 용도로 우선 사용한다.
Vo는 Mapper 에서 Service, Controller 로 반환하는 값 객체로 정의한다.
Vo는 Mapper 조회 결과를 담을 수 있고, Service 에서 비즈니스 로직 처리 후 필요한 데이터를 가공해서 Controller 로 반환하는 용도로 사용한다.
Form은 Controller 입력 검증과 요청 바인딩 전용으로 두고, @Valid 와 Jakarta Validation 어노테이션을 우선 사용한다.
현재 코드처럼 DTO/VO는 Lombok @Getter, 필요한 경우에만 @Setter를 사용한다.
Form 안에는 DTO 변환 메서드를 둘 수 있다. 예: userDto(), fileUploadDto()
DTO 안에 연관된 다른 DTO 변환이 꼭 필요할 때만 최소한의 보조 메서드를 둔다.
외부 응답에 노출되면 안 되는 내부 필드는 응답에 사용될 수 있는 객체에서 @JsonIgnore로 숨긴다.
Form 에서 DTO 로 변환할 때는 검증과 trim(), 기본값 치환까지 같이 처리하는 현재 패턴을 우선 따른다.

Mapper 메서드명은 SQL 동작이 드러나도록 select, insert, update 접두어를 사용한다.
삭제가 물리 삭제가 아니라 상태 변경이면 delete 대신 목적이 드러나는 update...Canceled, update...DelYn 같은 이름을 우선한다.
Mapper XML namespace는 인터페이스의 전체 경로와 정확히 일치시킨다.
XML의 id는 Mapper 메서드명과 동일하게 맞춘다.
조회 결과 타입은 resultType, 저장/수정 파라미터는 DTO 필드명과 매핑되는 프로퍼티명을 그대로 사용한다.
Mapper XML 안 SQL 블록 시작부 주석은 현재 코드처럼 /*Mapper.method*/ 형식을 유지한다.
Mapper XML 위치는 src/main/resources/mapper/**/*.xml 이다.
map-underscore-to-camel-case: true 설정으로 DB 컬럼 user_idx 는 Java 필드 userIdx 로 자동 매핑된다.
useGeneratedKeys, keyProperty 를 사용하는 insert 가 있으므로 신규 PK 생성 테이블은 현재 패턴을 먼저 확인한다.
상태 집계나 이력성 데이터는 단건 update 외에 이벤트 로그 insert 가 같이 필요한지 확인한다.

Java 코드는 현재 프로젝트 스타일에 맞춰 탭/들여쓰기와 import 정렬을 유지한다.
Lombok은 반복 보일러플레이트 제거에만 절제해서 사용한다.
로그는 Slf4j를 사용하고 반복문 내부 대량 출력은 지양한다.
새로운 기능은 가능하면 역할이 드러나는 패키지로 분리한다.
생성자 주입을 기본으로 하고 필드 주입은 추가하지 않는다.
Service 에서 DB 상태를 바꾸는 메서드는 필요한 범위에서 @Transactional을 사용하고, 조회 전용은 readOnly = true를 우선 검토한다.
문자열 입력값은 현재 코드처럼 필요한 지점에서 trim() 처리하고, null 가능성 여부를 먼저 확인한다.

Controller 는 요청/응답 조립과 인증 주체 확인에 집중하고, DB 처리나 복잡한 계산은 Service 로 넘긴다.
Controller 응답은 ResponseEntity<ApiResponse<T>> 를 기본으로 사용한다. 파일 다운로드처럼 바이너리 응답이 필요한 경우만 예외로 둔다.
Controller 에서는 @RequestBody, @PathVariable, @RequestHeader, @CookieValue 를 명시적으로 선언해 요청 출처를 드러낸다.
인증 사용자 확인은 모듈 구현에 따라 HttpSession 또는 SecurityContextHolder 를 사용하므로 기존 방식을 먼저 맞춘다.