234 lines
5.1 KiB
Markdown
234 lines
5.1 KiB
Markdown
# Dabeeo Detection API
|
|
|
|
> Dabeeo 변화 탐지 시스템을 위한 백엔드 API 서버
|
|
|
|
---
|
|
|
|
## 📋 프로젝트 소개
|
|
|
|
**dabeeo-detection-api**
|
|
|
|
본 프로젝트는 영상 데이터를 기반으로 변화 탐지를 수행하는 시스템의 백엔드 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 |
|
|
|
|
---
|
|
|
|
## 🚀 시작하기
|
|
|
|
### 필수 요구사항
|
|
|
|
- Java 21 (JDK 21)
|
|
- PostgreSQL 12+ (PostGIS 확장 필요)
|
|
- Gradle 8.x (또는 Gradle Wrapper 사용)
|
|
- Docker & Docker Compose (선택사항)
|
|
|
|
---
|
|
|
|
### 로컬 환경 설정
|
|
|
|
#### 1. 저장소 클론
|
|
|
|
https://kamco.git.gs.dabeeo.com/MVPTeam/DABEEO-DETECTION-APPLICATION.git
|
|
|
|
---
|
|
|
|
#### 2. 데이터베이스 설정
|
|
|
|
PostgreSQL 데이터베이스를 준비하고
|
|
`src/main/resources/application-local.yml` 파일을 생성합니다.
|
|
|
|
```yaml
|
|
spring:
|
|
config:
|
|
activate:
|
|
on-profile: local
|
|
datasource:
|
|
url: jdbc:postgresql://localhost:5432/dabeeo_detection_dev
|
|
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` | 개발 서버 | 8080 | `application-dev.yml` |
|
|
| `prod` | 운영 서버 | 8080 | `application-prod.yml` |
|
|
|
|
---
|
|
|
|
### 프로파일 실행 방법
|
|
|
|
```bash
|
|
# dev 실행
|
|
./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
|
|
|
|
# 테스트 제외
|
|
./gradlew clean build -x test
|
|
|
|
# JAR 생성
|
|
./gradlew bootJar
|
|
```
|
|
|
|
빌드 결과:
|
|
|
|
build/libs/ROOT.jar
|
|
|
|
---
|
|
|
|
## 📁 프로젝트 구조
|
|
### (2026-04-08 기준)
|
|
|
|
```
|
|
api-app # 메인 실행 모듈
|
|
├── app
|
|
│ ├── src/main
|
|
│ │ ├── java/com/cd/detection
|
|
│ │ │ ├── DabeeoDetectionApiApplication.java
|
|
│ │ │
|
|
│ │ │ ├── config # 설정 파일
|
|
│ │ │
|
|
│ │ │ ├── domain # 도메인
|
|
│ │ │ │ ├── imagery # 영상 데이터 관리
|
|
│ │ │ │ ├── labeling # 라벨링 툴
|
|
│ │ │ │ ├── label # 라벨링 관리
|
|
│ │ │ │ ├── model # 모델관리
|
|
│ │ │ │ ├── inference # 추론관리
|
|
│ │ │ │ ├── system # 시스템관리
|
|
│ │ │ │ └── log # 로그관리
|
|
│ │ │
|
|
│ │ │ ├── entity # 공용 JPA 엔티티 (DB 공통 사용)
|
|
│ │ │ │
|
|
│ │ │ └── repository # 공용 Repository (DB 공통 인터페이스/구현)
|
|
│ │ │
|
|
│ │ └── resources # 설정 및 리소스 파일
|
|
│ │ ├── application.yml
|
|
│ │ ├── application-dev.yml
|
|
│ │ └── application-prod.yml
|
|
│ │
|
|
│ └── build.gradle
|
|
│
|
|
├── infrastructure-db-postgres # Postgres 전용 설정/확장
|
|
│ └── build.gradle
|
|
│
|
|
├── build.gradle
|
|
├── settings.gradle
|
|
├── gradle/
|
|
└── gradlew
|
|
```
|
|
|
|
---
|
|
|
|
## 🧩 아키텍처 설계
|
|
|
|
본 프로젝트는 API 모듈과 DB 모듈을 분리한 멀티 모듈 구조를 사용합니다.
|
|
|
|
---
|
|
|
|
### 📌 모듈 구성
|
|
|
|
| 모듈 | 설명 |
|
|
|------|------|
|
|
| api-app | API 및 비즈니스 로직 |
|
|
| infrastructure-db-postgres | DB 접근 및 설정 |
|
|
|
|
---
|
|
|
|
## 🗄️ Database Module 분리 전략
|
|
|
|
DB 관련 로직은 별도의 모듈(infrastructure-db-postgres)로 분리되어 관리됩니다.
|
|
|
|
---
|
|
|
|
### 🎯 분리 목적
|
|
|
|
- 기술 의존성 분리
|
|
- DB 교체 용이성
|
|
- 관심사 분리
|
|
- 확장성 확보
|
|
|
|
---
|
|
|
|
### 🔄 처리 흐름
|
|
|
|
Controller → Service → Repository → DB
|
|
|
|
---
|
|
|
|
### 💡 설계 포인트
|
|
|
|
- API 모듈은 DB 기술에 직접 의존하지 않음
|
|
- DB 관련 코드는 별도 모듈에서 관리
|
|
- DB 변경 시 API 코드 수정 최소화
|
|
|
|
---
|
|
|
|
## 🔥 한 줄 요약
|
|
|
|
DB 기술 변경에 유연하게 대응하기 위해 persistence 레이어를 모듈로 분리했습니다.
|