graph TD
    Client[Browser / Client Client] <-->|HTTP / HTTPS / Axios| NodeServer[Node.js Express Server]
    Client <-->|Websocket / Socket.io| NodeServer
    NodeServer <-->|SQL Queries| Postgres[(PostgreSQL DB)]
    NodeServer <-->|PubSub / Job Queue| Redis[(Redis Server)]
    NodeServer <-->|Presigned URL / PUT| MinIO[(MinIO / Cloudflare R2)]
    NodeServer -.->|Structured Input/Output| Gemini[Google Gemini API]
    NodeServer -.->|Local Shell Command| CLI[Local CLI Converters / PDF / CAD]

2.2 백그라운드 비동기 태스크 파이프라인

무겁고 연산량이 많은 작업은 사용자 응답 속도를 저해하지 않도록 Redis 기반의 BullMQ 대기열을 통해 비동기로 처리합니다.

sequenceDiagram
    participant Client as 브라우저 (Client)
    participant Server as 백엔드 서버 (Express)
    participant Redis as 레디스 큐 (BullMQ)
    participant Worker as 백그라운드 워커 (Worker)
    participant Storage as 오브젝트 스토리지 (S3/MinIO)

    Client->>Server: 폴더 압축 또는 파일 변환 요청
    Server->>Redis: Job 등록 (convert-pdf, zip-folder)
    Server-->>Client: 202 Accepted 응답 (즉시 반환)
    Redis->>Worker: Job 전달
    Worker->>Storage: 원본 파일 다운로드
    Worker->>Worker: 로컬 변환/압축 CLI 실행 (PDF/ZIP 생성)
    Worker->>Storage: 변환 완료본 업로드 (object_key/preview_key)
    Worker-->>Server: Job 완료 알림
    Server-->>Client: Socket.io 실시간 완료 알림 전송 및 새로고침 트리거

3. 프로젝트 디렉토리 구조 (Project Structure)

본 프로젝트는 Express MVC 아키텍처 패턴을 기반으로 관심사를 분리하고, 어드민 기능과 외부 라이브러리 연동 모듈을 격리하여 관리하고 있습니다.

