qcast3/qcast-api
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
qcast-api/doc/DOMAIN_HANDOVER.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.7 KiB
Raw Blame History

도메인 기능 인수인계서 (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 두 레이어에 산재되어 있어 표준화 여지가 있음 (시간 되면).

끝.