fix(property): 검색 조건 지역 집계 반영

[HOKAGO-MEMORIES]

변경 내용

• 지도 viewport API와 기존 매물 조회 API에 keyword 검색 조건을 추가했습니다.
• 지역 집계, 클러스터, 상세 매물이 같은 검색/필터 조건을 공유하도록 DAO 공통 필터를 정리했습니다.
• 검색/필터 조건이 활성화된 상태에서는 지역 마커가 대표 가격 대신 조건에 맞는 매물 수를 표시하도록 변경했습니다.
• 검색 결과가 없을 때 지역 마커도 사라지는 케이스를 테스트로 보강했습니다.
• docs/08_API_SPEC.md에 keyword 파라미터와 지역 집계 동작을 반영했습니다.

테스트

• cmd /c npm test
• cmd /c npm run build
• ./mvnw -q -Dtest=MapViewportControllerTest,PropertyControllerTest test
• ./mvnw -q test

closes #94

Summary by CodeRabbit

• New Features
  • Added optional keyword search to map viewport and property listing endpoints.
  • Region markers can display matching listing counts when search conditions are active.
• Bug Fixes
  • Improved keyword matching to search across title, building name, and address fields reliably, treating % and _ as literal text.
• Documentation
  • Updated API spec to document the new keyword parameter and related map display behavior.
• Tests
  • Added/updated backend and frontend tests to cover keyword filtering and label/count rendering.

[vercel]

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

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

