Merge pull request #213 from Team-StackUp/feat/markdown-contract

feat: AI 텍스트 포맷 계약 + 마크다운 렌더러 도입

Author: Jaeho-Site

ai/src/ai_server/chain/prompts/answer_coaching.py

@@ -13,6 +13,9 @@
     "없는 경험을 지어내지 말고, 있는 내용을 구조(두괄식·근거·결과)와 구체성으로 보강. 답변이 비었거나 "
     "'모르겠다'면 '이렇게 접근했다면' 식으로 짧게.\n"
     "- **coaching_comment (한 줄 코칭)**: 이 답변에서 가장 중요한 보완점 하나를 한 문장으로.\n"
+    "포맷: model_answer 와 answer_rewrite 는 필요하면 **GFM 마크다운**(굵게·리스트·코드 블록)을 "
+    "사용해도 됩니다 — 화면이 마크다운으로 렌더합니다. coaching_comment 는 서식 기호 없는 "
+    "일반 텍스트 한 문장으로.\n"
     "- **질문이 경험·행동·자소서 기반**('그때 무엇을 어떻게 했는가', 지원동기·성장·갈등 등)이면 "
     "model_answer 와 answer_rewrite 를 **STAR(상황·과제·행동·결과) 골격**으로 구성하고, 본인의 구체적 "
     "행동·정량적 결과·배운 점이 드러나게 코칭하세요. (기술 개념 질문이면 STAR 대신 정확성·깊이 우선.)\n"

ai/src/ai_server/chain/prompts/feedback_generation.py

@@ -10,6 +10,7 @@
     "  - logic_score: 논리·인과관계 명확성\n"
     "  - communication_score: 답변의 명료성·구조화\n"
     "- 요약:\n"
+    "  - 모든 텍스트 필드는 마크다운 서식 기호 없이 일반 텍스트로 작성 (화면이 plain text 렌더).\n"
     "  - strengths_summary: 가장 잘한 점 3가지 이내 (각 1~2문장).\n"
     "  - weaknesses_summary: 가장 부족한 점 3가지 이내 (각 1~2문장).\n"
     "  - improvement_keywords: 다음 면접에서 채울 키워드 5~10개 (짧은 명사구).\n"

ai/src/ai_server/chain/prompts/feedback_panel.py

@@ -14,6 +14,7 @@
     "- 점수를 매기기 전에 강점/약점 근거를 먼저 정리한 뒤 산정한다(즉흥 점수 금지).\n"
     "- strength/weakness 는 각각 한 줄(한국어, 구체적으로). keywords 는 이 축에서 보완할 "
     "개선 키워드 0~4개(짧은 명사구).\n"
+    "- 모든 텍스트 필드는 마크다운 서식 기호 없이 일반 텍스트로 작성하세요 (화면이 plain text 렌더).\n"
     "- detail: 이 축에 대한 2~4문장 상세 평가. **답변의 구체적 부분을 인용/지목**하고 무엇이 "
     "왜 좋았는지/아쉬웠는지 근거를 들어 서술한다(추상적 총평 금지).\n"
     "- score_rationale: 그 점수를 준 핵심 근거(가점/감점 요인)를 한두 문장으로.\n"

ai/src/ai_server/chain/prompts/feedback_synthesis.py

@@ -11,6 +11,8 @@
     "- improvement_keywords: 다음 면접에서 보완할 키워드 5~10개(짧은 명사구).\n"
     "- study_plan: 구체적 학습 방향/다음 단계 액션 아이템 3~6개. 각 항목은 '무엇을 어떻게'가 "
     "드러나는 실행 문장(예: 'Redis 분산 락의 SETNX·TTL 옵션을 직접 구현해보며 원자성 보장 원리 정리').\n"
+    "모든 텍스트 필드는 **마크다운 서식 기호 없이 일반 텍스트**로 작성하세요(굵게 **, 리스트 -, "
+    "코드 ` 금지) — 화면이 plain text 로 렌더하고, highlights 는 원문 부분 문자열 매칭에 쓰입니다.\n"
     "- highlights: 지원자가 꼭 기억해야 할 **가장 중요한 핵심 구절 3~6개**. 화면에서 강조 표시할 "
     "용도라, 반드시 위 strengths_summary·weaknesses_summary 본문에 **그대로 등장한 짧은 구절"
     "(각 2~12어절)을 글자 그대로 발췌**하세요(새로 짓거나 바꿔쓰지 말 것 — 부분 문자열 매칭에 사용). "

ai/src/ai_server/chain/prompts/question_generation.py

