Files
Gnuboard7/app/Repositories/MenuRepository.php
T
HeuJung b10e89bef0 fix(core,board,ecommerce,page,gdpr,ckeditor5,kginicis,admin_basic,basic): 목록 조회·검증 계층 정비 및 감사 지적 전건 처리
목록 조회 성능 축(깊은 OFFSET·정렬·색인)과 그 검증 계층에서 계획서 전수검수와 3회에 걸친
감사가 지적한 항목을 처리했다. 세부 경위는 의 각 회차 문서에 있다.

검증 계층 — 컨트롤러가 base Request 를 직접 주입받던 확장 13곳을 전용 FormRequest 로 옮겼다.
옮기면서 기존 동작 계약은 그대로 두었다: 상한 초과 limit 을 거부하지 않고 상한까지 반환하던
공개 API, per_page 를 범위로 조정하던 관리자 목록, 미지원 period 를 year 로 해석하던 인기글
목록 모두 종전과 같은 응답을 낸다. 상한/폴백을 rules 로 승격시키면 200 이던 응답이 422 가
되어 기존 링크가 깨지므로, 규칙은 타입만 닫고 클램프·폴백은 접근자가 맡는다. period 는
접근자가 닫힌 집합만 반환해 캐시 키 공간도 함께 닫힌다.

ckeditor5 이미지 업로드만 ResponseHelper 봉투를 쓰지 않는다. 응답을 파싱하는 주체가 CDN 으로
로드되는 상위 CKEditor5 43.3.1 의 SimpleUploadAdapter 라 규약을 바꿀 수 없어, 각 응답 지점에
사유를 명시한 면제를 부착하고 근거를 API 문서에 남겼다.

하네스 — 룰 5개의 대상 경로 패턴이 매처와 맞지 않아 번들 확장 컨트롤러가 검사 대상에서
통째로 빠져 있었다. 패턴을 고치자 확장 위반 17건이 드러나 전건 처리했다. severity 오타가
요약 집계 양쪽에 안 잡혀 "0 error" 로 보고되던 문제도 런너 사전 검증으로 막았다.

정렬 게이트 대조 하네스는 관계 정렬 변형만 쓰는 저장소를 탐지하지 못한 채 통과시키고 있었다.
탐지·제외·인자 파싱을 함께 고치고 단위 테스트를 신설했다.
2026-08-02 15:29:29 +09:00

567 lines
20 KiB
PHP