[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: df2549f6-338b-4506-b9e6-be71b9b775ba

📥 Commits

Reviewing files that changed from the base of the PR and between ad3de24 and 6cb0c85.

📒 Files selected for processing (5)

• backend/src/main/java/com/ssafy/salmanhae/model/dao/property/JdbcPropertyDao.java
• backend/src/test/java/com/ssafy/salmanhae/controller/property/PropertyControllerTest.java
• docs/08_API_SPEC.md
• frontend/src/store/mapStore.js
• frontend/src/store/mapStore.test.mjs

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

• frontend/src/store/mapStore.test.mjs

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

• backend/src/test/java/com/ssafy/salmanhae/controller/property/PropertyControllerTest.java
• docs/08_API_SPEC.md
• backend/src/main/java/com/ssafy/salmanhae/model/dao/property/JdbcPropertyDao.java
• frontend/src/store/mapStore.js

---

📝 Walkthrough

Walkthrough

Adds optional keyword filters to backend property and viewport searches, threads the keyword through the frontend viewport request path, and changes region markers to show matching listing counts when search conditions are active. Updates tests and API docs.

Changes

Keyword search and region marker counts

Layer / File(s)	Summary
Search criteria and controller wiring backend/src/main/java/com/ssafy/salmanhae/model/dto/property/PropertySearchCriteria.java, backend/src/main/java/com/ssafy/salmanhae/controller/map/MapViewportController.java, backend/src/main/java/com/ssafy/salmanhae/controller/property/PropertyController.java	The search criteria record adds keyword plus keyword helper methods, and both controllers accept and pass the optional keyword into criteria construction.
DAO keyword filtering backend/src/main/java/com/ssafy/salmanhae/model/dao/property/JdbcPropertyDao.java	findInBounds routes criteria predicates through appendPropertyFilters, which now adds a case-insensitive keyword match across title, building name, address, and road address.
Viewport search state and request frontend/src/store/mapStore.js, frontend/src/api/properties.test.mjs	The map store forwards searchKeyword in viewport requests, broadens local keyword matching across property fields, and adds an active-search getter; the API test now expects the keyword param.
Region marker count display frontend/src/utils/mapViewport.js, frontend/src/views/MapExplorer.vue, frontend/src/utils/mapViewport.test.mjs	Region-average marker labels can render transaction counts, and the map view passes that mode when search conditions are active; the utility test covers the count label output.
Tests and API spec backend/src/test/java/com/ssafy/salmanhae/controller/map/MapViewportControllerTest.java, backend/src/test/java/com/ssafy/salmanhae/controller/property/PropertyControllerTest.java, docs/08_API_SPEC.md	Backend controller tests and the API spec are updated for the new keyword query parameter and the region-aggregate search/count behavior.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• ssafy-salman/salmanhae#54 — Introduced MapViewportController#getViewport and the viewport API shape extended by this PR.
• ssafy-salman/salmanhae#56 — Added the shared JdbcPropertyDao criteria/filter construction that this PR extends with keyword matching.
• ssafy-salman/salmanhae#60 — Added the viewport marker label utility that now renders counts based on active search conditions.

Poem

I hopped across the viewport map,
With keyword crumbs and a happy clap.
When search winds blow, the markers count,
And matching homes all hop to mount.
🐰✨

🚥 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	제목이 지도 검색 조건의 지역 집계 반영이라는 핵심 변경을 간결하게 잘 요약합니다.
Description check	✅ Passed	변경 내용, 테스트, closes #94를 포함해 템플릿 핵심 항목을 대부분 갖췄습니다.
Linked Issues check	✅ Passed	keyword 추가, 공통 DAO 필터, 지역 마커 count 표시, 무결과 테스트, 문서 반영이 모두 #94 요구를 충족합니다.
Out of Scope Changes check	✅ Passed	요구사항과 무관한 변경은 보이지 않으며, 테스트·문서·연관 UI/서버 수정이 모두 목적과 일치합니다.

_{✏️ 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 codex/fix-f1-map-search-regions

---

_{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
`@backend/src/main/java/com/ssafy/salmanhae/model/dao/property/JdbcPropertyDao.java`:
- Around line 659-669: The keyword search in JdbcPropertyDao currently binds
user input directly into LIKE, so % and _ are treated as wildcards instead of
literal characters. Update the keywordPattern handling in the hasKeyword block
to escape SQL wildcard characters before putting the value into params, and add
an ESCAPE clause to the LIKE predicates so plain-text searches work correctly
for literal inputs like 100% or _동.

In `@docs/08_API_SPEC.md`:
- Line 107: The API spec entry for keyword is incomplete and does not match the
actual search contract. Update the documentation in the API spec around the
keyword field so it reflects all supported search targets exposed by the
implementation, including title and road_address in addition to building
name/address; make the description consistent wherever keyword is documented.

In `@frontend/src/store/mapStore.js`:
- Line 163: The viewport request in fetchViewport is still sending the raw
searchKeyword even though filteredProperties and hasActiveSearchConditions treat
whitespace-only input as empty. Update fetchViewport in mapStore to trim this
value before building the request payload, and make sure the keyword field uses
the normalized search keyword consistently with the existing search-state
checks.

🪄 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: e2ceef47-6866-4431-ba2a-ed63af34072b

📥 Commits

Reviewing files that changed from the base of the PR and between 89fa876 and ad3de24.

📒 Files selected for processing (12)

• backend/src/main/java/com/ssafy/salmanhae/controller/map/MapViewportController.java
• backend/src/main/java/com/ssafy/salmanhae/controller/property/PropertyController.java
• backend/src/main/java/com/ssafy/salmanhae/model/dao/property/JdbcPropertyDao.java
• backend/src/main/java/com/ssafy/salmanhae/model/dto/property/PropertySearchCriteria.java
• backend/src/test/java/com/ssafy/salmanhae/controller/map/MapViewportControllerTest.java
• backend/src/test/java/com/ssafy/salmanhae/controller/property/PropertyControllerTest.java
• docs/08_API_SPEC.md
• frontend/src/api/properties.test.mjs
• frontend/src/store/mapStore.js
• frontend/src/utils/mapViewport.js
• frontend/src/utils/mapViewport.test.mjs
• frontend/src/views/MapExplorer.vue