1. 시스템 아키텍처 및 연동 구조
본 시스템은 실시간 협업과 대용량 건설 산출물 관리를 위해 웹소켓, 비동기 작업 큐 및 분산 저장소를 포함하는 모던 웹 아키텍처로 구성되어 있습니다.
graph TD
Client[Browser / Client] <-->|HTTP / Axios| NodeServer[Node.js Express Server]
Client <-->|Websocket / Socket.io| NodeServer
NodeServer <-->|SQL Queries| Postgres[(PostgreSQL DB)]
NodeServer <-->|PubSub / Queue| Redis[(Redis Server)]
NodeServer <-->|Presigned URL / PUT| MinIO[(MinIO Object Storage)]
기술 스택 (Tech Stack)
- 프론트엔드 (Frontend): HTML5, Vanilla JavaScript, Vanilla CSS, Axios, Socket.io-client, OpenLayers (GIS), Cesium (3D 모델)
- 백엔드 (Backend): Node.js (Express), Socket.io, BullMQ (비동기 작업 큐), Winston (로깅)
- 데이터베이스 (Database): PostgreSQL (ver4 스키마), Redis (소켓 및 작업 큐 세션 관리)
- 오브젝트 스토리지 (Storage): MinIO / AWS S3 (Presigned URL 및 원격 정적 파일 보관)
2. 사용자 권한 체계 (User Permission System)
사용자 정보 및 소속 프로젝트별로 세분화된 권한 관리를 지원하며, UI 및 API 호출 수준에서 차단 및 필터링이 적용됩니다.
| 권한 레벨 |
그룹/명칭 |
주요 권한 범위 및 설명 |
| Super / Dev |
super / dev |
시스템 전체 관리 및 개발자 전용 모달 접근 권한. 비활성화된 프로젝트 우회 접근 지원. |
| Master |
관리자 |
프로젝트 전반의 산출물 수정/삭제/관리, 개별 폴더/파일별 권한 제어 및 대량 압축 다운로드 권한. |
| Sub-Master |
부관리자 |
신규 폴더 생성 및 삭제, 과업개요 정보 수정, 사용자 권한 배정 및 변경 처리. |
| Security Worker |
보안참여자 |
보안 설정이 적용된 비밀 폴더 및 파일에 대한 읽기/쓰기 권한 부여 및 관리. |
| Worker |
일반참여자 |
일반 산출물 업로드/다운로드, 개인 메모 작성 및 수정, AI 연동 문서 요약(Gemini) 기능 활용. |
| Viewer |
참관자 |
스토리지 조회 및 개별 파일 다운로드만 가능 (활동 로그 노출 방지 및 파일 추가/수정 버튼 숨김). |
3. 핵심 모듈 명세 (Core Module Specifications)
3.1 아카이브 모듈 (Archive Module)
프로젝트별 모든 산출물(도면, 공문, 과업 문서 등)을 관리하는 핵심 가상 스토리지 시스템입니다.
- 폴더 구조 제어: 폴더 생성(createFolder), 이름 변경(renameTarget), 다른 폴더로의 계층식 위치 이동(relocateTarget)을 실시간 지원합니다.
- S3 Presigned URL 업로드: 대용량 업로드 안전성을 위해 서버의 자원을 거치지 않고, 스토리지로부터 Presigned URL을 직접 발급받아 브라우저가 직접 Put Object를 수행합니다.
- 백그라운드 ZIP 압축 다운로드: 대량의 파일이나 폴더 통째 다운로드 시, BullMQ 큐에 작업을 위임하여 서버 부하를 최소화하고 완료 시 다운로드 링크를 팝업으로 제공합니다.
- 가상 휴지통: 삭제된 파일은 즉시 지워지지 않고 휴지통으로 이동하며, 소유자 및 관리자의 승인을 통해 복원하거나 영구 삭제할 수 있습니다.
- 뷰어 및 메모 연동: HWP/DWG 등 다양한 확장자 파일을 PDF로 자동 변환하여 브라우저에서 즉시 열람하는 통합 뷰어를 제공하며, 파일별 텍스트 메모 및 AI 요약 서비스를 연동합니다.
3.2 과업개요 모듈 (Overview Module)
계약 사항 및 상세 마일스톤 정보, 지도 개요도를 하나의 통합 카드뷰 대시보드로 제공합니다.
- 계약 및 사업 정보: 계약 금액(외화 금액 포함), Commencement Date, 준공 예정일, 공동 수급사 구성 지분율 및 대표인 정보를 보관합니다.
- 개요도 드래그앤드롭 업로드: 현장 위치도 및 종합 개요도를 별도 파일 선택창 없이 드래그하여 직관적으로 변경 및 등록할 수 있습니다.
- 과업 일정 캘린더: 연월 단위의 마일스톤 일정을 생성/관리하고 주요 진척도를 실시간 모니터링합니다.
- 시차 연동 실시간 시계: 해외 프로젝트의 경우 해당 현장 국가의 표준시 시차 데이터를 바탕으로 실시간 현지 시각을 헤더에 동적으로 출력합니다.
3.3 공문 모듈 (Official Document Module)
프로젝트 관계 기관 간 송수신된 공문 번호, 날짜, 수신처 목록과 문서를 체계적으로 매핑 및 보관합니다.
- 공문 정보 관리 (발송일, 제목, 수발신처, 문서 번호).
- 공문 매핑 첨부파일 연계 보관 및 1-클릭 다운로드 서비스.
3.4 GSIM (GIS 기반 위치 모델 모듈)
건설 현장의 실제 위경도 좌표 및 고도(Height) 값과 연계하여 모델 및 데이터를 공간 정보와 매핑합니다.
- 2D(OpenLayers) 지도 및 3D(Cesium) 입체 모델 뷰어 탑재.
- 줌 레벨에 최적화된 마커 클러스터링(Clustering) 기법으로 대량의 포인트를 성능 저하 없이 표시.
4. 실시간 동기화 및 로그 모듈
4.1 Websocket 다중 접속자 커서 (Socket.io)
프로젝트 협업 효율성을 극대화하기 위해 다중 유저 동시 접속 시 각 유저의 Client 마우스 움직임을 추적하여 화면상에 실시간으로 커서 위치와 소속/이름표를 그려줍니다.
4.2 실시간 로그 및 클릭 통계
- 푸터 실시간 한 줄 로그: 파일 생성, 삭제, 변환 등 유저가 수행한 핵심 행위가 푸터의 띠 배너 형태로 전 유저에게 실시간 브로드캐스트됩니다.
- 클릭 활동 추적: 향후 화면 분석 및 건설 관리 통계용으로 유저가 누르는 주요 탭, 버튼 등의 액션을 수집하여
tb_click_log 테이블에 실시간으로 기록합니다.
5. 안정성 및 장애 예방 설계 (Reliability & Robustness)
💡 최신 패치 반영 사항 (System Resilience)
- 캐시 잠김 해제 미들웨어: GET 요청 중 정적 자원을 제외한 비동기 동적 API 요청에 대하여 브라우저 304 캐시를 완전히 강제 무효화함으로써, 이전 에러 데이터에 의한 화면 중단 현상을 원천 방지하였습니다.
- 서버 Crash 방어 널가드 (Null-Guard): DB 조회 쿼리 등에서 일시적인 커넥션 유실이나 스키마 에러가 나더라도 백엔드 프로세스가 통째로 죽지 않도록, 주요 API 핸들러 전반에 예외 위임(try-catch) 및 Null 체크 조건문을 완비하였습니다.
- 클라이언트 실시간 디버거: 사용자 브라우저 상에서 유발된 자바스크립트 크래시 및 미처리 거부(Unhandled Rejection) 오류를 백엔드 콘솔로 자동 수집/출력해 주는 에러 추적 스크립트를 내장하였습니다.