sam-docs/quickstart/quick-start.md

# SAM 개발 빠른 참조

**5분 가이드** - 일상 개발에 필요한 핵심 규칙

---

## 🚀 개발 명령어

```bash
# 전체 서비스 시작
composer dev              # Laravel + Queue + Pail + Vite

# 개별 명령어
php artisan migrate       # DB 마이그레이션
./vendor/bin/pint        # 코드 포맷팅
php artisan test         # 테스트 실행
npm run dev              # Vite HMR (프론트엔드)

# API 문서
# http://api.sam.kr/api-docs/index.html (Swagger)
```

**자세히:** [`claudedocs/SAM/dev_commands.md`](./claudedocs/SAM/dev_commands.md)

---

## 📝 API 개발 3대 원칙

### 1️⃣ Service-First
```php
// ✅ Good
class ProductController {
    public function index(Request $request, ProductService $service) {
        return ApiResponse::handle(fn() =>
            $service->getList($request->validated())
        );
    }
}

// ❌ Bad - Controller에 비즈니스 로직
public function index() {
    $products = Product::where('tenant_id', auth()->user()->tenant_id)->get();
}
```

### 2️⃣ Multi-tenant (BelongsToTenant)
```php
// ✅ Good - 모든 모델에 적용
class Product extends Model {
    use BelongsToTenant, SoftDeletes, ModelTrait;
}

// ❌ Bad - tenant_id 필터링 누락
Product::all(); // 전체 테넌트 데이터 노출 위험
```

### 3️⃣ FormRequest 검증
```php
// ✅ Good
public function store(StoreProductRequest $request, ProductService $service) {
    return ApiResponse::handle(fn() =>
        $service->create($request->validated())
    );
}

// ❌ Bad - Controller에서 직접 검증
public function store(Request $request) {
    $validated = $request->validate([...]);
}
```

**자세히:** [`claudedocs/SAM/api_rules.md`](./claudedocs/SAM/api_rules.md)

---

## ✅ 커밋 전 5분 체크리스트

```bash
# 1. 핵심 규칙 확인
□ Service-First (비즈니스 로직 → Service)
□ FormRequest 사용 (Controller 검증 금지)
□ BelongsToTenant + SoftDeletes 적용
□ i18n 키 사용 (직접 문자열 금지)

# 2. 코드 품질
□ Pint 포맷팅 실행: ./vendor/bin/pint
□ PHPStan 검사 통과 (있는 경우)
□ 테스트 실행: php artisan test

# 3. Swagger 문서화
□ @OA\Tag, @OA\Schema 작성
□ ApiKeyAuth + BearerAuth 명시
□ Request/Response 예시 추가

# 4. 데이터베이스
□ Migration 파일에 COMMENT 추가
□ Foreign Key 최소화 (설계 시에만)
□ created_by, updated_by, deleted_by 컬럼 확인

# 5. Git
□ 의미 있는 커밋 메시지
□ feat/fix/refactor/docs 타입 사용
```

**자세히:** [`claudedocs/SAM/quality_checklist.md`](./claudedocs/SAM/quality_checklist.md)

---

## 🗄️ 데이터베이스 규칙

### 필수 컬럼
```php
Schema::create('products', function (Blueprint $table) {
    $table->id()->comment('ID');
    $table->foreignId('tenant_id')->comment('테넌트 ID');

    // 비즈니스 컬럼...

    $table->foreignId('created_by')->nullable()->comment('생성자 ID');
    $table->foreignId('updated_by')->nullable()->comment('수정자 ID');
    $table->foreignId('deleted_by')->nullable()->comment('삭제자 ID');
    $table->timestamps();
    $table->softDeletes();
});
```

### 감사 로그
- **보관 기간:** 13개월
- **대상:** 모든 Create/Update/Delete 작업
- **실패 허용:** 감사 로그 실패 시 비즈니스 로직 계속 진행

---

## 🔐 인증 & 권한

### API 인증 흐름
```
1. API Key (X-API-KEY) - 애플리케이션 인증
2. Sanctum Token (Bearer) - 사용자 인증
```

### 권한 체계
```
Menu (메뉴)
 ↓ has
Permission (권한)
 ↓ belongs to
Role (역할)
 ↓ belongs to
Department (부서)
 ↓ has
User (사용자)
```

**3-State 시스템:**
- **Inherit** (상속): 상위 권한 따름
- **Allow** (허용): 명시적 허용
- **Deny** (거부): 명시적 거부

---

## 📦 Git 커밋 형식

```bash
# 형식
[type]: 간결한 제목

- 변경 상세 내용 1
- 변경 상세 내용 2

# 타입
feat:     새로운 기능
fix:      버그 수정
refactor: 리팩토링
docs:     문서 변경
style:    코드 포맷팅
test:     테스트 추가
chore:    기타 작업

# 예시
feat: 제품 카테고리 관리 API 구현

- ProductCategoryService 추가
- Swagger 문서화 완료
- PHPUnit 테스트 작성
```

**자세히:** [`claudedocs/SAM/git_conventions.md`](./claudedocs/SAM/git_conventions.md)

---

## 🏗️ 프로젝트 구조

```
SAM/
├── api/              # Laravel 12 REST API (독립)
├── admin/            # Laravel 12 + Filament v3 (독립)
├── react/            # React 19 프론트엔드 (독립)
├── docker/           # Docker 설정
│
├── CLAUDE.md         # 프로젝트 개요
├── CURRENT_WORKS.md  # 현재 작업 현황
├── SAM_QUICK_REFERENCE.md  # 이 파일
│
└── claudedocs/       # 상세 문서
    ├── SAM/          # SAM 프로젝트 문서
    │   ├── api_rules.md
    │   ├── dev_commands.md
    │   ├── quality_checklist.md
    │   ├── git_conventions.md
    │   └── database_schema.md
    │
    └── mes/          # MES/ERP 프로젝트 문서
```

---

## 🌐 환경 정보

| 환경 | 도메인 | 특징 |
|------|--------|------|
| 로컬 | sam.kr | Docker, HMR |
| 개발 | codebridge-x.com | 클라우드, 수동 배포 |
| 운영 | TBD | 설정 중 |

---

## 🔗 더 자세한 정보

| 주제 | 문서 |
|------|------|
| **프로젝트 개요** | [`CLAUDE.md`](./CLAUDE.md) |
| **현재 작업** | [`CURRENT_WORKS.md`](./CURRENT_WORKS.md) |
| **API 규칙** | [`claudedocs/SAM/api_rules.md`](./claudedocs/SAM/api_rules.md) |
| **개발 명령어** | [`claudedocs/SAM/dev_commands.md`](./claudedocs/SAM/dev_commands.md) |
| **품질 체크리스트** | [`claudedocs/SAM/quality_checklist.md`](./claudedocs/SAM/quality_checklist.md) |
| **Git 규칙** | [`claudedocs/SAM/git_conventions.md`](./claudedocs/SAM/git_conventions.md) |
| **DB 스키마** | [`claudedocs/SAM/database_schema.md`](./claudedocs/SAM/database_schema.md) |
| **MES 프로젝트** | [`claudedocs/mes/README.md`](./claudedocs/mes/README.md) |

---

**업데이트**: 2025-11-18