PM_ver4/
├── app.js                              # Express 서버 설정, 공통 미들웨어 바인딩, 라우터 매핑
├── server.js                           # HTTP 서버 생성, Socket.io 초기화, 서비스 포트 오픈 (기본: 6565)
├── socket.js                           # Socket.io 실시간 접속자 좌표 및 이벤트 공유 핸들러
├── queue.js                            # BullMQ 기반 비동기 작업 대기열 (PDF 변환, AI 요약, ZIP 압축)
├── logger.js                           # Winston 기반 일별 순환 로그(Winston Daily Rotate File) 설정
├── config/                             # 스토리지 및 인프라 커넥터 설정
│   ├── cloudClient.js                  # Cloudflare R2 스토리지 연결 설정 (S3 SDK 기반)
│   ├── onPremiseClient.js              # 온프레미스 MinIO 스토리지 연결 설정
│   └── redis.js                        # ioredis 기반 Redis 커넥터
├── db/                                 # 데이터베이스 액세스 레이어
│   ├── config.js                       # ONPREMISE / CLOUD 환경별 DB 설정 분리
│   ├── pool.js                         # PostgreSQL pg.Pool 인스턴스 export
│   └── index.js                        # DB 연결 테스트 및 풀 유효성 검사
├── routes/                             # HTTP REST API 라우팅 정의
│   ├── mainRouter.js                   # 호스트 도메인 판별 및 첫 페이지 포워딩
│   ├── authRouter.js                   # 세션 및 프로젝트 권한 조회/부여
│   ├── archiveRouter.js                # 파일/폴더 트리, 압축 다운로드, AI 요약
│   ├── officialDocRouter.js            # 수발신 공문 및 Gemini API 연계 API
│   ├── overviewRouter.js               # 대시보드 메타데이터, 캘린더, 시설 규모 API
│   ├── commonRouter.js                 # 환경 설정값 및 공통 메타 조회 API
│   ├── gsimRouter.js                   # GSIM 연동 API
│   └── admin/                          # [격리 배치] 어드민 전용 라우터 (adminRouter.js)
├── controllers/                        # 핵심 비즈니스 로직 (Controller)
│   ├── authController.js               # 사용자 인증 및 미세 권한(lev) 제어
│   ├── archiveController.js            # 파일 이력/삭제/이동 및 BullMQ 연계 제어
│   ├── officialDocController.js        # 공문서 등록 및 Gemini 구조화 파싱 제어
│   ├── overviewController.js           # 종합 개요 수치 및 일정 관리
│   ├── commonController.js             # 공통 설정 조회/수정
│   ├── gsimController.js               # GSIM 지도 관련 동기화
│   └── admin/                          # [격리 배치] 어드민 전용 비즈니스 로직 (adminController.js)
├── oauth/                              # Sentinel SSO 연동 모듈
│   ├── oauthRouter.js                  # OAuth 인증 콜백 API
│   ├── oauthController.js              # 인증 및 Mock 세션 주입 미들웨어
│   └── oauthService.js                 # Sentinel 서버 통신 서비스
├── programs/                           # 백엔드 연동용 로컬 외부 CLI 프로그램 모음
│   ├── encryp.exe                      # 보안 파일 암호화 모듈
│   ├── pdf_thumb.exe                   # PDF 미리보기 이미지 추출기
│   ├── dwgToPdfConverter/              # CAD 도면(.dwg, .dxf) PDF 변환 팩
│   ├── hwpConverter/                   # 한글 문서(.hwp) PDF/HTML 변환 팩
│   └── msofficeConverter/              # MS Office 문서 변환 팩
├── views/                              # 정적 웹 자원 및 클라이언트 템플릿
│   ├── login/                          # 로그인 웹페이지
│   ├── index/                          # 도메인 분기별 첫 마크업 리소스
│   ├── main/                           # 대시보드 및 아카이브 SPA 클라이언트 코드
│   ├── anti_debugging.js               # 소스 스니핑 방지 클라이언트 보안 스크립트
│   ├── anti-debug-sw.js                # 안티 디버깅용 서비스 워커
│   └── admin/                          # [격리 배치] 어드민 웹 대시보드 (html, css, js)
└── package.json                        # 종속성 구성 및 스크립트 정의

4. 관리 데이터 및 시스템 정책 (Managed Data Policy)

4.1 3대 삭제 제한 규칙 (RESTRICT)

시스템 데이터의 정합성과 참조 무결성을 보존하기 위해, 데이터베이스 수준의 물리적 CASCADE 삭제를 금지하고 백엔드 API 단에서 연관 이력을 검사하여 삭제를 제한합니다:

프로젝트 삭제 제한: 아카이브 파일 데이터(tb_data), 공문서 파일(tb_official_doc_file), 공지사항(tb_banner_notice) 중 해당 프로젝트 ID를 참조하는 레코드가 1건이라도 존재할 경우 삭제 요청을 반려(400 Bad Request)합니다.
사용자 삭제 제한: 프로젝트 권한 매핑 테이블(tb_permission)에 해당 유저가 참여 중인 현장 정보가 등록되어 있을 경우 사용자 계정 삭제를 제한합니다.
공통 코드 삭제 제한: 대분류 마스터 코드(code_master) 하위에 소분류 세부 코드(code_detail)가 단 1개라도 생성되어 있을 경우 대분류 코드 삭제를 방지합니다.

4.2 시스템 글로벌 보존 정책 및 자동 삭제 실행 방식

시스템의 디스크 용량 관리 및 보안 가이드라인에 따라 자동 파일 삭제 정책이 탑재되어 작동합니다.

1) 적용 기준 (Criteria)

tb_system_policy 테이블의 GLOBAL_DELETE_POLICY 설정(활성화 여부 is_active, 보존 기한 limit_days, 기준 파일 개수 limit_file_count)을 기준으로 작동합니다.
대상: 아카이브의 3단계 폴더 (is_folder = true 및 data_depth = 3) 중 아래 두 조건을 동시에 만족하는 폴더입니다.
- 해당 폴더 하위(4단계 이하)의 유효한 파일 개수(삭제되지 않은 파일)가 limit_file_count 미만인 경우.
- 폴더의 최종 변경 활동 시각(last_folder_act_date)으로부터 limit_days 일이 경과한 경우.

