ERP-node/popdocs/archive/PROJECT_ARCHITECTURE.md

# VEXPLOR (WACE 솔루션) 프로젝트 아키텍처

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

---

## Quick Reference

### 기술 스택 요약

| 영역 | 기술 |
|------|------|
| Frontend | Next.js 14, TypeScript, shadcn/ui, Tailwind CSS |
| Backend | Node.js + Express (주력), Java Spring (레거시) |
| Database | PostgreSQL (173개 테이블) |
| 핵심 기능 | 노코드 화면 빌더, 멀티테넌시, 워크플로우 |

### 디렉토리 맵

```
ERP-node/
├── frontend/              # Next.js
│   ├── app/              # 라우팅 (main, auth, pop)
│   ├── components/       # UI 컴포넌트 (281개+)
│   └── lib/              # API, 레지스트리 (463개)
├── backend-node/         # Node.js 백엔드
│   └── src/
│       ├── controllers/  # 68개
│       ├── services/     # 78개
│       └── routes/       # 47개
├── db/                   # 마이그레이션
└── docs/                 # 문서
```

### 핵심 테이블

| 분류 | 테이블 |
|------|--------|
| 화면 | screen_definitions, screen_layouts_v2, screen_layouts_pop |
| 메뉴 | menu_info, authority_master |
| 사용자 | user_info, company_mng |
| 플로우 | flow_definition, flow_step |

---

## 1. 프로젝트 개요

### 1.1 제품 소개
- **WACE 솔루션**: PLM(Product Lifecycle Management) + 노코드 화면 빌더
- **멀티테넌시**: company_code 기반 회사별 데이터 격리
- **마이그레이션**: JSP에서 Next.js로 완전 전환

### 1.2 핵심 기능
1. **Screen Designer**: 드래그앤드롭 화면 구성
2. **워크플로우**: 플로우 기반 업무 자동화
3. **배치 시스템**: 스케줄 기반 작업 자동화
4. **외부 연동**: DB, REST API 통합
5. **리포트**: 동적 보고서 생성
6. **다국어**: i18n 지원

---

## 2. Frontend 구조

### 2.1 라우트 그룹

```
app/
├── (main)/           # 메인 레이아웃
│   ├── admin/       # 관리자 기능
│   │   ├── screenMng/    # 화면 관리
│   │   ├── systemMng/    # 시스템 관리
│   │   ├── userMng/      # 사용자 관리
│   │   └── automaticMng/ # 자동화 관리
│   ├── screens/[screenId]/  # 동적 화면 뷰어
│   └── dashboard/[id]/      # 대시보드 뷰어
├── (auth)/           # 인증
│   └── login/
└── (pop)/            # POP 전용
    └── pop/screens/[screenId]/
```

### 2.2 주요 컴포넌트

| 폴더 | 파일 수 | 역할 |
|------|---------|------|
| screen/ | 70+ | 화면 디자이너, 위젯 |
| admin/ | 137 | 테이블, 메뉴, 코드 관리 |
| dataflow/ | 101 | 노드 기반 플로우 에디터 |
| dashboard/ | 32 | 대시보드 빌더 |
| v2/ | 20+ | V2 컴포넌트 시스템 |
| pop/ | 26 | POP 전용 컴포넌트 |

### 2.3 라이브러리 (lib/)

```
lib/
├── api/              # API 클라이언트 (50개+)
│   ├── screen.ts    # 화면 API
│   ├── menu.ts      # 메뉴 API
│   └── flow.ts      # 플로우 API
├── registry/         # 컴포넌트 레지스트리 (463개)
│   ├── DynamicComponentRenderer.tsx
│   └── components/
├── v2-core/          # Zod 기반 타입 시스템
└── utils/            # 유틸리티 (30개+)
```

---

## 3. Backend 구조

### 3.1 디렉토리

```
backend-node/src/
├── controllers/      # 68개 컨트롤러
├── services/         # 78개 서비스
├── routes/           # 47개 라우트
├── middleware/       # 인증, 에러 처리
├── database/         # DB 연결
├── types/            # 26개 타입 정의
└── utils/            # 16개 유틸
```

### 3.2 주요 서비스

| 영역 | 서비스 |
|------|--------|
| 화면 | screenManagementService, layoutService |
| 데이터 | dataService, tableManagementService |
| 플로우 | flowDefinitionService, flowExecutionService |
| 배치 | batchService, batchSchedulerService |
| 외부연동 | externalDbConnectionService, externalCallService |

