ERP-node/POPUPDATE_2.md

# POP 컴포넌트 정의서 v7.0

## POP 헌법 (공통 규칙)

### 제1조. 컴포넌트의 정의

- 컴포넌트란 디자이너가 그리드에 배치하는 것이다
- 그리드에 배치하지 않는 것은 컴포넌트가 아니다

### 제2조. 컴포넌트의 독립성

- 모든 컴포넌트는 독립적으로 동작한다
- 컴포넌트는 다른 컴포넌트의 존재를 직접 알지 못한다 (이벤트 버스로만 통신)

### 제3조. 데이터의 자유

- 모든 컴포넌트는 자신의 테이블 + 외부 테이블을 자유롭게 조인할 수 있다
- 컬럼별로 read/write/readwrite/hidden을 개별 설정할 수 있다
- 보유 데이터 중 원하는 컬럼만 골라서 저장할 수 있다

### 제4조. 통신의 규칙

- 컴포넌트 간 통신은 반드시 이벤트 버스(usePopEvent)를 통한다
- 컴포넌트가 다른 컴포넌트를 직접 참조하거나 호출하지 않는다
- 이벤트는 화면 단위로 격리된다 (다른 POP 화면의 이벤트를 받지 않는다)
- 같은 화면 안에서는 이벤트를 통해 자유롭게 데이터를 주고받을 수 있다

### 제5조. 역할의 분리

- 조회용 입력(pop-search)과 저장용 입력(pop-field)은 다른 컴포넌트다
- 이동/실행(pop-icon)과 값 선택 후 반환(pop-lookup)은 다른 컴포넌트다
- 자주 쓰는 패턴은 하나로 합치되, 흐름 자체는 강제하고 보이는 방식만 옵션으로 제공한다

### 제6조. 시스템 설정도 컴포넌트다

- 프로필, 테마, 대시보드 보이기/숨기기 같은 시스템 설정도 컴포넌트(pop-system)로 만든다
- 디자이너가 pop-system을 배치하지 않으면 해당 화면에 설정 기능이 없다
- 이를 통해 디자이너가 "이 화면에 설정 기능을 넣을지 말지"를 직접 결정한다

### 제7조. 디자이너의 권한

- 디자이너는 컴포넌트를 배치하고 설정한다
- 디자이너는 사용자에게 커스텀을 허용할지 말지 결정한다 (userConfigurable)
- 디자이너가 "사용자 커스텀 허용 = OFF"로 설정하면, 사용자는 변경할 수 없다
- 컴포넌트의 옵션 설정(어떻게 저장하고 어떻게 조회하는지 등)은 디자이너가 결정한다

### 제8조. 컴포넌트의 구성

- 모든 컴포넌트는 3개 파일로 구성된다: 실제 컴포넌트, 디자인 미리보기, 설정 패널
- 모든 컴포넌트는 레지스트리에 등록해야 디자이너에 나타난다
- 모든 컴포넌트 인스턴스는 userConfigurable, displayName 공통 속성을 가진다

---

## 현재 상태

- 그리드 시스템 (v5.2): 완성
- 컴포넌트 레지스트리: 완성 (PopComponentRegistry.ts)
- 구현 완료: `pop-text` 1개 (pop-text.tsx)
- 기존 `components-spec.md`는 v4 기준이라 갱신 필요

## 아키텍처 개요

```mermaid
graph TB
  subgraph designer [디자이너]
    Palette[컴포넌트 팔레트]
    Grid[CSS Grid 캔버스]
    ConfigPanel[속성 설정 패널]
  end

  subgraph registry [레지스트리]
    Registry[PopComponentRegistry]
  end

  subgraph infra [공통 인프라]
    DataSource[useDataSource 훅]
    EventBus[usePopEvent 훅]
    ActionRunner[usePopAction 훅]
  end

  subgraph components [9개 컴포넌트]
    Text[pop-text - 완성]
    Dashboard[pop-dashboard]
    Table[pop-table]
    Button[pop-button]
    Icon[pop-icon]
    Search[pop-search]
    Field[pop-field]
    Lookup[pop-lookup]
    System[pop-system]
  end

  subgraph backend [기존 백엔드 API]
    DataAPI[dataApi - 동적 CRUD]
    DashAPI[dashboardApi - 통계 쿼리]
    CodeAPI[commonCodeApi - 공통코드]
    NumberAPI[numberingRuleApi - 채번]
  end

  Palette --> Grid
  Grid --> ConfigPanel
  ConfigPanel --> Registry

  Registry --> components
  components --> infra
  infra --> backend
  EventBus -.->|컴포넌트 간 통신| components
  System -.->|보이기/숨기기 제어| components
```

