니쥬는 AI와의 대화로 취향을 분석한다. 그 결과로 두 종류의 상품 리스트를 만든다. 리스트를 둘로 나누는 것이 이 API의 전제다.

sequenceDiagram
    participant C as Spring 또는 모니터링 시스템
    participant A as AI Server
    participant P as FastAPI Application
    participant D as 카탈로그 DB

    C->>A: GET /health
    A->>P: 애플리케이션 실행 상태 확인
    P->>D: 커넥션 확인
    D-->>P: 응답

    alt 요청 처리 가능
        P-->>A: 정상 상태
        A-->>C: 200 OK
    else 필수 초기화 미완료
        P-->>A: 비정상 상태
        A-->>C: 503 SERVICE_UNAVAILABLE
    end

sequenceDiagram
    participant U as 사용자
    participant F as 프론트엔드
    participant S as Spring Backend
    participant A as AI Server
    participant R as Redis 세션 상태
    participant P as 목표 판정 (서버 로직)
    participant L as 응답 모델
    participant X as 추출 모델

    U->>F: 대화 시작 (NU-04)
    F->>S: 세션 생성 요청
    S->>A: POST /v1/chat/sessions
    A->>P: 첫 턴 목표 판정 (OPENING)
    A->>L: 첫 발화 생성
    A->>R: 세션 생성 (이력·상태 저장)
    A-->>S: 201 sessionId, greeting
    S-->>F: 첫 발화 표시

    loop 최대 20개 대화 사이클
        U->>F: 발화 입력
        F->>S: 턴 전송
        S->>A: POST /v1/chat/sessions/{id}/messages
        A->>R: 세션 상태 로드
        A->>P: 이번 턴 목표 판정 (LLM 미사용)
        P-->>A: 목표 + 지시문

        A->>L: 시스템(불변) + 누적 이력 + 지시문 + 이번 발화
        L-->>A: 응답 스트림
        A-->>S: event: token
        S-->>F: SSE 릴레이
        A->>A: 지시문 누출 절단 · 질문 1개 강제

        A->>X: [STATE] + 직전 AI 발화 + 이번 발화 (구조화 출력)
        X-->>A: 델타 JSON (items·axes·drop)
        A->>A: 병합 · 정정 · 상한 초과분 방출
        A->>R: 세션 상태 저장
        A-->>S: event: done (turn, canClose)
    end

Redis에서 세션 상태 로드
→ 서버가 이번 턴 목표를 정한다 (개수 기반 규칙, LLM 미사용)
→ 응답 모델 호출: [시스템(불변)] + [누적 이력] + [지시문 + 이번 발화]
→ 토큰을 SSE로 흘려보낸다
→ 응답 후처리: 지시문 누출 절단, 물음표 2개 이상이면 첫 질문까지만
→ 추출 모델 호출: [STATE] 블록 + 직전 AI 발화 + 이번 발화 → 델타 JSON
→ 병합·정정·방출 후 Redis 저장
→ done 이벤트로 턴 수와 종료 가능 여부 전달

sequenceDiagram
    participant U as 사용자
    participant F as 프론트엔드
    participant S as Spring Backend
    participant A as AI Server
    participant J as 리스트 생성 잡 큐
    participant L as LLM 및 임베딩
    participant D as 카탈로그 DB

    F->>S: 대화 종료
    S->>A: POST /v1/chat/sessions/{id}/close
    A->>A: 프로필 확정 (서버 규칙)
    A->>L: 요약문 생성
    A->>A: 표시 키워드 선별 (서버 규칙)
    A-->>S: 200 profile, summary, keywords
    S-->>F: 확인 화면 표시 (NU-04A)

    alt 정정 요청
        U->>F: 다릅니다
        F->>S: 세션 재개
        S->>A: POST /v1/chat/sessions/{id}/messages
        Note over S,A: 목표 CORRECT로 정정 대화, 이후 close 재호출
    else 확정
        U->>F: 맞습니다
        F->>S: 확정 전송
        S->>S: 프로필·요약문·키워드 저장
        S->>A: POST /v1/recommendations/jobs
        A->>J: 잡 등록
        A->>A: 세션 원문 삭제 (병렬)
        A-->>S: 202 jobId, pollAfterMs
        S-->>F: 메인 화면으로 이동

        J->>L: 검색 문장 재작성 · 임베딩
        J->>D: 벡터 검색 및 하드필터
        J->>J: 스코어 · 다양성 선별
        J->>L: 추천 이유 생성

        loop 완료까지 폴링
            S->>A: GET /v1/recommendations/jobs/{jobId}
            alt 처리 중
                A-->>S: 200 running, progress
            else 완료
                A-->>S: 200 succeeded, lists
            end
        end

        S->>S: 두 리스트 저장
        S-->>F: SSE로 리스트 전달
    end

