# KAMCO Change Detection API

> KAMCO 변화 탐지 시스템을 위한 백엔드 API 서버

## 📋 프로젝트 소개

**kamco-change-detection-api**는 공간 데이터의 변화를 탐지하고 관리하기 위한 RESTful API 서버입니다.
JTS(Java Topology Suite)를 활용한 지오메트리 데이터 처리와 PostgreSQL을 통한 공간 데이터 저장을 지원합니다.

## 🛠️ 기술 스택

| Category | Technology |
|----------|------------|
| **Language** | Java 21 |
| **Framework** | Spring Boot 3.5.7 |
| **Database** | PostgreSQL (with PostGIS) |
| **ORM** | Spring Data JPA + Hibernate |
| **Query** | QueryDSL 5.0.0 (Jakarta) |
| **Geospatial** | JTS (Java Topology Suite) + GeoJSON |
| **Connection Pool** | HikariCP |
| **Build Tool** | Gradle 8.x |
| **Monitoring** | Spring Boot Actuator |
| **Container** | Docker + Docker Compose |
| **CI/CD** | Jenkins |

## 🚀 시작하기

### 필수 요구사항

- Java 21 (JDK 21)
- PostgreSQL 12+ (PostGIS 확장 필요)
- Gradle 8.x (또는 Gradle Wrapper 사용)
- Docker & Docker Compose (선택사항)

### 로컬 환경 설정

1. **저장소 클론**
```bash
git clone https://10.100.0.10:3210/dabeeo/kamco-dabeeo-backoffice.git
cd kamco-back
```

2. **데이터베이스 설정**

PostgreSQL 데이터베이스를 준비하고 `src/main/resources/application-local.yml`을 생성:

```yaml
spring:
  config:
    activate:
      on-profile: local
  datasource:
    url: jdbc:postgresql://localhost:5432/your_database
    username: your_username
    password: your_password
```

> **참고**: `application-local.yml`은 `.gitignore`에 포함되어 있어 Git에 커밋되지 않습니다.

3. **빌드 및 실행**

```bash
# 빌드
./gradlew build

# 실행 (local 프로파일)
./gradlew bootRun

# 또는 JAR 파일로 실행
java -jar build/libs/ROOT.jar
```

서버가 시작되면 http://localhost:8080 에서 접근 가능합니다.

## ⚙️ 프로파일 설정

애플리케이션은 환경별로 다른 설정을 사용합니다:

| 프로파일 | 환경 | 포트 | 설정 파일 |
|---------|------|------|-----------|
| `local` | 로컬 개발 | 8080 | `application.yml` (기본) |
| `dev` | 개발 서버 | 7100 | `application-dev.yml` |
| `prod` | 운영 서버 | 8080 | `application-prod.yml` |

### 프로파일 활성화

```bash
# 개발 환경으로 실행
./gradlew bootRun --args='--spring.profiles.active=dev'

# JAR 실행 시
java -jar build/libs/ROOT.jar --spring.profiles.active=dev
```

## 🧪 테스트

```bash
# 전체 테스트 실행
./gradlew test

# 특정 테스트 클래스 실행
./gradlew test --tests com.kamco.cd.kamcoback.KamcoBackApplicationTests

# 테스트 리포트 확인
open build/reports/tests/test/index.html
```

## 📦 빌드

```bash
# 전체 빌드 (테스트 포함)
./gradlew clean build

# 테스트 제외 빌드 (CI/CD에서 사용)
./gradlew clean build -x test

# JAR 파일만 생성
./gradlew bootJar
```

빌드된 JAR 파일: `build/libs/ROOT.jar`

## 🐳 Docker로 실행하기

### Docker Compose 사용 (권장)

```bash
# 빌드 및 실행
docker-compose -f docker-compose-dev.yml up -d

# 로그 확인
docker-compose -f docker-compose-dev.yml logs -f

# 중지
docker-compose -f docker-compose-dev.yml down
```

