# 도메인 기능 인수인계서 (BOM / 권한 / API / 우편번호 / 배치)

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

> **이 문서의 범위**: 출력·DTO·인증 외 나머지 도메인 작업.
> 다른 트랙은 `HANDOVER_INDEX.md` 참조.

---

## 0. 한 줄 요약

[1xxx] 티켓 시리즈와 새로 추가된 API들이 모이는 곳. **BOM 부모/자식 의미**, **오브젝트 복사 권한**, **발전시뮬레이션 API 신규 개발**, **우편번호 하이픈 자동 처리**, **배치(Quartz) 포트/시간 조정** 등 다양한 도메인 작업이 들어 있습니다.

---

## 1. BOM (자재 명세서)

### 1.1 `[1487]` 자식 BOM 조회 쿼리 컬럼 의미 수정
- 커밋: `0c979df6`
- 가장 헷갈렸던 부분: **컬럼명과 의미가 직관과 반대**.
  - `PACKAGE_ITEM_ID` = **자식**
  - `ITEM_ID` = **부모**
- BOM 조회/저장 쿼리를 새로 손댈 때 항상 이 의미를 다시 확인하세요. **반대로 알면 부모-자식 관계가 통째로 뒤집힙니다.**

### 1.2 권장
- 새 매퍼 쿼리에 컬럼 alias를 줄 때 `PARENT_ITEM_ID` / `CHILD_ITEM_ID` 같이 의미 명시한 별칭을 써서 후임자가 헷갈리지 않게 하세요.

---

## 2. 권한

### 2.1 `[1485]` 오브젝트 복사 기능 권한 설정
- 커밋: `491f9304`, `31e3c77a`
- 오브젝트 복사 액션은 모두에게 열려 있지 않고 **권한이 있는 사용자만** 수행 가능하게 제한.
- 권한 체크는 Controller/Service 레이어에서. 프론트에서도 버튼이 노출/비노출되는지 양쪽 정합성 확인 필요.

---

## 3. 발전시뮬레이션 관련 신규 API

### 3.1 `[?]` 발전시뮬레이션 관련 견적서 조회 API
- 커밋: `7211101a`
- 발전시뮬레이션이 참조하는 견적서를 조회하는 신규 엔드포인트.

### 3.2 `[?]` 발전시뮬레이션 물건번호 목록 조회 API
- 커밋: `c7253388`
- 물건번호(objectNo) 목록을 발전시뮬레이션 화면에 노출.

### 3.3 `[1516]` 발전량 수정 — 중복 모듈 처리
- 커밋: `3b090f7e`
- 같은 모듈이 중복으로 잡혀 발전량 계산이 중복되던 문제 수정.

### 3.4 `[1375]` 인증용량 쿼리 수정
- 커밋: `2c0a8a35`, `0a0e248b`
- 인증용량 산출 쿼리 보정. (수정이 두 번 나뉜 걸 보면 한 번에 안 잡힘 — 새 케이스가 발견되면 또 분기 추가될 가능성.)

---

## 4. 모듈 / PCS / 거치대

### 4.1 `[1479]` 물건 정보 화면에 일부 PCS 명칭이 표시되지 않는다 — 스토리지뱃더리 추가
- 커밋: `3a4dab2f`
- "스토리지뱃더리"(스토리지 배터리, 일본어 표기)를 PCS 종류에 추가.

### 4.2 `[1763]` 특정 지붕재 사용 시 Plan 복사 오류
- 커밋: `1b4e64b5`
- 특정 지붕재가 들어간 Plan을 복사하면 지붕재 정보가 올바르게 전달되지 않음 → 복사 시 매핑 보정.

### 4.3 `[1764]` 북쪽 면 설치 사양 변경
- 커밋: `408cc75a`
- 북쪽 면 설치 사양 처리 분기 추가.

### 4.4 `[1423]` 설계 가져오기 기능
- 커밋: `2b43fad2`
- 다른 설계를 현재 화면으로 가져오는 기능 보강.

---

## 5. 우편번호

### 5.1 한 일

| 내용 | 커밋 |
|------|------|
| 판매점 우편번호 등록 시 하이픈이 없으면 **셋째 자리 뒤에 자동 하이픈 조합**으로 등록 처리 | `e05ef305` |
| 우편번호 변경 부분 추가 | `4e502c42` |

### 5.2 정책

- 일본 우편번호는 `XXX-XXXX` 7자리 + 하이픈 형식. 사용자가 하이픈 없이 7자리만 넣어도 받아주도록 자동 보정.

---

## 6. 배치 (Spring Batch + Quartz)

### 6.1 한 일

| 내용 | 커밋 |
|------|------|
| 배치 잡이 8080, 8081 두 곳에서 실행되던 것을 8080만 실행하도록 수정 | `711c8fcd` |
| 개발에 `batch: scheduler-port: 8090` 추가 | `4bcc2fe9` |
| `materialJob`: `02:30 → 04:50`, `bomJob`: `02:40 → 05:20` 시간 조정 | `19250727` |
| job 수정 / 제목 한 줄에 나타내기 | `6b072e42`, `4759c572` |

### 6.2 주의

- 배치 잡 시간을 옮길 때는 **다른 잡과 겹치지 않는지** 반드시 확인하세요. 같은 시간에 여러 잡이 돌면 DB 부하/락이 발생합니다.
- 잡이 두 인스턴스(8080/8081)에서 동시에 도는 사고가 있었던 영역이라 **포트 분리 정책**이 들어가 있습니다.

---

## 7. Java 버전 / 빌드 환경

### 7.1 한 일
- 커밋 `73da60a0`, `9b762063`, `d68b1270`, `037e3201` (java 버전 맞춤 1~3)
- 로컬·CI 자바 버전 불일치로 빌드 실패가 반복돼 **Java 17** 로 정렬.

### 7.2 주의
- 새 환경 세팅 시 `JAVA_HOME` 이 17 인지 먼저 확인.
- `pom.xml` 의 `<java.version>` 도 17 로 고정.

---

## 8. 핵심 파일 / 위치

| 위치 | 역할 |
|------|------|
| `com.interplug.qcast.biz.bom.*` | BOM 도메인 |
| `com.interplug.qcast.biz.simulation.*` | 발전시뮬레이션 |
| `com.interplug.qcast.biz.permission.*` 또는 Controller 단의 권한 어노테이션 | 권한 |
| `com.interplug.qcast.batch.*` | 배치 잡 / Quartz 설정 |
| `application*.yml` | 포트/스케줄러 포트/잡 시간 등 설정 |

---

## 9. 인수 직후 권장 절차

1. 이 문서 통독.
2. `application.yml` 와 `application-{profile}.yml` 차이를 확인 (특히 배치 포트).
3. BOM 자식 조회 쿼리 한 번 직접 실행 → 부모/자식 컬럼 의미 체득.
4. 발전시뮬레이션 신규 API 두 개의 endpoint URL을 Swagger UI에서 확인.

---

## 10. 미해결 / 추적 중

- `[1375]` 인증용량 쿼리는 **케이스가 더 있을 수 있음** (이미 두 차례 수정됨).
- 배치 잡 시간 정책은 운영 데이터 양에 따라 또 옮길 가능성 있음.
- 권한 체크가 Controller/Service 두 레이어에 산재되어 있어 **표준화 여지**가 있음 (시간 되면).

끝.