세션 상태를 프로필로 확정
→ 요약문 생성
→ 표시 키워드 선별
→ 프로필 + 요약문 + 키워드 반환

잡 등록 · 세션 원문 삭제 (병렬)
→ 검색 문장 재작성 → 임베딩 → 벡터 검색 → 스코어 · 선별 → 이유 생성
→ self·gift 두 리스트 반환

sequenceDiagram
    participant T as 재생성 트리거
    participant S as Spring Backend
    participant A as AI Server
    participant L as LLM 및 임베딩
    participant D as 카탈로그 DB

    T->>S: 프로필 변경 · 주간 배치 · 피드백 누적 · TTL 만료
    S->>A: POST /v1/recommendations (mode, profile, feedbackSummary)
    A->>D: 조건에 맞는 상품 조회
    D-->>A: 후보 300~500

    alt 최소 점수를 넘는 후보 있음
        A->>A: 모드별 순위 계산과 선별
        A->>L: 추천 이유 생성
        A-->>S: 200 items, funnel
    else 전량 미달
        A-->>S: 200 items 빈 배열, emptyReason
    end

    S->>S: 리스트 교체 저장

프로필 수신 및 검증
→ 조건에 맞는 상품 후보 조회 (제외 목록 · constraints 반영)
→ 모드별 순위 계산과 선별
→ 추천 이유 생성
→ 응답 검증 및 정제

sequenceDiagram
    participant U as 사용자
    participant F as 프론트엔드
    participant S as Spring Backend
    participant A as AI Server

    U->>F: 좋아요 · 싫어요 · 이미 있음 (NU-08)
    F->>S: 피드백 전송
    S->>A: POST /v1/recommendations/{id}/feedback
    A->>A: 귀인 대상 판정 (상품 · 취향 항목 · 매핑)
    A-->>S: 200 accepted, effects
    S->>S: effects대로 프로필과 제외 목록 갱신
    Note over S,A: 다음 리스트 재생성 요청에 feedbackSummary로 반영

엔드포인트 10개는 7개 기능으로 묶인다.

사용자가 화면 앞에서 완료를 기다리는 기능은 2와 3이다. 기능 4는 사용자가 메인 화면으로 이동한 뒤에 돌고, 결과가 준비되면 백엔드가 SSE로 알린다. 5~7은 백엔드나 배치가 부르므로 응답 시간이 화면 체감에 직접 걸리지 않는다.

행 순서는 아래 「API별 요청·응답 계약」의 순서와 같다.

같은 기능 안에서도 처리 방식이 갈린다. 백엔드가 호출 코드를 짤 때 이 표를 먼저 본다.

NU-03~NU-12는 서비스 화면 번호이고, 엔드포인트의 /v1은 API 계약 버전이다. 상세 설계 문서가 v3까지 개정되었지만 계약 자체는 아직 첫 버전이므로 /v3 경로를 새로 파지 않는다.

대화(기능 2·3)를 빼면 사용자가 AI 서버를 기다리는 화면이 없다. 나머지 화면은 백엔드가 저장한 리스트를 조회하므로, recommendations는 화면 진입 API가 아니라 갱신 API다.

필드 표는 필드 | 타입 | 설명 3열로 통일한다. 아무 표기가 없으면 필수이며, 그렇지 않은 것만 설명 앞에 표기한다.

공통 헤더는 다음과 같다.

공통 경로 파라미터 타입은 다음과 같다. 경로 표기는 요청·응답 JSON과 같은 camelCase로 통일한다.

