feat: API 통합을 위한 기초 인프라 구축

- 네트워크 레이어 구현 (Dio 기반 ApiClient) - 환경별 설정 관리 시스템 구축 - 의존성 주입 설정 (GetIt) - API 엔드포인트 상수 정의 - 인터셉터 구현 (Auth, Error, Logging) - 프로젝트 아키텍처 개선 (core, data, di 디렉토리 구조) - API 통합 계획서 및 요구사항 문서 작성 - 필요 패키지 추가 (dio, flutter_secure_storage, get_it 등)
2025-07-24 14:54:28 +09:00
parent e0bc5894b2
commit 2b31d3af5f
29 changed files with 3542 additions and 344 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,174 @@
+# 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 도구 속성 표시 금지