⚙️[기능추가][Todo] 할일·카테고리 API 백엔드 연동

[EM-H20]

📝 현재 문제점

• Todo·Category 기능이 현재 SharedPreferences 기반 로컬 전용으로 동작하고 있어 디바이스 간 동기화·서버 백업이 되지 않는다.
• 백엔드에서는 8개 엔드포인트(/api/todos 4개, /api/todo-categories 4개)가 이미 배포 완료되었으나, 프론트엔드에서는 Retrofit 클라이언트·Remote DataSource·통합 Repository 모두 미구현 상태.
• TodoModel 의 JSON 직렬화가 snake_case (scheduled_dates, category_ids) 인 반면, 실제 API 계약은 camelCase (scheduledDates, categoryIds) 라서 바로 연결해도 동작하지 않는다.
• docs/api-specs/02_todo.md 의 오류 코드(INVALID_TITLE, INVALID_DATE_FORMAT, 403 FORBIDDEN)가 실제 API (INVALID_INPUT_VALUE, TODO_NOT_FOUND 404 통일) 와 불일치 — Auth alignment 사이클과 같은 문서 정합화 필요.

🛠️ 해결 방안 / 제안 기능

• Retrofit 기반 TodoRemoteDataSource 신설 — /api/todos 4개 + /api/todo-categories 4개 엔드포인트 매핑.
• TodoModel·TodoCategoryModel 의 JSON 키를 camelCase 로 정렬해 서버 계약과 일치시킴.
• 기존 LocalTodoDataSource 는 캐시 레이어로 재활용, TodoRepositoryImpl 합성 클래스를 신설해 Remote+Local 합성. 동기화 전략은 별도 spec 사이클에서 확정.
• api_endpoints.dart 에 /api/todos, /api/todo-categories 상수 추가.
• 서버 응답 오류 코드(TODO_NOT_FOUND, CATEGORY_NOT_FOUND, TODO_ALREADY_EXISTS, CATEGORY_ALREADY_EXISTS, INVALID_INPUT_VALUE) 를 도메인 예외 또는 사용자 메시지로 매핑.
• docs/api-specs/02_todo.md 를 api-docs.json 최신 계약 기준으로 갱신 (Auth alignment 와 동일 패턴).
• TDD 사이클로 진행 — 단위 테스트(매핑·예외) + 위젯 테스트(로딩·에러 상태) 동반.

⚙️ 작업 내용

• 백엔드 API 명세 확인 및 api-docs.json 기준 도메인 계약 정리
• Retrofit TodoRemoteDataSource 인터페이스 정의 + .g.dart 생성
• TodoModel / TodoCategoryModel JSON 키 camelCase 정렬, 마이그레이션 코드 유지·검증
• TodoRepositoryImpl 신설, LocalTodoRepositoryImpl 는 게스트/오프라인 폴백으로 분기
• todo_provider.dart Provider 체인 갱신 (Remote DataSource → Repository → UseCase → Notifier)
• 에러 envelope (ApiErrorResponse) → 사용자 메시지 매핑 (SpaceSnackBar 연동)
• 02_todo.md 문서 최신 API 계약으로 갱신
• 통합 후 회귀: 기존 category_map_screen, todo_add_bottom_sheet, category_add_bottom_sheet 흐름 그대로 동작 확인

🙋‍♂️ 담당자

• 백엔드: 이수환 (이미 배포 완료)
• 프론트엔드: 이수환
• 디자인: -

[EM-H20]

Guide by SUH-LAB

브랜치

20260523_#77_할일_카테고리_API_백엔드_연동

커밋 메시지

할일·카테고리 API 백엔드 연동 : feat : {변경 사항에 대한 설명} https://github.com/SpaceStudyShip/SpaceStudyShip-FE/issues/77

[EM-H20]

작업 개요

이슈 #77 — Todo / TodoCategory 도메인을 백엔드 API(api-docs.json, 8 엔드포인트)와 연동.
기존 SharedPreferences 단독 LocalRepository 위에 Retrofit 기반 Remote DataSource + 캐시 폴백 Repository 를 얹고,
인증 상태(isAuthenticated)에 따라 Provider 가 Remote/Local 을 자동 선택하도록 분기.
로그아웃 / 회원탈퇴 시 다른 사용자 데이터 오염을 막기 위해 Todo 로컬 캐시도 함께 정리.

구현 목표

• api-docs.json Todo·TodoCategory 8 엔드포인트 클라이언트 추가
• 서버를 source of truth 로 두고, 네트워크 실패 시 로컬 캐시 폴백
• 게스트(미로그인) 사용자는 기존처럼 LocalRepository 만 사용 — 흐름 회귀 없음
• 도메인 에러 코드 4종(TODO_NOT_FOUND, TODO_ALREADY_EXISTS, CATEGORY_NOT_FOUND, CATEGORY_ALREADY_EXISTS) 표준 매핑
• 로그아웃·탈퇴 시 로컬 Todo 캐시 정리

구현 내용

1. 네트워크 인프라