취향 프로필은 백엔드가 저장하고 AI Server가 요청마다 받는다. 각 배열은 항상 존재하며 값이 없으면 빈 배열을 사용한다. 세션 전체에서 10개 배열의 ProfileItem 합계는 최대 12개다.

POST /v1/chat/sessions/{sessionId}/close의 최상위 summary는 profile.summary와 같은 값이다. 두 위치에 모두 두어야 하는지는 아직 확정되지 않았으며, 현재 계약에서는 하위 호환을 위해 둘 다 반환한다.

10개 취향 배열의 의미와 추천 역할은 다음과 같다.

deferralReason에 따라 선물 신호의 강도가 다르다.

value를 카테고리로 정규화하지 않는다. "캠핑장에서 핸드드립"을 "아웃도어 > 캠핑"으로 바꾸면, 캠핑을 실제로 하는 사람과 캠핑 영상만 보는 사람이 같은 값이 된다. 구체성이 떨어지면 추천 정확도가 떨어진다.

확인 화면(NU-04A)과 친구 상세(NU-06)에 표시하는 대표 키워드다. 프로필 항목에서 서버 규칙으로 선별하며 모델을 호출하지 않는다.

선별 규칙은 다음과 같다.

• lifestyle은 넣지 않는다. 요약문에서 제외하는 규칙과 같은 이유다. 생활 맥락은 친구가 보는 화면에 드러나면 안 된다.
• 3개 고정이 아니라 최대 3개다. 대화가 짧게 끝나면 조건을 만족하는 항목이 3개에 미치지 못할 수 있다. 개수를 채우려고 확신도가 낮은 항목을 올리지 않는다.
• 키워드는 사용자에게 보이는 값이고, 검색에 쓰는 항목과 범위가 다르다. 검색은 linkRole이 query인 항목 전체를 쓰며 visibility와 무관하다.

추출 결과 조회와 추천 리스트 재생성은 동일한 RecommendationResult 구조를 사용한다.

{
  "recommendationId": "r_5f6g",
  "generatedAt": "2026-09-02T14:45:00Z",
  "mode": "gift",
  "priceRange": { "min": 12000, "max": 185000, "currency": "KRW" },
  "items": [
    {
      "productId": "p_1234",
      "title": "티타늄 더블월 머그컵 350ml",
      "price": 148000,
      "imageUrl": "https://cdn.example.com/p1234.jpg",
      "productUrl": "https://example.com/products/1234",
      "category": "캠핑식기",
      "priceBand": 3,
      "rank": 0,
      "score": 0.809,
      "reason": "직접 사기엔 조금 망설여지는 물건이에요. 캠핑에서 커피 내려 드시는 걸 좋아해서 오래 쓸 수 있는 컵을 골랐어요.",
      "matchedSignals": [
        {
          "field": "unaffordable",
          "value": null,
          "label": "캠핑 장비",
          "tasteNodeId": "outdoor.camping.camping_dish",
          "via": "vector_content",
          "similarity": 0.87,
          "contribution": 0.42
        }
      ],
      "ranking": {
        "mode": "gift",
        "factors": { "wantSignal": 0.74, "deferralWeight": 1.5, "giftability": 0.81 },
        "rankerVersion": "gift-1.0.0"
      }
    }
  ],
  "emptyReason": null,
  "funnel": { "retrieved": 412, "afterHardFilter": 268, "afterScoreFloor": 91, "returned": 20 }
}

추천 가능한 상품이 없으면 오류 대신 다음과 같이 반환한다.

{
  "recommendationId": "r_5f6h",
  "generatedAt": "2026-09-02T14:46:00Z",
  "mode": "gift",
  "priceRange": null,
  "items": [],
  "emptyReason": "NO_RELEVANT_CANDIDATE",
  "suggestion": "MORE_CONVERSATION",
  "funnel": { "retrieved": 180, "afterHardFilter": 132, "afterScoreFloor": 0, "returned": 0 }
}

details의 내부 필드는 오류 코드마다 달라지는 확장 영역이다. 현재 공통 타입은 JSON object로만 정해졌고 오류 코드별 하위 스키마는 미확정이다.

{
  "code": "LLM_UNAVAILABLE",
  "message": "일시적인 오류입니다. 잠시 후 다시 시도해 주세요.",
  "retryable": true,
  "requestId": "req_8f2a",
  "details": null
}

