sam-docs/dev/quickstart/quick-start.md

SAM 개발 빠른 참조

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

---

🚀 개발 명령어

# 전체 서비스 시작
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)

자세히: docs/quickstart/dev-commands.md

---

📝 API 개발 3대 원칙

1️⃣ Service-First

// ✅ 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)

// ✅ Good - 모든 모델에 적용
class Product extends Model {
    use BelongsToTenant, SoftDeletes, ModelTrait;
}

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

3️⃣ FormRequest 검증

// ✅ 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([...]);
}

자세히: docs/standards/api-rules.md

---

✅ 커밋 전 5분 체크리스트

# 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 타입 사용

자세히: docs/standards/quality-checklist.md

---

🗄️ 데이터베이스 규칙

필수 컬럼

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 커밋 형식

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

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

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

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

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

자세히: docs/standards/git-conventions.md

---

🏗️ 프로젝트 구조

SAM/
├── api/              # Laravel 12 REST API (독립)
├── mng/              # Laravel 12 + Blade/Tailwind (독립)
├── react/            # Next.js 15 프론트엔드 (독립)
├── docs/             # 기술 문서
├── design/           # 디자인 시스템 (Storybook)
├── planning/         # 기획 문서
├── sales/            # 영업자 사이트 (추후)
├── docker/           # Docker 설정
│
├── CLAUDE.md         # 프로젝트 개요
├── CURRENT_WORKS.md  # 현재 작업 현황
│
└── docs/             # 상세 문서
    ├── system/       # 시스템 현황 (아키텍처, DB, 인프라)
    ├── standards/    # 개발 표준
    ├── quickstart/   # 빠른 시작 가이드
    └── mes/          # MES/ERP 프로젝트 문서

---

🌐 환경 정보

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

---

🔗 더 자세한 정보

주제	문서
프로젝트 개요	CLAUDE.md
현재 작업	CURRENT_WORKS.md
API 규칙	docs/standards/api-rules.md
개발 명령어	docs/quickstart/dev-commands.md
품질 체크리스트	docs/standards/quality-checklist.md
Git 규칙	docs/standards/git-conventions.md
DB 스키마	docs/system/database/README.md
MES 프로젝트	docs/projects/mes/README.md

---

업데이트: 2025-12-26