Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,31 @@ dependencies {
implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

// === 로컬 전용 dev 소스셋(스펙 021) ===
// src/dev: 마커 클러스터링 튜닝 페이지처럼 로컬 실행(bootRun)에서만 쓰는 코드. 배포 jar(bootJar)·운영 이미지에는 넣지 않는다.
// 운영 코드가 바뀌어 dev 코드가 깨지면 바로 알 수 있도록 check(= build)가 컴파일한다.
sourceSets {
dev {
compileClasspath += sourceSets.main.output
runtimeClasspath += sourceSets.main.output
}
}

configurations {
devImplementation.extendsFrom implementation
devCompileOnly.extendsFrom compileOnly
devAnnotationProcessor.extendsFrom annotationProcessor
devRuntimeOnly.extendsFrom runtimeOnly
}

tasks.named('bootRun') {
classpath += sourceSets.dev.output
}

tasks.named('check') {
dependsOn tasks.named('devClasses')
}

tasks.named('test') {
useJUnitPlatform()
finalizedBy tasks.named('jacocoTestReport')
Expand Down
156 changes: 156 additions & 0 deletions docs/adr/0015-server-side-grid-marker-clustering.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
# ADR 0015: 지도 마커 클러스터링 — 서버 고정 그리드

## 상태 (Status)

Accepted (2026-10-09)

> **갱신 (2026-10-15)** — 유형 필터의 출처를 회원 저장 필터에서 요청 파라미터(`practiceTypes`)로 고쳤다([ADR 0016](0016-filter-param-and-sort-tags.md)). 클러스터링 결정 자체는 그대로다.

## 배경

지도 화면은 확대 정도에 따라 장소를 숫자 원("100")으로 묶어 보여주고, 확대하면 개별 장소를 보여준다. 지금은 `GET /places/coordinates`가 노출 장소 전체 좌표를 내려주고 **클러스터링은 앱이 각자** 한다([스펙 005](../specs/005-place-course-discovery.md)).

앱은 iOS·안드로이드 두 벌이다. 플랫폼마다 클러스터러 구현과 파라미터가 달라, **같은 화면에서도 묶이는 결과가 다를 수 있다.** 두 앱이 같은 결과를 보여주도록 클러스터링을 서버로 옮기기로 했다(2026-10-08).

고려할 조건은 다음과 같다.

- 장소는 현재 약 200개이고 계속 늘어난다.
- 디자인의 클러스터는 **개수만 있는 원**이다. 지역 이름은 없다.
- **검색은 버튼으로만 한다.** 처음 진입하거나 "재검색"을 누르면 그때의 화면 범위에서 장소를 찾는다. 이후 **확대·축소는 새 검색 없이 묶음만 바뀌고**, 카메라를 옮겨도 검색 결과는 그대로다.
- 유형 필터가 마커에도 적용된다(`practiceTypes` 요청 파라미터, [ADR 0016](0016-filter-param-and-sort-tags.md)). 필터 조합마다 보이는 장소 집합이 다르다.
- 기기마다 화면 크기가 다르고, 지도 SDK의 줌 단위도 플랫폼마다 다를 수 있다.

## 결정

**검색할 때 서버가 고정 그리드로 확대 단계별 묶음을 모두 계산해 한 번에 내려준다.** 요청은 검색 범위(화면 bbox)만 받는다. 확대·축소할 때 앱은 서버에 묻지 않고 받아 둔 단계 중 하나를 고른다.

### 1. 검색 한 번에 모든 확대 단계를 준다

- 응답에는 검색 범위의 장소 목록과, **확대 단계별 묶음**(클러스터·개별 장소)이 들어 있다. 단계는 넓은 순으로 **그리드 단계들 → 개별 장소만 보이는 단계**이고, 검색 범위와 무관하게 항상 같은 구성이다.
- 가장 넓은 단계는 **한반도 전체 화면용**이다. 앱이 최대 축소를 한반도 전체로 제한하고, 그 화면에서 전국 장소가 약 6~8개 마커(팔도 정도의 밀도)로 보이도록 칸 크기를 튜닝한다.
- 단계 구간은 화면 폭 0부터 무한대까지 빈틈없이 이어져, **어떤 확대·축소 상태든 해당 단계가 반드시 하나 있다.**
- 각 단계에는 **"화면 경도 폭이 얼마부터 얼마까지일 때 쓰는가"** 를 붙인다. 앱은 지금 화면의 경도 폭(동쪽 경도 − 서쪽 경도)으로 맞는 단계를 골라 그린다.
- 확대·축소에 서버 왕복이 없어 **즉시 바뀐다.** 묶는 계산은 서버가 하므로 두 플랫폼의 결과는 같다. 앱의 일은 경도 폭 비교 하나뿐이다.
- 경도 폭을 기준으로 쓰는 이유: Web Mercator의 가로 좌표는 경도에 정비례해, 앱이 투영 계산 없이 화면 모서리 경도만 빼면 된다. 앱 지도의 투영이 조금 다르더라도 앱은 SDK가 알려주는 화면 모서리 경도만 쓰므로 규칙은 그대로 적용된다.

### 2. 검색 범위 안의 장소만 묶는다

묶는 대상은 **검색 범위 안의 장소**(노출 조건·`practiceTypes` 필터 적용)뿐이다. 아래 추천 목록(`GET /places`)과 같은 집합이라, 어느 단계든 **클러스터 개수 합 + 개별 장소 수 = 목록 전체 개수**가 된다.

### 3. 격자는 지도 좌표에 고정한다

- 격자는 **Web Mercator(EPSG:3857) 좌표의 원점에 고정**한다. 검색 범위나 화면이 아니라 지도에 박혀 있으므로, 같은 지역은 어떤 범위로 검색해도 같은 칸으로 나뉜다.
- Web Mercator를 쓰는 이유: 대부분의 웹·모바일 지도가 쓰는 투영이라, 같은 크기의 칸이 화면에서도 거의 정사각형으로 보인다. 위경도(4326)로 칸을 나누면 한국 위도에서 칸이 세로로 약 1.25배 길쭉해진다.

### 4. 칸 크기는 2배 단위의 고정 크기만 쓴다

- 단계마다 칸 크기가 정해져 있고, 한 단계 작아질 때마다 칸이 절반이 된다. 화면 폭에 맞는 단계는 **화면 가로에 약 5칸이 들어가는 단계**다(실제로는 3.5~7칸).
- 칸 크기를 화면 폭에 딱 맞추지 않는 이유: 조금만 확대해도 칸이 바뀌어 묶음이 계속 다시 섞이고, 화면 크기가 조금 다른 기기끼리 격자가 어긋난다. 고정 크기면 화면 폭이 꽤 바뀌기 전까지 같은 묶음이 유지되고, 기기가 달라도 같은 단계를 고르는 경우가 많다.
- 앱은 줌 레벨을 다루지 않는다. SDK마다 줌 단위가 다르면 서버가 SDK에 묶이기 때문이다.

### 5. 응답은 알고리즘과 무관하게 둔다

- 단계별 묶음은 **클러스터(개수·위치·범위)** 와 **개별 장소** 두 종류뿐이다. 칸 번호·칸 크기 같은 그리드 전용 값은 넣지 않는다. 단계와 경도 폭 범위는 거리 기반 방식에도 있는 개념이다.
- 이렇게 두면 추후 서버 안에서 계산 방식을 바꿔도 앱은 수정할 필요가 없다.

### 6. 클러스터 위치는 칸 안쪽으로 제한한 중심점이다

클러스터 원은 묶인 장소들의 중심점에 그리되, 칸 가장자리에서 칸 크기의 1/4 안쪽 영역으로 제한한다.

- 중심점을 그대로 쓰면 이웃한 두 칸의 장소가 공유 경계에 몰렸을 때 두 원이 붙어 겹친다.
- 칸 중앙에 그리면 겹치지 않지만, 장소가 칸 구석에 있어도 가운데에 떠 위치가 부정확해진다.
- 안쪽으로 제한하면 이웃한 원은 최소 칸 크기의 절반만큼 떨어지고(폰 화면 약 37pt), 대부분의 클러스터는 실제 중심점에 그대로 그려진다.

### 7. 클러스터 탭 확대는 서버가 범위(`bounds`)로 정한다

클러스터를 탭했을 때 **어디로 확대할지는 서버가 정하고, 얼마나 확대할지는 기기가 정한다.**

- 서버는 클러스터마다 묶인 장소들을 감싸는 **좌표 범위(`bounds`, 남서·북동)** 를 준다.
- 앱은 탭하면 그 범위를 지도 SDK의 범위 맞춤 기능(카카오 `fitMapPoints` 등)에 넘긴다. 여백(padding)은 앱이 정한다.
- SDK가 그 기기의 화면 크기·비율에 맞춰 범위가 다 들어오는 줌을 계산한다. 작은 폰은 더 확대되고 큰 화면은 덜 확대되지만, **묶였던 장소가 모두 화면에 들어온다는 결과는 같다.**
- 확대가 끝나면 앱은 새 화면 경도 폭에 맞는 단계로 바꿔 그린다(서버 요청 없음). 그래서 탭 한 번에 클러스터가 작은 클러스터나 개별 장소로 풀린다.

**범위 최소 크기** — 여러 장소가 거의 같은 좌표에 있으면 범위가 점처럼 작아져, SDK 최대 확대에서도 같은 칸에 남아 풀리지 않을 수 있다. 범위의 가로·세로를 **"묶지 않는 화면 폭"의 절반 이상**으로 넓혀 준다. 그러면 범위에 맞춘 화면 폭이 앱 여백을 더해도 묶지 않는 폭 이하가 되어, **탭 한 번에 반드시 개별 장소로 풀린다.**

범위는 픽셀이 아니라 좌표라 SDK·기기와 무관하고, 그리드든 거리 기반이든 "묶인 장소들의 범위"는 똑같이 줄 수 있다. 계산 방식을 바꿔도 앱의 탭 동작은 그대로다.

### 8. 기본값은 운영하며 화면을 보고 조정한다

화면당 칸 수(5), 묶지 않는 화면 폭(지상 약 1km), 원 위치 제한(칸의 1/4)은 서버 설정값으로 둔다. 앱 연동 전후로 실제 지도에 그려 보며 조정한다(스펙의 튜닝 방법 참고).

### 9. 기존 좌표 API는 전환 기간 동안 유지한다

`GET /places/coordinates`는 앱이 클러스터 API로 옮겨 갈 때까지 유지하고, 이후 제거한다.

## 결과

### 긍정적

- iOS·안드로이드가 같은 규칙으로 같은 결과를 보여준다.
- **확대·축소가 즉시 바뀐다.** 검색할 때 한 번만 서버에 묻는다.
- 클러스터 숫자와 추천 목록 개수가 항상 맞는다(같은 장소 집합).
- 같은 입력이면 항상 같은 응답이다(결정적).
- 검색 범위 장소를 한 번 조회해 메모리에서 단계별로 묶으면 끝난다. 유형 필터는 조회 조건에 더하면 되고, 미리 계산해 둘 것이 없다.
- 앱의 클러스터러 구현·튜닝이 필요 없어진다.
- 클러스터 탭 확대도 서버가 정한 범위를 따르므로 두 플랫폼의 확대 결과가 같다. 앱은 범위 맞춤 한 줄만 구현하면 된다.

### 부정적

- **칸 경계에서 쪼개진다.** 아주 가까운 두 장소도 경계 양쪽에 있으면 다른 클러스터가 된다.
- 경계에 장소가 몰린 클러스터는 원이 실제 중심점보다 칸 안쪽에 그려진다(겹침 방지의 대가). 탭하면 `bounds`로 이동하므로 확대 결과에는 영향이 없다.
- 검색 응답이 단계 수만큼 커진다(기본 11단계). 장소 200개 규모에서는 문제없지만, 검색 범위의 장소가 수천 개로 늘면 크기를 다시 본다.
- 앱이 최대 축소를 한반도 전체로 제한해야 한다. 그보다 더 축소하면 원이 서로 가까워질 수 있다.
- 앱이 단계를 고르는 규칙(경도 폭 비교)을 구현해야 한다. 단순한 비교라 플랫폼 간 차이가 생길 여지는 작다.
- 화면 크기가 다른 기기는 같은 줌에서도 보이는 영역이 달라, 클러스터가 픽셀 단위로 같지는 않다.

### 중립적

- [ADR 0003](0003-region-hierarchy-and-postgis.md)의 region 테이블은 여전히 없다. 이번 결정은 region에 의존하지 않는다.

## 검토한 대안

### 클라이언트 클러스터링 유지

지금 방식이다. 서버 작업이 없지만, 플랫폼마다 결과가 달라질 수 있다는 문제를 해결하지 못한다. 서버로 옮긴 이유 자체라 택하지 않았다.

### 행정구역(시도·시군구) 기준 묶음

"마포구 12"처럼 지역 이름이 붙는 디자인에 맞는 방식이다. 하지만 디자인의 클러스터는 개수만 있고, region 테이블(중심좌표)도 구현돼 있지 않다. 지역마다 크기 차이가 커서 화면에서 밀도가 고르지 않다는 문제도 있다.

### 거리 기반 — 검색할 때 계산 (`ST_ClusterDBSCAN` 등)

가까운 장소끼리 묶어 경계 쪼개짐이 없고 원 간격도 자연스럽게 확보되며, 실제 분포를 더 잘 보여준다. 검색할 때만 계산하는 지금 구조에서는 장소 집합이 재검색 전까지 고정이라, 화면을 옮길 때 묶음이 흔들리는 문제도 없다. 다만 단계마다 거리 기준을 정하고 결과를 단계 간에 일관되게 맞추는 일이 그리드보다 복잡하다. 단순하고 예측하기 쉬운 그리드로 시작하고, 아래 전환 조건에 따라 다시 본다.

### 거리 기반 — 전체 장소를 미리 계산 (Supercluster 방식)

검색과 무관하게 전체 장소를 단계별로 미리 묶어 두는 정석이다. 장소가 추가·승인·삭제될 때마다 다시 계산해야 하고, 유형 필터 때문에 **필터 조합별로** 미리 계산해야 해서 비용이 조합 수만큼 늘어난다. 검색할 때 검색 범위만 계산하는 지금 구조로 충분해 택하지 않았다.

### 거리 기반으로의 전환

**추후 전환 후보로 남긴다.** 응답이 단계별 묶음 형태라 서버 안의 묶는 방식만 바꾸면 된다(검색 범위 장소에 단계별 거리 기반 묶음 적용).

전환을 검토할 시점: 경계 쪼개짐이나 칸 안쪽으로 당겨진 원 위치가 디자인·QA에서 문제로 지적되거나, 장소 수가 늘어 밀도 차이가 두드러질 때. 응답 형태를 알고리즘과 무관하게 두었으므로 서버만 바꾸면 된다.

### 확대 — 서버가 목표 줌 레벨을 준다

"이 클러스터는 줌 15에서 풀린다"처럼 레벨을 주면 앱 구현이 더 단순하다. 하지만 SDK마다 줌 단위가 다르면 서버가 특정 SDK에 묶이고, 같은 줌이라도 화면 크기에 따라 보이는 영역이 달라 기기마다 풀리는 정도가 달라진다. 좌표 범위를 주고 기기가 맞추는 쪽을 택했다.

### 확대 — 앱이 알아서 확대한다

탭하면 한두 단계 확대하는 식으로 앱에 맡길 수 있다. 서버 응답은 단순해지지만, 몇 단계를 확대해야 풀리는지 앱이 모르므로 여러 번 탭해야 하거나 지나치게 확대될 수 있고, 플랫폼마다 동작이 달라진다. 플랫폼 통일이라는 목표와 맞지 않아 택하지 않았다.

### 확대·축소할 때마다 서버에 다시 요청

단계 하나만 주고, 앱이 확대·축소를 마칠 때마다 새 화면 범위로 다시 요청하는 방식이다. 응답은 작지만 확대할 때마다 0.1~0.3초 왕복이 생기고, 요청마다 화면 범위가 바뀌어 "검색은 버튼으로만"이라는 화면 흐름과도 맞지 않는다.

### 확대 대신 묶인 장소 목록을 보여준다

탭하면 클러스터 안 장소 목록을 띄우는 방식이다. 디자인에 이런 화면이 없어 지금은 택하지 않았다. 필요해지면 클러스터 범위로 기존 목록 API(`GET /places`)를 부르는 식으로 확장할 수 있다.

## 참조

- [스펙 021 — 지도 마커 서버 클러스터링](../specs/021-marker-clustering.md)
- [스펙 005 — 코스 탐색(마커 좌표 API)](../specs/005-place-course-discovery.md)
- [ADR 0003 — 지역 처리](0003-region-hierarchy-and-postgis.md)
- [ADR 0010 — 목록 조회 전략](0010-list-query-cursor-postgis.md)
- 이슈 [#76](https://github.com/Central-MakeUs/Rodi-Server/issues/76)
1 change: 1 addition & 0 deletions docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,4 +34,5 @@
| [0012](0012-visit-record-duplicate-guard.md) | 방문 기록 중복 방지 — 쿨다운 | Accepted |
| [0013](0013-withdrawal-locked-as-status.md) | 재가입 대기 안내 — 에러 대신 상태 응답 | Accepted |
| [0014](0014-nickname-validation-and-profanity-filter.md) | 닉네임 검증 — 형식 규칙 + 리소스 금칙어(포함/정확 일치 분리) | Accepted |
| [0015](0015-server-side-grid-marker-clustering.md) | 지도 마커 클러스터링 — 서버 고정 그리드 | Accepted |
| [0016](0016-filter-param-and-sort-tags.md) | 홈 유형 필터 분리 — 저장 태그는 정렬(sort_tags), 필터는 요청 파라미터 | Accepted |
Loading
Loading