ERP-node/popdocs/components-spec.md

# POP 컴포넌트 상세 설계서

> AI 에이전트 안내: Quick Reference 먼저 확인 후 필요한 섹션만 참조

---

## Quick Reference

### 총 컴포넌트 수: 13개

| 분류 | 개수 | 컴포넌트 |
|------|------|----------|
| 레이아웃 | 2 | container, tab-panel |
| 데이터 표시 | 4 | data-table, card-list, kpi-gauge, status-indicator |
| 입력 | 4 | number-pad, barcode-scanner, form-field, action-button |
| 특화 기능 | 3 | timer, alarm-list, process-flow |

### 개발 우선순위

1단계: number-pad, status-indicator, kpi-gauge, action-button
2단계: data-table, card-list, barcode-scanner, timer
3단계: container, tab-panel, form-field, alarm-list, process-flow

### POP UI 필수 원칙

- 버튼 최소 크기: 48px (1.5cm)
- 고대비 테마 지원
- 단순 탭 조작 (스와이프 최소화)
- 알람에만 원색 사용
- 숫자 우측 정렬

---

## 컴포넌트 목록

| # | 컴포넌트 | 역할 |
|---|----------|------|
| 1 | pop-container | 레이아웃 뼈대 |
| 2 | pop-tab-panel | 정보 분류 |
| 3 | pop-data-table | 대량 데이터 |
| 4 | pop-card-list | 시각적 목록 |
| 5 | pop-kpi-gauge | 목표 달성률 |
| 6 | pop-status-indicator | 상태 표시 |
| 7 | pop-number-pad | 수량 입력 |
| 8 | pop-barcode-scanner | 스캔 입력 |
| 9 | pop-form-field | 범용 입력 |
| 10 | pop-action-button | 작업 실행 |
| 11 | pop-timer | 시간 측정 |
| 12 | pop-alarm-list | 알람 관리 |
| 13 | pop-process-flow | 공정 현황 |

---

## 1. pop-container

역할: 모든 컴포넌트의 부모, 화면 뼈대

| 기능 | 설명 |
|------|------|
| 반응형 그리드 | 모바일/태블릿 자동 대응 |
| 플렉스 방향 | row, column, wrap |
| 간격 설정 | gap, padding |
| 배경/테두리 | 색상, 둥근모서리 |
| 스크롤 설정 | 가로/세로/없음 |

---

## 2. pop-tab-panel

역할: 정보 분류, 화면 공간 효율화

| 기능 | 설명 |
|------|------|
| 탭 모드 | 상단/하단/좌측 탭 |
| 아코디언 모드 | 접기/펼치기 |
| 아이콘 지원 | 탭별 아이콘 |
| 뱃지 표시 | 알림 개수 표시 |
| 기본 활성 탭 | 초기 선택 설정 |

---

## 3. pop-data-table

역할: 대량 데이터 표시, 선택, 편집

| 기능 | 설명 |
|------|------|
| 가상 스크롤 | 대량 데이터 성능 |
| 행 선택 | 단일/다중 선택 |
| 인라인 편집 | 셀 직접 수정 |
| 정렬/필터 | 컬럼별 정렬, 검색 |
| 고정 컬럼 | 좌측 컬럼 고정 |
| 행 색상 조건 | 상태별 배경색 |
| 큰 글씨 모드 | POP 전용 가독성 |

---

## 4. pop-card-list

역할: 시각적 강조가 필요한 목록

| 기능 | 설명 |
|------|------|
| 카드 레이아웃 | 1열/2열/3열 |
| 이미지 표시 | 부품/제품 사진 |
| 상태 뱃지 | 진행중/완료/대기 |
| 진행률 바 | 작업 진척도 |
| 스와이프 액션 | 완료/삭제 (선택적) |
| 클릭 이벤트 | 상세 모달 연결 |

---

## 5. pop-kpi-gauge

역할: 목표 대비 실적 시각화

| 기능 | 설명 |
|------|------|
| 게이지 타입 | 원형/반원형/수평바 |
| 목표값 | 기준선 표시 |
| 현재값 | 실시간 바인딩 |
| 색상 구간 | 위험/경고/정상 |
| 단위 표시 | %, 개, 초 등 |
| 애니메이션 | 값 변경 시 전환 |
| 라벨 | 제목, 부제목 |

---

## 6. pop-status-indicator

역할: 설비/공정 상태 즉시 파악

