RESTAPI_SERVER/README.md

# REST API 서버

Oracle Database를 사용하는 Node.js Express REST API 서버입니다.

## 🚀 기능

### 🎯 **핵심 기능**
- **완전한 웹 UI**: API 키 발급, 데이터 관리, 모니터링 대시보드
- **사용자 인증**: JWT 토큰 기반 로그인/회원가입 시스템
- **API 키 관리**: 키 생성, 권한 설정, 사용량 모니터링
- **CRUD 작업**: 데이터 생성, 조회, 수정, 삭제
- **Oracle DB 연결**: Oracle Database와 연결 풀 사용
- **RESTful API**: 표준 REST API 엔드포인트 제공
- **에러 핸들링**: 체계적인 에러 처리 및 응답
- **CORS 지원**: 크로스 오리진 요청 허용

### 🔐 **보안 기능**
- **JWT 토큰 인증**: 안전한 사용자 세션 관리
- **API 키 인증**: 외부 시스템 연동을 위한 API 키 시스템
- **권한 관리**: 사용자별, API 키별 세분화된 권한 제어
- **비밀번호 해시**: PBKDF2 기반 안전한 비밀번호 저장

### 📊 **관리 기능**
- **실시간 대시보드**: API 사용 통계 및 모니터링
- **사용자 관리**: 관리자 전용 사용자 관리 패널
- **API 문서**: 내장된 인터랙티브 API 문서
- **시스템 모니터링**: 서버 및 데이터베이스 상태 확인

## 📋 요구사항

- Node.js 14.x 이상
- Oracle Database 접근 권한
- Oracle Instant Client (oracledb 패키지용)

## 🛠 설치 및 실행

### 방법 1: Docker 사용 (권장) 🐳

#### 🚀 **Windows 사용자 - 간단한 실행**
```cmd
# 서버 시작 (빌드 포함)
start-server.bat

# 서버 중지
stop-server.bat
```

#### 📋 **Windows 배치 파일 목록**
- `start-server.bat` - 서버 빌드 및 시작 (Oracle DB 연결 실패 시 Mock DB 자동 사용)
- `stop-server.bat` - 서버 중지

#### 🗄️ **데이터베이스 옵션**
1. **Mock DB (기본)**: Oracle DB 연결 없이 메모리 기반 데이터 사용
2. **Oracle DB**: 실제 Oracle Database 연결 (Instant Client 필요)

#### 🐧 **Linux/macOS 사용자**
```bash
# 실행 권한 부여 (최초 1회)
chmod +x *.sh

# 서버 시작 (빌드 포함)
./start-server.sh

# 서버 중지
./stop-server.sh
```

#### 📋 **Linux 스크립트 파일 목록**
- `start-server.sh` - 서버 빌드 및 시작 (Oracle DB 연결 실패 시 Mock DB 자동 사용)
- `stop-server.sh` - 서버 중지

자세한 Docker 사용법은 [DOCKER.md](DOCKER.md)를 참조하세요.

### 방법 2: 직접 설치

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

