sam-docs/standards/quality-checklist.md

# 코드 품질 체크리스트

**업데이트**: 2025-12-26

---

## SAM API 개발 규칙 준수

```
□ Service-First 아키텍처
  - 비즈니스 로직은 Service 클래스에 작성
  - Controller는 DI + ApiResponse::handle()만 사용

□ Multi-tenancy
  - BelongsToTenant global scope 적용
  - ModelTrait 사용 (is_active, date handling)
  - tenant_id 컬럼 및 필터링 확인

□ Soft Delete
  - SoftDeletes 트레잇 적용
  - deleted_at, deleted_by 컬럼

□ Audit 컬럼
  - created_by, updated_by, deleted_by
  - COMMENT 추가 필수
```

---

## Validation & i18n

```
□ FormRequest 검증 사용
  - 직접 validate() 호출 금지
  - PaginateRequest, BomItemsRequest 등 공통 Request 재사용

□ i18n 메시지 키 사용
  - __('message.xxx') 형식
  - __('error.xxx') 형식
  - 직접 문자열 사용 금지
```

---

## Swagger 문서화

```
□ Swagger 파일 위치 확인
  - app/Swagger/v1/{Resource}Api.php

□ Controller Clean
  - Controller에 Swagger 주석 없음
  - 비즈니스 로직만 포함

□ 필수 요소 포함
  - Resource 태그 적용
  - ApiKeyAuth + BearerAuth security
  - 스키마 정의 (Model, Pagination, CreateRequest, UpdateRequest)
  - 예시 값 제공

□ 중복 방지
  - 공통 스키마 재사용
  - nullable/oneOf 정확히 구분

□ 재생성 확인
  - php artisan l5-swagger:generate 실행
  - Swagger UI 접근 테스트
```

---

## 데이터베이스

```
□ 마이그레이션 파일 작성
  - 명확한 파일명 (YYYY_MM_DD_HHMMSS_action_table.php)
  - up/down 메서드 모두 구현
  - 롤백 테스트 완료

□ 인덱스 최적화
  - tenant_id 인덱스
  - 검색/정렬에 사용되는 컬럼 인덱스
  - 복합 인덱스 고려

□ FK 제약조건
  - 개발 환경: 제약조건 생성
  - 운영 환경: 최소화 또는 제거
```

---

## 코드 품질

```
□ 코드 포맷팅
  - ./vendor/bin/pint 실행
  - PSR-12 준수 확인

□ 네이밍
  - 명확하고 일관된 변수/메서드명
  - camelCase (PHP), snake_case (DB)

□ 주석
  - 복잡한 로직에 주석 추가
  - PHPDoc 작성 (@param, @return, @throws)

□ 에러 처리
  - 예외 던지기 (Exception)
  - 글로벌 핸들러에서 JSON 변환
```

---

## 테스트

```
□ 테스트 케이스 작성
  - Feature Test (API 엔드포인트)
  - Unit Test (Service 메서드)

□ 로컬 테스트 실행
  - php artisan test
  - 모든 테스트 통과 확인

□ Swagger UI 테스트
  - http://api.sam.kr/api-docs/index.html
  - 실제 API 호출 테스트
```

---

## 감사 로그

```
□ 감사 로그 고려
  - 중요한 작업 (created, updated, deleted)
  - before/after 데이터 저장
  - 실패 허용 (비즈니스 로직 차단 금지)
```

---

## 환경 확인

```
□ Docker 서비스 실행 확인
  - composer dev 또는 개별 서비스

□ 마이그레이션 상태 확인
  - php artisan migrate:status
  - 미실행 마이그레이션 확인

□ Git 상태 확인
  - git status
  - 불필요한 파일 제외
```

---

## 문서 업데이트

```
□ CURRENT_WORKS.md 업데이트
  - 진행 중인 작업 상태
  - 완료된 작업 기록
  - 히스토리 제거 (현재 상태만)

□ API 변경사항 문서화
  - 엔드포인트 추가/변경/삭제
  - 스키마 변경
```

---

## 최종 체크

```
□ 모든 변경 사항 커밋 준비
□ 커밋 메시지 작성 (Git 컨벤션 준수)
□ 테스트 통과
□ 문서 최신화
□ 코드 리뷰 준비
```

---

## 빠른 체크 (요약)

```
✓ Service-First
✓ BelongsToTenant
✓ SoftDeletes
✓ FormRequest
✓ i18n 키
✓ Swagger 완성도
✓ Pint 포맷팅
✓ 테스트 통과
✓ 감사 로그
✓ 문서 업데이트
```