@@ -16,6 +16,7 @@
     "- 카테고리는 다음 중에서 선택: CS_FUNDAMENTAL, PROJECT_DEEP_DIVE, TECH_CHOICE, "
     "BEHAVIORAL.\n"
     "- 한국어로 작성하되 기술 용어는 영문 원어를 그대로 둡니다.\n"
+    "- 질문·근거 텍스트에는 마크다운 서식 기호를 쓰지 마세요 (화면이 plain text 렌더, 스트리밍 표시).\n"
     "- 질문 문장은 **간결하게**: 한두 문장(대략 80자 이내)으로, 장황한 배경 설명이나 "
     "중복 수식 없이 핵심만 묻습니다. 면접관이 입으로 자연스럽게 말할 길이여야 합니다.\n"
     "- **직무 맞춤(타깃 회사/JD 제공 시)**: 먼저 채용공고에서 **핵심 요구 역량 5~8개를 뽑아** "

backend/openapi.json

@@ -2842,6 +2842,69 @@
         }
       }
     },
+    "/api/documents/{documentId}/content" : {
+      "get" : {
+        "tags" : [ "Documents" ],
+        "summary" : "분석 원문(마크다운) 프록시",
+        "description" : "presigned URL 은 내부(MinIO) 호스트라 브라우저가 직접 접근할 수 없어 Core 가 원문 바이트를 중계한다 (TTS 오디오 프록시와 동일 패턴).",
+        "operationId" : "getAnalyzedDocumentContent",
+        "parameters" : [ {
+          "name" : "documentId",
+          "in" : "path",
+          "required" : true,
+          "schema" : {
+            "type" : "integer",
+            "format" : "int64"
+          }
+        } ],
+        "responses" : {
+          "200" : {
+            "description" : "분석 원문 (text/markdown)",
+            "content" : {
+              "*/*" : {
+                "schema" : {
+                  "type" : "string",
+                  "format" : "binary"
+                }
+              }
+            }
+          },
+          "401" : {
+            "description" : "인증 실패",
+            "content" : {
+              "*/*" : {
+                "schema" : {
+                  "type" : "string",
+                  "format" : "binary"
+                }
+              }
+            }
+          },
+          "404" : {
+            "description" : "분석 문서 없음",
+            "content" : {
+              "*/*" : {
+                "schema" : {
+                  "type" : "string",
+                  "format" : "binary"
+                }
+              }
+            }
+          },
+          "422" : {
+            "description" : "아직 분석 산출물이 없음",
+            "content" : {
+              "*/*" : {
+                "schema" : {
+                  "type" : "string",
+                  "format" : "binary"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/auth/google/callback" : {
       "get" : {
         "tags" : [ "Auth" ],

backend/src/main/java/com/stackup/stackup/document/application/AnalyzedDocumentQueryService.java

@@ -53,6 +53,17 @@ public AnalyzedDocumentResult getForUser(Long userId, Long documentId) {
         return AnalyzedDocumentResult.of(doc, parseTechStack(doc.getTechStack()), downloadUrl);
     }
 
+    // 분석 원문(마크다운) 프록시 — presigned URL 은 내부(MinIO) 호스트라 브라우저가 직접 접근할
+    // 수 없다(TTS 오디오 프록시와 동일 이유). 소유권 검증 후 Core 가 바이트를 중계한다.
+    public java.io.InputStream getContentForUser(Long userId, Long documentId) {
+        AnalyzedDocument doc = documentRepository.findActiveByIdAndOwner(documentId, userId)
+            .orElseThrow(() -> new DomainException(ApiErrorCode.DOC_NOT_FOUND));
+        if (doc.getDocumentPath() == null || doc.getDocumentPath().isBlank()) {
+            throw new DomainException(ApiErrorCode.DOC_NOT_ANALYZED);
+        }
+        return storage.get(doc.getDocumentPath());
+    }
+
     private List<String> parseTechStack(String json) {
         if (json == null || json.isBlank()) {
             return List.of();

backend/src/main/java/com/stackup/stackup/document/presentation/AnalyzedDocumentController.java

@@ -7,8 +7,14 @@
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.tags.Tag;
+import java.time.Duration;
 import java.util.List;
 import lombok.RequiredArgsConstructor;
+import org.springframework.core.io.InputStreamResource;
+import org.springframework.core.io.Resource;
+import org.springframework.http.CacheControl;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
@@ -61,4 +67,27 @@ public AnalyzedDocumentResponse get(
     ) {
         return AnalyzedDocumentResponse.from(queryService.getForUser(principal.userId(), documentId));
     }
+
+    @Operation(
+        operationId = "getAnalyzedDocumentContent",
+        summary = "분석 원문(마크다운) 프록시",
+        description = "presigned URL 은 내부(MinIO) 호스트라 브라우저가 직접 접근할 수 없어 "
+            + "Core 가 원문 바이트를 중계한다 (TTS 오디오 프록시와 동일 패턴)."
+    )
+    @ApiResponses({
+        @ApiResponse(responseCode = "200", description = "분석 원문 (text/markdown)"),
+        @ApiResponse(responseCode = "401", description = "인증 실패"),
+        @ApiResponse(responseCode = "404", description = "분석 문서 없음"),
+        @ApiResponse(responseCode = "422", description = "아직 분석 산출물이 없음")
+    })
+    @GetMapping("/{documentId}/content")
+    public ResponseEntity<Resource> content(
+        @AuthenticationPrincipal UserPrincipal principal,
+        @PathVariable Long documentId
+    ) {
+        return ResponseEntity.ok()
+            .contentType(MediaType.parseMediaType("text/markdown; charset=utf-8"))
+            .cacheControl(CacheControl.maxAge(Duration.ofMinutes(10)).cachePrivate())
+            .body(new InputStreamResource(queryService.getContentForUser(principal.userId(), documentId)));
+    }
 }

backend/src/test/java/com/stackup/stackup/document/application/AnalyzedDocumentQueryServiceTest.java

@@ -0,0 +1,60 @@
+package com.stackup.stackup.document.application;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import com.stackup.stackup.common.exception.ApiErrorCode;
+import com.stackup.stackup.common.exception.DomainException;
+import com.stackup.stackup.common.storage.ObjectStorageClient;
+import com.stackup.stackup.document.domain.AnalyzedDocument;
+import com.stackup.stackup.document.domain.AnalyzedDocumentRepository;
+import java.io.ByteArrayInputStream;
+import java.util.Optional;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+@ExtendWith(MockitoExtension.class)
+class AnalyzedDocumentQueryServiceTest {
+
+    @Mock AnalyzedDocumentRepository documentRepository;
+    @Mock ObjectStorageClient storage;
+    @InjectMocks AnalyzedDocumentQueryService service;
+
+    // 분석 원문 프록시(A5) — presigned URL 은 내부 호스트라 브라우저 직접 접근 불가,
+    // Core 가 소유권 검증 후 바이트를 중계한다.
+    @Test
+    void getContentForUser_streamsMarkdownFromStorage() {
+        AnalyzedDocument doc = mock(AnalyzedDocument.class);
+        when(doc.getDocumentPath()).thenReturn("analyzed/resume/42/summary.md");
+        when(documentRepository.findActiveByIdAndOwner(42L, 1L)).thenReturn(Optional.of(doc));
+        when(storage.get("analyzed/resume/42/summary.md"))
+            .thenReturn(new ByteArrayInputStream("## 개요".getBytes()));
+
+        assertThat(service.getContentForUser(1L, 42L)).isNotNull();
+    }
+
+    @Test
+    void getContentForUser_throwsNotFoundForOthersDocument() {
+        when(documentRepository.findActiveByIdAndOwner(42L, 1L)).thenReturn(Optional.empty());
+
+        assertThatThrownBy(() -> service.getContentForUser(1L, 42L))
+            .isInstanceOfSatisfying(DomainException.class,
+                e -> assertThat(e.getErrorCode()).isEqualTo(ApiErrorCode.DOC_NOT_FOUND));
+    }
+
+    @Test
+    void getContentForUser_throwsWhenNoDocumentPathYet() {
+        AnalyzedDocument doc = mock(AnalyzedDocument.class);
+        when(doc.getDocumentPath()).thenReturn(null);
+        when(documentRepository.findActiveByIdAndOwner(42L, 1L)).thenReturn(Optional.of(doc));
+
+        assertThatThrownBy(() -> service.getContentForUser(1L, 42L))
+            .isInstanceOfSatisfying(DomainException.class,
+                e -> assertThat(e.getErrorCode()).isEqualTo(ApiErrorCode.DOC_NOT_ANALYZED));
+    }
+}

docs/api-conventions.md

@@ -67,6 +67,7 @@ POST   /api/resumes/{id}/reanalyze 재분석
 
 GET    /api/documents              분석 문서 목록
 GET    /api/documents/{id}         분석 문서 상세 (S3 URL 포함)
+GET    /api/documents/{id}/content 분석 원문(마크다운) 프록시 — presigned 는 내부 호스트라 Core 중계
 ```
 
 ### 2.4 면접 세션