ERP-node/popdocs/FILES.md

# POP 파일 상세 목록

**최종 업데이트: 2026-02-05 (v5 그리드 시스템 통합)**

이 문서는 POP 화면 시스템과 관련된 모든 파일을 나열하고 각 파일의 역할을 설명합니다.

---

## 목차

1. [App Router 파일](#1-app-router-파일)
2. [Designer 파일](#2-designer-파일)
3. [Panels 파일](#3-panels-파일)
4. [Renderers 파일](#4-renderers-파일)
5. [Types 파일](#5-types-파일)
6. [Utils 파일](#6-utils-파일)
7. [Management 파일](#7-management-파일)
8. [Dashboard 파일](#8-dashboard-파일)
9. [Library 파일](#9-library-파일)
10. [루트 컴포넌트 파일](#10-루트-컴포넌트-파일)

---

## 1. App Router 파일

### `frontend/app/(pop)/layout.tsx`

| 항목 | 내용 |
|------|------|
| 역할 | POP 전용 레이아웃 래퍼 |
| 라우트 그룹 | `(pop)` - URL에 포함되지 않음 |
| 특징 | 데스크톱과 분리된 터치 최적화 환경 |

---

### `frontend/app/(pop)/pop/page.tsx`

| 항목 | 내용 |
|------|------|
| 역할 | POP 메인 대시보드 |
| 경로 | `/pop` |
| 사용 컴포넌트 | `PopDashboard` |

---

### `frontend/app/(pop)/pop/screens/[screenId]/page.tsx`

| 항목 | 내용 |
|------|------|
| 역할 | 개별 POP 화면 뷰어 (v5 전용) |
| 경로 | `/pop/screens/:screenId` |
| 버전 | v5 그리드 시스템 전용 |

**핵심 코드 구조**:

```typescript
// v5 레이아웃 상태
const [layout, setLayout] = useState<PopLayoutDataV5>(createEmptyPopLayoutV5());

// 레이아웃 로드
useEffect(() => {
  const popLayout = await screenApi.getLayoutPop(screenId);
  
  if (isV5Layout(popLayout)) {
    setLayout(popLayout);
  } else {
    // 레거시 레이아웃은 빈 v5로 처리
    setLayout(createEmptyPopLayoutV5());
  }
}, [screenId]);

// v5 그리드 렌더링
{hasComponents ? (
  <PopRenderer
    layout={layout}
    viewportWidth={viewportWidth}
    currentMode={currentModeKey}
    isDesignMode={false}
  />
) : (
  // 빈 화면
)}
```

**제공 기능**:
- 반응형 모드 감지 (useResponsiveModeWithOverride)
- 프리뷰 모드 (`?preview=true`)
- 디바이스/방향 수동 전환 (프리뷰 모드)
- 4개 그리드 모드 지원

---

### `frontend/app/(pop)/pop/work/page.tsx`

| 항목 | 내용 |
|------|------|
| 역할 | 작업 화면 (샘플) |
| 경로 | `/pop/work` |

---

## 2. Designer 파일

### `frontend/components/pop/designer/PopDesigner.tsx`

| 항목 | 내용 |
|------|------|
| 역할 | POP 화면 디자이너 메인 (v5 전용) |
| 의존성 | react-dnd, ResizablePanelGroup |

**핵심 Props**:

```typescript
interface PopDesignerProps {
  selectedScreen: ScreenDefinition;
  onBackToList: () => void;
  onScreenUpdate?: (updatedScreen: Partial<ScreenDefinition>) => void;
}
```

**상태 관리**:

```typescript
// v5 레이아웃
const [layout, setLayout] = useState<PopLayoutDataV5>(createEmptyPopLayoutV5());

// 선택 상태
const [selectedComponentId, setSelectedComponentId] = useState<string | null>(null);

// 그리드 모드 (4개)
const [currentMode, setCurrentMode] = useState<GridMode>("tablet_landscape");

// UI 상태
const [isLoading, setIsLoading] = useState(true);
const [isSaving, setIsSaving] = useState(false);
const [hasChanges, setHasChanges] = useState(false);
```

**주요 핸들러**:

| 핸들러 | 역할 |
|--------|------|
| `handleDropComponent` | 컴포넌트 드롭 (그리드 위치 계산) |
| `handleUpdateComponent` | 컴포넌트 속성 수정 |
| `handleDeleteComponent` | 컴포넌트 삭제 |
| `handleSave` | v5 레이아웃 저장 |

---

### `frontend/components/pop/designer/PopCanvas.tsx`

| 항목 | 내용 |
|------|------|
| 역할 | v5 CSS Grid 기반 캔버스 |
| 렌더링 | CSS Grid (4/6/8/12칸) |
| 모드 | 4개 (태블릿/모바일 x 가로/세로) |

**핵심 Props**:

```typescript
interface PopCanvasProps {
  layout: PopLayoutDataV5;
  selectedComponentId: string | null;
  currentMode: GridMode;
  onModeChange: (mode: GridMode) => void;
  onSelectComponent: (id: string | null) => void;
  onDropComponent: (type: PopComponentType, position: PopGridPosition) => void;
  onUpdateComponent: (componentId: string, updates: Partial<PopComponentDefinitionV5>) => void;
  onDeleteComponent: (componentId: string) => void;
}
```

**뷰포트 프리셋**:

```typescript
const VIEWPORT_PRESETS = [
  { id: "mobile_portrait", label: "모바일 세로", width: 375, height: 667 },    // 4칸
  { id: "mobile_landscape", label: "모바일 가로", width: 667, height: 375 },   // 6칸
  { id: "tablet_portrait", label: "태블릿 세로", width: 768, height: 1024 },   // 8칸
  { id: "tablet_landscape", label: "태블릿 가로", width: 1024, height: 768 },  // 12칸
];
```

**제공 기능**:
- 4개 모드 프리셋 전환
- 줌 컨트롤 (30% ~ 150%)
- 패닝 (Space + 드래그)
- 컴포넌트 드래그 앤 드롭
- 그리드 좌표 계산

---

### `frontend/components/pop/designer/index.ts`

```typescript
export { default as PopDesigner } from "./PopDesigner";
export { default as PopCanvas } from "./PopCanvas";
export { default as ComponentEditorPanel } from "./panels/ComponentEditorPanel";
export { default as PopRenderer } from "./renderers/PopRenderer";
export * from "./types";
export * from "./utils/gridUtils";
```

---

## 3. Panels 파일

### `frontend/components/pop/designer/panels/ComponentEditorPanel.tsx`

| 항목 | 내용 |
|------|------|
| 역할 | v5 컴포넌트 편집 패널 |
| 위치 | 오른쪽 사이드바 |

**핵심 Props**:

```typescript
interface ComponentEditorPanelProps {
  component: PopComponentDefinitionV5 | null;
  currentMode: GridMode;
  onUpdateComponent?: (updates: Partial<PopComponentDefinitionV5>) => void;
  className?: string;
}
```

**3개 탭**:

| 탭 | 아이콘 | 내용 |
|----|--------|------|
| `grid` | Grid3x3 | 그리드 위치 (col, row, colSpan, rowSpan) |
| `settings` | Settings | 라벨, 타입별 설정 |
| `data` | Database | 데이터 바인딩 (Phase 4) |

---

### `frontend/components/pop/designer/panels/index.ts`

```typescript
export { default as ComponentEditorPanel, default } from "./ComponentEditorPanel";
```

---

## 4. Renderers 파일

### `frontend/components/pop/designer/renderers/PopRenderer.tsx`

| 항목 | 내용 |
|------|------|
| 역할 | v5 레이아웃 CSS Grid 렌더러 |
| 입력 | PopLayoutDataV5, viewportWidth, currentMode |

**핵심 Props**:

```typescript
interface PopRendererProps {
  layout: PopLayoutDataV5;
  viewportWidth: number;
  currentMode?: GridMode;
  isDesignMode?: boolean;
  selectedComponentId?: string | null;
  onComponentClick?: (componentId: string) => void;
  onBackgroundClick?: () => void;
  className?: string;
}
```

**CSS Grid 스타일 생성**:

```typescript
const gridStyle: React.CSSProperties = {
  display: "grid",
  gridTemplateColumns: `repeat(${breakpoint.columns}, 1fr)`,
  gridAutoRows: `${breakpoint.rowHeight}px`,
  gap: `${breakpoint.gap}px`,
  padding: `${breakpoint.padding}px`,
};
```

**컴포넌트 위치 변환**:

```typescript
const convertPosition = (position: PopGridPosition): React.CSSProperties => ({
  gridColumn: `${position.col} / span ${position.colSpan}`,
  gridRow: `${position.row} / span ${position.rowSpan}`,
});
```

---

### `frontend/components/pop/designer/renderers/index.ts`

```typescript
export { default as PopRenderer, default } from "./PopRenderer";
```

---

## 5. Types 파일

### `frontend/components/pop/designer/types/pop-layout.ts`

| 항목 | 내용 |
|------|------|
| 역할 | POP 레이아웃 v5 타입 시스템 |
| 버전 | v5 전용 (레거시 제거됨) |

**핵심 타입**:

```typescript
// 그리드 모드
type GridMode = "mobile_portrait" | "mobile_landscape" | "tablet_portrait" | "tablet_landscape";

// 그리드 브레이크포인트
interface GridBreakpoint {
  label: string;
  columns: number;
  minWidth: number;
  maxWidth: number;
  rowHeight: number;
  gap: number;
  padding: number;
}

// v5 레이아웃
interface PopLayoutDataV5 {
  version: "pop-5.0";
  gridConfig: PopGridConfig;
  components: Record<string, PopComponentDefinitionV5>;
  dataFlow: PopDataFlow;
  settings: PopGlobalSettingsV5;
  metadata?: PopLayoutMetadata;
  overrides?: Record<GridMode, PopModeOverrideV5>;
}

// 그리드 위치
interface PopGridPosition {
  col: number;      // 시작 열 (1부터)
  row: number;      // 시작 행 (1부터)
  colSpan: number;  // 열 크기
  rowSpan: number;  // 행 크기
}

// v5 컴포넌트 정의
interface PopComponentDefinitionV5 {
  id: string;
  type: PopComponentType;
  label?: string;
  position: PopGridPosition;
  visibility?: { modes: GridMode[]; defaultVisible: boolean };
  dataBinding?: PopDataBinding;
  style?: PopStylePreset;
  config?: PopComponentConfig;
}
```

**주요 함수**:

| 함수 | 역할 |
|------|------|
| `createEmptyPopLayoutV5()` | 빈 v5 레이아웃 생성 |
| `addComponentToV5Layout()` | v5에 컴포넌트 추가 |
| `createComponentDefinitionV5()` | v5 컴포넌트 정의 생성 |
| `isV5Layout()` | v5 타입 가드 |
| `detectGridMode()` | 뷰포트 너비로 모드 감지 |

---

### `frontend/components/pop/designer/types/index.ts`

```typescript
export * from "./pop-layout";
```

---

## 6. Utils 파일

### `frontend/components/pop/designer/utils/gridUtils.ts`

| 항목 | 내용 |
|------|------|
| 역할 | 그리드 위치 계산 유틸리티 |
| 용도 | 좌표 변환, 겹침 감지, 자동 배치 |

**주요 함수**:

| 함수 | 역할 |
|------|------|
| `convertPositionToMode()` | 12칸 기준 위치를 다른 모드로 변환 |
| `isOverlapping()` | 두 위치 겹침 여부 확인 |
| `resolveOverlaps()` | 겹침 해결 (아래로 밀기) |
| `mouseToGridPosition()` | 마우스 좌표 → 그리드 좌표 |
| `gridToPixelPosition()` | 그리드 좌표 → 픽셀 좌표 |
| `isValidPosition()` | 위치 유효성 검사 |
| `clampPosition()` | 위치 범위 조정 |
| `findNextEmptyPosition()` | 다음 빈 위치 찾기 |
| `autoLayoutComponents()` | 자동 배치 |

---

## 7. Management 파일

### `frontend/components/pop/management/PopCategoryTree.tsx`

| 항목 | 내용 |
|------|------|
| 역할 | POP 화면 카테고리 트리 |
| 기능 | 그룹 추가/수정/삭제, 화면 목록 |

---

### `frontend/components/pop/management/PopScreenSettingModal.tsx`

| 항목 | 내용 |
|------|------|
| 역할 | POP 화면 설정 모달 |
| 기능 | 화면명, 설명, 그룹 설정 |

---

### `frontend/components/pop/management/PopScreenPreview.tsx`

| 항목 | 내용 |
|------|------|
| 역할 | POP 화면 미리보기 |
| 기능 | 썸네일, 기본 정보 표시 |

---

### `frontend/components/pop/management/PopScreenFlowView.tsx`

| 항목 | 내용 |
|------|------|
| 역할 | 화면 간 플로우 시각화 |
| 기능 | 화면 연결 관계 표시 |

---

### `frontend/components/pop/management/index.ts`

```typescript
export { PopCategoryTree } from "./PopCategoryTree";
export { PopScreenSettingModal } from "./PopScreenSettingModal";
export { PopScreenPreview } from "./PopScreenPreview";
export { PopScreenFlowView } from "./PopScreenFlowView";
```

---

## 8. Dashboard 파일

### `frontend/components/pop/dashboard/PopDashboard.tsx`

| 항목 | 내용 |
|------|------|
| 역할 | POP 대시보드 메인 |
| 구성 | 헤더, KPI, 메뉴그리드, 공지, 푸터 |

---

### 기타 Dashboard 컴포넌트

| 파일 | 역할 |
|------|------|
| `DashboardHeader.tsx` | 상단 헤더 |
| `DashboardFooter.tsx` | 하단 푸터 |
| `MenuGrid.tsx` | 메뉴 그리드 |
| `KpiBar.tsx` | KPI 요약 바 |
| `NoticeBanner.tsx` | 공지 배너 |
| `NoticeList.tsx` | 공지 목록 |
| `ActivityList.tsx` | 최근 활동 목록 |

---

## 9. Library 파일

### `frontend/lib/api/popScreenGroup.ts`

| 항목 | 내용 |
|------|------|
| 역할 | POP 화면 그룹 API 클라이언트 |

**API 함수**:

```typescript
async function getPopScreenGroups(searchTerm?: string): Promise<PopScreenGroup[]>
async function createPopScreenGroup(data: CreatePopScreenGroupRequest): Promise<...>
async function updatePopScreenGroup(id: number, data: UpdatePopScreenGroupRequest): Promise<...>
async function deletePopScreenGroup(id: number): Promise<...>
async function ensurePopRootGroup(): Promise<...>
```

---

### `frontend/lib/registry/PopComponentRegistry.ts`

| 항목 | 내용 |
|------|------|
| 역할 | POP 컴포넌트 중앙 레지스트리 |

---

### `frontend/lib/schemas/popComponentConfig.ts`

| 항목 | 내용 |
|------|------|
| 역할 | POP 컴포넌트 설정 스키마 |
| 검증 | Zod 기반 |

---

## 10. 루트 컴포넌트 파일

### `frontend/components/pop/index.ts`

```typescript
export * from "./designer";
export * from "./management";
export * from "./dashboard";
// 개별 컴포넌트 export
```

---

### 기타 루트 레벨 컴포넌트

| 파일 | 역할 |
|------|------|
| `PopApp.tsx` | POP 앱 셸 |
| `PopHeader.tsx` | 공통 헤더 |
| `PopBottomNav.tsx` | 하단 네비게이션 |
| `PopStatusTabs.tsx` | 상태 탭 |
| `PopWorkCard.tsx` | 작업 카드 |
| `PopProductionPanel.tsx` | 생산 패널 |
| `PopSettingsModal.tsx` | 설정 모달 |
| `PopAcceptModal.tsx` | 수락 모달 |
| `PopProcessModal.tsx` | 프로세스 모달 |
| `PopEquipmentModal.tsx` | 설비 모달 |

---

## 파일 수 통계

| 폴더 | 파일 수 | 설명 |
|------|---------|------|
| `app/(pop)` | 4 | App Router 페이지 |
| `components/pop/designer` | 9 | 디자이너 모듈 (v5) |
| `components/pop/management` | 5 | 관리 모듈 |
| `components/pop/dashboard` | 12 | 대시보드 모듈 |
| `components/pop` (루트) | 15 | 루트 컴포넌트 |
| `lib` | 3 | 라이브러리 |
| **총계** | **48** | |

---

## 삭제된 파일 (v5 통합으로 제거)

| 파일 | 이유 |
|------|------|
| `PopCanvasV4.tsx` | v4 Flexbox 캔버스 |
| `PopFlexRenderer.tsx` | v4 Flexbox 렌더러 |
| `PopLayoutRenderer.tsx` | v3 CSS Grid 렌더러 |
| `ComponentRenderer.tsx` | 레거시 컴포넌트 렌더러 |
| `ComponentEditorPanelV4.tsx` | v4 편집 패널 |
| `PopPanel.tsx` | 레거시 팔레트 패널 |
| `test-v4/page.tsx` | v4 테스트 페이지 |

---

*이 문서는 POP 화면 시스템의 파일 목록을 관리하기 위한 참조용으로 작성되었습니다. (v5 그리드 시스템 기준)*