qcast3/qcast-front
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
qcast-front/docs/MODULE_CIRCUIT_HANDOVER.md
ysCha dd5fea7f21 cluade
2026-05-06 18:06:48 +09:00

11 KiB
Raw Blame History

모듈 / 배치 / 회로 / 처마 / 티켓 시리즈 인수인계서

작성일: 2026-05-06 (옵션 B 분리) 대상: 후임 AI 엔지니어 또는 개발 관리자 작업 브랜치: hotfix/dev_yscha

이 문서의 범위: 태양광 모듈 배치, 회로/PCS/접속함, 처마/가대, 그리고 [1xxx] 티켓 시리즈 같은 도메인 특화 작업을 다룹니다. 다른 트랙은 HANDOVER_INDEX.md 참조.

0. 한 줄 요약

지붕 형상이 결정된 다음 단계 — 태양광 모듈을 어디에 어떻게 배치하고, 모듈을 어느 PCS·접속함에 묶고, 처마/가대를 어떻게 잡을지 — 의 자잘한 버그/개선 트랙입니다. 티켓([1xxx]) 단위로 들어와 처리된 케이스가 많아 항목이 많지만, 각각은 국소적인 수정입니다.

1. 회로 / PCS / 접속함 트랙

태양광 시스템에서 모듈 → 접속함 → PCS(전력변환기) → 분전반 으로 이어지는 회로 구성 영역.

1.1 Cross Mix (DC3) 접속함 통합 (커밋 0eb888fb)

  • 문제: PCS 담당 모듈 타입에 따라 접속함이 여러 건 내려가던 것을 1건으로 합쳐야 했음.
  • 수정: PCS 담당 모듈 타입 기준으로 필터링해서 1건만 내려가도록 통합.

1.2 subModuleTpCd 추가 (커밋 f022956c)

  • trestles[] 에 Cross Mix 식별용 필드 추가.
  • 단일/동계열은 빈 값.

1.3 moduleTpCd 보존 + dedupe 키 변경 (커밋 795c9789)

  • PCS 접속함 응답의 새 필드 moduleTpCd 를 프론트 상태/제출 파라미터까지 보존.
  • 중복 제거 키를 (itemId, moduleTpCd) 조합으로 변경.

1.4 PassivityCircuitAllocation ref prop 제거

  • forwardRef 미사용 함수형 컴포넌트에 ref 를 prop 으로 넘겨 React warning 이 발생 → 제거.

1.5 [1491] 실내 집중형 PCS 접속함 산출 이상 (커밋 d0590f51, 471093eb)

  • 실내 집중형 PCS 사용 시 접속함이 정상 산출 안 되던 현상 + cvrLmtRow 처마 커버 단수 보정.

1.6 [1749] 모듈 배치 후 회로 설정 오류 (커밋 a11010c0)

  • 배치 후 회로 단계에서 할당 실패하던 케이스 수정.

1.7 [1845] 실내집중형 PCS 수동 회로분할 동일 방위/구배 강제 (커밋 ba92e340)

  • 작성일: 2026-05-06
  • 배경 (HANASYS 보고): HANASYS DESIGN 에서 屋内集中PCS(pcsTpCd === 'INDFCS') + 수동 회로분할 시, 다른 방위 또는 다른 구배의 지붕면 모듈을 같은 직렬회로로 묶을 수 있는 사례. 屋外マルチPCS(OUTDMULTI) 또는 자동분할 경로에서는 정상.
  • 원인: PassivityCircuitAllocation.jsx > handleCircuitNumberFix 의 switch (pcsTpCd) 분기에서 OUTDMULTI 는 surfaceType (방위-구배 키) 검증이 있었으나, INDFCS 는 northModuleYn 만 검증하고 방위/구배 검증 누락.
  • 수정: INDFCS 분기에 surfaceType 누적 검증 추가. 검증 대상은 이번 선택 모듈 + 같은 PCS 의 기존 할당 모듈 합집합 (북면 검사와 동일한 누적 패턴). 그룹 2개 이상이면 alert + return.
  • 신규 메시지 키: module.circuit.fix.not.same.direction.pitch.error (ko / ja). 기존 module.circuit.fix.not.same.roof.error 의 4개 호출지점은 의미가 달라 그대로 유지.
  • 태그: [INDFCS-SAME-ROOF 2026-05-06]
  • 회귀 체크: ① INDFCS 동일 방위/구배 누적 ② INDFCS 1차 동향 후 2차 남향 추가 차단 ③ 북면 혼합 차단(기존) ④ OUTDMULTI 다방위 차단(기존) ⑤ 자동분할 영향 없음.

