BE Request Weekly Matching Type

BE 개발 요청서 — 매칭 후보가 "이번 주 것"인지 알려 주세요

작성: 2026-09-14 · FE 담당: @junseo2323 대상: ditto-develop/ditto-server 관련: Frontend-Group-Matching-Guide (이슈 #171 · PR #174) · BE 개발 요청서 — 매칭 후보 소개노트 열람 권한 · FE 브랜치 feat/s3-migration 요청 2건 · [확장] + [확인] · P1

---

요약

#	항목	태그	우선	지금 상태
1	매칭 후보 응답에 그 퀴즈셋의 주차를 넣어 주세요	확장	P1	FE가 quizSetId 크기로 추측 중 — 틀리는 경우가 있습니다
2	어드민이 한 주에 퀴즈셋을 2개 만들면 /quiz-progress/current 가 500입니다	확인	P3	생성 시 막지 않음

전제: 운영은 한 주에 한 종류입니다 — 이번 주 1:1, 다음 주 그룹 식으로 번갈아 갑니다. 이 문서는 그 전제 위에서 씁니다.

---

1. 매칭 후보 응답에 주차를 넣어 주세요 (P1)

왜 — 격주 운영이면 매주 지난 사이클 데이터가 딸려 옵니다

그룹 매칭이 후보 그룹 수락/거절 방식으로 바뀌면서(PR #174) FE는 홈에서 두 엔드포인트를 같이 호출합니다.

GET /api/v1/matches/1on1   → findLatestCompletedQuizSet(memberId, ONE_TO_ONE)
GET /api/v1/matches/group  → findLatestCompletedQuizSet(memberId, GROUP)

둘 다 "내가 최근 완주한 <타입> 퀴즈셋" 을 타입별로 독립해서 찾습니다. 주차를 보지 않습니다. 그래서 격주로 번갈아 가는 운영에서는 매주, 반대 타입 엔드포인트가 지난 사이클 후보를 200으로 돌려줍니다.

10주차 = 그룹 → 11주차 = 1:1 인 경우 11주차 매칭 기간에

• /matches/1on1 → 11주차 후보 ✅
• /matches/group → 10주차 후보 ⚠️ (응답 안 한 그룹은 myStatus: PENDING 으로, 수락했던 그룹은 ACCEPTED/isFormed 로 계속 내려옵니다. 거절한 것만 빠집니다)

후보 행이 지난 주 것도 남는다는 건 PR #173 설명에도 있는 내용입니다 ("후보 행은 지난 주 것도 남기 때문에 퀴즈셋으로 좁히지 않으면 열람 권한이 영구히 열린다"). 같은 성질이 매칭 결과 화면에도 그대로 나타납니다.

지금 FE는 이렇게 추측하고 있습니다

// src/app/home/MainSection.tsx
// quizSetId 가 큰 쪽이 이번 주일 것이다 — 어디까지나 추측
const groupIsThisWeek =
  groupResult !== null &&
  (candidateResult === null ||
    Number(groupResult.quizSetId) >= Number(candidateResult.quizSetId));

서버의 정본 기준은 quizSet.endDate DESC 인데 응답에 endDate 가 없어 같은 기준으로 비교할 수 없습니다.

이 추측이 실제로 틀리는 경우 (지금 있는 버그입니다)

이번 주 퀴즈를 건너뛴 회원입니다.

10주차(그룹) 완주 · 후보에 응답 안 함 → 11주차(1:1) 퀴즈를 안 품 11주차 매칭 기간:

• /matches/1on1 → 404 0004 (완주한 1:1 퀴즈셋이 없음)
• /matches/group → 10주차 그룹 후보 200

→ 비교 대상이 없어 FE는 10주차 그룹 카드를 이번 주 결과로 그립니다. 이번 주에 참여도 안 했는데 "이번주 매칭" 카드에 지난 주 그룹이 뜹니다.

두 번째로, 어드민이 다음 주 퀴즈셋을 미리 만들어 두면 id 순서와 endDate 순서가 어긋나 비교 자체가 깨집니다.

FE에서 자체 해결이 안 되는 이유

"이번 주 퀴즈셋 id를 받아서 대조하면 되지 않나" 를 먼저 검토했는데, 매칭 기간에는 그 값을 받을 수 없습니다.

• GET /quiz-sets/current-week → findCurrentWeekActive(now) → startDate <= now <= endDate
• 매칭 배치는 목 05:00에 endDate < now 인 퀴즈셋을 잡습니다(MatchingScheduler, findEndedQuizSetsWithoutCandidates)
• 즉 퀴즈셋의 endDate 는 목 05:00 이전이어야 하고, 그래서 매칭·대화 기간에는 findCurrentWeekActive 가 빈 배열입니다

결국 매칭 기간에 "이번 주 퀴즈셋이 무엇인지" 물어볼 곳이 없습니다.

요청 — year / month / week 가 가장 좋습니다

MatchCandidateResponse 와 GroupCandidateResponse 양쪽에 추가해 주세요.

// GET /api/v1/matches/1on1  ·  GET /api/v1/matches/group
{
  "quizSetId": 10,
  "year": 2026,          // ← 대상 퀴즈셋의 운영 주
  "month": 9,
  "week": 2,
  ...
}

이 모양을 선호하는 이유: FE는 홈 진입 때 이미 GET /api/v1/system/state 를 부르고 있고, 그 응답이 { year, month, week, period } 입니다. 같은 키로 오면 추가 요청 없이 한 줄 비교로 끝납니다. 서버에도 OperationWeek.containing(...) 이 이미 있으니 CurrentWeekQuizSetsResponse 와 같은 방식이면 됩니다.

대안도 괜찮습니다. 편하신 쪽으로 주시면 FE가 맞추겠습니다.

// (대안 a) 퀴즈셋 종료 시각 — 서버가 정렬에 쓰는 값 그대로
{ "quizSetId": 10, "quizSetEndDate": "2026-09-09 23:59:59", ... }

// (대안 b) 서버가 아예 판정
{ "quizSetId": 10, "isCurrentWeek": true, ... }

또는 아예 안 내려주기: 대상 퀴즈셋이 이번 주가 아니면 0004 로 닫아 주셔도 FE는 깔끔합니다. 다만 매칭 기간이 주 경계를 어떻게 넘는지(금 00:00 채팅 개방 이후 등)는 서버 판단이라, 값만 주시는 쪽을 우선으로 요청드립니다.

---

2. 한 주에 퀴즈셋이 2개면 500 (확인, P3)

운영이 한 주 한 종류라 평상시엔 닿지 않습니다. 다만 막아 두는 곳이 없어 남겨 둡니다.

• AdminQuizService.createQuizSet 은 validatePeriodWithinOneWeek 만 봅니다 — 기간이 한 운영 주 안인지만 보고, 같은 주에 퀴즈셋이 이미 있는지는 보지 않습니다.

• 그 상태에서 회원이 두 퀴즈셋에 모두 답하면(validateNotCompleted 는 그 퀴즈셋 재완주만 막습니다) quiz_progress 행이 2개 생기고,

• GET /api/v1/quiz-progress/current 가 부르는 findActiveProgress 가

  if (progresses.size > 1) {
      log.error { "한 주에 여러 퀴즈셋에 참여한 사용자 발견: ..." }
      throw ErrorException(ErrorCode.INTERNAL_ERROR)   // 500 / 9999
  }

  로 500 을 던집니다.

증상: FE는 이 오류를 삼켜 진행 상태를 못 읽습니다 — 퀴즈를 다 푼 사람이 "아직 안 푼 사람"으로 보입니다(참여 완료 카드 대신 시작 카드, 참여자 수 0). 회복은 POST /quiz-progress/reset(퀴즈 화면 "새로 풀기") 뿐인데 이번 주 답변을 전부 지웁니다.

요청: 어드민 퀴즈셋 생성 시 "같은 운영 주에 이미 퀴즈셋이 있으면 거부"를 넣어 주시면, findActiveProgress 의 전제가 구조적으로 참이 됩니다. 운영 전환기에 두 개를 둬야 할 일이 있는지에 따라 판단 부탁드립니다.

---

3. 그때까지 FE는

• quizSetId 크기 비교를 유지합니다. 값이 내려오면 그 한 줄만 바꿉니다.
• §1의 "이번 주 퀴즈를 건너뛴 회원" 케이스는 고칠 수단이 없어 그대로 둡니다.
• 그룹 매칭 연동(PR #174 반영)은 이 요청과 무관하게 완료해 두었습니다. 이 문서는 "지난 사이클 후보가 섞여 들어오는 것"만 다룹니다.

---

4. 회신 체크리스트

• 매칭 후보 응답(/matches/1on1, /matches/group)에 대상 퀴즈셋의 주차를 넣어 주실 수 있습니까?
• 모양은 year·month·week(선호) / quizSetEndDate / isCurrentWeek 중 어느 쪽입니까?
• "이번 주가 아니면 0004" 로 닫는 방향도 검토 가능합니까? (선택)
• 어드민 퀴즈셋 생성에 "한 운영 주에 하나" 제약을 넣을 수 있습니까? (§2)
• 예상 일정

---

부록 A. BE 쪽 참고 위치

무엇	파일
타입별 최신 완주 퀴즈셋 (endDate DESC, 주차 무관)	domain/.../quiz/repository/querydsl/QuizSetRepositoryImpl.kt → findLatestCompletedQuizSet
후보 응답 DTO	api/.../match/dto/MatchCandidateResponse.kt · GroupCandidateResponse.kt
후보 조회 서비스	api/.../match/service/MatchCandidateService.kt · GroupCandidateService.kt
이번 주 활성 퀴즈셋 (매칭 기간엔 빈 배열)	QuizSetRepositoryImpl.findCurrentWeekActive (startDate <= now <= endDate)
매칭 배치 (목 05:00, endDate < now)	api/.../match/scheduler/MatchingScheduler.kt
운영 주 계산	domain/.../system/OperationWeek.kt → containing(...)
한 주 진행 판정 (500 지점)	api/.../quiz/service/QuizProgressService.kt → findActiveProgress
어드민 퀴즈셋 생성 검증	api/.../admin/quiz/...AdminQuizService.kt → validatePeriodWithinOneWeek

부록 B. FE 쪽 위치

무엇	파일
1:1/그룹 분기 (추측 지점)	src/app/home/MainSection.tsx → groupIsThisWeek
현재 주차·기간	src/shared/lib/api/externalApi.ts → getExternalSystemState (year/month/week/period)
후보 조회	src/shared/lib/api/externalApi.ts → getExternalMatchCandidates / getExternalGroupCandidates
응답 타입	src/features/matching/api/matchingApi.ts → GetMatchCandidatesResponse / GetGroupCandidatesResponse
진행 조회	src/shared/lib/api/externalApi.ts → getExternalQuizProgress
E2E	cypress/e2e/matching-profile/00-entry.cy.ts · 03-result-group.cy.ts