Admin Dashboard Implementation Guide

관리자 화면(Admin Panel) 마이그레이션 및 데이터베이스 연동 설계서

1. 전체 시스템 아키텍처 및 구현 계획

본 설계서는 관리자화면_통합대시보드_UI제안.html 정적 파일의 사용자 동작 시뮬레이션을 프로덕션 급 서버 인프라에 안착하기 위한 설계 명세입니다. 시스템 환경은 Node.js / PostgreSQL / MinIO S3 및 Redis Queue 아키텍처를 준수합니다.

ℹ️ 백엔드 연동 방식

본 시스템은 관리 업무의 연속성 확보 및 동시성 처리를 위해 REST API 채널 외에도 Socket.io 서버 채널을 동시에 가용하여 실시간 웹소켓 통신을 처리하도록 구성됩니다.

구현 단계별 개발 로드맵

[1단계] 데이터베이스 스키마 확장 및 마이그레이션

공통 코드 분류 및 세부 값 제어를 위한 code_master 및 code_detail 테이블 신설.
기존 테이블 활용 (컬럼 추가 없음): 기존에 존재하는 프로젝트 테이블(tb_project)의 category 컬럼과 사용자 테이블(tb_user)의 "group" 컬럼을 code_detail.base_code 외래키 참조 구조로 그대로 연동하여 불필요한 테이블 팽창 및 컬럼 추가를 차단합니다.
시스템 공통 자동 보존 및 삭제 임계치를 독립적으로 제어하기 위한 tb_system_policy (시스템 공통 정책 테이블) 신설.
실시간 배너 공지 이력 보관을 위한 tb_banner_notice 및 정기 자동삭제 실행 결과를 기록하기 위한 tb_auto_clean_log 신설.

[2단계] 백엔드 RESTful API 및 WebSocket 핸들러 개발

REST API: 각 기능 및 공통 코드 데이터의 CRUD API Endpoint 구축 (Express Controller 연동).
WebSocket: socket.js에 접속한 클라이언트 세션을 users 메모리 맵에 보관 및 관리자가 강제퇴장(forcedLogout) 이벤트를 호출하면 해당 클라이언트 소켓의 접속을 끊고 세션을 제거하도록 구현.

[3단계] 프론트엔드 어드민 대시보드 UI 연동

프로토타입 디자인 컨셉(Pretendard 서체, Forest Green 테마 색상)을 CSS 변수로 그대로 반영.
모달 다이얼로그와 탭 렌더링에 실시간 API 데이터 통신 로직 바인딩.

2. 데이터베이스 스키마 설계 (ERD)

기존에 이미 보유한 tb_project.category 및 tb_user."group" 구조를 활용한 관계 정의는 다음과 같습니다.

classDiagram class code_master { +main_code : VARCHAR(30) PK +main_code_nm : VARCHAR(100) +use_yn : CHAR(1) +rmk : VARCHAR(255) } class code_detail { +main_code : VARCHAR(30) PK/FK +sub_code : VARCHAR(30) PK +base_code : VARCHAR(61) UNIQUE +code_nm : VARCHAR(100) +sort_ord : INT +use_yn : CHAR(1) +rmk : VARCHAR(255) } class tb_project { +project_id : VARCHAR(50) PK +project_nm : VARCHAR(100) +category : VARCHAR(50) FK +limit_storage : INT +is_active : BOOLEAN } class tb_system_policy { +policy_id : INT PK +policy_key : VARCHAR(50) UNIQUE +limit_file_count : INT +limit_days : INT +is_active : BOOLEAN +upd_date : TIMESTAMP } class tb_user { +user_id : VARCHAR(50) PK +user_nm : VARCHAR(50) +user_pw : VARCHAR(255) +company : VARCHAR(50) +dept : VARCHAR(50) +position : VARCHAR(50) +group : VARCHAR(50) FK +is_resigned : BOOLEAN } class tb_permission { +project_id : VARCHAR(50) PK/FK +user_id : VARCHAR(50) PK/FK +lev : INT } class tb_banner_notice { +banner_id : SERIAL PK +project_id : VARCHAR(50) FK +reg_date : DATE +start_date : DATE +end_date : DATE +notice_text : TEXT +status_code : VARCHAR(61) FK } class tb_log { +log_id : SERIAL PK +project_id : VARCHAR(50) +activity : VARCHAR(100) +user_id : VARCHAR(50) +user_ip : VARCHAR(50) +log_date : TIMESTAMP +path_arr : TEXT[] } code_master "1" --> "0..*" code_detail code_detail "1" --> "0..*" tb_project : "category 참조" code_detail "1" --> "0..*" tb_user : "group 참조" code_detail "1" --> "0..*" tb_banner_notice : "status_code 참조" tb_project "1" --> "0..*" tb_permission tb_user "1" --> "0..*" tb_permission tb_project "1" --> "0..*" tb_banner_notice

