[FEAT] recommendation controller

[rkdms6767]

📌 작업 내용 및 특이사항

• RecommendationValidator (STEP5 출력 자체 검증): ValidationIssue(code/message/path), ValidationOutcome(valid/issues) 타입 추가 + recommendedCandidateId·alternativeCandidateIds·excludedCandidates·recommendationReasons·confidence 정합성 검증 로직 구현

• RecommendationController: /api/v1/candidate-filters, /api/v1/recommendations, /api/v1/recommendation-output-validations 3개 API 구현 (요청/응답 DTO 4개 포함)

• candidateFilterResult를 클라이언트가 보낸 그대로 믿고, environmentId도 안 쓰여서 다른 환경 결과를 재사용하는 것도 막을 방법이 없었다.→ 서버가 environmentId+sessionContext로 직접 다시 계산하도록 고침 fix: recommendations API가 클라이언트의 candidateFilterResult를 신뢰하지 않고 서버에서 재계산하도록 수정

• fix: RecommendationValidator가 제외된 추천 후보·중복 대안 후보를 검증하지 못하던 문제 수정

📚 기타

• @PostMapping("/candidate-filters") 프론트용 (필요한지 화면구성 회의 때)

Summary by CodeRabbit

• 새 기능
  • 추천 후보 필터링, 추천 생성, 추천 결과 검증을 위한 내부 API를 추가했습니다.
  • 추천 요청과 검증 결과를 표준화된 형식으로 제공합니다.
  • 추천 후보의 존재 여부, 판매 가능 여부, 중복 및 제외 상태를 검증합니다.
  • 추천 사유와 신뢰도 범위 등 추천 데이터의 유효성을 확인합니다.
  • 검증 결과에 유효성, 실행 계획 준비 여부, 오류 및 경고 목록을 포함합니다.

[coderabbitai]

Walkthrough

추천 모듈에 검증 계약과 RecommendationValidator를 추가했다. 후보 필터링, 추천 생성, 추천 결과 검증을 /api/v1 API로 제공한다. 추천 생성 요청에서는 후보 필터 결과를 서버가 재계산한다.

Changes

추천 검증 및 API

Layer / File(s)	Summary
검증 계약과 요청 DTO backend/src/main/java/com/kiobridge/kiobridge/modules/recommendation/ValidationIssue.java, ValidationOutcome.java, controller/dto/*	검증 이슈와 결과, 후보 필터링·추천·추천 검증 요청과 응답을 레코드로 추가한다. 필수 값과 목록의 null을 검증한다. RecommendationRequest에서 candidateFilterResult를 제거한다.
추천 결과 검증 backend/src/main/java/com/kiobridge/kiobridge/modules/recommendation/RecommendationValidator.java	추천 후보와 대안 후보의 존재 여부, 판매 가능 여부, 중복, 제외 상태를 검증한다. 제외 후보 식별 여부, 추천 사유, confidence 범위를 검사한다.
추천 모듈 API 연결 backend/src/main/java/com/kiobridge/kiobridge/modules/recommendation/controller/RecommendationController.java	POST /candidate-filters, POST /recommendations, POST /recommendation-output-validations 엔드포인트를 추가한다. fixture 조회와 후보 필터, 추천 엔진, 검증기 호출을 연결한다. 추천 생성 전에 후보 필터 결과를 서버에서 재계산한다.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant RecommendationController
  participant SimulationApiClient
  participant CandidateFilterService
  participant RecommendationEngineService
  participant RecommendationValidator
  Client->>RecommendationController: POST /recommendations
  RecommendationController->>SimulationApiClient: 환경 fixture와 호환성 규칙 조회
  SimulationApiClient-->>RecommendationController: 후보와 규칙 반환
  RecommendationController->>CandidateFilterService: 후보 필터 결과 계산
  CandidateFilterService-->>RecommendationController: CandidateFilterResult 반환
  RecommendationController->>RecommendationEngineService: 프로필과 필터 결과로 추천 생성
  RecommendationEngineService-->>RecommendationController: Recommendation 반환
  Client->>RecommendationController: POST /recommendation-output-validations
  RecommendationController->>SimulationApiClient: 전체 후보 조회
  SimulationApiClient-->>RecommendationController: 전체 후보 목록 반환
  RecommendationController->>RecommendationValidator: Recommendation과 후보 목록 검증
  RecommendationValidator-->>RecommendationController: ValidationOutcome 반환
  RecommendationController-->>Client: RecommendationValidationResponse 반환

Loading

Possibly related PRs

• watTHEBUG/kioBridge#21: Recommendation, Candidate, ExcludedCandidate 계약을 검증 로직과 API가 사용한다.
• watTHEBUG/kioBridge#37: CandidateFilterResult와 후보 필터링 결과를 추천 생성 흐름이 사용한다.
• watTHEBUG/kioBridge#39: RecommendationEngineService가 생성한 Recommendation을 이 PR의 검증기가 검증한다.

🚥 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
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 주요 변경 사항인 RecommendationController 기능 추가를 명확하고 간결하게 설명합니다.

✨ 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/recommendation-controller

---

_{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/kiobridge/kiobridge/modules/recommendation/controller/RecommendationController.java`:
- Around line 52-62: Update RecommendationController.recommend so it does not
trust or pass request.candidateFilterResult() directly to
recommendationEngineService. Recompute the candidate filter result on the server
using the request’s environmentId and sessionContext, or validate a
server-issued opaque/signed result bound to both environment and session before
invoking the recommendation engine.

In
`@backend/src/main/java/com/kiobridge/kiobridge/modules/recommendation/RecommendationValidator.java`:
- Around line 53-54: Update the recommendation validation flow so
validateRecommendedCandidate also receives excludedCandidateIds, and make it
report a validation issue at /recommendation/recommendedCandidateId when the
recommended candidate is excluded. Preserve the existing alternative-candidate
validation behavior and issue handling.
- Around line 106-111: Update the alternative-candidate validation flow around
alternativeCandidateIds and validateAlternativeCandidate to track IDs already
encountered. When a later entry repeats an earlier ID, return a validation issue
for that entry using its array-index path instead of validating it as a new
candidate; preserve the existing validation behavior for unique IDs.

🪄 Autofix

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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 1f1583cf-1e44-447f-96ab-41a752f8ae0b

📥 Commits

Reviewing files that changed from the base of the PR and between 753d957 and 780de60.

📒 Files selected for processing (8)

• backend/src/main/java/com/kiobridge/kiobridge/modules/recommendation/RecommendationValidator.java
• backend/src/main/java/com/kiobridge/kiobridge/modules/recommendation/ValidationIssue.java
• backend/src/main/java/com/kiobridge/kiobridge/modules/recommendation/ValidationOutcome.java
• backend/src/main/java/com/kiobridge/kiobridge/modules/recommendation/controller/RecommendationController.java
• backend/src/main/java/com/kiobridge/kiobridge/modules/recommendation/controller/dto/CandidateFilterRequest.java
• backend/src/main/java/com/kiobridge/kiobridge/modules/recommendation/controller/dto/RecommendationRequest.java
• backend/src/main/java/com/kiobridge/kiobridge/modules/recommendation/controller/dto/RecommendationValidationRequest.java
• backend/src/main/java/com/kiobridge/kiobridge/modules/recommendation/controller/dto/RecommendationValidationResponse.java