[Phase 6] test(ai): 안전 분석 경로 검증 및 문서화

[HOKAGO-MEMORIES]

변경 내용

• backend-ai SAFETY_ANALYSIS가 Spring Boot safety-summary의 사전 계산 안전 점수와 시설 개수를 카드/답변에 명확히 노출하도록 검증을 추가했습니다.
• 깨진 안전/분석 응답 문구를 정상 한국어로 정리하고, intent 기반 단위 테스트도 workers_called 없이 동작하도록 호환성을 보강했습니다.
• pgvector 세션 설정 SQL을 파라미터 바인딩 형태로 맞춰 기존 테스트 호환성을 회복했습니다.
• F-4 안전시설 수집, 안전 점수 계산, backend-ai 연동 흐름을 운영 문서와 API/도메인/로드맵 문서에 정리했습니다.

연결 이슈

• Closes [FEAT][F-4] 안전 분석 경로 검증 및 문서 정리 #78

테스트 체크리스트

• C:\Users\Linear\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe -m pytest tests --basetemp ..\.tmp\pytest3 -p no:cacheprovider
• ./mvnw.cmd test

리뷰 포인트

• 유저 요청 시점에는 public safety API를 호출하지 않고 Spring safety-summary와 DB precomputed rows만 사용하는 계약을 테스트/문서로 고정했습니다.
• backend-ai 테스트는 샌드박스 임시 폴더 권한 문제 때문에 권한 있는 실행에서 검증했습니다.

Summary by CodeRabbit

• New Features

  • Enhanced safety analysis responses with clearer safety-score details and nearby facility information.
  • Polished price analysis wording to use more natural “recent transactions” phrasing.

• Bug Fixes

  • Improved analysis routing to correctly select workers when an intent is available but no workers were initially chosen.
  • Strengthened user-facing fallback messages when required property/analysis data is missing.
  • Updated safety result labels and answer phrasing for better clarity (e.g., “경찰시설” wording).

[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 5:29pm

[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: d821c5ea-edfe-4856-8049-fcafcd049304

📥 Commits

Reviewing files that changed from the base of the PR and between 428f37e and 2c4a47f.

📒 Files selected for processing (2)

• backend-ai/app/clients/llm_client.py
• backend-ai/tests/test_analysis_answer_generation.py

---

📝 Walkthrough

Walkthrough

Adds intent-driven worker fallback, updates safety and price analysis wording, parameterizes Supabase session settings, expands safety analysis tests, and documents the F-4 safety batch and API flow.

Changes

F-4 Safety Analysis Feature, Fixes, and Documentation

Layer / File(s)	Summary
Intent enum and AgentState.intent field backend-ai/app/graph/state.py	Adds Intent as a StrEnum and extends AgentState with an optional intent field.
LLM routing fallback from state intent backend-ai/app/clients/llm_client.py	In LLMClient.generate_answer, derives workers_called from state["intent"] when the list is empty and accepts only renderable worker identifiers.
Korean output wording corrections backend-ai/app/clients/spring_client.py, backend-ai/app/services/analysis_answer_service.py	Changes price-analysis and safety-analysis output strings to use the updated Korean phrasing in the Spring client and answer service.
Parameterized SQL session settings backend-ai/app/clients/supabase_client.py	Replaces inline SET LOCAL SQL strings with parameterized cursor.execute calls in the Supabase vector client.
Safety analysis and output tests backend-ai/tests/test_safety_analysis.py, backend-ai/tests/test_agent_chat.py, backend-ai/tests/test_analysis_answer_generation.py, backend-ai/tests/test_spring_client.py	Adds safety analysis graph tests, updates price and safety answer expectations, and tightens Spring client assertions to exact returned summaries.
F-4 safety documentation additions docs/06_EXTERNAL_APIS.md, docs/07_DOMAIN_MODEL.md, docs/08_API_SPEC.md, docs/09_BATCH_INGESTION.md, docs/11_ROADMAP.md	Adds F-4 safety API operations, stored model, analysis contract, batch runbook, and roadmap status sections.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• ssafy-salman/salmanhae#42: Both PRs modify backend-ai/app/graph/state.py with the Intent enum and extend intent-based routing in LLMClient.generate_answer.
• ssafy-salman/salmanhae#63: That PR modified LLMClient.generate_answer worker routing; this PR adds a backward-compatible fallback deriving workers_called from state["intent"] when missing.
• ssafy-salman/salmanhae#21: Both PRs touch backend-ai/app/clients/supabase_client.py in the pgvector search path, with overlapping changes to SET LOCAL session timeout handling.

Suggested labels

ai-generated

🐇 I twitched my nose and read the trail,
거래 now sings where 실거래 went pale.
Safety comes from stored-up lore,
And intent picks workers at the door. 🌙

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 5.88% 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 is concise and accurately summarizes the main change: safety-analysis validation and documentation for Phase 6.
Description check	✅ Passed	The description matches the template sections and includes the change summary, linked issue, tests, and review points.
Linked Issues check	✅ Passed	The changes add SAFETY_ANALYSIS safety-summary tests, fallback wording checks, and F-4 docs/roadmap updates required by #78.
Out of Scope Changes check	✅ Passed	No clear unrelated changes stand out; the intent and SQL updates support the described tests and backend-ai integration.

_{✏️ 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/6-f4-safety-analysis-docs-verification

---

_{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 `@backend-ai/app/clients/llm_client.py`:
- Around line 182-184: The intent hydration in generate_answer() is promoting
HUG_CALC into workers_called, but the method still lacks a dedicated HUG_CALC
handling branch and falls back to the generic response. Update the routing in
llm_client.py so generate_answer() recognizes HUG_CALC as a valid task path and
returns the appropriate task-specific answer instead of the generic “질문 의도를…”
fallback; if intent hydration is meant only for renderable intents, add a guard
around the workers_called assignment to exclude HUG_CALC.

🪄 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: 074a5a1b-f498-4c37-99a9-020f87e61cc6

📥 Commits

Reviewing files that changed from the base of the PR and between 6d55e7c and 428f37e.

📒 Files selected for processing (14)

• backend-ai/app/clients/llm_client.py
• backend-ai/app/clients/spring_client.py
• backend-ai/app/clients/supabase_client.py
• backend-ai/app/graph/state.py
• backend-ai/app/services/analysis_answer_service.py
• backend-ai/tests/test_agent_chat.py
• backend-ai/tests/test_analysis_answer_generation.py
• backend-ai/tests/test_safety_analysis.py
• backend-ai/tests/test_spring_client.py
• docs/06_EXTERNAL_APIS.md
• docs/07_DOMAIN_MODEL.md
• docs/08_API_SPEC.md
• docs/09_BATCH_INGESTION.md
• docs/11_ROADMAP.md