1.8 [1845] 보정 — 검증 단위를 PCS → 회로번호로 좁힘 (커밋 4ebe4cb4)

  • 작성일: 2026-05-06
  • 배경: 1.7 수정 직후 회귀에서 자동분할 후 수동분할 이어가는 시나리오 차단 발견. 자동으로 회로 1=남(south-5.5) 4장이 부여된 같은 PCS 에, 수동으로 회로 2=서(west-5.5) 4장을 묶으려 하면 alert 차단됨. 회로 1 과 회로 2 는 서로 다른 직렬회로이므로 통과돼야 정상.
  • 원인: 1.7 의 (b) 누적 패턴이 같은 PCS 의 모든 기존 모듈을 합집합 대상으로 잡아, 다른 회로번호까지 검증에 포함됨. HANASYS 보고 본문 "同一の直列回路として構成できてしまう" 에 비춰 보면 검증 단위는 PCS 가 아니라 회로번호 가 맞음.
  • 수정: originHaveThisPcsModules 를 getCircuitNumber() 결과 (이번 부여하려는 회로번호 문자열) 와 일치하는 모듈로 필터링한 sameCircuitExisting 으로 교체. 이번 선택 모듈 + 같은 회로번호 기존 모듈만 합집합 검증.
  • 진단 경로: debugCapture.log('INDFCS-VALIDATION', ...) 임시 삽입 → NEXT_PUBLIC_ENABLE_LOGGING=true 로 재현 → debug/debug.log 에서 uniqueKeys 와 existingSameCircuitCount 확인 후 정식화 시 제거.
  • 태그: [INDFCS-SAME-ROOF 2026-05-06] (1.7 과 동일 태그, 주석에 "보정 2026-05-06" 명시)
  • 회귀 체크 추가: ⑥ 자동(회로 1 = 남) → 수동(회로 2 = 서) 통과 ⑦ 수동에서 같은 회로번호로 다른 방위 묶기는 여전히 차단.

2. 모듈 배치 / 설치 영역

2.1 [1956] 모듈 설치면 제대로 설치 안 되는 현상 (커밋 aa16a45b)

  • 특정 지붕 형태에서 모듈이 자리잡지 못하던 케이스 수정.

2.2 [1830] 모듈 설치영역 대각 발생 (커밋 2101d30d)

  • 모듈 설치 영역 외곽이 대각으로 잘못 잡히던 현상 수정.

2.3 [1805] 설치 영역 / 겹치는 선 (커밋 7b8b995e, fdfa8d52)

  • 설치 영역이 잘못 잡히는 케이스.
  • 겹치는 선이 있을 때 모듈 설치 영역에 이상 발생 → 수정.

2.4 [1798] 배치면 그리기 오류 (커밋 76d3637a)

  • 배치면 그리는 단계에서 발생하던 오류 수정.

2.5 [1807] 거치대 / 낙설 방지 금구 (커밋 1681fd85, 6cf55600)

  • 거치대 선택 시 "낙설 방지 금구 설치" 가 자동으로 체크되는 현상 수정 (1, 2 차).

2.6 [1485] 오브젝트 복사 기능 권한 설정 (커밋 b9bb4708)

  • 복사 기능을 권한 그룹에 따라 제어.

2.7 top / bottom = in 할당 (커밋 13cd9211, f2b527b7)

  • 모듈 할당 정책에서 top·bottom 방향이 in 일 때의 처리.
  • 추가/제외 두 단계로 처리.

2.8 수동 배치 시 자동 물떼세 배치 (커밋 b1c35376, revert 13f10fd1)

  • 한 번 적용했다가 revert 됨. 향후 재적용 시 revert 사유 확인 필요.

3. 처마 / 가대 / 지붕재

3.1 [1455] 처마 커버 표시 (커밋 0e70c3af)

  • 처마 커버 표시 로직 보강.

3.2 처마 커버 설치 이상 (커밋 18083f89)

  • 일부 케이스에서 처마 커버가 잘못 설치되던 현상 수정.

3.3 [1751] 기와 형태 처마 돌출 치수 변경 (커밋 1dd4e0cf)

  • 기와 지붕에서 처마 돌출 치수를 바꿨을 때 동작 보정.

3.4 [1840] 팔작지붕 도면 사례 (커밋 cd5eebd0)

  • 팔작지붕 형태가 생성되지 않던 케이스.

3.5 [1480] 사의 각도 설정 "각도" (커밋 3eaf3f2c, 90228121, dffb8c0d, 4a270ba5, 2514fc92)

  • 사(斜) 각도를 "각도" 단위로 설정했을 때 발생하는 문제. 다회 수정 — 한 번에 안 잡혀서 여러 차례 들어감.

3.6 [1471] (관련) 플랜별 지붕재 변경 저장 (커밋 64ba5ad3)

  • 플랜마다 지붕재를 다르게 저장.

