superport/CLAUDE.md

Superport ERP System - Project Rules v2.0

💡 Note: Global Claude Code rules from ~/.claude/CLAUDE.md are automatically applied. This document contains project-specific configurations only.

🎯 Project Identity

Superport는 Rust 백엔드 + Flutter 웹/모바일 기반의 엔터프라이즈 ERP 시스템입니다.

Core Domains

• Equipment Management: 장비 입고/출고, 시리얼 번호 추적, 재고 관리
• Company Management: 고객사 정보, 다중 지점 관리
• User Management: 역할 기반 접근 제어 (S: 관리자, M: 멤버)
• License Management: 유지보수 라이선스, 만료일 추적
• Warehouse Management: 창고 위치 체계적 관리

🏗️ Architecture Rules

Clean Architecture Structure

lib/
├── core/               # ⚠️ 핵심 설정 - 신중히 수정
│   ├── api_client.dart     # Dio/Retrofit 설정
│   ├── exceptions.dart     # 전역 예외 처리
│   └── navigation.dart     # 라우팅 관리
├── data/               # 데이터 레이어
│   ├── dto/                # API 응답 모델 (Freezed)
│   ├── repositories/       # 데이터 소스 추상화
│   └── services/          # API 서비스 (Retrofit)
├── domain/             # 비즈니스 로직
│   ├── entities/          # 도메인 모델
│   ├── repositories/      # Repository 인터페이스
│   └── usecases/         # 비즈니스 로직
├── services/           # 애플리케이션 서비스
│   ├── auth_service.dart  # JWT 인증 관리
│   ├── api_service.dart   # API 호출 관리
│   └── storage_service.dart # 로컬 저장소
├── screens/            # Feature-First UI
│   └── [feature]/
│       ├── controllers/   # Provider 기반 상태 관리
│       ├── widgets/       # 재사용 컴포넌트
│       └── [feature]_form.dart
└── di/                 # GetIt 의존성 주입

Architecture Constraints

constraints:
  - "Controller는 반드시 ChangeNotifier 상속"
  - "모든 API 호출은 ApiService 경유"
  - "DTO는 Freezed + JsonSerializable 필수"
  - "화면별 Controller 분리 원칙"
  - "Mock과 Real 서비스 완전 분리"

💻 Development Environment

API Endpoints

development:
  base_url: "https://api-dev.beavercompany.co.kr"
  test_account: "admin@test.com / Test123!@#"
  jwt_expiry: 24h

production:
  base_url: "TBD"
  security: "JWT + Secure Storage"

Environment Switching

// 환경 변수 설정 (.env)
API_MODE=mock  # mock | real
BASE_URL=https://api-dev.beavercompany.co.kr

// 코드에서 환경 전환
final isMockMode = dotenv.env['API_MODE'] == 'mock';
if (isMockMode) {
  GetIt.I.registerSingleton<ApiService>(MockApiService());
} else {
  GetIt.I.registerSingleton<ApiService>(RealApiService());
}

🧪 Test Automation System

Test Infrastructure

// 모든 화면 테스트는 BaseScreenTest 상속
abstract class BaseScreenTest {
  // 자동 에러 진단 및 수정
  ApiErrorDiagnostics diagnostics;
  
  // 한국식 현실적 테스트 데이터
  TestDataGenerator generator;
  
  // 병렬 실행 제어 (최대 3개)
  SemaphoreManager semaphore;
}

Test Execution Priority

test_order:
  1: "Company Management"     # 회사 먼저 생성
  2: "User Management"        # 회사에 사용자 연결
  3: "Warehouse Location"     # 창고 위치 설정
  4: "Equipment In"          # 장비 입고
  5: "License Management"    # 라이선스 등록
  6: "Equipment Out"         # 장비 출고
  7: "Overview Dashboard"    # 통계 확인

Test Commands

# 전체 테스트 실행 (병렬)
flutter test test/master_test_suite.dart

# 특정 화면 테스트
flutter test test/screens/company/company_test.dart

# Mock 모드 테스트
API_MODE=mock flutter test

# 에러 진단 모드
flutter test --dart-define=DIAGNOSTIC_MODE=true

🎨 UI/UX Standards

Design System

base_template: "Metronic Admin Template"
component_library: "ShadCN Flutter Port"

colors:
  primary: "#5867dd"      # Metronic 기본색
  secondary: "#34bfa3"
  background: "#f7f8fa"
  error: "#fd397a"
  success: "#0abb87"

typography:
  font_family: "NotoSansKR"
  korean_support: true

layout:
  style: "Microsoft Dynamics 365"
  structure: "Header + Sidebar + Content"
  responsive: "Web First → Mobile Adaptive"

Component Patterns

// 모든 폼은 이 패턴 따르기
class EntityForm extends StatefulWidget {
  final EntityController controller;
  final FormMode mode; // create | edit | view
  
  // 필수 섹션
  Widget buildBasicInfo() {}
  Widget buildDetailInfo() {}
  Widget buildActionButtons() {}
}