### Docker만 사용

```bash
# 이미지 빌드
docker build -f Dockerfile-dev -t kamco-changedetection-api:latest .

# 컨테이너 실행
docker run -d \
  --name kamco-changedetection-api \
  -p 7100:8080 \
  kamco-changedetection-api:latest

# 로그 확인
docker logs -f kamco-changedetection-api
```

## 📡 API 및 모니터링

### Actuator 헬스체크

애플리케이션 상태를 확인할 수 있는 엔드포인트가 제공됩니다:

```bash
# 헬스체크
curl http://localhost:8080/monitor/health

# 응답 예시
{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP"
    },
    "diskSpace": {
      "status": "UP"
    }
  }
}
```

**Actuator 엔드포인트**:
- `/monitor/health` - 애플리케이션 헬스 체크
- `/monitor/health/readiness` - Kubernetes Readiness Probe
- `/monitor/health/liveness` - Kubernetes Liveness Probe

## 🏗️ 프로젝트 구조

```
kamco-back/
├── src/
│   ├── main/
│   │   ├── java/com/kamco/cd/kamcoback/
│   │   │   ├── KamcoBackApplication.java     # 메인 애플리케이션
│   │   │   ├── config/                       # 설정 클래스
│   │   │   │   ├── WebConfig.java            # Jackson, CORS 설정
│   │   │   │   └── StartupLogger.java        # 시작 로그
│   │   │   ├── common/                       # 공통 유틸리티
│   │   │   │   └── utils/geometry/           # GeoJSON 직렬화
│   │   └── resources/
│   │       ├── application.yml               # 기본 설정 + local/prod
│   │       └── application-dev.yml           # 개발 환경 설정
│   └── test/                                 # 테스트 코드
├── build.gradle                              # Gradle 빌드 설정
├── Dockerfile-dev                            # Docker 이미지 정의
├── docker-compose-dev.yml                    # Docker Compose 설정
├── Jenkinsfile-dev                           # Jenkins CI/CD 파이프라인
├── .editorconfig                             # 코드 스타일 설정
├── intellij-java-google-style.xml            # IntelliJ 코드 스타일
└── README.md                                 # 이 문서
```

## 🎨 코드 스타일

프로젝트는 **Google Java Style Guide**를 따르며, 일부 커스터마이징이 적용되어 있습니다:

- **들여쓰기**: 탭 (표시 너비: 2칸)
- **최대 줄 길이**: 100자
- **줄 바꿈**: LF (Unix 스타일)
- **인코딩**: UTF-8

### IntelliJ IDEA 설정

1. `Preferences` → `Editor` → `Code Style` → `Java`
2. `Import Scheme` → `intellij-java-google-style.xml` 선택

## 📐 주요 기능

### GeoJSON 지원

JTS Geometry 타입이 자동으로 GeoJSON 형식으로 직렬화/역직렬화됩니다:

```java
@Entity
public class SpatialEntity {
    @Column(columnDefinition = "geometry(Point,4326)")
    private Point location;

    @Column(columnDefinition = "geometry(Polygon,4326)")
    private Polygon boundary;
}
```

**특징**:
- 16자리 정밀도 (기본 8자리에서 증가)
- Point, Polygon, Geometry 타입 지원
- 자동 JSON 변환 (Jackson ObjectMapper 설정)

### QueryDSL 설정

타입 안전한 쿼리를 위해 QueryDSL이 설정되어 있습니다:

```java
// Q-class는 빌드 시 자동 생성됨
QSpatialEntity entity = QSpatialEntity.spatialEntity;

List<SpatialEntity> results = queryFactory
    .selectFrom(entity)
    .where(entity.name.eq("example"))
    .fetch();
```

**Q-class 생성 위치**: `build/generated/sources/annotationProcessor/java/main`

## 🚢 배포

### Jenkins CI/CD

Jenkins를 통한 자동 배포가 설정되어 있습니다 (`Jenkinsfile-dev`):

