[api] 코딩 컨벤션 추가

AGENTS.md

@@ -29,7 +29,7 @@
 - `deploy`: 배포 관련 리소스가 있으면 이 경로를 우선 확인한다.
 
 ## 현재 확인된 구조
-- 현재 기준 메인 흐름은 `Controller -> Form -> Dto -> Service -> Mapper(XML) -> vo -> Service -> Controller` 순서로 연결된다.
+- 현재 기준 메인 흐름은 `Controller -> Form -> Dto -> Service -> Mapper(XML) -> Vo -> Service -> Controller` 순서로 연결된다.
 - API 에서 request 받을 때 POST 는 주로 JSON을 사용한다. Controller 는 `form` 객체로 요청을 받은 뒤 DTO 로 변환해서 Service 에 전달한다.
 - MyBatis는 인터페이스와 XML을 함께 사용한다.
 - Mapper 인터페이스는 `src/main/java/.../mapper`, SQL XML은 `src/main/resources/mapper/...` 경로를 짝으로 맞춘다.
@@ -45,18 +45,20 @@
 - 설정성 클래스는 `config` 하위 역할별 패키지에 둔다. 예: `config.jwt`, `config.exception`, `config.properties`
 
 ## DTO/VO/Mapper 규칙
-- `Dto`는 저장, 수정, 로그 적재처럼 내부 상태 변경이나 DB update/insert에 사용하는 값 객체로 본다.
-- `Vo`는 조회 결과나 스케줄 실행 판단에 필요한 읽기 전용 성격의 값으로 본다.
+- `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 변환이 꼭 필요할 때만 최소한의 보조 메서드를 둔다.
-- 외부 응답에 노출되면 안 되는 내부 필드는 DTO 에 `@JsonIgnore`로 숨긴다.
+- 외부 응답에 노출되면 안 되는 내부 필드는 응답에 사용될 수 있는 객체에서 `@JsonIgnore`로 숨긴다.
 - Mapper 메서드명은 SQL 동작이 드러나도록 `select`, `insert`, `update` 접두어를 사용한다.
 - 삭제가 물리 삭제가 아니라 상태 변경이면 `delete` 대신 목적이 드러나는 `update...Canceled`, `update...DelYn` 같은 이름을 우선한다.
 - Mapper XML `namespace`는 인터페이스의 전체 경로와 정확히 일치시킨다.
 - XML의 `id`는 Mapper 메서드명과 동일하게 맞춘다.
-- 조회 결과 타입은 `resultType`, 저장/수정 파라미터는 DTO/VO 필드명과 매핑되는 프로퍼티명을 그대로 사용한다.
+- 조회 결과 타입은 `resultType`, 저장/수정 파라미터는 DTO 필드명과 매핑되는 프로퍼티명을 그대로 사용한다.
 - Mapper XML 안 SQL 블록 시작부 주석은 현재 코드처럼 `/*Mapper.method*/` 형식을 유지한다.
 
 ## 작업 원칙
@@ -81,7 +83,6 @@
 - Controller 는 요청/응답 조립과 인증 주체 확인에 집중하고, DB 처리나 복잡한 계산은 Service 로 넘긴다.
 - Controller 응답은 `ResponseEntity<ApiResponse<T>>` 를 기본으로 사용한다. 파일 다운로드처럼 바이너리 응답이 필요한 경우만 예외로 둔다.
 - Controller 에서는 `@RequestBody`, `@PathVariable`, `@RequestHeader`, `@CookieValue` 를 명시적으로 선언해 요청 출처를 드러낸다.
-- Service 는 resultCode 를 DTO 에 담아 반환하는 패턴이 일부 있으므로, 기존 모듈 흐름에 맞춰 유지한다.
 - 인증 사용자 확인은 모듈 구현에 따라 `HttpSession` 또는 `SecurityContextHolder` 를 사용하므로 기존 방식을 먼저 맞춘다.
 
 ## 예외/응답 규칙
@@ -117,6 +118,8 @@
 - 무엇을 바꿨는지보다 왜 그렇게 바꿨는지를 짧고 분명하게 설명한다.
 - 파일 수정 후 가능하면 테스트 또는 최소 실행 검증 결과를 함께 남긴다.
 - 검증하지 못한 내용은 추정으로 말하지 않고 미실행 사유를 적는다.
+- 사용자가 IDE 에서 파일을 수정하거나 새 파일을 만든 뒤 질문할 수 있으므로, 관련 답변 전에는 저장된 최신 파일 상태를 다시 확인하는 것을 우선한다.
+- 이전에 읽은 세션 문맥만으로 최신 파일 상태를 단정하지 말고, 저장되지 않은 편집 내용은 확인할 수 없음을 전제로 설명한다.
 - 요청 범위를 벗어나는 개선점은 강제로 반영하지 말고 제안으로 분리한다.
 
 ## 사용자 선호 규칙
@@ -180,12 +183,11 @@
 - 새 모듈 추가 시: `modules/{moduleName}/` 하위에 Controller, Service, Mapper, dto/, vo/, 필요 시 form/ 구조로 생성
 - Mapper XML은 `resources/mapper/{moduleName}/` 에 위치
 - Form 에서 DTO 로 변환할 때는 검증과 trim, 기본값 치환까지 같이 처리하는 현재 패턴을 우선 따른다.
-- 파일/인증처럼 상태값을 내려주는 DTO 는 `resultCode` 필드를 활용하는 기존 흐름을 해치지 않도록 한다.
 
 ## MyBatis 규칙
 - Mapper XML 위치: `src/main/resources/mapper/**/*.xml`
 - `map-underscore-to-camel-case: true` 설정 → DB 컬럼 `user_idx` → Java 필드 `userIdx` 자동 매핑
 - Mapper 인터페이스와 XML의 namespace, id 반드시 일치시킬 것
-- VO: DB 조회 결과 매핑용 / DTO: 서비스 레이어 간 데이터 전달용 / Form: 컨트롤러 입력 검증용
+- DTO/VO/Form 역할 정의는 `DTO/VO/Mapper 규칙` 섹션을 기준으로 맞춘다.
 - `useGeneratedKeys`, `keyProperty` 를 사용하는 insert 가 있으므로 신규 PK 생성 테이블은 현재 패턴을 먼저 확인한다.
 - 상태 집계나 이력성 데이터는 단건 update 외에 이벤트 로그 insert 가 같이 필요한지 확인한다.