qcast3/qcast-api
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
qcast-api/doc/HANDOVER_INDEX.md
ysCha e24938f8d7 인수인계서 5종 git 관리 시작 + Claude 메모리를 프로젝트 내부로 이동 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-05-06 15:39:34 +09:00

5.6 KiB
Raw Blame History

인수인계 문서 인덱스 (qcast-api)

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

0. 이 폴더는 뭔가요?

qcast-api 프로젝트(태양광 시스템 QCAST의 백엔드 API)의 트랙별 인수인계 문서가 모여 있습니다. 한 파일에 다 넣으면 너무 길고 영역이 섞여서 보기 어렵기 때문에 4개 트랙으로 분리했습니다.

읽는 순서: 위에서부터 차례로. 출력(Excel/PDF) 트랙이 가장 양이 많고 손댈 일도 많으니 먼저 읽으세요.

참고: 이 프로젝트는 중간 서버입니다. 구조는 QSP API → qcast-api → qcast-front 입니다. "다른 팀 서버에 알려야 한다" 가 아니라 여기서 직접 DTO/로직을 고치면 됩니다.

1. 트랙별 문서

OUTPUT_HANDOVER.md ★ 가장 자주 손댐

견적서 / 발전시뮬레이션 / Excel·PDF 출력 트랙. 견적서·중량·구조도·계통도 등의 Excel/PDF 출력 관련 작업이 가장 많은 영역입니다. 정렬·파일명·이미지·전각문자·도면 비율 등 출력물에서 보이는 거의 모든 것이 여기에 모입니다.

핵심 키워드: 견적서 / 발전시뮬레이션 / Excel(jxls+POI) / PDF(iText html2pdf) / 정렬 / 파일명 포맷 / 전각문자 / 도면 비율 / ®→Ⓡ→(R) / 폰트

DTO_MIDDLE_SERVER_HANDOVER.md

중간 서버 DTO 변경 트랙. QSP API 응답 또는 프론트 요청 스키마가 바뀌면 qcast-api DTO를 통과해야 하므로 DTO 수정이 필수입니다. 통보문만 주고 미루면 다음 날 같은 일을 또 하게 됩니다.

핵심 키워드: 중간 서버 / DTO 수정 / moduleTpCd / subModuleTpCd / Cross Mix / addresseeCompanyName 50자 / selectParentAgentInfo

AUTH_ERROR_HANDOVER.md

인증 / 로그인 추적 / 에러 저장 API 트랙. 자동 로그인·로그아웃 동작 추적, 클라이언트 에러를 백엔드에 저장하는 errSave/quotationErrSave API.

핵심 키워드: 로그인·로그아웃 추적 / 자동 로그인 추적 / errSave / quotationErrSave / itemList null 체크

DOMAIN_HANDOVER.md

도메인 기능 트랙 (BOM / 권한 / 발전시뮬레이션 API / 우편번호 / 배치 등). 출력·DTO·인증 외 나머지 도메인 작업 전반. [1xxx] 티켓 시리즈와 새로 추가된 API들.

핵심 키워드: BOM 부모/자식 / 오브젝트 복사 권한 / 발전시뮬레이션 물건번호 API / 우편번호 하이픈 / 배치(Batch) / Quartz / 인증용량 쿼리 / [1xxx] 티켓

2. 같이 봐야 하는 자료

메모리 인덱스

  • 위치: ~/.claude/projects/-Users-cha-Works-Projects-qcast3-qcast-api/memory/MEMORY.md
  • 작업 시 지켜야 할 사용자(Cha) 작업 스타일이 들어 있습니다.
  • 작업 시작 전에 반드시 통독하세요.

커밋 로그 (자동 누적, 2026-05-06~)

  • 위치: ~/.claude/projects/-Users-cha-Works-Projects-qcast3-qcast-api/memory/commit_log.txt
  • 본 저장소의 .git/hooks/post-commit 훅이 매 커밋 직후 한 줄 append 합니다.
  • 형식: YYYY-MM-DD HH:MM:SS [브랜치] short(fullhash) 커밋제목
  • 인수인계서/리뷰에 해시를 인용해야 할 때 우선 참조. 푸시 여부는 기록되지 않으므로 별도 확인.

사내 자료 (참고)

  • 자바 코드 스타일: doc/eclipse-java-google-style.xml
  • 자매 프로젝트 인수인계: qcast-front/docs/HANDOVER_INDEX.md (프론트 영역의 결정 사항이 백엔드 동작 이해에도 필요할 때 참조)

3. 인수받은 직후 추천 절차

  1. 이 인덱스 통독 (5분).
  2. 메모리 MEMORY.md 통독 — 사용자 스타일 / 중간 서버 원칙 / 커밋 메시지 규칙 (5~10분).
  3. OUTPUT_HANDOVER.md 통독 — 가장 자주 손대는 영역 (20~30분).
  4. 나머지 3개 트랙 문서는 필요할 때 펼쳐 보는 레퍼런스 로 사용.
  5. pom.xml / application.yml / 매퍼 폴더 구조를 한 번 훑어 패키지 구성을 머리에 넣기.

4. 핵심 원칙 3줄 요약

이 프로젝트에서 일을 한다면 적어도 이 3개는 머리에 두세요.

  1. 중간 서버다. QSP/프론트 스키마가 바뀌었다는 정보를 받으면, 통보만 하지 말고 그 자리에서 DTO를 직접 수정.
  2. 출력물(Excel/PDF)은 양쪽을 따로 본다. Excel은 jxls/POI, PDF는 iText html2pdf — 같은 견적서라도 두 곳을 동시에 고쳐야 함.
  3. 작업 끝나면 한국어 한 줄 커밋 메시지를 함께 제시한다. (단, AI가 직접 git commit 하지 말 것, 사용자가 직접 커밋함.)

5. 기술 스택 한눈에

항목 내용
언어 Java 17
프레임워크 Spring Boot 3.3.0, Maven
DB 접근 MyBatis 3.0.3 (XML 매퍼: src/main/resources/mappers/)
데이터베이스 MSSQL Server (DB명: NEWPVCAD)
보안/암호화 Spring Security, Jasypt
외부 API 호출 OpenFeign
Excel Apache POI / jxls
PDF iText html2pdf
API 문서 Springdoc OpenAPI (Swagger UI)
스케줄러 Spring Batch + Quartz

패키지 구조: com.interplug.qcast.biz.{도메인} 안에 Controller / Service / Mapper / DTO.

6. 브랜치 전략

  • main — 운영 (PR 대상은 보통 여기)
  • dev — 개발 통합
  • dev-deploy — 개발 서버 배포용
  • dev_ysCha — 담당자 개인 작업 브랜치 (현재 체크아웃)
  • hotfix/9999 — 긴급 수정용
  • feature/{이름이나 번호} — 기능별 브랜치

끝.