superport/CLAUDE.md

Superport ERP System

💡 Note: Global Claude Code rules are in ~/.claude/CLAUDE.md. This document contains project-specific context.

🎯 Project Overview

Superport는 기업용 장비 관리 및 유지보수를 위한 클라우드 기반 ERP 시스템입니다.

Business Purpose

• 장비 입출고 및 재고 관리 자동화
• 유지보수 라이선스 만료일 추적
• 고객사별 장비 배치 현황 관리
• 실시간 대시보드를 통한 경영 인사이트 제공

Target Users

• 관리자 (Admin): 전체 시스템 관리, 사용자 권한 설정
• 매니저 (Manager): 장비 입출고 승인, 라이선스 관리
• 일반 사용자 (Member): 장비 조회, 기본 작업 수행

🏗️ Technical Architecture

Tech Stack

Frontend:
  platform: Flutter Web (Mobile ready)
  state_management: Provider + ChangeNotifier
  ui_framework: ShadCN Flutter Port
  api_client: Dio + Retrofit
  code_generation: Freezed + JsonSerializable

Backend:
  language: Rust
  framework: Actix-Web
  database: PostgreSQL
  auth: JWT (24시간 만료)
  api_url: http://43.201.34.104:8080/api/v1
  source_path: /Users/maximilian.j.sul/Documents/flutter/superport_api

Infrastructure:
  hosting: AWS (예정)
  storage: S3 (예정)
  ci_cd: GitHub Actions (예정)

Project Structure (Clean Architecture)

/Users/maximilian.j.sul/Documents/flutter/
├── superport/            # Flutter Frontend (Clean Architecture)
│   ├── lib/
│   │   ├── core/         # 핵심 공통 기능
│   │   │   ├── controllers/  # BaseController 추상화
│   │   │   ├── errors/       # 에러 처리 체계
│   │   │   ├── utils/        # 유틸리티 함수
│   │   │   └── widgets/      # 공통 위젯
│   │   ├── data/         # Data Layer (외부 인터페이스)
│   │   │   ├── datasources/  # Remote/Local 데이터소스
│   │   │   │   ├── remote/   # API 클라이언트 (Retrofit)
│   │   │   │   └── interceptors/ # Dio 인터셉터
│   │   │   ├── models/       # DTO (Freezed 불변 객체)
│   │   │   └── repositories/ # Repository 구현체
│   │   ├── domain/       # Domain Layer (비즈니스 로직)
│   │   │   ├── repositories/ # Repository 인터페이스
│   │   │   └── usecases/    # UseCase (비즈니스 규칙)
│   │   ├── screens/      # Presentation Layer
│   │   │   └── [feature]/
│   │   │       ├── controllers/ # ChangeNotifier 상태 관리
│   │   │       └── widgets/     # Feature별 UI 컴포넌트
│   │   └── services/     # 레거시 서비스 (마이그레이션 중)
│   └── test/
│       ├── domain/       # UseCase 단위 테스트
│       ├── integration/  # 통합 테스트
│       │   ├── automated/ # UI 자동화 테스트
│       │   └── real_api/  # 실제 API 테스트
│       └── widget/       # 위젯 테스트
│
└── superport_api/        # Rust Backend
    ├── src/
    │   ├── handlers/     # API 엔드포인트
    │   ├── services/     # 비즈니스 로직
    │   └── entities/     # DB 모델
    └── migrations/       # DB 마이그레이션

✅ Implementation Status

Architecture (100% - Clean Architecture)

• ✅ Domain Layer: 25개 UseCase, 6개 Repository 인터페이스
• ✅ Data Layer: 9개 DataSource, 52개 DTO 모델 (Freezed)
• ✅ Presentation Layer: 28개 Controller (ChangeNotifier)
• ✅ DI Container: GetIt + Injectable 패턴 완성
• ✅ Error Handling: Either<Failure, Success> 패턴 전체 적용
• ✅ API Integration: Dio + Retrofit + Interceptors 체계 구축

Completed Features (100%)

• ✅ 인증 시스템: JWT 기반 로그인/로그아웃
• ✅ 회사 관리: CRUD, 지점 관리, 연락처 정보, 소프트 딜리트 완료
• ✅ 사용자 관리: 계정 생성, 권한 설정 (Admin/Manager/Member)
• ✅ 창고 위치 관리: 입고지 등록 및 관리, 소프트 딜리트 완료
• ✅ 장비 입고: 시리얼 번호 추적, 수량 관리, 소프트 딜리트 완료
• ✅ 라이선스 관리: 유지보수 기간, 만료일 알림, 소프트 딜리트 완료
• ✅ 소프트 딜리트: 모든 핵심 화면(Company, Equipment, License, Warehouse Location)에서 논리 삭제 구현