// 리스트 화면 패턴
class EntityList extends StatelessWidget {
  // 필수 요소
  Widget buildSearchBar() {}
  Widget buildFilterOptions() {}
  Widget buildDataTable() {}
  Widget buildPagination() {}
}

🔌 API Integration Rules

Error Handling Strategy

// 모든 API 호출은 이 패턴 사용
try {
  final response = await apiService.call();
  return Right(response);
} on DioException catch (e) {
  // 422개 에러 패턴 자동 분석
  final diagnosis = ApiErrorDiagnostics.analyze(e);
  return Left(ApiFailure(
    code: diagnosis.code,
    message: diagnosis.userMessage, // 한국어
    technicalDetails: diagnosis.details,
  ));
}

Response Parsing Rules

// JSON 파싱 주의사항
rules:
  - "null 값 안전 처리 필수"
  - "날짜는 ISO 8601 형식"
  - "ID는 항상 String 타입"
  - "빈 배열은 [] 반환"
  - "중첩 객체는 별도 DTO 생성"

🚨 Critical Areas & Known Issues

⚠️ Current Gotchas

equipment_in:
  issue: "시리얼 번호 중복 체크 미구현"
  workaround: "프론트엔드에서 임시 검증"

license_management:
  issue: "만료일 계산 로직 불일치"
  note: "백엔드와 프론트엔드 로직 통일 필요"

user_permission:
  issue: "권한 체크 일부 화면 누락"
  affected: ["warehouse_location", "overview"]

🔥 Hot Paths (성능 주의)

critical_operations:
  - path: "Equipment List with 10000+ items"
    solution: "Virtual scrolling 구현됨"
    
  - path: "Dashboard statistics calculation"
    solution: "5분 캐싱 적용"
    
  - path: "Company branch tree loading"
    solution: "Lazy loading 필수"

📊 Current Sprint Focus

Active Development (2025-01-06)

priority_1:
  task: "Overview Dashboard 완성"
  acceptance_criteria:
    - "실시간 통계 데이터 정확성"
    - "차트 렌더링 성능 최적화"
    - "필터링 기능 구현"

priority_2:
  task: "Equipment Out 프로세스"
  blockers:
    - "출고 승인 워크플로우 미정"
    - "재고 차감 로직 검증 필요"

priority_3:
  task: "Mobile App 변환 준비"
  requirements:
    - "반응형 레이아웃 점검"
    - "터치 제스처 최적화"

🧬 Code Generation Commands

Freezed & JsonSerializable

# 단일 파일 생성
flutter pub run build_runner build --delete-conflicting-outputs

# 전체 재생성 (주의: 시간 소요)
flutter pub run build_runner build --delete-conflicting-outputs

# Watch mode (개발 중)
flutter pub run build_runner watch

Injectable (DI)

# DI 설정 재생성
flutter pub run build_runner build --delete-conflicting-outputs

🔍 Debugging Helpers

Quick Debug Commands

// API 응답 로깅
ApiService.enableLogging = true;

// Mock 데이터 확인
MockDataViewer.show(context);

// 현재 인증 상태
AuthService.debugPrintToken();

// Controller 상태 추적
controller.addListener(() => print(controller.debugState));

Performance Monitoring

// 화면 렌더링 시간 측정
Timeline.startSync('ScreenRender');
// ... rendering code
Timeline.finishSync();

// API 호출 시간 추적
final stopwatch = Stopwatch()..start();
await apiCall();
print('API took: ${stopwatch.elapsed}');

📝 Commit Message Convention

Project-Specific Prefixes

equipment: 장비 관리 관련
company: 회사 관리 관련
user: 사용자 관리 관련
license: 유지보수 라이선스 관련
warehouse: 창고 관련
dashboard: 대시보드 관련
auth: 인증/권한 관련
api: API 연동 관련

Examples

equipment: 시리얼 번호 중복 검증 로직 추가
company: 지점 트리 구조 lazy loading 구현
test: Equipment In 자동화 테스트 완성
api: 422 에러 자동 복구 메커니즘 구현

🎯 Success Metrics

Code Quality Standards

flutter_analyze:
  errors: 0
  warnings: < 10
  info: < 50

test_coverage:
  minimum: 80%
  critical_paths: 100%

performance:
  initial_load: < 3s
  api_response: < 500ms
  list_render: < 100ms

🚀 Quick Start Guide

For New Developers

# 1. 환경 설정
cp .env.example .env
flutter pub get

# 2. 코드 생성
flutter pub run build_runner build --delete-conflicting-outputs

# 3. Mock 모드로 시작
API_MODE=mock flutter run -d chrome

# 4. 테스트 실행
flutter test test/master_test_suite.dart

# 5. 실제 API 연동
API_MODE=real flutter run -d chrome

---

Version: 2.0
Last Updated: 2025-01-06
Project Stage: Production Ready
Next Milestone: Mobile App Release