Merge pull request #113 from Team-StackUp/feature/multi-agent-feedback-panel

feat: 멀티 면접관 패널 — 평가위원별 분해 저장·표시 (Phase 2A)

Author: i3months

ai/src/ai_server/chain/feedback_generation_chain.py

@@ -14,6 +14,7 @@
 from ai_server.chain.prompts import feedback_panel
 from ai_server.config.settings import Settings
 from ai_server.core.client import CoreClient
+from ai_server.model.messages.feedback import PanelBreakdownItem
 from ai_server.observability.llm_logging_callback import CoreAiLogCallback
 
 log = structlog.get_logger(__name__)
@@ -27,6 +28,7 @@ class FeedbackResult(BaseModel):
     strengths_summary: str | None = Field(None)
     weaknesses_summary: str | None = Field(None)
     improvement_keywords: list[str] = Field(default_factory=list)
+    panel_breakdown: list[PanelBreakdownItem] = Field(default_factory=list)
 
 
 class FeedbackGenerator(Protocol):
@@ -320,6 +322,17 @@ async def generate(
         )
         keywords = _dedup_keywords(tech.keywords + logic.keywords + comm.keywords)
 
+        breakdown = [
+            PanelBreakdownItem(
+                evaluator=spec.label,
+                dimension=spec.dimension_name,
+                score=res.score,
+                strength=res.strength,
+                weakness=res.weakness,
+            )
+            for spec, res in zip(specs, (tech, logic, comm))
+        ]
+
         return FeedbackResult(
             overall_score=overall,
             technical_accuracy=tech.score,
@@ -328,4 +341,5 @@ async def generate(
             strengths_summary=strengths,
             weaknesses_summary=weaknesses,
             improvement_keywords=keywords,
+            panel_breakdown=breakdown,
         )

ai/src/ai_server/messaging/consumers/feedback_consumer.py

@@ -108,6 +108,7 @@ async def handle(self, message: AbstractIncomingMessage) -> None:
                 strengths_summary=result.strengths_summary,
                 weaknesses_summary=result.weaknesses_summary,
                 improvement_keywords=result.improvement_keywords,
+                panel_breakdown=result.panel_breakdown,
                 report_s3_key=None,
             )
 

ai/src/ai_server/model/messages/feedback.py

@@ -62,6 +62,18 @@ class GenerateFeedbackRequest(BaseModel):
     voice_analysis_summary: VoiceAnalysisSummary | None = None
 
 
+class PanelBreakdownItem(BaseModel):
+    """멀티 면접관 패널의 평가위원 1명 결과(분해 표시·저장용)."""
+
+    model_config = camel_config()
+
+    evaluator: str  # 라벨: 기술/인성/논리/전달
+    dimension: str  # 평가축 이름
+    score: float | None = None
+    strength: str | None = None
+    weakness: str | None = None
+
+
 class FeedbackCallbackPayload(BaseModel):
     """AI → Core 종합 피드백. 점수는 0~100 (NULL 허용)."""
 
@@ -75,4 +87,6 @@ class FeedbackCallbackPayload(BaseModel):
     strengths_summary: str | None = None
     weaknesses_summary: str | None = None
     improvement_keywords: list[str] = Field(default_factory=list)
+    # 평가위원별 분해(패널). 비어 있으면 단일/레거시 경로.
+    panel_breakdown: list[PanelBreakdownItem] = Field(default_factory=list)
     report_s3_key: str | None = None

ai/tests/test_feedback_panel.py

@@ -53,6 +53,9 @@ async def test_weighted_overall_and_dimension_mapping():
     assert r.overall_score == 65
     assert "[기술]" in r.strengths_summary and "[논리]" in r.strengths_summary
     assert set(r.improvement_keywords) == {"JPA", "trade-off", "STAR"}
+    # 평가위원별 분해
+    assert [b.evaluator for b in r.panel_breakdown] == ["기술", "논리", "전달"]
+    assert [b.score for b in r.panel_breakdown] == [80, 60, 40]
 
 
 @pytest.mark.asyncio

backend/openapi.json

@@ -3341,6 +3341,13 @@
               "type" : "string"
             }
           },
+          "panelBreakdown" : {
+            "type" : "array",
+            "description" : "Per-evaluator panel breakdown (multi-interviewer). Empty for single/legacy feedback.",
+            "items" : {
+              "$ref" : "#/components/schemas/PanelBreakdownItem"
+            }
+          },
           "reportFilePath" : {
             "type" : "string",
             "description" : "Stored report path when AI generates a detailed learning guide/report."
@@ -3351,6 +3358,27 @@
           }
         }
       },