2) 실행 시점 및 작동 방식 (Execution & Deletion Timing)

정책이 활성화(is_active=true)된 경우, 다음 두 가지 시점에 조건에 부합하는 폴더와 하위 파일들이 자동으로 감지되어 휴지통으로 즉시 이동(Soft-Delete: is_removed = true) 처리됩니다.

실시간 감지 (사용자 접속 시):
- 사용자가 아카이브 화면(메인 트리 화면)에 진입하여 폴더 목록이 렌더링될 때, 화면단(pageRenderer.js)에서 만료가 경과한 3단계 폴더를 즉시 탐색합니다.
- 탐색 성공 시 백엔드 API(removeTarget)를 통해 폴더 및 하위 파일들을 휴지통으로 이동시킵니다. 이 자동 처리 과정은 **참관인(Viewer)이나 작업자(Worker) 등 낮은 권한을 지닌 사용자 세션에서도 정상 수행되도록 예외 처리(Bypass)**되어 있으며, 최신 DB 설정 기준 및 만료 시간을 백엔드에서 2차 검증(Double-Check)하여 안전성을 확보합니다.
정기 배치 스케줄러 (매일 자정 00:00):
- 사용자가 접속하지 않더라도, 백엔드 서버에서 실행 중인 백그라운드 배치 엔진(scheduler.js)이 매일 자정에 한 번씩 데이터베이스를 직접 조회하여 조건에 부합하는 대상을 자동 감지하고 휴지통으로 이동시킵니다.
- 작업 결과(성공 여부, 대상 경로, 적용 기준 등)는 tb_auto_clean_log 테이블에 SYSTEM 작업자 식별자로 기록됩니다.

4.3 시스템 활동 로그(tb_log) 활동유형 정의

시스템 내 모든 파일 관리, 사용자 권한 및 프로젝트 설정 관련 중요 감사 로그는 tb_log 테이블에 기록되며, activity 컬럼에 설정되는 주요 활동유형은 다음과 같습니다.

1) 아카이브 및 파일 관리 관련 활동유형 (File & Archive Operations)

createFolder: 일반 폴더 생성
createFolder-${folderType}: 특정 유형의 폴더 생성 (예: createFolder-officialDoc 등)
uploadData_file / uploadData_folder: 파일 및 폴더 업로드
uploadData_titleImg: 프로젝트 메인 타이틀 이미지 업로드
renameTarget_file / renameTarget_folder: 파일/폴더 이름 변경
editAuthor: 파일의 소유자/작성자 정보 수정
downloadTarget_file / downloadTarget_folder: 파일 및 폴더 다운로드
relocateTarget_file / relocateTarget_folder: 파일 및 폴더 이동 (경로 변경)
removeTarget_file / removeTarget_folder: 파일 및 폴더 임시 삭제 (휴지통 이동)
removeTarget_folder_expired: 보존 정책 만료로 인한 폴더 자동/수동 삭제 (휴지통 이동)
deleteTarget_file / deleteTarget_folder: 파일 및 폴더 영구 삭제 (오브젝트 스토리지 및 DB 실제 삭제)
setDataPermission_file / setDataPermission_folder: 파일/폴더 개별 접근 권한 설정 변경
convertPdf: 캐드/오피스 문서의 PDF 뷰어용 변환 처리 기록
summarizeAI: Google Gemini AI를 활용한 공문서 요약 처리 기록

2) 프로젝트 내 사용자 권한 관련 활동유형 (Project Member Permissions)

addPermission_subMaster / deletePermission_subMaster: 프로젝트 서브 마스터 권한 부여 및 삭제
addPermission_securityWorker / deletePermission_securityWorker: 프로젝트 보안 작업자 권한 부여 및 삭제
addPermission_${lev} / deletePermission_${lev}: 기타 권한 부여 및 삭제 (예: worker, viewer 등)

3) 시스템 및 프로젝트 관리자 활동유형 (System Admin Audit Logs)

