# 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. 프로젝트 디렉토리 구조 및 역할 ```text 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. 요약 및 권장 사항 1. **완성도 높은 비동기 아키텍처**: BullMQ를 활용해 고부하 작업인 오피스/도면 뷰어용 PDF 변환과 AI 처리, 폴더 ZIP 생성 등을 이벤트 기반 비동기로 처리하는 완성도 높은 분산 처리 설계를 따르고 있습니다. 2. **AI-Native 설계**: Gemini의 Structured Output 기능을 선제적으로 결합하여, 단순 텍스트 검색을 넘어 공문 및 문서 자료의 지능형 분류 및 메타데이터 정리를 자동화하였습니다. 3. **향후 개선 가능 영역**: - 현재 백그라운드 워커(`Worker`)들이 해당 Node.js 앱 외에 외부 서버/컴퓨터(자체 실행 스크립트 등)에서 백업 처리되고 있을 수 있으므로 Redis 연결 정보의 동기화 상태 점검이 필요합니다. - 데이터베이스 접속 부하 관리를 위해 `idleTimeoutMillis`와 `connectionTimeoutMillis`를 각각 5초로 비교적 타이트하게 구성해 두었으므로 다중 사용자 접속 시 DB 커넥션 고갈 가능성을 상시 모니터링해야 합니다.