+      "PanelBreakdownItem" : {
+        "type" : "object",
+        "properties" : {
+          "evaluator" : {
+            "type" : "string"
+          },
+          "dimension" : {
+            "type" : "string"
+          },
+          "score" : {
+            "type" : "number",
+            "format" : "double"
+          },
+          "strength" : {
+            "type" : "string"
+          },
+          "weakness" : {
+            "type" : "string"
+          }
+        }
+      },
       "CandidateRepositoryResponse" : {
         "type" : "object",
         "properties" : {

backend/src/main/java/com/stackup/stackup/session/application/FeedbackCallbackService.java

@@ -75,6 +75,7 @@ public void apply(FeedbackCallbackEnvelope envelope) {
             payload.strengthsSummary(),
             payload.weaknessesSummary(),
             keywordsToJson(payload.improvementKeywords()),
+            breakdownToJson(payload.panelBreakdown()),
             payload.reportS3Key()
         );
         try {
@@ -109,6 +110,19 @@ private String keywordsToJson(java.util.List<String> keywords) {
         }
     }
 
+    private String breakdownToJson(
+            java.util.List<com.stackup.stackup.session.application.dto.PanelBreakdownItem> breakdown) {
+        if (breakdown == null || breakdown.isEmpty()) {
+            return null;
+        }
+        try {
+            return JSON.writeValueAsString(breakdown);
+        } catch (JsonProcessingException e) {
+            log.warn("panel_breakdown json serialize failed", e);
+            return null;
+        }
+    }
+
     private boolean isProcessed(String messageId) {
         if (messageId == null || messageId.isBlank()) {
             return false;

backend/src/main/java/com/stackup/stackup/session/application/dto/FeedbackCallbackPayload.java

@@ -14,6 +14,7 @@ public record FeedbackCallbackPayload(
     String strengthsSummary,
     String weaknessesSummary,
     List<String> improvementKeywords,
+    List<PanelBreakdownItem> panelBreakdown,
     String reportS3Key
 ) {
 }

backend/src/main/java/com/stackup/stackup/session/application/dto/FeedbackResult.java

@@ -1,6 +1,7 @@
 package com.stackup.stackup.session.application.dto;
 
 import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.stackup.stackup.session.domain.SessionFeedback;
 import java.time.Instant;
@@ -17,6 +18,7 @@ public record FeedbackResult(
     String strengthsSummary,
     String weaknessesSummary,
     List<String> improvementKeywords,
+    List<PanelBreakdownItem> panelBreakdown,
     String reportFilePath,
     Instant createdAt
 ) {
@@ -34,11 +36,23 @@ public static FeedbackResult of(SessionFeedback f) {
             f.getStrengthsSummary(),
             f.getWeaknessesSummary(),
             parseKeywords(f.getImprovementKeywords()),
+            parseBreakdown(f.getPanelBreakdown()),
             f.getReportFilePath(),
             f.getCreatedAt()
         );
     }
 
+    private static List<PanelBreakdownItem> parseBreakdown(String json) {
+        if (json == null || json.isBlank()) {
+            return List.of();
+        }
+        try {
+            return JSON.readValue(json, new TypeReference<List<PanelBreakdownItem>>() {});
+        } catch (JsonProcessingException e) {
+            return Collections.emptyList();
+        }
+    }
+
     @SuppressWarnings("unchecked")
     private static List<String> parseKeywords(String json) {
         if (json == null || json.isBlank()) {

backend/src/main/java/com/stackup/stackup/session/application/dto/PanelBreakdownItem.java

@@ -0,0 +1,14 @@
+package com.stackup.stackup.session.application.dto;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+
+// 멀티 면접관 패널의 평가위원 1명 결과(분해). AI 콜백 camelCase 와 1:1, 응답에도 그대로 노출.
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public record PanelBreakdownItem(
+    String evaluator,
+    String dimension,
+    Double score,
+    String strength,
+    String weakness
+) {
+}

backend/src/main/java/com/stackup/stackup/session/domain/SessionFeedback.java

@@ -52,6 +52,11 @@ public class SessionFeedback extends BaseSoftDeleteEntity {
     @Column(name = "improvement_keywords", columnDefinition = "jsonb")
     private String improvementKeywords;
 
+    // 멀티 면접관 패널의 평가위원별 분해 JSON. null = 단일/레거시.
+    @JdbcTypeCode(SqlTypes.JSON)
+    @Column(name = "panel_breakdown", columnDefinition = "jsonb")
+    private String panelBreakdown;
+
     @Column(name = "report_file_path", length = 1000)
     private String reportFilePath;
 
@@ -62,7 +67,8 @@ public class SessionFeedback extends BaseSoftDeleteEntity {
     private SessionFeedback(InterviewSession session, Double overallScore, Double technicalAccuracy,
                             Double logicScore, Double communicationScore,
                             String strengthsSummary, String weaknessesSummary,
-                            String improvementKeywordsJson, String reportFilePath) {
+                            String improvementKeywordsJson, String panelBreakdownJson,
+                            String reportFilePath) {
         if (session == null) {
             throw new IllegalArgumentException("session must not be null");
         }
@@ -74,17 +80,19 @@ private SessionFeedback(InterviewSession session, Double overallScore, Double te
         this.strengthsSummary = strengthsSummary;
         this.weaknessesSummary = weaknessesSummary;
         this.improvementKeywords = improvementKeywordsJson;
+        this.panelBreakdown = panelBreakdownJson;
         this.reportFilePath = reportFilePath;
     }
 
     public static SessionFeedback of(InterviewSession session, Double overallScore,
                                      Double technicalAccuracy, Double logicScore,
                                      Double communicationScore,
                                      String strengthsSummary, String weaknessesSummary,
-                                     String improvementKeywordsJson, String reportFilePath) {
+                                     String improvementKeywordsJson, String panelBreakdownJson,
+                                     String reportFilePath) {
         return new SessionFeedback(session, overallScore, technicalAccuracy, logicScore,
             communicationScore, strengthsSummary, weaknessesSummary,
-            improvementKeywordsJson, reportFilePath);
+            improvementKeywordsJson, panelBreakdownJson, reportFilePath);
     }
 
     // 공유 토큰을 보장(없으면 발급)하고 현재 토큰 반환. 멱등.