⚙️ [기능추가][Fuel][API연동] 백엔드 Fuel API 연동 (잔량 조회·거래 내역 페이지네이션)

[EM-H20]

📝 현재 문제점

• api-docs.json 에 Fuel 태그가 신설되며 GET /api/fuel, GET /api/fuel/transactions 2 개 엔드포인트가 확정되었으나 앱에는 아직 연동되어 있지 않음
• 현재 lib/features/fuel/ 는 FuelLocalDataSource 와 local 전용 FuelRepositoryImpl 만 존재하여, 잔량·거래 내역이 모두 디바이스 로컬에서만 관리됨
• 서버는 잔량과 거래 내역의 Source of Truth 를 보유하지만 클라이언트가 이를 조회하지 않으므로, 디바이스 간 동기화·다중 기기 시나리오·서버 트리거 이벤트(STUDY_SESSION 충전, EXPLORATION_UNLOCK 차감) 결과가 앱에 반영되지 못함
• 거래 내역은 서버가 페이지네이션·기간/타입 필터를 제공하지만 앱은 전체 로컬 리스트만 읽고 있어 사용 패턴 확장 시 성능·UX 모두 한계
• 직전 ⚙️[기능추가][Todo] 할일·카테고리 API 백엔드 연동 #77 Todo 가 동일 server-first + cache 폴백 패턴으로 정리되었으므로 Fuel 도 동일 규약을 따라가야 일관성 유지 가능

🛠️ 해결 방안 / 제안 기능

• FuelRemoteDataSource 신설 후 Fuel 태그 2 개 엔드포인트 매핑 (Retrofit)
• FuelRepositoryImpl 을 server-first + cache 폴백 구조로 재구성 (네트워크 성공 시 서버값 캐시 갱신, 실패 시 마지막 캐시 반환)
• 인증 상태(AuthState) 에 따라 server-backed / local-only Repository 를 분기 (게스트는 기존 로컬 동작 유지)
• 로그아웃·회원 탈퇴 시 Fuel 캐시 정리 (Todo 와 동일하게 signOut 훅에서 invalidate)
• 거래 내역 페이지네이션을 도메인·UI 까지 노출하여 향후 무한 스크롤·기간 필터 UI 적용 가능하도록 구조화
• 차감/충전 mutation API 가 백엔드에 없는 현 시점 정책 명시 — 클라이언트의 chargeFuel / consumeFuel 은 서버 액션(타이머 완료·장소 해금) 이후 getFuel 재조회로 동기화하는 흐름을 따른다

⚙️ 작업 내용

API 연동 대상 (총 2 개)

• GET /api/fuel — 연료 잔량 조회 (FuelResponse)
• GET /api/fuel/transactions — 거래 내역 페이지네이션 (FuelTransactionListResponse)
  • Query: type (charge|consume), startDate, endDate, page (기본 0), size (기본 20, 최대 100)

레이어별 작업

• Data Layer
  • fuel_remote_datasource.dart (Retrofit) — 2 개 엔드포인트 정의
  • Response DTO (Freezed + JsonSerializable): FuelResponseModel, FuelTransactionListResponseModel, 페이지네이션 메타(page / size / totalElements / totalPages)
  • FuelRepositoryImpl 재작성 — 서버 우선 조회 → 성공 시 LocalDataSource 캐시 갱신 → 실패(네트워크/401) 시 캐시 폴백
  • LocalFuelRepositoryImpl 분리 — 게스트·오프라인 전용 (기존 동작 보존)
• Domain Layer
  • FuelEntity / FuelTransactionEntity 기존 유지 (필드 동일)
  • FuelTransactionPage 신규 도메인 모델 (페이지네이션 메타 포함)
  • UseCase 확장: GetFuelUseCase, GetFuelTransactionsUseCase (page/size/type/startDate/endDate 인자)
• Presentation Layer
  • fuel_provider.dart — 인증 상태에 따라 Repository 분기 (Todo 패턴 재사용)
  • 로그아웃 / 탈퇴 시 Fuel 캐시 invalidate 훅 등록
  • 거래 내역 화면 (있다면) 페이지네이션 대응, 없다면 후속 이슈로 분리
• Infrastructure
  • ApiEndpoints 에 fuel, fuelTransactions 상수 추가
  • 401 응답은 기존 AuthInterceptor 로 처리 (재발급 큐 재사용)
  • 거래 내역 캐싱 정책 결정 — 최신 페이지 1 회 캐시 vs 전체 누적 vs 미캐싱 (정책 합의 후 구현)

테스트

• FuelRemoteDataSource 직렬화/역직렬화 단위 테스트
• FuelRepositoryImpl server-first / cache fallback / 401 시나리오 테스트
• 인증 분기 Provider 테스트 (게스트·로그인·로그아웃 전환)

문서/체크리스트

• 09_PIPELINE.md 의 spec → plan → execute → TDD → verification 순서 준수
• flutter analyze / flutter test 통과 확인 후 커밋
• 커밋 메시지 feat : Fuel Remote DataSource·Repository 구현(server-first + cache 폴백) #<issue> 형식

비고

• 백엔드에 현재 연료 충전/차감 mutation 엔드포인트가 명세되어 있지 않음 → 본 이슈 범위는 read-only 동기화에 한정
• 서버 트리거(STUDY_SESSION / EXPLORATION_UNLOCK) 이후 클라이언트 재조회 흐름은 본 이슈에서 훅만 마련하고, 트리거 측 통합은 타이머·탐험 이슈에서 처리

🙋‍♂️ 담당자

• 백엔드: 이름
• 프론트엔드: 이름
• 디자인: 이름

[EM-H20]

Guide by SUH-LAB

브랜치

20260525_#79_백엔드_Fuel_API_연동_잔량_조회_거래_내역_페이지네이션

커밋 메시지

백엔드 Fuel API 연동 (잔량 조회·거래 내역 페이지네이션) : feat : {변경 사항에 대한 설명} https://github.com/SpaceStudyShip/SpaceStudyShip-FE/issues/79