**파이프라인 단계**:
1. **Checkout**: Git 저장소에서 코드 가져오기 (develop 브랜치)
2. **Get Commit Hash**: 버전 태깅용 커밋 해시 추출
3. **Build**: Gradle로 JAR 빌드 (테스트 제외)
4. **Docker Build & Deploy**: Docker 이미지 빌드 및 배포
5. **Cleanup**: 오래된 이미지 정리

**자동 기능**:
- Git 커밋 해시로 이미지 태깅
- 기존 컨테이너 자동 교체
- 헬스체크로 배포 검증
- 오래된 이미지 자동 정리 (최신 5개 유지)

### 수동 배포

```bash
# 1. 빌드
./gradlew clean build -x test

# 2. Docker 이미지 빌드
docker-compose -f docker-compose-dev.yml build

# 3. 배포
docker-compose -f docker-compose-dev.yml up -d

# 4. 헬스체크
curl http://localhost:7100/monitor/health
```

## 🔧 개발 가이드

### 새로운 엔티티 추가

1. `domain` 패키지에 엔티티 클래스 생성
2. JPA 어노테이션 설정
3. 빌드하여 Q-class 자동 생성
4. Repository 인터페이스 작성 (QueryDSL custom 메서드 포함)

### GeoJSON 데이터 다루기

```java
// Controller에서 GeoJSON 수신/반환
@PostMapping("/spatial")
public ResponseEntity<SpatialEntity> create(@RequestBody SpatialEntity entity) {
    // Point, Polygon이 자동으로 GeoJSON에서 변환됨
    return ResponseEntity.ok(spatialService.save(entity));
}

// 응답 예시
{
  "id": 1,
  "location": {
    "type": "Point",
    "coordinates": [126.9779692, 37.5662952]
  }
}
```

### 데이터베이스 마이그레이션

현재 설정은 `ddl-auto: validate`이므로 스키마 변경 시:

1. 수동으로 마이그레이션 스크립트 작성
2. 또는 개발 중에는 `ddl-auto: update` 사용 (주의 필요)
3. 운영 환경에서는 반드시 `validate` 유지

## 📝 환경 변수

Docker Compose 또는 시스템 환경 변수로 설정 가능:

| 변수명 | 설명 | 기본값 |
|--------|------|--------|
| `SPRING_PROFILES_ACTIVE` | 활성 프로파일 | `local` |
| `IMAGE_TAG` | Docker 이미지 태그 | `latest` |
| `TZ` | 타임존 | `Asia/Seoul` |

## 🐛 트러블슈팅

### DataSource 설정 오류

```
Failed to configure a DataSource: 'url' attribute is not specified
```

**해결 방법**:
1. 프로파일 이름 확인: `dev`, `prod`, `local` (철자 정확히)
2. 해당 프로파일의 `application-{profile}.yml`에 datasource 설정 존재 확인
3. PostgreSQL 접속 정보 확인

### Q-class가 생성되지 않음

```bash
# 강제로 Q-class 재생성
./gradlew clean compileJava
```

생성 위치: `build/generated/sources/annotationProcessor/java/main`

### Docker 컨테이너 헬스체크 실패

```bash
# 컨테이너 로그 확인
docker logs kamco-changedetection-api

# 직접 헬스체크
docker exec kamco-changedetection-api curl http://localhost:8080/monitor/health
```

## 📚 참고 문서

- [Spring Boot 3.5.7 Documentation](https://docs.spring.io/spring-boot/3.5.7/reference/)
- [Spring Data JPA](https://docs.spring.io/spring-data/jpa/reference/)
- [QueryDSL](https://querydsl.com/static/querydsl/latest/reference/html/)
- [JTS Topology Suite](https://github.com/locationtech/jts)
- [GeoJSON Specification](https://geojson.org/)

## 📄 라이선스

Copyright © 2024 KAMCO. All rights reserved.

## 👥 기여자

- Development Team at KAMCO