---

## 공통 인프라 (모든 컴포넌트가 공유)

### 핵심 원칙: 모든 컴포넌트는 데이터를 자유롭게 다룬다

1. **데이터 전달**: 모든 컴포넌트는 자신이 보유한 데이터를 다른 컴포넌트에 전달/수신 가능
2. **테이블 조인**: 자신의 테이블 + 외부 테이블 자유롭게 조인하여 데이터 구성
3. **컬럼별 CRUD 제어**: 컬럼 단위로 "조회만" / "저장 대상" / "숨김"을 개별 설정 가능
4. **선택적 저장**: 보유 데이터 중 원하는 컬럼만 골라서 저장/수정/삭제 가능

### 공통 인스턴스 속성 (모든 컴포넌트 배치 시 설정 가능)

디자이너가 컴포넌트를 그리드에 배치할 때 설정하는 공통 속성:

- `userConfigurable`: boolean - 사용자가 이 컴포넌트를 숨길 수 있는지 (개인 설정 패널에 노출)
- `displayName`: string - 개인 설정 패널에 보여줄 이름 (예: "금일 생산실적")

### 1. DataSourceConfig (데이터 소스 설정 타입)

모든 데이터 연동 컴포넌트가 사용하는 표준 설정 구조:

- `tableName`: 대상 테이블
- `columns`: 컬럼 바인딩 목록 (ColumnBinding 배열)
- `filters`: 필터 조건 배열
- `sort`: 정렬 설정
- `aggregation`: 집계 함수 (count, sum, avg, min, max)
- `joins`: 테이블 조인 설정 (JoinConfig 배열)
- `refreshInterval`: 자동 새로고침 주기 (초)
- `limit`: 조회 건수 제한

### 1-1. ColumnBinding (컬럼별 읽기/쓰기 제어)

각 컬럼이 컴포넌트에서 어떤 역할을 하는지 개별 설정:

- `columnName`: 컬럼명
- `sourceTable`: 소속 테이블 (조인된 외부 테이블 포함)
- `mode`: "read" | "write" | "readwrite" | "hidden"
  - read: 조회만 (화면에 표시하되 저장 안 함)
  - write: 저장 대상 (사용자 입력 -> DB 저장)
  - readwrite: 조회 + 저장 모두
  - hidden: 내부 참조용 (화면에 안 보이지만 다른 컴포넌트에 전달 가능)
- `label`: 화면 표시 라벨
- `defaultValue`: 기본값

예시: 발주 품목 카드에서 5개 컬럼 중 3개만 저장

```
columns: [
  { columnName: "item_code",   sourceTable: "order_items", mode: "read" },
  { columnName: "item_name",   sourceTable: "item_info",   mode: "read" },
  { columnName: "inbound_qty", sourceTable: "order_items", mode: "readwrite" },
  { columnName: "warehouse",   sourceTable: "order_items", mode: "write" },
  { columnName: "memo",        sourceTable: "order_items", mode: "write" },
]
```

### 1-2. JoinConfig (테이블 조인 설정)

외부 테이블과 자유롭게 조인:

- `targetTable`: 조인할 외부 테이블명
- `joinType`: "inner" | "left" | "right"
- `on`: 조인 조건 { sourceColumn, targetColumn }
- `columns`: 가져올 컬럼 목록

### 2. useDataSource 훅

DataSourceConfig를 받아서 기존 API를 호출하고 결과를 반환:

- 로딩/에러/데이터 상태 관리
- 자동 새로고침 타이머
- 필터 변경 시 자동 재조회
- 기존 `dataApi`, `dashboardApi` 활용
- **CRUD 함수 제공**: save(data), update(id, data), delete(id)
  - ColumnBinding의 mode가 "write" 또는 "readwrite"인 컬럼만 저장 대상에 포함
  - "read" 컬럼은 저장 시 자동 제외

### 3. usePopEvent 훅 (이벤트 버스 - 데이터 전달 포함)

컴포넌트 간 통신 (단순 이벤트 + 데이터 페이로드):

- `publish(eventName, payload)`: 이벤트 발행
- `subscribe(eventName, callback)`: 이벤트 구독
- `getSharedData(key)`: 공유 데이터 직접 읽기
- `setSharedData(key, value)`: 공유 데이터 직접 쓰기
- 화면 단위 스코프 (다른 POP 화면과 격리)

