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

6.9 KiB
Raw Blame History

UI / 모달 / 다이얼로그 인수인계서

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

이 문서의 범위: 모달/다이얼로그/계산기 토글/라인 표시 같은 UI 트랙만 다룹니다. 다른 트랙은 HANDOVER_INDEX.md 참조.

0. 한 줄 요약

여러 입력 모달에 계산기 패드 토글 버튼을 추가하고, 외벽선/평면도 같은 중요한 단계에 확정 다이얼로그를 붙이고, 라인 라벨/색/인덱스 표시를 정돈한 트랙입니다.

1. 계산기 패드 토글 — 대규모 시리즈

사용자가 모달의 숫자 입력 칸을 누르면 계산기 패드가 떠야 하는 요구사항이 있어, 거의 모든 입력 모달에 토글 버튼을 추가했습니다.

1.1 적용된 모달

모달 커밋
補助線 사이즈변경 / 이동 / 복사 60cb8691
サイズ変更 (사이즈 변경) bc389e3a
モジュール / 架台設定 (모듈/거치대) b10fc270
配置面初期設定 (배치면 초기 설정) 025b7ede
屋根形状の設定 (지붕 형상 설정) ebc6181b
オブジェクト配置 (오브젝트 배치) 678b9442
물건 등록 3365000b, 662a4653
견적서 ea849ee5
일반 (공통) 1d4d1ab3

1.2 동작

  • 입력 칸 옆 계산기 아이콘 클릭 → 키패드 표시/숨김 토글
  • 키패드는 + - × ÷ 사칙 연산 + 즉시 반영

1.3 주의

  • 모달마다 입력 컴포넌트 구조가 조금씩 달라서 공통 컴포넌트 한 개로 통합돼 있지 않습니다. 같은 패턴이 여러 모달에 반복 구현돼 있어요.
  • 새 모달에 추가할 때는 가장 비슷한 모달의 코드를 베이스로 잡으세요.

2. 일본어 모달 토글 추가 시리즈

UI 옵션을 켜고 끄는 토글 스위치를 일본어 모달들에 추가한 별도 시리즈입니다.

모달 커밋
外壁の編集とオフセット (외벽 편집/오프셋) 6967b8cd
棟線移動・桁上げ下げ (마루 이동/도리 올리기 내리기) 84ac6d50
軒/ケラバ変更 (처마/박공 변경) 94f050d9
補助線の作成 (보조선 작성) 2c19a208, a0cac795

3. 확정 다이얼로그 — 외벽선 / 평면도

3.1 외벽선 확정

  • 커밋 7d1e49a1
  • 외벽선 작성을 끝낼 때 "확정하시겠습니까?" 다이얼로그.
  • 버튼 클릭 + Enter 키 양쪽 다 지원.

3.2 평면도 확정

  • 커밋 0e3acedf
  • 평면도 단계 종료 시 같은 패턴.

3.3 왜 추가했나

  • 사용자가 실수로 다음 단계로 넘어가면 앞 단계로 되돌리기 어려운 작업이 있습니다. 그래서 명시적으로 확정 단계를 둠.

4. 라인 오버 → 평행 라인 자동 전환

  • 커밋 26b583e2
  • 사용자가 외벽선을 너무 많이 끌면 평행 라인까지만 잘라서 자동 변환.
  • SK 트랙의 clamp 정책(SK_MOVEMENT_HANDOVER.md §8.1)과 같은 사용자 경험을 만들어주는 UI 측 동작.

5. 라인 표시·관리 정리 (작은 작업 모음)

항목 커밋
잔여선 삭제 + 라벨 표시 (local) 1d00e000
라인 줄 표시 / 인덱스 재설치 8fef6c9f, 428ff36a
라인 색 정리 02c8422e
동일 라벨 처리 c2215157
innerLine 정리 c2eba138
라벨 변경 376ccab8
빌드 오류 수정 — debugLabels import 제거 (정책 정착 계기) 6b02b2ca