전체 오류 코드는 다음과 같다.

RECOMMENDATION_FAILED는 HTTP 오류 코드가 아니다. 리스트 생성 잡의 결과 상태이므로 GET /v1/recommendations/jobs/{jobId}의 200 응답 안에 status: "failed"와 함께 담긴다.

모델을 쓰는 API라 일반 서버와 다른 실패가 있다. 부분 실패를 전체 실패로 만들지 않는 것이 원칙이다.

오류가 아닌 것은 다음과 같다.

순서는 위 기능 분류를 따른다. 각 엔드포인트 줄에 소속 기능을 함께 표기한다.

GET /health · 기능 1 AI 서버 상태 확인

Spring Backend, 배포 플랫폼 또는 모니터링 시스템이 FastAPI 프로세스와 필수 초기화 상태를 확인한다. 반복 호출에 비용과 지연이 생기지 않도록 LLM과 임베딩 API는 호출하지 않는다. 이 엔드포인트만 서비스 토큰을 요구하지 않는다.

요청 본문과 필수 파라미터가 없다.

{
  "status": "ok",
  "version": "1.0.0",
  "dependencies": { "catalogDb": "ok" },
  "catalog": { "totalProducts": 8420, "lastBatchAt": "2026-09-02T06:00:00Z" }
}

dependencies와 catalog의 하위 타입은 다음과 같다.

POST /v1/chat/sessions · 기능 2 취향 대화

취향 수집 대화를 시작하고 첫 발화를 반환한다. 온보딩에서 받은 값은 취향 항목이 아니라 첫 질문의 시드로만 쓴다.

OnboardingInput의 하위 필드는 모두 필수이며 값이 없으면 빈 배열을 보낸다.

{
  "userId": "u_10293",
  "existingProfile": null,
  "onboarding": {
    "seedCategories": ["아웃도어", "커피"],
    "excludeCategories": ["주류"],
    "constraints": ["견과류 알레르기"]
  }
}

201 Created

{
  "sessionId": "s_7a2b",
  "greeting": "안녕하세요! 요즘 어떻게 지내시는지 궁금해요.",
  "maxTurns": 20
}

POST /v1/chat/sessions/{sessionId}/messages · 기능 2 취향 대화

사용자의 한 턴을 전달하고 모델 응답을 토큰 단위로 스트리밍한다. 응답 본문은 text/event-stream이며, 백엔드는 이 스트림을 프론트엔드로 릴레이한다.

{ "message": "주말마다 캠핑 가요" }

200 OK, Content-Type: text/event-stream

이벤트 페이로드 타입은 다음과 같다.

event: token
data: {"text":"캠핑 좋죠. "}

event: token
data: {"text":"주로 어디로 다니세요?"}

event: done
data: {"turn":3,"maxTurns":20,"canClose":false,"itemCount":4}

대화 사이클 하나는 모델 호출 두 번으로 처리된다. 스트림에 실리는 것은 앞의 하나뿐이다.

추출 호출의 입력은 대화 전체가 아니라 세 조각이다.

[지금까지 파악한 것]   ← [STATE] 블록 (items ≤ 12 · axes ≤ 3)
[직전 AI 발화]
[이번 사용자 발화]

출력은 response_format: json_schema(strict: true)로 형식을 강제한다.

{
  "items": [
    { "value": "핸드드립", "field": "hobbies", "confidence": 0.85,
      "evidence": "가서 커피 직접 내려 마시는 게 제일 좋아요",
      "intent": "none", "defer": "none", "urgency": "none" }
  ],
  "axes": [],
  "drop": []
}

델타 최상위 타입은 다음과 같다.

ExtractionItem 타입은 다음과 같다.

DropInstruction 타입은 다음과 같다.

현재 프로토타입 chat/schema.py의 추출 스키마는 drop을 array<string>으로 구현했지만, 문자열만으로는 remove와 lower를 구분할 수 없다. 이 문서는 array<DropInstruction>을 최종 계약으로 정하며 구현 단계에서 프로토타입을 맞춰야 한다.

