fix(map): 지도 줌 계층과 마커 피드백 보정

[HOKAGO-MEMORIES]

Summary

• Add SIDO-level viewport mode and direct visible-property aggregation for SIDO/SIGUNGU/DONG region markers.
• Tighten cluster grid sizes and cap Naver map zoom at backend-supported max zoom to reduce empty zoom/API-error cases.
• Show feedback for region/cluster marker clicks, use monthly rent for monthly-rent marker labels, and translate MULTI_FAMILY to Korean.
• Update Map View API docs for the revised zoom thresholds and representative-price behavior.

Tests

• backend: .\mvnw.cmd test
• frontend: pnpm test
• frontend: pnpm build

Closes #64

Summary by CodeRabbit

• New Features
  • Added a lower-zoom “SIDO average” map view for broader-area browsing.
  • Introduced a selected-viewport summary card with price/count details and one-click zoom to the selection.
• Bug Fixes
  • Improved viewport mode switching across zoom ranges.
  • Corrected marker/summary primary price display to align with the correct transaction type (including monthly rent for region-average and monthly-rent items).
• UI Improvements
  • Enhanced region-level and property-type labels in map markers and summaries.
  • Updated a property filter label to clearer wording.
• Documentation
  • Updated the Map View API example request and zoom-to-display-mode mapping.
• Tests
  • Updated and expanded viewport utility, controller, and store tests to match new behavior.

