# 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, 커밋 `[TBD-CODE]`)

### 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 저장 → 팝업 확인).

끝.