From f8f5cef6e17102bb44420f9d24d6945d81d48ed1 Mon Sep 17 00:00:00 2001 From: teddy Date: Mon, 2 Feb 2026 12:26:48 +0900 Subject: [PATCH] first commit --- README.md | 387 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 387 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..14f8adf --- /dev/null +++ b/README.md @@ -0,0 +1,387 @@ +# KAMCO Change Detection Training API + +> KAMCO 변화 탐지 학습 시스템을 위한 백엔드 API 서버 + +## 📋 프로젝트 소개 + + +## 🛠️ 기술 스택 + +| 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.training.KamcoTrainingApplicationTests + +# 테스트 리포트 확인 +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 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 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