[Phase 1] map viewport contract

[HOKAGO-MEMORIES]

변경 내용

• F-1 지도 확대 수준별 표시를 위한 /api/v1/map/viewport 계약과 최소 구현 추가
• zoom threshold를 SIGUNGU_AVG, DONG_AVG, PROPERTY_CLUSTER, PROPERTY_MARKER로 분기
• 테스트용 dotenv 격리와 CORS 테스트 origin 명시
• docs/08_API_SPEC.md에 threshold 정책 반영
• phases/map-viewport-zoom phase 문서 5개 작성

연결 이슈

closes #53

테스트

• ./mvnw.cmd -q -Dtest=MapViewportControllerTest test
• ./mvnw.cmd -q -Dtest=PropertyControllerTest,MapViewportControllerTest test
• ./mvnw.cmd -q test

Summary by CodeRabbit

• New Features
  • Added a zoom-aware GET /api/v1/map/viewport endpoint that returns a mode, viewport items, and totalCount based on zoom (region average → cluster → property markers).
• Bug Fixes
  • Improved request validation for missing/invalid zoom and geographic bounds (returns 400 with error codes).
• Tests
  • Added controller tests covering zoom-based mode switching and empty-result behavior.
• Documentation
  • Updated API spec examples and zoom-threshold “display mode” documentation, plus new phase planning/QA docs.
• Chores
  • Updated test environment handling and CORS test configuration.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
salmanhae	Ready	Preview, Comment	Jun 24, 2026 6:32am

[coderabbitai]

📝 Walkthrough

Walkthrough

Phase 1 adds a zoom-aware GET /api/v1/map/viewport endpoint, its viewport DTO contract, zoom-to-mode service routing, MockMvc coverage, test environment setup, and matching API/phase documentation updates.

Changes

Map Viewport API Contract (Phase 1)

Layer / File(s)	Summary
Viewport DTO types and sealed response hierarchy backend/src/main/java/com/ssafy/salmanhae/model/dto/map/MapViewportItemType.java, backend/src/main/java/com/ssafy/salmanhae/model/dto/map/MapViewportMode.java, backend/src/main/java/com/ssafy/salmanhae/model/dto/map/MapViewportItemResponse.java, backend/src/main/java/com/ssafy/salmanhae/model/dto/map/MapViewportRequest.java, backend/src/main/java/com/ssafy/salmanhae/model/dto/map/MapViewportResponse.java, backend/src/main/java/com/ssafy/salmanhae/model/dto/map/RegionAverageViewportItem.java, backend/src/main/java/com/ssafy/salmanhae/model/dto/map/PropertyClusterViewportItem.java, backend/src/main/java/com/ssafy/salmanhae/model/dto/map/PropertyViewportItem.java	MapViewportItemType and MapViewportMode enums are added; MapViewportItemResponse is defined as a sealed interface; MapViewportRequest and MapViewportResponse are introduced; and three viewport item records are added for region averages, clusters, and properties.
Service interface and zoom routing backend/src/main/java/com/ssafy/salmanhae/service/map/MapViewportService.java, backend/src/main/java/com/ssafy/salmanhae/service/map/MapViewportServiceImpl.java	MapViewportService declares getViewport; MapViewportServiceImpl validates input, checks bounds, resolves the mode from zoom thresholds, and returns an empty response for the resolved mode.
REST endpoint wiring backend/src/main/java/com/ssafy/salmanhae/controller/map/MapViewportController.java	MapViewportController exposes GET /api/v1/map/viewport, accepts bounds and filter parameters, builds PropertySearchCriteria, validates bounds, and delegates to the service.
Controller tests and test environment setup backend/src/test/java/com/ssafy/salmanhae/controller/map/MapViewportControllerTest.java, backend/src/test/resources/.env.properties, backend/src/test/resources/application-test.properties, .gitignore	MockMvc tests cover zoom-mode responses and invalid input handling; test dotenv and CORS settings are added; .gitignore un-ignores the test env properties file.
API spec and phase planning docs docs/08_API_SPEC.md, phases/map-viewport-zoom/phase1-map-viewport-contract.md, phases/map-viewport-zoom/phase1.status.json, phases/map-viewport-zoom/phase2-region-and-cluster-query.md, phases/map-viewport-zoom/phase3-frontend-map-viewport-api.md, phases/map-viewport-zoom/phase4-frontend-zoom-rendering.md, phases/map-viewport-zoom/phase5-qa-docs-deploy.md	The API spec separates cluster and property-marker response modes and adds zoom thresholds; the phase contract and completion status are added; the phase docs for backend, frontend, rendering, and QA/deploy planning are added.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• ssafy-salman/salmanhae#10: Introduced the PropertySearchCriteria and shared API/error-response primitives used by the new viewport controller and service validation path.

Poem

