122 lines
11 KiB
Markdown
122 lines
11 KiB
Markdown
# 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 커넥션 고갈 가능성을 상시 모니터링해야 합니다.
|