drop의 lower는 정정 대화에서 주로 쓴다. 사용자가 "틀렸다"고 말한 것과 "그 정도는 아니다"라고 말한 것을 같게 처리하면 항목이 과하게 지워진다. 확신도 조정 폭은 피드백 수집의 confidenceChange와 같은 값을 쓴다.

drop으로 처리된 항목은 items 상한 12개를 넘어 방출할 때 우선 대상이 된다. 사용자가 방금 아니라고 말한 항목보다 오래된 항목이 먼저 밀려나면 정정이 반영되지 않는다.

한 대화 사이클에 items 3개를 넘기지 않는다. 델타는 서버가 병합·정정한 뒤 Redis에 반영하고 원본은 버린다. 추출 호출이 실패하면 그 사이클은 빈 델타로 넘어가고 대화는 끊기지 않는다. 델타는 SSE에 실리지 않으므로 프론트엔드는 파싱 책임을 지지 않는다.

20번째 입력은 받지 않고 끊는 것이 아니다. 응답 스트림과 추출·병합을 모두 완료한 뒤 다음 done 이벤트를 보낸다.

event: done
data: {"turn":20,"maxTurns":20,"canClose":true,"inputLocked":true,
       "completionReason":"MAX_CYCLES","profileCompleteness":"partial",
       "lastTurnExtractionFailed":false}

• 프론트엔드는 입력창을 잠그고 분석이 완료됐어요를 표시한 뒤 /close를 호출한다.
• profileCompleteness=partial은 수집 스키마가 덜 채워졌다는 뜻이지 처리 실패가 아니다. UI에서 “모든 취향을 충분히 파악했다”고 표현하지 않는다.
• 마지막 추출이 실패하면 기존 누적 State로 확정하고 lastTurnExtractionFailed=true를 남긴다.
• 20번째 처리 후의 21번째 메시지는 409 SESSION_CLOSED로 거절한다.
• 최대 사이클 도달에 의한 /close는 신호 부족을 이유로 422를 반환하지 않고 현재까지의 값으로 프로필을 만든다.

DELETE /v1/chat/sessions/{sessionId} · 기능 2 취향 대화

사용자가 대화 중 이탈하거나 취소했을 때 호출한다. 추출을 실행하지 않고 세션 원문과 상태를 즉시 삭제한다.

POST /v1/chat/sessions/{sessionId}/close · 기능 3 프로필 확정

대화를 종료하고 세션 상태를 취향 프로필로 확정한다. 요약문과 표시 키워드를 함께 생성해 동기로 반환한다. 이 시점에 세션 원문을 삭제하지 않는다. 확인 화면에서 정정 대화로 돌아갈 수 있기 때문이다.

요청 본문이 없다.

200 OK

{
  "profile": { "...": "TasteProfile" },
  "summary": "캠핑을 다니면서 직접 커피를 내려 마시는 걸 즐깁니다. 가벼운 장비를 선호하고, 향이 강한 제품은 좋아하지 않습니다.",
  "keywords": {
    "taste": ["핸드드립", "가벼운 장비"],
    "interest": ["캠핑", "티타늄 머그컵"]
  },
  "correctionAvailable": true,
  "completionReason": "MAX_CYCLES",
  "profileCompleteness": "partial",
  "missingSignals": ["dislikes"]
}

요약문 생성이 실패해도 200을 반환하고 summary를 null로 둔다. 프로필과 키워드는 모델을 호출하지 않는 서버 규칙의 산출물이므로 함께 실패하지 않는다.

correctionAvailable이 false이면 이미 정정 대화를 한 번 사용한 세션이다. 프론트엔드는 이 값으로 정정 버튼의 노출 여부를 정한다.

POST /v1/recommendations/jobs · 기능 4 리스트 생성

사용자가 확인 화면에서 프로필을 승인하면 백엔드가 호출한다. self·gift 두 리스트 생성을 하나의 잡으로 등록하고, 같은 시점에 세션 원문 삭제를 병렬로 실행한다. 삭제 완료를 기다리지 않고 202를 반환한다.

{
  "userId": "u_10293",
  "sessionId": "s_7a2b",
  "profile": { "...": "TasteProfile" },
  "feedbackSummary": null
}

202 Accepted

{ "jobId": "j_9c4d", "status": "pending", "pollAfterMs": 1000, "estimatedMs": null }

