프로젝트 개요 - nbacheng/nbcio-boot

기술 스택

백엔드 핵심 프레임워크

Nbcio-Boot의 백엔드 아키텍처는 다음과 같은 기술 스택으로 구성된다:

구분	기술명	버전	용도
기초 프레임워크	Spring Boot	2.3.5.RELEASE	애플리케이션 부트스트래핑 및 의존성 관리
영속성 프레임워크	Mybatis-plus	3.4.3.1	데이터베이스 CRUD 작업 및 동적 SQL
보안 프레임워크	Apache Shiro	1.7.0	인증, 인가, 세션 관리
토큰 기반 인증	JWT	3.11.0	Stateless 인증 토큰 생성 및 검증
데이터베이스 연결 풀	Alibaba Druid	1.1.22	커넥션 풀링 및 SQL 모니터링
캐시 프레임워크	Redis	-	분산 캐시 및 세션 저장소
로깅	Logback	-	구조화된 로그 출력
JSON 처리	Fastjson	-	JSON 직렬화/역직렬화
API 문서화	Swagger-ui	-	REST API 문서 자동 생성
작업 스케줄링	Quartz	-	배치 작업 및 스케줄링

(README.md:24-37)

개발 환경 요구사항

프로젝트 실행을 위한 개발 환경은 다음과 같다:

구분	요구사항	비고
프로그래밍 언어	Java 8	JDK 1.8 이상 필요
통합 개발 환경	STS (Lombok 플러그인 설치) 또는 IDEA	Lombok 어노테이션 처리 필수
의존성 관리	Maven	pom.xml 기반 빌드 관리
데이터베이스	MySQL 5.7+, Oracle 11g, SqlServer, PostgreSQL, 국산 DB 등	다중 데이터베이스 지원
캐시 서버	Redis	분산 캐시 및 세션 클러스터링

(README.md:41-52)

기술 스택 선정 이유

Spring Boot 2.3.5.RELEASE는 안정적인 프로덕션 환경을 제공하며, Mybatis-plus 3.4.3.1은 복잡한 쿼리 작성 없이도 효율적인 데이터 접근이 가능하다. Apache Shiro 1.7.0과 JWT 3.11.0의 조합은 세션 기반 인증과 토큰 기반 인증을 모두 지원하여, 전통적인 웹 애플리케이션과 RESTful API 서비스에 모두 대응할 수 있다. Druid 1.1.22는 SQL 실행 모니터링과 성능 통계를 제공하여 데이터베이스 병목 현상을 조기에 발견할 수 있다 (README.md:24-37).

시스템 아키텍처

모듈 구조도

正在加载图表渲染器...

아키텍처 설명:

클라이언트 계층: nbcio-vue 프론트엔드와 딩딩 클라이언트가 HTTP 요청을 게이트웨이 계층으로 전송한다 (README.md:8-13).
게이트웨이 계층: Swagger UI가 API 문서를 제공하고, Apache Shiro가 인증/인가 필터 역할을 수행하며, JWT 토큰을 검증한다 (README.md:24-37).
비즈니스 계층: Flowable 6.7.2 기반 워크플로우 엔진, ERP 모듈, 채팅 모듈, 급여 승인 모듈이 핵심 비즈니스 로직을 처리한다 (README.md:89-98).
데이터 계층: Mybatis-plus가 ORM 매핑을 담당하고, Druid가 데이터베이스 연결 풀을 관리한다.
인프라 계층: MySQL이 주 데이터 저장소이며, Redis가 캐시와 세션을 관리하고, Quartz가 백그라운드 작업을 스케줄링한다.

핵심 모듈 상세 분석

워크플로우 관리 모듈

职责边界 (책임 경계):

수행하는 기능: Flowable 6.7.2 엔진을 기반으로 프로세스 설계, 폼 정의, 프로세스 시작, 프로세스 흐름, 메시지 알림 기능을 제공한다. 사용자 정의 비즈니스 프로세스 정의와 흐름을 지원한다 (README.md:89-98).
수행하지 않는 기능: 타사 워크플로우 엔진(JBPM, Activiti 등)과의 호환성, 레거시 프로세스 마이그레이션, 복잡한 비즈니스 규칙 엔진 기능은 포함하지 않는다.

