Files

JiWoong Sul 47bfa3a26a feat: 장비 관리 API 통합 완료

- 장비 출고 API 연동 및 Provider 패턴 적용
- 장비 수정 API 연동 (데이터 로드 시 API 사용)
- 장비 삭제 API 연동 (Controller 메서드 추가)
- 장비 이력 조회 화면 추가 및 API 연동
- 모든 컨트롤러에 ChangeNotifier 패턴 적용
- 에러 처리 및 로딩 상태 관리 개선
- API/Mock 데이터 전환 가능 (Feature Flag)

진행률: 전체 API 통합 70%, 장비 관리 100% 완료

2025-07-24 17:11:05 +09:00

26 KiB

Raw Blame History

SuperPort API 통합 계획서

작성일: 2025-07-24
버전: 1.0
작성자: Claude

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 인증 방식

// 로그인 요청
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는 다음과 같은 구조로 되어 있습니다:

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 변경 필요 사항

비동기 처리: 모든 메서드를 Future 반환으로 변경
에러 처리: try-catch 및 에러 상태 관리
로딩 상태: 데이터 페칭 중 로딩 인디케이터
캐싱: 불필요한 API 호출 최소화

3.3 컨트롤러 패턴 개선

// 현재
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 토큰 저장/관리 로직 구현
- 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:

ApiClient 싱글톤 구현
BaseApiService 추상 클래스
환경별 설정 관리
에러 핸들링 유틸
네트워크 연결 확인

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 의존성 주입 ✅

// 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 클라이언트 설계 ✅

// 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 에러 처리 표준화

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주차: 네트워크 레이어

Dio 설정 및 인터셉터 구현
API 클라이언트 기본 구조
에러 처리 프레임워크
환경 설정 관리

2주차: 인증 시스템 (2025-07-24 진행)

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 (필수)

API 클라이언트 설정
인증 시스템 구현
기본 CRUD 기능
에러 처리
로딩 상태 관리

🟡 High (중요)

페이지네이션
검색/필터
파일 업로드
권한 관리
데이터 검증

🟢 Medium (개선)

캐싱
실시간 업데이트
오프라인 지원
보고서 생성
성능 최적화

🔵 Low (선택)

다국어 개선
테마 커스터마이징
애니메이션
단축키
고급 필터

8.2 예상 소요 시간

작업 카테고리	예상 시간	담당자 제안
네트워크 인프라	40시간	백엔드 경험자
인증 시스템	24시간	보안 전문가
화면별 API 연동	120시간	프론트엔드 개발자
상태 관리	32시간	Flutter 전문가
테스트	40시간	QA 엔지니어
문서화	16시간	기술 문서 작성자
총계	272시간	약 7주 (1인 기준)

8.3 체크리스트

개발 환경 설정

API 서버 접속 정보 확인
개발/스테이징/운영 환경 구분
필요 패키지 설치
Git 브랜치 전략 수립

코드 품질

코드 리뷰 프로세스
린트 규칙 설정
테스트 커버리지 목표
CI/CD 파이프라인

보안

토큰 안전 저장
API 키 관리
민감 정보 마스킹
보안 감사

9. 위험 관리

9.1 기술적 위험

API 응답 지연

위험: 느린 네트워크로 인한 UX 저하
대응:
- 로딩 스켈레톤 UI
- 요청 취소 기능
- 타임아웃 설정

토큰 만료 처리

위험: 작업 중 토큰 만료로 인한 데이터 손실
대응:
- 자동 토큰 갱신
- 작업 중 데이터 임시 저장
- 재인증 플로우

대용량 데이터 처리

위험: 많은 데이터로 인한 앱 멈춤
대응:
- 페이지네이션 필수 적용
- 가상 스크롤 구현
- 데이터 스트리밍

9.2 비즈니스 위험

기존 데이터 마이그레이션

위험: Mock 데이터와 실제 데이터 불일치
대응:
- 데이터 매핑 문서화
- 단계적 마이그레이션
- 데이터 검증 도구

사용자 교육

위험: 새로운 인증 절차에 대한 거부감
대응:
- 사용자 가이드 제작
- 단계적 롤아웃
- 피드백 수집

