Feat(#101): 분석 결과 증거 카드 저장 및 raw score 노출

[LATE-BL00MER]

📋 작업 내용

• RabbitMQ AnalysisResultPayload 최상위에 optional evidenceCards 필드를 추가했습니다.
• 증거 카드 계약을 category, title, description 구조로 정의했습니다.
• 증거 카드를 분석 결과와 함께 보관하도록 AnalysisEvidenceCard 엔티티와 detection_evidence_cards 테이블을 추가했습니다.
• 저장된 증거 카드를 분석 상세 REST 응답의 evidenceCards로 노출했습니다.
• 분석 출처별 점수는 weightedContributions가 아닌 rawScores를 사용하도록 변경했습니다.
  • textScore: 문자 문맥 분석 원점수
  • urlScore: URL 분석 원점수
  • rulesScore: 금융 규칙 분석 원점수
• 기존 저장 데이터에 raw score가 없으면 기존 점수를 사용하는 하위 호환 처리를 추가했습니다.
• evidenceCards가 누락된 구버전 RabbitMQ 이벤트도 정상적으로 처리합니다.
• 증거 카드는 최대 5개까지 허용하며 필수값과 문자열 길이를 검증합니다.
• 기존 Indicator와 증거 카드가 섞이지 않도록 증거 카드를 별도 엔티티로 분리했습니다.

연동 및 배포 참고

• Spring이 evidenceCards를 먼저 수신할 수 있도록 본 PR을 먼저 반영합니다.
• Spring 반영 이후 AI에서 RabbitMQ 결과 이벤트에 evidenceCards 매핑을 추가하면 됩니다.
• 프론트 분석 상세 응답의 scoreBreakdown 필드가 다음과 같이 변경됩니다.
  • llmScore → textScore
  • patternScore → rulesScore
  • urlScore는 유지

🧪 테스트 결과

• ✅ ./gradlew.bat test
• ✅ 전체 테스트 통과
• ✅ RabbitMQ evidenceCards 역직렬화 검증
• ✅ 증거 카드 저장 및 REST 응답 매핑 검증
• ✅ rawScores 응답 매핑 검증
• ✅ evidenceCards가 없는 기존 이벤트 하위 호환 검증
• ✅ 기존 저장 데이터의 점수 대체 처리 검증
• ✅ Flyway V21 마이그레이션 검증

🔗 관련 이슈

Closes #101

Refs SafeFam/SafeFam_AI#64

✅ 체크리스트

• 관련 이슈를 연결했습니다.
• 구현 범위와 변경 이유를 설명했습니다.
• 로컬 테스트를 통과했습니다.
• API 변경 사항을 Swagger에 반영했습니다.
• DB 변경 사항과 마이그레이션을 포함했습니다.
• 민감 정보가 코드·로그·테스트 데이터에 포함되지 않았습니다.
• 프론트엔드에 영향을 주는 응답 스키마 또는 Enum 변경을 공유했습니다.
• 병합 전 작업 브랜치를 삭제하지 않았습니다.

Summary by CodeRabbit

• New Features
  • Analysis results now include up to five evidence cards with categories, titles, and descriptions.
  • Score breakdowns now distinguish text-based and rules-based scores, alongside URL scores.
  • Evidence cards are retained with analysis results and displayed in responses.
• Validation
  • Evidence cards require valid text fields and are rejected for failed analyses.
• Compatibility
  • Results without evidence cards remain supported.

[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: 55c7ded7-c31d-4da1-b692-084b1e2779c5

📥 Commits

Reviewing files that changed from the base of the PR and between f815c8e and 6ec4ee0.

📒 Files selected for processing (13)

• src/main/java/com/gold/safefam/domain/analysis/dto/AnalysisResponse.java
• src/main/java/com/gold/safefam/domain/analysis/entity/Analysis.java
• src/main/java/com/gold/safefam/domain/analysis/entity/AnalysisEvidenceCard.java
• src/main/java/com/gold/safefam/domain/analysis/mapper/AnalysisResponseMapper.java
• src/main/java/com/gold/safefam/domain/analysis/messaging/event/AnalysisResultEvent.java
• src/main/java/com/gold/safefam/domain/analysis/service/AnalysisResultApplyService.java
• src/main/java/com/gold/safefam/domain/analysis/service/AnalysisResultValidator.java
• src/main/resources/db/migration/V21__create_detection_evidence_cards.sql
• src/test/java/com/gold/safefam/domain/analysis/mapper/AnalysisResponseMapperTest.java
• src/test/java/com/gold/safefam/domain/analysis/service/AnalysisResultApplyMappingTest.java
• src/test/java/com/gold/safefam/domain/analysis/service/AnalysisResultValidatorTest.java
• src/test/java/com/gold/safefam/infrastructure/messaging/rabbitmq/consumer/AnalysisResultConsumerTest.java
• src/test/java/com/gold/safefam/support/AnalysisResultEventFixture.java

---

📝 Walkthrough

Walkthrough

Changes

The analysis result event now accepts structured evidence cards. The validator checks card count and text limits. Valid cards are persisted with analyses and returned by the response mapper. Score breakdowns expose raw text, URL, and rules scores with legacy fallbacks.

Analysis evidence cards

Layer / File(s)	Summary
Evidence card and score contracts src/main/java/com/gold/safefam/domain/analysis/dto/AnalysisResponse.java, src/main/java/com/gold/safefam/domain/analysis/messaging/event/AnalysisResultEvent.java	The event payload and response DTO define evidence cards. ScoreBreakdown uses text, URL, and rules score fields.
Validation and persistence flow src/main/java/com/gold/safefam/domain/analysis/service/AnalysisResultValidator.java, src/main/java/com/gold/safefam/domain/analysis/service/AnalysisResultApplyService.java, src/main/java/com/gold/safefam/domain/analysis/entity/Analysis.java, src/main/java/com/gold/safefam/domain/analysis/entity/AnalysisEvidenceCard.java, src/main/resources/db/migration/V21__create_detection_evidence_cards.sql, src/test/java/com/gold/safefam/domain/analysis/service/*, src/test/java/com/gold/safefam/infrastructure/messaging/rabbitmq/consumer/AnalysisResultConsumerTest.java, src/test/java/com/gold/safefam/support/AnalysisResultEventFixture.java	Successful payloads validate and persist up to five evidence cards. Failed payloads reject non-empty cards. Legacy null card lists remain valid.
Response mapping and score fallback src/main/java/com/gold/safefam/domain/analysis/mapper/AnalysisResponseMapper.java, src/test/java/com/gold/safefam/domain/analysis/mapper/AnalysisResponseMapperTest.java	The mapper returns evidence cards and prefers raw scores, falling back to legacy values when raw scores are unavailable.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 6ec4e

The change adds optional evidence-card storage and response fields while exposing raw score components with backward compatibility; no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant AnalysisResultEvent
  participant AnalysisResultValidator
  participant AnalysisResultApplyService
  participant Analysis
  participant AnalysisResponseMapper
  AnalysisResultEvent->>AnalysisResultValidator: validate evidence cards and scores
  AnalysisResultValidator-->>AnalysisResultApplyService: accept valid result
  AnalysisResultApplyService->>Analysis: attach evidence cards
  AnalysisResponseMapper->>Analysis: read cards and scores
  AnalysisResponseMapper-->>AnalysisResultEvent: return AnalysisResponse

Loading

Possibly related issues

• SafeFam/SafeFam_AI#64 — Defines the evidence-card payload and raw-score changes implemented by this PR.

Possibly related PRs

• SafeFam/SafeFam_BE#48 — Introduced analysis result persistence and response mapping that this PR extends.
• SafeFam/SafeFam_BE#67 — Established the analysis result messaging flow extended with evidence cards.
• SafeFam/SafeFam_BE#68 — Directly relates to evidence-card validation, mapping, and persistence in the analysis result flow.

Suggested reviewers: pearseona

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The implementation covers evidence cards, persistence, response mapping, raw-score fallback, and legacy events, but no Swagger update is shown.	Add or verify the Swagger schema for evidenceCards and the textScore, urlScore, and rulesScore response fields.
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.78% 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the two primary changes: storing analysis evidence cards and exposing raw scores.
Out of Scope Changes check	✅ Passed	All listed production and test changes support evidence-card persistence, raw-score exposure, compatibility, or validation; no unrelated scope is evident.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/64-evidence-cards

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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