원문 삭제가 실패해도 잡 등록은 진행한다. 삭제 실패는 로그로 남기며, 세션 TTL이 최종 삭제를 보장한다.

검색용 항목이 없어도 불완전 프로필을 422로 되돌리지 않고 잡을 등록한다. worker는 빈 추천 결과와 emptyReason: NO_PROFILE_SIGNAL로 정상 완료한다.

GET /v1/recommendations/jobs/{jobId} · 기능 4 리스트 생성

잡의 진행 상태와 결과를 조회한다. 완료 응답에 self·gift 두 리스트가 함께 담긴다. 결과는 완료 후 10분간 보관하고 지운다.

요청 본문과 쿼리 파라미터가 없다.

200 OK. status에 따라 본문이 달라진다.

공통 필드와 상태별 필드 타입은 다음과 같다.

RecommendationLists는 키가 고정된 객체다.

JobError 타입은 다음과 같다.

{
  "jobId": "j_9c4d",
  "status": "succeeded",
  "lists": {
    "self": { "...": "추천 공통 응답 (mode: self)" },
    "gift": { "...": "추천 공통 응답 (mode: gift)" }
  }
}

{ "jobId": "j_9c4d", "status": "running", "progress": 0.6, "pollAfterMs": 1000 }

{
  "jobId": "j_9c4d",
  "status": "failed",
  "error": { "code": "RECOMMENDATION_FAILED", "message": "추천 리스트 생성에 실패했습니다", "retryable": true }
}

잡 자체의 실패는 HTTP 오류가 아니라 200 응답의 status: "failed"로 전달한다. 폴링 경로에서 조회 실패와 잡 실패를 구분하기 위해서다. retryable이 참이면 백엔드가 같은 프로필로 POST /v1/recommendations/jobs를 다시 호출할 수 있다. 프로필은 이미 백엔드에 저장되어 있으므로 대화를 다시 하지 않아도 된다.

프로필은 이 응답에 담기지 않는다. 확정 시점에 백엔드가 이미 저장했기 때문이다.

POST /v1/recommendations · 기능 4 추천 리스트 재생성

저장된 프로필로 한 모드의 리스트를 다시 만든다. 화면 진입 시 호출하는 엔드포인트가 아니다.

FeedbackSummary가 포함되면 아래 다섯 배열을 모두 보내며 값이 없으면 빈 배열을 사용한다.

{
  "userId": "u_10293",
  "mode": "gift",
  "profile": { "...": "TasteProfile 전체" },
  "excludeCategories": ["주류"],
  "excludeProductIds": ["p_881"],
  "feedbackSummary": {
    "likedProductIds": ["p_402"],
    "dislikedProductIds": ["p_119"],
    "alreadyHaveProductIds": ["p_555"],
    "hiddenProductIds": [],
    "dislikedSignals": ["캠핑 조명"]
  },
  "limit": 20
}

200 OK와 추천 공통 응답을 반환한다. items가 빈 배열이어도 성공 응답이며 emptyReason으로 원인을 구분한다.

LLM_UNAVAILABLE은 이 엔드포인트에서 발생하지 않는다. 추천 이유 생성이 실패하면 기본 문구로 대체하고 추천은 그대로 반환한다.

POST /v1/recommendations/{recommendationId}/feedback · 기능 5 피드백 수집

사용자가 추천 상품에 남긴 반응을 받아, 백엔드가 프로필과 제외 목록에 반영할 변경을 알려준다.

FeedbackMatchedSignal은 추천 응답의 MatchedSignal 전체가 아니라 귀인에 필요한 최소 필드만 받는다.

{
  "productId": "p_1234",
  "action": "already_have",
  "matchedSignals": [
    { "field": "interests", "value": "캠핑장에서 핸드드립", "tasteNodeId": "outdoor.camping.camping_coffee" }
  ]
}

FeedbackEffect는 target에 따라 필드가 달라지는 tagged union이다.

현재 확정된 change 값은 exclude와 move_to_owned뿐이다. 반복 dislike처럼 확신도를 낮추는 경우의 change 열거형과 confidenceChange 조정 폭은 아직 미확정이다.

