344 lines
15 KiB
HTML
344 lines
15 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="ko">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>PROJECT MASTER ver 4.0 기능명세서</title>
|
|
<!-- Google Fonts - Inter & Noto Sans KR -->
|
|
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600;700&family=Noto+Sans+KR:wght@300;400;500;700&display=swap" rel="stylesheet">
|
|
|
|
<style>
|
|
:root {
|
|
--primary: #10b981;
|
|
--primary-dark: #047857;
|
|
--primary-light: #ecfdf5;
|
|
--bg: #f8fafc;
|
|
--card-bg: #ffffff;
|
|
--text-main: #0f172a;
|
|
--text-muted: #475569;
|
|
--border: #e2e8f0;
|
|
--shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
|
|
--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
|
|
}
|
|
|
|
body {
|
|
font-family: 'Inter', 'Noto Sans KR', sans-serif;
|
|
background-color: var(--bg);
|
|
color: var(--text-main);
|
|
line-height: 1.7;
|
|
margin: 0;
|
|
padding: 0;
|
|
}
|
|
|
|
.container {
|
|
max-width: 1000px;
|
|
margin: 40px auto;
|
|
padding: 40px;
|
|
background-color: var(--card-bg);
|
|
border-radius: 16px;
|
|
box-shadow: var(--shadow-lg);
|
|
border: 1px solid var(--border);
|
|
}
|
|
|
|
/* Header Styling */
|
|
header {
|
|
border-bottom: 2px solid var(--border);
|
|
padding-bottom: 24px;
|
|
margin-bottom: 40px;
|
|
position: relative;
|
|
}
|
|
|
|
h1 {
|
|
font-size: 2.2rem;
|
|
font-weight: 700;
|
|
margin: 0 0 8px 0;
|
|
background: linear-gradient(135deg, var(--primary-dark) 0%, var(--primary) 100%);
|
|
-webkit-background-clip: text;
|
|
-webkit-text-fill-color: transparent;
|
|
}
|
|
|
|
.subtitle {
|
|
font-size: 1.1rem;
|
|
color: var(--text-muted);
|
|
margin: 0;
|
|
}
|
|
|
|
/* Typography & Structure */
|
|
h2 {
|
|
font-size: 1.6rem;
|
|
font-weight: 700;
|
|
color: var(--primary-dark);
|
|
margin-top: 40px;
|
|
margin-bottom: 20px;
|
|
display: flex;
|
|
align-items: center;
|
|
border-left: 5px solid var(--primary);
|
|
padding-left: 12px;
|
|
}
|
|
|
|
h3 {
|
|
font-size: 1.25rem;
|
|
font-weight: 600;
|
|
color: var(--text-main);
|
|
margin-top: 30px;
|
|
margin-bottom: 12px;
|
|
border-bottom: 1px dashed var(--border);
|
|
padding-bottom: 6px;
|
|
}
|
|
|
|
p, li {
|
|
font-size: 1rem;
|
|
color: var(--text-muted);
|
|
}
|
|
|
|
ul {
|
|
padding-left: 20px;
|
|
margin-bottom: 20px;
|
|
}
|
|
|
|
li {
|
|
margin-bottom: 8px;
|
|
}
|
|
|
|
/* Premium Table Styles */
|
|
table {
|
|
width: 100%;
|
|
border-collapse: collapse;
|
|
margin: 24px 0;
|
|
font-size: 0.95rem;
|
|
box-shadow: var(--shadow);
|
|
border-radius: 8px;
|
|
overflow: hidden;
|
|
border: 1px solid var(--border);
|
|
}
|
|
|
|
th {
|
|
background-color: var(--primary-dark);
|
|
color: #ffffff;
|
|
font-weight: 600;
|
|
text-align: left;
|
|
padding: 14px 16px;
|
|
}
|
|
|
|
td {
|
|
padding: 14px 16px;
|
|
border-bottom: 1px solid var(--border);
|
|
background-color: #ffffff;
|
|
color: var(--text-muted);
|
|
}
|
|
|
|
tr:last-child td {
|
|
border-bottom: none;
|
|
}
|
|
|
|
tr:nth-child(even) td {
|
|
background-color: #f8fafc;
|
|
}
|
|
|
|
tr:hover td {
|
|
background-color: var(--primary-light);
|
|
color: var(--primary-dark);
|
|
transition: all 0.2s ease;
|
|
}
|
|
|
|
/* Mermaid Wrapper */
|
|
.diagram-container {
|
|
background-color: #f8fafc;
|
|
border: 1px solid var(--border);
|
|
border-radius: 12px;
|
|
padding: 24px;
|
|
margin: 24px 0;
|
|
display: flex;
|
|
justify-content: center;
|
|
box-shadow: inset 0 2px 4px 0 rgb(0 0 0 / 0.05);
|
|
}
|
|
|
|
.mermaid {
|
|
width: 100%;
|
|
display: flex;
|
|
justify-content: center;
|
|
}
|
|
|
|
/* Highlight Boxes (Alerts) */
|
|
.alert {
|
|
background-color: var(--primary-light);
|
|
border-left: 4px solid var(--primary);
|
|
border-radius: 4px 8px 8px 4px;
|
|
padding: 16px 20px;
|
|
margin: 24px 0;
|
|
color: var(--primary-dark);
|
|
}
|
|
|
|
.alert-title {
|
|
font-weight: 700;
|
|
margin-bottom: 4px;
|
|
}
|
|
|
|
/* Responsive Design */
|
|
@media (max-width: 768px) {
|
|
.container {
|
|
margin: 0;
|
|
padding: 20px;
|
|
border-radius: 0;
|
|
box-shadow: none;
|
|
border: none;
|
|
}
|
|
h1 {
|
|
font-size: 1.8rem;
|
|
}
|
|
table {
|
|
display: block;
|
|
overflow-x: auto;
|
|
}
|
|
}
|
|
</style>
|
|
|
|
<!-- Mermaid.js CDN for dynamic rendering of charts -->
|
|
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
|
|
<script>
|
|
mermaid.initialize({
|
|
startOnLoad: true,
|
|
theme: 'neutral',
|
|
securityLevel: 'loose'
|
|
});
|
|
</script>
|
|
</head>
|
|
<body>
|
|
|
|
<div class="container">
|
|
<header>
|
|
<h1>PROJECT MASTER ver 4.0 기능명세서</h1>
|
|
<p class="subtitle">시스템 아키텍처, 기능 명세 및 운영 가이드라인</p>
|
|
</header>
|
|
|
|
<h2>1. 시스템 아키텍처 및 연동 구조</h2>
|
|
<p>본 시스템은 실시간 협업과 대용량 건설 산출물 관리를 위해 웹소켓, 비동기 작업 큐 및 분산 저장소를 포함하는 모던 웹 아키텍처로 구성되어 있습니다.</p>
|
|
|
|
<div class="diagram-container">
|
|
<div class="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)]
|
|
</div>
|
|
</div>
|
|
|
|
<h3>기술 스택 (Tech Stack)</h3>
|
|
<ul>
|
|
<li><strong>프론트엔드 (Frontend)</strong>: HTML5, Vanilla JavaScript, Vanilla CSS, Axios, Socket.io-client, OpenLayers (GIS), Cesium (3D 모델)</li>
|
|
<li><strong>백엔드 (Backend)</strong>: Node.js (Express), Socket.io, BullMQ (비동기 작업 큐), Winston (로깅)</li>
|
|
<li><strong>데이터베이스 (Database)</strong>: PostgreSQL (ver4 스키마), Redis (소켓 및 작업 큐 세션 관리)</li>
|
|
<li><strong>오브젝트 스토리지 (Storage)</strong>: MinIO / AWS S3 (Presigned URL 및 원격 정적 파일 보관)</li>
|
|
</ul>
|
|
|
|
<h2>2. 사용자 권한 체계 (User Permission System)</h2>
|
|
<p>사용자 정보 및 소속 프로젝트별로 세분화된 권한 관리를 지원하며, UI 및 API 호출 수준에서 차단 및 필터링이 적용됩니다.</p>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>권한 레벨</th>
|
|
<th>그룹/명칭</th>
|
|
<th>주요 권한 범위 및 설명</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><strong>Super / Dev</strong></td>
|
|
<td>super / dev</td>
|
|
<td>시스템 전체 관리 및 개발자 전용 모달 접근 권한. 비활성화된 프로젝트 우회 접근 지원.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>Master</strong></td>
|
|
<td>관리자</td>
|
|
<td>프로젝트 전반의 산출물 수정/삭제/관리, 개별 폴더/파일별 권한 제어 및 대량 압축 다운로드 권한.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>Sub-Master</strong></td>
|
|
<td>부관리자</td>
|
|
<td>신규 폴더 생성 및 삭제, 과업개요 정보 수정, 사용자 권한 배정 및 변경 처리.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>Security Worker</strong></td>
|
|
<td>보안참여자</td>
|
|
<td>보안 설정이 적용된 비밀 폴더 및 파일에 대한 읽기/쓰기 권한 부여 및 관리.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>Worker</strong></td>
|
|
<td>일반참여자</td>
|
|
<td>일반 산출물 업로드/다운로드, 개인 메모 작성 및 수정, AI 연동 문서 요약(Gemini) 기능 활용.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>Viewer</strong></td>
|
|
<td>참관자</td>
|
|
<td>스토리지 조회 및 개별 파일 다운로드만 가능 (활동 로그 노출 방지 및 파일 추가/수정 버튼 숨김).</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h2>3. 핵심 모듈 명세 (Core Module Specifications)</h2>
|
|
|
|
<h3>3.1 아카이브 모듈 (Archive Module)</h3>
|
|
<p>프로젝트별 모든 산출물(도면, 공문, 과업 문서 등)을 관리하는 핵심 가상 스토리지 시스템입니다.</p>
|
|
<ul>
|
|
<li><strong>폴더 구조 제어</strong>: 폴더 생성(createFolder), 이름 변경(renameTarget), 다른 폴더로의 계층식 위치 이동(relocateTarget)을 실시간 지원합니다.</li>
|
|
<li><strong>S3 Presigned URL 업로드</strong>: 대용량 업로드 안전성을 위해 서버의 자원을 거치지 않고, 스토리지로부터 Presigned URL을 직접 발급받아 브라우저가 직접 Put Object를 수행합니다.</li>
|
|
<li><strong>백그라운드 ZIP 압축 다운로드</strong>: 대량의 파일이나 폴더 통째 다운로드 시, BullMQ 큐에 작업을 위임하여 서버 부하를 최소화하고 완료 시 다운로드 링크를 팝업으로 제공합니다.</li>
|
|
<li><strong>가상 휴지통</strong>: 삭제된 파일은 즉시 지워지지 않고 휴지통으로 이동하며, 소유자 및 관리자의 승인을 통해 복원하거나 영구 삭제할 수 있습니다.</li>
|
|
<li><strong>뷰어 및 메모 연동</strong>: HWP/DWG 등 다양한 확장자 파일을 PDF로 자동 변환하여 브라우저에서 즉시 열람하는 통합 뷰어를 제공하며, 파일별 텍스트 메모 및 AI 요약 서비스를 연동합니다.</li>
|
|
</ul>
|
|
|
|
<h3>3.2 과업개요 모듈 (Overview Module)</h3>
|
|
<p>계약 사항 및 상세 마일스톤 정보, 지도 개요도를 하나의 통합 카드뷰 대시보드로 제공합니다.</p>
|
|
<ul>
|
|
<li><strong>계약 및 사업 정보</strong>: 계약 금액(외화 금액 포함), Commencement Date, 준공 예정일, 공동 수급사 구성 지분율 및 대표인 정보를 보관합니다.</li>
|
|
<li><strong>개요도 드래그앤드롭 업로드</strong>: 현장 위치도 및 종합 개요도를 별도 파일 선택창 없이 드래그하여 직관적으로 변경 및 등록할 수 있습니다.</li>
|
|
<li><strong>과업 일정 캘린더</strong>: 연월 단위의 마일스톤 일정을 생성/관리하고 주요 진척도를 실시간 모니터링합니다.</li>
|
|
<li><strong>시차 연동 실시간 시계</strong>: 해외 프로젝트의 경우 해당 현장 국가의 표준시 시차 데이터를 바탕으로 실시간 현지 시각을 헤더에 동적으로 출력합니다.</li>
|
|
</ul>
|
|
|
|
<h3>3.3 공문 모듈 (Official Document Module)</h3>
|
|
<p>프로젝트 관계 기관 간 송수신된 공문 번호, 날짜, 수신처 목록과 문서를 체계적으로 매핑 및 보관합니다.</p>
|
|
<ul>
|
|
<li>공문 정보 관리 (발송일, 제목, 수발신처, 문서 번호).</li>
|
|
<li>공문 매핑 첨부파일 연계 보관 및 1-클릭 다운로드 서비스.</li>
|
|
</ul>
|
|
|
|
<h3>3.4 GSIM (GIS 기반 위치 모델 모듈)</h3>
|
|
<p>건설 현장의 실제 위경도 좌표 및 고도(Height) 값과 연계하여 모델 및 데이터를 공간 정보와 매핑합니다.</p>
|
|
<ul>
|
|
<li>2D(OpenLayers) 지도 및 3D(Cesium) 입체 모델 뷰어 탑재.</li>
|
|
<li>줌 레벨에 최적화된 마커 클러스터링(Clustering) 기법으로 대량의 포인트를 성능 저하 없이 표시.</li>
|
|
</ul>
|
|
|
|
<h2>4. 실시간 동기화 및 로그 모듈</h2>
|
|
|
|
<h3>4.1 Websocket 다중 접속자 커서 (Socket.io)</h3>
|
|
<p>프로젝트 협업 효율성을 극대화하기 위해 다중 유저 동시 접속 시 각 유저의 Client 마우스 움직임을 추적하여 화면상에 실시간으로 커서 위치와 소속/이름표를 그려줍니다.</p>
|
|
|
|
<h3>4.2 실시간 로그 및 클릭 통계</h3>
|
|
<ul>
|
|
<li><strong>푸터 실시간 한 줄 로그</strong>: 파일 생성, 삭제, 변환 등 유저가 수행한 핵심 행위가 푸터의 띠 배너 형태로 전 유저에게 실시간 브로드캐스트됩니다.</li>
|
|
<li><strong>클릭 활동 추적</strong>: 향후 화면 분석 및 건설 관리 통계용으로 유저가 누르는 주요 탭, 버튼 등의 액션을 수집하여 <code>tb_click_log</code> 테이블에 실시간으로 기록합니다.</li>
|
|
</ul>
|
|
|
|
<h2>5. 안정성 및 장애 예방 설계 (Reliability & Robustness)</h2>
|
|
|
|
<div class="alert">
|
|
<div class="alert-title">💡 최신 패치 반영 사항 (System Resilience)</div>
|
|
<ul>
|
|
<li><strong>캐시 잠김 해제 미들웨어</strong>: GET 요청 중 정적 자원을 제외한 비동기 동적 API 요청에 대하여 브라우저 304 캐시를 완전히 강제 무효화함으로써, 이전 에러 데이터에 의한 화면 중단 현상을 원천 방지하였습니다.</li>
|
|
<li><strong>서버 Crash 방어 널가드 (Null-Guard)</strong>: DB 조회 쿼리 등에서 일시적인 커넥션 유실이나 스키마 에러가 나더라도 백엔드 프로세스가 통째로 죽지 않도록, 주요 API 핸들러 전반에 예외 위임(try-catch) 및 Null 체크 조건문을 완비하였습니다.</li>
|
|
<li><strong>클라이언트 실시간 디버거</strong>: 사용자 브라우저 상에서 유발된 자바스크립트 크래시 및 미처리 거부(Unhandled Rejection) 오류를 백엔드 콘솔로 자동 수집/출력해 주는 에러 추적 스크립트를 내장하였습니다.</li>
|
|
</ul>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|