ERP-node/popdocs/decisions/004-grid-guide-integration.md

ADR-004: 그리드 가이드 CSS Grid 통합

상태: 승인됨 날짜: 2026-02-05 결정자: 개발팀

---

컨텍스트

그리드 가이드는 다음 목적을 가짐:

1. 시각적 기준: 어디에 배치할지 눈으로 확인 가능
2. 정렬 도움: 칸에 맞춰 배치하기 쉬움
3. 디자인 일관성: 규칙적인 배치 유도

기존 구현:

• GridGuide.tsx: SVG <line> 요소로 격자선 렌더링
• PopRenderer.tsx: CSS Grid로 컴포넌트 배치

---

문제

좌표계 불일치

SVG 좌표: 픽셀 기반 (0, 0) ~ (width, height)
CSS Grid 좌표: 칸 기반 (col 1~12, row 1~20)

→ 두 좌표계를 정확히 동기화하기 어려움
→ 격자선과 컴포넌트가 정렬되지 않음 ("무늬가 따로 논다")

구체적 증상

1. GridGuide의 행/열 라벨이 4부터 시작 (잘못된 계산)
2. 격자선 위치와 실제 CSS Grid 셀 위치 불일치
3. 줌/패닝 시 두 레이어가 다르게 동작

---

결정

GridGuide.tsx를 삭제하고, PopRenderer.tsx에서 CSS Grid 기반으로 격자를 직접 렌더링한다.

핵심 원칙:

"격자선은 컴포넌트와 같은 좌표계에서 태어나야 한다"

---

대안 검토

Option A: SVG 계산 수정

• 방법: GridGuide의 좌표 계산을 정확히 수정
• 장점: 기존 코드 활용
• 단점: 근본적으로 두 좌표계가 다름, 유지보수 어려움
• 결정: 채택 안 함

Option B: PopRenderer에 CSS 배경 격자

• 방법: background-image: linear-gradient()로 격자 표현
• 장점: 구현 간단
• 단점: 라벨 표시 불가, 셀 단위 상호작용 불가
• 결정: 채택 안 함

Option C: CSS Grid 셀로 격자 렌더링 (채택)

• 방법: 실제 div 요소를 12x20 = 240개 생성, CSS Grid로 배치
• 장점:
  • 컴포넌트와 100% 동일한 좌표계
  • 셀 단위 hover, 클릭 등 상호작용 가능
  • 라벨은 캔버스 외부에 별도 렌더링
• 단점: DOM 요소 증가 (240개)
• 결정: 채택

---

구현 상세

역할 분담

컴포넌트	역할	좌표계
PopRenderer	격자 셀 + 컴포넌트	CSS Grid
PopCanvas	라벨 + 줌/패닝 + 토글	absolute
GridGuide	(삭제)	-

PopRenderer 변경

// gridCells 생성 (useMemo)
const gridCells = useMemo(() => {
  const cells = [];
  for (let row = 1; row <= 20; row++) {
    for (let col = 1; col <= 12; col++) {
      cells.push({ id: `${col}-${row}`, col, row });
    }
  }
  return cells;
}, []);

// 렌더링
{showGridGuide && gridCells.map(cell => (
  <div
    key={cell.id}
    className="border border-dashed border-blue-300/40"
    style={{
      gridColumn: cell.col,
      gridRow: cell.row,
    }}
  />
))}

PopCanvas 라벨 구조

    [1] [2] [3] [4] [5] [6] [7] [8] [9] [10][11][12]  ← 열 라벨 (캔버스 상단)
    ┌───────────────────────────────────────────┐
[1] │   │   │   │   │   │   │   │   │   │   │   │
[2] │   │   │   │   │   │   │   │   │   │   │   │
[3] │   │   │   │ ■ │   │   │   │   │   │   │   │  ← 5열 3행
    └───────────────────────────────────────────┘
 ↑ 행 라벨 (캔버스 좌측)

---

결과

기대 효과

1. 격자선과 컴포넌트 100% 정렬
2. 정확한 행/열 번호 표시 (1부터 시작)
3. 줌/패닝 시 일관된 동작
4. 향후 셀 클릭으로 빠른 배치 기능 확장 가능

트레이드오프

• DOM 요소 240개 추가 (성능 영향 미미)
• GridGuide 코드 삭제 필요

---

관련 문서

• 문제: PROBLEMS.md > P004
• 변경: CHANGELOG.md > 2026-02-05 오후
• 세션: sessions/2026-02-05.md