13 KiB
13 KiB
백엔드 코드 패턴 검증 (validate-backend)
백엔드 코드 및 작업계획서 내 PHP 코드 블록이 그누보드7 규정을 준수하는지 검증합니다.
이전 이름:
/validate-code(2026-05-06 부로/validate-backend로 개명).단일 영역 검증 금지: 한 작업 단위에서 백엔드와 프론트가 함께 변경되었다면 본 스킬만 실행하고 검증 완료를 선언하지 않는다.
/validate-frontend도 함께 실행하거나 통합 메타 스킬/validate-branch를 사용한다.
0단계: 검증 대상 유형 판별 (CRITICAL)
⚠️ CRITICAL: 검증 대상이 소스코드인지 작업계획서인지 먼저 판별
판별 기준
| 파일 확장자 | 유형 | 검증 방식 |
|---|---|---|
*.php |
소스코드 | 파일 전체를 PHP 코드로 검증 |
*.md |
작업계획서 | 마크다운 내 PHP 코드 블록 추출 후 검증 |
작업계획서 검증 시 추가 단계
작업계획서(.md) 파일인 경우:
- 코드 블록 추출: 마크다운에서 ```php 코드 블록 추출
- 컨텍스트 파악: 코드 블록 앞뒤 텍스트로 해당 코드의 용도 파악 (Controller, Service, Repository 등)
- 유형별 검증: 파악된 용도에 맞는 규정 적용
⚠️ 작업계획서 검증 시 주의사항:
- 코드 블록이 예시/설명 목적인지, 실제 구현 계획인지 구분
- "예시:", "Example:", "// 예시" 등이 포함된 코드는 참고용으로 처리
- 실제 구현 계획 코드만 엄격하게 검증
1단계: 규정 문서 읽기
다음 규정 문서를 읽어 최신 규칙을 확인합니다:
docs/backend/service-repository.md- Service-Repository 패턴docs/backend/validation.md- FormRequest 검증 규칙docs/backend/enum.md- Enum 사용 규칙docs/backend/controllers.md- 컨트롤러 계층 규칙docs/backend/api-resources.md- API 리소스 규칙docs/backend/exceptions.md- Custom Exception 다국어 처리docs/backend/middleware.md- 미들웨어 등록 규칙docs/backend/routing.md- 라우트 네이밍 및 권한 체크docs/backend/response-helper.md- API 응답 규칙docs/backend/service-provider.md- 서비스 프로바이더 안전성docs/extension/permissions.md- 권한 시스템 (Policy 사용 금지)docs/backend/notification-system.md- BaseNotification 상속 규칙docs/backend/broadcasting.md- Broadcasting 규칙docs/backend/core-config.md- 코어 설정 SSoTdocs/extension/storage-driver.md- StorageInterface 사용 규칙
2단계: 검증 대상 파일 읽기
$ARGUMENTS 경로의 파일을 읽습니다.
경로가 지정되지 않은 경우, 현재 작업 중인 PHP 파일들을 대상으로 합니다:
app/Services/**/*.php- Service 클래스app/Http/Requests/**/*.php- FormRequest 클래스app/Repositories/**/*.php- Repository 클래스app/Http/Controllers/**/*.php- Controller 클래스app/Http/Resources/**/*.php- API Resource 클래스**/Listeners/**/*.php- Listener 클래스
3단계: 규정 기반 자동 검증 (CRITICAL)
⚠️ CRITICAL: 1단계에서 읽은 규정 문서의 모든 규칙을 검증 항목으로 사용합니다.
스킬에 하드코딩된 검증 항목이 아닌, 규정 문서가 Single Source of Truth입니다.
3.1 규정에서 검증 패턴 추출
1단계에서 읽은 모든 규정 문서에서 다음 패턴을 추출합니다:
| 추출 대상 | 검증 유형 |
|---|---|
❌ 또는 잘못된 키워드가 포함된 코드 블록 |
금지 패턴 - 발견 시 에러 |
✅ 또는 올바른 키워드가 포함된 코드 블록 |
필수 패턴 - 누락 시 경고 |
⚠️ 절대 금지, CRITICAL 등 강조된 규칙 |
필수 검증 항목 |
TL;DR 섹션의 핵심 포인트 |
우선 검증 항목 |
3.2 검증 방법
금지 패턴 검증:
# 규정 문서의 ❌ 예시에서 추출한 패턴을 grep으로 검사
grep -rn "[금지 패턴]" [대상 파일/디렉토리]
발견 시: 에러로 보고하고 규정 문서의 해당 섹션 참조 안내
필수 패턴 검증:
- 해당 컨텍스트에서 필수 패턴이 사용되어야 하는 경우, 누락 여부 확인
- 누락 시: 경고로 보고하고 규정 문서의 올바른 예시 안내
3.3 파일 유형별 규정 매핑
검증 대상 파일의 경로에 따라 해당하는 규정 문서를 우선적으로 적용합니다:
| 파일 경로 패턴 | 우선 적용 규정 |
|---|---|
app/Services/** |
service-repository.md |
app/Http/Requests/** |
validation.md |
app/Repositories/** |
service-repository.md |
app/Http/Controllers/** |
controllers.md, routing.md |
app/Http/Resources/** |
api-resources.md |
**/Listeners/** |
hooks.md (extension) |
app/Providers/** |
service-provider.md |
app/Http/Middleware/** |
middleware.md |
app/Exceptions/** |
exceptions.md |
3.4 백엔드 핵심 원칙 검증
백엔드 핵심 원칙 및 빈번 실수 패턴을 검증합니다.
| # | 검증 항목 | 금지 패턴 | 올바른 패턴 |
|---|---|---|---|
| 1 | FormRequest authorize() | 인증/권한 로직 구현 | return true 고정 + permission 미들웨어 체인 |
| 2 | API 리소스 $this->when() | 커스텀 메서드에서 $this->when() |
삼항 연산자 사용 |
| 3 | ResponseHelper 인수 순서 | ResponseHelper::success($data, $message) |
ResponseHelper::success($messageKey, $data) — 메시지 first |
| 4 | 미들웨어 전역 등록 | append() 로 인증 미들웨어 전역 등록 |
appendToGroup('api') 사용 |
| 5 | 로그아웃 구현 | 단일 단계 로그아웃 | 토큰 삭제 → 세션 무효화 → Auth::logout() (3단계) |
| 6 | ServiceProvider DB 접근 | 검증 없이 DB 접근 | .env + 테이블 존재 확인 필수 |
| 7 | exists/unique 규칙 | exists:table,col 문자열 |
Rule::exists(Model::class, 'col') |
| 8 | DB CASCADE 삭제 | onDelete('cascade') 의존 삭제 |
Service에서 명시적 삭제 (훅/파일/로깅 보장) |
| 9 | Storage 직접 호출 | Storage::disk() 직접 호출 |
StorageInterface 사용 필수 |
| 10 | 파사드 사용 | \Log::info(), auth()->user() |
use Facades\Log; Log::info() |
3.5 PHPDoc 검증
규정 문서에서 PHPDoc 관련 규칙도 추출하여 검증합니다:
@param,@return타입 명시 여부- 한국어 설명 포함 여부
@throws명시 (예외 발생 시)
4단계: 테스트 실행 검증
검증 대상 파일에 해당하는 테스트가 있는 경우, 테스트를 실행하여 통과 여부를 확인합니다.
php artisan test --filter=[TestClassName]
5단계: 결과 보고
검증 결과를 다음 형식으로 보고합니다:
## 코드 패턴 검증 결과
### 검증 파일
- [파일 경로]
### [규정 문서명] - [섹션명] 검증 결과
#### 금지 패턴 검사
- ❌ 금지 패턴 발견: [패턴] (파일:라인)
- 규정: [규정 문서명] > [섹션명]
- 수정 방법: [올바른 패턴으로 변경]
- ✅ 금지 패턴 없음
#### 필수 패턴 검사
- ❌ 필수 패턴 누락: [컨텍스트]에서 [패턴] 필요
- 규정: [규정 문서명] > [섹션명]
- ✅ 필수 패턴 준수
### 테스트 실행 결과 (해당되는 경우)
- ✅ 모든 테스트 통과 (X passed)
- ❌ 테스트 실패: [실패 메시지]
6단계: 작업계획서 전용 검증 (마크다운 파일인 경우)
검증 대상이 작업계획서(.md)인 경우, 다음 추가 검증을 수행합니다.
6.1 코드 블록 추출 및 분류
마크다운 파일에서 PHP 코드 블록을 추출하고 용도별로 분류합니다:
| 코드 블록 컨텍스트 | 적용 규정 |
|---|---|
| Controller 관련 | controllers.md, routing.md |
| Service 관련 | service-repository.md |
| Repository 관련 | service-repository.md |
| FormRequest 관련 | validation.md |
| API Resource 관련 | api-resources.md |
| Exception 관련 | exceptions.md |
| Listener/Hook 관련 | hooks.md |
6.2 Controller 코드 블록 검증
// ✅ 올바른 패턴
class ProductController extends AdminBaseController
{
public function __construct(
private readonly ProductServiceInterface $productService
) {}
}
// ❌ 잘못된 패턴 - Repository 직접 주입
class ProductController extends AdminBaseController
{
public function __construct(
private readonly ProductRepository $productRepository // ❌
) {}
}
검증 항목:
- ❌ Repository 직접 주입 (Service를 통해야 함)
- ❌ 컨트롤러 내 검증 로직 (FormRequest 사용 필수)
- ❌ 컨트롤러 내 비즈니스 로직 (Service로 위임 필수)
- ✅ ResponseHelper 사용
6.3 Service 코드 블록 검증
// ✅ 올바른 패턴
class ProductService implements ProductServiceInterface
{
public function __construct(
private readonly ProductRepositoryInterface $productRepository
) {}
public function create(array $data): Product
{
HookManager::doAction('sirsoft-ecommerce.product.before_create', $data);
$data = HookManager::applyFilters('sirsoft-ecommerce.product.filter_create_data', $data);
$result = $this->productRepository->create($data);
HookManager::doAction('sirsoft-ecommerce.product.after_create', $result);
return $result;
}
}
// ❌ 잘못된 패턴 - 검증 로직 포함
public function create(array $data): Product
{
if (empty($data['name'])) { // ❌ FormRequest에서 처리해야 함
throw new ValidationException();
}
}
검증 항목:
- ❌ RepositoryInterface 대신 구체 클래스 타입힌트
- ❌ Service 내 검증 로직
- ✅ 훅 실행 순서: before → filter → action → after
- ✅ 훅 네이밍:
[vendor-module].[entity].[action]_[timing]
6.4 Repository 코드 블록 검증
// ✅ 올바른 패턴
class ProductRepository implements ProductRepositoryInterface
{
public function __construct(
private readonly Product $model
) {}
}
검증 항목:
- ✅ RepositoryInterface 구현
- ❌ 비즈니스 로직 포함 (Service로 이동 필요)
6.5 FormRequest 코드 블록 검증
// ✅ 올바른 패턴
public function rules(): array
{
return [
'name' => ['required', 'string', 'max:255'],
'price' => ['required', 'numeric', 'min:0'],
];
}
public function messages(): array
{
return [
'name.required' => __('validation.custom.product.name.required'),
];
}
검증 항목:
- ✅
__()함수를 사용한 다국어 메시지 - ❌ 하드코딩된 한국어 메시지
6.6 API Response 코드 블록 검증
// ✅ 올바른 패턴
return ResponseHelper::success(
data: new ProductResource($product),
message: __('messages.product.created')
);
// ❌ 잘못된 패턴
return response()->json(['data' => $product]); // ResponseHelper 미사용
6.7 작업계획서 검증 결과 보고 형식
## 작업계획서 백엔드 코드 검증 결과
### 검증 파일
- [마크다운 파일 경로]
### 코드 블록 요약
- Controller 코드 블록: X개
- Service 코드 블록: Y개
- Repository 코드 블록: Z개
- FormRequest 코드 블록: W개
- 총 검증 대상: N개
### Controller 검증
- ✅ Service 주입 패턴 준수
- ❌ Repository 직접 주입: [위치]
- ✅ ResponseHelper 사용
### Service 검증
- ✅ RepositoryInterface 사용
- ❌ 구체 클래스 타입힌트: [위치]
- ✅ 훅 실행 순서 준수
- ❌ Service 내 검증 로직: [위치]
### Repository 검증
- ✅ Interface 구현
- ❌ 비즈니스 로직 포함: [위치]
### FormRequest 검증
- ✅ 다국어 메시지 사용
- ❌ 하드코딩된 메시지: [위치]
### API Response 검증
- ✅ ResponseHelper 사용
- ❌ 직접 response() 사용: [위치]
핵심 원칙
⚠️ CRITICAL:
- 규정 문서가 Single Source of Truth - 스킬에 검증 항목 하드코딩 금지
- 규정 문서의 ❌/✅ 예시를 자동으로 검증 패턴으로 사용
- 규정이 변경되면 검증도 자동으로 변경됨
- 파일 유형에 따라 해당 규정 문서 우선 적용
- 작업계획서(.md) 검증 시 코드 블록 추출 후 동일한 규정 적용