123 lines
5.6 KiB
Markdown
123 lines
5.6 KiB
Markdown
# 인수인계 문서 인덱스 (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/{이름이나 번호}` — 기능별 브랜치
|
|
|
|
---
|
|
|
|
끝.
|