🐇 I hopped by the viewport, ears held high,
Zoom levels dancing under the sky.
Clusters, markers, regions too,
All lined up in a tidy view.
Empty today, but the path is clear—
The map can bloom when data appears.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description covers changes, linked issue, and tests; the review-point section is omitted, but that is non-critical.
Linked Issues check	✅ Passed	The implementation matches #53 by adding the zoom-aware viewport API, thresholds, tests, and phase1 contract document.
Out of Scope Changes check	✅ Passed	The extra docs and test-environment changes are referenced by the PR goals, so they are in scope.
Title check	✅ Passed	The title matches the main change: Phase 1 work for the map viewport contract.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch phase/1-map-viewport-contract

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

backend/src/test/java/com/ssafy/salmanhae/controller/map/MapViewportControllerTest.java (1)

23-81: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add explicit zoom boundary tests for the controller contract.

Please add assertions for zoom=0 (SIGUNGU_AVG), zoom=21 (PROPERTY_MARKER), and out-of-range zoom=22 returning INVALID_REQUEST to lock down @Min/@Max boundary behavior.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@backend/src/test/java/com/ssafy/salmanhae/controller/map/MapViewportControllerTest.java`
around lines 23 - 81, The MapViewportControllerTest coverage is missing explicit
zoom boundary checks for the controller contract. Extend the existing
`getViewport...` tests to assert that `zoom=0` returns `SIGUNGU_AVG`, `zoom=21`
returns `PROPERTY_MARKER`, and `zoom=22` is rejected with `INVALID_REQUEST`,
using the same `baseViewportRequest()`/`mockMvc.perform(...)` pattern so the
`@Min/@Max` behavior is locked down in the controller tests.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/08_API_SPEC.md`:
- Around line 168-178: The example payload in the API spec is still mixing
PROPERTY_CLUSTER data into the PROPERTY_MARKER response, which conflicts with
the split mode contract. Update the relevant examples in the spec so the
PROPERTY_MARKER example contains only individual marker items, and keep any
clustered items shown only in the PROPERTY_CLUSTER example or section. Use the
mode labels PROPERTY_CLUSTER and PROPERTY_MARKER to verify the examples match
the intended payload shape.

In `@phases/map-viewport-zoom/phase1-map-viewport-contract.md`:
- Around line 15-20: The phase 1 checklist is still marked incomplete even
though the phase status says it is done, so update the checklist in
phase1-map-viewport-contract.md to match the implemented/completed state. Make
the entries for the GET /api/v1/map/viewport accessibility, zoom threshold
behavior, bounds validation, backend controller tests, and API spec reflect
completion so the checklist and phase status stay consistent.

---

Nitpick comments:
In
`@backend/src/test/java/com/ssafy/salmanhae/controller/map/MapViewportControllerTest.java`:
- Around line 23-81: The MapViewportControllerTest coverage is missing explicit
zoom boundary checks for the controller contract. Extend the existing
`getViewport...` tests to assert that `zoom=0` returns `SIGUNGU_AVG`, `zoom=21`
returns `PROPERTY_MARKER`, and `zoom=22` is rejected with `INVALID_REQUEST`,
using the same `baseViewportRequest()`/`mockMvc.perform(...)` pattern so the
`@Min/@Max` behavior is locked down in the controller tests.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4517fee2-ca13-4853-8c97-286f0f9ce93e

📥 Commits

Reviewing files that changed from the base of the PR and between 2a81344 and 443685f.

📒 Files selected for processing (22)

• .gitignore
• backend/src/main/java/com/ssafy/salmanhae/controller/map/MapViewportController.java
• backend/src/main/java/com/ssafy/salmanhae/model/dto/map/MapViewportItemResponse.java
• backend/src/main/java/com/ssafy/salmanhae/model/dto/map/MapViewportItemType.java
• backend/src/main/java/com/ssafy/salmanhae/model/dto/map/MapViewportMode.java
• backend/src/main/java/com/ssafy/salmanhae/model/dto/map/MapViewportRequest.java
• backend/src/main/java/com/ssafy/salmanhae/model/dto/map/MapViewportResponse.java
• backend/src/main/java/com/ssafy/salmanhae/model/dto/map/PropertyClusterViewportItem.java
• backend/src/main/java/com/ssafy/salmanhae/model/dto/map/PropertyViewportItem.java
• backend/src/main/java/com/ssafy/salmanhae/model/dto/map/RegionAverageViewportItem.java
• backend/src/main/java/com/ssafy/salmanhae/service/map/MapViewportService.java
• backend/src/main/java/com/ssafy/salmanhae/service/map/MapViewportServiceImpl.java
• backend/src/test/java/com/ssafy/salmanhae/controller/map/MapViewportControllerTest.java
• backend/src/test/resources/.env.properties
• backend/src/test/resources/application-test.properties
• docs/08_API_SPEC.md
• phases/map-viewport-zoom/phase1-map-viewport-contract.md
• phases/map-viewport-zoom/phase1.status.json
• phases/map-viewport-zoom/phase2-region-and-cluster-query.md
• phases/map-viewport-zoom/phase3-frontend-map-viewport-api.md
• phases/map-viewport-zoom/phase4-frontend-zoom-rendering.md
• phases/map-viewport-zoom/phase5-qa-docs-deploy.md