956 lines
32 KiB
Markdown
956 lines
32 KiB
Markdown
# WACE ERP 시스템 전체 워크플로우 문서
|
|
|
|
> 작성일: 2026-02-06
|
|
> 분석 방법: Multi-Agent System (Backend + Frontend + DB 전문가 병렬 분석)
|
|
|
|
---
|
|
|
|
## 목차
|
|
|
|
1. [시스템 개요](#1-시스템-개요)
|
|
2. [기술 스택](#2-기술-스택)
|
|
3. [전체 아키텍처](#3-전체-아키텍처)
|
|
4. [백엔드 아키텍처](#4-백엔드-아키텍처)
|
|
5. [프론트엔드 아키텍처](#5-프론트엔드-아키텍처)
|
|
6. [데이터베이스 구조](#6-데이터베이스-구조)
|
|
7. [인증/인가 워크플로우](#7-인증인가-워크플로우)
|
|
8. [화면 디자이너 워크플로우](#8-화면-디자이너-워크플로우)
|
|
9. [사용자 업무 워크플로우](#9-사용자-업무-워크플로우)
|
|
10. [플로우 엔진 워크플로우](#10-플로우-엔진-워크플로우)
|
|
11. [데이터플로우 시스템](#11-데이터플로우-시스템)
|
|
12. [대시보드 시스템](#12-대시보드-시스템)
|
|
13. [배치/스케줄 시스템](#13-배치스케줄-시스템)
|
|
14. [멀티테넌시 아키텍처](#14-멀티테넌시-아키텍처)
|
|
15. [외부 연동](#15-외부-연동)
|
|
16. [배포 환경](#16-배포-환경)
|
|
|
|
---
|
|
|
|
## 1. 시스템 개요
|
|
|
|
WACE는 **로우코드(Low-Code) ERP 플랫폼**이다. 관리자가 코드 없이 드래그앤드롭으로 업무 화면을 설계하면, 사용자는 해당 화면으로 바로 업무를 처리할 수 있는 구조다.
|
|
|
|
### 핵심 컨셉
|
|
|
|
```
|
|
관리자 → 화면 디자이너로 화면 설계 → 메뉴에 연결
|
|
↓
|
|
사용자 → 메뉴 클릭 → 화면 자동 렌더링 → 업무 수행
|
|
```
|
|
|
|
### 주요 특징
|
|
|
|
- **드래그앤드롭 화면 디자이너**: 코드 없이 UI 구성
|
|
- **동적 컴포넌트 시스템**: V2 통합 컴포넌트 10종으로 모든 UI 표현
|
|
- **플로우 엔진**: 워크플로우(승인, 이동 등) 자동화
|
|
- **데이터플로우**: 비즈니스 로직을 비주얼 다이어그램으로 설계
|
|
- **멀티테넌시**: 회사별 완벽한 데이터 격리
|
|
- **다국어 지원**: KR/EN/CN 다국어 라벨 관리
|
|
|
|
---
|
|
|
|
## 2. 기술 스택
|
|
|
|
| 영역 | 기술 | 비고 |
|
|
|------|------|------|
|
|
| **Frontend** | Next.js 15 (App Router) | React 19, TypeScript |
|
|
| **UI 라이브러리** | shadcn/ui + Radix UI | Tailwind CSS 4 |
|
|
| **상태 관리** | React Context + Zustand | React Query (서버 상태) |
|
|
| **Backend** | Node.js + Express | TypeScript |
|
|
| **Database** | PostgreSQL | Raw Query (ORM 미사용) |
|
|
| **인증** | JWT | 자동 갱신, 세션 관리 |
|
|
| **빌드/배포** | Docker | dev/prod 분리 |
|
|
| **포트** | FE: 9771(dev)/5555(prod) | BE: 8080 |
|
|
|
|
---
|
|
|
|
## 3. 전체 아키텍처
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 사용자 브라우저 │
|
|
│ Next.js App (React 19 + shadcn/ui + Tailwind CSS) │
|
|
│ ├── 인증: JWT + Cookie + localStorage │
|
|
│ ├── 상태: Context + Zustand + React Query │
|
|
│ └── API: Axios Client (lib/api/) │
|
|
└──────────────────────────┬──────────────────────────────────────┘
|
|
│ HTTP/JSON (JWT Bearer Token)
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Express Backend (Node.js) │
|
|
│ ├── Middleware: Helmet → CORS → RateLimit → Auth → Permission │
|
|
│ ├── Routes: 60+ 모듈 │
|
|
│ ├── Controllers: 69개 │
|
|
│ ├── Services: 87개 │
|
|
│ └── Database: pg Pool (Raw Query) │
|
|
└──────────────────────────┬──────────────────────────────────────┘
|
|
│ TCP/SQL
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ PostgreSQL Database │
|
|
│ ├── 시스템 테이블: 사용자, 회사, 메뉴, 권한, 화면 │
|
|
│ ├── 메타데이터: 테이블/컬럼 정의, 코드, 카테고리 │
|
|
│ ├── 비즈니스: 동적 생성 테이블 (화면별) │
|
|
│ └── 멀티테넌시: 모든 테이블에 company_code │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 백엔드 아키텍처
|
|
|
|
### 4.1 디렉토리 구조
|
|
|
|
```
|
|
backend-node/src/
|
|
├── app.ts # Express 앱 진입점
|
|
├── config/ # 환경설정, Multer
|
|
├── controllers/ # 69개 컨트롤러
|
|
├── services/ # 87개 서비스
|
|
├── routes/ # 60+ 라우트 모듈
|
|
├── middleware/ # 인증, 권한, 에러 처리
|
|
│ ├── authMiddleware.ts # JWT 인증
|
|
│ ├── permissionMiddleware.ts # 3단계 권한 체크
|
|
│ ├── superAdminMiddleware.ts # 슈퍼관리자 전용
|
|
│ └── errorHandler.ts # 전역 에러 처리
|
|
├── database/ # DB 연결, 커넥터 팩토리
|
|
│ ├── db.ts # PostgreSQL Pool
|
|
│ ├── DatabaseConnectorFactory.ts
|
|
│ ├── PostgreSQLConnector.ts
|
|
│ ├── MySQLConnector.ts
|
|
│ └── MariaDBConnector.ts
|
|
├── types/ # TypeScript 타입 (26개)
|
|
└── utils/ # 유틸리티 (16개)
|
|
```
|
|
|
|
### 4.2 미들웨어 스택 (실행 순서)
|
|
|
|
```
|
|
요청 → Helmet (보안 헤더)
|
|
→ Compression (응답 압축)
|
|
→ Body Parser (JSON/URLEncoded, 10MB)
|
|
→ CORS (교차 출처 허용)
|
|
→ Rate Limiter (10,000 req/min)
|
|
→ Token Refresh (자동 갱신)
|
|
→ Route Handlers (비즈니스 로직)
|
|
→ Error Handler (전역 에러 처리)
|
|
```
|
|
|
|
### 4.3 API 라우트 도메인별 분류
|
|
|
|
#### 인증/사용자 관리
|
|
| 라우트 | 역할 |
|
|
|--------|------|
|
|
| `/api/auth` | 로그인, 로그아웃, 토큰 갱신, 회사 전환 |
|
|
| `/api/admin/users` | 사용자 CRUD, 비밀번호 초기화, 상태 변경 |
|
|
| `/api/company-management` | 회사 CRUD |
|
|
| `/api/departments` | 부서 관리 |
|
|
| `/api/roles` | 권한 그룹 관리 |
|
|
|
|
#### 화면/메뉴 관리
|
|
| 라우트 | 역할 |
|
|
|--------|------|
|
|
| `/api/screen-management` | 화면 정의 CRUD, 그룹, 파일, 임베딩 |
|
|
| `/api/admin/menus` | 메뉴 트리 CRUD, 화면 할당 |
|
|
| `/api/table-management` | 테이블 CRUD, 엔티티 조인, 카테고리 |
|
|
| `/api/common-codes` | 공통 코드/카테고리 관리 |
|
|
| `/api/multilang` | 다국어 키/번역 관리 |
|
|
|
|
#### 데이터 관리
|
|
| 라우트 | 역할 |
|
|
|--------|------|
|
|
| `/api/data` | 동적 테이블 CRUD, 조인 쿼리 |
|
|
| `/api/data/:tableName` | 특정 테이블 데이터 조회 |
|
|
| `/api/data/join` | 조인 쿼리 실행 |
|
|
| `/api/dynamic-form` | 동적 폼 데이터 저장 |
|
|
| `/api/entity-search` | 엔티티 검색 |
|
|
| `/api/entity-reference` | 엔티티 참조 |
|
|
| `/api/numbering-rules` | 채번 규칙 관리 |
|
|
| `/api/cascading-*` | 연쇄 드롭다운 관계 |
|
|
|
|
#### 자동화
|
|
| 라우트 | 역할 |
|
|
|--------|------|
|
|
| `/api/flow` | 플로우 정의/단계/연결/실행 |
|
|
| `/api/dataflow` | 데이터플로우 다이어그램/실행 |
|
|
| `/api/batch-configs` | 배치 작업 설정 |
|
|
| `/api/batch-management` | 배치 작업 관리 |
|
|
| `/api/batch-execution-logs` | 배치 실행 로그 |
|
|
|
|
#### 대시보드/리포트
|
|
| 라우트 | 역할 |
|
|
|--------|------|
|
|
| `/api/dashboards` | 대시보드 CRUD, 쿼리 실행 |
|
|
| `/api/reports` | 리포트 생성 |
|
|
|
|
#### 외부 연동
|
|
| 라우트 | 역할 |
|
|
|--------|------|
|
|
| `/api/external-db-connections` | 외부 DB 연결 (PostgreSQL, MySQL, MariaDB, MSSQL, Oracle) |
|
|
| `/api/external-rest-api-connections` | 외부 REST API 연결 |
|
|
| `/api/mail` | 메일 발송/수신/템플릿 |
|
|
| `/api/tax-invoice` | 세금계산서 |
|
|
|
|
#### 특수 도메인
|
|
| 라우트 | 역할 |
|
|
|--------|------|
|
|
| `/api/delivery` | 배송/화물 관리 |
|
|
| `/api/risk-alerts` | 위험 알림 |
|
|
| `/api/todos` | 할일 관리 |
|
|
| `/api/bookings` | 예약 관리 |
|
|
| `/api/digital-twin` | 디지털 트윈 (야드 모니터링) |
|
|
| `/api/schedule` | 스케줄 자동 생성 |
|
|
| `/api/vehicle` | 차량 운행 |
|
|
| `/api/driver` | 운전자 관리 |
|
|
| `/api/files` | 파일 업로드/다운로드 |
|
|
| `/api/ddl` | DDL 실행 (슈퍼관리자 전용) |
|
|
|
|
### 4.4 서비스 레이어 패턴
|
|
|
|
```typescript
|
|
// 표준 서비스 패턴
|
|
class ExampleService {
|
|
// 목록 조회 (멀티테넌시 적용)
|
|
async findAll(companyCode: string, filters?: any) {
|
|
if (companyCode === "*") {
|
|
// 슈퍼관리자: 전체 데이터
|
|
return await db.query("SELECT * FROM table ORDER BY company_code");
|
|
} else {
|
|
// 일반 사용자: 자기 회사 데이터만
|
|
return await db.query(
|
|
"SELECT * FROM table WHERE company_code = $1",
|
|
[companyCode]
|
|
);
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4.5 에러 처리 전략
|
|
|
|
```typescript
|
|
// 전역 에러 핸들러 (errorHandler.ts)
|
|
- PostgreSQL 에러: 중복키(23505), 외래키(23503), 널 제약(23502) 등
|
|
- JWT 에러: 만료, 유효하지 않은 토큰
|
|
- 일반 에러: 500 Internal Server Error
|
|
- 개발 환경: 상세 에러 스택 포함
|
|
- 운영 환경: 일반적인 에러 메시지만 반환
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 프론트엔드 아키텍처
|
|
|
|
### 5.1 디렉토리 구조
|
|
|
|
```
|
|
frontend/
|
|
├── app/ # Next.js App Router
|
|
│ ├── (auth)/ # 인증 (로그인)
|
|
│ ├── (main)/ # 메인 앱 (인증 필요)
|
|
│ ├── (pop)/ # 모바일/팝업
|
|
│ └── (admin)/ # 특수 관리자
|
|
├── components/ # React 컴포넌트
|
|
│ ├── screen/ # 화면 디자이너 & 뷰어
|
|
│ ├── admin/ # 관리 기능
|
|
│ ├── dashboard/ # 대시보드 위젯
|
|
│ ├── dataflow/ # 데이터플로우 디자이너
|
|
│ ├── v2/ # V2 통합 컴포넌트
|
|
│ ├── ui/ # shadcn/ui 기본 컴포넌트
|
|
│ └── report/ # 리포트 디자이너
|
|
├── lib/
|
|
│ ├── api/ # API 클라이언트 (57개 모듈)
|
|
│ ├── registry/ # 컴포넌트 레지스트리 (482개)
|
|
│ ├── utils/ # 유틸리티
|
|
│ └── v2-core/ # V2 코어 로직
|
|
├── contexts/ # React Context (인증, 메뉴, 화면 등)
|
|
├── hooks/ # Custom Hooks
|
|
├── stores/ # Zustand 상태관리
|
|
└── middleware.ts # Next.js 인증 미들웨어
|
|
```
|
|
|
|
### 5.2 페이지 라우팅 구조
|
|
|
|
```
|
|
/login → 로그인
|
|
/main → 메인 대시보드
|
|
/screens/[screenId] → 동적 화면 뷰어 (사용자)
|
|
|
|
/admin/screenMng/screenMngList → 화면 관리
|
|
/admin/screenMng/dashboardList → 대시보드 관리
|
|
/admin/screenMng/reportList → 리포트 관리
|
|
/admin/systemMng/tableMngList → 테이블 관리
|
|
/admin/systemMng/commonCodeList → 공통코드 관리
|
|
/admin/systemMng/dataflow → 데이터플로우 관리
|
|
/admin/systemMng/i18nList → 다국어 관리
|
|
/admin/userMng/userMngList → 사용자 관리
|
|
/admin/userMng/companyList → 회사 관리
|
|
/admin/userMng/rolesList → 권한 관리
|
|
/admin/automaticMng/flowMgmtList → 플로우 관리
|
|
/admin/automaticMng/batchmngList → 배치 관리
|
|
/admin/automaticMng/mail/* → 메일 시스템
|
|
/admin/menu → 메뉴 관리
|
|
|
|
/dashboard/[dashboardId] → 대시보드 뷰어
|
|
/pop/work → 모바일 작업 화면
|
|
```
|
|
|
|
### 5.3 V2 통합 컴포넌트 시스템
|
|
|
|
**"하나의 컴포넌트, 여러 모드"** 철학으로 설계된 10개 통합 컴포넌트:
|
|
|
|
| 컴포넌트 | 모드 | 역할 |
|
|
|----------|------|------|
|
|
| **V2Input** | text, number, password, slider, color | 텍스트/숫자 입력 |
|
|
| **V2Select** | dropdown, radio, checkbox, tag, toggle | 선택 입력 |
|
|
| **V2Date** | date, datetime, time, range | 날짜/시간 입력 |
|
|
| **V2List** | table, card, kanban, list | 데이터 목록 표시 |
|
|
| **V2Layout** | grid, split-panel, flex | 레이아웃 구성 |
|
|
| **V2Group** | tab, accordion, section, modal | 그룹 컨테이너 |
|
|
| **V2Media** | image, video, audio, file | 미디어 표시 |
|
|
| **V2Biz** | flow, rack, numbering-rule | 비즈니스 로직 |
|
|
| **V2Hierarchy** | tree, org-chart, BOM, cascading | 계층 구조 |
|
|
| **V2Repeater** | inline-table, modal, button | 반복 데이터 |
|
|
|
|
### 5.4 API 클라이언트 규칙
|
|
|
|
```typescript
|
|
// 절대 금지: fetch 직접 사용
|
|
const res = await fetch('/api/flow/definitions'); // ❌
|
|
|
|
// 반드시 사용: lib/api/ 클라이언트
|
|
import { getFlowDefinitions } from '@/lib/api/flow';
|
|
const res = await getFlowDefinitions(); // ✅
|
|
```
|
|
|
|
환경별 URL 자동 처리:
|
|
| 환경 | 프론트엔드 | 백엔드 API |
|
|
|------|-----------|-----------|
|
|
| 로컬 개발 | localhost:9771 | localhost:8080/api |
|
|
| 운영 | v1.vexplor.com | api.vexplor.com/api |
|
|
|
|
### 5.5 상태 관리 체계
|
|
|
|
```
|
|
전역 상태
|
|
├── AuthContext → 인증/세션/토큰
|
|
├── MenuContext → 메뉴 트리/권한
|
|
├── ScreenPreviewContext → 프리뷰 모드
|
|
├── ScreenMultiLangContext → 다국어 라벨
|
|
├── TableOptionsContext → 테이블 옵션
|
|
└── ActiveTabContext → 활성 탭
|
|
|
|
로컬 상태
|
|
├── Zustand Stores → 화면 디자이너 상태, 사용자 상태
|
|
└── React Query → 서버 데이터 캐시 (5분 stale, 30분 GC)
|
|
```
|
|
|
|
### 5.6 레지스트리 시스템
|
|
|
|
```typescript
|
|
// 컴포넌트 등록 (482개 등록됨)
|
|
ComponentRegistry.registerComponent({
|
|
id: "v2-input",
|
|
name: "통합 입력",
|
|
category: ComponentCategory.V2,
|
|
component: V2Input,
|
|
configPanel: V2InputConfigPanel,
|
|
defaultConfig: { inputType: "text" }
|
|
});
|
|
|
|
// 동적 렌더링
|
|
<DynamicComponentRenderer
|
|
component={componentData}
|
|
formData={formData}
|
|
onFormDataChange={handleChange}
|
|
/>
|
|
```
|
|
|
|
---
|
|
|
|
## 6. 데이터베이스 구조
|
|
|
|
### 6.1 테이블 도메인별 분류
|
|
|
|
#### 사용자/인증/회사
|
|
| 테이블 | 역할 |
|
|
|--------|------|
|
|
| `company_mng` | 회사 마스터 |
|
|
| `user_info` | 사용자 정보 |
|
|
| `user_info_history` | 사용자 변경 이력 |
|
|
| `user_dept` | 사용자-부서 매핑 |
|
|
| `dept_info` | 부서 정보 |
|
|
| `authority_master` | 권한 그룹 마스터 |
|
|
| `authority_sub_user` | 사용자-권한 매핑 |
|
|
| `login_access_log` | 로그인 로그 |
|
|
|
|
#### 메뉴/화면
|
|
| 테이블 | 역할 |
|
|
|--------|------|
|
|
| `menu_info` | 메뉴 트리 구조 |
|
|
| `screen_definitions` | 화면 정의 (screenId, 테이블명 등) |
|
|
| `screen_layouts_v2` | V2 레이아웃 (JSON) |
|
|
| `screen_layouts` | V1 레이아웃 (레거시) |
|
|
| `screen_groups` | 화면 그룹 (계층구조) |
|
|
| `screen_group_screens` | 화면-그룹 매핑 |
|
|
| `screen_menu_assignments` | 화면-메뉴 할당 |
|
|
| `screen_field_joins` | 화면 필드 조인 설정 |
|
|
| `screen_data_flows` | 화면 데이터 플로우 |
|
|
| `screen_table_relations` | 화면-테이블 관계 |
|
|
|
|
#### 메타데이터
|
|
| 테이블 | 역할 |
|
|
|--------|------|
|
|
| `table_type_columns` | 테이블 타입별 컬럼 정의 (회사별) |
|
|
| `table_column_category_values` | 컬럼 카테고리 값 |
|
|
| `code_category` | 공통 코드 카테고리 |
|
|
| `code_info` | 공통 코드 값 |
|
|
| `category_column_mapping` | 카테고리-컬럼 매핑 |
|
|
| `cascading_relation` | 연쇄 드롭다운 관계 |
|
|
| `numbering_rules` | 채번 규칙 |
|
|
| `numbering_rule_parts` | 채번 규칙 파트 |
|
|
|
|
#### 플로우/자동화
|
|
| 테이블 | 역할 |
|
|
|--------|------|
|
|
| `flow_definition` | 플로우 정의 |
|
|
| `flow_step` | 플로우 단계 |
|
|
| `flow_step_connection` | 플로우 단계 연결 |
|
|
| `node_flows` | 노드 플로우 (버튼 액션) |
|
|
| `dataflow_diagrams` | 데이터플로우 다이어그램 |
|
|
| `batch_definitions` | 배치 작업 정의 |
|
|
| `batch_schedules` | 배치 스케줄 |
|
|
| `batch_execution_logs` | 배치 실행 로그 |
|
|
|
|
#### 외부 연동
|
|
| 테이블 | 역할 |
|
|
|--------|------|
|
|
| `external_db_connections` | 외부 DB 연결 정보 |
|
|
| `external_rest_api_connections` | 외부 REST API 연결 |
|
|
|
|
#### 다국어
|
|
| 테이블 | 역할 |
|
|
|--------|------|
|
|
| `multi_lang_key_master` | 다국어 키 마스터 |
|
|
|
|
#### 기타
|
|
| 테이블 | 역할 |
|
|
|--------|------|
|
|
| `work_history` | 작업 이력 |
|
|
| `todo_items` | 할일 목록 |
|
|
| `file_uploads` | 파일 업로드 |
|
|
| `ddl_audit_log` | DDL 감사 로그 |
|
|
|
|
### 6.2 동적 테이블 생성 패턴
|
|
|
|
관리자가 화면 생성 시 비즈니스 테이블이 동적으로 생성된다:
|
|
|
|
```sql
|
|
CREATE TABLE "dynamic_table_name" (
|
|
"id" VARCHAR(500) PRIMARY KEY DEFAULT gen_random_uuid()::text,
|
|
"created_date" TIMESTAMP DEFAULT now(),
|
|
"updated_date" TIMESTAMP DEFAULT now(),
|
|
"writer" VARCHAR(500),
|
|
"company_code" VARCHAR(500), -- 멀티테넌시 필수!
|
|
-- 사용자 정의 컬럼들 (모두 VARCHAR(500))
|
|
"product_name" VARCHAR(500),
|
|
"price" VARCHAR(500),
|
|
...
|
|
);
|
|
CREATE INDEX idx_dynamic_company ON "dynamic_table_name"(company_code);
|
|
```
|
|
|
|
### 6.3 테이블 관계도
|
|
|
|
```
|
|
company_mng (company_code PK)
|
|
│
|
|
├── user_info (company_code FK)
|
|
│ ├── authority_sub_user (user_id FK)
|
|
│ └── user_dept (user_id FK)
|
|
│
|
|
├── menu_info (company_code)
|
|
│ └── screen_menu_assignments (menu_objid FK)
|
|
│
|
|
├── screen_definitions (company_code)
|
|
│ ├── screen_layouts_v2 (screen_id FK)
|
|
│ ├── screen_groups → screen_group_screens (screen_id FK)
|
|
│ └── screen_field_joins (screen_id FK)
|
|
│
|
|
├── authority_master (company_code)
|
|
│ └── authority_sub_user (master_objid FK)
|
|
│
|
|
├── flow_definition (company_code)
|
|
│ ├── flow_step (flow_id FK)
|
|
│ └── flow_step_connection (flow_id FK)
|
|
│
|
|
└── [동적 비즈니스 테이블들] (company_code)
|
|
```
|
|
|
|
---
|
|
|
|
## 7. 인증/인가 워크플로우
|
|
|
|
### 7.1 로그인 프로세스
|
|
|
|
```
|
|
┌─── 사용자 ───┐ ┌─── 프론트엔드 ───┐ ┌─── 백엔드 ───┐ ┌─── DB ───┐
|
|
│ │ │ │ │ │ │ │
|
|
│ ID/PW 입력 │────→│ POST /auth/login │────→│ 비밀번호 검증 │────→│ user_info│
|
|
│ │ │ │ │ │ │ 조회 │
|
|
│ │ │ │ │ JWT 토큰 생성 │ │ │
|
|
│ │ │ │←────│ 토큰 반환 │ │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ │ localStorage 저장│ │ │ │ │
|
|
│ │ │ Cookie 저장 │ │ │ │ │
|
|
│ │ │ /main 리다이렉트 │ │ │ │ │
|
|
└──────────────┘ └──────────────────┘ └──────────────┘ └──────────┘
|
|
```
|
|
|
|
### 7.2 JWT 토큰 관리
|
|
|
|
```
|
|
토큰 저장: localStorage (주 저장소) + Cookie (SSR 미들웨어용)
|
|
|
|
자동 갱신:
|
|
├── 10분마다 만료 시간 체크
|
|
├── 만료 30분 전: 백그라운드 자동 갱신
|
|
├── 401 응답 시: 즉시 갱신 시도
|
|
└── 갱신 실패 시: /login 리다이렉트
|
|
|
|
세션 관리:
|
|
├── 데스크톱: 30분 비활성 → 세션 만료 (5분 전 경고)
|
|
└── 모바일: 24시간 비활성 → 세션 만료 (1시간 전 경고)
|
|
```
|
|
|
|
### 7.3 권한 체계 (3단계)
|
|
|
|
```
|
|
SUPER_ADMIN (company_code = "*")
|
|
├── 모든 회사 데이터 접근 가능
|
|
├── DDL 실행 가능
|
|
├── 시스템 설정 변경
|
|
└── 다른 회사로 전환 (switch-company)
|
|
|
|
COMPANY_ADMIN (userType = "COMPANY_ADMIN")
|
|
├── 자기 회사 데이터만 접근
|
|
├── 사용자 관리 가능
|
|
└── 메뉴/화면 관리 가능
|
|
|
|
USER (일반 사용자)
|
|
├── 자기 회사 데이터만 접근
|
|
├── 권한 그룹에 따른 메뉴 접근
|
|
└── 할당된 화면만 사용 가능
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 화면 디자이너 워크플로우
|
|
|
|
### 8.1 관리자: 화면 설계
|
|
|
|
```
|
|
Step 1: 화면 생성
|
|
└→ /admin/screenMng/screenMngList
|
|
└→ "새 화면" 클릭 → 화면명, 설명, 메인 테이블 입력
|
|
|
|
Step 2: 화면 디자이너 진입 (ScreenDesigner.tsx)
|
|
├── 좌측 패널: 컴포넌트 팔레트 (V2 컴포넌트 10종)
|
|
├── 중앙 캔버스: 드래그앤드롭 영역
|
|
└── 우측 패널: 선택된 컴포넌트 속성 설정
|
|
|
|
Step 3: 컴포넌트 배치
|
|
└→ V2Input 드래그 → 캔버스 배치 → 속성 설정:
|
|
├── 위치: x, y 좌표
|
|
├── 크기: width, height
|
|
├── 데이터 바인딩: columnName = "product_name"
|
|
├── 라벨: "제품명"
|
|
├── 조건부 표시: 특정 조건에서만 보이기
|
|
└── 플로우 연결: 버튼 클릭 시 실행할 플로우
|
|
|
|
Step 4: 레이아웃 저장
|
|
└→ screen_layouts_v2 테이블에 JSON 형태로 저장
|
|
└→ Zod 스키마 검증 → V2 형식 우선, V1 호환 저장
|
|
|
|
Step 5: 메뉴에 화면 할당
|
|
└→ /admin/menu → 메뉴 트리에서 "제품 관리" 선택
|
|
└→ 화면 연결 (screen_menu_assignments)
|
|
```
|
|
|
|
### 8.2 화면 레이아웃 저장 구조 (V2)
|
|
|
|
```json
|
|
{
|
|
"version": "v2",
|
|
"components": [
|
|
{
|
|
"id": "comp-1",
|
|
"componentType": "v2-input",
|
|
"position": { "x": 100, "y": 50 },
|
|
"size": { "width": 200, "height": 40 },
|
|
"config": {
|
|
"inputType": "text",
|
|
"columnName": "product_name",
|
|
"label": "제품명",
|
|
"required": true
|
|
}
|
|
},
|
|
{
|
|
"id": "comp-2",
|
|
"componentType": "v2-list",
|
|
"position": { "x": 100, "y": 150 },
|
|
"size": { "width": 600, "height": 400 },
|
|
"config": {
|
|
"listType": "table",
|
|
"tableName": "products",
|
|
"columns": ["product_name", "price", "quantity"]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 9. 사용자 업무 워크플로우
|
|
|
|
### 9.1 전체 흐름
|
|
|
|
```
|
|
사용자 로그인
|
|
↓
|
|
메인 대시보드 (/main)
|
|
↓
|
|
좌측 메뉴에서 "제품 관리" 클릭
|
|
↓
|
|
/screens/[screenId] 라우팅
|
|
↓
|
|
InteractiveScreenViewer 렌더링
|
|
├── screen_definitions에서 화면 정보 로드
|
|
├── screen_layouts_v2에서 레이아웃 JSON 로드
|
|
├── V2 → Legacy 변환 (호환성)
|
|
└── 메인 테이블 데이터 자동 로드
|
|
↓
|
|
컴포넌트별 렌더링
|
|
├── V2Input → formData 바인딩
|
|
├── V2List → 테이블 데이터 표시
|
|
├── V2Select → 드롭다운/라디오 선택
|
|
└── Button → 플로우/액션 연결
|
|
↓
|
|
사용자 인터랙션
|
|
├── 폼 입력 → formData 업데이트
|
|
├── 테이블 행 선택 → selectedRowsData 업데이트
|
|
└── 버튼 클릭 → 플로우 실행
|
|
↓
|
|
플로우 실행 (nodeFlowButtonExecutor)
|
|
├── Step 1: 데이터 검증
|
|
├── Step 2: API 호출 (INSERT/UPDATE/DELETE)
|
|
├── Step 3: 성공/실패 처리
|
|
└── Step 4: 테이블 자동 새로고침
|
|
```
|
|
|
|
### 9.2 조건부 표시 워크플로우
|
|
|
|
```
|
|
관리자 설정:
|
|
"특별 할인 입력" 컴포넌트
|
|
└→ 조건: product_type === "PREMIUM" 일 때만 표시
|
|
|
|
사용자 사용:
|
|
1. 화면 진입 → evaluateConditional() 실행
|
|
2. product_type ≠ "PREMIUM" → "특별 할인 입력" 숨김
|
|
3. 사용자가 product_type을 "PREMIUM"으로 변경
|
|
4. formData 업데이트 → evaluateConditional() 재평가
|
|
5. product_type === "PREMIUM" → "특별 할인 입력" 표시!
|
|
```
|
|
|
|
---
|
|
|
|
## 10. 플로우 엔진 워크플로우
|
|
|
|
### 10.1 플로우 정의 (관리자)
|
|
|
|
```
|
|
/admin/automaticMng/flowMgmtList
|
|
↓
|
|
플로우 생성:
|
|
├── 이름: "제품 승인 플로우"
|
|
├── 테이블: "products"
|
|
└── 단계 정의:
|
|
Step 1: "신청" (requester)
|
|
Step 2: "부서장 승인" (manager)
|
|
Step 3: "최종 승인" (director)
|
|
연결: Step 1 → Step 2 → Step 3
|
|
```
|
|
|
|
### 10.2 플로우 실행 (사용자)
|
|
|
|
```
|
|
1. 사용자: 제품 신청
|
|
└→ "저장" 버튼 클릭
|
|
└→ flowApi.startFlow() → 상태: "부서장 승인 대기"
|
|
|
|
2. 부서장: 승인 화면
|
|
└→ V2Biz (flow) 컴포넌트 → 현재 단계 표시
|
|
└→ [승인] 클릭 → flowApi.approveStep()
|
|
└→ 상태: "최종 승인 대기"
|
|
|
|
3. 이사: 최종 승인
|
|
└→ [승인] 클릭 → flowApi.approveStep()
|
|
└→ 상태: "완료"
|
|
└→ products.approval_status = "APPROVED"
|
|
```
|
|
|
|
### 10.3 데이터 이동 (moveData)
|
|
|
|
```
|
|
플로우의 핵심 동작: 데이터를 한 스텝에서 다음 스텝으로 이동
|
|
|
|
Step 1 (접수) → Step 2 (검토) → Step 3 (완료)
|
|
├── 단건 이동: moveData(flowId, dataId, fromStep, toStep)
|
|
└── 배치 이동: moveBatchData(flowId, dataIds[], fromStep, toStep)
|
|
```
|
|
|
|
---
|
|
|
|
## 11. 데이터플로우 시스템
|
|
|
|
### 11.1 개요
|
|
|
|
데이터플로우는 비즈니스 로직을 **비주얼 다이어그램**으로 설계하는 시스템이다.
|
|
|
|
```
|
|
/admin/systemMng/dataflow
|
|
↓
|
|
React Flow 기반 캔버스
|
|
├── InputNode: 데이터 입력 (폼 데이터, 테이블 데이터)
|
|
├── TransformNode: 데이터 변환 (매핑, 필터링, 계산)
|
|
├── DatabaseNode: DB 조회/저장
|
|
├── RestApiNode: 외부 API 호출
|
|
├── ConditionNode: 조건 분기
|
|
├── LoopNode: 반복 처리
|
|
├── MergeNode: 데이터 합치기
|
|
└── OutputNode: 결과 출력
|
|
```
|
|
|
|
### 11.2 데이터플로우 실행
|
|
|
|
```
|
|
버튼 클릭 → 데이터플로우 트리거
|
|
↓
|
|
InputNode: formData 수집
|
|
↓
|
|
TransformNode: 데이터 가공
|
|
↓
|
|
ConditionNode: 조건 분기 (가격 > 10000?)
|
|
├── Yes → DatabaseNode: INSERT INTO premium_products
|
|
└── No → DatabaseNode: INSERT INTO standard_products
|
|
↓
|
|
OutputNode: 결과 반환 → toast.success("저장 완료")
|
|
```
|
|
|
|
---
|
|
|
|
## 12. 대시보드 시스템
|
|
|
|
### 12.1 구조
|
|
|
|
```
|
|
관리자: /admin/screenMng/dashboardList
|
|
└→ 대시보드 생성 → 위젯 추가 → 레이아웃 저장
|
|
|
|
사용자: /dashboard/[dashboardId]
|
|
└→ 위젯 그리드 렌더링 → 실시간 데이터 표시
|
|
```
|
|
|
|
### 12.2 위젯 종류
|
|
|
|
| 카테고리 | 위젯 | 역할 |
|
|
|----------|------|------|
|
|
| 시각화 | CustomMetricWidget | 커스텀 메트릭 표시 |
|
|
| | StatusSummaryWidget | 상태 요약 |
|
|
| 리스트 | CargoListWidget | 화물 목록 |
|
|
| | VehicleListWidget | 차량 목록 |
|
|
| 지도 | MapTestWidget | 지도 표시 |
|
|
| | WeatherMapWidget | 날씨 지도 |
|
|
| 작업 | TodoWidget | 할일 목록 |
|
|
| | WorkHistoryWidget | 작업 이력 |
|
|
| 알림 | BookingAlertWidget | 예약 알림 |
|
|
| | RiskAlertWidget | 위험 알림 |
|
|
| 기타 | ClockWidget | 시계 |
|
|
| | CalendarWidget | 캘린더 |
|
|
|
|
---
|
|
|
|
## 13. 배치/스케줄 시스템
|
|
|
|
### 13.1 구조
|
|
|
|
```
|
|
관리자: /admin/automaticMng/batchmngList
|
|
↓
|
|
배치 작업 생성:
|
|
├── 이름: "일일 재고 집계"
|
|
├── 실행 쿼리: SQL 또는 데이터플로우 ID
|
|
├── 스케줄: Cron 표현식 ("0 0 * * *" = 매일 자정)
|
|
└── 활성화/비활성화
|
|
↓
|
|
배치 스케줄러 (batch_schedules)
|
|
↓
|
|
자동 실행 → 실행 로그 (batch_execution_logs)
|
|
```
|
|
|
|
### 13.2 배치 실행 흐름
|
|
|
|
```
|
|
Cron 트리거 → 배치 정의 조회 → SQL/데이터플로우 실행
|
|
↓
|
|
성공: execution_log에 "SUCCESS" 기록
|
|
실패: execution_log에 "FAILED" + 에러 메시지 기록
|
|
```
|
|
|
|
---
|
|
|
|
## 14. 멀티테넌시 아키텍처
|
|
|
|
### 14.1 핵심 원칙
|
|
|
|
```
|
|
모든 비즈니스 테이블: company_code 컬럼 필수
|
|
모든 쿼리: WHERE company_code = $1 필수
|
|
모든 JOIN: ON a.company_code = b.company_code 필수
|
|
모든 집계: GROUP BY company_code 필수
|
|
```
|
|
|
|
### 14.2 데이터 격리
|
|
|
|
```
|
|
회사 A (company_code = "COMPANY_A"):
|
|
└→ 자기 데이터만 조회/수정/삭제 가능
|
|
|
|
회사 B (company_code = "COMPANY_B"):
|
|
└→ 자기 데이터만 조회/수정/삭제 가능
|
|
|
|
슈퍼관리자 (company_code = "*"):
|
|
└→ 모든 회사 데이터 조회 가능
|
|
└→ 일반 회사는 "*" 데이터를 볼 수 없음
|
|
|
|
중요: company_code = "*"는 공통 데이터가 아니라 슈퍼관리자 전용 데이터!
|
|
```
|
|
|
|
### 14.3 코드 패턴
|
|
|
|
```typescript
|
|
// 백엔드 표준 패턴
|
|
const companyCode = req.user!.companyCode;
|
|
|
|
if (companyCode === "*") {
|
|
// 슈퍼관리자: 전체 데이터
|
|
query = "SELECT * FROM table ORDER BY company_code";
|
|
} else {
|
|
// 일반 사용자: 자기 회사만, "*" 제외
|
|
query = "SELECT * FROM table WHERE company_code = $1 AND company_code != '*'";
|
|
params = [companyCode];
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 15. 외부 연동
|
|
|
|
### 15.1 외부 DB 연결
|
|
|
|
```
|
|
지원 DB: PostgreSQL, MySQL, MariaDB, MSSQL, Oracle
|
|
|
|
관리: /api/external-db-connections
|
|
├── 연결 정보 등록 (host, port, database, credentials)
|
|
├── 연결 테스트
|
|
├── 쿼리 실행
|
|
└── 데이터플로우에서 DatabaseNode로 사용
|
|
```
|
|
|
|
### 15.2 외부 REST API 연결
|
|
|
|
```
|
|
관리: /api/external-rest-api-connections
|
|
├── API 엔드포인트 등록 (URL, method, headers)
|
|
├── 인증 설정 (Bearer, Basic, API Key)
|
|
├── 테스트 호출
|
|
└── 데이터플로우에서 RestApiNode로 사용
|
|
```
|
|
|
|
### 15.3 메일 시스템
|
|
|
|
```
|
|
관리: /admin/automaticMng/mail/*
|
|
├── 메일 템플릿 관리
|
|
├── 메일 발송 (개별/대량)
|
|
├── 수신 메일 확인
|
|
└── 발송 이력 조회
|
|
```
|
|
|
|
---
|
|
|
|
## 16. 배포 환경
|
|
|
|
### 16.1 Docker 구성
|
|
|
|
```
|
|
개발 환경 (Mac):
|
|
├── docker/dev/docker-compose.backend.mac.yml (BE: 8080)
|
|
└── docker/dev/docker-compose.frontend.mac.yml (FE: 9771)
|
|
|
|
운영 환경:
|
|
├── docker/prod/docker-compose.backend.prod.yml (BE: 8080)
|
|
└── docker/prod/docker-compose.frontend.prod.yml (FE: 5555)
|
|
```
|
|
|
|
### 16.2 서버 정보
|
|
|
|
| 환경 | 서버 | 포트 | DB |
|
|
|------|------|------|-----|
|
|
| 개발 | 39.117.244.52 | FE:9771, BE:8080 | 39.117.244.52:11132 |
|
|
| 운영 | 211.115.91.141 | FE:5555, BE:8080 | 211.115.91.141:11134 |
|
|
|
|
### 16.3 백엔드 시작 시 자동 작업
|
|
|
|
```
|
|
서버 시작 (app.ts)
|
|
├── 마이그레이션 실행 (DB 스키마 업데이트)
|
|
├── 배치 스케줄러 초기화
|
|
├── 위험 알림 캐시 로드
|
|
└── 메일 정리 Cron 시작
|
|
```
|
|
|
|
---
|
|
|
|
## 부록: 업무 진행 요약
|
|
|
|
### 새로운 업무 화면을 만드는 전체 프로세스
|
|
|
|
```
|
|
1. [DB] 테이블 관리에서 비즈니스 테이블 생성
|
|
└→ 컬럼 정의, 타입 설정
|
|
|
|
2. [화면] 화면 관리에서 새 화면 생성
|
|
└→ 메인 테이블 지정
|
|
|
|
3. [디자인] 화면 디자이너에서 UI 구성
|
|
└→ V2 컴포넌트 배치, 데이터 바인딩
|
|
|
|
4. [로직] 데이터플로우 설계 (필요시)
|
|
└→ 저장/수정/삭제 로직 다이어그램
|
|
|
|
5. [플로우] 플로우 정의 (승인 프로세스 필요시)
|
|
└→ 단계 정의, 연결
|
|
|
|
6. [메뉴] 메뉴에 화면 할당
|
|
└→ 사용자가 접근할 수 있게 메뉴 트리 배치
|
|
|
|
7. [권한] 권한 그룹에 메뉴 할당
|
|
└→ 특정 사용자 그룹만 접근 가능하게
|
|
|
|
8. [사용] 사용자가 메뉴 클릭 → 업무 시작!
|
|
```
|