진입점 및 핵심 API:

프로세스 정의 API: /workflow/definition/* - BPMN 2.0 XML 업로드 및 배포
프로세스 인스턴스 API: /workflow/process/* - 프로세스 시작, 조회, 종료
태스크 API: /workflow/task/* - 사용자 태스크 할당, 완료, 위임
폼 API: /workflow/form/* - 동적 폼 렌더링 및 데이터 바인딩

핵심 데이터 구조:

yaml
1# 프로세스 정의 요청 구조 (추정)
2ProcessDefinitionRequest:
3  name: string          # 프로세스 이름
4  key: string           # 프로세스 고유 키
5  category: string      # 카테고리
6  xmlContent: string    # BPMN 2.0 XML 내용
7  deploymentName: string # 배포 이름
8
9# 프로세스 인스턴스 응답 구조 (추정)
10ProcessInstanceResponse:
11  id: string            # 인스턴스 ID
12  processDefinitionId: string # 프로세스 정의 ID
13  startTime: datetime   # 시작 시간
14  startUserId: string   # 시작 사용자 ID
15  businessKey: string   # 비즈니스 키
16  variables: map        # 프로세스 변수

핵심 호출 체인:

사용자가 프론트엔드에서 프로세스 시작 요청
Shiro 필터가 인증 토큰 검증
WorkflowController가 요청 수신
Flowable ProcessRuntime 서비스 호출
프로세스 인스턴스 생성 및 초기 변수 설정
첫 번째 사용자 태스크 생성
메시지 알림 서비스가 담당자에게 알림 발송

오류 처리 및 경계 조건:

프로세스 정의가 존재하지 않을 때: NotFoundException 발생, 사용자에게 정의 목록으로 리다이렉트
권한 부족 시: UnauthorizedException 발생, 403 응답 반환
동시성 충돌 시: Optimistic Locking 적용, 재시도 권장 메시지 표시
타임아웃 처리: 장기 실행 프로세스는 비동기로 처리, 상태 폴링 API 제공

ERP 재고 관리 모듈

职责边界 (책임 경계):

수행하는 기능: 프론트엔드에서 ERP 형식의 테이블 선택 기능을 구현하여, 향후 재고 관리 등 ERP 애플리케이션을 지원한다 (README.md:89-98).
수행하지 않는 기능: 완전한 ERP 시스템(재무, 인사, 구매 등), 복잡한 재고 최적화 알고리즘, 다중 창고 관리는 현재 미포함.

진입점 및 핵심 API:

재고 조회 API: /erp/inventory/* - 재고 현황, 이력 조회
입출고 API: /erp/stock/* - 입고, 출고, 조정 처리
마스터 데이터 API: /erp/master/* - 품목, 창고, 거래처 관리

핵심 데이터 구조:

yaml
1# 재고 마스터 구조 (추정)
2InventoryMaster:
3  itemCode: string      # 품목 코드
4  warehouseCode: string # 창고 코드
5  quantity: decimal     # 현재 수량
6  reservedQty: decimal  # 예약 수량
7  availableQty: decimal # 가용 수량
8  unit: string          # 단위
9  lastUpdated: datetime # 최종 수정 일시
10
11# 입출고 트랜잭션 구조 (추정)
12StockTransaction:
13  transactionId: string # 트랜잭션 ID
14  transactionType: enum # IN(입고), OUT(출고), ADJUST(조정)
15  itemCode: string      # 품목 코드
16  quantity: decimal     # 수량
17  warehouseCode: string # 창고 코드
18  referenceNo: string   # 참조 번호
19  transactionDate: datetime # 거래 일시

핵심 호출 체인:

사용자가 입출고 전표 입력
ERP 서비스가 품목 및 창고 유효성 검증
트랜잭션 생성 및 재고 마스터 업데이트
이력 테이블에 변경 사항 기록
연관 모듈(구매, 판매)에 이벤트 발행

오류 처리 및 경계 조건:

음수 재고 방지: 출고 시 가용 재고 확인, 부족 시 InsufficientStockException 발생
동시성 제어: 재고 업데이트 시 데이터베이스 레벨 락 적용
마스터 데이터 무결성: 품목 삭제 시 연관 트랜잭션 존재 여부 확인

딩딩 연동 급여 승인 모듈

职责边界 (책임 경계):

수행하는 기능: 급여 프로세스를 딩딩과 연동하여, 프로세스 정의 후 딩딩을 통해 승인 및 흐름을 처리한다 (README.md:89-98).
수행하지 않는 기능: 딩딩 조직도 동기화, 타사 메신저(슬랙, 위챗 등) 연동, 복잡한 급여 계산 로직은 별도 모듈 담당.

진입점 및 핵심 API:

급여 승인 요청 API: /salary/approval/* - 승인 요청 생성, 조회
딩딩 콜백 API: /dingtalk/callback/* - 딩딩 승인 결과 수신
사용자 매핑 API: /dingtalk/user/* - 시스템 사용자와 딩딩 사용자 매핑

핵심 데이터 구조:

yaml
1# 급여 승인 요청 구조 (추정)
2SalaryApprovalRequest:
3  requestId: string     # 요청 ID
4  applicantId: string   # 신청자 ID
5  departmentCode: string # 부서 코드
6  salaryMonth: string   # 급여 월
7  totalAmount: decimal  # 총 급여액
8  details: list         # 상세 내역
9  dingtalkProcessInstanceId: string # 딩딩 프로세스 인스턴스 ID
10
11# 딩딩 콜백 구조 (추정)
12DingtalkCallback:
13  processInstanceId: string # 프로세스 인스턴스 ID
14  taskId: string        # 태스크 ID
15  userId: string        # 승인자 ID
16  result: enum          # APPROVE(승인), REJECT(반려)
17  comment: string       # 코멘트
18  timestamp: datetime   # 콜백 시간

핵심 호출 체인:

사용자가 급여 승인 요청 생성
시스템이 딩딩 API 호출하여 프로세스 인스턴스 생성
딩딩 클라이언트에서 승인자에게 알림
승인자가 딩딩에서 승인/반려 처리
딩딩이 콜백 API로 결과 전송
시스템이 급여 상태 업데이트 및 신청자에게 알림

오류 처리 및 경계 조건:

딩딩 API 호출 실패 시: 재시도 메커니즘 적용, 실패 시 로컬 큐에 저장
콜백 중복 수신 시: 멱등성 처리로 중복 업데이트 방지
네트워크 타임아웃 시: 비동기 처리, 상태 폴링으로 결과 확인

실시간 채팅 모듈

职责边界 (책임 경계):

수행하는 기능: 사용자 간 실시간 채팅 기능을 제공한다 (README.md:89-98).
수행하지 않는 기능: 파일 전송(이미지, 문서), 음성/영상 통화, 채팅방 권한 관리의 세부 설정은 현재 미포함 가능성.

진입점 및 핵심 API:

메시지 전송 API: /chat/message/* - 메시지 생성, 조회
채팅방 API: /chat/room/* - 채팅방 생성, 참여, 나가기
WebSocket 엔드포인트: /ws/chat - 실시간 메시지 수신

핵심 데이터 구조:

yaml
1# 채팅 메시지 구조 (추정)
2ChatMessage:
3  messageId: string     # 메시지 ID
4  roomId: string        # 채팅방 ID
5  senderId: string      # 발신자 ID
6  content: string       # 메시지 내용
7  messageType: enum     # TEXT, SYSTEM
8  timestamp: datetime   # 전송 시간
9  readBy: list          # 읽은 사용자 목록
10
11# 채팅방 구조 (추정)
12ChatRoom:
13  roomId: string        # 채팅방 ID
14  name: string          # 채팅방 이름
15  type: enum            # PRIVATE(1:1), GROUP(그룹)
16  participants: list    # 참여자 목록
17  lastMessage: ChatMessage # 최근 메시지
18  createdAt: datetime   # 생성 시간

핵심 호출 체인:

사용자가 메시지 전송
WebSocket을 통해 서버로 메시지 전달
서버가 메시지 저장 및 Redis에 발행
Redis Pub/Sub으로 모든 인스턴스에 메시지 브로드캐스트
대상 사용자의 WebSocket 세션으로 메시지 전송
클라이언트가 메시지 수신 및 UI 업데이트

오류 처리 및 경계 조건:

WebSocket 연결 끊김 시: 자동 재연결 메커니즘, 연결 복구 후 미수신 메시지 동기화
메시지 전송 실패 시: 로컬 저장 후 재시도, 최대 3회 시도 후 실패 알림
Redis 장애 시: 폴백으로 데이터베이스 폴링 방식으로 전환

핵심 데이터 흐름

워크플로우 처리 시퀀스

正在加载图表渲染器...

시퀀스 다이어그램 설명:

인증 단계: 사용자 요청이 Shiro 필터를 통과하며 JWT 토큰이 검증된다. 세션 정보는 Redis에서 조회된다 (README.md:24-37).
프로세스 시작: WorkflowController가 Flowable 엔진의 processRuntime.start() 메서드를 호출한다.
데이터베이스 조회: Flowable 엔진이 MySQL에서 BPMN 2.0 XML 프로세스 정의를 조회한다.
인스턴스 생성: 프로세스 인스턴스가 생성되고 런타임 데이터가 MySQL에 저장된다.
알림 발송: 알림 서비스가 Redis 큐에 알림 메시지를 저장하고, 담당자에게 비동기로 발송한다.

급여 승인 프로세스 데이터 흐름

正在加载图表渲染器...

데이터 흐름 설명:

요청 생성: 급여 승인 요청 데이터가 생성되고 데이터베이스에 저장된다 (README.md:89-98).
유효성 검증: 신청자 권한, 부서 코드, 급여 월 등의 데이터가 검증된다.
딩딩 연동: 딩딩 API를 호출하여 프로세스 인스턴스를 생성하고 승인자에게 알림을 발송한다.
콜백 처리: 승인자가 딩딩에서 처리하면 콜백 API가 결과를 수신한다.
멱등성 체크: 동일 콜백이 중복 수신되는 것을 방지하기 위해 Redis에서 처리 여부를 확인한다.
상태 업데이트: 급여 상태가 승인 또는 반려로 업데이트되고 신청자에게 알림이 발송된다.

주요 기능

Flowable 기반 워크플로우 관리

Flowable 6.7.2를 기반으로 한 워크플로우 관리 시스템은 다음 기능을 제공한다:

프로세스 설계: BPMN 2.0 표준을 따르는 프로세스 정의 지원
폼 정의: 동적 폼을 통한 데이터 수집 및 프로세스 변수 바인딩
프로세스 시작: 사용자 정의 비즈니스 키와 함께 프로세스 인스턴스 생성
프로세스 흐름: 조건부 게이트웨이, 병렬 게이트웨이, 서브프로세스 지원
메시지 알림: 태스크 할당, 마감일 임박, 프로세스 완료 시 알림 발송

(README.md:89-98)

딩딩 연동 급여 승인

딩딩과 연동된 급여 승인 프로세스는 다음 특징을 갖는다:

프로세스 정의: 급여 승인을 위한 전용 프로세스 템플릿 제공
딩딩 연동: 딩딩 API를 통한 승인 요청 및 결과 수신
실시간 동기화: 승인 상태가 실시간으로 시스템에 반영
이력 추적: 모든 승인 이력이 데이터베이스에 저장되어 감사 추적 지원

(README.md:89-98)

ERP 형식 재고 관리

프론트엔드에서 ERP 형식의 테이블 선택 기능을 구현하여:

마스터-디테일 구조: 헤더-라인 아이템 형태의 데이터 입력 지원
다중 선택: 품목, 창고 등 마스터 데이터의 다중 선택 기능
실시간 검증: 입력 데이터의 실시간 유효성 검증
확장성: 향후 완전한 재고 관리 시스템으로 확장 가능한 구조

(README.md:89-98)

실시간 채팅

사용자 간 실시간 통신을 위한 채팅 기능:

1:1 채팅: 개인 간 메시지 교환
그룹 채팅: 부서, 프로젝트 단위 그룹 대화
메시지 영속화: 모든 메시지가 데이터베이스에 저장
읽음 확인: 메시지 수신 및 읽음 상태 추적

(README.md:89-98)

적용 시나리오

중소기업 ERP 시스템

Nbcio-Boot는 중소기업을 위한 경량 ERP 시스템으로 적용할 수 있다. MySQL 5.7+ 데이터베이스와 Redis 캐시를 기반으로, 재고 관리, 급여 승인, 워크플로우 관리를 통합된 플랫폼에서 제공한다 (README.md:41-52). 다중 데이터베이스 지원(MySQL, Oracle, SqlServer, PostgreSQL, 국산 DB)으로 기존 인프라와의 통합이 용이하다.

기업 내부 워크플로우 자동화

Flowable 6.7.2 기반 워크플로우 엔진을 통해 기업 내부의 다양한 승인 프로세스를 자동화할 수 있다. 휴가 신청, 경비 처리, 계약 승인 등 반복적인 업무 프로세스를 BPMN 2.0 표준으로 정의하고, 딩딩 연동을 통해 모바일 환경에서도 승인이 가능하다 (README.md:89-98).

협업 플랫폼 구축

실시간 채팅 기능과 워크플로우 관리를 결합하여 기업 내부 협업 플랫폼을 구축할 수 있다. 프로젝트 단위 그룹 채팅, 태스크 할당 알림, 문서 승인 요청 등을 단일 플랫폼에서 처리할 수 있다.

보고서 읽기 가이드

正在加载图表渲染器...

읽기 순서 추천:

프로젝트 개요 (현재 문서): Nbcio-Boot의 전체적인 기술 스택, 핵심 모듈, 주요 기능을 파악
시스템 아키텍처: 모듈 간 의존 관계와 계층 구조 심층 분석
데이터 흐름 분석: 워크플로우 처리, 급여 승인 등 핵심 프로세스의 데이터 흐름 이해
API 설계: RESTful API 엔드포인트 및 요청/응답 구조 확인
데이터 모델: 데이터베이스 스키마 및 엔티티 관계 분석
핵심 기능 상세: 각 모듈의 구현 세부 사항 심층 분석
의존성 그래프: 외부 라이브러리 및 모듈 간 의존 관계 파악

프로젝트 핵심 능력 지표

지표	수치	비고
지원 데이터베이스	5개 이상	MySQL, Oracle, SqlServer, PostgreSQL, 국산 DB 등 (README.md:41-52)
핵심 비즈니스 모듈	4개	워크플로우, ERP, 채팅, 급여 승인 (README.md:89-98)
백엔드 기술 스택	10개 이상	Spring Boot, Mybatis-plus, Shiro, JWT, Druid, Redis, Logback, Fastjson, Swagger, Quartz (README.md:24-37)
워크플로우 표준	BPMN 2.0	Flowable 6.7.2 기반 (README.md:89-98)
외부 연동	딩딩	급여 승인 프로세스 연동 (README.md:89-98)
최소 Java 버전	Java 8	JDK 1.8 이상 필요 (README.md:41-52)

확장 계획

프로젝트는 향후 OA(Office Automation) 및 ERP(Enterprise Resource Planning) 관련 기능을 지속적으로 확장할 계획이다 (README.md:99-104). 현재 구현된 ERP 형식 테이블 선택 기능을 기반으로 완전한 재고 관리, 구매 관리, 판매 관리 모듈이 추가될 예정이다. 또한 워크플로우 엔진을 활용한 전자결재, 일정 관리, 프로젝트 관리 등 OA 기능도 단계적으로 도입될 것이다.