superport/CLAUDE.md

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 (라이선스)

• 유지보수 라이선스
• 기간 및 방문 주기 관리

🛠 개발 명령어

# 개발 실행
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 도구 속성 표시 금지