• 파일: lib/core/constants/api_endpoints.dart, lib/core/errors/app_exception.dart, lib/core/network/dio_exception_handler.dart
• Todo · TodoCategory 엔드포인트 상수 추가
• 도메인 Exception 4종 추가: TodoNotFoundException, TodoAlreadyExistsException, CategoryNotFoundException, CategoryAlreadyExistsException
• DioExceptionHandler 의 code 기반 switch 에 위 4 case 매핑 추가
• 이유: 서버가 반환하는 code 를 일관된 예외 타입으로 흡수해야 Repository / UseCase 단에서 분기가 깔끔해짐

2. Model / DTO 정렬

• 파일: lib/features/todo/data/models/ 전반
• 기존 TodoModel, TodoCategoryModel JSON 키를 백엔드 계약(camelCase)에 맞춰 정렬
• 구버전(snake_case 또는 다른 키) 캐시는 자동 마이그레이션 — 사용자 단말 업그레이드 시 로컬 데이터 유실 없음
• Request 전용 DTO 4종 추가
  • TodoCreateRequestModel
  • TodoUpdateRequestModel (PATCH semantics — null 필드는 미수정)
  • CategoryCreateRequestModel
  • CategoryUpdateRequestModel
• 이유: Entity ↔ Model 변환 책임을 Data Layer 안에 가두기 위해 Create/Update 요청 본문은 별도 모델로 분리

특이사항:

• Request DTO 는 fromJson 이 실제로 호출되지 않음 → analyzer "unused" 잡음 발생
• analysis_options.yaml 에 unused_element 억제 룰을 좁게 적용해서 코드 생성 보일러플레이트 잡음만 무음 처리

3. Remote DataSource

• 파일: lib/features/todo/data/datasources/todo_remote_datasource.dart
• Retrofit 으로 8 엔드포인트 매핑 — getTodos, createTodo, updateTodo, deleteTodo, getCategories, createCategory, updateCategory, deleteCategory
• getTodos 는 date, categoryId 옵션 쿼리 지원

4. Repository 구현 (server-first + cache 폴백)

• 파일: lib/features/todo/data/repositories/todo_repository_impl.dart
• 동작 원칙
  • 읽기(getTodoList / getCategories): Remote 호출 → 성공 시 캐시 갱신, 네트워크 실패만 캐시 폴백
  • 쓰기(create / update / delete): Remote 호출 → 성공 시 캐시 동기 반영, 실패 시 예외 그대로 전파
• 네트워크 실패 판정(_isNetworkFailure): timeout / connectionError / unknown 만 폴백 대상. badResponse(4xx/5xx), cancel, badCertificate 는 폴백하지 않고 도메인 Exception 으로 변환
• deleteCategory 호출 시 서버가 연관 Todo 의 categoryIds 에서 자동 제거하므로, 로컬 캐시도 동일 정리

특이사항:

• ID 발급은 클라이언트 책임 — Uuid().v4() 로 TodoCreateRequestModel.id / CategoryCreateRequestModel.id 채움
• updateTodo 는 PATCH 라서 null 필드는 미수정 — 호출부는 변경할 필드만 채워 보내면 됨
• 동기화 큐 / 재시도는 후속 사이클로 보류 (현재는 실패 시 예외 즉시 전파)

5. 인증 상태 기반 Repository 분기

• 파일: lib/features/auth/presentation/providers/auth_provider.dart, lib/features/todo/presentation/providers/todo_provider.dart
• isAuthenticatedProvider 신규 추가 — AuthEntity != null && !isGuest 일 때 true
• todoRepositoryProvider 가 위 값을 watch 하여
  • 인증됨: TodoRepositoryImpl (Remote + Cache)
  • 미인증/게스트: 기존 LocalTodoRepositoryImpl (SharedPreferences 단독)
• 이유: 로그인 / 로그아웃 시 Provider 가 자동 재구성되어 호출부는 신경 쓸 게 없음

6. 로그아웃·탈퇴 시 로컬 캐시 정리

• 파일: lib/features/auth/data/repositories/auth_repository_impl.dart
• 로그아웃 / 회원탈퇴 후 _clearLocalDomainCaches() 호출 → LocalTodoDataSource.clearAll()
• 예외 발생 시 흡수(로그만 남김) — 캐시 정리 실패가 인증 상태 전이를 막지 않도록 보장
• 이유: 동일 단말에서 다른 계정 로그인 시 이전 사용자 Todo 가 노출되는 사고 방지

7. 게스트 signOut CircularDependencyError 핫픽스

• 파일: lib/features/auth/presentation/providers/auth_provider.dart (_clearGuestData)
• 증상: 게스트 모드에서 Todo/Category 생성 후 로그아웃 → 로그에 게스트 데이터 삭제 실패: Instance of 'CircularDependencyError' 출력, Todo/Category 가 그대로 남음
• 원인: 6번에서 todoRepositoryProvider 가 isAuthenticatedProvider → authNotifierProvider 를 watch 하도록 바꾸면서, AuthNotifier 내부의 _clearGuestData 가 같은 todoRepositoryProvider 를 ref.read 하는 순간 사이클이 형성

  authNotifierProvider (실행 중)
    └─ ref.read(todoRepositoryProvider)
          └─ ref.watch(isAuthenticatedProvider)
                └─ ref.watch(authNotifierProvider)   ← 순환
  

