v7.0.0-beta.1 release

This commit is contained in:
HeuJung committed 2026-04-01 10:30:52 +09:00
commit 6595fd0eb5
3967 files changed
+1875383

No files matched your search

@@ -0,0 +1,42 @@
<?php
namespace App\Http\Controllers\Api\Base;
/**
* 관리자용 베이스 컨트롤러
*
* 모든 관리자 컨트롤러가 상속받아야 하는 기본 클래스입니다.
* 관리자 권한 검증, 관리자 전용 기능을 제공합니다.
*/
abstract class AdminBaseController extends BaseApiController
{
public function __construct()
{
// 관리자 인증 및 권한 체크 미들웨어 적용
$this->middleware(['auth:sanctum', 'admin'])->except(['login']);
}
/**
* 현재 관리자 사용자를 반환합니다.
*
* @return \App\Models\User|null
*/
protected function getCurrentAdmin()
{
return $this->getCurrentUser();
}
/**
* 관리자 권한을 확인합니다.
*
* @return bool
*/
protected function isAdmin(): bool
{
$user = $this->getCurrentAdmin();
// TODO: 실제 관리자 권한 체크 로직 구현
return $user !== null;
}
}
@@ -0,0 +1,99 @@
<?php
namespace App\Http\Controllers\Api\Base;
use Illuminate\Support\Facades\Log;
/**
* 인증된 사용자용 베이스 컨트롤러
*
* 인증이 필요한 API 컨트롤러가 상속받아야 하는 기본 클래스입니다.
* 사용자 인증, 권한 체크, 리소스 소유권 확인 등의 기능을 제공합니다.
*/
abstract class AuthBaseController extends BaseApiController
{
public function __construct()
{
// 사용자 인증 미들웨어 적용
$this->middleware('auth:sanctum');
}
/**
* 사용자 소유권을 확인합니다.
*
* @param int $userId 확인할 사용자 ID
* @return bool
*/
protected function isOwner(int $userId): bool
{
return $this->getCurrentUser()?->id === $userId;
}
/**
* 사용자가 특정 리소스에 접근할 수 있는지 확인합니다.
*
* @param mixed $resource 접근하려는 리소스
* @return bool
*/
protected function canAccessResource($resource): bool
{
// 기본적으로 자신의 리소스만 접근 가능
if (method_exists($resource, 'user_id')) {
return $this->getCurrentUser()?->id === $resource->user_id;
}
return true;
}
/**
* 사용자 활동을 기록합니다.
*
* @param string $action 수행한 작업
* @param array $data 관련 데이터
* @return void
*/
protected function logUserActivity(string $action, array $data = []): void
{
// TODO: 사용자 활동 로그 시스템 구현
Log::info("User Activity: {$action}", [
'user_id' => $this->getCurrentUser()?->uuid,
'data' => $data,
'timestamp' => now()
]);
}
/**
* 리소스 소유권을 확인하고, 소유자가 아니면 Forbidden 응답을 반환합니다.
*
* @param mixed $resource 확인할 리소스
* @param string $messageKey 오류 메시지 키
* @return \Illuminate\Http\JsonResponse|null 소유자이면 null, 아니면 Forbidden 응답
*/
protected function checkOwnership($resource, string $messageKey = 'common.forbidden')
{
if (!$this->canAccessResource($resource)) {
return $this->forbidden($messageKey);
}
return null;
}
/**
* API 사용량을 기록합니다.
*
* @param string $endpoint 엔드포인트
* @param array $data 관련 데이터
* @return void
*/
protected function logApiUsage(string $endpoint, array $data = []): void
{
// TODO: API 사용량 통계 시스템 구현
Log::info("Auth API Usage: {$endpoint}", [
'user_id' => $this->getCurrentUser()?->uuid,
'ip' => request()->ip(),
'user_agent' => request()->userAgent(),
'data' => $data,
'timestamp' => now(),
]);
}
}
@@ -0,0 +1,264 @@
<?php
namespace App\Http\Controllers\Api\Base;
use App\Helpers\ResponseHelper;
use App\Http\Controllers\Controller;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\Auth;
use Symfony\Component\HttpFoundation\BinaryFileResponse;
/**
* API 컨트롤러의 최상위 베이스 클래스
*
* 모든 API 컨트롤러가 공통으로 사용하는 기능을 제공합니다.
* Admin, Auth, Public 컨트롤러는 이 클래스를 상속받습니다.
*/
abstract class BaseApiController extends Controller
{
/**
* 성공 응답을 생성합니다.
*
* @param string $messageKey 메시지 키
* @param mixed $data 응답 데이터
* @param int $statusCode HTTP 상태 코드
* @param array $messageParams 메시지 매개변수
* @return \Illuminate\Http\JsonResponse
*/
protected function success(
string $messageKey = 'common.success',
mixed $data = null,
int $statusCode = 200,
array $messageParams = []
) {
return ResponseHelper::success($messageKey, $data, $statusCode, $messageParams, 'core');
}
/**
* 실패 응답을 생성합니다.
*
* @param string $messageKey 메시지 키
* @param int $statusCode HTTP 상태 코드
* @param mixed $errors 오류 정보
* @param array $messageParams 메시지 매개변수
* @return \Illuminate\Http\JsonResponse
*/
protected function error(
string $messageKey = 'common.failed',
int $statusCode = 400,
mixed $errors = null,
array $messageParams = []
) {
return ResponseHelper::error($messageKey, $statusCode, $errors, $messageParams, 'core');
}
/**
* 리소스와 함께 성공 응답을 생성합니다.
*
* @param string $messageKey 메시지 키
* @param mixed $resource JSON 리소스
* @param int $statusCode HTTP 상태 코드
* @param array $messageParams 메시지 매개변수
* @return \Illuminate\Http\JsonResponse
*/
protected function successWithResource(
string $messageKey = 'common.success',
mixed $resource = null,
int $statusCode = 200,
array $messageParams = []
) {
return ResponseHelper::successWithResource($messageKey, $resource, $statusCode, $messageParams, 'core');
}
/**
* 현재 인증된 사용자를 반환합니다.
*
* @return \App\Models\User|null
*/
protected function getCurrentUser()
{
return Auth::user();
}
/**
* Not Found 응답을 생성합니다.
*
* @param string $messageKey 메시지 키
* @param array $messageParams 메시지 매개변수
* @return \Illuminate\Http\JsonResponse
*/
protected function notFound(
string $messageKey = 'common.not_found',
array $messageParams = []
) {
return $this->error($messageKey, 404, null, $messageParams);
}
/**
* Unauthorized 응답을 생성합니다.
*
* @param string $messageKey 메시지 키
* @param array $messageParams 메시지 매개변수
* @return \Illuminate\Http\JsonResponse
*/
protected function unauthorized(
string $messageKey = 'common.unauthorized',
array $messageParams = []
) {
return $this->error($messageKey, 401, null, $messageParams);
}
/**
* Forbidden 응답을 생성합니다.
*
* @param string $messageKey 메시지 키
* @param array $messageParams 메시지 매개변수
* @return \Illuminate\Http\JsonResponse
*/
protected function forbidden(
string $messageKey = 'common.forbidden',
array $messageParams = []
) {
return $this->error($messageKey, 403, null, $messageParams);
}
/**
* Validation Error 응답을 생성합니다.
*
* @param mixed $errors 검증 오류
* @param string $messageKey 메시지 키
* @param array $messageParams 메시지 매개변수
* @return \Illuminate\Http\JsonResponse
*/
protected function validationError(
mixed $errors,
string $messageKey = 'common.validation_failed',
array $messageParams = []
) {
return $this->error($messageKey, 422, $errors, $messageParams);
}
/**
* 파일 응답을 반환합니다 (ETag 및 캐싱 헤더 포함).
*
* @param string $filePath 파일 경로
* @param string $mimeType MIME 타입
* @param int $maxAge 캐시 유지 시간 (초, 기본: 1년)
*/
protected function fileResponse(string $filePath, string $mimeType, int $maxAge = 31536000): BinaryFileResponse|Response
{
// ETag 생성 (파일 수정 시간 + 파일 크기 기반)
$etag = md5(filemtime($filePath).filesize($filePath));
// If-None-Match 헤더 확인 (ETag 비교)
if (request()->header('If-None-Match') === $etag) {
return response('', 304)->header('ETag', $etag); // 304 Not Modified
}
// 환경별 캐싱 정책
$cacheControl = app()->environment('production')
? "public, max-age={$maxAge}, immutable" // 프로덕션: immutable 추가
: 'no-cache'; // 개발: 캐싱 비활성화
$response = response()->file($filePath, [
'Content-Type' => $mimeType,
'Expires' => gmdate('D, d M Y H:i:s', time() + $maxAge).' GMT',
'ETag' => $etag,
]);
// Cache-Control 헤더를 수동으로 설정 (기본 헤더 덮어쓰기)
$response->headers->set('Cache-Control', $cacheControl);
return $response;
}
/**
* JSON 응답을 반환합니다 (캐싱 헤더 포함).
*
* @param mixed $data JSON으로 변환할 데이터
* @param int $maxAge 캐시 유지 시간 (초, 기본: 1시간)
* @param int $status HTTP 상태 코드
* @return JsonResponse JSON 응답
*/
protected function cachedJsonResponse(mixed $data, int $maxAge = 3600, int $status = 200): JsonResponse
{
return response()->json($data, $status, [
'Cache-Control' => "public, max-age={$maxAge}",
]);
}
/**
* ETag를 생성합니다.
*
* @param mixed $data 해시할 데이터
* @return string ETag 값 (따옴표 포함)
*/
protected function generateETag(mixed $data): string
{
$content = is_string($data) ? $data : json_encode($data);
return '"' . md5($content) . '"';
}
/**
* 클라이언트 캐시가 유효한지 확인합니다.
*
* @param string $etag 현재 ETag 값
* @return bool 캐시가 유효하면 true
*/
protected function isNotModified(string $etag): bool
{
$clientEtag = request()->header('If-None-Match');
return $clientEtag !== null && $clientEtag === $etag;
}
/**
* 304 Not Modified 응답을 반환합니다.
*
* @param string $etag ETag 값
* @param int $maxAge 캐시 TTL (초)
* @return Response 304 응답
*/
protected function notModifiedResponse(string $etag, int $maxAge = 3600): Response
{
return response('', 304)
->header('ETag', $etag)
->header('Cache-Control', "public, max-age={$maxAge}");
}
/**
* 캐시 헤더와 함께 성공 응답을 반환합니다.
*
* 클라이언트의 ETag가 일치하면 304 Not Modified를 반환합니다.
*
* @param string $messageKey 메시지 키
* @param mixed $data 응답 데이터
* @param int $maxAge 캐시 TTL (초, 기본: 1시간)
* @param array $messageParams 메시지 매개변수
* @return JsonResponse|Response JSON 응답 또는 304 응답
*/
protected function successWithCache(
string $messageKey = 'common.success',
mixed $data = null,
int $maxAge = 3600,
array $messageParams = []
): JsonResponse|Response {
$etag = $this->generateETag($data);
// 304 Not Modified 처리
if ($this->isNotModified($etag)) {
return $this->notModifiedResponse($etag, $maxAge);
}
return response()->json([
'success' => true,
'message' => __($messageKey, $messageParams),
'data' => $data,
])
->header('ETag', $etag)
->header('Cache-Control', "public, max-age={$maxAge}")
->header('Vary', 'Accept-Encoding, Accept-Language');
}
}
@@ -0,0 +1,68 @@
<?php
namespace App\Http\Controllers\Api\Base;
use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\Log;
use Symfony\Component\HttpFoundation\BinaryFileResponse;
/**
* 공개 API용 베이스 컨트롤러
*
* 인증이 필요하지 않은 공개 API 컨트롤러가 상속받아야 하는 기본 클래스입니다.
* 캐싱, 속도 제한, API 사용량 추적 등의 기능을 제공합니다.
*/
abstract class PublicBaseController extends BaseApiController
{
public function __construct()
{
// 공개 API는 속도 제한 없음 (무제한 접근 허용)
}
/**
* 캐시된 응답을 반환하거나 새로 생성합니다.
*
* @param string $key 캐시 키
* @param callable $callback 데이터 생성 콜백
* @param int $ttl 캐시 유지 시간 (초)
* @return mixed
*/
protected function cached(string $key, callable $callback, int $ttl = 3600)
{
return cache()->remember($key, $ttl, $callback);
}
/**
* API 사용량을 기록합니다.
*
* @param string $endpoint 엔드포인트
* @param array $data 관련 데이터
* @return void
*/
protected function logApiUsage(string $endpoint, array $data = []): void
{
// TODO: API 사용량 통계 시스템 구현
Log::info("Public API Usage: {$endpoint}", [
'ip' => request()->ip(),
'user_agent' => request()->userAgent(),
'data' => $data,
'timestamp' => now()
]);
}
/**
* 클라이언트 정보를 가져옵니다.
*
* @return array
*/
protected function getClientInfo(): array
{
return [
'ip' => request()->ip(),
'user_agent' => request()->userAgent(),
'referer' => request()->header('referer'),
'timestamp' => now()
];
}
}