### 4. PopActionConfig (액션 설정 타입)

모든 컴포넌트가 사용할 수 있는 액션 표준 구조:

- `type`: "navigate" | "modal" | "save" | "delete" | "api" | "event" | "refresh"
- `navigate`: { screenId, url }
- `modal`: { title, dataSource }
- `save`: { targetColumns }
- `delete`: { confirmMessage }
- `api`: { method, endpoint, body }
- `event`: { eventName, payload }
- `refresh`: { targetComponents }

---

## 컴포넌트 정의 (9개)

### 1. pop-text (완성)

- **한 줄 정의**: 보여주기만 함
- **카테고리**: display
- **역할**: 정적 표시 전용 (이벤트 없음)
- **서브타입**: text, datetime, image, title
- **데이터**: 없음 (정적 콘텐츠)
- **이벤트**: 발행 없음, 수신 없음
- **설정**: 내용, 폰트 크기/굵기, 좌우/상하 정렬, 이미지 URL/맞춤/크기, 날짜 포맷 빌더

### 2. pop-dashboard (신규)

- **한 줄 정의**: 숫자를 집계해서 보여줌
- **카테고리**: display
- **역할**: 숫자 데이터를 집계/계산하여 시각화
- **서브타입**:
  - kpi-card: 숫자 + 단위 + 라벨 + 증감 표시
  - chart: 막대/원형/라인 차트
  - gauge: 게이지 (목표 대비 달성률)
  - stat-card: 통계 카드 (건수 + 대기 + 링크)
- **데이터**: DataSourceConfig (조인/집계 자유)
- **CRUD**: 주로 읽기. 목표값 수정 등 필요 시 write 컬럼으로 저장 가능
- **이벤트**:
  - 수신: filter_changed, data_ready
  - 발행: kpi_clicked (KPI 카드 클릭 시 상세 데이터 전달)
- **설정**: 데이터 소스, 집계 함수, 라벨, 단위, 색상 구간, 차트 타입, 새로고침 주기, 목표값, 표시 모드(slide/scroll/grid)

### 3. pop-table (신규 - 가장 복잡)

- **한 줄 정의**: 데이터 목록을 보여주고 편집함
- **카테고리**: display
- **역할**: 데이터 목록 표시 + 편집 (카드형/테이블형)
- **서브타입**:
  - card-list: 카드 형태
  - table-list: 테이블 형태 (행/열 장부)
- **데이터**: DataSourceConfig (조인/컬럼별 읽기쓰기 자유)
- **CRUD**: useDataSource의 save/update/delete 사용. write/readwrite 컬럼만 자동 추출
- **카드 템플릿** (card-list 전용): 카드 내부 미니 그리드로 요소 배치, 요소별 데이터 바인딩
- **이벤트**:
  - 수신: filter_changed, refresh, data_ready
  - 발행: row_selected, row_action, save_complete, delete_complete
- **설정**: 데이터 소스, 표시 모드, 카드 템플릿, 컬럼 정의, 행 선택 방식, 페이징, 정렬, 인라인 편집 여부

### 4. pop-button (신규)

- **한 줄 정의**: 누르면 액션 실행 (저장, 삭제 등)
- **카테고리**: action
- **역할**: 액션 실행 (저장, 삭제, API 호출, 모달 열기 등)
- **데이터**: 이벤트로 수신한 데이터를 액션에 활용
- **CRUD**: 버튼 클릭 시 수신 데이터 기반으로 save/update/delete 실행
- **이벤트**:
  - 수신: data_ready, row_selected
  - 발행: save_complete, delete_complete 등
- **설정**: 라벨, 아이콘, 크기, 스타일, 액션 설정(PopActionConfig), 확인 다이얼로그, 로딩 상태

### 5. pop-icon (신규)

- **한 줄 정의**: 누르면 어딘가로 이동 (돌아오는 값 없음)
- **카테고리**: action
- **역할**: 네비게이션 (화면 이동, URL 이동, 새로고침)
- **데이터**: 없음
- **이벤트**: 없음 (네비게이션은 이벤트가 아닌 직접 실행)
- **설정**: 아이콘 종류(lucide-icon), 라벨, 배경색/그라디언트, 크기, 클릭 액션(PopActionConfig), 뱃지 표시
- **pop-lookup과의 차이**: pop-icon은 이동/실행만 함. 값을 선택해서 돌려주지 않음

### 6. pop-search (신규)

