From 2e7c8769aa2fd1e089fb72cd682ffca9272a2564 Mon Sep 17 00:00:00 2001 From: sangwook yoo Date: Mon, 22 Jun 2026 10:48:29 +0900 Subject: [PATCH] ``` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs(outerline): 외벽선 확정(handleFix) 흐름 및 PDF 자동 확정 가이드 문서 추가 ``` - 외벽선 확정 (`handleFix`) 로직의 상세 흐름과 확정 후 캔버스/Recoil 불변 조건을 문서화합니다. - PDF 도면 분석을 통한 외벽선 자동 확정 기능 구현 시 참고할 설계 가이드와 체크리스트를 포함합니다. - `handleFix` 본체와 `useEffect`, `ccwCheck` 등 관련 로직의 역할 및 주의사항을 명확히 합니다. ``` --- docs/외벽선 확정(handleFix) 흐름.md | 284 ++++++++++++++++++++++++++++ 1 file changed, 284 insertions(+) create mode 100644 docs/외벽선 확정(handleFix) 흐름.md diff --git a/docs/외벽선 확정(handleFix) 흐름.md b/docs/외벽선 확정(handleFix) 흐름.md new file mode 100644 index 00000000..72d6d336 --- /dev/null +++ b/docs/외벽선 확정(handleFix) 흐름.md @@ -0,0 +1,284 @@ +# 외벽선 확정 (`handleFix`) 흐름 + +> Q.CAST Floor Plan — **지붕덮개 → 외벽선 그리기** 모달의 **「외벽선 확정」** 버튼이 호출하는 로직 정리. +> PDF/Gemini 도면 분석 후 캔버스에 외벽선을 그린 뒤, 옵션에 따라 이 확정 단계를 자동 실행할 때 참고한다. + +코드 단일 진실 공급원: + +| 역할 | 경로 | +|---|---| +| UI (버튼) | `src/components/floor-plan/modal/outerlinesetting/WallLineSetting.jsx` | +| 핵심 로직 | `src/hooks/roofcover/useOuterLineWall.js` — `handleFix`, `ccwCheck`, `points` `useEffect` | +| 상태 | `src/store/outerLineAtom.js` — `outerLinePointsState`, `outerLineFixState` | +| 라인 생성 | `src/hooks/useLine.js` — `addLine` (QLine + `attributes.planeSize`) | +| PDF 임포트 대응 구현 | `src/hooks/pdf-import/usePdfImport.js` — `applyOuterline` | +| 확정 후 다음 단계 | `src/components/floor-plan/modal/roofShape/RoofShapeSetting.jsx` | + +--- + +## 0. 한눈에 보기 + +``` +[외벽선 그리기 메뉴] → WallLineSetting 모달 + ↓ (클릭/Enter) + SweetAlert 확인 (modal.cover.outline.fix.confirm) + ↓ confirm + handleFix() — 닫힘 정점 추가 + isFix.current = true + ↓ (points useEffect) + outerLine QLine 재생성 + outerLinePoint circle + ↓ isFix.current === true + outerLineFix 플래그 ON → 모달 닫기 → ccwCheck → 지붕형상 설정 모달 오픈 +``` + +**확정 직후 캔버스/Recoil이 만족해야 하는 불변 조건** (PDF 자동 확정도 동일): + +1. `canvas` 객체 중 `name === 'outerLine'` 인 QLine ≥ 2 (닫힌 다각형) +2. `name === 'outerLinePoint'` 인 fabric.Circle (정점, `visible: false`) +3. `canvas.outerLineFix === true` **및** Recoil `outerLineFixState === true` +4. 외벽선 정점 순서는 **반시계(CCW)** — `ccwCheck` 또는 동등 전처리 +5. QLine 은 반드시 `useLine.addLine` 경유 — `attributes.planeSize`, `fontSize` 없으면 지붕형상·처마/케라바·저장 복원 깨짐 +6. 좌표에 **축소 scale 을 곱하지 않음** — `QLine.length × 10 = 표시 mm` 불변식 유지 + +--- + +## 1. UI 진입점 + +### 1-1. 모달·버튼 + +- 컴포넌트: `WallLineSetting` (`WithDraggable`, class `r`) +- 메뉴 진입: `useMenu` → `currentMenu === EXTERIOR_WALL_LINE` → `addPopup(..., )` +- 버튼 DOM: `div.grid-btn-wrap > button.btn-frame.modal.act` +- i18n 키: `modal.cover.outline.fix` (ko: 「외벽선 확정」) + +### 1-2. 클릭 핸들러 + +확정 버튼은 **즉시** `handleFix` 를 부르지 않고, 확인 다이얼로그를 거친다. + +```jsx +// WallLineSetting.jsx +swalFire({ + type: 'confirm', + text: getMessage('modal.cover.outline.fix.confirm'), + confirmFn: handleFix, +}) +``` + +동일 확인은 `useOuterLineWall.enterCheck` (Enter 키) 에서도 사용한다. + +> **자동 확정 구현 시**: 사용자 확인이 필요 없으면 `swalFire` 를 생략하고 `handleFix` 또는 아래 §5 의 「확정 후처리」만 직접 호출하면 된다. + +--- + +## 2. `handleFix` 본체 + +파일: `useOuterLineWall.js` + +### 2-1. 사전 조건·검증 + +| 단계 | 조건 | 실패 시 | +|---|---|---| +| 1 | `points.length >= 3` | `return` (무발화) | +| 2 | 모든 꼭짓점이 첫 점 기준 직각(각도 % 90 === 0) | `return` — 축정렬 직사각형만으로 닫힌 경우 확정 불가 | + +검증 통과 후: + +```javascript +setPoints((prev) => [...prev, { x: prev[0].x, y: prev[0].y }]) // 폐곡선: 마지막 = 첫 점 +isFix.current = true +``` + +- `points` 는 Recoil `outerLinePointsState` +- `isFix.current` 는 ref — **다음 `points` useEffect 한 번**에서만 소비된다 (자동으로 false 로 리셋되지 않음; 훅 unmount 전까지 true 유지) + +### 2-2. `handleFix` 가 직접 하지 **않는** 일 + +다음은 모두 **`useEffect([points])`** 와 **`ccwCheck`** 에 위임된다. + +- Fabric `outerLine` / `outerLinePoint` 생성 +- `outerLineFixState` / `canvas.outerLineFix` 설정 +- 마우스·키보드 이벤트 해제 +- `WallLineSetting` 모달 닫기 +- `RoofShapeSetting` 모달 열기 + +--- + +## 3. `points` 변경 시 useEffect (확정의 실질 후처리) + +`points` 가 바뀔 때마다 실행된다. 확정 **이전**에도 그리기 미리보기 역할을 한다. + +### 3-1. 공통 (매 `points` 변경) + +1. 기존 `outerLine`, `helpGuideLine` 제거 (`removeLine`) +2. `startPoint` 제거 +3. `points.length === 0` → `setOuterLineFix(true)` 후 return (초기화 경로) +4. `points.length === 1` → 시작점 빨간 circle (`startPoint`) +5. `points.length >= 2`: + - `setOuterLineFix(false)` — **그리는 중에는 미확정** + - `outerLinePoint` circle 생성 (`visible: false`) + - 인접 정점 쌍마다 `drawLine` → `addLine` (`name: 'outerLine'`, `strokeWidth: 3`, …) + - 3점 이상이면 닫힘 가이드 (`helpGuideLine`, 회색 점선) + +### 3-2. 확정 분기 (`isFix.current === true`) + +```javascript +if (isFix.current) { + removeAllMouseEventListeners() + removeAllDocumentEventListeners() + canvas?.renderAll() + setOuterLineFix(true) + canvas.outerLineFix = true + closePopup(id) // WallLineSetting 닫기 + ccwCheck() // §4 + addPopup(propertiesId, 1, ) +} +``` + +**수동 플로우 확정 후 사용자가 보는 화면**: 외벽선 그리기 모달 종료 → **지붕형상 설정** 모달 자동 오픈. + +--- + +## 4. `ccwCheck` — 정점 순서 보정 + +확정 직후 호출. 외벽선이 **시계 방향**이면 **반시계**로 뒤집는다. + +1. `canvas.getObjects()` 에서 `name === 'outerLine'` 필터 +2. `outerLines.length < 2` → `wall.line.not.found` 알림 후 return +3. Shoelace signed area 로 CCW 판별 (`signedArea > 0` → CW) +4. CW 이면 각 라인을 `[x2,y2,x1,y1]` 로 **역방향 재생성** (`addLine` + 기존 line `remove`) + +PDF 임포트(`usePdfImport.ensureCounterClockwise`)는 **정점 배열** 단계에서 동일 목적을 수행한다. 캔버스에 이미 그려진 뒤라면 `ccwCheck` 와 결과가 같아야 한다. + +--- + +## 5. PDF 자동 확정 — `handleFix` 와의 대응 + +현재 `usePdfImport.applyOuterline` 은 **수동 확정 직후 캔버스 상태**까지는 맞추지만, **`handleFix` 전체를 호출하지는 않는다**. + +| 수동 `handleFix` 후 | `applyOuterline` 현재 | 자동 확정 옵션 추가 시 | +|---|---|---| +| SweetAlert 확인 | PDF 덮어쓰기 확인만 | 옵션으로 생략/유지 선택 | +| `points` 에 닫힘점 추가 | `closedPoints = [...pts, pts[0]]` + `setOuterLinePoints` | 동일 | +| `useEffect` 로 QLine 재그리기 | `drawOuterLines` (`addLine` 동일 옵션) | 동일 | +| `outerLinePoint` circle | `drawOuterLinePoints` | 동일 | +| `canvas.outerLineFix` + `outerLineFixState` | ✅ 설정함 | ✅ 필수 | +| `ccwCheck` | `ensureCounterClockwise` (정점 단계) | 라인 그린 뒤 CW 이면 `ccwCheck` 또는 정점 보정 | +| `closePopup(WallLineSetting)` | 해당 모달 없음 | 불필요 | +| `RoofShapeSetting` 모달 오픈 | ❌ **안 함** | 옵션 `autoFix: true` 시 `addPopup` 으로 직행 | +| `fitViewport` + `canvasZoomState` | ✅ PDF 전용 | 수동 확정에는 없음 — PDF 유지 | +| 마우스 리스너 제거 | 그리기 모드 미사용 | 불필요 | + +`PlacementShapeSetting` PDF 분기는 메뉴만 `ROOF_SHAPE_SETTINGS` 로 보내고, **지붕형상 모달 자동 오픈은 하지 않는다** — 자동 확정 옵션은 별도 구현이 필요하다. + +참고: `CLAUDE.md` PDF 임포트 절 — 「수동 외벽선 확정(`useOuterLineWall.handleFix`) 직후와 동일한 상태」. + +--- + +## 6. 자동 확정 구현 가이드 (권장) + +### 6-1. `handleFix` 를 그대로 호출하지 **말** 것 + +`handleFix` 는 `useOuterLineWall` 훅 내부에 묶여 있고, 전제 조건이 다르다. + +- Recoil `outerLinePointsState` 가 **미닫힌** 정점 배열이어야 함 (마지막 ≠ 첫 점) +- `WallLineSetting` 모달이 마ounted 되어 `propertiesId` 로 `RoofShapeSetting` 을 열어야 함 +- 직각-only 다각형이면 조용히 실패 + +PDF 경로는 이미 **닫힌 폴리곤 + 라인 객체**가 있으므로, 훅 밖에서 후처리하는 편이 안전하다. + +### 6-2. 권장: 공통 「확정 후처리」 추출 (미래 리팩터) + +아래를 `finalizeOuterLine({ canvas, points, options })` 같은 유틸/훅으로 묶으면 수동·PDF·자동 옵션이 한 경로를 탄다. + +```text +입력: closedPoints (첫점=끝점 포함 가능, drawOuterLines 기준 인접쌍) +1. clearExisting outerLine / outerLinePoint (필요 시) +2. drawOuterLines(closedPoints) // useLine.addLine +3. drawOuterLinePoints(closedPoints) +4. CCW 보정 (정점 또는 ccwCheck) +5. canvas.outerLineFix = true; setOuterLineFix(true) +6. canvas.renderAll() +7. [옵션] fitViewport +8. [옵션] addPopup(RoofShapeSetting) +``` + +### 6-3. 최소 변경 (현재 코드베이스) + +`applyOuterline` 의 `proceed()` 끝에 옵션 분기만 추가: + +```javascript +// options.autoOpenRoofShape === true 일 때 +const roofShapeId = uuidv4() +addPopup(roofShapeId, 1, ) +setCurrentMenu(MENU.ROOF_COVERING.ROOF_SHAPE_SETTINGS) // 메뉴 탭 동기화 +``` + +`usePopup` / `useMenu` 의존은 `usePdfImport` 또는 호출측(`PdfImportModal`, `PlacementShapeSetting`)에서 주입. + +### 6-4. 검증 체크리스트 (자동 확정 후) + +- [ ] `canvas.getObjects().filter(o => o.name === 'outerLine').length >= 3` +- [ ] 각 QLine 에 `attributes.planeSize` 존재 +- [ ] `canvas.outerLineFix === true` +- [ ] `useRoofShapeSetting` 마운트 시 `wall.line.not.found` 미발생 +- [ ] 치수 라벨(mm)이 실측과 일치 (scale 미적용) +- [ ] 외벽선 그리기 메뉴 재진입 시 `setOuterLineFix(false)` 로 **재편집 모드**로 떨어지지 않도록 — PDF 플로우는 `ROOF_SHAPE_SETTINGS` 메뉴 유지 (`PlacementShapeSetting` 참고) + +--- + +## 7. 관련 Recoil / Canvas 플래그 + +| 키 | 타입 | 확정 전 (그리기 중) | 확정 후 | +|---|---|---|---| +| `outerLinePointsState` | `{x,y}[]` | 미닫힘 정점들 | 닫힘(마지막=첫점) 또는 동일 좌표의 closed ring | +| `outerLineFixState` | `boolean` | `false` (2점 이상) | `true` | +| `canvas.outerLineFix` | `boolean` (canvas 커스텀) | `false` | `true` — 직렬화/가드에 사용 (`common.js` `'outerLineFix'`) | + +`canvasAtom` 의 selector 는 `outerLineFix === false` 이거나 points 비어 있으면 특정 UI를 잠근다. + +--- + +## 8. 확정 이후 파이프라인 + +``` +handleFix 완료 + → RoofShapeSetting (useRoofShapeSetting) + → WALL/ROOF 폴리곤 생성, pitchText, 처마/케라바 타입 + → (이후) 보조선, 처마·케라바 편집, 배치면 … +``` + +`useRoofShapeSetting` 진입 가드: + +```javascript +if (!canvas.outerLineFix || outerLines.length === 0) { + swalFire({ text: getMessage('wall.line.not.found') }) + closePopup(id) +} +``` + +자동 확정 없이 `outerLineFix` 만 켜 두면 메뉴는 지붕형상으로 가도 **모달을 열어 주지 않으면** 사용자는 수동으로 메뉴를 눌러야 한다. + +--- + +## 9. 유사 이름 주의 (`handleFix` 동명이인) + +| 훅 | 용도 | +|---|---| +| **`useOuterLineWall.handleFix`** | **본 문서 대상** — 외벽선 그리기 확정 | +| `usePropertiesSetting.handleFix` | 외벽선 **속성**(처마/케라바) 확정 — 다른 모달 | +| `usePlacementShapeDrawing.handleFix` | 배치면 그리기 확정 | +| `useRoofLinePropertySetting.handleFix` | 지붕선 속성 확정 | +| `useAuxiliaryDrawing.handleFix` | 보조선 확정 | + +DOM class `btn-frame modal act` + 「외벽선 확定/외벽선 확정」은 **`WallLineSetting`** 과 **`PlacementShapeDrawing`** 등에서 공유 메시지 키를 쓸 수 있다. DOM path `modal-pop-wrap r` + `useOuterLineWall` 이면 **본 문서** 대상이다. + +--- + +## 10. 참고 문서·코드 + +- `docs/PDF Gemini 평면도 분석 기능 구현 계획.md` — PDF → 캔버스 반영 전체 +- `docs/Canvas Status.md` — §2.1 외벽선 그리기, §2.2 지붕형상 설정 +- `CLAUDE.md` — PDF 임포트 불변식 (scale, `addLine`, `outerLineFix`) + +--- + +*작성: 2026-06-19 — PDF 자동 외벽선 확정 기능 설계용*