# 인수인계 문서 인덱스 (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](./OUTPUT_HANDOVER.md) ★ 가장 자주 손댐
**견적서 / 발전시뮬레이션 / Excel·PDF 출력 트랙.**
견적서·중량·구조도·계통도 등의 Excel/PDF 출력 관련 작업이 가장 많은 영역입니다. 정렬·파일명·이미지·전각문자·도면 비율 등 출력물에서 보이는 거의 모든 것이 여기에 모입니다.

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

---

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

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

---

### [AUTH_ERROR_HANDOVER.md](./AUTH_ERROR_HANDOVER.md)
**인증 / 로그인 추적 / 에러 저장 API 트랙.**
자동 로그인·로그아웃 동작 추적, 클라이언트 에러를 백엔드에 저장하는 `errSave`/`quotationErrSave` API.

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

---

### [DOMAIN_HANDOVER.md](./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/{이름이나 번호}` — 기능별 브랜치

---

끝.