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

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

---

## 1. 시스템 아키텍처 및 연동 구조

```mermaid
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]` 스택 트레이스로 출력해 주는 디버깅 시스템이 구동 중입니다.