3.7 [1456] 배치면 초기 설정에서 지붕재 / 촌 위치 변경 (커밋 07ce6b6f)

3.8 [1960] 배치도·계통도에 가대 표시 (커밋 4d91da5f, 9c25d3ed)

  • 출력된 배치도/계통도에 가대가 잘못 표시되던 케이스.

3.9 [1971] 외벽선 작성 방향 "반시계 방향" 표기 삭제 (커밋 d15c9e69)

  • UI 표기 정리.

3.10 [1806] 서까래 높이 조정 (커밋 caab0d9d, 01b9625a)

  • 서까래 높이 조정에 따른 지붕 형상 불일치 + 라인 오버 체크 1, 2 차.

3.11 [1961][1969][2118] (커밋 3f5f4908)

  • 묶음 수정.

4. 견적서 / 도면 표기

4.1 [1525] 면형상 배치 치수 표기 이상 (커밋 f77794ce)

4.2 [1482] 도면 흐름 방향 좌우 표시 잘림 (커밋 4b098fa5)

  • 흐름 방향이 좌우로 설정된 경우 도면에서 일부가 잘려 보이던 현상.

4.3 [1482] 플랜 복사 시 견적서에 [하제피치] 표시 (커밋 e912d084)

  • 플랜 복사 시 발생.

4.4 [1470] 배치도·계통도 화질 개선 (커밋 be95b1b3)

  • cell 이미지 추가로 출력 화질 개선.

4.5 [1766] 방위 변경 체크박스 견적서 표기 (커밋 f3bddbea)

4.6 [1423] 설계 가져오기 기능 (커밋 f87bfb90)

  • 다른 설계에서 가져오기.

4.7 [카톡] 견적서 / 물건검색 1차점 숨김 (커밋 a10196f9, 44aca56d)

  • 1차점 사용자에게는 일부 정보 숨기고, 2차점 로그인 사용자에게만 노출.

5. 캔버스 / 좌표 / 일반 버그

5.1 확대 축소 100% 가운데 정렬 (커밋 98440188, 8d9379c3)

5.2 회전 시 길이 계산 반영 안 됨 (커밋 3c702cf5)

5.3 배치면 다수 시 길이 계산 안 됨 (커밋 606acf91)

5.4 혹장 계산 roofLine (커밋 0e4b0b41)

5.5 roofWidth / roofHeight null 문제 (커밋 2cc28147)

5.6 임시저장 폼 — 물건명 50자 제한 (커밋 71da4d07)

5.7 dev 관련 링크 수정 (커밋 a2bbb035, 31b01132)

6. 작업 패턴 — 티켓 시리즈를 다룰 때

이 트랙은 거의 티켓([1xxx]) 단위 국소 수정으로 구성됩니다. 새 티켓이 들어왔을 때:

  1. 재현 시나리오 확보 — 어떤 데이터/플로우에서 발생하는지 명확히 합의.
  2. 유사 티켓 검색 — 같은 영역에서 비슷한 [1xxx] 가 이미 처리됐는지 git log + 본 문서로 확인.
  3. 국소 수정 — SK_MOVEMENT_HANDOVER.md §6 #1 원칙 (잘 되는 코드 안 건드리기) 엄수.
  4. 회귀 검증 — 가까운 시나리오 1~2개 추가로 돌려 보기.
  5. 태그 + 커밋 메시지 — 인라인 [Tagname YYYY-MM-DD] + git commit 메시지 제안 (사용자가 직접 커밋).

7. 미해결 / 추적

  • [1480] 사의 각도 — 5번 수정이 들어간 만큼 완전히 잡혔는지 추적 필요.
  • [1805] 모듈 설치영역 — 겹치는 선 케이스가 다양해 추가 보고 가능성 있음.
  • 수동 물떼세 배치 — revert 후 미적용 상태. 재적용 시 revert 사유부터.

8. 핵심 파일 (영역별 진입점)

영역 핵심 파일/디렉터리
회로/PCS/접속함 src/...PassivityCircuitAllocation*, 회로 hook
모듈 배치 모듈 배치/설치 영역 컴포넌트
처마/가대 processEavesEdge 인근 (skeleton-utils.js) — SK 트랙과 겹침 주의
견적서/도면 출력 컴포넌트
dev/링크 package.json, .env.localhost

(파일 위치는 영역별로 흩어져 있어 git log + 커밋 해시 확인이 가장 빠릅니다.)

9. 인수 직후 권장 절차

  1. 이 문서 통독 → 어느 영역의 티켓이 많은지 감 잡기.
  2. 가장 최근 [1xxx] 커밋 1~2개를 골라 변경 디프 직접 확인.
  3. 인접 영역 티켓이 들어오면 본 문서 + git log 로 유사 사례 먼저 검색.

끝.