gbpark/invyone
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

22

Browse Source
This commit is contained in:
gbpark
2026-04-07 13:39:14 +09:00
parent 7669baa171
commit e3fe7b640f
41 changed files with 673 additions and 225 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+76 -69
View File
@@ -5,17 +5,17 @@
**INVION**은 제조업 특화 Low-Code ERP/PLM(Product Lifecycle Management) 플랫폼입니다.
사용자가 런타임에 화면·테이블·워크플로우를 정의할 수 있는 **메타데이터 기반 설계**로, 코드 수정 없이 업무 화면을 구성합니다.
듀얼 백엔드(Node.js + Spring Boot) 아키텍처로 점진적 마이그레이션을 지원하며, 멀티테넌시(company_code 기반)로 복수 기업을 단일 인스턴스에서 운영합니다.
Spring Boot + Next.js 풀스택 구조이며, 멀티테넌시(company_code 기반)로 복수 기업을 단일 인스턴스에서 운영합니다.
## 주요 특징
- **Low-Code 화면 디자이너**: 드래그앤드롭으로 업무 화면 구성, V2 컴포넌트 시스템
- **듀얼 백엔드**: Node.js(Express) ↔ Spring Boot(MyBatis) 동일 API 스펙 유지
- **Spring Boot 백엔드**: Java 21 + MyBatis (SqlSessionTemplate) + PostgreSQL
- **v5 Cosmic Glassmorphism UI**: 코스믹 배경 + 글래스 블러 기반 모던 디자인 시스템
- **멀티테넌시**: company_code 기반 데이터 격리, Super Admin 전사 접근
- **멀티 DB 연결**: PostgreSQL(메인) + MSSQL + Oracle + MySQL 외부 DB 지원
- **반응형 디자인**: 데스크톱 / 태블릿 / 모바일 완전 대응
- **3D 시각화**: React Three Fiber 기반 Digital Twin / Yard Layout
- **3D / 차트 / 지도**: React Three Fiber, Recharts, Leaflet 통합
- **GitOps 배포**: Jenkins + Kaniko + Helm + Traefik (Kubernetes)
## 기술 스택
@@ -26,41 +26,34 @@
| 프레임워크 | **Next.js 15** (App Router, Turbopack) | React 19 |
| 언어 | **TypeScript 5** | strict mode |
| 스타일링 | **Tailwind CSS v4** + v5 커스텀 CSS (`--v5-` prefix) | 글래스모피즘 테마 |
| UI 라이브러리 | **shadcn/ui** + Radix UI | 커스텀 오버라이드 |
| 상태 관리 | **Zustand** (글로벌) + **TanStack Query** (서버) | |
| UI 라이브러리 | **shadcn/ui** + Radix UI (15개 컴포넌트) | 커스텀 오버라이드 |
| 상태 관리 | **Zustand 5** (글로벌) + **TanStack Query 5** (서버) | |
| 테이블 | **TanStack Table** + **TanStack Virtual** | 가상 스크롤 |
| HTTP 클라이언트 | **Axios** | 70개 API 모듈 (`lib/api/`) |
| 플로우 디자이너 | **XY Flow** (@xyflow/react) | 데이터플로우 |
| 3D | **React Three Fiber** + Drei | Digital Twin |
| 차트 | **Recharts** + **D3** | 대시보드 / 분석 |
| 지도 | **Leaflet** + React Leaflet | 위치 기반 시각화 |
| 리치 텍스트 | **Tiptap** | 에디터 |
| 드래그앤드롭 | **DnD Kit** | 화면 디자이너 / 탭 정렬 |
| 폼 | **React Hook Form** + Zod | 유효성 검증 |
| 폼 | **React Hook Form** + **Zod** | 유효성 검증 |
| 문서 생성 | **jsPDF** + **exceljs** + mammoth | PDF / Excel / Word |
| 바코드 / QR | **jsbarcode** + **qrcode** + @zxing | 스캔 / 생성 |
| 아이콘 | **Lucide React** | |
### Backend — Node.js (Express)
| 영역 | 기술 | 비고 |
|------|------|------|
| 런타임 | **Node.js 20+** | LTS |
| 프레임워크 | **Express 4** | TypeScript |
| 데이터베이스 | **PostgreSQL** (pg) + MSSQL + Oracle + MySQL | 멀티 DB |
| 인증 | **JWT** (jsonwebtoken) + bcryptjs | |
| 로깅 | **Winston** | |
| 메일 | **Nodemailer** + IMAP | 수신/발신 |
| 바코드 | **bwip-js** | |
| 문서 생성 | **docx** + html-to-docx | |
| 스케줄링 | **node-cron** | 배치 |
### Backend — Spring Boot (마이그레이션 대상)
### Backend — Spring Boot
| 영역 | 기술 | 비고 |
|------|------|------|
| 언어 | **Java 21** | LTS |
| 프레임워크 | **Spring Boot 3.3.x** | |
| 프레임워크 | **Spring Boot 3.3.5** | |
| 빌드 | **Gradle** (Groovy DSL) | |
| SQL Mapper | **MyBatis 3** (SqlSessionTemplate 직접 사용) | Mapper Interface 미사용 |
| 데이터베이스 | **PostgreSQL** + HikariCP | |
| 보안 | **Spring Security** + JWT (jjwt) | |
| JSON | **Jackson** (숫자→문자열 직렬화) | Node API 호환 |
| 보안 | **Spring Security** + JWT (jjwt 0.12.3) | |
| JSON | **Jackson** (숫자→문자열 직렬화, null 키 포함) | |
| 메일 | **Spring Boot Starter Mail** | IMAP 수신 + SMTP 발신 |
| 로깅 | **SLF4J + Logback** | Spring Boot 기본 |
> **아키텍처 핵심**: `Map<String, Object>` 기반 — Low-Code 플랫폼 특성상 테이블/컬럼이 런타임에 결정되므로 DTO 클래스를 사용하지 않습니다. Service에서 `sqlSession`으로 XML을 직접 호출하는 3레이어 구조입니다.
>
@@ -73,11 +66,12 @@
| 영역 | 기술 |
|------|------|
| 컨테이너화 | Docker + Docker Compose |
| E2E 테스트 | **Playwright** |
| 단위 테스트 | Jest + Supertest |
| 백엔드 핫리로드 | **Spring Boot DevTools** |
| 코드 품질 | ESLint + Prettier |
| 백엔드 핫리로드 | nodemon |
| CI/CD | Jenkins |
| CI/CD | **Jenkins** + **Kaniko** (이미지 빌드) |
| 오케스트레이션 | **Kubernetes** + **Helm** (GitOps) |
| 리버스 프록시 | **Traefik** (HTTPS, Let's Encrypt) |
| 컨테이너 레지스트리 | `registry.kpslp.kr` (프라이빗) |
## 프로젝트 구조
@@ -105,23 +99,16 @@ INVION/
│ │ ├── animations/ # 애니메이션 컴포넌트
│ │ └── ... # dashboard, vehicle, tax-invoice 등
│ ├── lib/ # 유틸리티, API 클라이언트, 서비스
│ │ ├── api/ # API 클라이언트 (fetch 직접 사용 금지)
│ │ ├── api/ # Axios 기반 API 클라이언트 (70개 모듈)
│ │ ├── stores/ # Zustand 스토어
│ │ ├── schemas/ # Zod 스키마
│ │ ├── services/ # 프론트 비즈니스 로직
│ │ └── types/ # TypeScript 타입 정의
│ ├── stores/ # 글로벌 Zustand 스토어
│ ├── hooks/ # Custom React Hooks
│ └── styles/ # v5-layout.css (글래스모피즘)
│
├── backend-node/ # Express + TypeScript 백엔드 (~87개 서비스)
│ └── src/
│ ├── app.ts # 엔트리포인트
│ ├── controllers/ # API 컨트롤러
│ ├── services/ # 비즈니스 로직
│ ├── middleware/ # 인증, 에러처리
│ ├── routes/ # 라우터
│ └── config/ # DB 연결 설정
│
├── backend-spring/ # Spring Boot 백엔드 (~95개 컨트롤러, ~96개 XML)
├── backend-spring/ # Spring Boot 백엔드 (95 컨트롤러, 97 서비스, 96 XML)
│ └── src/main/
│ ├── java/com/erp/
│ │ ├── common/ # BaseService (sqlSession 주입)
@@ -137,18 +124,17 @@ INVION/
├── db/ # 데이터베이스
│ └── migrations/ # 순차 마이그레이션 SQL
├── docker/ # Docker 설정 (dev/prod/deploy)
├── scripts/ # 개발/배포 스크립트
├── docs/ # 프로젝트 문서
├── scripts/ # 개발/배포 스크립트 (dev/prod)
├── Dockerfile # 프로덕션 멀티스테이지 빌드 (Spring + Next.js)
└── Jenkinsfile # CI/CD 파이프라인
└── Jenkinsfile # CI/CD 파이프라인 (Kaniko + Helm)
```
## 빠른 시작
### 1. 필수 요구사항
- **Node.js**: 20.10+
- **Java**: 21 (Spring Boot 백엔드 사용 시)
- **Java**: 21
- **Node.js**: 20.10+ (프론트엔드 빌드용)
- **PostgreSQL**: 데이터베이스 서버
- **npm**: 10.0+
@@ -158,9 +144,6 @@ INVION/
# 프론트엔드 (Turbopack, port 9771)
cd frontend && npm install && npm run dev
# 백엔드 — Node.js (port 8080)
cd backend-node && npm install && npm run dev
# 백엔드 — Spring Boot (port 8081)
cd backend-spring && ./gradlew bootRun
```
@@ -181,8 +164,9 @@ docker-compose -f docker/deploy/docker-compose.yml up -d
| 서비스 | URL | 설명 |
|--------|-----|------|
| **프론트엔드** | http://localhost:9771 | Next.js UI |
| **백엔드 (Node)** | http://localhost:8080 | Express REST API |
| **백엔드 (Spring)** | http://localhost:8081 | Spring Boot REST API |
| **백엔드 API** | http://localhost:8081 | Spring Boot REST API |
> 프론트엔드는 `next.config.mjs`의 rewrite 설정으로 `/api/*` 요청을 백엔드(8081)로 프록시합니다.
## 주요 기능
@@ -217,12 +201,15 @@ docker-compose -f docker/deploy/docker-compose.yml up -d
### 7. 기타 기능
- 메일 연동 (IMAP 수신 + SMTP 발신)
- 바코드/라벨 생성 (bwip-js)
- 바코드/QR 생성 및 스캔 (jsbarcode + qrcode + @zxing)
- 대시보드 차트 (Recharts + D3)
- 지도 시각화 (Leaflet)
- 리포트 / 세금계산서
- 문서 생성 (PDF, Excel, Word)
- 다국어 지원
- 번호 채번 규칙
- 배치 스케줄링 + 외부 DB 연동
- 파일/문서 관리 (DOCX 생성)
- 배치 스케줄링
- 파일/문서 관리
## 디자인 시스템 — v5 Cosmic Glassmorphism
@@ -232,7 +219,7 @@ INVION v5는 **코스믹 글래스모피즘** 디자인 언어를 사용합니
- **글래스 UI**: `backdrop-filter: blur()` 기반 반투명 패널
- **CSS 변수**: `--v5-` prefix로 shadcn/Tailwind 변수와 충돌 방지
- **다크/라이트 테마**: 크로스페이드 전환 애니메이션
- **모션 디테일**: 모든 전환/호버/진입에 애니메이션 적용
- **모션 디테일**: 모든 전환/호버/진입에 애니메이션 적용 (CSS 기반, framer-motion 미사용)
주요 스타일 파일:
- `frontend/styles/v5-layout.css` — v5 전체 CSS
@@ -240,19 +227,25 @@ INVION v5는 **코스믹 글래스모피즘** 디자인 언어를 사용합니
## 환경 변수
```bash
# backend-node/.env
DATABASE_URL=postgresql://postgres:password@localhost:5432/dbname
JWT_SECRET=your-jwt-secret
JWT_EXPIRES_IN=24h
PORT=8080
CORS_ORIGIN=http://localhost:9771
```yaml
# backend-spring/src/main/resources/application.yml
# spring.datasource.url, spring.datasource.username, etc.
server:
port: 8081
spring:
datasource:
url: jdbc:postgresql://host:port/dbname
username: postgres
password: ****
jwt:
secret: your-jwt-secret
expiration: 86400000
file:
upload-dir: ./uploads
```
```bash
# frontend/.env.local
NEXT_PUBLIC_API_URL=http://localhost:8080/api
NEXT_PUBLIC_API_URL=http://localhost:8081/api
```
## 배포
@@ -260,13 +253,26 @@ NEXT_PUBLIC_API_URL=http://localhost:8080/api
### 프로덕션 빌드
```bash
# 멀티스테이지 Docker 빌드 (Spring Boot + Next.js)
# 멀티스테이지 Docker 빌드 (Spring Boot + Next.js → 단일 컨테이너)
docker build -t invion .
```
### CI/CD
멀티스테이지 빌드 과정:
1. **Stage 1** — Spring Boot 빌드 (`eclipse-temurin:21-jdk-alpine`, Gradle → bootJar)
2. **Stage 2** — Next.js 빌드 (`node:20.10-alpine`, npm → standalone)
3. **Stage 3** — 런타임 (`eclipse-temurin:21-jre-alpine` + Node.js, 두 서비스 병렬 실행)
Jenkins 파이프라인 (`Jenkinsfile`)으로 자동 빌드 및 배포가 설정되어 있습니다.
### CI/CD 파이프라인
```
Git Push → Jenkins → Kaniko 이미지 빌드 → 프라이빗 레지스트리 푸시
→ Helm 차트 태그 업데이트 → Kubernetes 자동 배포 (GitOps)
```
- **이미지 빌드**: Kaniko (Docker-in-Docker 불필요)
- **레지스트리**: `registry.kpslp.kr` (프라이빗)
- **배포**: Helm 차트 + GitOps (이미지 태그 자동 업데이트)
- **프로덕션 도메인**: Traefik 리버스 프록시 + Let's Encrypt HTTPS
## 코드 컨벤션
@@ -283,10 +289,11 @@ Jenkins 파이프라인 (`Jenkinsfile`)으로 자동 빌드 및 배포가 설정
### 공통 규칙
- **TypeScript**: 엄격한 타입 정의 사용
- **TypeScript**: strict mode 활성화
- **ESLint + Prettier**: 일관된 코드 스타일
- **shadcn/ui**: UI 컴포넌트 표준
- **API 클라이언트**: `frontend/lib/api/` 전용 클라이언트 사용 (fetch 직접 사용 금지)
- **API 클라이언트**: `frontend/lib/api/` Axios 기반 전용 클라이언트 사용 (fetch 직접 사용 금지)
- **멀티테넌시**: 모든 쿼리에 company_code 필터링 필수
- **Map 기반**: Spring Boot 백엔드는 DTO 대신 `Map<String, Object>` 사용
- **snake→camel 변환 금지**: `toCamelCaseKeys()` 등 변환 함수 사용 불가
- **MyBatis 설정**: `map-underscore-to-camel-case: false` 유지