{
  "accepted": true,
  "appliedToRanking": true,
  "effects": [
    { "target": "product", "productId": "p_1234", "change": "exclude" },
    { "target": "profile_item", "value": "캠핑장에서 핸드드립", "change": "move_to_owned", "confidenceChange": 0.0 }
  ]
}

GET /v1/catalog/coverage · 기능 6 카탈로그 운영

내부 운영용 엔드포인트다. 취향 노드 대비 상품이 부족한 구간을 알려준다.

CoverageGap 타입은 다음과 같다.

{
  "generatedAt": "2026-09-02T06:00:00Z",
  "totalProducts": 8420,
  "totalNodes": 312,
  "nodeCoverage": 0.71,
  "gaps": [
    { "nodeId": "hobby.craft.leather", "productCount": 8,  "bandsCovered": 1, "priority": "high" },
    { "nodeId": "pet.cat.toy",         "productCount": 21, "bandsCovered": 2, "priority": "medium" }
  ]
}

상품 개수만 세면 이미 많은 카테고리를 계속 더 수집하게 된다. gaps는 노드별 가격대 분포(bandsCovered)를 함께 보고 다음 수집 대상을 정한다.

아직 백엔드와 연결하지 않아 실제 호출 테스트는 진행하지 않았다. 아래 응답은 스키마 확인을 위해 작성한 예시이며 실행 결과가 아니다.

# 1) 세션 생성
curl -X POST https://ai.needu.internal/v1/chat/sessions \
  -H "Authorization: Bearer $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userId":"u_10293","existingProfile":null,
       "onboarding":{"seedCategories":["아웃도어"],"excludeCategories":[],"constraints":[]}}'
# → 201 { "sessionId": "s_7a2b", "greeting": "...", "maxTurns": 20 }

# 2) 턴 전송 (SSE)
curl -N -X POST https://ai.needu.internal/v1/chat/sessions/s_7a2b/messages \
  -H "Authorization: Bearer $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"주말마다 캠핑 가요"}'
# → event: token / event: done

# 3) 종료 및 프로필 확정
curl -X POST https://ai.needu.internal/v1/chat/sessions/s_7a2b/close \
  -H "Authorization: Bearer $SERVICE_TOKEN"
# → 200 { "profile": {...}, "summary": "...", "keywords": {...}, "correctionAvailable": true }

# 4) 사용자 승인 후 리스트 생성 등록
curl -X POST https://ai.needu.internal/v1/recommendations/jobs \
  -H "Authorization: Bearer $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userId":"u_10293","sessionId":"s_7a2b","profile":{...}}'
# → 202 { "jobId": "j_9c4d", "status": "pending", "pollAfterMs": 1000 }

# 5) 리스트 생성 결과 폴링
curl https://ai.needu.internal/v1/recommendations/jobs/j_9c4d \
  -H "Authorization: Bearer $SERVICE_TOKEN"
# → 200 { "status": "succeeded", "lists": {...} }

# 6) 리스트 재생성
curl -X POST https://ai.needu.internal/v1/recommendations \
  -H "Authorization: Bearer $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request.json
# → 200 { "recommendationId": "r_5f6g", "items": [...], "funnel": {...} }

# 6) 피드백
curl -X POST https://ai.needu.internal/v1/recommendations/r_5f6g/feedback \
  -H "Authorization: Bearer $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"productId":"p_1234","action":"already_have"}'

프론트엔드에서 AI 서버로 가는 경로가 없으므로 AI 서버는 백엔드 서버와만 연결된다.

클라우드 담당에게 필요한 것은 다음과 같다.

• AI 서버용 프라이빗 서브넷과 백엔드로부터의 인바운드 규칙
• PostgreSQL(pgvector 확장 포함) 인스턴스와 Redis
• 카탈로그 배치용 스케줄러 (수집·속성추출·임베딩)
• 시크릿 매니저
• SSE를 지원하는 로드밸런서 설정 (응답 버퍼링 비활성화)

이 문서는 계약만 정한다. 계약을 구현하는 방법은 다음 단계에서 하나씩 정한다.

계약을 먼저 정한 이유는, 위 다섯 가지가 전부 바뀌어도 백엔드가 부르는 엔드포인트와 주고받는 스키마가 그대로이기 때문이다.