Skip to content

Frontend Candidate Profile Guide

Jump to bottom
tuna edited this page Sep 14, 2026 · 1 revision

매칭 후보 프로필·소개노트 열람 가이드 (프론트)

상태: 배포 완료 (#173 · 이슈 #172 / #174 · 이슈 #171). 인증 헤더·응답 래핑 등 공통 규약은 Frontend-Chat-Guide를 볼 것. 그룹 후보 조회·수락·거절 자체는 Frontend-Group-Matching-Guide에 있다.

한눈에

성사 전 후보에게도 소개노트가 열렸다. BE-Request — 매칭 후보 소개노트 열람 권한 (P0) 처리 결과다.

  • GET /api/v1/users/{id}/intro-notes — 후보 단계에서 미리보기 3문항이 내려온다. 경로·스키마 변경 없음.
  • 1:1 후보와 그룹 후보 모두 같은 규칙이다.
  • 프로필 상세 API(/users/{id}/profile·/ratings·/answers)는 여전히 성사 후 전용이다. 후보 카드에 필요한 정보는 후보 목록 응답에 이미 다 들어 있으니 그대로 쓰면 된다.

관계별 공개 범위

관계 소개노트 프로필 상세 · 받은 평가 · 답변 일치
본인 전체 10문항 — (/users/me 계열)
매칭 성사 · 같은 그룹 채팅 참여 전체 10문항 열림
이번 주 매칭 후보 (성사 전) 미리보기 3문항 403 / 0003
그 외 · 차단 관계 403 / 0003 403 / 0003

후보 판정 기준

서버가 "조회자가 최근 완료(COMPLETED)한 퀴즈셋"을 기준으로 판정한다. 퀴즈셋을 FE가 넘길 필요는 없다.

타입 기준 후보로 보는 조건
1:1 내가 최근 완료한 1:1 퀴즈셋 그 퀴즈셋의 후보 페어에 둘이 함께 있음 (GET /api/v1/matches/1on1의 candidates[].userId)
그룹 내가 최근 완료한 그룹 퀴즈셋 같은 후보 그룹에 둘 다 거절하지 않은 채 남아 있음 (GET /api/v1/matches/group의 groups[].members[].userId)

둘 중 하나라도 맞으면 열린다. 실무적으로는 후보 목록 응답에 있는 userId면 소개노트가 열린다고 보면 된다.

  • 지난 주 후보는 닫힌다. 다음 주 퀴즈셋을 완주하는 순간 기준이 옮겨가 이전 주 후보는 403이 된다. 매칭 주가 지난 뒤 열어 둔 화면에서 재조회하면 빈 카드가 아니라 403이 날 수 있으니, 목록을 다시 받아 화면을 맞추는 편이 안전하다.
  • 차단하면 후보여도 막힌다. 내가 차단했든 상대가 나를 차단했든 403이다(피그마 6.2.2).
  • 그룹에서 내가 거절했거나 자동 거절된 그룹의 구성원은 후보가 아니다 — 후보 목록에서 사라지는 것과 같은 타이밍에 소개노트도 닫힌다.

REST

1) 소개노트 조회 (후보 미리보기)

GET /api/v1/users/{id}/intro-notes

{
  "success": true,
  "data": {
    "answers": [                                  // 성사 전이면 최대 3개, 성사 후면 10개
      { "questionCode": "stress-relief",
        "question": "스트레스 받을 때 나만의 해소법은?",
        "answer": "무조건 걷습니다" },
      { "questionCode": "most-used-apps",
        "question": "요즘 내가 가장 많이 쓰는 앱 3개는?",
        "answer": "지도, 캘린더, 메모" },
      { "questionCode": "one-word",               // 항상 마지막 칸
        "question": "나를 한 줄로 표현한다면?",
        "answer": "느긋한 편이에요" }
    ],
    "completedCount": 3                           // 이 응답에 담긴 답변 중 작성된 수
  }
}

미리보기 구성은 무작위 2문항 + one-word 고정이다. 요청서 §2-1의 (b)안을 골랐다.

  • one-word는 항상 마지막에 온다. 상대가 안 썼어도 answer: ""로 포함된다 — 화면 마지막 칸 계약을 지키기 위해서다.
  • 무작위 2문항은 상대가 실제로 작성한 답변 중에서만 뽑는다. 빈 카드로 슬롯을 낭비하지 않는다. 따라서 상대가 one-word 외에 아무것도 안 썼으면 answers는 1개짜리로 온다. answers.length === 3을 가정하지 말 것.
  • answers는 항상 고정 질문 순서(문항 정의 순)로 정렬돼 온다. 무작위로 섞여 오지 않는다.
  • 같은 상대는 매번 같은 3문항이 온다. (조회자, 대상자) 쌍으로 결정적이라 새로고침해도 화면이 바뀌지 않는다. 사람마다 조합은 다르다. 단 상대가 새 답변을 작성하면 뽑기 대상이 늘어 조합이 바뀔 수 있다.
  • FE가 다시 3개로 자르지 말 것. 서버가 이미 잘라서 내려준다. 성사 후에는 10문항이 그대로 오므로, 개수로 성사 여부를 판단하지 말고 화면 상태(후보/성사)로 분기하는 게 맞다.
  • completedCount는 이 응답에 담긴 것 중 작성된 수다. 성사 전에는 최대 3이라 "10문항 중 N개 작성" 같은 표시에 쓰면 안 된다.

