ERP-node/popdocs/archive/V4_CORE_RULES.md

# POP v4 핵심 규칙 가이드

## 개요

v4에서는 **"위치"를 설정하는 게 아니라 "규칙"을 설정**합니다.

```
v3 (기존): 4개 모드 각각 컴포넌트 위치 설정 → 4배 작업량
v4 (신규): 3가지 규칙만 설정 → 모든 화면 자동 적응
```

---

## 핵심 규칙 3가지

### 1. 크기 규칙 (Size Rules)

각 컴포넌트의 **너비**와 **높이**를 어떻게 결정할지 정합니다.

| 모드 | 설명 | 예시 |
|------|------|------|
| **fixed** | 고정 px | 버튼 높이 48px |
| **fill** | 부모 공간 채움 | 입력창 너비 = 화면 너비 |
| **hug** | 내용에 맞춤 | 라벨 너비 = 텍스트 길이 |

```typescript
// 예시: 버튼
{
  width: "fill",      // 화면 너비에 맞춤
  height: "fixed",    // 고정
  fixedHeight: 48     // 48px
}

// 예시: 라벨
{
  width: "hug",       // 텍스트 길이만큼
  height: "hug"       // 텍스트 높이만큼
}
```

#### 크기 모드 시각화

```
fixed (고정):
├────48px────┤
┌────────────┐
│   버튼     │ ← 화면 커져도 48px 유지
└────────────┘

fill (채움):
├─────────────────────────────────┤
┌─────────────────────────────────┐
│         입력창                   │ ← 화면 크기에 맞춤
└─────────────────────────────────┘

hug (맞춤):
├──────┤
┌──────┐
│라벨  │ ← 내용 길이만큼만
└──────┘
```

---

### 2. 배치 규칙 (Layout Rules)

컴포넌트들을 **어떻게 나열할지** 정합니다.

#### 스택 방향

```
가로 스택 (horizontal):        세로 스택 (vertical):
┌─────┬─────┬─────┐           ┌─────────────┐
│  A  │  B  │  C  │           │      A      │
└─────┴─────┴─────┘           ├─────────────┤
                               │      B      │
                               ├─────────────┤
                               │      C      │
                               └─────────────┘
```

#### 설정 항목

| 항목 | 설명 | 옵션 |
|------|------|------|
| **direction** | 스택 방향 | horizontal / vertical |
| **wrap** | 줄바꿈 허용 | true / false |
| **gap** | 요소 간 간격 | 8 / 16 / 24 px |
| **alignItems** | 교차축 정렬 | start / center / end / stretch |
| **justifyContent** | 주축 정렬 | start / center / end / space-between |

```typescript
// 예시: 버튼 그룹 (가로 배치)
{
  direction: "horizontal",
  wrap: true,           // 공간 부족하면 줄바꿈
  gap: 16,              // 버튼 간격 16px
  alignItems: "center"  // 세로 중앙 정렬
}
```

---

### 3. 반응형 규칙 (Responsive Rules)

**화면이 좁아지면** 어떻게 바꿀지 정합니다.

```typescript
// 예시: 768px 이하면 가로→세로 전환
{
  direction: "horizontal",
  responsive: [
    {
      breakpoint: 768,      // 768px 이하일 때
      direction: "vertical" // 세로로 바꿈
    }
  ]
}
```

#### 시각화

```
768px 이상 (태블릿):          768px 이하 (모바일):
┌─────┬─────┬─────┐          ┌─────────────┐
│  A  │  B  │  C  │    →     │      A      │
└─────┴─────┴─────┘          │      B      │
                              │      C      │
                              └─────────────┘
```

---

## 실제 예시: 작업지시 화면

### 규칙 설정

```typescript
{
  root: {
    type: "stack",
    direction: "vertical",
    gap: 16,
    padding: { top: 16, right: 16, bottom: 16, left: 16 },
    children: ["header", "form", "buttons"]
  },
  
  containers: {
    "header": {
      type: "stack",
      direction: "horizontal",
      alignItems: "center",
      children: ["title", "status"]
    },
    "form": {
      type: "stack",
      direction: "vertical",
      gap: 12,
      children: ["field1", "field2", "field3"]
    },
    "buttons": {
      type: "stack",
      direction: "horizontal",
      gap: 12,
      responsive: [
        { breakpoint: 480, direction: "vertical" }
      ],
      children: ["cancelBtn", "submitBtn"]
    }
  },
  
  components: {
    "title": { width: "hug", height: "hug" },
    "status": { width: "hug", height: "hug" },
    "field1": { width: "fill", height: "fixed", fixedHeight: 48 },
    "field2": { width: "fill", height: "fixed", fixedHeight: 48 },
    "field3": { width: "fill", height: "fixed", fixedHeight: 48 },
    "cancelBtn": { width: "fill", height: "fixed", fixedHeight: 48 },
    "submitBtn": { width: "fill", height: "fixed", fixedHeight: 48 }
  }
}
```

### 결과

```
태블릿 가로 (1024px)              모바일 세로 (375px)
┌──────────────────────────┐     ┌─────────────────┐
│ 작업지시 #1234    [진행중]│     │작업지시   [진행]│
├──────────────────────────┤     ├─────────────────┤
│ [품번____________]       │     │[품번_________]  │
│ [품명____________]       │     │[품명_________]  │
│ [수량____________]       │     │[수량_________]  │
├──────────────────────────┤     ├─────────────────┤
│ [취소]        [작업완료] │     │[취소]           │
└──────────────────────────┘     │[작업완료]       │
                                 └─────────────────┘
```

---

## v3 vs v4 비교

| 항목 | v3 (기존) | v4 (신규) |
|------|----------|----------|
| **설계 방식** | 4개 모드 각각 위치 설정 | 3가지 규칙 설정 |
| **작업량** | 4배 | 1배 |
| **데이터** | col, row, colSpan, rowSpan | width, height, direction, gap |
| **반응형** | 수동 (모드별 설정) | 자동 (브레이크포인트) |
| **유지보수** | 4곳 수정 | 1곳 수정 |

---

## 규칙 설계 체크리스트

### 크기 규칙
- [ ] 터치 요소(버튼, 입력창) 높이: fixed 48px
- [ ] 너비가 화면에 맞아야 하는 요소: fill
- [ ] 내용 길이에 맞아야 하는 요소: hug

### 배치 규칙
- [ ] 컴포넌트 나열 방향 결정 (가로/세로)
- [ ] 간격 설정 (8/16/24px)
- [ ] 정렬 방식 결정 (start/center/stretch)

### 반응형 규칙
- [ ] 768px 이하에서 가로→세로 전환 필요한 곳
- [ ] 480px 이하에서 추가 조정 필요한 곳

---

## 관련 문서

- [반응형 디자인 가이드](./RESPONSIVE_DESIGN_GUIDE.md) - 크기 기준
- [크기 프리셋](./SIZE_PRESETS.md) - 컴포넌트별 기본값
- [v4 구현 계획](./POP_V4_CONSTRAINT_SYSTEM_PLAN.md) - 전체 계획

---

*최종 업데이트: 2026-02-04*