# PM_ver4 로컬 실행을 위한 To-Do List 및 개발 환경 세팅 가이드

이 문서는 **PM_ver4** 프로젝트를 로컬(Windows) 개발 환경에서 성공적으로 빌드하고 실행하기 위한 전체 To-Do List입니다. 이 프로젝트는 Node.js(Express) 백엔드, PostgreSQL DB, Redis(BullMQ), MinIO(스토리지) 및 외부 OAuth(Sentinel) 연동으로 구성되어 있습니다.

---

## 📋 로컬 실행 To-Do List 요약

- [V] **1단계: 필수 개발 도구 설치 (Prerequisites)**
- [V] **2단계: 의존성 패키지 설치 (`npm install`)**
- [V] **3단계: Docker Compose를 이용한 로컬 인프라 구동 (DB, Redis, MinIO)**
- [V] **4단계: 환경 변수(`.env`) 파일 작성**
- [ ] **5단계: 데이터베이스 스키마 생성 및 초기 데이터 적재**
- [ ] **6단계: 로컬 테스트를 위한 인증(SSO) 우회 설정 (선택/권장)**
- [ ] **7단계: 외부 문서 변환 프로그램 확인 (`programs/`)**
- [ ] **8단계: 웹 서버 실행 및 접속 테스트**

---

## 🛠️ 단계별 상세 가이드

### 1단계: 필수 개발 도구 설치
프로젝트 구동을 위해 로컬 PC에 아래 도구들이 설치되어 있어야 합니다.
*   **Node.js**: v18 또는 v20 LTS 권장
*   **Docker Desktop**: PostgreSQL, Redis, MinIO를 원클릭으로 띄우기 위해 필요

### 2단계: 의존성 패키지 설치
1. 터미널(PowerShell 등)을 열고 프로젝트 폴더의 `trunk/PM_ver4`로 이동합니다.
2. 아래 명령어를 실행하여 npm 패키지들을 설치합니다.
   ```bash
   npm install
   ```

### 3단계: Docker Compose 실행 (로컬 인프라 구동)
프로젝트에 포함된 `docker-compose.yml`을 사용하여 PostgreSQL, Redis, MinIO 서비스를 가상 환경으로 실행합니다.
1. `trunk/PM_ver4` 디렉토리에서 아래 명령을 실행합니다.
   ```bash
   docker compose up -d
   ```
2. 컨테이너가 정상적으로 실행되었는지 확인합니다 (`docker ps`).
   *   **PostgreSQL**: `5432` 포트
   *   **Redis**: `6379` 포트
   *   **MinIO**: `9000` (S3 API), `9001` (관리자 웹 콘솔) 포트

### 4단계: 환경 변수(`.env`) 파일 작성
`trunk/PM_ver4` 루트 디렉토리에 `.env` 파일을 새로 생성하고 아래 내용을 환경에 맞춰 입력합니다.

```env
# 1. 공통 애플리케이션 설정
NODE_ENV=development
SERVICE_NAME=PM_ver4_LOCAL
DEPLOYMENT_TYPE=ONPREMISE
COOKIE_SECRET=your_secret_cookie_key

# 2. 로컬 서버 IP 및 포트
LOCAL_IP=localhost
LOCAL_PORT=6565

# 3. PostgreSQL DB 설정 (ONPREMISE)
ONPREMISE_POSTGRES_HOST=localhost
ONPREMISE_POSTGRES_PORT=5432
ONPREMISE_POSTGRES_DATABASE=pm_db
ONPREMISE_POSTGRES_USER=postgres
ONPREMISE_POSTGRES_PASSWORD=your_password

# 4. Redis 설정
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# 5. MinIO 스토리지 설정
MINIO_ENDPOINT=http://localhost:9000
MINIO_ACCESSKEYID=minio_access_key
MINIO_SECRETACCESSKEY=minio_secret_key

# 6. OAuth(Sentinel SSO) 인증 서버 설정
SENTINEL_BASE=http://sso.hanmaceng.co.kr  # 실제 사내 SSO 주소 입력
CLIENT_ID=PM_LOCAL

# 7. Gemini API 설정 (공문 AI 파싱 기능 사용 시 필요)
GEMINI_API_KEY=your_google_gemini_api_key
```

