ysCha e24938f8d7 인수인계서 5종 git 관리 시작 + Claude 메모리를 프로젝트 내부로 이동

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-05-06 15:39:34 +09:00

4.0 KiB

Raw Blame History

중간 서버 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 수정 시 점검 포인트

Request 인 경우: 프론트가 보내는 필드를 받을 수 있는지 (필드명/타입 일치).
Response 인 경우: QSP 응답을 그대로 통과시키는지 (또는 변환 로직이 있는지).
Lombok @Data 또는 @Getter/@Setter 가 붙어 있는지 확인.
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. 인수 직후 권장 절차

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

6. 미해결 / 추적 중

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

끝.

4.0 KiB Raw Blame History