ERP-node/docs/screen-implementation-guide/_TEMPLATE.md

# [화면명]

> Screen ID: /screens/XXX
> 메뉴 경로: [L2 메뉴] > [L3 메뉴]

## 1. 테이블 선택 및 화면 구조

### 1.1 사용 테이블

| 테이블명 | 용도 | 비고 |
|----------|------|------|
| `table_name` | 마스터 데이터 | 주 테이블 |
| `detail_table` | 디테일 데이터 | FK: master_id |

### 1.2 테이블 관계

```
┌─────────────────┐       ┌─────────────────┐
│  master_table   │       │  detail_table   │
├─────────────────┤       ├─────────────────┤
│ id (PK)         │──1:N──│ master_id (FK)  │
│ name            │       │ id (PK)         │
│ ...             │       │ ...             │
└─────────────────┘       └─────────────────┘
```

### 1.3 화면 구조 개요

- **화면 유형**: [목록형 / 마스터-디테일 / 단일 폼 / 복합]
- **주요 기능**: [CRUD / 조회 / 집계 등]

---

## 2. 컴포넌트 배치도

### 2.1 전체 레이아웃

```
┌─────────────────────────────────────────────────────────────┐
│ [검색 영역] v2-table-search-widget                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│ [메인 테이블] v2-table-list                                 │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│ [버튼 영역] v2-button-primary (신규, 저장, 삭제)            │
└─────────────────────────────────────────────────────────────┘
```

### 2.2 컴포넌트 목록

| 컴포넌트 ID | 컴포넌트 타입 | 역할 |
|-------------|---------------|------|
| `search-widget` | v2-table-search-widget | 검색 필터 |
| `main-table` | v2-table-list | 데이터 목록 |
| `btn-new` | v2-button-primary | 신규 등록 |
| `btn-save` | v2-button-primary | 저장 |
| `btn-delete` | v2-button-primary | 삭제 |

---

## 3. 각 컴포넌트별 설정

### 3.1 v2-table-search-widget

```json
{
  "targetTableId": "main-table",
  "searchFields": [
    {
      "field": "name",
      "label": "이름",
      "type": "text"
    },
    {
      "field": "status",
      "label": "상태",
      "type": "select",
      "options": [
        { "value": "active", "label": "활성" },
        { "value": "inactive", "label": "비활성" }
      ]
    }
  ]
}
```

### 3.2 v2-table-list

```json
{
  "tableName": "master_table",
  "columns": [
    {
      "field": "id",
      "headerName": "ID",
      "width": 80,
      "visible": false
    },
    {
      "field": "name",
      "headerName": "이름",
      "width": 150
    },
    {
      "field": "status",
      "headerName": "상태",
      "width": 100
    }
  ],
  "features": {
    "checkbox": true,
    "pagination": true,
    "sorting": true
  },
  "pagination": {
    "pageSize": 20
  }
}
```

### 3.3 v2-button-primary (저장)

```json
{
  "label": "저장",
  "actionType": "save",
  "variant": "default",
  "afterSaveActions": ["refreshTable"]
}
```

---

## 4. 컴포넌트 연동 설정

### 4.1 이벤트 흐름

```
[검색 입력]
    │
    ▼
v2-table-search-widget
    │ onFilterChange
    ▼
v2-table-list (자동 재조회)
    │
    ▼
[데이터 표시]
```

### 4.2 연동 설정

| 소스 컴포넌트 | 이벤트/액션 | 대상 컴포넌트 | 동작 |
|---------------|-------------|---------------|------|
| search-widget | onFilterChange | main-table | 필터 적용 |
| btn-save | click | main-table | refreshTable |

---

## 5. 사용자 사용 예시 시나리오

### 시나리오 1: 데이터 조회

| 단계 | 사용자 동작 | 기대 결과 |
|------|-------------|-----------|
| 1 | 화면 진입 | 전체 목록 표시 |
| 2 | 검색어 입력 | 필터링된 결과 표시 |
| 3 | 정렬 클릭 | 정렬 순서 변경 |

### 시나리오 2: 데이터 등록

| 단계 | 사용자 동작 | 기대 결과 |
|------|-------------|-----------|
| 1 | [신규] 버튼 클릭 | 등록 모달/폼 표시 |
| 2 | 데이터 입력 | 입력 필드 채움 |
| 3 | [저장] 버튼 클릭 | 저장 완료, 목록 갱신 |

### 시나리오 3: 데이터 수정

| 단계 | 사용자 동작 | 기대 결과 |
|------|-------------|-----------|
| 1 | 행 더블클릭 | 수정 모달/폼 표시 |
| 2 | 데이터 수정 | 필드 값 변경 |
| 3 | [저장] 버튼 클릭 | 저장 완료, 목록 갱신 |

### 시나리오 4: 데이터 삭제

| 단계 | 사용자 동작 | 기대 결과 |
|------|-------------|-----------|
| 1 | 행 체크박스 선택 | 선택 표시 |
| 2 | [삭제] 버튼 클릭 | 삭제 확인 다이얼로그 |
| 3 | 확인 | 삭제 완료, 목록 갱신 |

---

## 6. 검증 체크리스트

- [ ] 데이터 조회가 정상 동작하는가?
- [ ] 검색 필터가 정상 동작하는가?
- [ ] 신규 등록이 정상 동작하는가?
- [ ] 수정이 정상 동작하는가?
- [ ] 삭제가 정상 동작하는가?
- [ ] 페이지네이션이 정상 동작하는가?
- [ ] 정렬이 정상 동작하는가?

---

## 7. 참고 사항

- 관련 화면: [관련 화면명](./related-screen.md)
- 특이 사항: 없음