🔀 :: (#72) - 알림 목록 API 연동

[leesengjun]

개요

Student App의 알림 목록 화면에 실제 알림 목록 API를 연동했습니다.

기존 Mock/로컬 데이터를 Swagger 기준 실제 API 응답으로 교체하고,
기존 Figma 알림 UI 구조를 유지하면서 전체 / 읽지 않음 탭이 서버 데이터를 기준으로 동작하도록 연결했습니다.

관련 이슈

• [FEATURE] 알림 목록 API 연동 #72

작업 내용

알림 목록 API 연동

• GET /api/v1/notifications API 연동
• 기존 Notification Feature 구조에 실제 API 데이터 연결
• 기존 Mock/로컬 알림 목록 조회 로직 교체
• 기존 Network / Repository / ViewModel 구조 유지

전체 / 읽지 않음 탭

• 전체 탭
  • unreadOnly=false
• 읽지 않음 탭
  • unreadOnly=true

현재 페이지의 데이터를 클라이언트에서 임의로 필터링하지 않고,
서버의 unreadOnly Query를 사용하도록 연결했습니다.

알림 응답 처리

다음 응답 데이터를 기존 알림 UI 모델에 연결했습니다.

• notificationId
• notificationType
• title
• content
• targetType
• targetId
• targetAvailable
• targetUnavailableReason
• deepLink
• read
• readAt
• createdAt

nullable 필드는 Swagger 기준으로 안전하게 처리했습니다.

Pagination / unreadCount

알림 목록 응답의 Pagination 정보를 처리합니다.

• page
• size
• totalElements
• totalPages
• first
• last
• unreadCount

unreadCount는 현재 페이지나 현재 필터 결과를 기준으로
클라이언트에서 다시 계산하지 않고 서버 응답 값을 그대로 사용합니다.

대상 접근 상태

서버에서 계산해 내려주는 다음 값을 기준으로 처리합니다.

• targetAvailable
• targetUnavailableReason
• deepLink

알림 대상 공고/프로그램 등의 상태를 확인하기 위해
클라이언트에서 별도의 API를 추가 호출하거나 상태를 재계산하지 않습니다.

기존 Figma에 존재하는 대상 삭제 / 접근 불가 상태 UI를 유지했습니다.

기존 UI 상태 유지

기존 Figma 알림 UI를 그대로 사용합니다.

• 전체 알림
• 읽지 않은 알림
• Empty
• Loading
• Network Error
• 대상 삭제
• 접근 불가

새로운 화면이나 UI는 추가하지 않았습니다.

이번 PR에서 제외한 작업

이번 PR은 알림 목록 조회만 담당합니다.

아래 기능은 포함하지 않습니다.

• PATCH /api/v1/notifications/read
• 단건 알림 읽음 처리
• 전체 알림 읽음 처리
• GET /api/v1/notifications/unread-count
• DELETE /api/v1/notifications/{notificationId}
• 알림 삭제
• FCM
• Push Notification 수신
• Deep Link Navigation 신규 구현
• 로그인 / 인증 기능 구현
• Access Token 하드코딩
• 새로운 UI 추가
• 불필요한 Architecture 리팩토링

테스트

• 알림 목록 DTO Parsing
• nullable 필드 Parsing
• Pagination 응답 Parsing
• unreadCount Parsing
• unreadOnly=false Query 전달
• unreadOnly=true Query 전달
• Loading → Success
• Loading → Empty
• Loading → Network Error
• 전체 알림 UI
• 읽지 않음 알림 UI
• 대상 삭제 상태
• 접근 불가 상태
• flutter analyze
• 관련 Notification 테스트
• 전체 flutter test
• git diff --check
• 실제 로그인 상태 서버 200 응답 테스트

확인 필요 사항

현재 로그인 기능이 완료되지 않아 유효한 Access Token을 사용한
GET /api/v1/notifications 실제 서버 200 응답 통합 테스트는 진행하지 못했습니다.

Swagger 기준 API Contract와 Fake Repository / DTO / ViewModel / UI 테스트를 통해
구현을 검증했으며, 로그인 기능이 develop에 병합된 이후 실제 계정으로 다음 항목을 확인할 예정입니다.

• 실제 알림 목록 조회
• 전체 / 읽지 않음 Query 동작
• 실제 notificationType
• 실제 unreadCount
• 삭제된 대상 상태
• 접근 불가 대상 상태
• nullable 데이터
• Pagination
• 실제 서버 Error Response

[minwoo0708]

Correctness: "읽지 않음" 탭에서 알림을 읽음 처리해도 더 이상 목록에서 사라지지 않습니다.

기존에는 NotificationFilter.unread가 선택되었을 때 visibleNotifications가 !isRead로 필터링했지만, 지금은 서버의 unreadOnly 쿼리에 의존하며 notifications를 필터링 없이 그대로 반환합니다. 그런데 markAsRead / markAllAsRead는 이미 로드된 목록의 isRead 플래그만 로컬에서 바꿀 뿐, 항목을 제거하거나 다시 불러오지 않습니다.

실패 시나리오: 사용자가 읽지 않음 탭(unreadOnly=true로 조회)을 연 상태에서 NotificationCard를 탭합니다. handleNotificationTap이 markAsRead(id)를 호출해 로컬에서 isRead=true로 바꾸고 unreadCount를 줄이지만, 카드는 (읽음 상태로 스타일만 바뀐 채) 사용자가 탭을 전환해 새로 fetch를 트리거하기 전까지 읽지 않음 탭 목록에 그대로 남아있습니다. 이 PR 이전에는(옛 visibleNotifications getter의 클라이언트 측 필터링) 항목이 즉시 사라졌습니다. PR 설명에서 의도적으로 제외한 PATCH 영속성 문제와는 별개로, 이 PR로 인한 실제 UX 회귀로 보입니다.

[minwoo0708]

Efficiency / Altitude: getNotifications가 반환 전에 서버의 모든 페이지를 순차적으로, 상한 없이 끌어모읍니다.

while (true) 루프가 last가 true가 되거나 nextPage >= totalPages가 될 때까지 _client.getNotifications(page: page, ...)를 한 번에 하나씩 순차적으로 호출하고 기다립니다. 알림이 수백 개인 사용자라면 화면이 로딩 상태를 벗어나기 전까지 수십 번의 순차적 왕복이 발생합니다(첫 응답 이후 totalPages를 알 수 있어 나머지를 Future.wait로 병렬 처리할 수 있음에도 그렇게 하지 않음). 이는 최초 로드, 탭 전환(selectFilter), 재시도 시마다 매번 발생합니다. 또한 가져오는 페이지 수에 상한이 없어서, 서버의 last/totalPages 값이 요청 간에 잘못되거나 일관성이 깨지는 경우 루프에 안전장치가 없어 엔드포인트를 계속 호출하게 됩니다.

결과적으로 페이지네이션 API의 목적이 무색해지고, 화면을 방문할 때마다 "전부 다 가져오기" 단일 호출처럼 동작하게 됩니다.

[minwoo0708]

Correctness / robustness: (여러 페이지에 걸친) 결과 중 알림 하나라도 형식이 잘못되면 전체 fetch가 폐기되고 일반적인 "네트워크 오류"가 표시됩니다.

notificationId, title, content, targetAvailable, isRead, createdAt 중 하나라도 null이면 _toDomain이 FormatException을 던지는데, 이 필드들은 모두 NotificationSummaryResponseDto에서 nullable로 모델링되어 있습니다(PR 설명에도 "nullable 필드는 Swagger 기준으로 안전하게 처리했습니다"라고 명시). 이 로직이 getNotifications의 페이지네이션 루프 안에서 실행되기 때문에, 가져온 모든 페이지 중 어딘가에 있는 알림 하나가 이 필드 중 하나라도 누락되면(예: title/content가 없는 SYSTEM 알림, 혹은 Swagger 계약상 실제로 옵셔널한 필드) 예외가 발생해 이미 가져온 모든 페이지가 폐기됩니다. 이후 view model의 포괄적인 on Object catch가 NotificationScreenStatus.networkError를 표시하는데, 이는 오해의 소지가 있습니다 -- 실제로는 네트워크 장애가 아니라 데이터/계약 문제이며, 사용자는 문제가 된 항목 하나가 아니라 전체 알림 목록을 잃게 됩니다.