createProject / updateProject / deleteProject: 프로젝트 등록, 수정 및 삭제
assignPermission / updatePermission / removePermission: 사용자에게 프로젝트 권한 최초 할당, 수정 및 삭제
createBanner / stopBanner: 시스템 공지사항 배너 등록 및 노출 중단
createUser / updateUser / deleteUser: 시스템 계정(관리자 포함) 생성, 정보 수정(비밀번호 초기화 등) 및 삭제
updateSystemPolicy: 시스템 보관/삭제 및 정기 자동 청소(Auto-Clean) 정책 정보 변경
createCodeMaster / updateCodeMaster / deleteCodeMaster: 공통 대분류 코드 등록, 수정 및 삭제
createCodeDetail / updateCodeDetail / deleteCodeDetail: 공통 소분류 코드 등록, 수정 및 삭제

5. 코드 기준 및 개발 표준 (Code Standards)

프로젝트 코드의 가독성과 확장성을 일관되게 유지하기 위해 다음 기준을 반드시 준수해야 합니다.

엄격한 모듈 격리 배치:
- 새로 추가되는 관리자(Admin) 관련 기능은 기존 어플리케이션 소스 영역에 결합하지 않고, routes/admin/, controllers/admin/, views/admin/ 하위에 완전히 격리 배치하여 개발합니다.
비동기 예외 세이프가드 (Crash Safeguard):
- 비정상적인 DB 쿼리 에러나 undefined 참조 오류가 발생했을 때 Node.js 프로세스가 다운되는 것을 막기 위해 모든 컨트롤러 함수 및 미들웨어의 내부 로직은 try-catch 블록으로 래핑하고 적절한 에러 로깅을 수행해야 합니다.
데이터베이스 연결 풀(Pool) 관리:
- 데이터베이스의 불필요한 커넥션 점유를 막고 자원을 효율화하기 위해 db/config.js에는 idleTimeoutMillis: 5000 및 connectionTimeoutMillis: 5000으로 타이트한 타임아웃 규칙이 적용되어 있습니다. 쿼리 실행 후에는 반드시 client.release()를 호출하여 커넥션을 풀로 즉시 반환하십시오.
원격 오류 수집 디버거:
- 클라이언트 측 브라우저에서 스크립트 실행 오류 발생 시 /api/common/log-client-error 엔드포인트를 통해 에러 스택을 실시간 수집하고 있으므로, 배포 전 개발 모드 상태에서 콘솔의 🚨 [CLIENT ERROR] 모니터링을 상시 수행하십시오.

6. 사용 권한 체계 (User Permission System)

유저의 세션 그룹 권한과 개별 프로젝트별 참여 권한 등급(lev)은 다음과 같이 비트/상수 형식으로 구분 및 통제됩니다.

권한 레벨 (`lev`)	그룹 / 명칭	시스템 상의 주요 권한 및 설명
255	Owner / Super	프로젝트의 소유주 및 시스템 최고 관리자. 프로젝트 삭제, 유저 전체 권한 제어, 어드민 모달 접근 및 비활성 현장 강제 접근 우회 가능.
191	Master	프로젝트 실질 관리자. 현장 내 모든 폴더/파일 관리, 권한 설정 변경, Zip 일괄 다운로드 가능.
127	Sub-Master	부관리자. 폴더 생성/삭제, 과업개요 정보 수정, 하위 사용자 권한 배정 및 해제 가능.
15	Security Worker	보안 담당 참여자. 보안으로 지정된 폴더 및 파일에 대한 읽기/쓰기 권한 접근 가능.
7	Worker	일반 협업 실무자. 일반 폴더에 대한 파일 업로드/다운로드, 메모 생성 및 Gemini AI 문서 요약 기능 사용 가능.
1	Viewer	단순 모니터링 참관자. 파일의 조회가 가능하지만, 데이터 수정/업로드/삭제 버튼 등 일체의 제어용 DOM 요소가 화면에서 자동 제거됩니다.

6.1 폴더별 접근 권한 설정 (Folder-Level Permissions)

최상단 1~3단계 폴더(data_depth <= 3)에 대해 프로젝트 참여자의 접근 등급을 개별 설정하여 미세 제어할 수 있습니다. 4단계 이하 하위 폴더와 파일은 상위 3단계 부모 폴더의 권한 설정을 실시간으로 동적 자동 상속받습니다.

1) 폴더별 사용자 권한 등급

