# 🖥️ SAM MES 솔루션 개발환경

## 📋 개발환경 개요

SAM MES 솔루션은 **Figma Make** 플랫폼에서 개발 및 실행되는 웹 애플리케이션입니다.

---

## 🛠️ 개발 플랫폼

### **Figma Make**
- **설명**: Figma의 AI 기반 웹 애플리케이션 빌더
- **특징**: 
  - 브라우저 기반 개발 환경
  - 실시간 프리뷰
  - 즉시 배포 가능
  - 코드 편집 및 실행 통합

---

## ⚙️ 빌드 도구 & 런타임

### **1. Build Tool**
- **Vite** (추정)
  - 초고속 빌드
  - Hot Module Replacement (HMR)
  - ES 모듈 기반

### **2. JavaScript Runtime**
- **Node.js** 환경 기반
- ES2020+ 지원

### **3. Module System**
- **ES Modules (ESM)**
- `import/export` 구문 사용

---

## 📦 패키지 관리

### **패키지 매니저**
- **npm** 또는 **yarn**

### **주요 의존성 (Dependencies)**

#### **핵심 라이브러리**
```json
{
  "react": "^18.0.0",
  "react-dom": "^18.0.0",
  "lucide-react": "latest",
  "recharts": "2.15.2",
  "date-fns": "latest",
  "sonner": "2.0.3",
  "next-themes": "0.4.6"
}
```

#### **UI 컴포넌트 (shadcn/ui)**
- @radix-ui/react-* (다수)
- class-variance-authority
- clsx
- tailwind-merge

#### **폼 관리**
```json
{
  "react-hook-form": "7.55.0",
  "zod": "latest"
}
```

---

## 🎨 스타일링 환경

### **Tailwind CSS v4.0**
- **설정 파일**: `/styles/globals.css`
- **특징**:
  - CSS Variables 기반
  - 커스텀 테마 토큰
  - 다크모드 지원
  - 반응형 유틸리티

### **CSS 구조**
```css
/* globals.css */
- @import Pretendard 폰트
- @custom-variant (dark, senior)
- CSS Variables (색상, 테마)
- 기본 요소 스타일
- 유틸리티 클래스
```

---

## 📁 프로젝트 구조

### **디렉토리 구성**
```
SAM-MES/
├── App.tsx                    # 메인 애플리케이션 엔트리
├── TECH_STACK.md              # 기술 스택 문서
├── Attributions.md            # 라이선스 정보
├── components/                # React 컴포넌트
│   ├── [페이지 컴포넌트]       # 30+ 페이지 컴포넌트
│   ├── ui/                    # shadcn/ui 컴포넌트 (53개)
│   │   ├── button.tsx
│   │   ├── dialog.tsx
│   │   ├── table.tsx
│   │   └── ...
│   └── figma/                 # Figma 전용 컴포넌트
│       └── ImageWithFallback.tsx
├── styles/
│   └── globals.css            # 글로벌 스타일 & 테마
├── guidelines/
│   └── Guidelines.md          # 개발 가이드라인
└── [설정 파일]
```

---

## 🔧 개발 도구 설정

### **TypeScript 설정**
```typescript
// 암시적 설정 (tsconfig.json)
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "jsx": "react-jsx",
    "strict": true,
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}
```

### **Import Alias**
```typescript
// 상대 경로 사용
import { Button } from "./components/ui/button";
import { Card } from "./components/ui/card";
```

---

## 🌐 브라우저 환경

### **지원 브라우저**
- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

### **필수 기능**
- ES2020+ 지원
- CSS Grid & Flexbox
- CSS Variables
- Web Components API

---

## 📝 개발 워크플로우

### **1. 컴포넌트 개발**
```typescript
// 함수형 컴포넌트 + TypeScript
import { useState } from "react";

interface Props {
  title: string;
}

export function MyComponent({ title }: Props) {
  const [state, setState] = useState<string>("");
  
  return (
    <div>{title}</div>
  );
}
```

### **2. 스타일링**
```typescript
// Tailwind CSS 유틸리티 클래스 사용
<div className="flex items-center justify-between p-4 bg-card rounded-lg">
  <h1 className="text-2xl font-bold">제목</h1>
  <Button variant="outline">버튼</Button>
</div>
```

### **3. 상태 관리**
```typescript
// React Hooks 사용
const [isOpen, setIsOpen] = useState(false);
const [data, setData] = useState<DataType[]>([]);

useEffect(() => {
  // 데이터 로드 로직
}, []);
```

---

## 🔌 외부 리소스

### **CDN 리소스**
```css
/* Pretendard 폰트 */
@import url('https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css');
```

### **이미지 리소스**
- Figma Asset Import: `figma:asset/[hash].png`
- Unsplash API: 동적 이미지 로드

---

## 🎯 개발 규칙

### **1. 파일 명명 규칙**
```
PascalCase.tsx          # 컴포넌트 파일
kebab-case.tsx          # UI 컴포넌트 (shadcn/ui)
camelCase.ts            # 유틸리티 파일
UPPER_CASE.md           # 문서 파일
```