3. 화면별 연동 테이블 및 데이터베이스 상세 매핑

📊 화면 1: 종합 용량 및 접속자 현황 (Dashboard)

주요 데이터 흐름 및 활용 테이블:

전체 사용 용량 KPI & 현장별 게이지바: tb_project 테이블의 한도 용량(storage_byte)과 tb_data 테이블의 실 누적 용량(data_size) 합산 결과 및 파일 건수를 COUNT()하여 렌더링.
실시간 접속자 세션 목록: 데이터베이스를 경유하지 않고 Node.js 메인 프로세스(socket.js)의 메모리 세션 해시맵에서 직접 연결 상태(ID, IP, 위치 경로)를 추출.
대기 중인 압축작업: Redis(BullMQ Queue) 대기열 API를 조회하여 보류 중인 백그라운드 압축 다운로드 개수 파악.

🏗️ 화면 2: 프로젝트 관리 (Project Management)

주요 데이터 흐름 및 활용 테이블:

좌측 프로젝트 그리드: tb_project 테이블 전체 데이터와 code_detail의 카테고리 코드 한글 명칭(TDC, GPD 등)을 tb_project.category 외래키 관계를 조인하여 렌더링.
우측 참여 권한 사용자 목록: tb_permission $\bowtie$ tb_user 조인을 통해 해당 현장에 기속된 사용자 리스트업 및 등급 인라인 셀렉트 업데이트.
사용자 배정 추가 모달: tb_user의 전체 사용자 데이터와 현재 프로젝트에 속해 있지 않은 유저 차집합 연산으로 가용 유저 목록 구성.

📢 화면 3: 실시간 배너 공지 (Banner Notice)

주요 데이터 흐름 및 활용 테이블:

공지사항 이력 및 등록 폼: tb_banner_notice 테이블 CRUD 매핑.
송출 상태 계산: 오늘 날짜 기준 start_date와 end_date 조건을 체크하여 공통코드 매핑 상태(NOTICE_STATUS_active, NOTICE_STATUS_scheduled, NOTICE_STATUS_expired)를 동적 할당.
검색 필터: 송출상태 및 등록일 범위(From ~ To) 기준 WHERE status_code = ? AND reg_date BETWEEN ? AND ? 쿼리 연동.

👥 화면 4: 사용자 관리 (User Management)

주요 데이터 흐름 및 활용 테이블:

좌측 계정 목록: tb_user 테이블 및 code_detail 권한그룹(기존 "group" 컬럼 재사용) 매핑 렌더링.
우측 참여 프로젝트 목록: tb_permission $\bowtie$ tb_project 조인을 활용하여 선택 유저가 소속된 모든 프로젝트 ID 및 현장명 출력.

🔎 화면 5: 감사 로그 조회 (Audit Logs)

주요 데이터 흐름 및 활용 테이블:

시스템 감사 이력 목록: 파일 삭제/이동/다운로드 이벤트를 적재하는 tb_log 테이블을 필터 검색 쿼리(사용자 ID, 액션타입)와 연동하여 리스트 렌더링.

⚙️ 화면 6: 자동 보존 및 파일 삭제 정책 설정 (Delete Policy)

주요 데이터 흐름 및 활용 테이블:

시스템 공통 자동 삭제 정책 설정 폼: 프로젝트 단위 설정을 탈피하고, 신설된 tb_system_policy의 단일 글로벌 레코드를 제어.
자동 삭제 정기 실행 이력: 정기 스케줄러 배치 구동 시의 로그 기록을 tb_auto_clean_log에서 리스트업. 설정값 저장 및 기록 적재 시 프로젝트 ID 대신 'SYSTEM' 기록 식별자를 사용.

🔑 화면 7: 공통 코드 관리 (Common Code Management)

주요 데이터 흐름 및 활용 테이블:

상단 마스터 대분류: code_master 테이블 CRUD.
하단 상세 소분류: code_detail 테이블 CRUD.
- 대분류 선택이 없을 시 소분류 등록 폼 진입 차단 유효성 제어.
- 소분류의 base_code 컬럼은 main_code || '_' || sub_code 조합으로 자동 동기화.
- 대분류 삭제 시 외래키 ON DELETE CASCADE 명세를 통하여 소분류 레코드가 데이터베이스에서 연쇄적으로 자동 청소되도록 설정.

4. 핵심 백엔드 CRUD API Endpoint 설계안