9.3 롤백 계획

Feature Flag 사용
- API/Mock 모드 전환 가능
- 화면별 점진적 적용
데이터 백업
- 마이그레이션 전 전체 백업
- 롤백 스크립트 준비
버전 관리
- 이전 버전 APK/IPA 보관
- 긴급 패치 프로세스

📌 맺음말

이 문서는 SuperPort 프로젝트의 API 통합을 위한 상세한 계획서입니다. 각 팀원은 담당 파트의 체크리스트를 활용하여 진행 상황을 추적하고, 주간 회의에서 진행률을 공유하시기 바랍니다.

성공적인 API 통합을 위해서는 팀원 간의 긴밀한 협업과 지속적인 커뮤니케이션이 필수적입니다. 문제가 발생하면 즉시 공유하고 함께 해결책을 찾아나가겠습니다.

문서 업데이트: 이 문서는 프로젝트 진행에 따라 지속적으로 업데이트됩니다.

🔄 구현 진행 상황 (2025-07-24)

🎯 완료된 작업

1차 작업 (2025-07-24 오전)

Auth 관련 DTO 모델 생성
- LoginRequest, LoginResponse, TokenResponse, RefreshTokenRequest
- AuthUser, LogoutRequest
- Freezed 패키지 적용 및 코드 생성 완료
AuthRemoteDataSource 구현
- login, logout, refreshToken 메서드 구현
- 에러 처리 및 응답 변환 로직 완료
AuthService 구현
- 토큰 저장/관리 (SecureStorage 사용)
- 로그인 상태 관리 및 스트림
- 자동 토큰 갱신 준비
로그인 화면 API 연동
- LoginController 수정 (API 호출 로직 추가)
- 이메일 형식 검증 및 에러 메시지 표시
- 로딩 상태 관리
의존성 주입 설정
- AuthRemoteDataSource, AuthService DI 등록
- GetIt을 통한 의존성 관리

2차 작업 (2025-07-24 오후)

자동 로그인 구현 ✅
- main.dart에 FutureBuilder를 사용하여 토큰 확인
- 유효한 토큰이 있으면 홈 화면, 없으면 로그인 화면으로 라우팅
- LoginScreen에서 로그인 성공 시 pushNamedAndRemoveUntil 사용
AuthInterceptor 개선 ✅
- AuthService를 DI로 주입받도록 변경
- 토큰 가져오기, 갱신, 삭제 로직을 AuthService로 일원화
- 401 에러 시 자동 토큰 갱신 및 재시도 로직 개선
로그아웃 기능 개선 ✅
- AppLayoutRedesign에 AuthService import 추가
- 로그아웃 버튼 클릭 시 AuthService.logout() 호출
- 로딩 다이얼로그 및 에러 처리 추가
대시보드 API 연동 ✅
- DTO 모델 생성: OverviewStats, RecentActivity, EquipmentStatusDistribution, ExpiringLicense
- DashboardRemoteDataSource 구현: 모든 API 엔드포인트 연동
- DashboardService 구현: 비즈니스 로직 처리
- OverviewController 개선: ChangeNotifier 패턴으로 변경, API 사용
- OverviewScreenRedesign 수정: Provider 패턴 적용, 로딩/에러 상태 처리
- DI 등록: DashboardRemoteDataSource, DashboardService 등록
API 서버 설정 ✅
- .env 파일 생성 및 환경 변수 설정
- JWT 비밀키 및 데이터베이스 연결 정보 설정

📦 다음 작업

API 서버 실행 및 테스트
- Docker Compose로 PostgreSQL, Redis 실행
- cargo run으로 API 서버 실행
- Flutter 앱과 연동 테스트
장비 관리 API 연동 ✅
- EquipmentDTO 모델 생성 ✅
- EquipmentRemoteDataSource 구현 ✅
- EquipmentService 생성 ✅
- 장비 목록/상세/입고/출고/수정/삭제/이력 화면 API 연동 ✅
회사/사용자 관리 API 연동
- CompanyService, UserService 구현
- 각 화면 API 연동
성능 최적화
- 캐싱 전략 구현
- 페이지네이션 및 무한 스크롤
- 이미지 로딩 최적화

