# 중간 서버 DTO 변경 인수인계서

> 작성일: 2026-05-06
> 대상: 후임 AI 엔지니어 또는 개발 관리자
> 작업 브랜치: `dev_ysCha`

> **이 문서의 범위**: qcast-api가 중간 서버로서 통과시키는 DTO 변경 작업만 다룹니다.
> 다른 트랙은 `HANDOVER_INDEX.md` 참조.

---

## 0. 한 줄 요약

`QSP API → qcast-api → qcast-front` 의 가운데 다리 역할이라, **양쪽 스키마가 바뀌면 중간 DTO를 반드시 통과시켜야** 합니다. "외부에 통보하면 끝"이 아니라 **여기서 직접 코드를 고칩니다**.

---

## 1. 가장 중요한 원칙 — 통보 X, 직접 수정 O

### 1.1 무엇을 잘못하기 쉬운가

QSP 응답이나 프론트 요청 스키마가 바뀌었다는 얘기를 들었을 때, AI가 자주 하는 실수:

> "QSP 응답에 X 필드가 추가되었습니다. DTO에 추가가 필요합니다." (← 이렇게 끝내고 코드는 안 고침)

이 프로젝트에서는 **틀린 행동**입니다.

### 1.2 사용자 피드백 (2026-04-22)

> "어제 명령했을 때는 추가 안 하고, 내가 오늘 다시 물으니깐 추가하면 일을 두번 하게 만들어."

### 1.3 올바른 행동

- 분석 → **그 자리에서 Edit으로 DTO 필드 추가**
- "반영할까요?" 재확인 없이 진행
- 통보 템플릿은 QSP 백엔드 팀 쪽에만 해당 (qcast-api 내부는 직접 수정)

---

## 2. 작업 위치

### 2.1 DTO 폴더

| 종류 | 위치 |
|------|------|
| Request DTO (프론트 → qcast-api) | `com.interplug.qcast.biz.{도메인}.dto.*Request` |
| Response DTO (QSP → qcast-api → 프론트) | `com.interplug.qcast.biz.{도메인}.dto.*Response` |

> 도메인별로 패키지가 다르므로 IDE의 "Find in Files" 로 필드명 검색이 빠릅니다.

### 2.2 수정 시 점검 포인트

1. **Request 인 경우**: 프론트가 보내는 필드를 받을 수 있는지 (필드명/타입 일치).
2. **Response 인 경우**: QSP 응답을 그대로 통과시키는지 (또는 변환 로직이 있는지).
3. **Lombok `@Data` 또는 `@Getter/@Setter`** 가 붙어 있는지 확인.
4. **Swagger 문서**에도 자동 반영되는지(어노테이션 사용 여부).

---

## 3. 한 일 (대표 사례)

### 3.1 PCS 접속함 `moduleTpCd`
- 커밋: `475733d2`
- PCS 접속함 **응답/요청 DTO 모두**에 `moduleTpCd` 필드 추가.
- 양방향이므로 두 군데를 동시에 수정해야 함.

### 3.2 `trestles[].subModuleTpCd`
- 커밋: `45f8bbd4`
- `trestles[]` 배열 요소에 `subModuleTpCd` 추가.
- **Cross Mix 식별용**. 단일/동계열은 빈 값.

### 3.3 `addresseeCompanyName` 50자 제한
- 커밋: `b2305295`
- 수신자 회사명 50자 제한. (DTO/검증/저장 어느 단에서 자르는지 확인하고 일관되게)

### 3.4 `selectParentAgentInfo` 관련
- 커밋: `fd2703ba`
- 부모 에이전트 정보 조회 — DTO + Mapper + Service 한 세트.

### 3.5 `CATEGORY` 20자 제한
- 커밋: `4db2ddfd`
- `CATEGORY, LEN(CATEGORY) AS M_USER` 20자 제한.

---

## 4. 검증 / 길이 제한 정책

길이 제한이 들어가는 필드들은 보통 다음 위치 **모두**에 같은 값을 둬야 합니다.

| 위치 | 역할 |
|------|------|
| DTO 필드 | `@Size(max = N)` 등으로 검증 |
| Mapper XML | DB 컬럼 길이 일치 |
| 프론트 입력 폼 | 입력 단에서 자르기 / 안내 |

> 한 곳만 50자, 다른 곳 100자 이렇게 어긋나면 운영에서 끊어집니다. 변경 시 전부 같이.

---

## 5. 인수 직후 권장 절차

1. 이 문서 통독.
2. `dto/` 하위 패키지 한 번 훑어 어떤 도메인이 있는지 확인.
3. 가장 최근 DTO 변경 커밋(`475733d2`, `45f8bbd4`) 의 diff 한 번 따라가 보기.
4. QSP 응답 ↔ 프론트 요청 매핑 흐름을 견적서 도메인 하나로 따라가 보기.

---

## 6. 미해결 / 추적 중

- 중간 서버 특성상 **상시 변경 영역**입니다. QSP 또는 프론트 변경 보고가 들어오면 즉시 DTO부터 확인하세요.
- 현재까지 별도의 미해결 DTO 이슈는 없으나, **변경 누락 = 운영 장애** 직결이므로 보수적으로.

끝.