⚙️ [기능추가][AI] AI 장소 추출의 진행/결과 화면 구현 필요

[Cassiiopeia]

📝 현재 문제점

• URL 분석 요청 후 폴링 기반으로 추출 진행 상태를 표시하고, 완료 시 추출된 장소 목록을 표시하는 화면 구현.

🛠️ 해결 방안 / 제안 기능

연동 API:

• GET /api/content/{contentId} - 콘텐츠 상세 조회 (폴링용)

완료 조건:

• 추출 진행 중 로딩 UI (애니메이션)
• 2초 간격 폴링으로 상태 확인
• 추출 완료 시 장소 목록 표시
• 추출 실패 시 에러 처리

🙋‍♂️ 담당자

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

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260209_#22_AI_장소_추출의_진행_결과_화면_구현_필요

커밋 메시지

AI 장소 추출의 진행/결과 화면 구현 필요 : feat : {변경 사항에 대한 설명} https://github.com/MapSee-Lab/MapSy-FE/issues/22

[Cassiiopeia]

#22 장소 추출 진행/결과 화면 구현

개요

URL 분석 요청 후 백엔드에서 장소 추출이 완료될 때까지 5초 간격 폴링으로 상태를 확인하고, 로딩 애니메이션을 표시하며, 완료 시 추출된 장소 목록을 화면에 출력하는 기능을 구현한다.

구현 범위

항목	상태
추출 진행 중 로딩 애니메이션 UI	완료
5초 간격 폴링 상태 확인 로직	완료
최대 5분(60회) 타임아웃	완료
추출 완료 시 장소 목록 표시	완료
추출 실패 시 에러 처리	완료
분석 취소 기능	완료

변경 파일

신규 파일

파일	역할
lib/features/ai_extraction/presentation/widgets/analyzing_section.dart	로딩 애니메이션 위젯
lib/features/ai_extraction/data/models/content_detail_response.dart	폴링 응답 DTO (Freezed)

관련 파일 (이슈 #21과 공유)

파일	해당 부분
lib/features/ai_extraction/presentation/ai_extraction_provider.dart	폴링 로직, 상태 전환
lib/features/ai_extraction/presentation/pages/ai_extraction_page.dart	analyzing/error 단계 UI 분기
lib/features/ai_extraction/data/ai_extraction_remote_datasource.dart	getContentDetail() API 호출
lib/features/ai_extraction/data/ai_extraction_repository.dart	getContentDetail() 인터페이스
lib/features/ai_extraction/data/ai_extraction_repository_impl.dart	getContentDetail() 구현

상세 구현

1. 로딩 애니메이션 UI (AnalyzingSection)

분석 진행 중 화면 중앙에 표시되는 위젯으로 구성:

• CircularProgressIndicator: 64x64 크기, strokeWidth 3, HomeColors.textPrimary 색상
• 안내 문구: "장소를 추출하고 있어요" + "잠시만 기다려주세요..."
• 취소 버튼: TextButton으로 "취소" 표시, 탭 시 폴링 중단 및 입력 화면 복귀

class AnalyzingSection extends StatelessWidget {
  const AnalyzingSection({super.key, required this.onCancel});
  final VoidCallback onCancel;

  @override
  Widget build(BuildContext context) {
    return Center(
      child: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          SizedBox(
            width: 64.w, height: 64.w,
            child: CircularProgressIndicator(
              strokeWidth: 3.w,
              color: HomeColors.textPrimary,
            ),
          ),
          SizedBox(height: 24.h),
          Text('AI가 장소를 추출하고 있어요', style: AppTextStyles.subHeading),
          SizedBox(height: 8.h),
          Text('잠시만 기다려주세요...', style: AppTextStyles.paragraph.copyWith(
            color: HomeColors.textSecondary,
          )),
          SizedBox(height: 32.h),
          TextButton(onPressed: onCancel, child: Text('취소')),
        ],
      ),
    );
  }
}

2. 폴링 로직 (AiExtractionNotifier._startPolling)

Timer.periodic을 사용한 5초 간격 폴링으로 콘텐츠 상태를 확인한다.

폴링 사양:

• 간격: 5초
• 최대 시도 횟수: 60회 (총 5분)
• API: GET /api/content/{contentId}
• 종료 조건: COMPLETED, FAILED, 타임아웃(60회 초과)