접근 차단 (None - 0): 해당 폴더 및 하위 파일 전체에 대해 조회 및 접근이 차단됩니다. (화면에 노출되지 않음)
참관자 (Viewer - 1): 해당 폴더 및 하위 파일에 대해 읽기(조회/다운로드)만 가능합니다.
일반참여자 (Worker - 7): 해당 폴더 및 하위 파일에 대해 업로드, 수정, 삭제가 가능합니다.
부관리자 (Sub-Master - 191): 폴더 권한 설정을 변경할 수 있습니다.

2) 권한 동적 상속 및 탐색 규칙

1~3단계 폴더는 tb_folder_permission 테이블에 개별 저장됩니다.
4단계 이하(data_depth >= 4) 데이터는 자체 권한값을 저장하지 않고, 쿼리 실행 시 path1, path2, path3 경로와 조인하여 상위 3단계 부모 폴더의 권한을 동적으로 탐색하여 상속받습니다.

7. 핵심 기능 및 주요 시나리오 (Core Scenarios)

7.1 Presigned URL 기반 대용량 파일 업로드

도면 등 대용량 파일 전송 시 백엔드 WAS의 입출력 부하 및 메모리 병목 현상을 방지하기 위해 Presigned URL 통신 기법을 도입하였습니다.

URL 요청: 브라우저에서 파일을 선택하면 백엔드 API(GET /api/archive/presigned-url)에 업로드 대상 정보를 전송합니다.
보안 서명 발급: 서버는 Cloudflare R2 / MinIO SDK를 사용하여 특정 버킷과 키에 대한 보안 업로드 서명이 담긴 임시 URL을 클라이언트에 발급합니다.
직접 업로드: 브라우저가 Axios를 이용해 스토리지(MinIO/R2) 엔드포인트로 파일을 직접 PUT 전송하여 파일 업로드를 완료합니다.
메타 적재: 업로드 성공 후 백엔드 서버에 성공 패킷을 전송하여 tb_data 테이블에 최종 트리 정보를 등록합니다.

7.2 오피스 및 CAD 도면 자동 PDF 변환 뷰어

다양한 산출물 포맷(.hwp, .dwg, .docx 등)을 웹상에서 별도 프로그램 설치 없이 즉시 조회할 수 있는 통합 문서 뷰어 파이프라인을 지원합니다.

변환 작업 큐잉: 파일 업로드 감지 시 백엔드 큐(convert-pdf)에 변환 태스크가 추가됩니다.
백그라운드 CLI 구동: 비동기 워커가 programs/ 내의 dwgToPdfConverter, hwpConverter 등 변환 CLI 프로세스를 작동시켜 PDF 표준 문서로 자동 렌더링을 진행합니다.
캐싱 및 썸네일: 변환된 PDF는 스토리지 내 preview_key 경로에 적재되고, 동시에 1페이지를 썸네일 이미지(thumbnail_key)로 추출하여 그리드 뷰에 제공합니다.

7.3 Google Gemini AI 기반 공문서 지능형 파싱 (Structured Output)

수발신 공문 처리 시 요약 및 정보 입력을 자동화하기 위해 AI 구조화 데이터 추출 기능이 탑재되어 있습니다.

멀티 파트 수집: 업로드된 문서 파일(input_file), 추출용 지시 가이드라인 프롬프트(prompt_file), 출력 형태를 고정한 JSON 스키마 규격(schema_file)을 수집합니다.
Gemini API 연동: Gemini 2.5 Flash API에 수집된 파일 세트를 전달하고 responseSchema를 강제 지정합니다.
구조화 정보 저장: Gemini가 반환한 완벽한 JSON 포맷 데이터(수/발신처, 공문 번호, 개조식 제목 요약, 관련 문서 ID)를 검증 후 tb_official_doc_file 컬럼에 자동 매핑하여 적재합니다.

8. 실 가동 환경 세팅 및 프로덕션 설정 (Production Setup)

실서버(운영 및 스테이징) 배포 시 시스템이 안정적으로 구동되기 위해 구성되어야 하는 인프라 설정 스펙입니다.

8.1 서버 운영체제(OS) 사양 필수 조치

