2b31d3af5f
- 네트워크 레이어 구현 (Dio 기반 ApiClient) - 환경별 설정 관리 시스템 구축 - 의존성 주입 설정 (GetIt) - API 엔드포인트 상수 정의 - 인터셉터 구현 (Auth, Error, Logging) - 프로젝트 아키텍처 개선 (core, data, di 디렉토리 구조) - API 통합 계획서 및 요구사항 문서 작성 - 필요 패키지 추가 (dio, flutter_secure_storage, get_it 등)
893 lines
22 KiB
Markdown
893 lines
22 KiB
Markdown
# 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_ (네트워크 레이어 및 기본 인프라 구현 완료) |