### 5단계: 데이터베이스 스키마 생성 및 초기 데이터 적재
Docker로 postgres 컨테이너만 띄운 상태이므로, 데이터베이스(`pm_db`) 내부에 스키마와 테이블들이 존재하지 않습니다. 로컬 실행을 위해 아래 작업이 필요합니다.

1. **스키마 백업본 확보**: 사내 개발 환경 혹은 운영 환경 DB에서 `ver4` 스키마 DDL/DML 백업 파일(`.sql` 등)을 받습니다.
2. **로컬 DB에 적용**:
   *   DBeaver, pgAdmin 등의 DB 클라이언트를 통해 `localhost:5432`로 PostgreSQL에 접속합니다.
   *   데이터베이스 이름: `pm_db`, 사용자: `postgres`, 비밀번호: `your_password`
   *   `ver4` 스키마를 생성하고 백업받은 SQL 덤프 파일을 실행하여 테이블들을 구축합니다.
   *   *참고: `tb_user`, `tb_permission`, `_test_tb_data`, `_test_tb_log`, `tb_official_doc_file` 등의 테이블이 필요합니다.*

### 6단계: 로컬 테스트를 위한 인증(SSO) 우회 설정 (권장)
이 프로젝트는 로그인 시 외부 `Sentinel SSO` 서버로 리다이렉트되어 인증을 처리합니다. 사내 망 외부이거나 로컬에서 간편하게 개발을 진행하려면 인증 미들웨어를 임시로 우회해야 합니다.

*   **우회 방법**: [oauthController.js](file:///d:/40. 개발소스/04. PM/pm_ver4/trunk/PM_ver4/oauth/oauthController.js) 파일의 `isLoggedIn` 함수를 수정하여 항상 특정 개발자 계정 세션을 갖도록 처리할 수 있습니다.
    ```javascript
    // d:/40. 개발소스/04. PM/pm_ver4/trunk/PM_ver4/oauth/oauthController.js
    exports.isLoggedIn = async(req, res, next) => {
        // 로컬 테스트 시 강제로 세션 주입하고 통과시킴
        req.session.user = { 
            userId: 'test_user', 
            user_nm: '테스트사용자',
            group: 'dev' 
        };
        next();
    }
    ```
*   **사용자 디바인딩 우회**: GSIM 서버 연동이 안 될 경우, [oauthController.js](file:///d:/40. 개발소스/04. PM/pm_ver4/trunk/PM_ver4/oauth/oauthController.js)의 `deserializeUser` 함수에서 `axios.post` 부분을 주석 처리하고 Mock User 정보를 `req.user`에 직접 할당해야 합니다.

### 7단계: 외부 문서 변환 프로그램 확인
`trunk/PM_ver4/programs/` 디렉토리에 파일 암호화 도구(`encryp.exe`), 썸네일 추출기(`pdf_thumb.exe`), 한글/캐드 변환 모듈 등이 존재합니다.
*   백그라운드 변환 기능(BullMQ 워커)이 올바르게 실행되려면 Windows 환경에서 해당 윈도우용 CLI 프로그램들의 실행 권한 및 관련 라이브러리 연동에 문제가 없어야 합니다.

### 8단계: 웹 서버 실행 및 접속 테스트
1. 의존성 패키지와 로컬 인프라(Docker) 세팅이 끝나면 아래 명령으로 Node.js 서버를 실행합니다.
   ```bash
   npm run start
   ```
   *(내부적으로 `nodemon server.js`가 구동됩니다.)*
2. 콘솔에 `>> Web Server Start : http://localhost:6565/ 번 포트에서 대기 중` 로그와 `Redis connected`, `DB 연결 성공` 메시지가 찍히는지 확인합니다.
3. 웹 브라우저를 열고 `http://localhost:6565`에 접속하여 로컬 구동 여부를 확인합니다.