• 수정: 게스트 = 로컬 전용이므로 Repository 분기 결과가 불필요. localTodoDataSourceProvider.clearAll() 직접 호출로 우회

  - () => ref.read(todoRepositoryProvider).clearAll(),
  + () => ref.read(localTodoDataSourceProvider).clearAll(),

• 부수 효과: 다른 4개 Repository(timerSession, fuel, exploration, badge) 는 auth 를 watch 하지 않아 로그상 정상 정리되었음 — 이번 사이클은 todo 한정

주요 변경사항 상세

TodoRepositoryImpl._isNetworkFailure

DioException 타입을 5종 / 3종으로 분류:

폴백 O (네트워크 실패)	폴백 X (서버/요청 오류)
connectionTimeout	badResponse (4xx/5xx)
receiveTimeout	badCertificate
sendTimeout	cancel
connectionError
unknown

폴백 X 케이스는 DioExceptionHandler.handle(e) 로 도메인 Exception 변환 후 throw — UI 가 정확한 에러를 받을 수 있도록.

Model 캐시 마이그레이션

TodoModel.fromJson, TodoCategoryModel.fromJson 에서 구버전 키 폴백 처리 추가.
신규 키가 없으면 구 키를 시도 → 기존 사용자 단말의 SharedPreferences 데이터 유실 없이 업그레이드 가능.

커밋 구성

총 21개 작업 커밋을 기능 단위 5개로 재구성 후 후속 핫픽스 2건 누적:

1. docs : Todo·Category API 백엔드 연동 spec/plan + 계약 문서 정렬 #77
2. feat : Todo·Category 네트워크 인프라(endpoints/exceptions/dio mapping) 추가 #77
3. feat : Todo·Category Model camelCase 정렬 및 Request DTO 4종 추가 #77
4. feat : Todo Remote DataSource·Repository 구현(server-first + cache 폴백) #77
5. feat : 인증 상태에 따라 Todo Repository 분기 + 로그아웃 캐시 정리 #77
6. fix : CI format #77 — 5번 도입 코드 포맷 보정
7. fix : 게스트 signOut 시 CircularDependencyError 로 todo 캐시가 정리되지 않던 문제 #77 — 7번 항목

백업 브랜치 backup/before-squash-77 에 원본 21 커밋 보존.

의존성 변경

없음 — 기존 dio, retrofit, freezed, json_serializable, uuid, intl 만 사용.

테스트 및 검증

회귀 테스트 추가:

• test/core/network/dio_exception_handler_test.dart — 신규 4 code 매핑 검증
• test/features/todo/data/models/*_test.dart — Model 6개(camelCase 정렬 + 구버전 캐시 마이그레이션 + Request DTO)
• test/features/todo/data/repositories/todo_repository_impl_test.dart — 네트워크 실패 폴백 / 서버 오류 throw / 캐시 동기화 검증
• test/features/todo/presentation/providers/todo_provider_test.dart — isAuthenticated 토글 시 Repository 타입 전환 검증
• test/features/auth/data/repositories/auth_repository_impl_test.dart — 로그아웃·탈퇴 시 localTodoDataSource.clearAll() 호출 검증

7번 핫픽스는 자동 테스트 보류 — 게스트 signOut 경로가 LocalTodoDataSource + timerSessionRepository + fuelRepository + explorationRepository + badgeRepository + timerNotifier 등 6개 Provider override 를 요구해 셋업 비용이 1라인 핫픽스 대비 과대. 대신 _clearGuestData 안에 cycle 원인 주석을 명시하고 실 디바이스에서 게스트 Todo 생성 → 로그아웃 → 재로그인 후 Todo 잔존 여부 수동 확인.

flutter analyze clean · flutter test 통과 기준.

참고사항

• PATCH semantics: updateTodo 호출부는 변경하지 않을 필드를 null 로 두면 서버가 무시 — 부분 갱신 가능
• categoryIds 정합성: 서버가 카테고리 삭제 시 Todo 의 categoryIds 를 자동 정리하므로, 클라이언트 캐시도 같은 규칙 적용
• 동기화 큐: 현재는 쓰기 실패 = 즉시 throw. 오프라인 쓰기 큐 / 재시도는 후속 이슈에서 다룸
• Riverpod cycle 주의: todoRepositoryProvider 가 authNotifierProvider 를 간접 watch 하므로, AuthNotifier 메서드 내부에서는 절대 todoRepositoryProvider 를 ref.read/watch 하지 말 것. 로컬 정리가 필요하면 localTodoDataSourceProvider 를 직접 사용
• 백업 브랜치: backup/before-squash-77 은 안전망. 5개 커밋이 충분히 검증되면 정리 가능