fix(map): 넓은 줌 시군구 집계 안정화

[HOKAGO-MEMORIES]

Summary

• Fix broad SIGUNGU_AVG viewport requests by aggregating active visible properties by sigungu instead of using the heavier region-stat join.
• Update the map viewport API spec and phase5 QA notes.
• Record the pre-merge Cloud Run probe where zoom<=11 returned 401, while cluster/detail modes already stayed capped.

Verification

• cd backend && ./mvnw.cmd -Dtest=MapViewportControllerTest test
• cd backend && ./mvnw.cmd test
• cd frontend && CI=true pnpm test
• cd frontend && CI=true pnpm build
• python scripts/execute_codex.py map-viewport-zoom --dry-run

Closes #61

Summary by CodeRabbit

• New Features
  • Broad zoom map views now return district-level (SIGUNGU) averages derived from active, visible properties within the current bounds.
• Bug Fixes
  • Corrected wide-zoom SIGUNGU_AVG response aggregation to keep results smaller and more consistent.
  • Updated map viewport analytics fields/values (e.g., averages and transaction counts) to match the new aggregation.
• Documentation
  • Updated the Map View API “표시 모드” descriptions and sample SIGUNGU_AVG payload.
• Tests
  • Expanded and adjusted map viewport controller assertions for the updated SIGUNGU_AVG response payload.

[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 8:02am

[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: dc594dda-803b-44c1-94ea-7ab5724399ee

📥 Commits

Reviewing files that changed from the base of the PR and between 8782011 and 9001cab.

📒 Files selected for processing (1)

• docs/08_API_SPEC.md

✅ Files skipped from review due to trivial changes (1)

• docs/08_API_SPEC.md

---

📝 Walkthrough

Walkthrough

Adds a SIGUNGU-specific viewport aggregation path in JdbcPropertyDao, updates the wide-zoom controller test to match the new response values, and refreshes the API spec and Phase 5 QA/status documents.

Changes

SIGUNGU viewport aggregation

Layer / File(s)	Summary
SIGUNGU aggregation DAO implementation backend/src/main/java/com/ssafy/salmanhae/model/dao/property/JdbcPropertyDao.java	Adds an early return in findRegionAverageViewportItems for regionLevel == "SIGUNGU" and introduces a helper that aggregates visible properties by sido and sigungu, computes average metrics, counts transactions, and orders results.
Controller test assertions updated backend/src/test/java/com/ssafy/salmanhae/controller/map/MapViewportControllerTest.java	Expands getViewportIsPublicAndReturnsSigunguModeAtWideZoom to validate response metadata and aggregate fields, and updates the expected avgDeposit and transactionCount values.
API spec and Phase 5 QA artifacts docs/08_API_SPEC.md, phases/map-viewport-zoom/phase5-qa-docs-deploy.md, phases/map-viewport-zoom/phase5.status.json, phases/map-viewport-zoom/qa-report-phase5.md	Updates the SIGUNGU_AVG and DONG_AVG API descriptions, marks Phase 5 checklist items complete, adds QA notes and report details, and records the phase as completed.

Sequence Diagram(s)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• ssafy-salman/salmanhae#54: Introduced the MapViewportControllerTest wide-zoom assertions that this PR expands and updates.
• ssafy-salman/salmanhae#56: Added the earlier region-average DAO logic that this PR extends with a SIGUNGU-specific aggregation path.

Suggested labels

ai-generated

🐇 Hop hop, the viewport is light,
SIGUNGU averages now read just right.
By sido and sigungu, the values align,
With tests and docs updated in line.

🚥 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
Title check	✅ Passed	The title clearly summarizes the main change: stabilizing broad-zoom sigungu aggregation in the map flow.
Description check	✅ Passed	It covers the change summary, linked issue, and verification steps, though it doesn't follow the template headings exactly.
Linked Issues check	✅ Passed	The changes address #61 by fixing broad SIGUNGU_AVG aggregation, updating docs, recording phase status, and using existing CI/CD paths.
Out of Scope Changes check	✅ Passed	The added docs and phase files align with the linked issue's documentation and deployment-recording requirements.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch phase/5-qa-docs-deploy

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: 1

🤖 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 171-172: The API spec example is out of sync with the updated
SIGUNGU_AVG behavior: the prose now says it is aggregated from visible
properties in the current bounds, but the example request/response still
reflects the old precomputed-style payload and mismatched zoom behavior. Update
the example block in docs/08_API_SPEC.md to match the current SIGUNGU_AVG
semantics, using the same request parameters and response shape shown by the
implementation, and ensure the example no longer contradicts the description
near SIGUNGU_AVG and DONG_AVG.

🪄 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: 973eb34a-c7bd-4179-8ceb-e8145c6aecdb

📥 Commits

Reviewing files that changed from the base of the PR and between fc0994f and 8782011.

📒 Files selected for processing (6)

• backend/src/main/java/com/ssafy/salmanhae/model/dao/property/JdbcPropertyDao.java
• backend/src/test/java/com/ssafy/salmanhae/controller/map/MapViewportControllerTest.java
• docs/08_API_SPEC.md
• phases/map-viewport-zoom/phase5-qa-docs-deploy.md
• phases/map-viewport-zoom/phase5.status.json
• phases/map-viewport-zoom/qa-report-phase5.md