### 3.3 API 엔드포인트

```
# 화면 관리
GET  /api/screen-management/screens
GET  /api/screen-management/screen/:id
POST /api/screen-management/screen
PUT  /api/screen-management/screen/:id
GET  /api/screen-management/layout-v2/:screenId
POST /api/screen-management/layout-v2/:screenId
GET  /api/screen-management/layout-pop/:screenId
POST /api/screen-management/layout-pop/:screenId

# 데이터 CRUD
GET    /api/data/:tableName
POST   /api/data/:tableName
PUT    /api/data/:tableName/:id
DELETE /api/data/:tableName/:id

# 인증
POST /api/auth/login
POST /api/auth/logout
GET  /api/auth/me
```

---

## 4. Database 구조

### 4.1 테이블 분류 (173개)

| 분류 | 개수 | 주요 테이블 |
|------|------|-------------|
| 화면/레이아웃 | 15 | screen_definitions, screen_layouts_v2, screen_layouts_pop |
| 메뉴/권한 | 7 | menu_info, authority_master, rel_menu_auth |
| 사용자/회사 | 6 | user_info, company_mng, dept_info |
| 테이블/컬럼 | 8 | table_type_columns, column_labels |
| 다국어 | 4 | multi_lang_key_master, multi_lang_text |
| 플로우/배치 | 12 | flow_definition, flow_step, batch_configs |
| 외부연동 | 4 | external_db_connections, external_call_configs |
| 리포트 | 5 | report_master, report_layout, report_query |
| 대시보드 | 2 | dashboards, dashboard_elements |
| 컴포넌트 | 6 | component_standards, web_type_standards |
| 비즈니스 | 100+ | item_info, sales_order_mng, inventory_stock |

### 4.2 화면 관련 테이블 상세

```sql
-- 화면 정의
screen_definitions: screen_id, screen_name, table_name, company_code

-- 데스크톱 레이아웃 (V2, 현재 사용)
screen_layouts_v2: id, screen_id, components(JSONB), grid_settings

-- POP 레이아웃
screen_layouts_pop: id, screen_id, components(JSONB), grid_settings

-- 화면 그룹
screen_groups: group_id, group_name, company_code
screen_group_screens: id, group_id, screen_id
```

### 4.3 멀티테넌시

```sql
-- 모든 테이블에 company_code 필수
ALTER TABLE example_table ADD COLUMN company_code VARCHAR(20) NOT NULL;

-- 모든 쿼리에 company_code 필터링 필수
SELECT * FROM example_table WHERE company_code = $1;

-- 예외: company_mng (회사 마스터 테이블)
```

---

## 5. 핵심 기능 상세

### 5.1 노코드 Screen Designer

**아키텍처**:
```
screen_definitions (화면 정의)
    ↓
screen_layouts_v2 (레이아웃, JSONB)
    ↓
DynamicComponentRenderer (동적 렌더링)
    ↓
registry/components (컴포넌트 라이브러리)
```

**컴포넌트 레지스트리**:
- V2 컴포넌트: Input, Select, Table, Button 등
- 위젯: FlowWidget, CategoryWidget 등
- 레이아웃: SplitPanel, TabPanel 등

### 5.2 워크플로우 (Flow)

**테이블 구조**:
```
flow_definition (플로우 정의)
    ↓
flow_step (단계 정의)
    ↓
flow_step_connection (단계 연결)
    ↓
flow_data_status (데이터 상태 추적)
```

### 5.3 POP 시스템

**별도 레이아웃 테이블**:
- `screen_layouts_pop`: POP 전용 레이아웃
- 모바일/태블릿 반응형 지원
- 제조 현장 최적화 컴포넌트

---

## 6. 개발 환경

### 6.1 로컬 개발

```bash
# Docker 실행
docker-compose -f docker-compose.win.yml up -d

# 프론트엔드: http://localhost:9771
# 백엔드: http://localhost:8080
```

### 6.2 데이터베이스

```
Host: 39.117.244.52
Port: 11132
Database: plm
Username: postgres
```

---

## 7. 관련 문서

- [POPUPDATE.md](../POPUPDATE.md): POP 개발 기록
- [docs/pop/components-spec.md](pop/components-spec.md): POP 컴포넌트 설계
- [.cursorrules](../.cursorrules): 개발 가이드라인

---

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