11 KiB
11 KiB
PM_ver4 프로젝트 분석 보고서
PM_ver4 프로젝트는 건설 및 엔지니어링 프로젝트를 효율적으로 통합 관리하기 위해 개발된 **웹 기반 프로젝트 관리 시스템(Project Management System)**입니다. 지도 기반 대시보드(Overview), 정교한 문서 저장소(Archive), 수발신 공문 관리(Official Document), 그리고 실시간 통신 및 백그라운드 처리 시스템으로 구성되어 있습니다.
1. 기술 스택 (Technology Stack)
| 구분 | 기술 / 라이브러리 | 설명 |
|---|---|---|
| Backend Core | Node.js (Express) | 웹 API 서버 및 애플리케이션의 핵심 비즈니스 로직 구동 |
| Database | PostgreSQL (pg) |
사용자 정보, 프로젝트 메타데이터, 권한, 파일 트랙킹 기록 보관 |
| WebSockets | Socket.io | 파일 업로드 완료, 변환 상태, AI 요약 진행 상황 등의 실시간 클라이언트 알림 처리 |
| Queue & Worker | BullMQ + Redis (ioredis) |
CPU 소모가 크거나 무거운 작업(PDF 변환, 썸네일 생성, AI 분석, ZIP 압축 등)의 비동기 큐잉 |
| Object Storage | MinIO / Cloudflare R2 (@aws-sdk/client-s3) |
배포 환경(DEPLOYMENT_TYPE)에 따라 자체 온프레미스 MinIO 또는 클라우드 R2 스토리지 선택 연결 |
| AI Integration | Google Gemini API (gemini-2.5-flash) |
PDF 등 문서 데이터 파싱, 스키마에 의한 구조화된 추출, 개조식 자동 요약 제공 |
| Client Rendering | Vanilla JS / CSS / HTML | SPA(Single Page Application) 형태로 속도와 화면 렌더링 최적화 |
| Security | Helmet, Cookie-Parser, JWT | 웹 취약점 보완 및 세션 보호. 서비스 워커 기반 안티 디버깅 탑재 |
2. 프로젝트 디렉토리 구조 및 역할
PM_ver4/
├── app.js # Express 서버 초기 세팅, 미들웨어 설정 및 라우터 매핑
├── server.js # HTTP 서버 생성, 소켓 초기화 및 서비스 포트 오픈 (기본: 6565)
├── socket.js # Socket.io 핸들러 (실시간 정보 전송 전용)
├── queue.js # BullMQ 기반 작업 대기열 정의 (PDF변환, AI요약, ZIP압축 등)
├── logger.js # Winston 기반 일별 순환 로깅 처리
├── config/ # 서버 설정 파일 모음
│ ├── cloudClient.js # Cloudflare R2 스토리지 커넥터 설정
│ ├── onPremiseClient.js # 온프레미스 MinIO 스토리지 커넥터 설정
│ └── redis.js # ioredis를 활용한 Redis 연결 정의
├── db/ # 데이터베이스 레이어
│ ├── config.js # ONPREMISE / CLOUD 데이터베이스 설정 분리
│ ├── index.js # PostgreSQL 연결 유효성 검사 및 풀(Pool) 바인딩
│ └── pool.js # pg Pool 인스턴스 export
├── routes/ # Express 라우팅 정의
│ ├── mainRouter.js # 메인 라우팅 및 호스트명(도메인)별 페이지 포워딩
│ ├── authRouter.js # 사용자 정보, 부서/직급 조회 및 권한 갱신
│ ├── commonRouter.js # 환경 정보, 프로젝트 변경 정보 등 공통 API
│ ├── overviewRouter.js # 프로젝트 대시보드 정보 변경 및 데이터 API
│ ├── archiveRouter.js # 파일/폴더 트리, 압축, AI 요약, 썸네일 API
│ ├── officialDocRouter.js # 공문서(수/발신), 첨부파일 처리, Gemini AI 연동 API
│ └── gsimRouter.js # 프로젝트 단계 및 북마크 연동 API
├── controllers/ # 핵심 비즈니스 로직 (MVC 중 Controller)
│ ├── authController.js # 사용자 로그인/로그아웃, 미세 권한(lev) 부여
│ ├── commonController.js # 공통 메타데이터 조회/수정
│ ├── overviewController.js # 대시보드 수치, 캘린더 이벤트, 시설 크기, 이슈 관리
│ ├── archiveController.js # 파일 트리/삭제/이동, 일괄 다운로드, BullMQ 연동 AI 요약
│ ├── officialDocController.js # 공문 등록/수정/삭제, 실시간 Gemini 구조화 문서 분석
│ └── gsimController.js # GSIM 시스템 정보 동기화 및 갱신
├── oauth/ # OAuth 외부 인증 컴포넌트
│ ├── oauthRouter.js # OAuth 인증 콜백 API
│ ├── oauthController.js # 'Sentinel' SSO 인증 서버와의 토큰 교환 미들웨어
│ └── oauthService.js # 토큰 교환 로직 구현
├── passport/ # 이전 로컬 로그인 모듈 (현재는 OAuth 위주 작동)
├── programs/ # 백엔드 연동 전용 외부 실행 파일(CLI)
│ ├── encryp.exe # 파일 암호화 도구
│ ├── handle.exe / nircmd.exe # 시스템 윈도우 조작 및 프로세스 제어 유틸리티
│ ├── pdf_thumb.exe # PDF 파일의 미리보기 썸네일 이미지 추출 도구
│ ├── dwgToPdfConverter/ # CAD 도면(.dwg, .dxf)을 PDF로 변환하는 모듈
│ ├── hwpConverter/ # 한글(.hwp) 파일을 PDF/HTML로 변환하는 모듈
│ └── msofficeConverter/ # MS 오피스 문서 변환 모듈
├── views/ # 클라이언트 정적 리소스 및 템플릿
│ ├── login/ # 로그인 웹페이지
│ ├── index/ # 각 배포 도메인별 전용 첫 화면 마크업
│ ├── main/ # 메인 대시보드/아카이브 인터페이스 리소스
│ ├── anti_debugging.js # 클라이언트 개발자 도구 및 디버깅 행위 차단 보안 스크립트
│ └── anti-debug-sw.js # 안티 디버깅 강화를 위한 Service Worker
└── package.json # 종속성 관리 및 start 스크립트 정의
3. 핵심 컴포넌트 아키텍처 및 상세 분석
① 다중 배포 및 테넌트 분기 (Multi-Tenant Routing)
mainRouter.js는process.env.SERVICE_NAME에 따라LOCAL,ONPREMISE,CLOUD환경을 판별합니다.- 클라이언트 접속 호스트명(
req.hostname)에 따라bim.,overseas.,jangheon.,gtb.등 각각에 최적화된 메인 화면(index-bim.html,index-overseas.html,index-jangheon.html등)을 반환하여 하나의 서버 코드로 다수의 파트너십 사이트를 지원합니다.
② 스토리지 추상화 및 Presigned URL 통신
- 대용량 도면이나 기밀 문서의 전송 성능 및 보안을 보장하기 위해 클라이언트가 파일을 직접 스토리지에 올리거나 받을 수 있는 Presigned URL 기법을 적용하였습니다.
onPremiseClient(자체 구축 MinIO)와cloudClient(Cloudflare R2)를 동일한 S3 API로 제어하여, 로컬 내부망과 AWS 클라우드 배포판 간의 스토리지 입출력 레이어를 깔끔하게 통일하였습니다.
③ 백그라운드 태스크 관리 (BullMQ & Redis)
- 업로드된 문서의 뷰어 제공을 위해 백엔드에서 변환기가 독립 실행되는 워커 구조를 채택하였습니다.
queue.js에서 생성되는 대기열:convert-pdf: 캐드 도면(DWG)이나 오피스 문서를 PDF로 정적 렌더링.pdf-thumb: PDF의 1페이지를 썸네일 이미지로 캐싱.zip-folder: 사용자가 특정 아카이브 폴더를 다운로드할 때 여러 스토리지 객체들을 비동기로 아카이빙(Zip)하여 준비 완료 시 소켓으로 전달.ai-summarize: 무거운 AI 추출 처리를 백그라운드에서 진행하여 API 제한이나 프론트엔드 연결 유실 방지.
④ 인텔리전트 AI 파싱 (Google Gemini 연동)
officialDocController.js의docGeminiAiAction에서는 멀티파트 업로드로 문서 파일(input_file), 요약 지시서(prompt_file), 출력 포맷 가이드라인(schema_file)을 수집한 뒤 Gemini API에 전달합니다.- Gemini의 Structured Output 기능(
responseSchema지정)을 활용하여 대외비 공문서의 핵심 정보(수신처, 발신처, 공문 번호, 제목 요약, 관련 문서 목록 등)를 완벽히 구조화된 JSON 데이터로 파싱하여 DB에 자동 적재합니다. archiveController.js에서는 개조식 요약 프롬프트를 통해 업로드된 임의의 문서를 요약하는 백그라운드 AI 요약 기능을 수행합니다.
⑤ 세밀한 권한 제어 (Granular Permissions)
- 전통적인 웹 애플리케이션의 단순 그룹 권한을 넘어
tb_permission테이블을 기반으로 사용자별/프로젝트별로 개별 기능에 대한 제어를 수행합니다. - 권한 등급(
lev)은 다음과 같은 상수 비트로 관리됩니다:- Owner (255): 프로젝트 생성자 / 모든 권한 소유
- Sub-Master (191): 부관리자
- Security-Worker (15): 기밀 취급 보안 실무자
- Worker (7): 일반 실무자 / 파일 읽기 및 쓰기 가능
- Viewer (1): 단순 참관자
⑥ 보안 기능
- 공공기관 및 대기업 중심의 도면/문서 취급 플랫폼 특성상 외부 도출 및 소스 분석을 차단하기 위해
anti_debugging.js를 사용합니다. debugger문이 포함된 주기적 무한 루프, 개발자 도구 오픈 감지, Service Worker(anti-debug-sw.js)를 통한 네트워크 격리 처리를 통해 프론트엔드 코드 스니핑과 조작을 효과적으로 차단합니다.
4. 요약 및 권장 사항
- 완성도 높은 비동기 아키텍처: BullMQ를 활용해 고부하 작업인 오피스/도면 뷰어용 PDF 변환과 AI 처리, 폴더 ZIP 생성 등을 이벤트 기반 비동기로 처리하는 완성도 높은 분산 처리 설계를 따르고 있습니다.
- AI-Native 설계: Gemini의 Structured Output 기능을 선제적으로 결합하여, 단순 텍스트 검색을 넘어 공문 및 문서 자료의 지능형 분류 및 메타데이터 정리를 자동화하였습니다.
- 향후 개선 가능 영역:
- 현재 백그라운드 워커(
Worker)들이 해당 Node.js 앱 외에 외부 서버/컴퓨터(자체 실행 스크립트 등)에서 백업 처리되고 있을 수 있으므로 Redis 연결 정보의 동기화 상태 점검이 필요합니다. - 데이터베이스 접속 부하 관리를 위해
idleTimeoutMillis와connectionTimeoutMillis를 각각 5초로 비교적 타이트하게 구성해 두었으므로 다중 사용자 접속 시 DB 커넥션 고갈 가능성을 상시 모니터링해야 합니다.
- 현재 백그라운드 워커(