프로젝트 기능명세서 (PROJECT MASTER ver 4.0)

본 명세서는 PROJECT MASTER ver 4.0의 시스템 아키텍처, 주요 기능 모듈, 데이터베이스 구조 및 최근 수정 사항을 기반으로 작성된 기능 명세서입니다.

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)

프론트엔드: HTML5, Vanilla JavaScript, Vanilla CSS, Axios, Socket.io-client, OpenLayers (지도), Cesium (3D 모델)
백엔드: Node.js (Express), Socket.io, BullMQ (비동기 처리 큐), Winston (로깅)
데이터베이스: PostgreSQL (ver4 스키마), Redis (세션/소켓/큐 관리)
스토리지: MinIO / AWS S3 (오브젝트 스토리지)

2. 권한 체계 (User Permission System)

유저 그룹 및 개별 프로젝트 권한 등급에 따라 사용 가능한 기능 및 접근 권한이 제어됩니다.

권한 레벨	그룹/명칭	설명 및 주요 권한
Super / Dev	super / dev	시스템 전체 관리 및 개발자 도구 모달 접근 가능. 비활성 프로젝트 우회 접근.
Master	관리자	프로젝트의 모든 폴더/파일 관리, 권한 설정, 다운로드 가능.
Sub-Master	부관리자	폴더 추가/삭제, 과업개요 정보 수정, 사용자 권한 배정 가능.
Security Worker	보안참여자	보안 폴더 및 파일 읽기/쓰기 권한 부여 가능.
Worker	일반참여자	일반 파일 업로드/다운로드, 메모 작성/수정, AI 요약 기능 사용 가능.
Viewer	참관자	데이터 조회 및 다운로드만 가능 (활동로그, 업로드 버튼 등 DOM 제거).

3. 핵심 기능 명세 (Core Module Specifications)

3.1 아카이브 모듈 (Archive Module)

프로젝트에 업로드된 산출물(폴더 및 파일)을 계층형 구조(트리)로 관리하는 핵심 스토리지 모듈입니다.

계층형 트리 탐색:
- 최대 Depth 4~5 수준의 폴더 및 파일 트리 구조 렌더링.
- 폴더 더블클릭 및 우측 리스트 뷰를 통한 산출물 탐색.
폴더 관리:
- 새 폴더 생성 (createFolder): 관리자 및 부관리자 이상 권한.
- 이름 변경 (renameTarget) 및 다른 폴더로의 위치 이동 (relocateTarget).
파일 업로드 & 다운로드:
- Presigned URL 업로드: 파일 업로드 시 S3/MinIO 보안 Presigned URL을 발급받아 브라우저가 직접 오브젝트 스토리지로 업로드.
- 다중 파일/폴더 ZIP 다운로드: 선택된 폴더나 다중 파일을 서버 측에서 백그라운드 큐(BullMQ)를 이용해 ZIP 압축한 뒤 발급된 다운로드 링크 제공.
휴지통 기능 (Recycle Bin):
- 삭제 시 즉시 지워지지 않고 휴지통으로 이동 (removeTarget).
- 휴지통 내 복원 (restoreTarget) 및 영구 삭제 (deleteTarget) 지원.
뷰어 및 메모:
- PDF 뷰어: 업로드된 문서 파일(HWP, PDF 등)을 PDF 변환 큐를 통해 PDF 표준 규격으로 자동 변환하여 브라우저 내장 뷰어 제공.
- 메모 & AI 요약: 각 파일별 텍스트 메모 기록 및 AI (Gemini 등) 연동을 통한 문서 요약 기능 제공.

3.2 과업개요 모듈 (Overview Module)

프로젝트의 기본 명세, 계약 상황 및 마일스톤 일정을 카드뷰 및 달력 형태로 제공합니다.

기본 개요 관리:
- 사업 목적, 시설 규모, 공동 도급사 분담 비율, 계약 금액, 과업 기간 등 종합 대시보드 제공.
이미지 드래그앤드롭:
- 위치도(Location Map), 개요도(Overview Map) 이미지를 드래그앤드롭하여 스토리지에 간편 업로드.
마일스톤 캘린더:
- 과업 주요 일정을 날짜 기반 달력에 표시 및 관리자 권한을 통한 추가/수정/삭제.
시차 타이머:
- 해외 프로젝트(overseas) 카테고리의 경우, 해당 국가의 표준시 시차를 실시간 계산하여 헤더에 표시.

3.3 공문 모듈 (Official Document Module)

프로젝트 내부/외부와 주고받은 공문서의 교환 현황 및 파일을 송수신 이력 형태로 관리합니다.

수신/발신 문서 대장: 수신처, 발신처, 문서 번호, 발송 일자, 제목 기록.
첨부파일 관리: 공문별 첨부파일을 아카이브 스토리지와 연동하여 보관 및 즉시 다운로드 제공.

3.4 위치기반 모델 모듈 (GSIM)

GIS 지도(OpenLayers) 및 Cesium 3D 엔진을 활용하여 특정 측량 포인트나 3D 지형/구조물 모델을 표시합니다.

2D/3D 배경지도 전환: 일반 지도, 위성 지도, 하이브리드 지도 레이어 제공.
클러스터링: 다수의 포인트를 줌 레벨에 따라 클러스터로 묶어 표현하고 상세 마커 카드 노출.

4. 실시간 및 로그 모듈 (Realtime & Logging)

4.1 실시간 다중 접속자 표시 (Socket.io)

마우스 커서 동기화: 동일 프로젝트에 접속 중인 다른 유저들의 마우스 커서 좌표와 이름표가 실시간으로 지도 및 화면 위에 SVG 객체로 렌더링됩니다.
실시간 데이터 동기화: 파일 업로드 완료, 변환 성공, 폴더 구조 변경 등의 상태가 소켓 이벤트를 통해 즉시 다른 접속자 화면에 동기화(새로고침 없이 반영)됩니다.

4.2 시스템 활동 로그 (System Activity Log)

푸터 실시간 로그: 모든 사용자의 파일 업로드, 다운로드, 폴더 변경 등 핵심 행위가 푸터 영역에 1행 로그 형태로 실시간 갱신됩니다.
상세 로그 검색: 활동 로그 모달창을 통해 사용자, 활동유형, 기간 필터 조건을 만족하는 전체 로그 이력을 페이징 및 정렬하여 조회할 수 있습니다.
사용자 UI 클릭 로그 통계: 상세 활동 추적을 위해 유저의 UI 요소 클릭 액션이 tb_click_log 테이블에 자동 기록됩니다.

5. 예외 및 안정성 처리 (System Robustness)

프론트엔드 캐싱 방지: 동적 API 통신에 Cache-Control: no-store 미들웨어를 두어 브라우저 304 물림으로 인한 이전 에러 응답 재발생을 원천 예방합니다.
서버 크래시 세이프가드: DB 쿼리 오류나 undefined 참조 발생 시, Node.js 프로세스가 비정상 종료(Crash)되지 않도록 핵심 컨트롤러 핸들러 전체에 try-catch 및 널 가드를 배치하였습니다.
원격 에러 추적: 클라이언트 브라우저에서 발생하는 자바스크립트 오류를 실시간 수집하여 서버 콘솔에 🚨 [CLIENT ERROR] 스택 트레이스로 출력해 주는 디버깅 시스템이 구동 중입니다.

7.0 KiB Raw Blame History