통합 관리자 대시보드 구현 계획 및 테이블 명세 가이드
관리자 화면(Admin Panel) 마이그레이션 및 데이터베이스 연동 설계서
1. 전체 시스템 아키텍처 및 구현 계획
본 설계서는 관리자화면_통합대시보드_UI제안.html 정적 파일의 사용자 동작 시뮬레이션을 프로덕션 급 서버 인프라에 안착하기 위한 설계 명세입니다. 시스템 환경은 Node.js / PostgreSQL / MinIO S3 및 Redis Queue 아키텍처를 준수합니다.
graph TD
Client[Browser Admin Page] -->|REST API Requests| Backend[Express.js Web Server]
Client -->|WebSocket Event Channel| SocketServer[Socket.io Server]
Backend -->|SQL Query / PG client| DB[(PostgreSQL Database)]
Backend -->|Enqueue / Monitor| Redis[(Redis / BullMQ Queue)]
SocketServer -->|Active Session Cache| Memory[Node.js Process Memory]
ℹ️ 백엔드 연동 방식
본 시스템은 관리 업무의 연속성 확보 및 동시성 처리를 위해 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의 전체 사용자 데이터와 현재 프로젝트에 속해 있지 않은 유저 차집합 연산으로 가용 유저 목록 구성.
👥 화면 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 | 글로벌 보존 정책 값 갱신 및 저장 |