성사 후에는 같은 경로로 10문항 전량이 온다. 아래 "대화가 시작되면 더 많은 질문과 답변을 볼 수 있어요" 문구는 성사 전에만 붙이면 된다.

2) 그룹 구성원 프로필 — 후보 목록 응답을 쓴다

후보 단계에서 구성원 프로필 상세 API를 호출하지 말 것. 403이다. 프로필 선택 화면에 필요한 값은 GET /api/v1/matches/group 응답의 groups[].members[]에 전부 들어 있다.

화면 요소 필드
닉네임 members[].nickname
성별 · 나이 members[].gender · age (둘 다 null 가능)
한 줄 소개 members[].introduction (소개노트 one-word 답변, null 가능)
지역 members[].location
캐리커쳐 members[].profileImageUrl
"12개중 8개 일치" members[].scoreBreakdown.matchedQuestions / totalQuestions

응답 전문과 점수 두 종류(그룹 평균 vs 개인별)의 차이는 Frontend-Group-Matching-Guide를 볼 것. 1:1 후보(GET /api/v1/matches/1on1의 candidates[])도 같은 카드 스키마를 쓴다.

즉 후보 단계 프로필 화면 = 후보 목록의 카드 + 소개노트 3문항이고, 서버 호출은 소개노트 하나만 추가로 하면 된다.

3) 성사 후에만 열리는 것

API 내려주는 것
GET /api/v1/users/{id}/profile 닉네임·성별·나이·한 줄 소개·캐리커쳐·지역·직업·관심사·평점
GET /api/v1/users/{id}/ratings 상대가 받은 평가 (공개 기준 3건 미달이면 비공개)
GET /api/v1/users/{id}/answers 나와의 퀴즈 답변 일치 요약

셋 다 판정 지점이 같아서 한꺼번에 열리고 한꺼번에 닫힌다. 성사 전에는 셋 다 403이다.

후보 카드에 없는 값은 직업·관심사·평점 셋뿐이다. 지금 FE가 후보 목록으로 폴백해 이 셋을 비워 두는 동작(useUserProfile)은 그대로 유지하면 된다. 요청서 §2-2에서 우선순위를 낮게 두신 항목이라 이번 범위에 넣지 않았다 — 필요하면 별도 요청서로 주시면 받는다. ratings는 요청대로 성사 전 계속 닫아 뒀다.

화면 분기

후보 단계 (성사 전)
  카드 정보  ← GET /api/v1/matches/group  또는  /matches/1on1  (이미 받은 응답 재사용)
  소개노트   ← GET /api/v1/users/{id}/intro-notes   → 3문항 + 안내 문구
  프로필 상세 API 호출 없음

성사 후
  프로필     ← GET /api/v1/users/{id}/profile
  평가·일치  ← GET /api/v1/users/{id}/ratings · /answers
  소개노트   ← GET /api/v1/users/{id}/intro-notes   → 10문항, 안내 문구 없음

에러 코드

code HTTP 언제 FE 처리
0003 403 후보도 성사 상대도 아님 / 차단 관계 / 지난 주 후보 빈 카드 대신 목록 재조회. 그래도 없으면 안내 문구
0004 404 없는 회원 목록 재조회

지금 FE는 403을 조용히 삼켜(IntroNoteContainer) 빈 카드를 띄우고 있다. 후보 구간이 열렸으니 정상 경로에서는 403이 나오지 않지만, 매칭 주가 지나 기준 퀴즈셋이 옮겨간 경우에는 여전히 403이 날 수 있다. 이 경우만 안내 문구로 처리하면 된다.

알아둘 것

  • 성사 후 소개노트에는 차단 검사가 없다. 차단 관계면 프로필 상세는 403인데 소개노트는 200으로 열린다(성사 전 구간만 이번에 차단을 반영했고, 성사 후는 기존 동작을 유지했다). 화면에서 차단 상대를 가려야 한다면 지금은 FE 쪽 판단이 필요하다. 서버에서 맞출지는 별도로 정한다.
  • 미리보기 문항은 사람마다 다르다. A가 보는 C의 3문항과 B가 보는 C의 3문항은 다를 수 있다. 캐시 키를 상대 userId만으로 잡아도 되지만, 서로 다른 계정으로 로그인해 확인할 때 같은 결과를 기대하지 말 것.
  • 1:1과 그룹의 기준 퀴즈셋이 따로 논다. 각각 "최근 완료한 해당 타입 퀴즈셋"이라, 1:1 후보와 그룹 후보가 동시에 열려 있을 수 있다.

요청서 회신 (BE-Request-Intro-Notes §4)

  • 매칭 후보에게 intro-notes를 열어 줄 수 있나 → 예
  • (a) 전량 / (b) 3문항 → (b) (one-word 항상 포함, 화면 마지막 칸 고정)
  • "후보" 판정 기준 → 조회자가 최근 완료한 퀴즈셋의 후보. 다음 주 퀴즈셋을 완주하면 지난 주 후보는 닫힘
  • 그룹 매칭 대상자도 같은 규칙인가 → 예 (#171에서 그룹 후보 생성이 붙으며 같이 맞췄다)
  • GET /users/{id}/profile도 함께? → 이번 범위 아님. 필요하면 별도 요청서로. ratings는 요청대로 성사 전 계속 닫음
  • 예상 일정 → 완료 (#173 · #174 머지됨)

Clone this wiki locally