In Progress (80%)

• 🔄 장비 출고: API 연동 완료, UI 개선 중
• 🔄 대시보드: 기본 통계 표시, 차트 구현 중
• 🔄 검색 및 필터: 기본 검색 구현, 고급 필터 개발 중
• 🔄 Service → Repository 마이그레이션: 진행률 85%, 일부 UseCase 의존성 정리 중
• 🔄 데이터 무결성: 소프트 딜리트 완료, 하드 딜리트 프로세스 검토 중

Not Started (0%)

• ⏳ 장비 대여: 대여/반납 프로세스
• ⏳ 장비 폐기: 폐기 사유 및 이력 관리
• ⏳ 보고서 생성: Excel/PDF 내보내기
• ⏳ 모바일 앱: 반응형 레이아웃 최적화
• ⏳ 알림 시스템: 이메일/푸시 알림

🐛 Known Issues

Critical

시리얼_번호_중복:
  location: "장비 입고 프로세스"
  issue: "백엔드에서 중복 체크 미구현"
  workaround: "프론트엔드 임시 검증"
  priority: HIGH

권한_체크_누락:
  location: ["warehouse_location", "overview"]
  issue: "일부 화면에서 역할 기반 접근 제어 미적용"
  impact: "모든 사용자가 접근 가능"
  priority: HIGH
  note: "소프트 딜리트 구현 완료로 데이터 보안성 향상"

Minor

상태_갱신_지연:
  location: "CRUD 작업 후 리스트 화면"
  issue: "일부 화면에서 자동 새로고침 미작동"
  workaround: "수동 새로고침"
  priority: MEDIUM
  status: "소프트 딜리트 구현으로 부분적 개선"

날짜_포맷:
  location: "라이선스 만료일"
  issue: "한국 시간대 표시 불일치"
  priority: LOW

🔌 Unused Backend API Integration Plan

현재 백엔드에 구현되었으나 프론트엔드에서 미사용 중인 API

1. /overview/license-expiry - 라이선스 만료 요약

용도: 30일/60일/90일 내 만료 예정인 라이선스 요약 정보 제공 활용 계획:

• 위치: Dashboard 화면 상단 알림 배너
• 구현 방법:
  • 만료 임박 라이선스 카운트를 배지로 표시
  • 클릭 시 상세 라이선스 목록으로 이동
  • 관리자/매니저 권한일 때만 표시
• 예상 효과: 라이선스 갱신 누락 방지, 사전 대응 가능

2. /lookups - 전체 조회 데이터

용도: 시스템 전체 드롭다운/셀렉트 박스용 마스터 데이터 제공 활용 계획:

• 위치: 앱 초기화 시 한 번 호출하여 캐싱
• 구현 방법:
  • LookupService 생성하여 전역 상태 관리
  • 장비 타입, 상태 코드, 제조사 목록 등 일괄 관리
  • 각 화면에서 개별 API 호출 대신 캐시된 데이터 사용
• 예상 효과: API 호출 횟수 감소, 응답 속도 향상

3. /lookups/type - 타입별 조회 데이터

용도: 특정 타입의 조회 데이터만 선택적으로 가져오기 활용 계획:

• 위치: 대량 데이터 입력 화면 (장비 일괄 등록, Excel 임포트)
• 구현 방법:
  • 필요한 타입만 선택적으로 로드
  • 동적 폼 생성 시 활용
  • 타입별 유효성 검증 규칙 적용
• 예상 효과: 메모리 사용량 최적화, 동적 UI 구성 가능

4. /health - 시스템 상태 체크

용도: API 서버 상태 및 DB 연결 상태 확인 활용 계획:

• 위치:
  • 로그인 화면 하단 (서버 상태 인디케이터)
  • 관리자 대시보드 (시스템 모니터링 위젯)
• 구현 방법:
  • 30초 간격 폴링으로 서버 상태 모니터링
  • 연결 실패 시 자동 재시도 및 사용자 알림
  • 서버 점검 시간 사전 공지 표시
• 예상 효과: 시스템 안정성 향상, 장애 조기 감지

구현 우선순위

1. Phase 1 (1주차): /overview/license-expiry - 대시보드 통합
2. Phase 2 (2주차): /lookups - 전역 캐싱 시스템 구축
3. Phase 3 (3주차): /health - 시스템 모니터링 구현
4. Phase 4 (4주차): /lookups/type - 동적 폼 시스템 구축