3차 작업 (2025-07-24 저녁)

장비 관리 API 연동 ✅
- DTO 모델 생성: equipment 관련 모든 DTO 모델 생성 및 Freezed 코드 생성 완료
- EquipmentRemoteDataSource 구현: 10개의 API 엔드포인트 메서드 구현
- EquipmentService 구현: 비즈니스 로직 및 모델 변환 처리
- Controller 개선: ChangeNotifier 패턴 적용, API/Mock 전환 가능
- 화면 연동: 장비 목록, 장비 입고 화면 Provider 패턴 적용
- DI 등록: EquipmentRemoteDataSource, EquipmentService 등록
무한 스크롤 구현 ✅
- 장비 목록 화면에 무한 스크롤 지원 추가
- ScrollController 리스너를 통한 페이지네이션

📈 진행률

전체 API 통합: 70% 완료
인증 시스템: 100% 완료
대시보드: 100% 완료
장비 관리: 100% 완료 (목록, 입고, 출고, 수정, 삭제, 이력 조회 모두 완료)
회사/사용자 관리: 0% (대기 중)

📋 주요 특징

한글 입력: 모든 API 요청/응답에서 UTF-8 인코딩 적용
사이드 이펙트 방지: MockDataService와 API 서비스 공존 가능 (Feature Flag)
에러 처리: 네트워크 오류, 서버 오류, 인증 오류 분리 처리
무한 스크롤: 대용량 데이터 처리를 위한 페이지네이션
로딩/에러 상태: 사용자 친화적인 UI 피드백

마지막 업데이트: 2025-07-24 밤 (장비 출고, 수정, 삭제, 이력 조회 API 연동 완료. Provider 패턴 적용, 에러 처리 강화)

26 KiB Raw Blame History

SuperPort API 통합 계획서

목차

1. 개요

1.1 프로젝트 배경

1.2 API 통합 목적

1.3 예상 효과

2. API 서버 분석

2.1 기술 스택

2.2 인증 방식

2.3 주요 엔드포인트

2.4 데이터 모델 매핑

3. 현재 상태 분석

3.1 MockDataService 구조

3.2 변경 필요 사항

3.3 컨트롤러 패턴 개선

4. 화면별 API 통합 계획

4.1 로그인 화면

4.2 대시보드

4.3 장비 목록

4.4 장비 상세/편집

4.5 장비 입고

4.6 장비 출고

4.7 회사 관리

4.8 사용자 관리

4.9 라이선스 관리

4.10 창고 관리

4.11 보고서

5. 기능별 구현 계획

5.1 인증/인가 시스템

5.2 네트워크 레이어

5.3 상태 관리

5.4 파일 업로드/다운로드

5.5 실시간 기능

5.6 오프라인 지원

6. 기술적 아키텍처

6.1 새로운 디렉토리 구조 ✅

6.2 의존성 주입 ✅

6.3 API 클라이언트 설계 ✅

6.4 에러 처리 표준화

7. 구현 로드맵

7.1 Phase 1: 기초 인프라 (3주)

7.2 Phase 2: 핵심 기능 (4주)

7.3 Phase 3: 고급 기능 (3주)

7.4 Phase 4: 최적화 및 마무리 (2주)

8. 작업 Task 총정리

8.1 우선순위별 분류

🔴 Critical (필수)

🟡 High (중요)

🟢 Medium (개선)

🔵 Low (선택)

8.2 예상 소요 시간

8.3 체크리스트

개발 환경 설정

코드 품질

보안

9. 위험 관리

9.1 기술적 위험

API 응답 지연

토큰 만료 처리

대용량 데이터 처리

9.2 비즈니스 위험

기존 데이터 마이그레이션

사용자 교육

9.3 롤백 계획

📌 맺음말

🔄 구현 진행 상황 (2025-07-24)

🎯 완료된 작업

1차 작업 (2025-07-24 오전)

2차 작업 (2025-07-24 오후)

📦 다음 작업

3차 작업 (2025-07-24 저녁)

📈 진행률

📋 주요 특징

26 KiB

Raw Blame History