debugLabels 별도 파일 금지 정책이 여기서 정착됐습니다 (SK_MOVEMENT_HANDOVER.md §6 #7 원칙). 디버그 라벨은 반드시 QPolygon.js 인라인 + NEXT_PUBLIC_RUN_MODE === 'local' 가드.

6. 보조라인 / SK 라인 기록 보존

  • 3c1a1f89 보조라인 맞춤
  • 7a987116 SK 라인 기록 보존
  • 사용자가 추가한 라인이 SK 재계산에서 사라지면 안 된다는 정책의 연장선 (SK 트랙 §5.1 미완료와 연계).

7. 배치 / 지붕 이동 보강

항목 커밋
배치면 이동 시 화살표 위치 수정 8eca824c
지붕 이동 시 보조선 길이 안 따라가는 현상 21f25995
offset ↔ moveline 벽라인 정상 이동 20235ac2
움직인 라인 그대로 유지 offset 94f18d15

8. 핵심 파일

파일 역할
補助線 모달 컴포넌트 계산기 토글 (커밋 60cb8691 으로 정확 위치 확인)
src/components/fabric/QPolygon.js 라인 표시·라벨 (인라인 디버그 라벨 포함)
src/hooks/roofcover/useMovementSetting.js 라인 오버 시 평행 변환 등 이동 UX

9. 저구배 + 특정 기와 시공 매뉴얼 안내 (2026-05-06, 커밋 a5d2964e)

9.1 무엇을

6종 기와 제품을 저구배 (2 ≤ 寸 < 2.5 또는 11.31° ≤ 角度 < 14.04°) 로 사용하려 할 때, 저장 직전에 시공 매뉴얼 확인 안내 alert 을 띄움 (OK 만 — 중단 흐름 없음).

9.2 트리거 3 곳

# 트리거 핸들러
1 配置面 초기설정 → 「保存」 PlacementShapeSetting.jsx handleSaveBtn
2 平面図入力 → 「屋根面の割り当て」 useRoofAllocationSetting.js handleSave
3 ［配置面］屋根材変更 → 「屋根面の割り当て」 useRoofAllocationSetting.js handleSaveContext

9.3 대상 屋根材 6종 (getRoofMaterialList 응답 기준)

ROOF_ID_WA_53A (和瓦A), ROOF_ID_WA_53B (和瓦B), ROOF_ID_HIRA_C (平板瓦C), ROOF_ID_HIRA_D (平板瓦D), ROOF_ID_HIRA_S (S瓦), ROOF_ID_HIRA_SEME (セメント瓦)

9.4 동작

  • 안내 alert (OK 만). 중단 흐름 없음 — OK 누르면 저장 진행.
  • 등록된 지붕재가 여러 개일 경우, 해당 항목마다 순차로 alert.
  • 세션 캐시 없음 — 트리거마다 매번 표시.

9.5 핵심 파일

파일 역할
src/util/roof-pitch-warning.js LOW_PITCH_RESTRICTED_ROOF_IDS Set + isLowPitchRestricted + notifyLowPitchRestrictionForRoofs
src/locales/{ko,ja}.json i18n 키 modal.roof.material.low.pitch.warning

9.6 임계 변경 시 주의

  • 寸 / 度 둘 다 OR 조건. roofAngleSet 이 'slope' 면 pitch 만, 'flat' 이면 angle 만 갱신될 수 있어서.
  • 6종 ID 변경은 LOW_PITCH_RESTRICTED_ROOF_IDS 만 수정하면 됨. 트리거 3개 핸들러는 수정 불필요.

10. 인수 직후 권장 절차

  1. 이 문서 통독.
  2. 계산기 토글 모달 1개 (예: 보조선 사이즈변경) 직접 띄워서 동작 확인.
  3. 외벽선 확정 다이얼로그 동작 확인 (Enter 키 포함).
  4. 라인 오버 → 평행 자동 전환 확인 (SK 트랙 §8.1 와 함께).
  5. 저구배 + 6종 기와 confirm 동작 확인 (배치면 초기설정에서 和瓦A + 寸=2 저장 → 팝업 확인).

끝.