hskwon
88644c88ab
폴더 재구성: - reference/ → standards/, architecture/, quickstart/로 분리 - principles/ → architecture/로 통합 - specs/security-policy.md → architecture/로 이동 새 구조: - standards/: 개발 표준 (어떻게 코드를 작성할 것인가) - architecture/: 아키텍처 & 설계 원칙 (왜 이렇게 설계하는가) - rules/: 비즈니스 규칙 (무엇이 유효한 데이터인가) - specs/: 기술 스펙 (무엇을 구현할 것인가) - guides/: 구현 가이드 (어떻게 구현할 것인가) - quickstart/: 빠른 시작 INDEX.md 개선: - 작업별 필수 문서 테이블 추가 - 폴더별 문서 목록 및 필수 확인 시점 명시 - 폴더 선택 기준 가이드 추가
3.6 KiB
3.6 KiB
코드 품질 체크리스트
업데이트: 2025-11-10
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 포맷팅
✓ 테스트 통과
✓ 감사 로그
✓ 문서 업데이트