void _startPolling(int contentId) {
  int attempts = 0;
  const maxAttempts = 60;

  _pollingTimer?.cancel();
  _pollingTimer = Timer.periodic(
    const Duration(seconds: 5),
    (timer) async {
      attempts++;

      if (attempts > maxAttempts) {
        timer.cancel();
        state = state.copyWith(
          step: AiExtractionStep.error,
          errorMessage: '분석 시간이 초과되었습니다. 다시 시도해주세요.',
        );
        return;
      }

      try {
        final repository = ref.read(aiExtractionRepositoryProvider);
        final detail = await repository.getContentDetail(contentId);

        if (detail.status.toUpperCase() == 'COMPLETED') {
          timer.cancel();
          final allPlaceIds = detail.places.map((p) => p.placeId).toSet();
          state = state.copyWith(
            step: AiExtractionStep.completed,
            places: detail.places,
            selectedPlaceIds: allPlaceIds,
          );
        } else if (detail.status.toUpperCase() == 'FAILED') {
          timer.cancel();
          state = state.copyWith(
            step: AiExtractionStep.error,
            errorMessage: '장소 추출에 실패했습니다. 다시 시도해주세요.',
          );
        }
      } catch (e) {
        debugPrint('AiExtraction: Polling failed: $e');
      }
    },
  );
}

3. 폴링 응답 DTO (ContentDetailResponse)

@freezed
class ContentDetailResponse with _$ContentDetailResponse {
  const factory ContentDetailResponse({
    required int contentId,
    required String status,       // PENDING, PROCESSING, COMPLETED, FAILED
    String? sourceUrl,
    @Default([]) List<PlaceModel> places,
  }) = _ContentDetailResponse;

  factory ContentDetailResponse.fromJson(Map<String, dynamic> json) =>
      _$ContentDetailResponseFromJson(json);
}

• status 필드: 대문자 비교(toUpperCase())로 서버 응답 형식에 유연하게 대응
• places 필드: 추출 완료 시 PlaceModel 목록이 포함됨, 미완료 시 빈 배열

4. 상태 전환 흐름

[input] → analyze() 호출 → [analyzing]
  │
  ├── 폴링 중 status == 'COMPLETED' → [completed] (장소 목록 표시)
  ├── 폴링 중 status == 'FAILED'    → [error] (에러 메시지)
  ├── 60회 초과 (5분 타임아웃)       → [error] (시간 초과 메시지)
  └── 사용자 취소                    → [input] (입력 화면 복귀)

5. 완료 시 장소 목록 표시

폴링에서 COMPLETED 수신 시:

1. 응답의 places 배열을 상태에 저장
2. 모든 장소 ID를 selectedPlaceIds에 기본 선택 상태로 설정
3. AiExtractionStep.completed로 전환하여 장소 결과 위젯(PlaceResultSection)을 렌더링

if (detail.status.toUpperCase() == 'COMPLETED') {
  timer.cancel();
  final allPlaceIds = detail.places.map((p) => p.placeId).toSet();
  state = state.copyWith(
    step: AiExtractionStep.completed,
    places: detail.places,
    selectedPlaceIds: allPlaceIds,  // 전체 선택 기본값
  );
}

6. 에러 처리

3가지 에러 시나리오:

시나리오	에러 메시지	처리
분석 요청 자체 실패	"URL 분석에 실패했습니다. 다시 시도해주세요."	analyze() catch 블록
서버에서 FAILED 반환	"장소 추출에 실패했습니다. 다시 시도해주세요."	폴링 중 status 체크
5분 타임아웃	"분석 시간이 초과되었습니다. 다시 시도해주세요."	attempts > 60

에러 화면에는 에러 아이콘(Icons.error_outline, 64sp), 에러 메시지, "다시 시도" 버튼을 표시한다. "다시 시도" 버튼은 retry()를 호출하여 input 상태로 복귀한다.

7. 취소 기능

분석 진행 중 두 가지 경로로 취소 가능:

• 취소 버튼 탭: AnalyzingSection의 onCancel 콜백으로 notifier.cancel() 호출
• 뒤로가기(AppBar/시스템 백버튼): PopScope에서 analyzing 상태일 때 notifier.cancel() 호출

void cancel() {
  _pollingTimer?.cancel();
  state = state.copyWith(
    step: AiExtractionStep.input,
    errorMessage: null,
  );
}

PopScope의 canPop이 analyzing 상태에서 false로 설정되어, 시스템 뒤로가기 시 폴링을 먼저 취소한 후 페이지를 닫는다.

8. 타이머 정리

Provider의 ref.onDispose에서 폴링 타이머를 정리하여 메모리 누수를 방지한다.

@override
AiExtractionState build() {
  ref.onDispose(() {
    _pollingTimer?.cancel();
  });
  return const AiExtractionState();
}

비고

• 폴링 중 개별 요청 실패(네트워크 오류 등)는 catch 후 무시하고 다음 폴링을 계속 진행함 (일시적 네트워크 불안정 대응)
• 완료 시 전체 장소가 기본 선택 상태로 설정되어 이슈 #23의 저장 플로우와 자연스럽게 연결됨