| 기능 | 설명 |
|------|------|
| 표시 타입 | 원형/사각/아이콘 |
| 상태 매핑 | 값 -> 색상/아이콘 자동 |
| 색상 설정 | 상태별 커스텀 |
| 크기 | S/M/L/XL |
| 깜빡임 | 알람 상태 강조 |
| 라벨 위치 | 상단/하단/우측 |
| 그룹 표시 | 여러 상태 한 줄 |

---

## 7. pop-number-pad

역할: 장갑 착용 상태 수량 입력

| 기능 | 설명 |
|------|------|
| 큰 버튼 | 최소 48px (1.5cm) |
| 레이아웃 | 전화기식/계산기식 |
| 소수점 | 허용/불허 |
| 음수 | 허용/불허 |
| 최소/최대값 | 범위 제한 |
| 단위 표시 | 개, kg, m 등 |
| 빠른 증감 | +1, +10, +100 버튼 |
| 진동 피드백 | 터치 확인 |
| 클리어 | 전체 삭제, 한 자리 삭제 |

---

## 8. pop-barcode-scanner

역할: 자재 투입, 로트 추적

| 기능 | 설명 |
|------|------|
| 카메라 스캔 | 모바일 카메라 연동 |
| 외부 스캐너 | USB/블루투스 연동 |
| 스캔 타입 | 바코드/QR/RFID |
| 연속 스캔 | 다중 입력 모드 |
| 이력 표시 | 최근 스캔 목록 |
| 유효성 검증 | 포맷 체크 |
| 자동 조회 | 스캔 후 API 연동 |
| 소리/진동 | 스캔 성공 피드백 |

---

## 9. pop-form-field

역할: 텍스트, 선택, 날짜 등 범용 입력

| 기능 | 설명 |
|------|------|
| 입력 타입 | text/number/date/time/select |
| 라벨 | 상단/좌측/플로팅 |
| 필수 표시 | 별표, 색상 |
| 유효성 검증 | 실시간 체크 |
| 에러 메시지 | 하단 표시 |
| 비활성화 | 읽기 전용 모드 |
| 큰 사이즈 | POP 전용 높이 |
| 도움말 | 툴팁/하단 설명 |

---

## 10. pop-action-button

역할: 작업 실행, 상태 변경

| 기능 | 설명 |
|------|------|
| 크기 | S/M/L/XL/전체너비 |
| 스타일 | primary/secondary/danger/success |
| 아이콘 | 좌측/우측/단독 |
| 로딩 상태 | 스피너 표시 |
| 비활성화 | 조건부 |
| 확인 다이얼로그 | 위험 작업 전 확인 |
| 길게 누르기 | 특수 동작 (선택적) |
| 뱃지 | 개수 표시 |

---

## 11. pop-timer

역할: 사이클 타임, 비가동 시간 측정

| 기능 | 설명 |
|------|------|
| 모드 | 스톱워치/카운트다운 |
| 시작/정지/리셋 | 기본 제어 |
| 랩 타임 | 구간 기록 |
| 목표 시간 | 초과 시 알림 |
| 표시 형식 | HH:MM:SS / MM:SS |
| 크기 | 작은/중간/큰 |
| 배경 색상 | 상태별 변경 |
| 자동 시작 | 조건부 트리거 |

---

## 12. pop-alarm-list

역할: 이상 상황 알림 및 확인

| 기능 | 설명 |
|------|------|
| 우선순위 | 긴급/경고/정보 |
| 색상 구분 | 레벨별 배경색 |
| 시간 표시 | 발생 시각 |
| 확인(Ack) | 알람 인지 처리 |
| 필터 | 미확인만/전체 |
| 정렬 | 시간순/우선순위순 |
| 상세 보기 | 클릭 시 모달 |
| 소리 알림 | 신규 알람 |

---

## 13. pop-process-flow

역할: 전체 공정 현황 시각화

| 기능 | 설명 |
|------|------|
| 노드 타입 | 공정/검사/대기 |
| 연결선 | 화살표, 분기 |
| 현재 위치 | 강조 표시 |
| 상태 색상 | 완료/진행/대기 |
| 클릭 이벤트 | 공정 상세 이동 |
| 가로/세로 | 방향 설정 |
| 축소/확대 | 핀치 줌 |
| 진행률 | 전체 대비 현재 |

---

## 커버 가능한 시나리오

이 13개 컴포넌트 조합으로 대응 가능한 화면:

- 작업 지시 화면
- 실적 입력 화면
- 품질 검사 화면
- 설비 모니터링 대시보드
- 자재 투입/출고 화면
- 알람 관리 화면
- 공정 현황판

---

## 기존 컴포넌트 재사용 가능 목록