- **한 줄 정의**: 조건을 입력해서 다른 컴포넌트를 조회/필터링
- **카테고리**: input
- **역할**: 다른 컴포넌트에 필터 조건 전달 + 자체 데이터 조회
- **서브타입**:
  - text-search: 텍스트 검색
  - date-range: 날짜 범위
  - select-filter: 드롭다운 선택 (공통코드 연동)
  - combo-filter: 복합 필터 (여러 조건 조합)
- **실행 방식**: auto(값 변경 즉시) 또는 button(검색 버튼 클릭 시)
- **데이터**: 공통코드/카테고리 API로 선택 항목 조회
- **이벤트**:
  - 수신: 없음
  - 발행: filter_changed (필터 값 변경 시)
- **설정**: 필터 타입, 대상 컬럼, 공통코드 연결, 플레이스홀더, 실행 방식(auto/button), 발행할 이벤트 이름
- **pop-field와의 차이**: pop-search 입력값은 조회용(DB에 안 들어감). pop-field 입력값은 저장용(DB에 들어감)

### 7. pop-field (신규)

- **한 줄 정의**: 저장할 값을 입력
- **카테고리**: input
- **역할**: 단일 데이터 입력 (폼 필드) - 입력한 값이 DB에 저장되는 것이 목적
- **서브타입**:
  - text: 텍스트 입력
  - number: 숫자 입력 (수량, 금액)
  - date: 날짜 선택
  - select: 드롭다운 선택
  - numpad: 큰 숫자패드 (현장용)
- **데이터**: DataSourceConfig (선택적)
  - select 옵션을 DB에서 조회 가능
  - ColumnBinding으로 입력값의 저장 대상 테이블/컬럼 지정
- **CRUD**: 자체 저장은 보통 하지 않음. value_changed 이벤트로 pop-button 등에 전달
- **이벤트**:
  - 수신: set_value (외부에서 값 설정)
  - 발행: value_changed (값 + 컬럼명 + 모드 정보)
- **설정**: 입력 타입, 라벨, 플레이스홀더, 필수 여부, 유효성 검증, 최소/최대값, 단위 표시, 바인딩 컬럼

### 8. pop-lookup (신규)

- **한 줄 정의**: 모달에서 값을 골라서 반환
- **카테고리**: input
- **역할**: 필드를 클릭하면 모달이 열리고, 목록에서 선택하면 값이 반환되는 컴포넌트
- **서브타입 (모달 안 표시 방식)**:
  - card: 카드형 목록
  - table: 테이블형 목록
  - icon-grid: 아이콘 그리드 (참조 화면의 거래처 선택처럼)
- **동작 흐름**: 필드 클릭 -> 모달 열림 -> 목록에서 선택 -> 모달 닫힘 -> 필드에 값 표시 + 이벤트 발행
- **데이터**: DataSourceConfig (모달 안 목록의 데이터 소스)
- **이벤트**:
  - 수신: set_value (외부에서 값 초기화)
  - 발행: value_selected (선택한 레코드 전체 데이터 전달), filter_changed (선택 값을 필터로 전달)
- **설정**: 라벨, 플레이스홀더, 데이터 소스, 모달 표시 방식(card/table/icon-grid), 표시 컬럼(모달 목록에 보여줄 컬럼), 반환 컬럼(선택 시 돌려줄 값), 발행할 이벤트 이름
- **pop-icon과의 차이**: pop-icon은 이동/실행만 하고 값이 안 돌아옴. pop-lookup은 값을 골라서 돌려줌
- **pop-search와의 차이**: pop-search는 텍스트/날짜/드롭다운으로 필터링. pop-lookup은 모달을 열어서 목록에서 선택

### 9. pop-system (신규)

- **한 줄 정의**: 시스템 설정을 하나로 통합한 컴포넌트 (프로필, 테마, 보이기/숨기기)
- **카테고리**: system
- **역할**: 사용자 개인 설정 기능을 제공하는 통합 컴포넌트
- **내부 포함 기능**:
  - 프로필 표시 (사용자명, 부서)
  - 테마 선택 (기본/다크/블루/그린)
  - 대시보드 보이기/숨기기 체크박스 (같은 화면의 userConfigurable=true 컴포넌트를 자동 수집)
  - 하단 메뉴 보이기/숨기기
  - 드래그앤드롭으로 순서 변경