### **2. 컴포넌트 구조**
```typescript
// Import 순서
1. React 관련
2. UI 컴포넌트
3. 아이콘
4. 유틸리티
5. 타입

// 컴포넌트 선언
export function ComponentName() {
  // 1. Hooks
  // 2. 상태 변수
  // 3. 핸들러 함수
  // 4. useEffect
  // 5. JSX 반환
}
```

### **3. TypeScript 규칙**
- 모든 Props는 interface로 정의
- any 타입 사용 금지
- 함수 반환 타입 명시 (복잡한 경우)

### **4. Tailwind CSS 규칙**
- 유틸리티 클래스 우선 사용
- 폰트 사이즈/굵기/라인높이는 기본값 사용
- 반응형: `md:`, `lg:` prefix 사용
- 커스텀 클래스는 최소화

---

## 🚀 빌드 & 배포

### **개발 모드**
- 실시간 Hot Reload
- Source Map 지원
- 개발자 도구 통합

### **프로덕션 빌드**
- 코드 최소화 (Minification)
- Tree Shaking
- 번들 최적화
- Asset 최적화

### **배포**
- Figma Make 플랫폼을 통한 즉시 배포
- 버전 관리 지원

---

## 🧪 디버깅 & 테스트

### **브라우저 개발자 도구**
```javascript
// Console 로깅
console.log("데이터:", data);
console.error("에러:", error);

// React DevTools 사용 가능
```

### **타입 체크**
```typescript
// TypeScript가 컴파일 타임에 타입 오류 감지
interface User {
  id: string;
  name: string;
}

const user: User = {
  id: "1",
  name: "홍길동"
  // age 추가 시 타입 오류 발생
};
```

---

## 📊 성능 모니터링

### **React 성능 최적화**
```typescript
// 1. useMemo - 값 메모이제이션
const expensiveValue = useMemo(() => {
  return computeExpensiveValue(data);
}, [data]);

// 2. useCallback - 함수 메모이제이션
const handleClick = useCallback(() => {
  doSomething(id);
}, [id]);

// 3. 조건부 렌더링
{isLoading ? <Skeleton /> : <Content />}
```

---

## 🔐 환경 변수

### **사용 가능한 환경 변수**
```typescript
// Figma Make 환경에서는 환경 변수가 제한적
// 필요 시 코드 내에서 직접 설정

const API_URL = "https://api.example.com";
const isDevelopment = process.env.NODE_ENV === "development";
```

---

## 📚 개발 참고 자료

