115 lines
4.0 KiB
Markdown
115 lines
4.0 KiB
Markdown
# 중간 서버 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 이슈는 없으나, **변경 누락 = 운영 장애** 직결이므로 보수적으로.
|
|
|
|
끝.
|