Merge branch 'main' into feat/#7-tagging-v1

Author: gyesswhat

.env.example

@@ -14,6 +14,10 @@ LOG_LEVEL=INFO
 # 생성: python -c "import secrets; print(secrets.token_urlsafe(32))"
 INTERNAL_API_TOKEN=change-me-to-a-random-32-byte-token
 
+# ---- Feature variants ----
+# 리포트 생성 서비스의 활성 프롬프트 버전 (app/services/report/ 하위)
+REPORT_VARIANT=v1_baseline
+
 # ---- AI provider ----
 ANTHROPIC_API_KEY=sk-ant-
 ANTHROPIC_MODEL=claude-haiku-4-5-20251001

app/api/report_public.py

@@ -0,0 +1,142 @@
+"""리포트 생성 안정 라우터 — ``/api/reports/*``.
+
+Spring이 호출하는 최종 안정 경로. 현재는 요청 스키마 검증 후 고정 더미 응답 반환.
+cutover 시 각 핸들러 본문을 ``report_service.run_*`` 호출로 교체하면 운영 전환 완료.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+
+from app.core.security import require_internal_token
+from app.schemas.report import (
+    AiCareerBrandingResponse,
+    AiCareerHighlightsResponse,
+    AiCareerNarrativeResponse,
+    AiCareerStrengthsAndInterviewResponse,
+    AiMiniReportResponse,
+    AiReportRequest,
+    InterviewQuestion,
+    StrengthItem,
+)
+from app.services.report._compute import (
+    build_evidences,
+    competency_frequency,
+    top_detail_tag_stats,
+    top_detail_tags,
+)
+
+router = APIRouter(
+    prefix="/api/reports",
+    tags=["reports"],
+    dependencies=[Depends(require_internal_token)],
+)
+
+
+@router.post("/mini", response_model=AiMiniReportResponse, summary="미니 리포트 생성")
+async def create_mini_report(req: AiReportRequest) -> AiMiniReportResponse:
+    return AiMiniReportResponse(
+        activity_summary=(
+            f"{req.nickname}님은 KOPLE, 밋업 프로젝트 등 복수의 프로젝트를 동시에 진행하며 "
+            "각 과제를 구조화하는 작업을 반복해왔어요. 특히 복잡한 요구사항이 주어졌을 때 "
+            "먼저 전체 흐름을 정의하고 실행하는 방식이 기록 전반에서 일관되게 나타나요. "
+            "설계 중 의문이 생기면 진행을 멈추고 재검토하는 패턴도 눈에 띄어요."
+        ),
+        next_focus_point=(
+            "아직 협업·조율 영역 기록이 적어요. 팀원과 의견을 조율했던 경험이나 "
+            "피드백을 주고받은 순간을 기록해보면 더 입체적인 커리어 서사가 만들어질 거예요."
+        ),
+        competency_frequency=competency_frequency(req.records),
+        top_detail_tags=top_detail_tags(req.records),
+    )
+
+
+@router.post(
+    "/career/branding", response_model=AiCareerBrandingResponse, summary="커리어 브랜딩 생성"
+)
+async def create_career_branding(req: AiReportRequest) -> AiCareerBrandingResponse:
+    return AiCareerBrandingResponse(
+        branding_statement=(
+            f"{req.nickname}님은 복잡한 문제를 구조로 풀어내는 '설계형 기획자'입니다."
+        ),
+        branding_pattern="복잡한 상황에서 먼저 구조를 정의하는 행동 방식",
+        top_detail_tags=top_detail_tag_stats(req.records),
+    )
+
+
+@router.post(
+    "/career/narrative", response_model=AiCareerNarrativeResponse, summary="커리어 내러티브 생성"
+)
+async def create_career_narrative(req: AiReportRequest) -> AiCareerNarrativeResponse:
+    return AiCareerNarrativeResponse(
+        narrative_summary=(
+            f"{req.nickname}님은 복수의 프로젝트를 동시에 진행하면서도 각 과제를 먼저 구조화하고 "
+            "실행하는 방식을 일관되게 유지해왔어요. 기획 중 설계적 의문이 생기면 진행을 "
+            "멈추고 재검토하는 패턴이 반복되며, 이는 완성도에 대한 높은 기준을 반영해요. "
+            "#기획_구조화와 #구조_개선이 다른 역량 태그보다 유독 많이 나온 건 이 방식의 증거예요."
+        ),
+    )
+
+
+@router.post(
+    "/career/strengths-and-interview",
+    response_model=AiCareerStrengthsAndInterviewResponse,
+    summary="커리어 강점 및 면접 질문 생성",
+)
+async def create_career_strengths_and_interview(
+    req: AiReportRequest,
+) -> AiCareerStrengthsAndInterviewResponse:
+    record_ids = [r.star_record_id for r in req.records[:2]]
+    evidences = build_evidences(req, record_ids)
+    return AiCareerStrengthsAndInterviewResponse(
+        strengths=[
+            StrengthItem(
+                title="구조 먼저 잡는 기획력",
+                description=(
+                    "요구사항이 복잡할수록 전체 흐름을 먼저 정의하고 실행해요. "
+                    "설계 중 의문이 생기면 멈추고 재검토하는 패턴이 일관돼요."
+                ),
+                evidences=evidences,
+            ),
+            StrengthItem(
+                title="시스템으로 해결하는 협업",
+                description=(
+                    "커뮤니케이션 문제를 개인 노력이 아닌 구조와 규칙으로 풀려는 접근이 반복돼요."
+                ),
+                evidences=evidences,
+            ),
+        ],
+        interview_questions=[
+            InterviewQuestion(
+                question=(
+                    "KOPLE 프로젝트에서 단기간에 완성했다고 하셨는데, "
+                    "구체적으로 얼마 만이었고 어떤 트레이드오프가 있었나요?"
+                ),
+                evidences=evidences,
+            ),
+            InterviewQuestion(
+                question="진행을 멈추고 재검토하는 판단을 팀원들에게 어떻게 설득하셨나요?",
+                evidences=evidences,
+            ),
+        ],
+    )
+
+
+@router.post(
+    "/career/highlights",
+    response_model=AiCareerHighlightsResponse,
+    summary="커리어 하이라이트 생성",
+)
+async def create_career_highlights(_req: AiReportRequest) -> AiCareerHighlightsResponse:
+    return AiCareerHighlightsResponse(
+        experience_highlights=[
+            (
+                "복수의 이해관계자 요구가 충돌하는 KOPLE 프로젝트에서, "
+                "전체 흐름을 구조화해 PRD와 기능명세서를 단기간에 완성했습니다."
+            ),
+            (
+                "설계 중 구조적 의문이 생겼을 때 진행을 멈추고 재검토함으로써, "
+                "개발 착수 전 핵심 설계 이슈를 선제 해결했습니다."
+            ),
+        ]
+    )

app/api/v1/__init__.py

@@ -9,7 +9,7 @@
 
 from fastapi import APIRouter, Depends
 
-from app.api.v1 import ping, tagging
+from app.api.v1 import ping, report, tagging
 from app.core.security import require_internal_token
 
 router = APIRouter(
@@ -20,3 +20,4 @@
 # Feature 라우터 등록 — 새 기능은 한 줄씩 여기에 추가.
 router.include_router(ping.router)
 router.include_router(tagging.router)
+router.include_router(report.router)

app/api/v1/report.py

@@ -0,0 +1,60 @@
+"""리포트 생성 실험 라우터 — ``/v1/reports/*``.
+
+실제 서비스 레이어를 호출하는 실험·개발 경로.
+검증이 끝나면 ``/api/reports/*`` 핸들러 본문을 이쪽 service 호출로 교체하면 운영 전환 완료.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from app.schemas.report import (
+    AiCareerBrandingResponse,
+    AiCareerHighlightsResponse,
+    AiCareerNarrativeResponse,
+    AiCareerStrengthsAndInterviewResponse,
+    AiMiniReportResponse,
+    AiReportRequest,
+)
+from app.services import report as report_service
+
+router = APIRouter(prefix="/reports", tags=["reports"])
+
+
+@router.post("/mini", response_model=AiMiniReportResponse, summary="미니 리포트 생성")
+async def create_mini_report(req: AiReportRequest) -> AiMiniReportResponse:
+    return await report_service.run_mini(req)
+
+
+@router.post(
+    "/career/branding", response_model=AiCareerBrandingResponse, summary="커리어 브랜딩 생성"
+)
+async def create_career_branding(req: AiReportRequest) -> AiCareerBrandingResponse:
+    return await report_service.run_branding(req)
+
+
+@router.post(
+    "/career/narrative", response_model=AiCareerNarrativeResponse, summary="커리어 내러티브 생성"
+)
+async def create_career_narrative(req: AiReportRequest) -> AiCareerNarrativeResponse:
+    return await report_service.run_narrative(req)
+
+
+@router.post(
+    "/career/strengths-and-interview",
+    response_model=AiCareerStrengthsAndInterviewResponse,
+    summary="커리어 강점 및 면접 질문 생성",
+)
+async def create_career_strengths_and_interview(
+    req: AiReportRequest,
+) -> AiCareerStrengthsAndInterviewResponse:
+    return await report_service.run_strengths_and_interview(req)
+
+
+@router.post(
+    "/career/highlights",
+    response_model=AiCareerHighlightsResponse,
+    summary="커리어 하이라이트 생성",
+)
+async def create_career_highlights(req: AiReportRequest) -> AiCareerHighlightsResponse:
+    return await report_service.run_highlights(req)

app/core/config.py

@@ -55,6 +55,12 @@ class Settings(BaseSettings):
         ),
     )
 
+    # ---- Feature variants ----
+    report_variant: str = Field(
+        default="v1_baseline",
+        description="리포트 생성 서비스의 활성 구현체 버전 (app/services/report/ 하위).",
+    )
+
     # ---- AI provider ----
     anthropic_api_key: str = Field(
         default="dev-no-api-key",

app/main.py

@@ -15,7 +15,7 @@
 from fastapi import FastAPI
 
 from app import __version__
-from app.api import health, tagging_public
+from app.api import health, report_public, tagging_public
 from app.api.v1 import router as v1_router
 from app.core.config import get_settings
 from app.core.logging import configure_logging, get_logger
@@ -74,10 +74,12 @@ def create_app() -> FastAPI:
     #   include_router 목록에 한 줄 추가하는 식으로 붙인다 (여기는 건드리지 않음).
     # - tagging_public: Spring 합의 안정 경로 /api/tagging. 현재 더미 응답이며
     #   v1_baseline 검증 후 cutover 시 핸들러 본문을 service 호출로 교체한다.
+    # - report_public: Spring 합의 안정 경로 /api/reports/*. 현재 더미 응답.
     # CORS 미들웨어는 의도적으로 미포함 — 서버 간 통신이므로 불필요.
     app.add_middleware(RequestContextMiddleware)
 
     app.include_router(health.router)
+    app.include_router(report_public.router)
     app.include_router(v1_router)
     app.include_router(tagging_public.router)
 

app/schemas/common.py

@@ -17,6 +17,14 @@ class JobRole(StrEnum):
     DESIGNER = "DESIGNER"
 
 
+class UserStatus(StrEnum):
+    """유저 상태 — Spring 측 enum 코드와 동일."""
+
+    STUDENT = "STUDENT"
+    JOB_SEEKER = "JOB_SEEKER"
+    EMPLOYED = "EMPLOYED"
+
+
 class PrimaryCategory(StrEnum):
     """5대 직무 역량 — Spring 측 enum 코드와 동일."""