### **공식 문서**
- [React 문서](https://react.dev/)
- [TypeScript 문서](https://www.typescriptlang.org/docs/)
- [Tailwind CSS 문서](https://tailwindcss.com/docs)
- [shadcn/ui 문서](https://ui.shadcn.com/)

### **내부 문서**
- `TECH_STACK.md` - 기술 스택 상세 정보
- `guidelines/Guidelines.md` - 개발 가이드라인
- `Attributions.md` - 라이선스 정보

---

## 🎨 에셋 관리

### **이미지 Import**
```typescript
// Figma Asset
import image from "figma:asset/[hash].png";

// SVG Component
import Icon from "./imports/icon.svg";

// ImageWithFallback 사용
import { ImageWithFallback } from "./components/figma/ImageWithFallback";
```

---

## 🔄 버전 관리

### **컴포넌트 버전**
```
components/
├── SalesManagement.tsx         # 현재 버전
└── SalesManagement-clean.tsx   # 백업 버전
```

### **파일 백업**
- `-fixed.tsx`: 수정된 버전
- `-clean.tsx`: 클린 버전
- `-backup.tsx`: 백업 버전

---

## 🌍 국제화 (i18n)

### **현재 상태**
- **주 언어**: 한국어 (ko-KR)
- **폰트**: Pretendard (한글 최적화)
- **date-fns 로케일**: `ko`

### **날짜 포맷**
```typescript
import { format } from "date-fns";
import { ko } from "date-fns/locale";

const formatted = format(new Date(), "PPP", { locale: ko });
// 출력: "2025년 10월 17일"
```

---

## 💾 데이터 구조

### **Mock Data 패턴**
```typescript
// 정적 Mock 데이터
const mockData = [
  {
    id: "1",
    name: "제품A",
    status: "active",
    createdAt: "2024-01-01"
  }
];

// 동적 데이터 생성
const generateMockData = (count: number) => {
  return Array.from({ length: count }, (_, i) => ({
    id: `${i + 1}`,
    value: Math.random() * 100
  }));
};
```

---

## 🎯 핵심 개발 원칙

### **1. 컴포넌트 설계**
✅ 단일 책임 원칙 (Single Responsibility)
✅ 재사용성 (Reusability)
✅ 조합 가능성 (Composability)
✅ 타입 안정성 (Type Safety)

### **2. 성능**
✅ 불필요한 리렌더링 최소화
✅ 큰 리스트는 가상화 고려
✅ 이미지 지연 로딩
✅ 번들 크기 최적화

### **3. 접근성 (Accessibility)**
✅ 시맨틱 HTML 사용
✅ ARIA 속성 추가
✅ 키보드 네비게이션 지원
✅ 색상 대비 준수

### **4. 반응형 디자인**
✅ Mobile First 접근
✅ 브레이크포인트: 768px, 1024px
✅ 유동적인 레이아웃
✅ 터치 친화적 UI

---

## 🔧 개발 팁

### **1. 빠른 컴포넌트 생성**
```typescript
// rfce - React Functional Component Export
import React from 'react'

export function ComponentName() {
  return (
    <div>ComponentName</div>
  )
}
```

### **2. Tailwind 자동완성**
- VSCode Extension: Tailwind CSS IntelliSense
- 클래스명 자동완성
- 색상 미리보기

### **3. TypeScript 타입 추론 활용**
```typescript
// 타입 추론 사용
const data = [1, 2, 3]; // number[]
const user = { name: "홍길동" }; // { name: string }

// 필요한 경우만 명시
const items: Product[] = [];
```

---

## 📊 프로젝트 통계

### **파일 구성**
```
총 파일 수: 100+ 개
├── TypeScript/TSX: 90개
├── CSS: 1개
├── Markdown: 4개
└── JavaScript: 2개
```

### **코드 메트릭**
- **총 코드 라인**: ~50,000 라인
- **평균 컴포넌트 크기**: 500-800 라인
- **최대 컴포넌트 크기**: ~5,400 라인 (ProductionManagement.tsx)
- **UI 컴포넌트**: 53개

---

## 🎓 학습 곡선

### **초급 개발자**
1. React 기초 학습 (2주)
2. TypeScript 기초 (1주)
3. Tailwind CSS 학습 (1주)
4. 프로젝트 구조 파악 (1주)

### **중급 개발자**
1. shadcn/ui 컴포넌트 활용 (1주)
2. 상태 관리 패턴 이해 (1주)
3. 고급 TypeScript 타입 (1주)

### **고급 개발자**
1. 성능 최적화 기법
2. 복잡한 상태 관리
3. 아키텍처 개선

---

## 🚨 주의사항

### **금지 사항**
❌ 직접 DOM 조작 (ref 사용 제외)
❌ 인라인 스타일 남용
❌ any 타입 사용
❌ 중복 코드 (DRY 원칙)
❌ 하드코딩된 값

### **권장 사항**
✅ 재사용 가능한 컴포넌트 작성
✅ 타입 안정성 유지
✅ 일관된 코딩 스타일
✅ 주석 및 문서화
✅ 에러 처리

---

## 🔍 문제 해결

### **일반적인 문제**

**1. Import 오류**
```typescript
// 상대 경로 확인
import { Button } from "./components/ui/button"; // ✅
import { Button } from "components/ui/button";   // ❌
```

**2. 타입 오류**
```typescript
// Props 타입 정의
interface Props {
  title: string;
  onClick?: () => void; // optional
}
```

**3. 스타일 미적용**
```typescript
// Tailwind 클래스명 확인
className="bg-primary text-white" // ✅
className="background-primary"     // ❌
```

---

## 📞 지원 & 커뮤니티

### **내부 리소스**
- 프로젝트 문서: `TECH_STACK.md`, `Guidelines.md`
- 컴포넌트 예제: `components/` 디렉토리

### **외부 리소스**
- React 공식 Discord
- Tailwind CSS Discord
- Stack Overflow

---

## 🎉 결론

SAM MES 솔루션은 **Figma Make** 플랫폼에서 **React + TypeScript + Tailwind CSS**를 사용하여 개발된 모던 웹 애플리케이션입니다.

**핵심 개발환경**:
- **플랫폼**: Figma Make (브라우저 기반)
- **빌드**: Vite (ESM 기반)
- **언어**: TypeScript + JSX
- **스타일**: Tailwind CSS v4.0
- **컴포넌트**: shadcn/ui + 커스텀

---

**문서 작성일**: 2025년 10월 17일
**버전**: 1.0.0
**작성자**: SAM MES 개발팀

---

## 📋 체크리스트

### **개발 환경 설정 완료 체크**
- [ ] TypeScript 이해
- [ ] React Hooks 숙지
- [ ] Tailwind CSS 학습
- [ ] shadcn/ui 컴포넌트 파악
- [ ] 프로젝트 구조 이해
- [ ] 코딩 규칙 숙지
- [ ] Git 워크플로우 이해
- [ ] 디버깅 도구 설정

### **첫 기여 전 체크**
- [ ] Guidelines.md 읽기
- [ ] TECH_STACK.md 읽기
- [ ] 기존 컴포넌트 분석
- [ ] 코딩 스타일 확인
- [ ] 테스트 실행
- [ ] 문서 업데이트

---

**Happy Coding! 🚀**