- **디자이너가 설정하는 것**: 크기(그리드에서 차지하는 영역), 내부 라벨/아이콘 크기와 위치
- **사용자가 하는 것**: 체크박스로 컴포넌트 보이기/숨기기, 테마 선택, 순서 변경
- **데이터**: 같은 화면의 layout_data에서 컴포넌트 목록을 자동 수집
- **저장**: 사용자별 설정을 localStorage에 저장 (데스크탑 패턴 따름)
- **이벤트**:
  - 수신: 없음
  - 발행: visibility_changed (컴포넌트 보이기/숨기기 변경 시), theme_changed (테마 변경 시)
- **설정**: 내부 라벨 크기, 아이콘 크기, 위치 정도만
- **특이사항**:
  - 디자이너가 이 컴포넌트를 배치하지 않으면 해당 화면에 개인 설정 기능이 없다
  - 디자이너가 "이 화면에 설정 기능을 넣을지 말지"를 직접 결정하는 구조
  - 메인 홈에는 배치, 업무 화면(입고 등)에는 안 배치하는 식으로 사용

---

## 컴포넌트 간 통신 예시

### 예시 1: 검색 -> 필터 연동

```mermaid
sequenceDiagram
  participant Search as pop-search
  participant Dashboard as pop-dashboard
  participant Table as pop-table

  Note over Search: 사용자가 창고 WH01 선택
  Search->>Dashboard: filter_changed
  Search->>Table: filter_changed
  Note over Dashboard: DataSource 재조회
  Note over Table: DataSource 재조회
```

### 예시 2: 데이터 전달 + 선택적 저장

```mermaid
sequenceDiagram
  participant Table as pop-table
  participant Field as pop-field
  participant Button as pop-button

  Note over Table: 사용자가 발주 행 선택
  Table->>Field: row_selected
  Table->>Button: row_selected
  Note over Field: 사용자가 qty를 500으로 입력
  Field->>Button: value_changed
  Note over Button: 사용자가 저장 클릭
  Note over Button: write/readwrite 컬럼만 추출하여 저장
  Button->>Table: save_complete
  Note over Table: 데이터 새로고침
```

### 예시 3: pop-lookup 거래처 선택 -> 품목 조회

```mermaid
sequenceDiagram
  participant Lookup as pop-lookup
  participant Table as pop-table

  Note over Lookup: 사용자가 거래처 필드 클릭
  Note over Lookup: 모달 열림 - 거래처 목록 표시
  Note over Lookup: 사용자가 대한금속 선택
  Note over Lookup: 모달 닫힘 - 필드에 대한금속 표시
  Lookup->>Table: filter_changed { company: "대한금속" }
  Note over Table: company=대한금속 필터로 재조회
  Note over Table: 발주 품목 3건 표시
```

### 예시 4: 컬럼별 읽기/쓰기 분리 동작

5개 컬럼이 있는 발주 화면:

- item_code (read) -> 화면에 표시, 저장 안 함
- item_name (read, 조인) -> item_info 테이블에서 가져옴, 저장 안 함
- inbound_qty (readwrite) -> 화면에 표시 + 사용자 수정 + 저장
- warehouse (write) -> 사용자 입력 + 저장
- memo (write) -> 사용자 입력 + 저장

저장 API 호출 시: `{ inbound_qty: 500, warehouse: "WH01", memo: "긴급" }` 만 전달
조회 API 호출 시: 5개 컬럼 전부 + 조인된 item_name까지 조회

---

## 구현 우선순위

- Phase 0 (공통 인프라): ColumnBinding, JoinConfig, DataSourceConfig 타입, useDataSource 훅 (CRUD 포함), usePopEvent 훅 (데이터 전달 포함), PopActionConfig 타입
- Phase 1 (기본 표시): pop-dashboard (KPI 카드 서브타입부터)
- Phase 2 (기본 액션): pop-button, pop-icon
- Phase 3 (데이터 목록): pop-table (테이블형부터, 카드형은 후순위)
- Phase 4 (입력/연동): pop-search, pop-field, pop-lookup
- Phase 5 (고도화): pop-table 카드 템플릿, 차트, 게이지
- Phase 6 (시스템): pop-system (프로필, 테마, 대시보드 보이기/숨기기 통합)

## 참고 파일

- 레지스트리: `frontend/lib/registry/PopComponentRegistry.ts`
- 기존 텍스트 컴포넌트: `frontend/lib/registry/pop-components/pop-text.tsx`
- 공통 스타일 타입: `frontend/lib/registry/pop-components/types.ts`
- POP 타입 정의: `frontend/components/pop/designer/types/pop-layout.ts`
- 기존 스펙 (v4): `popdocs/components-spec.md`