feat: API 통합을 위한 기초 인프라 구축

- 네트워크 레이어 구현 (Dio 기반 ApiClient) - 환경별 설정 관리 시스템 구축 - 의존성 주입 설정 (GetIt) - API 엔드포인트 상수 정의 - 인터셉터 구현 (Auth, Error, Logging) - 프로젝트 아키텍처 개선 (core, data, di 디렉토리 구조) - API 통합 계획서 및 요구사항 문서 작성 - 필요 패키지 추가 (dio, flutter_secure_storage, get_it 등)
2025-07-24 14:54:28 +09:00
parent e0bc5894b2
commit 2b31d3af5f
29 changed files with 3542 additions and 344 deletions
--- a/doc/API_Integration_Plan.md
+++ b/doc/API_Integration_Plan.md
@@ -0,0 +1,893 @@
+# SuperPort API 통합 계획서
+
+**작성일**: 2025-07-24  
+**버전**: 1.0  
+**작성자**: Claude  
+
+## 목차
+
+1. [개요](#1-개요)
+2. [API 서버 분석](#2-api-서버-분석)
+3. [현재 상태 분석](#3-현재-상태-분석)
+4. [화면별 API 통합 계획](#4-화면별-api-통합-계획)
+5. [기능별 구현 계획](#5-기능별-구현-계획)
+6. [기술적 아키텍처](#6-기술적-아키텍처)
+7. [구현 로드맵](#7-구현-로드맵)
+8. [작업 Task 총정리](#8-작업-task-총정리)
+9. [위험 관리](#9-위험-관리)
+
+---
+
+## 1. 개요
+
+### 1.1 프로젝트 배경
+
+SuperPort는 현재 MockDataService를 사용하여 모든 데이터를 메모리에서 관리하고 있습니다. 이는 개발 초기 단계에서는 유용했지만, 실제 운영 환경에서는 다음과 같은 한계가 있습니다:
+
+- 데이터 영속성 부재
+- 다중 사용자 동시 접근 불가
+- 실시간 데이터 동기화 불가
+- 보안 및 인증 기능 부재
+
+### 1.2 API 통합 목적
+
+- **데이터 영속성**: PostgreSQL 데이터베이스를 통한 안정적인 데이터 저장
+- **다중 사용자 지원**: 동시 접근 및 실시간 업데이트 지원
+- **보안 강화**: JWT 기반 인증 및 역할 기반 접근 제어
+- **확장성**: 향후 기능 추가를 위한 견고한 백엔드 인프라
+
+### 1.3 예상 효과
+
+- 실제 운영 환경 배포 가능
+- 데이터 무결성 및 일관성 보장
+- 사용자별 권한 관리
+- 감사 로그 및 이력 추적
+- 대용량 데이터 처리 능력
+
+---
+
+## 2. API 서버 분석
+
+### 2.1 기술 스택
+
+- **언어**: Rust
+- **프레임워크**: Actix-web 4.5
+- **ORM**: SeaORM
+- **데이터베이스**: PostgreSQL 16
+- **인증**: JWT (Access + Refresh Token)
+
+### 2.2 인증 방식
+
+```json
+// 로그인 요청
+POST /api/v1/auth/login
+{
+  "username": "user@example.com",
+  "password": "password123"
+}
+
+// 응답
+{
+  "access_token": "eyJ0eXAiOiJKV1Q...",
+  "refresh_token": "eyJ0eXAiOiJKV1Q...",
+  "token_type": "Bearer",
+  "expires_in": 3600
+}
+```
+
+### 2.3 주요 엔드포인트
+
+| 기능 | 메서드 | 경로 | 설명 |
+|------|--------|------|------|
+| **인증** |
+| 로그인 | POST | /auth/login | 사용자 인증 |
+| 로그아웃 | POST | /auth/logout | 세션 종료 |
+| 토큰 갱신 | POST | /auth/refresh | 액세스 토큰 갱신 |
+| **장비** |
+| 목록 조회 | GET | /equipment | 페이징, 필터, 정렬 지원 |
+| 상세 조회 | GET | /equipment/{id} | 장비 상세 정보 |
+| 생성 | POST | /equipment | 새 장비 등록 |
+| 수정 | PUT | /equipment/{id} | 장비 정보 수정 |
+| 삭제 | DELETE | /equipment/{id} | 장비 삭제 |
+| 입고 | POST | /equipment/in | 장비 입고 처리 |
+| 출고 | POST | /equipment/out | 장비 출고 처리 |
+| **회사** |
+| 목록 조회 | GET | /companies | 회사 목록 |
+| 지점 조회 | GET | /companies/{id}/branches | 회사별 지점 |
+
+### 2.4 데이터 모델 매핑
+
+| Flutter 모델 | API DTO | 변경사항 |
+|--------------|---------|----------|
+| Equipment | EquipmentDto | category 구조 변경 |
+| Company | CompanyDto | branch 관계 추가 |
+| User | UserDto | role → role_type |
+| License | LicenseDto | 완전 일치 |
+
+---
+
+## 3. 현재 상태 분석
+
+### 3.1 MockDataService 구조
+
+현재 MockDataService는 다음과 같은 구조로 되어 있습니다:
+
+```dart
+class MockDataService {
+  static final MockDataService _instance = MockDataService._internal();
+  
+  // 메모리 저장소
+  final List<Equipment> _equipments = [];
+  final List<Company> _companies = [];
+  
+  // 동기적 메서드
+  List<Equipment> getEquipments() => _equipments;
+  void addEquipment(Equipment equipment) => _equipments.add(equipment);
+}
+```
+
+### 3.2 변경 필요 사항
+
+1. **비동기 처리**: 모든 메서드를 Future 반환으로 변경
+2. **에러 처리**: try-catch 및 에러 상태 관리
+3. **로딩 상태**: 데이터 페칭 중 로딩 인디케이터
+4. **캐싱**: 불필요한 API 호출 최소화
+
+### 3.3 컨트롤러 패턴 개선
+
+```dart
+// 현재
+class EquipmentController {
+  List<Equipment> get equipments => MockDataService().getEquipments();
+}
+
+// 개선 후
+class EquipmentController extends ChangeNotifier {
+  List<Equipment> _equipments = [];
+  bool _isLoading = false;
+  String? _error;
+  
+  Future<void> loadEquipments() async {
+    _isLoading = true;
+    notifyListeners();
+    
+    try {
+      _equipments = await _apiService.getEquipments();
+      _error = null;
+    } catch (e) {
+      _error = e.toString();
+    } finally {
+      _isLoading = false;
+      notifyListeners();
+    }
+  }
+}
+```
+
+---
+
+## 4. 화면별 API 통합 계획
+
+### 4.1 로그인 화면
+
+**사용 API 엔드포인트**:
+- POST /api/v1/auth/login
+- POST /api/v1/auth/refresh
+
+**작업 Task**:
+- [ ] AuthService 클래스 생성
+- [ ] JWT 토큰 저장/관리 로직 구현
+  - [x] SecureStorage 설정
+  - [ ] Access Token 저장
+  - [ ] Refresh Token 저장
+- [ ] 로그인 폼 검증 추가
+  - [ ] 이메일 형식 검증
+  - [ ] 비밀번호 최소 길이 검증
+- [ ] 로그인 실패 에러 처리
+  - [ ] 401: 잘못된 인증 정보
+  - [ ] 429: 너무 많은 시도
+  - [ ] 500: 서버 오류
+- [ ] 자동 로그인 구현
+  - [ ] 토큰 유효성 검사
+  - [ ] 토큰 자동 갱신
+- [ ] 로그아웃 기능 구현
+
+### 4.2 대시보드
+
+**사용 API 엔드포인트**:
+- GET /api/v1/overview/stats
+- GET /api/v1/overview/recent-activities
+- GET /api/v1/equipment/status-distribution
+- GET /api/v1/licenses/expiring-soon
+
+**작업 Task**:
+- [ ] DashboardService 생성
+- [ ] 통계 데이터 모델 생성
+  - [ ] OverviewStats DTO
+  - [ ] RecentActivity DTO
+  - [ ] StatusDistribution DTO
+- [ ] DashboardController 비동기화
+  - [ ] 동시 다중 API 호출 구현
+  - [ ] 부분 로딩 상태 관리
+- [ ] 실시간 업데이트 구현
+  - [ ] WebSocket 연결 설정
+  - [ ] 실시간 이벤트 수신
+- [ ] 캐싱 전략 구현
+  - [ ] 5분 캐시 TTL
+  - [ ] Pull-to-refresh 구현
+- [ ] 에러 시 부분 렌더링
+
+### 4.3 장비 목록
+
+**사용 API 엔드포인트**:
+- GET /api/v1/equipment?page=1&limit=20&sort=created_at&order=desc
+- GET /api/v1/equipment/categories
+- GET /api/v1/companies/names
+
+**작업 Task**:
+- [ ] EquipmentService 생성
+- [ ] 페이지네이션 구현
+  - [ ] 무한 스크롤 구현
+  - [ ] 페이지 상태 관리
+  - [ ] 로딩 인디케이터
+- [ ] 필터링 기능
+  - [ ] 카테고리별 필터
+  - [ ] 상태별 필터
+  - [ ] 회사별 필터
+  - [ ] 날짜 범위 필터
+- [ ] 정렬 기능
+  - [ ] 생성일 정렬
+  - [ ] 이름 정렬
+  - [ ] 상태 정렬
+- [ ] 검색 기능
+  - [ ] 디바운싱 구현
+  - [ ] 검색 결과 하이라이트
+- [ ] 일괄 작업
+  - [ ] 다중 선택 UI
+  - [ ] 일괄 삭제
+  - [ ] 일괄 상태 변경
+
+### 4.4 장비 상세/편집
+
+**사용 API 엔드포인트**:
+- GET /api/v1/equipment/{id}
+- PUT /api/v1/equipment/{id}
+- GET /api/v1/equipment/{id}/history
+- POST /api/v1/files/upload
+
+**작업 Task**:
+- [ ] 상세 정보 로딩
+  - [ ] 기본 정보 표시
+  - [ ] 이력 정보 로딩
+  - [ ] 관련 문서 표시
+- [ ] 편집 모드 구현
+  - [ ] 폼 데이터 바인딩
+  - [ ] 실시간 검증
+  - [ ] 변경사항 추적
+- [ ] 이미지 업로드
+  - [ ] 파일 선택 UI
+  - [ ] 업로드 진행률
+  - [ ] 썸네일 생성
+- [ ] 히스토리 표시
+  - [ ] 타임라인 UI
+  - [ ] 상태 변경 이력
+  - [ ] 담당자 정보
+
+### 4.5 장비 입고
+
+**사용 API 엔드포인트**:
+- POST /api/v1/equipment/in
+- GET /api/v1/warehouse-locations
+- GET /api/v1/equipment/serial-check/{serial}
+
+**작업 Task**:
+- [ ] 입고 폼 구현
+  - [ ] 장비 정보 입력
+  - [ ] 시리얼 번호 중복 검사
+  - [ ] 창고 위치 선택
+- [ ] 바코드 스캔 통합
+  - [ ] 카메라 권한 요청
+  - [ ] 바코드 디코딩
+  - [ ] 자동 필드 채우기
+- [ ] 일괄 입고
+  - [ ] CSV 파일 업로드
+  - [ ] 데이터 검증
+  - [ ] 진행률 표시
+- [ ] 입고증 생성
+  - [ ] PDF 생성
+  - [ ] 이메일 전송
+
+### 4.6 장비 출고
+
+**사용 API 엔드포인트**:
+- POST /api/v1/equipment/out
+- GET /api/v1/equipment/available
+- GET /api/v1/customers
+
+**작업 Task**:
+- [ ] 출고 폼 구현
+  - [ ] 가용 장비 조회
+  - [ ] 수량 검증
+  - [ ] 고객 정보 입력
+- [ ] 출고 승인 프로세스
+  - [ ] 승인 요청
+  - [ ] 승인자 알림
+  - [ ] 승인 이력
+- [ ] 출고 문서
+  - [ ] 출고증 생성
+  - [ ] 전자 서명
+  - [ ] 문서 보관
+
+### 4.7 회사 관리
+
+**사용 API 엔드포인트**:
+- GET /api/v1/companies
+- POST /api/v1/companies
+- PUT /api/v1/companies/{id}
+- GET /api/v1/companies/{id}/branches
+- POST /api/v1/companies/{id}/branches
+
+**작업 Task**:
+- [ ] 회사 목록 구현
+  - [ ] 본사/지점 트리 구조
+  - [ ] 확장/축소 UI
+  - [ ] 검색 필터
+- [ ] 회사 등록
+  - [ ] 사업자번호 검증
+  - [ ] 주소 검색 API 연동
+  - [ ] 중복 확인
+- [ ] 지점 관리
+  - [ ] 지점 추가/편집
+  - [ ] 지점별 권한 설정
+  - [ ] 지점 이전 기능
+- [ ] 회사 통계
+  - [ ] 장비 보유 현황
+  - [ ] 라이선스 현황
+  - [ ] 사용자 현황
+
+### 4.8 사용자 관리
+
+**사용 API 엔드포인트**:
+- GET /api/v1/users
+- POST /api/v1/users
+- PUT /api/v1/users/{id}
+- PATCH /api/v1/users/{id}/status
+- POST /api/v1/users/{id}/reset-password
+
+**작업 Task**:
+- [ ] 사용자 목록
+  - [ ] 역할별 필터
+  - [ ] 회사별 필터
+  - [ ] 상태별 표시
+- [ ] 사용자 등록
+  - [ ] 이메일 중복 확인
+  - [ ] 임시 비밀번호 생성
+  - [ ] 환영 이메일 발송
+- [ ] 권한 관리
+  - [ ] 역할 선택 UI
+  - [ ] 권한 미리보기
+  - [ ] 권한 변경 이력
+- [ ] 비밀번호 관리
+  - [ ] 비밀번호 재설정
+  - [ ] 강제 변경 설정
+  - [ ] 비밀번호 정책
+
+### 4.9 라이선스 관리
+
+**사용 API 엔드포인트**:
+- GET /api/v1/licenses
+- POST /api/v1/licenses
+- GET /api/v1/licenses/expiring?days=30
+- POST /api/v1/licenses/{id}/renew
+
+**작업 Task**:
+- [ ] 라이선스 목록
+  - [ ] 만료일 기준 정렬
+  - [ ] 상태별 색상 구분
+  - [ ] 갱신 알림 표시
+- [ ] 라이선스 등록
+  - [ ] 계약 정보 입력
+  - [ ] 파일 첨부
+  - [ ] 자동 갱신 설정
+- [ ] 만료 알림
+  - [ ] 30일전 알림
+  - [ ] 7일전 알림
+  - [ ] 당일 알림
+- [ ] 라이선스 갱신
+  - [ ] 갱신 프로세스
+  - [ ] 갱신 이력
+  - [ ] 비용 추적
+
+### 4.10 창고 관리
+
+**사용 API 엔드포인트**:
+- GET /api/v1/warehouse-locations
+- POST /api/v1/warehouse-locations
+- GET /api/v1/warehouse-locations/{id}/inventory
+- PATCH /api/v1/warehouse-locations/{id}/capacity
+
+**작업 Task**:
+- [ ] 창고 목록
+  - [ ] 위치별 그룹핑
+  - [ ] 용량 표시
+  - [ ] 사용률 차트
+- [ ] 창고 등록
+  - [ ] 위치 정보
+  - [ ] 용량 설정
+  - [ ] 담당자 지정
+- [ ] 재고 현황
+  - [ ] 실시간 재고
+  - [ ] 장비별 위치
+  - [ ] 이동 이력
+- [ ] 창고 이동
+  - [ ] 이동 요청
+  - [ ] 승인 프로세스
+  - [ ] 이동 추적
+
+### 4.11 보고서
+
+**사용 API 엔드포인트**:
+- GET /api/v1/reports/equipment-status
+- GET /api/v1/reports/license-summary
+- POST /api/v1/reports/export/excel
+- POST /api/v1/reports/export/pdf
+
+**작업 Task**:
+- [ ] 보고서 템플릿
+  - [ ] 장비 현황 보고서
+  - [ ] 라이선스 보고서
+  - [ ] 사용자 활동 보고서
+- [ ] 보고서 생성
+  - [ ] 기간 선택
+  - [ ] 필터 옵션
+  - [ ] 미리보기
+- [ ] 내보내기
+  - [ ] Excel 다운로드
+  - [ ] PDF 다운로드
+  - [ ] 이메일 전송
+- [ ] 정기 보고서
+  - [ ] 스케줄 설정
+  - [ ] 자동 생성
+  - [ ] 수신자 관리
+
+---
+
+## 5. 기능별 구현 계획
+
+### 5.1 인증/인가 시스템
+
+**구현 내용**:
+- JWT 토큰 관리 서비스
+- 자동 토큰 갱신 인터셉터
+- 역할 기반 라우트 가드
+- 세션 타임아웃 처리
+
+**작업 Task**:
+- [ ] AuthService 구현
+  - [ ] 로그인/로그아웃
+  - [ ] 토큰 저장/조회
+  - [ ] 토큰 갱신 로직
+- [ ] AuthInterceptor 구현
+  - [ ] 요청 헤더 토큰 추가
+  - [ ] 401 에러 처리
+  - [ ] 토큰 갱신 재시도
+- [ ] RouteGuard 구현
+  - [ ] 인증 확인
+  - [ ] 권한 확인
+  - [ ] 리다이렉트 처리
+
+### 5.2 네트워크 레이어
+
+**구현 내용**:
+- Dio 클라이언트 설정
+- API 엔드포인트 관리
+- 에러 처리 표준화
+- 요청/응답 로깅
+
+**작업 Task**:
+- [x] ApiClient 싱글톤 구현
+- [ ] BaseApiService 추상 클래스
+- [x] 환경별 설정 관리
+- [ ] 에러 핸들링 유틸
+- [ ] 네트워크 연결 확인
+
+### 5.3 상태 관리
+
+**구현 내용**:
+- Repository 패턴 도입
+- 데이터 캐싱 전략
+- 옵티미스틱 업데이트
+- 상태 동기화
+
+**작업 Task**:
+- [ ] Repository 인터페이스 정의
+- [ ] 캐시 매니저 구현
+- [ ] 상태 업데이트 로직
+- [ ] 충돌 해결 전략
+
+### 5.4 파일 업로드/다운로드
+
+**구현 내용**:
+- Multipart 파일 업로드
+- 진행률 표시
+- 파일 다운로드 관리
+- 오프라인 파일 캐싱
+
+**작업 Task**:
+- [ ] FileService 구현
+- [ ] 업로드 큐 관리
+- [ ] 다운로드 매니저
+- [ ] 파일 캐시 정책
+
+### 5.5 실시간 기능
+
+**구현 내용**:
+- WebSocket 연결 관리
+- 실시간 이벤트 처리
+- 자동 재연결
+- 이벤트 필터링
+
+**작업 Task**:
+- [ ] WebSocketService 구현
+- [ ] 이벤트 리스너 관리
+- [ ] 재연결 로직
+- [ ] 이벤트 라우팅
+
+### 5.6 오프라인 지원
+
+**구현 내용**:
+- 로컬 데이터베이스 (SQLite)
+- 동기화 큐 관리
+- 충돌 해결
+- 오프라인 모드 UI
+
+**작업 Task**:
+- [ ] 로컬 DB 스키마 설계
+- [ ] 동기화 서비스 구현
+- [ ] 충돌 해결 UI
+- [ ] 오프라인 인디케이터
+
+---
+
+## 6. 기술적 아키텍처
+
+### 6.1 새로운 디렉토리 구조 ✅
+
+```
+lib/
+├── core/ ✅
+│   ├── config/ ✅
+│   │   └── environment.dart ✅
+│   ├── constants/ ✅
+│   │   ├── api_endpoints.dart ✅
+│   │   └── app_constants.dart ✅
+│   ├── errors/ ✅
+│   │   ├── exceptions.dart ✅
+│   │   └── failures.dart ✅
+│   └── utils/ ✅
+│       ├── validators.dart ✅
+│       └── formatters.dart ✅
+├── data/ ✅
+│   ├── datasources/ ✅
+│   │   ├── local/ ✅
+│   │   │   └── cache_datasource.dart
+│   │   └── remote/ ✅
+│   │       ├── api_client.dart ✅
+│   │       ├── interceptors/ ✅
+│   │       │   ├── auth_interceptor.dart ✅
+│   │       │   ├── error_interceptor.dart ✅
+│   │       │   └── logging_interceptor.dart ✅
+│   │       ├── auth_remote_datasource.dart
+│   │       └── equipment_remote_datasource.dart
+│   ├── models/ ✅
+│   │   ├── auth/
+│   │   ├── equipment/
+│   │   └── common/
+│   └── repositories/ ✅
+│       ├── auth_repository_impl.dart
+│       └── equipment_repository_impl.dart
+├── di/ ✅
+│   └── injection_container.dart ✅
+├── domain/
+│   ├── entities/
+│   ├── repositories/
+│   └── usecases/
+├── presentation/
+│   ├── controllers/
+│   ├── screens/
+│   └── widgets/
+└── main.dart
+```
+
+### 6.2 의존성 주입 ✅
+
+```dart
+// GetIt을 사용한 DI 설정 ✅
+final getIt = GetIt.instance;
+
+Future<void> setupDependencies() async {
+  // 환경 초기화 ✅
+  await Environment.initialize();
+  
+  // 네트워크 ✅
+  getIt.registerLazySingleton(() => Dio());
+  getIt.registerLazySingleton(() => const FlutterSecureStorage());
+  
+  // API 클라이언트 ✅
+  getIt.registerLazySingleton(() => ApiClient());
+  
+  // 데이터소스
+  // TODO: Remote datasources will be registered here
+  
+  // 리포지토리
+  // TODO: Repositories will be registered here
+  
+  // 컨트롤러
+  // TODO: Controllers will be registered here
+}
+```
+
+### 6.3 API 클라이언트 설계 ✅
+
+```dart
+// ApiClient 클래스 구현됨 (Retrofit 대신 순수 Dio 사용)
+class ApiClient {
+  late final Dio _dio;
+  static final ApiClient _instance = ApiClient._internal();
+  
+  factory ApiClient() => _instance;
+  
+  ApiClient._internal() {
+    _dio = Dio(_baseOptions);
+    _setupInterceptors();
+  }
+  
+  // GET, POST, PUT, PATCH, DELETE 메서드 구현됨
+  // 파일 업로드/다운로드 메서드 구현됨
+  // 인터셉터 설정 완료 (Auth, Error, Logging)
+}
+```
+
+### 6.4 에러 처리 표준화
+
+```dart
+class ApiException implements Exception {
+  final String message;
+  final int? statusCode;
+  final Map<String, dynamic>? errors;
+  
+  ApiException({
+    required this.message,
+    this.statusCode,
+    this.errors,
+  });
+}
+
+class ErrorHandler {
+  static String getErrorMessage(dynamic error) {
+    if (error is DioError) {
+      switch (error.type) {
+        case DioErrorType.connectTimeout:
+          return "연결 시간이 초과되었습니다";
+        case DioErrorType.other:
+          if (error.error is SocketException) {
+            return "인터넷 연결을 확인해주세요";
+          }
+          break;
+        default:
+          return "알 수 없는 오류가 발생했습니다";
+      }
+    }
+    return error.toString();
+  }
+}
+```
+
+---
+
+## 7. 구현 로드맵
+
+### 7.1 Phase 1: 기초 인프라 (3주)
+
+**1주차: 네트워크 레이어**
+- [x] Dio 설정 및 인터셉터 구현
+- [x] API 클라이언트 기본 구조
+- [ ] 에러 처리 프레임워크
+- [x] 환경 설정 관리
+
+**2주차: 인증 시스템**
+- [ ] AuthService 구현
+- [ ] 토큰 관리 로직
+- [ ] 로그인/로그아웃 화면 연동
+- [ ] 자동 토큰 갱신
+
+**3주차: 기본 데이터 레이어**
+- [ ] Repository 패턴 구현
+- [ ] 기본 모델 변환
+- [ ] 첫 화면(대시보드) API 연동
+- [ ] 로딩/에러 상태 관리
+
+### 7.2 Phase 2: 핵심 기능 (4주)
+
+**4-5주차: 장비 관리**
+- [ ] 장비 목록/상세 API 연동
+- [ ] 입출고 프로세스 구현
+- [ ] 검색/필터/정렬 기능
+- [ ] 이미지 업로드
+
+**6-7주차: 회사/사용자 관리**
+- [ ] 회사 CRUD 구현
+- [ ] 지점 관리 기능
+- [ ] 사용자 관리 및 권한
+- [ ] 프로필 관리
+
+### 7.3 Phase 3: 고급 기능 (3주)
+
+**8주차: 실시간 기능**
+- [ ] WebSocket 연결 구현
+- [ ] 실시간 알림
+- [ ] 대시보드 실시간 업데이트
+- [ ] 이벤트 처리
+
+**9주차: 오프라인 지원**
+- [ ] 로컬 데이터베이스 설정
+- [ ] 동기화 로직 구현
+- [ ] 오프라인 모드 UI
+- [ ] 충돌 해결
+
+**10주차: 보고서 및 파일**
+- [ ] 보고서 생성 기능
+- [ ] Excel/PDF 다운로드
+- [ ] 파일 관리 시스템
+- [ ] 대량 데이터 처리
+
+### 7.4 Phase 4: 최적화 및 마무리 (2주)
+
+**11주차: 성능 최적화**
+- [ ] API 호출 최적화
+- [ ] 캐싱 전략 개선
+- [ ] 이미지 최적화
+- [ ] 번들 크기 최적화
+
+**12주차: 테스트 및 배포**
+- [ ] 통합 테스트
+- [ ] 사용자 승인 테스트
+- [ ] 배포 준비
+- [ ] 문서화
+
+---
+
+## 8. 작업 Task 총정리
+
+### 8.1 우선순위별 분류
+
+#### 🔴 Critical (필수)
+1. [x] API 클라이언트 설정
+2. [ ] 인증 시스템 구현
+3. [ ] 기본 CRUD 기능
+4. [ ] 에러 처리
+5. [ ] 로딩 상태 관리
+
+#### 🟡 High (중요)
+6. [ ] 페이지네이션
+7. [ ] 검색/필터
+8. [ ] 파일 업로드
+9. [ ] 권한 관리
+10. [ ] 데이터 검증
+
+#### 🟢 Medium (개선)
+11. [ ] 캐싱
+12. [ ] 실시간 업데이트
+13. [ ] 오프라인 지원
+14. [ ] 보고서 생성
+15. [ ] 성능 최적화
+
+#### 🔵 Low (선택)
+16. [ ] 다국어 개선
+17. [ ] 테마 커스터마이징
+18. [ ] 애니메이션
+19. [ ] 단축키
+20. [ ] 고급 필터
+
+### 8.2 예상 소요 시간
+
+| 작업 카테고리 | 예상 시간 | 담당자 제안 |
+|--------------|-----------|-------------|
+| 네트워크 인프라 | 40시간 | 백엔드 경험자 |
+| 인증 시스템 | 24시간 | 보안 전문가 |
+| 화면별 API 연동 | 120시간 | 프론트엔드 개발자 |
+| 상태 관리 | 32시간 | Flutter 전문가 |
+| 테스트 | 40시간 | QA 엔지니어 |
+| 문서화 | 16시간 | 기술 문서 작성자 |
+| **총계** | **272시간** | 약 7주 (1인 기준) |
+
+### 8.3 체크리스트
+
+#### 개발 환경 설정
+- [ ] API 서버 접속 정보 확인
+- [x] 개발/스테이징/운영 환경 구분
+- [x] 필요 패키지 설치
+- [ ] Git 브랜치 전략 수립
+
+#### 코드 품질
+- [ ] 코드 리뷰 프로세스
+- [ ] 린트 규칙 설정
+- [ ] 테스트 커버리지 목표
+- [ ] CI/CD 파이프라인
+
+#### 보안
+- [ ] 토큰 안전 저장
+- [ ] API 키 관리
+- [ ] 민감 정보 마스킹
+- [ ] 보안 감사
+
+---
+
+## 9. 위험 관리
+
+### 9.1 기술적 위험
+
+#### API 응답 지연
+- **위험**: 느린 네트워크로 인한 UX 저하
+- **대응**: 
+  - 로딩 스켈레톤 UI
+  - 요청 취소 기능
+  - 타임아웃 설정
+
+#### 토큰 만료 처리
+- **위험**: 작업 중 토큰 만료로 인한 데이터 손실
+- **대응**:
+  - 자동 토큰 갱신
+  - 작업 중 데이터 임시 저장
+  - 재인증 플로우
+
+#### 대용량 데이터 처리
+- **위험**: 많은 데이터로 인한 앱 멈춤
+- **대응**:
+  - 페이지네이션 필수 적용
+  - 가상 스크롤 구현
+  - 데이터 스트리밍
+
+### 9.2 비즈니스 위험
+
+#### 기존 데이터 마이그레이션
+- **위험**: Mock 데이터와 실제 데이터 불일치
+- **대응**:
+  - 데이터 매핑 문서화
+  - 단계적 마이그레이션
+  - 데이터 검증 도구
+
+#### 사용자 교육
+- **위험**: 새로운 인증 절차에 대한 거부감
+- **대응**:
+  - 사용자 가이드 제작
+  - 단계적 롤아웃
+  - 피드백 수집
+
+### 9.3 롤백 계획
+
+1. **Feature Flag 사용**
+   - API/Mock 모드 전환 가능
+   - 화면별 점진적 적용
+
+2. **데이터 백업**
+   - 마이그레이션 전 전체 백업
+   - 롤백 스크립트 준비
+
+3. **버전 관리**
+   - 이전 버전 APK/IPA 보관
+   - 긴급 패치 프로세스
+
+---
+
+## 📌 맺음말
+
+이 문서는 SuperPort 프로젝트의 API 통합을 위한 상세한 계획서입니다. 각 팀원은 담당 파트의 체크리스트를 활용하여 진행 상황을 추적하고, 주간 회의에서 진행률을 공유하시기 바랍니다.
+
+성공적인 API 통합을 위해서는 팀원 간의 긴밀한 협업과 지속적인 커뮤니케이션이 필수적입니다. 문제가 발생하면 즉시 공유하고 함께 해결책을 찾아나가겠습니다.
+
+**문서 업데이트**: 이 문서는 프로젝트 진행에 따라 지속적으로 업데이트됩니다.
+
+---
+
+_마지막 업데이트: 2025-07-24_ (네트워크 레이어 및 기본 인프라 구현 완료)