Files

2026-06-12 17:14:03 +09:00

12 KiB

Raw Permalink Blame History

PM_ver4 통합 관리자 화면 실물 연동 구현 계획서

본 계획서는 [통합관리자대시보드_화면설계서.html](file:///d:/40. 개발소스/04. PM/pm_ver4/trunk/PM_ver4/통합관리자대시보드_화면설계서.html) 및 [통합관리자대시보드_구현가이드.html](file:///d:/40. 개발소스/04. PM/pm_ver4/trunk/PM_ver4/통합관리자대시보드_구현가이드.html)의 세부 명세와 스펙을 전적으로 분석하고 참고하여, 실제 가동 가능한 백엔드 REST API, 데이터베이스 스키마 확장, 실시간 웹소켓 세션 제어, 배치 스케줄러, 프론트엔드 비동기 통신을 통합적으로 구축하기 위해 수립한 최종 상세 구현 계획서입니다.

1. 구현 전제 및 핵심 비즈니스 규칙

① 소스코드 격리 배치 정책 (기존 소스와의 분리)

기존 어플리케이션 소스코드 파일들과 물리적으로 완전히 격리하여 독립적인 유지보수와 안정적인 버전 관리를 보장하기 위해 다음과 같이 전용 하위 디렉토리를 신설하여 작업합니다.

백엔드 라우터: routes/admin/ 폴더 신설
- adminRouter.js를 배치하여 어드민 API 엔드포인트 일괄 관리.
백엔드 컨트롤러: controllers/admin/ 폴더 신설
- adminController.js를 배치하여 어드민 비즈니스 로직 일괄 관리.
프론트엔드 뷰 & 정적 리소스: views/admin/ 폴더 신설
- dashboard.html (마크업), dashboard.js (Fetch 및 인터랙션 스크립트), dashboard.css (테마 스타일시트) 배치.

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

기속 데이터의 안전한 보호를 위해, 데이터베이스의 CASCADE 물리적 삭제를 지양하고 백엔드 API에서 COUNT 검증 후 400 Bad Request와 상세 경고 메시지를 응답하는 로직을 일괄 적용합니다.

프로젝트 관리: 관련 테이블(tb_data, tb_official_doc_file, tb_banner_notice 등)에 해당 현장 ID 사용 이력이 1건이라도 존재할 시 프로젝트 삭제 차단.
사용자 관리: 권한 테이블(tb_permission)에 해당 유저의 프로젝트 참여/배정 정보가 존재할 시 계정 삭제 차단.
공통 코드 관리: 대분류 코드(code_master) 하위에 소분류 세부 코드(code_detail)가 단 1개라도 등록되어 있을 시 대분류 삭제 차단.

③ 데이터 모델 최적화 (기존 컬럼의 공통코드 외래키 매핑)

불필요한 테이블 팽창 및 신규 컬럼을 방지하기 위해, 기존 tb_project.category 및 tb_user."group" 컬럼을 신설할 공통코드 상세 키(code_detail.base_code)의 참조 매핑 대상으로 그대로 재사용합니다.

④ 접근 제어 보안 통제

일반 유저가 관리자 라우트 및 REST API 엔드포인트에 직접 우회 접근하는 것을 차단하기 위해 로그인 세션의 권한 그룹을 검증하는 isAdmin 보안 미들웨어를 신설하여 라우터 전면에 주입합니다.
관리자 권한 식별 그룹 코드는 공통코드 소분류인 USER_GROUP_super (수퍼관리자)로 검증합니다.

2. 확장 데이터 스키마 상세 (PostgreSQL DDL 요약)

다음 5개 신규 물리 테이블 스키마를 기존 데이터베이스에 DDL 패치로 적재합니다.

-- 1. 공통 코드 대분류 마스터
CREATE TABLE code_master (
    main_code VARCHAR(30) PRIMARY KEY,
    main_code_nm VARCHAR(100) NOT NULL,
    use_yn CHAR(1) DEFAULT 'Y',
    rmk VARCHAR(255)
);

-- 2. 공통 코드 소분류 상세
CREATE TABLE code_detail (
    main_code VARCHAR(30) REFERENCES code_master(main_code) ON DELETE CASCADE,
    sub_code VARCHAR(30) NOT NULL,
    base_code VARCHAR(61) UNIQUE NOT NULL, -- main_code || '_' || sub_code 형태 자동 완성
    code_nm VARCHAR(100) NOT NULL,
    sort_ord INT DEFAULT 1,
    use_yn CHAR(1) DEFAULT 'Y',
    rmk VARCHAR(255),
    PRIMARY KEY (main_code, sub_code)
);

-- 3. 시스템 글로벌 보관 및 자동 삭제 정책 설정
CREATE TABLE tb_system_policy (
    policy_id SERIAL PRIMARY KEY,
    policy_key VARCHAR(50) UNIQUE NOT NULL,
    limit_file_count INT DEFAULT 100,
    limit_days INT DEFAULT 30,
    is_active BOOLEAN DEFAULT FALSE,
    upd_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 4. 실시간 배너 공지 이력 관리
CREATE TABLE tb_banner_notice (
    banner_id SERIAL PRIMARY KEY,
    project_id VARCHAR(50) REFERENCES tb_project(project_id),
    reg_date DATE DEFAULT CURRENT_DATE,
    start_date DATE NOT NULL,
    end_date DATE NOT NULL,
    notice_text TEXT NOT NULL,
    status_code VARCHAR(61) REFERENCES code_detail(base_code)
);

-- 5. 정기 자동 청소 배치 실행 이력 로그
CREATE TABLE tb_auto_clean_log (
    log_id SERIAL PRIMARY KEY,
    clean_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    project_id VARCHAR(50) DEFAULT 'SYSTEM',
    clean_path TEXT NOT NULL,
    criteria_info VARCHAR(100),
    result_status VARCHAR(20) NOT NULL
);

3. 핵심 백엔드 REST API 명세 (`/api/admin`)

① 프로젝트 및 권한 배정 API

GET /api/admin/projects : 전체 프로젝트 목록 및 공통코드 기반 카테고리 정보 조회.
POST /api/admin/projects : 신규 프로젝트 등록.
PUT /api/admin/projects/:id : 특정 프로젝트 카테고리, 용량제한, 활성 상태 변경.
DELETE /api/admin/projects/:id : 프로젝트 삭제 (단, tb_data 등 사용이력 체크 후 존재 시 400 반환).
GET /api/admin/permissions/project/:projectId : 현장 참여 유저 목록 조회.
POST /api/admin/permissions/assign : 다중 유저 배정 (tb_permission 일괄 Insert).
PUT /api/admin/permissions/update : 배정 유저 권한 등급(lev) 수정.
DELETE /api/admin/permissions/remove : 현장 참여 권한 배정 제외.

② 실시간 배너 공지 API

GET /api/admin/banners : 등록일 범위 및 송출 상태 기반 이력 검색 및 조회.
POST /api/admin/banners : 신규 배너 작성 및 저장 (오늘과 비교하여 상태 계산).
PUT /api/admin/banners/stop/:id : 배너 수동 송출 중지 (상태를 NOTICE_STATUS_expired로 강제 업데이트).

③ 사용자 관리 API

GET /api/admin/users : 전체 사용자 정보 및 재직 상태, 권한그룹 조회.
GET /api/admin/users/:id/permissions : 해당 유저가 참여 중인 현장 목록 조회.
POST /api/admin/users : 신규 사용자 계정 등록 (패스워드는 bcrypt 암호화 저장).
PUT /api/admin/users/:id : 사용자 정보, 그룹 및 재직(재직/퇴직잠금) 상태 수정.
DELETE /api/admin/users/:id : 사용자 삭제 (단, tb_permission에 배정 이력 존재 시 400 반환).

④ 감사 로그 및 정책 설정 API

GET /api/admin/audit-logs : tb_log 기반 파일 조작 중요 이벤트(삭제, 이동, 다운로드 등) 필터링 조회.
GET /api/admin/system-policy : 단일 글로벌 보존 정책 정보 조회.
POST /api/admin/system-policy/update : 글로벌 삭제 정책 설정값 변경 갱신.
GET /api/admin/system-policy/logs : tb_auto_clean_log 정기 스케줄러 배치 구동 이력 조회.

⑤ 공통 코드 관리 API

GET /api/admin/common-codes/masters : 대분류 마스터 리스트 조회.
POST /api/admin/common-codes/masters : 대분류 등록.
DELETE /api/admin/common-codes/masters/:code : 대분류 삭제 (단, code_detail에 자식이 있을 시 400 반환).
GET /api/admin/common-codes/details/:mainCode : 선택 대분류의 소분류 목록 조회.
POST /api/admin/common-codes/details : 소분류 등록 (base_code 자동 조합 필드 저장).

4. 실시간 웹소켓 접속 제어 (`socket.js`)

실시간 접속자 정보 캐싱: 클라이언트 소켓 연결 수립 시, user_id, user_nm, project_id, curPath, user_ip 정보를 전달받아 실시간 접속 메모리 맵 users에 관리합니다.
강제 퇴장 처리: 관리자가 프론트 대시보드에서 [강제퇴장] 단추를 누르면 forcedLogout 소켓 이벤트를 전송하고, 백엔드 서버는 타겟 사용자의 소켓 세션을 탐색하여 즉시 socket.disconnect(true)를 작동시켜 강제 로그아웃 처리를 수행합니다.

5. 자동 보존 백그라운드 스케줄러

정기 주기 배치 구동: node-cron 또는 BullMQ/Redis 기반의 스케줄러가 매일 자정에 자동 실행됩니다.
삭제 연산: tb_system_policy 설정값의 활성화 상태(is_active=true), 최소 유지 개수, 보존 일수 기준에 해당하는 디스크 내 파일(MinIO 스토리지 연동)을 제거하고 DB 메타 데이터를 삭제(Soft Delete 마킹 권장)합니다.
결과 적재: 완료 시 tb_auto_clean_log에 처리한 파일들의 삭제 정보와 정책 적용 기준을 SYSTEM 기록 식별자와 함께 기록합니다.

6. 세부 구현 TO-DO LIST

[1단계] 데이터베이스 확장 DDL 패치 및 기본 데이터 적재 (Seed)

db_patch.sql에 신규 테이블(5개) DDL 쿼리 작성 및 PostgreSQL DB 실행.
공통 코드 기초 레코드 세팅 (카테고리 구분, 권한그룹 코드, 배너상태 코드 등) Seeding 실행.
글로벌 정책 기본 상태(GLOBAL_DELETE_POLICY) 설정 1건 INSERT 적재.

[2단계] 백엔드 관리자 컨트롤러 및 REST API 라우터 개발

권한 그룹 인증용 isAdmin 보안 미들웨어 구현 (middlewares/auth.js).
격리된 폴더 controllers/admin/을 신설하고 adminController.js CRUD 핸들러 구현.
3대 삭제 차단(RESTRICT) 규칙 검증 카운팅 쿼리 및 400 Bad Request 에러 응답 로직 구현.
격리된 폴더 routes/admin/을 신설하고 adminRouter.js 구현 및 app.js 등록.

[3단계] 웹소켓 실시간 접속 맵 구축 및 강제 퇴장 연동

socket.js 내 접속자 메모리 세션 해시맵 구조 설계 및 수집 정보 바인딩.
어드민 전송 forcedLogout 수신부 구현 및 대상 클라이언트 강제 disconnect 트리거 처리.

[4단계] 자동 삭제 배치 스케줄러 구동부 구현

주기적(매일 자정)으로 글로벌 삭제 정책을 조회하여 타겟 파일(MinIO S3 연계)을 필터링 및 제거하는 배치 기능 개발.
삭제 실행 이력을 tb_auto_clean_log에 기록 연동.

[5단계] 프론트엔드 라우팅 적용 및 AJAX 동적 바인딩

관리자 페이지 진입용 GET /admin 라우트 세션 권한 보호 조치 및 EJS/HTML 템플릿 마운트.
격리된 폴더 views/admin/ 하위에 대시보드 마크업, CSS, JS 파일(Fetch 및 인터랙션) 배치.
UI 명세서의 Forest Green 테마 스타일, 행 호버 효과, 행 왜곡 방지 및 모달 팝업 페이드인/블러 효과 정비.
7개 관리 탭 내 JavaScript AJAX Fetch 연동 코드를 구현하여 실물 REST API와 데이터를 연동하고, 400 반환 시 안내 알럿 및 경고 팝업 호출.

7. 검증 계획 (Verification Plan)

① 자동화 API 테스트

mocha 통합 테스트 코드를 신설하여 다음 사항을 자동 검증합니다.
- 비인가 사용자가 /admin 및 하위 API 호출 시 403 Forbidden 발생 여부.
- 3대 삭제 차단 API 호출 시 400 Bad Request 에러 응답 및 데이터 정합성 보존 여부.
- 소분류 상세 코드 등록 시 조합 코드(base_code) 자동 포맷팅 생성 여부.

② 시나리오 기반 수동 검증

화면 인터랙션 육안 확인: 7개 화면의 UI 요소가 깨짐 없이 렌더링되는지 확인하고, 모달 블러 배경 효과를 검사합니다.
웹소켓 강제퇴장: 다중 접속 환경에서 특정 일반 유저를 Kick 하였을 때, 해당 소켓 접속이 즉시 차단되고 리다이렉트가 구동되는지 테스트합니다.
삭제 차단 기능 테스트: 사용 중인 데이터가 있는 프로젝트, 배정된 사용자를 인위적으로 삭제 요청하여 "이력이 존재하여 삭제할 수 없습니다" 경고가 정상 호출되는지 테스트합니다.
정책 요약 동적 매핑: 글로벌 정책 제어값 수정 시 예정 시나리오 문구가 실시간 한글 조합으로 업데이트되는지 체크합니다.

12 KiB Raw Permalink Blame History