#### 2. Oracle Instant Client 설치
Oracle Instant Client를 시스템에 설치해야 합니다.
- [Oracle Instant Client 다운로드](https://www.oracle.com/database/technologies/instant-client.html)

#### 3. 서버 실행
```bash
# 개발 모드 (nodemon 사용)
npm run dev

# 프로덕션 모드
npm start
```

서버는 포트 5577에서 실행됩니다: http://localhost:5577

### 🌐 **웹 UI 접속**
브라우저에서 http://localhost:5577 접속하여 관리 대시보드를 사용할 수 있습니다.

**기본 관리자 계정:**
- 사용자명: `admin`
- 비밀번호: `admin123!`

## 🗄 데이터베이스 설정

### 연결 정보
- **호스트**: 39.117.244.52
- **포트**: 11521
- **데이터베이스**: XE
- **사용자명**: wace
- **비밀번호**: wace0909!!

### 테이블 구조
```sql
CREATE TABLE API_DATA (
    ID NUMBER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    NAME VARCHAR2(100) NOT NULL,
    DESCRIPTION VARCHAR2(500),
    DATA_VALUE CLOB,
    CREATED_AT TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UPDATED_AT TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

## 📡 API 엔드포인트

### 🔐 **인증 API**
- **Base URL**: `http://localhost:5577/auth`

#### 사용자 등록
```
POST /auth/register
Content-Type: application/json

{
  "username": "사용자명",
  "email": "이메일@example.com",
  "password": "비밀번호"
}
```

#### 로그인
```
POST /auth/login
Content-Type: application/json

{
  "username": "사용자명",
  "password": "비밀번호"
}
```

#### API 키 생성
```
POST /auth/api-keys
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "keyName": "키 이름",
  "permissions": ["read", "write", "delete"]
}
```

### 📊 **데이터 API**
- **Base URL**: `http://localhost:5577/api`
- **인증**: API 키 또는 JWT 토큰 필요

#### 1. 헬스 체크
```
GET /api/health
```

#### 2. 모든 데이터 조회
```
GET /api/data
X-API-Key: {YOUR_API_KEY}
# 또는
Authorization: Bearer {JWT_TOKEN}
```

#### 3. 특정 데이터 조회
```
GET /api/data/:id
X-API-Key: {YOUR_API_KEY}
```

#### 4. 데이터 생성
```
POST /api/data
X-API-Key: {YOUR_API_KEY}
Content-Type: application/json

{
  "name": "데이터 이름",
  "description": "데이터 설명",
  "dataValue": "데이터 값"
}
```

#### 5. 데이터 수정
```
PUT /api/data/:id
X-API-Key: {YOUR_API_KEY}
Content-Type: application/json

{
  "name": "수정된 이름",
  "description": "수정된 설명",
  "dataValue": "수정된 값"
}
```

#### 6. 데이터 삭제
```
DELETE /api/data/:id
X-API-Key: {YOUR_API_KEY}
```

## 📝 응답 형식

### 성공 응답
```json
{
  "success": true,
  "message": "작업 성공 메시지",
  "data": { ... }
}
```

### 에러 응답
```json
{
  "success": false,
  "message": "에러 메시지",
  "error": "상세 에러 정보"
}
```

## 🧪 테스트 예제

### cURL을 사용한 테스트

#### 데이터 생성
```bash
curl -X POST http://localhost:5577/api/data \
  -H "Content-Type: application/json" \
  -d '{
    "name": "테스트 데이터",
    "description": "API 테스트용 데이터",
    "dataValue": "{\"test\": true}"
  }'
```

#### 모든 데이터 조회
```bash
curl http://localhost:5577/api/data
```

#### 특정 데이터 조회
```bash
curl http://localhost:5577/api/data/1
```

#### 데이터 수정
```bash
curl -X PUT http://localhost:5577/api/data/1 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "수정된 데이터",
    "description": "수정된 설명",
    "dataValue": "{\"updated\": true}"
  }'
```

#### 데이터 삭제
```bash
curl -X DELETE http://localhost:5577/api/data/1
```

## 🔧 설정 파일

### config/database.js
Oracle Database 연결 설정이 포함되어 있습니다.

## 📁 프로젝트 구조

```
restapi-server/
├── start-server.bat         # Windows 서버 시작 스크립트
├── stop-server.bat          # Windows 서버 중지 스크립트
├── start-server.sh          # Linux 서버 시작 스크립트
├── stop-server.sh           # Linux 서버 중지 스크립트
├── config/
│   └── database.js          # DB 연결 설정
├── database/
│   ├── connection.js        # DB 연결 풀 관리
│   ├── queries.js           # SQL 쿼리 함수들
│   └── init.sql            # 테이블 생성 스크립트
├── routes/
│   ├── api.js              # 데이터 API 라우트
│   └── auth.js             # 인증 API 라우트
├── middleware/
│   └── auth.js             # 인증 미들웨어
├── public/                 # 웹 UI 정적 파일
│   ├── index.html          # 메인 대시보드 페이지
│   ├── css/
│   │   └── style.css       # 스타일시트
│   └── js/
│       └── app.js          # 프론트엔드 JavaScript
├── scripts/                 # 기타 Docker 스크립트 (선택사항)
│   ├── docker-build.bat     # Windows용 빌드 스크립트
│   ├── docker-build.sh      # Linux/macOS용 빌드 스크립트
│   ├── docker-run.bat       # Windows용 실행 스크립트
│   ├── docker-run.sh        # Linux/macOS용 실행 스크립트
│   ├── docker-run-dev.bat   # Windows용 개발 모드 스크립트
│   └── docker-run-dev.sh    # Linux/macOS용 개발 모드 스크립트
├── test/
│   └── api-test.js          # API 테스트 스크립트
├── postman/
│   └── REST-API-Collection.json # Postman 테스트 컬렉션
├── Dockerfile               # Docker 이미지 빌드 설정
├── docker-compose.yml       # Docker Compose 설정 (프로덕션)
├── docker-compose.dev.yml   # Docker Compose 설정 (개발)
├── .dockerignore           # Docker 빌드 제외 파일
├── package.json            # 프로젝트 설정
├── server.js               # 메인 서버 파일
├── README.md               # 프로젝트 문서
└── DOCKER.md               # Docker 실행 가이드
```

## 🚨 주의사항

1. Oracle Instant Client가 올바르게 설치되어 있어야 합니다.
2. 데이터베이스 연결 정보가 정확한지 확인하세요.
3. 방화벽에서 포트 5577이 열려있는지 확인하세요.
4. 프로덕션 환경에서는 보안을 위해 데이터베이스 연결 정보를 환경변수로 관리하세요.

## 🐛 문제 해결

### Oracle Client 관련 오류
- Oracle Instant Client가 설치되어 있는지 확인
- 시스템 PATH에 Oracle Client 경로가 포함되어 있는지 확인

### 데이터베이스 연결 오류
- 네트워크 연결 상태 확인
- 데이터베이스 서버가 실행 중인지 확인
- 연결 정보(호스트, 포트, 사용자명, 비밀번호)가 정확한지 확인