| POP 컴포넌트 | 기존 컴포넌트 | 수정 필요 |
|-------------|--------------|----------|
| pop-data-table | v2-table-widget | 큰 글씨 모드 추가 |
| pop-form-field | v2-input-widget, v2-select-widget | 큰 사이즈 옵션 |
| pop-action-button | v2-button-widget | 크기/확인 다이얼로그 |
| pop-tab-panel | tab-widget | POP 스타일 적용 |

---

*최종 업데이트: 2026-01-29*
feat(pop): POP 화면 관리 시스템 구현 Backend: - screen_layouts_pop 테이블용 CRUD API 추가 (getLayoutPop, saveLayoutPop, deleteLayoutPop, getScreenIdsWithPopLayout) - 멀티테넌시 권한 체크 포함 Frontend API: - screenApi에 POP 레이아웃 함수 4개 추가 POP 관리 페이지: - popScreenMngList 신규 생성 - isPop prop으로 미리보기 URL 분기 (/pop/screens/{id}) - CreateScreenModal에서 POP 화면 생성 시 빈 레이아웃 자동 생성 POP 디자이너: - PopDesigner, PopCanvas, PopPanel, SectionGrid 컴포넌트 구현 - react-dnd로 팔레트→캔버스 드래그앤드롭 - react-grid-layout으로 컴포넌트 자유 배치/리사이즈 - 그리드 단순화: 고정 셀 크기(40px) 기반 자동 계산, 그리드 점 제거 - onLayoutChange를 onDragStop/onResizeStop으로 변경하여 드롭 시 크기 유지 2026-02-02 15:15:01 +09:00			`# POP 컴포넌트 상세 설계서`

			`> AI 에이전트 안내: Quick Reference 먼저 확인 후 필요한 섹션만 참조`

			`---`

			`## Quick Reference`

			`### 총 컴포넌트 수: 13개`

			`\| 분류 \| 개수 \| 컴포넌트 \|`
			`\|------\|------\|----------\|`
			`\| 레이아웃 \| 2 \| container, tab-panel \|`
			`\| 데이터 표시 \| 4 \| data-table, card-list, kpi-gauge, status-indicator \|`
			`\| 입력 \| 4 \| number-pad, barcode-scanner, form-field, action-button \|`
			`\| 특화 기능 \| 3 \| timer, alarm-list, process-flow \|`

			`### 개발 우선순위`

			`1단계: number-pad, status-indicator, kpi-gauge, action-button`
			`2단계: data-table, card-list, barcode-scanner, timer`
			`3단계: container, tab-panel, form-field, alarm-list, process-flow`

			`### POP UI 필수 원칙`

			`- 버튼 최소 크기: 48px (1.5cm)`
			`- 고대비 테마 지원`
			`- 단순 탭 조작 (스와이프 최소화)`
			`- 알람에만 원색 사용`
			`- 숫자 우측 정렬`

			`---`

			`## 컴포넌트 목록`

			`\| # \| 컴포넌트 \| 역할 \|`
			`\|---\|----------\|------\|`
			`\| 1 \| pop-container \| 레이아웃 뼈대 \|`
			`\| 2 \| pop-tab-panel \| 정보 분류 \|`
			`\| 3 \| pop-data-table \| 대량 데이터 \|`
			`\| 4 \| pop-card-list \| 시각적 목록 \|`
			`\| 5 \| pop-kpi-gauge \| 목표 달성률 \|`
			`\| 6 \| pop-status-indicator \| 상태 표시 \|`
			`\| 7 \| pop-number-pad \| 수량 입력 \|`
			`\| 8 \| pop-barcode-scanner \| 스캔 입력 \|`
			`\| 9 \| pop-form-field \| 범용 입력 \|`
			`\| 10 \| pop-action-button \| 작업 실행 \|`
			`\| 11 \| pop-timer \| 시간 측정 \|`
			`\| 12 \| pop-alarm-list \| 알람 관리 \|`
			`\| 13 \| pop-process-flow \| 공정 현황 \|`

			`---`

			`## 1. pop-container`

			`역할: 모든 컴포넌트의 부모, 화면 뼈대`

			`\| 기능 \| 설명 \|`
			`\|------\|------\|`
			`\| 반응형 그리드 \| 모바일/태블릿 자동 대응 \|`
			`\| 플렉스 방향 \| row, column, wrap \|`
			`\| 간격 설정 \| gap, padding \|`
			`\| 배경/테두리 \| 색상, 둥근모서리 \|`
			`\| 스크롤 설정 \| 가로/세로/없음 \|`

			`---`

			`## 2. pop-tab-panel`

			`역할: 정보 분류, 화면 공간 효율화`

			`\| 기능 \| 설명 \|`
			`\|------\|------\|`
			`\| 탭 모드 \| 상단/하단/좌측 탭 \|`
			`\| 아코디언 모드 \| 접기/펼치기 \|`
			`\| 아이콘 지원 \| 탭별 아이콘 \|`
			`\| 뱃지 표시 \| 알림 개수 표시 \|`
			`\| 기본 활성 탭 \| 초기 선택 설정 \|`

			`---`

			`## 3. pop-data-table`

			`역할: 대량 데이터 표시, 선택, 편집`

			`\| 기능 \| 설명 \|`
			`\|------\|------\|`
			`\| 가상 스크롤 \| 대량 데이터 성능 \|`
			`\| 행 선택 \| 단일/다중 선택 \|`
			`\| 인라인 편집 \| 셀 직접 수정 \|`
			`\| 정렬/필터 \| 컬럼별 정렬, 검색 \|`
			`\| 고정 컬럼 \| 좌측 컬럼 고정 \|`
			`\| 행 색상 조건 \| 상태별 배경색 \|`
			`\| 큰 글씨 모드 \| POP 전용 가독성 \|`

			`---`

			`## 4. pop-card-list`

			`역할: 시각적 강조가 필요한 목록`

			`\| 기능 \| 설명 \|`
			`\|------\|------\|`
			`\| 카드 레이아웃 \| 1열/2열/3열 \|`
			`\| 이미지 표시 \| 부품/제품 사진 \|`
			`\| 상태 뱃지 \| 진행중/완료/대기 \|`
			`\| 진행률 바 \| 작업 진척도 \|`
			`\| 스와이프 액션 \| 완료/삭제 (선택적) \|`
			`\| 클릭 이벤트 \| 상세 모달 연결 \|`

			`---`

			`## 5. pop-kpi-gauge`

			`역할: 목표 대비 실적 시각화`

			`\| 기능 \| 설명 \|`
			`\|------\|------\|`
			`\| 게이지 타입 \| 원형/반원형/수평바 \|`
			`\| 목표값 \| 기준선 표시 \|`
			`\| 현재값 \| 실시간 바인딩 \|`
			`\| 색상 구간 \| 위험/경고/정상 \|`
			`\| 단위 표시 \| %, 개, 초 등 \|`
			`\| 애니메이션 \| 값 변경 시 전환 \|`
			`\| 라벨 \| 제목, 부제목 \|`

			`---`

			`## 6. pop-status-indicator`

			`역할: 설비/공정 상태 즉시 파악`

			`\| 기능 \| 설명 \|`
			`\|------\|------\|`
			`\| 표시 타입 \| 원형/사각/아이콘 \|`
			`\| 상태 매핑 \| 값 -> 색상/아이콘 자동 \|`
			`\| 색상 설정 \| 상태별 커스텀 \|`
			`\| 크기 \| S/M/L/XL \|`
			`\| 깜빡임 \| 알람 상태 강조 \|`
			`\| 라벨 위치 \| 상단/하단/우측 \|`
			`\| 그룹 표시 \| 여러 상태 한 줄 \|`

			`---`

			`## 7. pop-number-pad`

			`역할: 장갑 착용 상태 수량 입력`

			`\| 기능 \| 설명 \|`
			`\|------\|------\|`
			`\| 큰 버튼 \| 최소 48px (1.5cm) \|`
			`\| 레이아웃 \| 전화기식/계산기식 \|`
			`\| 소수점 \| 허용/불허 \|`
			`\| 음수 \| 허용/불허 \|`
			`\| 최소/최대값 \| 범위 제한 \|`
			`\| 단위 표시 \| 개, kg, m 등 \|`
			`\| 빠른 증감 \| +1, +10, +100 버튼 \|`
			`\| 진동 피드백 \| 터치 확인 \|`
			`\| 클리어 \| 전체 삭제, 한 자리 삭제 \|`

			`---`

			`## 8. pop-barcode-scanner`

			`역할: 자재 투입, 로트 추적`

			`\| 기능 \| 설명 \|`
			`\|------\|------\|`
			`\| 카메라 스캔 \| 모바일 카메라 연동 \|`
			`\| 외부 스캐너 \| USB/블루투스 연동 \|`
			`\| 스캔 타입 \| 바코드/QR/RFID \|`
			`\| 연속 스캔 \| 다중 입력 모드 \|`
			`\| 이력 표시 \| 최근 스캔 목록 \|`
			`\| 유효성 검증 \| 포맷 체크 \|`
			`\| 자동 조회 \| 스캔 후 API 연동 \|`
			`\| 소리/진동 \| 스캔 성공 피드백 \|`

			`---`

			`## 9. pop-form-field`

			`역할: 텍스트, 선택, 날짜 등 범용 입력`

			`\| 기능 \| 설명 \|`
			`\|------\|------\|`
			`\| 입력 타입 \| text/number/date/time/select \|`
			`\| 라벨 \| 상단/좌측/플로팅 \|`
			`\| 필수 표시 \| 별표, 색상 \|`
			`\| 유효성 검증 \| 실시간 체크 \|`
			`\| 에러 메시지 \| 하단 표시 \|`
			`\| 비활성화 \| 읽기 전용 모드 \|`
			`\| 큰 사이즈 \| POP 전용 높이 \|`
			`\| 도움말 \| 툴팁/하단 설명 \|`

			`---`

			`## 10. pop-action-button`

			`역할: 작업 실행, 상태 변경`

			`\| 기능 \| 설명 \|`
			`\|------\|------\|`
			`\| 크기 \| S/M/L/XL/전체너비 \|`
			`\| 스타일 \| primary/secondary/danger/success \|`
			`\| 아이콘 \| 좌측/우측/단독 \|`
			`\| 로딩 상태 \| 스피너 표시 \|`
			`\| 비활성화 \| 조건부 \|`
			`\| 확인 다이얼로그 \| 위험 작업 전 확인 \|`
			`\| 길게 누르기 \| 특수 동작 (선택적) \|`
			`\| 뱃지 \| 개수 표시 \|`

			`---`

			`## 11. pop-timer`

			`역할: 사이클 타임, 비가동 시간 측정`

			`\| 기능 \| 설명 \|`
			`\|------\|------\|`
			`\| 모드 \| 스톱워치/카운트다운 \|`
			`\| 시작/정지/리셋 \| 기본 제어 \|`
			`\| 랩 타임 \| 구간 기록 \|`
			`\| 목표 시간 \| 초과 시 알림 \|`
			`\| 표시 형식 \| HH:MM:SS / MM:SS \|`
			`\| 크기 \| 작은/중간/큰 \|`
			`\| 배경 색상 \| 상태별 변경 \|`
			`\| 자동 시작 \| 조건부 트리거 \|`

			`---`

			`## 12. pop-alarm-list`

			`역할: 이상 상황 알림 및 확인`

			`\| 기능 \| 설명 \|`
			`\|------\|------\|`
			`\| 우선순위 \| 긴급/경고/정보 \|`
			`\| 색상 구분 \| 레벨별 배경색 \|`
			`\| 시간 표시 \| 발생 시각 \|`
			`\| 확인(Ack) \| 알람 인지 처리 \|`
			`\| 필터 \| 미확인만/전체 \|`
			`\| 정렬 \| 시간순/우선순위순 \|`
			`\| 상세 보기 \| 클릭 시 모달 \|`
			`\| 소리 알림 \| 신규 알람 \|`

			`---`

			`## 13. pop-process-flow`

			`역할: 전체 공정 현황 시각화`

			`\| 기능 \| 설명 \|`
			`\|------\|------\|`
			`\| 노드 타입 \| 공정/검사/대기 \|`
			`\| 연결선 \| 화살표, 분기 \|`
			`\| 현재 위치 \| 강조 표시 \|`
			`\| 상태 색상 \| 완료/진행/대기 \|`
			`\| 클릭 이벤트 \| 공정 상세 이동 \|`
			`\| 가로/세로 \| 방향 설정 \|`
			`\| 축소/확대 \| 핀치 줌 \|`
			`\| 진행률 \| 전체 대비 현재 \|`

			`---`

			`## 커버 가능한 시나리오`

			`이 13개 컴포넌트 조합으로 대응 가능한 화면:`

			`- 작업 지시 화면`
			`- 실적 입력 화면`
			`- 품질 검사 화면`
			`- 설비 모니터링 대시보드`
			`- 자재 투입/출고 화면`
			`- 알람 관리 화면`
			`- 공정 현황판`

			`---`

			`## 기존 컴포넌트 재사용 가능 목록`

			`\| POP 컴포넌트 \| 기존 컴포넌트 \| 수정 필요 \|`
			`\|-------------\|--------------\|----------\|`
			`\| pop-data-table \| v2-table-widget \| 큰 글씨 모드 추가 \|`
			`\| pop-form-field \| v2-input-widget, v2-select-widget \| 큰 사이즈 옵션 \|`
			`\| pop-action-button \| v2-button-widget \| 크기/확인 다이얼로그 \|`
			`\| pop-tab-panel \| tab-widget \| POP 스타일 적용 \|`

			`---`

			`최종 업데이트: 2026-01-29`