# 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. 구현 전제 및 핵심 비즈니스 규칙

### ① 소스코드 격리 배치 정책 (기존 소스와의 분리)
기존 어플리케이션 소스코드 파일들과 물리적으로 완전히 격리하여 독립적인 유지보수와 안정적인 버전 관리를 보장하기 위해 다음과 같이 **전용 하위 디렉토리를 신설**하여 작업합니다.
1. **백엔드 라우터**: `routes/admin/` 폴더 신설
   - `adminRouter.js`를 배치하여 어드민 API 엔드포인트 일괄 관리.
2. **백엔드 컨트롤러**: `controllers/admin/` 폴더 신설
   - `adminController.js`를 배치하여 어드민 비즈니스 로직 일괄 관리.
3. **프론트엔드 뷰 & 정적 리소스**: `views/admin/` 폴더 신설
   - `dashboard.html` (마크업), `dashboard.js` (Fetch 및 인터랙션 스크립트), `dashboard.css` (테마 스타일시트) 배치.

### ② 3대 삭제 제한 규칙 (RESTRICT)
기속 데이터의 안전한 보호를 위해, 데이터베이스의 CASCADE 물리적 삭제를 지양하고 백엔드 API에서 COUNT 검증 후 `400 Bad Request`와 상세 경고 메시지를 응답하는 로직을 일괄 적용합니다.
1. **프로젝트 관리**: 관련 테이블(`tb_data`, `tb_official_doc_file`, `tb_banner_notice` 등)에 해당 현장 ID 사용 이력이 1건이라도 존재할 시 프로젝트 삭제 차단.
2. **사용자 관리**: 권한 테이블(`tb_permission`)에 해당 유저의 프로젝트 참여/배정 정보가 존재할 시 계정 삭제 차단.
3. **공통 코드 관리**: 대분류 코드(`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 패치로 적재합니다.

```sql
-- 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 하였을 때, 해당 소켓 접속이 즉시 차단되고 리다이렉트가 구동되는지 테스트합니다.
* [ ] **삭제 차단 기능 테스트**: 사용 중인 데이터가 있는 프로젝트, 배정된 사용자를 인위적으로 삭제 요청하여 "이력이 존재하여 삭제할 수 없습니다" 경고가 정상 호출되는지 테스트합니다.
* [ ] **정책 요약 동적 매핑**: 글로벌 정책 제어값 수정 시 예정 시나리오 문구가 실시간 한글 조합으로 업데이트되는지 체크합니다.