<?php
namespace App\Repositories;
use App\Contracts\Repositories\MenuRepositoryInterface;
use App\Enums\ExtensionOwnerType;
use App\Helpers\PermissionHelper;
use App\Models\Menu;
use App\Models\Module;
use App\Models\Plugin;
use App\Models\User;
use App\Repositories\Concerns\ResolvesSortSpec;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Support\Facades\DB;
class MenuRepository implements MenuRepositoryInterface
{
use ResolvesSortSpec;
/** 허용 정렬 컬럼 (MenuListRequest 와 동일 집합) */
private const SORTABLE_COLUMNS = ['created_at', 'name', 'slug', 'order'];
/**
* 다국어 JSON 컬럼 목록 (검색·정렬 시 로케일 경로로 풀어야 하는 컬럼)
*
* @var array<int, string>
*/
private const TRANSLATABLE_COLUMNS = ['name'];
/**
* 모든 메뉴를 조회합니다.
*
* @return Collection 메뉴 컬렉션 (관계 데이터 포함)
*/
public function getAll(): Collection
{
return Menu::with(['creator', 'parent', 'children'])
->orderBy('order')
->get();
}
/**
* 최상위 메뉴들을 조회합니다.
*
* @return Collection 최상위 메뉴 컬렉션 (활성화된 것만)
*/
public function getTopLevelMenus(): Collection
{
return Menu::topLevel()
->active()
->with(['creator', 'activeChildren'])
->get();
}
/**
* 관리용 최상위 메뉴 목록을 조회합니다. (비활성 확장 메뉴 제외)
*
* @param array $activeModuleIdentifiers 활성 모듈 식별자 목록
* @param array $activePluginIdentifiers 활성 플러그인 식별자 목록
* @param User|null $user 접근 권한 판정 대상 사용자 (null 이면 역할 필터 미적용)
* @return Collection 최상위 메뉴 컬렉션 (자식 메뉴 포함)
*/
public function getTopLevelMenusForManagement(array $activeModuleIdentifiers = [], array $activePluginIdentifiers = [], ?User $user = null): Collection
{
$extensionFilter = function ($query) use ($activeModuleIdentifiers, $activePluginIdentifiers) {
// 코어 메뉴 또는 사용자 생성 메뉴
$query->whereNull('extension_type')
->orWhere('extension_type', ExtensionOwnerType::Core)
// 활성화된 모듈의 메뉴
->orWhere(function ($q) use ($activeModuleIdentifiers) {
$q->where('extension_type', ExtensionOwnerType::Module)
->whereIn('extension_identifier', $activeModuleIdentifiers);
})
// 활성화된 플러그인의 메뉴
->orWhere(function ($q) use ($activePluginIdentifiers) {
$q->where('extension_type', ExtensionOwnerType::Plugin)
->whereIn('extension_identifier', $activePluginIdentifiers);
});
};
$query = Menu::whereNull('parent_id')
->where($extensionFilter);
// 권한 스코프 필터링
PermissionHelper::applyPermissionScope($query, 'core.menus.read');
// 사용자 역할 기반 접근 제어
if ($user) {
$query->accessibleBy($user);
}
return $query->with(['creator', 'roles', 'children' => function ($query) use ($extensionFilter, $user) {
$query->where($extensionFilter);
if ($user) {
$query->accessibleBy($user);
}
$query->with('roles')
->orderBy('order');
}])
->orderBy('order')
->get();
}
/**
* 활성화된 메뉴들만 조회합니다.
*
* @return Collection 활성화된 메뉴 컬렉션
*/
public function getActiveMenus(): Collection
{
return Menu::active()
->with(['creator', 'parent', 'activeChildren'])
->orderBy('order')
->get();
}
/**
* ID로 메뉴를 찾습니다.
*
* @param int $id 메뉴 ID
* @return Menu|null 찾은 메뉴 모델 또는 null
*/
public function findById(int $id): ?Menu
{
return Menu::with(['creator', 'parent', 'children'])->find($id);
}
/**
* 슬러그로 메뉴를 찾습니다.
*
* @param string $slug 메뉴 슬러그
* @return Menu|null 찾은 메뉴 모델 또는 null
*/
public function findBySlug(string $slug): ?Menu
{
return Menu::where('slug', $slug)->first();
}
/**
* 새로운 메뉴를 생성합니다.
*
* @param array $data 메뉴 생성 데이터
* @return Menu 생성된 메뉴 모델
*/
public function create(array $data): Menu
{
return Menu::create($data);
}
/**
* 기존 메뉴를 업데이트합니다.
*
* @param Menu $menu 업데이트할 메뉴 모델
* @param array $data 업데이트할 데이터
* @return bool 업데이트 성공 여부
*/
public function update(Menu $menu, array $data): bool
{
return $menu->update($data);
}
/**
* 메뉴를 삭제합니다.
*
* @param Menu $menu 삭제할 메뉴 모델
* @return bool 삭제 성공 여부
*/
public function delete(Menu $menu): bool
{
return $menu->delete();
}
/**
* 메뉴의 순서를 업데이트합니다.
*
* @param array $menuOrders 메뉴 ID와 순서 매핑 배열
* @return bool 업데이트 성공 여부
*/
public function updateOrder(array $menuOrders): bool
{
try {
foreach ($menuOrders as $order => $menuId) {
Menu::where('id', $menuId)->update(['order' => $order + 1]);
}
return true;
} catch (\Exception $e) {
return false;
}
}
/**
* 계층 구조를 고려한 메뉴 순서를 업데이트합니다.
*
* @param array $orderData 계층 구조 순서 데이터
* @return bool 업데이트 성공 여부
*/
public function updateOrderWithHierarchy(array $orderData): bool
{
try {
DB::beginTransaction();
// ① depth 이동 처리 (parent_id 변경)
if (isset($orderData['moved_items'])) {
foreach ($orderData['moved_items'] as $movedItem) {
Menu::where('id', $movedItem['id'])
->update(['parent_id' => $movedItem['new_parent_id']]);
}
}
// ② 부모 메뉴 순서 업데이트
if (isset($orderData['parent_menus'])) {
foreach ($orderData['parent_menus'] as $parentMenu) {
Menu::where('id', $parentMenu['id'])
->update(['order' => $parentMenu['order']]);
}
}
// ③ 자식 메뉴 순서 업데이트
if (isset($orderData['child_menus'])) {
foreach ($orderData['child_menus'] as $parentId => $children) {
foreach ($children as $childMenu) {
Menu::where('id', $childMenu['id'])
->where('parent_id', $parentId)
->update(['order' => $childMenu['order']]);
}
}
}
DB::commit();
return true;
} catch (\Exception $e) {
DB::rollBack();
return false;
}
}
/**
* 특정 확장에 속한 메뉴들을 조회합니다.
*
* @param ExtensionOwnerType $type 확장 타입
* @param string $identifier 확장 식별자
* @return Collection 확장에 속한 메뉴 컬렉션
*/
public function getMenusByExtension(ExtensionOwnerType $type, string $identifier): Collection
{
return Menu::where('extension_type', $type)
->where('extension_identifier', $identifier)
->with(['creator', 'parent', 'children'])
->orderBy('order')
->get();
}
/**
* 부모 메뉴의 자식 메뉴들을 조회합니다.
*
* @param int $parentId 부모 메뉴 ID
* @return Collection 자식 메뉴 컬렉션
*/
public function getChildrenByParent(int $parentId): Collection
{
return Menu::where('parent_id', $parentId)
->with(['creator', 'children'])
->orderBy('order')
->get();
}
/**
* 네비게이션용 활성화된 메뉴들을 자식 메뉴와 함께 조회합니다.
*
* @return Collection 활성화된 메뉴 컬렉션 (자식 메뉴 포함)
*/
public function getActiveMenusWithChildren(): Collection
{
$activeExtensionFilter = function ($query) {
// 코어 메뉴 또는 사용자 생성 메뉴
$query->whereNull('extension_type')
->orWhere('extension_type', ExtensionOwnerType::Core)
// 활성화된 모듈의 메뉴
->orWhere(function ($q) {
$q->where('extension_type', ExtensionOwnerType::Module)
->whereExists(function ($subQuery) {
$subQuery->select(DB::raw(1))
->from((new Module)->getTable())
->whereColumn('modules.identifier', 'menus.extension_identifier')
->where('modules.status', 'active');
});
})
// 활성화된 플러그인의 메뉴
->orWhere(function ($q) {
$q->where('extension_type', ExtensionOwnerType::Plugin)
->whereExists(function ($subQuery) {
$subQuery->select(DB::raw(1))
->from((new Plugin)->getTable())
->whereColumn('plugins.identifier', 'menus.extension_identifier')
->where('plugins.status', 'active');
});
});
};
return Menu::active()
->where($activeExtensionFilter)
->with(['activeChildren' => function ($query) use ($activeExtensionFilter) {
$query->where($activeExtensionFilter)
->orderBy('order');
}])
->whereNull('parent_id') // 최상위 메뉴만
->orderBy('order')
->get();
}
/**
* 사용자가 접근 가능한 네비게이션용 메뉴들을 조회합니다.
*
* @param User $user 접근 권한을 확인할 사용자
* @return Collection 사용자가 접근 가능한 메뉴 컬렉션
*/
public function getAccessibleNavigationMenus(User $user): Collection
{
return Menu::active()
->accessibleBy($user)
->with(['activeChildren' => function ($query) use ($user) {
$query->accessibleBy($user)->orderBy('order');
}])
->whereNull('parent_id') // 최상위 메뉴만
->orderBy('order')
->get();
}
/**
* slug와 확장 정보로 메뉴를 찾습니다.
*
* @param string $slug 메뉴 슬러그
* @param ExtensionOwnerType $extensionType 확장 타입
* @param string $extensionIdentifier 확장 식별자
* @return Menu|null 찾은 메뉴 모델 또는 null
*/
public function findBySlugAndExtension(string $slug, ExtensionOwnerType $extensionType, string $extensionIdentifier): ?Menu
{
return Menu::where('slug', $slug)
->where('extension_type', $extensionType)
->where('extension_identifier', $extensionIdentifier)
->first();
}
/**
* 메뉴를 생성하거나 업데이트합니다.
*
* @param array $attributes 조회 조건
* @param array $values 생성/업데이트할 데이터
* @return Menu 생성 또는 업데이트된 메뉴 모델
*/
public function updateOrCreate(array $attributes, array $values): Menu
{
return Menu::updateOrCreate($attributes, $values);
}
/**
* 특정 확장의 모든 메뉴를 삭제합니다.
*
* @param ExtensionOwnerType $type 확장 타입
* @param string $identifier 확장 식별자
* @return int 삭제된 레코드 수
*/
public function deleteByExtension(ExtensionOwnerType $type, string $identifier): int
{
return Menu::where('extension_type', $type)
->where('extension_identifier', $identifier)
->delete();
}
/**
* 같은 부모 내에서 최대 순서 값을 조회합니다.
*
* @param int|null $parentId 부모 메뉴 ID (null이면 최상위)
* @return int 최대 순서 값 (없으면 0)
*/
public function getMaxOrder(?int $parentId = null): int
{
return (int) Menu::where('parent_id', $parentId)->max('order');
}
/**
* 필터 조건이 적용된 최상위 메뉴 목록을 조회합니다.
*
* @param array $filters 필터 조건 배열 (sort_by/sort_order/검색 필드)
* @param array $activeModuleIdentifiers 활성 모듈 식별자 목록
* @param array $activePluginIdentifiers 활성 플러그인 식별자 목록
* @param User|null $user 접근 권한 판정 대상 사용자 (null 이면 역할 필터 미적용)
* @return Collection 최상위 메뉴 컬렉션 (자식 메뉴 포함)
*/
public function getFilteredTopLevelMenus(array $filters, array $activeModuleIdentifiers = [], array $activePluginIdentifiers = [], ?User $user = null): Collection
{
$extensionFilter = function ($query) use ($activeModuleIdentifiers, $activePluginIdentifiers) {
$query->whereNull('extension_type')
->orWhere('extension_type', ExtensionOwnerType::Core)
->orWhere(function ($q) use ($activeModuleIdentifiers) {
$q->where('extension_type', ExtensionOwnerType::Module)
->whereIn('extension_identifier', $activeModuleIdentifiers);
})
->orWhere(function ($q) use ($activePluginIdentifiers) {
$q->where('extension_type', ExtensionOwnerType::Plugin)
->whereIn('extension_identifier', $activePluginIdentifiers);
});
};
$query = Menu::whereNull('parent_id')
->where($extensionFilter);
// 권한 스코프 필터링
PermissionHelper::applyPermissionScope($query, 'core.menus.read');
// 사용자 역할 기반 접근 제어
if ($user) {
$query->accessibleBy($user);
}
// 활성화 상태 필터
if (isset($filters['is_active'])) {
$query->where('is_active', $filters['is_active']);
}
// 다중 검색 조건 적용
if (! empty($filters['filters'])) {
$searchableFields = ['name', 'slug', 'url'];
foreach ($filters['filters'] as $filter) {
$field = $filter['field'] ?? null;
$value = $filter['value'] ?? null;
$operator = $filter['operator'] ?? 'like';
if (! $field || ! $value) {
continue;
}
// 'all' 필드인 경우 모든 검색 가능 필드에서 검색
if ($field === 'all') {
$query->where(function ($q) use ($searchableFields, $value, $operator) {
foreach ($searchableFields as $searchField) {
$q->orWhere(function ($subQ) use ($searchField, $value, $operator) {
$this->applySearchableField($subQ, $searchField, $value, $operator);
});
}
});
} elseif (in_array($field, $searchableFields)) {
$this->applySearchableField($query, $field, $value, $operator);
}
}
}
// 정렬 (허용 컬럼 화이트리스트로 해석)
foreach ($this->resolveSortSpec($filters, self::SORTABLE_COLUMNS, 'order', 'asc') as $sort) {
$query->orderBy($this->qualifySortColumn($sort['column']), $sort['direction']);
}
// 자식 메뉴도 동일한 조건 적용하여 로드
return $query->with(['creator', 'roles', 'children' => function ($childQuery) use ($extensionFilter, $filters, $user) {
$childQuery->where($extensionFilter);
// 자식 메뉴에도 사용자 역할 기반 접근 제어 적용
if ($user) {
$childQuery->accessibleBy($user);
}
// 자식 메뉴에도 활성화 상태 필터 적용
if (isset($filters['is_active'])) {
$childQuery->where('is_active', $filters['is_active']);
}
$childQuery->with('roles')->orderBy('order');
}])->get();
}
/**
* 필터 연산자를 쿼리에 적용합니다.
*
* @param Builder $query 쿼리 빌더
* @param string $field 필드명
* @param string $value 검색 값
* @param string $operator 연산자 (like, eq, starts_with, ends_with)
*/
/**
* 검색 대상 필드에 조건을 적용합니다. (다국어 JSON 컬럼 인지)
*
* `name` 은 다국어 JSON 컬럼이다. JSON 은 유니코드 이스케이프(`\uXXXX`)로 저장되므로
* 컬럼 전체에 LIKE 를 걸면 한글·일본어 검색어가 **절대 매칭되지 않는다**
* (저장된 바이트는 `{"ko":"대시보드"}` 이다).
* 지원 로케일별 JSON 경로(`name->ko`)로 나눠 검색한다 — 저장소 공통 관례다.
*
* @param Builder $query 쿼리 빌더
* @param string $field 필드명
* @param string $value 검색 값
* @param string $operator 연산자 (like, eq, starts_with, ends_with)
*/
private function applySearchableField($query, string $field, string $value, string $operator): void
{
if (! in_array($field, self::TRANSLATABLE_COLUMNS, true)) {
$this->applyFilterOperator($query, $field, $value, $operator);
return;
}
$query->where(function ($q) use ($field, $value, $operator) {
foreach ($this->translatableLocales() as $locale) {
$q->orWhere(function ($subQ) use ($field, $locale, $value, $operator) {
$this->applyFilterOperator($subQ, "{$field}->{$locale}", $value, $operator);
});
}
});
}
/**
* 정렬 컬럼이 다국어 JSON 컬럼이면 현재 로케일 경로로 바꿉니다.
*
* JSON 원문으로 정렬하면 `{"ko":"\uXXXX...` 문자열 순서가 되어 사람이 읽는 순서와
* 무관해진다. 화면에 보이는 값(현재 로케일)으로 정렬해야 목록 순서가 납득 가능해진다.
*
* @param string $column 정렬 컬럼
* @return string 실제 정렬에 쓸 컬럼 표현
*/
private function qualifySortColumn(string $column): string
{
if (! in_array($column, self::TRANSLATABLE_COLUMNS, true)) {
return $column;
}
return $column.'->'.app()->getLocale();
}
/**
* 다국어 필드가 값을 가질 수 있는 로케일 목록을 반환합니다.
*
* 다국어 JSON 필드의 언어 집합은 `translatable_locales` 다 — 번역 파일이 없어도
* 데이터는 저장될 수 있으므로 UI 표시 언어(`supported_locales`)보다 넓다.
*
* @return array<int, string> 로케일 코드 목록
*/
private function translatableLocales(): array
{
$locales = config('app.translatable_locales', config('app.supported_locales', []));
return empty($locales) ? [app()->getLocale()] : array_values($locales);
}
private function applyFilterOperator($query, string $field, string $value, string $operator): void
{
switch ($operator) {
case 'eq':
$query->where($field, $value);
break;
case 'starts_with':
$query->where($field, 'like', $value.'%');
break;
case 'ends_with':
$query->where($field, 'like', '%'.$value);
break;
case 'like':
default:
$query->where($field, 'like', '%'.$value.'%');
break;
}
}
}