권장 OS: Windows Server 2019 / 2022 이상
필수 이유: programs/ 폴더 내부에서 동작하는 한글 문서 변환(hwpConverter), CAD 도면 변환(dwgToPdfConverter), 문서 미리보기 이미지 추출(pdf_thumb.exe) 등 핵심 문서 변환 엔진들이 Windows Native 32/64비트 실행 파일(.exe CLI) 및 동적 연결 라이브러리(DLL)에 전적으로 의존하고 있습니다. 따라서 실서버 환경은 반드시 Windows Server OS 상에서 Node.js 프로세스가 직접 실행되어야 합니다.

8.2 프로덕션 환경변수(`.env`) 구성 표준

가동 환경에 맞춰 .env 내의 파라미터를 다음과 같이 엄격하게 구분하여 배포합니다.

# 1. 런타임 최적화 모드 및 고유 식별자 설정
NODE_ENV=production
SERVICE_NAME=PM_PRODUCTION               # 다중 도메인 매핑 시 호스트 판별 기준자
DEPLOYMENT_TYPE=CLOUD                    # CLOUD(R2 스토리지) 또는 ONPREMISE(MinIO) 분기

# 2. 포트 및 리스닝 IP
LOCAL_IP=0.0.0.0                         # 외부 트래픽 수신 허용
LOCAL_PORT=6565

# 3. 운영 PostgreSQL 데이터베이스 설정
ONPREMISE_POSTGRES_HOST=10.0.10.5        # 격리된 내부망 DB 서버 IP
ONPREMISE_POSTGRES_PORT=5432
ONPREMISE_POSTGRES_DATABASE=pm_prod_db
ONPREMISE_POSTGRES_USER=pm_db_admin
ONPREMISE_POSTGRES_PASSWORD=secure_prod_password

# 4. Redis 고가용성 세션/큐 스토어
REDIS_HOST=10.0.10.6
REDIS_PORT=6379
REDIS_PASSWORD=secure_redis_password

# 5. Cloudflare R2 스토리지 자격 증명 (S3 호환 엔드포인트)
MINIO_ENDPOINT=https://your-cf-account-id.r2.cloudflarestorage.com
MINIO_ACCESSKEYID=your_r2_access_key
MINIO_SECRETACCESSKEY=your_r2_secret_key

8.3 Nginx 역방향 프록시(Reverse Proxy) 및 SSL 종단 구성

외부망 포트 80(HTTP) 및 443(HTTPS) 서비스 노출을 위해 웹 서버 전면에 Nginx를 역방향 프록시로 배치하고 SSL 인증서 처리를 종단합니다.

Nginx 필수 웹소켓 프록시 설정: 실시간 마우스 커서 트래킹(socket.io)이 끊기지 않도록 Upgrade 및 Connection 헤더를 백엔드로 넘겨주어야 합니다.

server {
    listen 443 ssl;
    server_name bim.yourdomain.co.kr;

    ssl_certificate c:/nginx/conf/ssl/yourdomain.crt;
    ssl_certificate_key c:/nginx/conf/ssl/yourdomain.key;

    location / {
        proxy_pass http://127.0.0.1:6565;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_cache_bypass $http_upgrade;
    }
}

8.4 PM2 프로세스 매니저 기반의 무중단 기동

Windows 환경에서 백엔드 Node.js 프로세스가 장애 시 자동 재기동되고 CPU 멀티 코어를 모두 활용하도록 PM2 클러스터 모드를 연동합니다.

PM2를 윈도우 백그라운드 서비스로 등록합니다 (pm2-windows-service 모듈 연동).
아래 명령어를 통해 멀티 코어 클러스터 인스턴스를 무중단 기동합니다:
```
pm2 start server.js -i max --name "pm-server-prod"
```

9. 개발자 준비 사항 (Developer Prerequisites)

시스템을 인계받거나 신규 배포 프로세스를 주도하는 개발자가 가동 전에 반드시 숙지하고 확보해야 하는 자격 증명 및 준비 사항입니다.