📋 TODO List

Immediate (This Week)

• 소프트 딜리트 구현 (모든 핵심 화면 완료)
• 장비 출고 프로세스 완성
• 대시보드 차트 구현 (Chart.js 통합)
• 시리얼 번호 중복 체크 백엔드 구현
• 권한 체크 누락 화면 수정
• /overview/license-expiry API 연동 (대시보드 알림 배너)
• 소프트 딜리트된 데이터 복구 기능 구현

Short Term (This Month)

• 장비 대여/반납 기능 구현
• 고급 검색 필터 구현 (삭제된 항목 필터링 포함)
• Excel 내보내기 기능
• 성능 최적화 (가상 스크롤링)
• /lookups API 활용한 전역 캐싱 시스템 구축
• /health API 활용한 서버 상태 모니터링
• 하드 딜리트 프로세스 및 권한 설계

Long Term

• 모바일 앱 최적화
• 푸시 알림 시스템
• 다국어 지원 (영어)
• 대시보드 커스터마이징
• /lookups/type API 활용한 동적 폼 시스템

🔑 Key Decisions

2025-08-12

• Decision: 소프트 딜리트 시스템 전면 구현 완료
• Reason: 데이터 무결성 보장, 실수로 인한 데이터 손실 방지, 감사 추적 강화
• Impact: Company, Equipment, License, Warehouse Location 모든 핵심 엔티티에서 논리 삭제 지원
• Implementation: deleted_at 필드 추가, API 및 UI에서 삭제된 데이터 필터링 자동 처리

2025-01-11

• Decision: Clean Architecture 전면 적용 완료
• Reason: 확장성, 테스트 용이성, 유지보수성 극대화
• Impact: 모든 기능이 UseCase 패턴으로 재구현됨

2025-01-07

• Decision: Mock 서비스 제거, Real API 전용으로 전환
• Reason: 개발 환경 단순화 및 실제 환경 테스트 강화

2025-01-06

• Decision: Provider 패턴 유지 (Riverpod 마이그레이션 보류)
• Reason: 현재 구조가 안정적, 팀 학습 곡선 고려

2024-12-20

• Decision: Flutter Web 우선 개발
• Reason: 빠른 배포와 크로스 플랫폼 지원

🚀 Quick Commands

Development

# Start development (Real API)
flutter run -d chrome

# Run tests
flutter test

# Generate code (Freezed, JsonSerializable)
flutter pub run build_runner build --delete-conflicting-outputs

# API integration test
./test_api_integration.sh

# Start backend API (별도 터미널)
cd /Users/maximilian.j.sul/Documents/flutter/superport_api
cargo run

# View API logs
cd /Users/maximilian.j.sul/Documents/flutter/superport_api
tail -f logs/api.log

API Configuration

Base URL: http://43.201.34.104:8080/api/v1
Test Account: admin@superport.kr / admin123!
API Source Code: /Users/maximilian.j.sul/Documents/flutter/superport_api

📞 Team Contacts

• Backend API Issues: Rust 백엔드 팀
• UI/UX Questions: 디자인 팀
• Business Logic: 프로덕트 매니저

---

🏆 Architecture Quality Score

영역	점수	설명
Clean Architecture	⭐⭐⭐⭐⭐	완벽한 레이어 분리
의존성 주입	⭐⭐⭐⭐⭐	GetIt + Injectable 우수
상태 관리	⭐⭐⭐⭐☆	Provider 패턴 안정적
API 통신	⭐⭐⭐⭐⭐	Dio + 인터셉터 체계적
코드 생성	⭐⭐⭐⭐⭐	Freezed 완벽 활용
테스트 구조	⭐⭐⭐⭐☆	포괄적이지만 개선 여지
폴더 구조	⭐⭐⭐⭐⭐	매우 체계적

종합 점수: 4.6/5.0 ⭐⭐⭐⭐⭐

---

Project Stage: Development (80% Complete)
Next Milestone: Beta Release (2025-02-01)
Last Updated: 2025-08-12
Version: 4.1

📅 Recent Updates

2025-08-12 - Soft Delete Implementation Complete

Agent: frontend-developer
Task: 소프트 딜리트 기능 전체 화면 구현
Result: Company, Equipment, License, Warehouse Location 모든 핵심 화면에서 소프트 딜리트 완료
Impact: 데이터 무결성 대폭 향상, 실수로 인한 데이터 손실 방지
Next Steps: 하드 딜리트 프로세스 설계, 삭제된 데이터 복구 기능 구현