# CLAUDE.md

이 파일은 Claude Code (claude.ai/code)가 SuperPort 프로젝트에서 작업할 때 필요한 가이드라인을 제공합니다.

## 🎯 프로젝트 개요

**SuperPort**는 Flutter 기반 장비 관리 ERP 시스템으로, 웹과 모바일 플랫폼을 지원합니다.

### 주요 기능
- 장비 입출고 관리 및 이력 추적
- 회사/지점 계층 구조 관리
- 사용자 권한 관리 (관리자/일반)
- 유지보수 라이선스 관리
- 창고 위치 관리

### 기술 스택
- **Frontend**: Flutter (Web + Mobile)
- **State Management**: Custom Controller Pattern
- **Data Layer**: MockDataService (API 연동 준비됨)
- **UI Theme**: Shadcn Design System
- **Localization**: 한국어 우선, 영어 지원

## 📂 프로젝트 구조

### 아키텍처 개요
```
lib/
├── models/              # 데이터 모델 (JSON serialization 포함)
├── services/            # 비즈니스 로직 서비스
│   └── mock_data_service.dart  # Singleton 패턴 Mock 데이터
├── screens/             # 화면별 디렉토리
│   ├── equipment/       # 장비 관리
│   ├── company/         # 회사/지점 관리
│   ├── user/           # 사용자 관리
│   ├── license/        # 라이선스 관리
│   ├── warehouse/      # 창고 관리
│   └── common/         # 공통 컴포넌트
│       ├── layouts/    # AppLayoutRedesign (사이드바 네비게이션)
│       └── custom_widgets/  # 재사용 위젯
└── theme/              # theme_shadcn.dart (커스텀 테마)
```

### 상태 관리 패턴
- **Controller Pattern** 사용 (Provider 대신)
- 각 화면마다 전용 Controller 구현
- 위치: `lib/screens/*/controllers/`
- 예시: `EquipmentInController`, `CompanyController`

## 💼 비즈니스 엔티티

### 1. Equipment (장비)
- 제조사, 이름, 카테고리 (대/중/소)
- 시리얼 번호가 있으면 수량 = 1 (수정 불가)
- 시리얼 번호가 없으면 복수 수량 가능
- 입출고 이력: 'I' (입고), 'O' (출고)

### 2. Company (회사)
- 본사/지점 계층 구조
- 지점별 독립된 주소와 연락처
- 회사 → 지점들 관계

### 3. User (사용자)
- 회사 연결
- 권한 레벨: 'S' (관리자), 'M' (일반)

### 4. License (라이선스)
- 유지보수 라이선스
- 기간 및 방문 주기 관리

## 🛠 개발 명령어

```bash
# 개발 실행
flutter run

# 빌드
flutter build web      # 웹 배포
flutter build apk      # Android APK
flutter build ios      # iOS (macOS 필요)

# 코드 품질
flutter analyze        # 정적 분석
flutter format .       # 코드 포맷팅

# 의존성
flutter pub get        # 설치
flutter pub upgrade    # 업그레이드

# 테스트
flutter test           # 테스트 실행
```

## 📐 코딩 컨벤션

### 네이밍 규칙
- **파일**: snake_case (`equipment_list.dart`)
- **클래스**: PascalCase (`EquipmentInController`)
- **변수/메서드**: camelCase (`userName`, `calculateTotal`)
- **Boolean**: 동사 기반 (`isReady`, `hasError`)

### 파일 구조
- 300줄 초과 시 기능별 분리 고려
- 모델별 파일 분리 (`equipment.dart` vs `equipment_in.dart`)
- 재사용 컴포넌트는 `custom_widgets/`로 추출

### UI 가이드라인
- **Metronic Admin Template** 디자인 패턴 준수
- **Material Icons** 사용
- **ShadcnCard**: 일관된 카드 스타일
- **FormFieldWrapper**: 폼 필드 간격
- 반응형 디자인 (웹/모바일)

## 🚀 구현 가이드

### 새 기능 추가 순서
1. `lib/models/`에 모델 생성
2. `MockDataService`에 목 데이터 추가
3. 화면 디렉토리에 Controller 생성
4. 목록/폼 화면 구현
5. `AppLayoutRedesign`에 네비게이션 추가

### 폼 구현 팁
- 필수 필드 검증
- 날짜 선택: 과거 날짜만 허용 (이력 기록용)
- 카테고리: 계층적 드롭다운 (대→중→소)
- 생성/수정 모드 모두 처리

## 📋 현재 상태

### ✅ 구현 완료
- 로그인 화면 (Mock 인증)
- 메인 레이아웃 (사이드바 네비게이션)
- 모든 엔티티 CRUD
- 한국어/영어 다국어 지원
- 반응형 디자인
- Mock 데이터 서비스

### 🔜 구현 예정
- API 연동
- 실제 인증
- 바코드 스캔
- 테스트 커버리지
- 장비 보증 추적
- PDF 내보내기 (의존성 준비됨)

## 🔍 디버깅 팁
- 데이터 문제: `MockDataService` 확인
- 비즈니스 로직: Controller 확인
- 정적 분석: `flutter analyze`
- 웹 문제: 브라우저 콘솔 확인

## 💬 응답 규칙

### 언어 설정
- **코드/변수명**: 영어
- **주석/문서/응답**: 한국어
- 기술 용어는 영어 병기 가능

### Git 커밋 메시지
```
type: 간단한 설명 (한국어)

선택적 상세 설명
```

**타입**:
- `feat`: 새 기능
- `fix`: 버그 수정
- `refactor`: 리팩토링
- `docs`: 문서 변경
- `test`: 테스트
- `chore`: 빌드/도구

**주의**: AI 도구 속성 표시 금지