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
```yaml
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
```
/Users/maximilian.j.sul/Documents/flutter/
├── superport/            # Flutter Frontend
│   ├── lib/
│   │   ├── core/         # 핵심 설정 및 유틸리티
│   │   ├── data/         # API 통신 레이어
│   │   │   ├── models/   # Freezed DTO
│   │   │   └── datasources/ # API 클라이언트
│   │   ├── screens/      # UI 화면
│   │   │   └── [feature]/
│   │   │       ├── controllers/ # 상태 관리
│   │   │       └── widgets/     # UI 컴포넌트
│   │   └── services/     # 비즈니스 로직
│
└── superport_api/        # Rust Backend
    ├── src/
    │   ├── handlers/     # API 엔드포인트
    │   ├── services/     # 비즈니스 로직
    │   └── entities/     # DB 모델
    └── migrations/       # DB 마이그레이션
```

## ✅ Implementation Status

### Completed Features (100%)
- ✅ **인증 시스템**: JWT 기반 로그인/로그아웃
- ✅ **회사 관리**: CRUD, 지점 관리, 연락처 정보
- ✅ **사용자 관리**: 계정 생성, 권한 설정 (Admin/Manager/Member)
- ✅ **창고 위치 관리**: 입고지 등록 및 관리
- ✅ **장비 입고**: 시리얼 번호 추적, 수량 관리
- ✅ **라이선스 관리**: 유지보수 기간, 만료일 알림

### In Progress (70%)
- 🔄 **장비 출고**: API 연동 완료, UI 개선 필요
- 🔄 **대시보드**: 기본 통계 표시, 차트 구현 중
- 🔄 **검색 및 필터**: 기본 검색 구현, 고급 필터 개발 중

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

## 🐛 Known Issues

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

권한_체크_누락:
  location: ["warehouse_location", "overview"]
  issue: "일부 화면에서 역할 기반 접근 제어 미적용"
  impact: "모든 사용자가 접근 가능"
  priority: HIGH
```

### Minor
```yaml
상태_갱신_지연:
  location: "CRUD 작업 후 리스트 화면"
  issue: "일부 화면에서 자동 새로고침 미작동"
  workaround: "수동 새로고침"
  priority: MEDIUM

날짜_포맷:
  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-01-07
- **Decision**: Mock 서비스 제거, Real API 전용으로 전환
- **Reason**: 개발 환경 단순화 및 실제 환경 테스트 강화

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

### 2024-12-20
- **Decision**: Flutter Web 우선 개발
- **Reason**: 빠른 배포와 크로스 플랫폼 지원

## 🚀 Quick Commands

### Development
```bash
# 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**: 프로덕트 매니저

---

**Project Stage**: Development (70% Complete)  
**Next Milestone**: Beta Release (2025-02-01)  
**Last Updated**: 2025-01-09  
**Version**: 3.1