[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 12:30pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e7037e5a-e3e4-467f-a90c-2855644d6b5e

📥 Commits

Reviewing files that changed from the base of the PR and between 26c5b63 and f0cad76.

📒 Files selected for processing (5)

• docs/08_API_SPEC.md
• frontend/src/store/mapStore.js
• frontend/src/store/mapStore.test.mjs
• frontend/src/utils/mapViewport.js
• frontend/src/utils/mapViewport.test.mjs

🚧 Files skipped from review as they are similar to previous changes (2)

• frontend/src/utils/mapViewport.test.mjs
• frontend/src/utils/mapViewport.js

---

📝 Walkthrough

Walkthrough

Adds SIDO_AVG viewport support, generalizes region-average aggregation, and updates frontend selection, labels, marker behavior, tests, and API docs.

Changes

SIDO_AVG Viewport Mode — Full Stack

Layer / File(s)	Summary
Backend mode routing and aggregation backend/src/main/java/com/ssafy/salmanhae/model/dto/map/MapViewportMode.java, backend/src/main/java/com/ssafy/salmanhae/service/map/MapViewportServiceImpl.java, backend/src/main/java/com/ssafy/salmanhae/model/dao/property/JdbcPropertyDao.java	Adds SIDO_AVG, routes zoom ≤ 9 to it, dispatches SIDO region-average queries, updates cluster grid zoom constants, and generalizes region-average SQL for SIDO/SIGUNGU/DONG.
Backend tests and API spec backend/src/test/java/com/ssafy/salmanhae/controller/map/MapViewportControllerTest.java, docs/08_API_SPEC.md	Updates viewport controller expectations for the new zoom mapping and revised statistics, and revises the API spec to document SIDO_AVG and the new zoom ranges.
Viewport utility helpers and tests frontend/src/utils/mapViewport.js, frontend/src/utils/mapViewport.test.mjs	Adds SIDO_AVG to viewport modes, changes primary price selection, introduces region and property label helpers, updates region-average marker labeling, and adjusts the utility tests.
Map store viewport selection state frontend/src/store/mapStore.js, frontend/src/store/mapStore.test.mjs	Adds selectedViewportItem, introduces viewport-data and selection actions, clears the selection in reset and property-selection paths, and adds store tests for viewport-data handling.
MapExplorer sidebar and marker interaction frontend/src/views/MapExplorer.vue	Adds the selected viewport sidebar summary card, updates marker click handling and zoom targets, uses the shared label and price helpers, adjusts the count label and filter text, and sets map maxZoom.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant MapExplorer
  participant mapStore
  participant MapViewportServiceImpl
  participant JdbcPropertyDao

  User->>MapExplorer: open map at low zoom
  MapExplorer->>MapViewportServiceImpl: GET /api/v1/map/viewport?zoom=8
  MapViewportServiceImpl->>MapViewportServiceImpl: resolveMode(zoom) -> SIDO_AVG
  MapViewportServiceImpl->>JdbcPropertyDao: findRegionAverageViewportItems(..., "SIDO", limit)
  JdbcPropertyDao-->>MapViewportServiceImpl: region-average items
  MapViewportServiceImpl-->>MapExplorer: viewport response with mode and items
  User->>MapExplorer: click region marker
  MapExplorer->>mapStore: selectViewportItem(item)
  MapExplorer-->>User: sidebar summary card and zoom action

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• ssafy-salman/salmanhae#54: Introduced the viewport API and initial zoom-based mode routing that this PR extends with SIDO_AVG.
• ssafy-salman/salmanhae#56: Added the earlier region-average aggregation path in JdbcPropertyDao, which this PR generalizes across region levels.
• ssafy-salman/salmanhae#62: Modified the same region-average query area in JdbcPropertyDao, making it directly relevant to the DAO refactor in this PR.

Suggested labels

ai-generated

Poem

🐇 A hop for SIDO, wide and grand,
The map now greets the whole blue land.
Monthly rent now leads the way,
And labels dance in Korean display.
Click, zoom, and peek — the sidebar sings,
While rabbit ears applaud these map-view things.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description does not follow the required template sections and is missing the checklist-style format.	Rewrite the PR description using the repository template: fill in 변경 내용, 연결 이슈, 테스트 checkboxes, and 리뷰 포인트.
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 (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately reflects the zoom-layer and marker-feedback changes.
Linked Issues check	✅ Passed	The changes align with #64 by adding SIDO zoom support, adjusting thresholds, marker feedback, monthly-rent labels, and Korean type labels.
Out of Scope Changes check	✅ Passed	No clear out-of-scope changes are evident; the edits support the map zoom and marker-feedback objectives.

_{✏️ 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 fix/map-viewport-followups

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 markdownlint-cli2 (0.22.1)

docs/08_API_SPEC.md

markdownlint-cli2 v0.22.1 (markdownlint v0.40.0)
Error: Unable to use configuration file '/coderabbit-0.markdownlint-cli2.jsonc'; ENOENT: no such file or directory, open '/coderabbit-0.markdownlint-cli2.jsonc'
at throwForConfigurationFile (file:///usr/local/lib/node_modules/markdownlint-cli2/markdownlint-cli2.mjs:48:9)
at readOptionsOrConfig (file:///usr/local/lib/node_modules/markdownlint-cli2/markdownlint-cli2.mjs:169:5)
at async main (file:///usr/local/lib/node_modules/markdownlint-cli2/markdownlint-cli2.mjs:927:21)
at async file:///usr/local/lib/node_modules/markdownlint-cli2/markdownlint-cli2-bin.mjs:14:22 {
[cause]: Error: ENOENT: no such file or directory, open '/coderabbit-0.markdownlint-cli2.jsonc'
at async open (node:internal/fs/promises:640:25)
at async Object.readFile (node:internal/fs/promises:1287:14)
at async readOptionsOrConfig (file:///usr/local/lib/node_modules/markdownlint-cli2/markdownlint-cli2.mjs:141:17)
at async main (file:///usr/local/lib/node_modules/markdownlint-cli2/markdownlint-cli2.mjs:927:21)
at async file:///usr/local/lib/node_modules/markdownlint-cli2/markdownlint-cli2-bin.mjs:14:22 {
errno: -2,
code: 'ENOENT',
syscall: 'open',
path: '/coderabbit-0.markdownlint-cli2.jsonc'
}
}

---

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

[coderabbitai]

Actionable comments posted: 3

🤖 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 175-178: The API spec sample is inconsistent with the updated zoom
thresholds, because the example request still uses a zoom level that now maps to
a different mode than the sample response shows. Update the sample
request/response around the documented zoom behavior so the request value, the
returned mode, and the explanation all match the new threshold logic in the API
spec; check the zoom table and the nearby sample block to keep them aligned.

In `@frontend/src/store/mapStore.js`:
- Around line 203-210: The viewport selection in selectViewportItem is sticky
and keeps overriding the property list in MapExplorer.vue, so clear
selectedViewportItem when the viewport refresh transitions to property results
or when the fetch mode becomes PROPERTY_MARKER. Update the state flow around
selectViewportItem and the viewport refresh/fetch handling so
selectedViewportItem is reset once real properties are loaded, allowing the
sidebar to show the new results instead of the summary card.

In `@frontend/src/utils/mapViewport.js`:
- Around line 25-29: The regionLevelLabel mapping currently returns an
inaccurate label for SIDO. Update the regionLevelLabel function so the SIDO
entry uses 시/도 instead of 도, while keeping the other level labels unchanged and
preserving the fallback to 지역.

🪄 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: abfa1e78-df45-4756-84f7-fa49bfcade0c

📥 Commits

Reviewing files that changed from the base of the PR and between 123df64 and 26c5b63.

📒 Files selected for processing (9)

• backend/src/main/java/com/ssafy/salmanhae/model/dao/property/JdbcPropertyDao.java
• backend/src/main/java/com/ssafy/salmanhae/model/dto/map/MapViewportMode.java
• backend/src/main/java/com/ssafy/salmanhae/service/map/MapViewportServiceImpl.java
• backend/src/test/java/com/ssafy/salmanhae/controller/map/MapViewportControllerTest.java
• docs/08_API_SPEC.md
• frontend/src/store/mapStore.js
• frontend/src/utils/mapViewport.js
• frontend/src/utils/mapViewport.test.mjs
• frontend/src/views/MapExplorer.vue