frontend-sync

프론트엔드 타입 동기화 워크플로우

백엔드 DTO가 변경되었습니다. 프론트엔드와 동기화를 확인해야 합니다.

1. 변경된 DTO 확인

변경된 백엔드 DTO 파일 식별:

• *Request.java
• *Response.java

2. 프론트엔드 타입 매핑

3. 불일치 점검

각 필드별로 확인:

• 필드명 일치 (camelCase)
• 필드 타입 일치 (Long → number, String → string, List → array)
• Optional 여부 일치 (nullable → ?)
• 중첩 객체 구조 일치

주의할 패턴

4. 프론트엔드 수정 (필요시)

타입 수정

app/frontend/src/types/index.ts 업데이트

API 클라이언트 수정 (필요시)

app/frontend/src/lib/api/*.ts 확인

컴포넌트 수정 (필요시)

변경된 필드를 사용하는 컴포넌트 확인:

• 필드명 변경: parentId → parentScenarioId
• 중첩 구조 변경: response.email → response.user.email

5. 빌드 검증

cd app/frontend
npm run build

TypeScript 컴파일 에러가 없어야 함.

완료 조건

• 백엔드 DTO와 프론트엔드 타입 일치 확인
• 필요한 타입 수정 완료
• 관련 컴포넌트/API 클라이언트 수정 완료
• npm run build 성공
• 이 조건 충족 전까지 DTO 변경 작업 미완료로 간주

API 계약 규칙 (중요)

CLAUDE.md 및 docs/architecture.md 참조:

• 요청: excludedCourseIds (Long 배열)
• 응답: excludedCourses (courseId 포함 객체 배열)

이 규칙을 위반하는 변경은 허용되지 않음.

에러 응답 동기화 워크플로우

백엔드 에러 처리가 변경되었거나, 프론트엔드 에러 표시를 확인해야 합니다.

6. ErrorResponse 구조 확인

통일된 에러 응답 구조

모든 백엔드 서비스는 동일한 구조 사용:

// GlobalExceptionHandler의 ErrorResponse
public record ErrorResponse(int status, String message) {}

프론트엔드 타입

// src/types/index.ts
interface ApiError {
  status: number;
  message: string;
}

7. 에러 처리 체크리스트

백엔드 확인

• 새 예외 클래스가 GlobalExceptionHandler에 등록되었는가?
• 적절한 HTTP 상태 코드 반환 (400, 401, 404, 409 등)
• 사용자 친화적 한글 메시지 포함

프론트엔드 확인

• API 호출부에서 에러 파싱: error.response?.data?.message
• 사용자에게 백엔드 메시지 표시 (고정 메시지 금지)
• HTTP 상태별 분기 처리 (필요시)

8. 에러 상태별 처리 가이드

9. 에러 처리 패턴

올바른 패턴 ✅

// React Query useMutation
onError: (error: AxiosError<ApiError>) => {
  const message = error.response?.data?.message || '오류가 발생했습니다';
  toast.error(message);
}

// try-catch
try {
  await api.call();
} catch (error) {
  const axiosError = error as AxiosError<ApiError>;
  const message = axiosError.response?.data?.message || '오류가 발생했습니다';
  toast.error(message);
}

금지된 패턴 ❌

// 고정 메시지 사용 금지
onError: () => {
  toast.error('실패했습니다. 다시 시도해주세요.');
}

// 에러 객체 무시 금지
catch (error) {
  toast.error('오류가 발생했습니다');
}

완료 조건 (에러 처리)

• ErrorResponse 구조가 모든 서비스에서 통일됨
• 프론트엔드 ApiError 타입 정의됨
• 모든 API 호출부에서 백엔드 메시지 파싱
• 고정 에러 메시지 사용 없음
• 이 조건 충족 전까지 에러 처리 변경 작업 미완료로 간주