# POP Monitoring Backend API

POP 모니터링 데이터를 제공하는 내부용 백엔드 서버입니다.

[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)
[![NestJS](https://img.shields.io/badge/NestJS-11.0-red)](https://nestjs.com/)

## 목차

- [개요](#개요)
- [Quick Start](#quick-start)
- [기술 스택](#기술-스택)
- [프로젝트 구조](#프로젝트-구조)
- [환경 설정](#환경-설정)
- [실행 방법](#실행-방법)
- [API 문서](#api-문서)
- [테스트](#테스트)
- [개발 가이드](#개발-가이드)
- [트러블슈팅](#트러블슈팅)
- [배포](#배포)

---

## 개요

### 목적

실시간 및 일자별 공정 현황, 재고 현황을 RESTful API로 제공합니다.

### 주요 기능

- **조립 공정 모니터링**: 실시간/일자별 조립 공정 현황 조회
- **재고 모니터링**: 재고 현황 실시간 조회
- **호기 관리**: 호기별 공정 상세 정보 조회
- **공정 상태 추적**: 대기/재공 상태 추적

### 주요 사용자

- 내부 대시보드
- 운영/현장 담당자
- 연동 서비스

---

## Quick Start

### 최소 요구사항

- Node.js >= 20
- MSSQL 접근 가능 환경 (사내 VPN 등)

### 빠른 시작

```bash
# 1. 저장소 클론
git clone <repository-url>
cd pop-monitoring-backend

# 2. 의존성 설치
npm install

# 3. 환경 변수 설정
cp .env.example .env
# .env 파일을 열어 MSSQL 접속 정보 입력

# 4. 개발 서버 실행
npm run start:dev

# 5. API 문서 확인
# http://localhost:3000/docs
```

---

## 기술 스택

### Core

- **Runtime**: Node.js 20
- **Language**: TypeScript 5
- **Framework**: NestJS 11

### Database

- **MSSQL**: Stored Procedure 기반 데이터 접근
- **Driver**: `mssql` (node-mssql)

### Libraries

- **Validation**: `class-validator`, `class-transformer`
- **Logging**: `nestjs-pino`, `pino`
- **Documentation**: `@nestjs/swagger`

### Development Tools

- **Testing**: Jest
- **Linting**: ESLint
- **Formatting**: Prettier
- **Type Checking**: TypeScript Compiler
- **Git Hooks**: Husky + lint-staged
- **Commit Linting**: Commitlint

---

## 프로젝트 구조

```
pop-monitoring-backend/
├── src/
│   ├── api/                          # API 엔드포인트
│   │   └── monitoring/
│   │       └── cp/
│   │           ├── assembly/         # 조립 모니터링
│   │           │   ├── dto/          # Data Transfer Objects
│   │           │   │   ├── request/  # Query/Body DTO
│   │           │   │   ├── response/ # Response DTO
│   │           │   │   └── internal/ # DB/Transform DTO
│   │           │   ├── transformers/ # 데이터 변환 로직
│   │           │   ├── assembly-monitoring.controller.ts
│   │           │   ├── assembly-monitoring.service.ts
│   │           │   └── assembly-monitoring.sp.repository.ts
│   │           └── inventory/        # 재고 모니터링
│   ├── common/                       # 공통 모듈
│   │   ├── decorators/               # 커스텀 데코레이터
│   │   ├── dto/                      # 공통 DTO
│   │   ├── filters/                  # Exception Filters
│   │   ├── interceptors/             # Interceptors
│   │   ├── middlewares/              # Middlewares
│   │   ├── types/                    # Type Definitions
│   │   └── utils/                    # Utility Functions
│   ├── infra/                        # 인프라 계층
│   │   └── mssql/                    # MSSQL 연결 관리
│   ├── app.module.ts                 # Root Module
│   └── main.ts                       # Application Entry
├── test/                             # E2E/Integration Tests
├── .github/                          # GitHub 설정
│   ├── workflows/                    # CI/CD
│   ├── ISSUE_TEMPLATE/               # Issue Templates
│   ├── CODING_CONVENTIONS.md         # 코딩 컨벤션
│   ├── CONTRIBUTING.md               # 기여 가이드
│   └── pull_request_template.md      # PR Template
├── .env.example                      # 환경 변수 예시
├── package.json
└── tsconfig.json
```

### 아키텍처

```
Client → Controller → Service → Repository → MSSQL (Stored Procedure)
```

**레이어별 역할**:

- **Controller**: HTTP 요청/응답 처리, 입력 검증
- **Service**: 비즈니스 로직 처리
- **Repository**: 데이터베이스 접근 (SP 호출)
- **Transformer**: DB 결과를 Response DTO로 변환

---

## 환경 설정

### 환경 변수 설정

`.env.example`을 복사하여 `.env` 파일을 생성합니다:

```bash
cp .env.example .env
```

### 환경 변수 설명

#### Server 설정

```bash
NODE_ENV=development          # development | production
PORT=3000                     # 서버 포트
LOG_LEVEL=info               # trace | debug | info | warn | error | fatal
```

#### MSSQL 데이터베이스

```bash
MSSQL_HOST=localhost         # DB 호스트
MSSQL_PORT=1433              # DB 포트
MSSQL_DB=your_database_name  # 데이터베이스 이름
MSSQL_USER=sa                # DB 사용자명
MSSQL_PASSWORD=your_password # DB 비밀번호
```

#### MSSQL 옵션

```bash
MSSQL_ENCRYPT=false          # SSL 암호화 사용 여부
MSSQL_TRUST_CERT=true        # 자체 서명 인증서 신뢰 여부
```

#### MSSQL Pool 설정

```bash
MSSQL_POOL_MAX=10            # 최대 연결 수
MSSQL_POOL_MIN=1             # 최소 연결 수
MSSQL_POOL_IDLE_TIMEOUT=30000    # 유휴 연결 타임아웃 (ms)
MSSQL_REQUEST_TIMEOUT=30000      # 요청 타임아웃 (ms)
```

---

## 실행 방법

### 개발 모드

```bash
# 의존성 설치
npm install

# 개발 서버 실행 (Hot Reload)
npm run start:dev

# 디버그 모드 실행
npm run start:debug
```

### 프로덕션 모드

```bash
# 빌드
npm run build

# 프로덕션 실행
npm run start:prod
```

### 코드 품질 체크

```bash
# Lint 체크 및 자동 수정
npm run lint

# Type 체크
npm run typecheck

# 코드 포맷팅
npm run format
```

---

## API 문서

### Swagger UI

서버 실행 후 다음 URL에서 API 문서를 확인할 수 있습니다:

```
http://localhost:3000/docs
```

---

## 테스트

### 테스트 실행

```bash
# Unit 테스트
npm run test

# Unit 테스트 (watch 모드)
npm run test:watch

# Integration 테스트
npm run test:int

# E2E 테스트
npm run test:e2e

# Coverage 측정
npm run test:cov
```

### 테스트 구조

- **Unit Test** (`*.spec.ts`): 개별 컴포넌트 테스트
- **Integration Test** (`*.int.spec.ts`): DB 연동 테스트
- **E2E Test** (`*.e2e-spec.ts`): 전체 플로우 테스트

---

## 개발 가이드

### 시작하기

1. **이슈 확인**: [GitHub Issues](../../issues)에서 작업할 이슈 확인
2. **브랜치 생성**: `feature/issue-number-feature-name` 형식으로 생성
3. **코딩 컨벤션 준수**: [CODING_CONVENTIONS.md](.github/CODING_CONVENTIONS.md) 참고
4. **테스트 작성**: 새로운 기능에 대한 테스트 필수
5. **코드 품질 체크**: Push 전 lint, typecheck 실행
6. **PR 생성**: [pull_request_template](.github/pull_request_template.md) 참고

### Git Hooks (자동 실행)

프로젝트에는 코드 품질을 자동으로 보장하는 Git Hooks가 설정되어 있습니다.

#### Pre-commit Hook

커밋 전 자동으로 실행됩니다:

- **lint-staged**: 변경된 파일만 ESLint + Prettier 자동 수정
  - `*.{ts,js}`: ESLint 수정 + Prettier 포맷팅
  - `*.{json,md,yml,yaml}`: Prettier 포맷팅

#### Pre-push Hook

푸시 전 자동으로 실행됩니다:

- **TypeScript 타입 체크**: `npm run typecheck`

#### Commit-msg Hook

커밋 메시지 작성 시 자동으로 검증됩니다:

- **Commitlint**: 커밋 메시지 형식 검증 (Conventional Commits)

#### Hook 우회 (긴급 상황)

```bash
# 커밋 시 hook 우회 (권장하지 않음)
git commit --no-verify

# 푸시 시 hook 우회 (권장하지 않음)
git push --no-verify
```

### 필수 확인 사항

Git Hooks가 자동으로 실행되지만, 수동으로 확인하고 싶다면:

```bash
# 1. Lint 체크
npm run lint

# 2. Type 체크
npm run typecheck

# 3. 테스트 실행
npm run test
```

### 코딩 컨벤션

자세한 내용은 [CODING_CONVENTIONS.md](.github/CODING_CONVENTIONS.md)를 참고하세요.

**핵심 규칙**:

- 파일명: `kebab-case`
- 변수/함수: `camelCase`
- 클래스/인터페이스: `PascalCase`
- 상수: `UPPER_SNAKE_CASE`
- DTO 파일: `{name}.{type}.dto.ts`

### Git 워크플로우

#### 브랜치 전략

```
main (production)
  └─ dev (development)
      ├─ feature/xxx
      ├─ fix/xxx
      └─ refactor/xxx
```

#### 커밋 메시지 규칙 (Commitlint 자동 검증)

커밋 메시지는 다음 형식을 따라야 하며, Commitlint가 자동으로 검증합니다:

```
<type>: <subject>

[optional body]
```

**Type** (필수):

- `feat`: 새로운 기능
- `fix`: 버그 수정
- `refactor`: 리팩토링
- `test`: 테스트 코드
- `chore`: 빌드, 설정
- `docs`: 문서
- `style`: 코드 포맷팅
- `perf`: 성능 개선
- `ci`: CI 설정
- `revert`: 커밋 되돌리기

**예시**:

```bash
# 올바른 커밋 메시지
git commit -m "feat: 실시간 현황 조회 API 추가"
git commit -m "fix: 날짜 검증 로직 오류 수정"

# 잘못된 커밋 메시지 (Commitlint가 거부함)
git commit -m "수정"
git commit -m "Fix bug"  # type은 소문자여야 함
```

---

## 배포

### 프로덕션 빌드

```bash
# 빌드
npm run build

# 빌드 결과 확인
ls -la dist/
```

### Docker 배포

```bash
# 이미지 빌드
docker build -t pop-monitoring-backend .

# 컨테이너 실행 (.env 사용)
docker run --env-file .env -p 3000:3000 pop-monitoring-backend
```

```bash
# docker-compose 사용
docker compose up --build -d
```

`PORT` 등 환경 변수는 `.env`에서 관리합니다.

### 환경별 설정

#### Development

```bash
NODE_ENV=development
LOG_LEVEL=debug
```

#### Production

```bash
NODE_ENV=production
LOG_LEVEL=info
```

## 추가 문서

- [코딩 컨벤션](.github/CODING_CONVENTIONS.md) - 프로젝트 코딩 규칙
- [PR 템플릿](.github/pull_request_template.md) - 프로젝트 기여 방법

---

## 라이선스

UNLICENSED - 내부 프로젝트