프론트엔드-백엔드 간 통신을 위해 구성되어야 할 RESTful API 리스트입니다.

1. 프로젝트 관리 API (`/api/admin/projects`)

메소드	엔드포인트	설명
GET	/	전체 프로젝트 및 카테고리 정보 조회
POST	/	신규 프로젝트 등록
PUT	/:id	특정 프로젝트 내용(카테고리 category 값, 용량제한, 활성화) 갱신
DELETE	/:id	프로젝트 영구 삭제 (참여 권한 및 메타데이터 자동 CASCADE)

2. 프로젝트 권한 배정 API (`/api/admin/permissions`)

메소드	엔드포인트	설명
GET	/project/:projectId	특정 현장에 참여 중인 유저 목록 조회
POST	/assign	현장에 특정 사용자 권한 신규 부여 (다중 배정)
PUT	/update	배정 유저의 권한 등급(lev) 수정
DELETE	/remove	현장 참여 권한 배정 제외 (매핑 행 삭제)

3. 실시간 배너 공지 API (`/api/admin/banners`)

메소드	엔드포인트	설명
GET	/	배너 송출 이력 조회 (상태, 날짜검색 필터 지원)
POST	/	신규 배너 공지 작성 및 등록
PUT	/stop/:id	공지 수동 송출 중지 (상태를 expired로 강제 업데이트)

4. 사용자 관리 API (`/api/admin/users`)

메소드	엔드포인트	설명
GET	/	전체 계정 정보 및 권한그룹 조회
GET	/:id/permissions	해당 유저가 참여 권한을 지닌 프로젝트 목록 조회
POST	/	신규 사용자 계정 등록 (패스워드 bcrypt 암호화)
PUT	/:id	사용자 정보(권한 그룹 group 포함) 및 재직 상태 갱신
DELETE	/:id	사용자 계정 삭제 (권한 정보 및 설정 연쇄 삭제)

5. 공통 코드 관리 API (`/api/admin/common-codes`)

메소드	엔드포인트	설명
GET	/masters	대분류 마스터 코드 목록 조회
POST	/masters	신규 대분류 등록
PUT	/masters/:code	대분류 수정
DELETE	/masters/:code	대분류 삭제 (하위 소분류 자동 연쇄 삭제)
GET	/details/:mainCode	선택된 대분류에 해당하는 소분류 정렬 조회
POST	/details	신규 소분류 등록 (base_code 자동 연산 생성)
PUT	/details/:mainCode/:subCode	소분류 수정 (명칭, 정렬순서, 사용여부)
DELETE	/details/:mainCode/:subCode	소분류 삭제

6. 시스템 공통 보존 정책 API (`/api/admin/system-policy`)

메소드	엔드포인트	설명
GET	/	시스템 글로벌 보존 정책 조회
POST	/update	글로벌 보존 정책 값 갱신 및 저장

1. 전체 시스템 아키텍처 및 구현 계획

구현 단계별 개발 로드맵

[1단계] 데이터베이스 스키마 확장 및 마이그레이션

[2단계] 백엔드 RESTful API 및 WebSocket 핸들러 개발

[3단계] 프론트엔드 어드민 대시보드 UI 연동

2. 데이터베이스 스키마 설계 (ERD)

3. 화면별 연동 테이블 및 데이터베이스 상세 매핑

📊 화면 1: 종합 용량 및 접속자 현황 (Dashboard)

🏗️ 화면 2: 프로젝트 관리 (Project Management)

📢 화면 3: 실시간 배너 공지 (Banner Notice)

👥 화면 4: 사용자 관리 (User Management)

🔎 화면 5: 감사 로그 조회 (Audit Logs)

⚙️ 화면 6: 자동 보존 및 파일 삭제 정책 설정 (Delete Policy)

🔑 화면 7: 공통 코드 관리 (Common Code Management)

4. 핵심 백엔드 CRUD API Endpoint 설계안

1. 프로젝트 관리 API (/api/admin/projects)

2. 프로젝트 권한 배정 API (/api/admin/permissions)

3. 실시간 배너 공지 API (/api/admin/banners)

4. 사용자 관리 API (/api/admin/users)

5. 공통 코드 관리 API (/api/admin/common-codes)

6. 시스템 공통 보존 정책 API (/api/admin/system-policy)

1. 프로젝트 관리 API (`/api/admin/projects`)

2. 프로젝트 권한 배정 API (`/api/admin/permissions`)

3. 실시간 배너 공지 API (`/api/admin/banners`)

4. 사용자 관리 API (`/api/admin/users`)

5. 공통 코드 관리 API (`/api/admin/common-codes`)

6. 시스템 공통 보존 정책 API (`/api/admin/system-policy`)