OAuth (Sentinel SSO) 연동 정보 확보:
- 실 서버 배포 시 백엔드가 사내 SSO 인증 공급자와 토큰 정보를 통신할 수 있도록 사내 네트워크 방화벽 허용 및 SSO 클라이언트 키(CLIENT_ID, CLIENT_SECRET)를 OAuth 관리 담당 부서로부터 발급받아야 합니다.
Google Gemini API 실서버용 인증 키 발급:
- 문서 자동 요약 및 인텔리전트 공문 파싱 한도 초과 오류(Rate Limit) 방지를 위해 결제가 연동된 Google AI Studio의 프로덕션 전용 API Key를 발급받아 .env에 설정해야 합니다.
안티 디버깅 코드 원복 검증:
- 개발 모드 분석을 위해 프론트엔드의 anti_debugging.js 로드 미들웨어나 임포트 구문을 변경/주석 처리했다면, 배포용 빌드 완료 전 반드시 원복하여 운영 환경에서 스니핑 보안이 즉각 작동되도록 조치해야 합니다.
R2 / MinIO Bucket 정책 제어 권한:
- 파일이 무단으로 유출되는 것을 막기 위해 스토리지 버킷의 public 접근 권한을 'Private'으로 격리하고, 오직 백엔드 서버만이 Presigned URL을 발행하고 파일을 지울 수 있는 S3 IAM 정책을 설계 및 연결해야 합니다.

10. 유지보수 가이드 (Maintenance Guide)

실서버 구동 후 발생할 수 있는 이상 현상 조치 및 일상적 점검 가이드라인입니다.

10.1 BullMQ 비동기 작업 큐 모니터링 (Bull Board)

PDF 변환 파일의 락 현상이나 MinIO 스토리지 전송 지연 등으로 비동기 변환/압축 작업이 실패할 경우 큐가 정체될 수 있습니다.

모니터링 대시보드 접속: http://[운영서버IP]:6565/admin/queues
조치 요령: 어드민 세션(USER_GROUP_super)으로 접속 후 Bull Board 웹 UI 상에서 실패한 작업(Failed)을 검사하고, 오류 원인(Stack Trace) 분석 후 Retry 버튼을 클릭하여 작업을 재실행하거나 쓰레기 작업을 Clean 합니다.

10.2 Winston 일별 순환 로그 및 예외 감시

logger.js에 설정된 Winston Daily Rotate File 라이브러리가 로그를 일별 분할하여 백업합니다.

로그 디렉토리: trunk/PM_ver4/logs/
주요 점검 파일:
- yyyy-MM-dd.error.log (서버 비즈니스 예외)
- yyyy-MM-dd.exception.log (예기치 못한 Uncaught Exception)
조치: 배치 장애나 DB 연결 이슈가 발생하는지 최소 주 1회 로그 상태를 확인하고 디스크가 고갈되지 않도록 보존 기한을 관리합니다.

10.3 DB 커넥션 고갈 방지 및 모니터링

다중 접속 상황에서 웹서버 연결이 지연되고 ETIMEDOUT 오류가 떨어지는 경우 DB 풀 고갈을 의심해야 합니다.

원인: client.release() 구문이 누락되거나 오류 발생 후 커넥션이 회수되지 않은 경우.
대응: pool.js 설정 파일의 max: 20 값을 모니터링 툴(Grafana / pg_activity)의 액티브 쿼리 수치를 기반으로 트래픽에 대응하여 점진적으로 상향 조치합니다.

10.4 자동 보존 정리 배치 실행 로그 감시

자정마다 돌며 스토리지를 정리해 주는 정리 배치가 누출 없이 작동 중인지 tb_auto_clean_log 테이블을 상시 쿼리하여 점검합니다.

SELECT clean_date, clean_path, criteria_info, result_status 
FROM ver4.tb_auto_clean_log 
ORDER BY clean_date DESC 
LIMIT 10;

result_status가 FAIL로 찍히는 경우, 백엔드 서버에서 R2/MinIO로의 S3 API 네트워크 접속 유실이 일어났거나 IAM Secret Key 만료 문제가 발생한 것이므로 환경변수 자격 증명을 갱신해 주어야 합니다.

README.md

PROJECT MASTER ver 4.0 - 통합 프로젝트 관리 시스템 (PM)

1. 시스템 개요 (System Overview)

2. 전체 구조도 및 아키텍처 (Architecture & Diagrams)

2.1 시스템 데이터 흐름도