diff --git a/.env.example b/.env.example
index 27d61180..46373dbb 100644
--- a/.env.example
+++ b/.env.example
@@ -3,7 +3,7 @@ APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=http://localhost
-APP_VERSION=7.0.5
+APP_VERSION=7.0.6
APP_LOCALE=ko
APP_FALLBACK_LOCALE=ko
@@ -22,7 +22,9 @@ BCRYPT_ROUNDS=12
LOG_CHANNEL=stack
LOG_STACK=single
LOG_DEPRECATIONS_CHANNEL=null
-LOG_LEVEL=debug
+# 설치 직후 기본값은 운영 기준(error). 관리자 환경설정 > 고급에서 조정하며,
+# 그 값이 이 항목보다 우선합니다. debug 로 두면 정상 동작 기록까지 매 요청 쌓입니다.
+LOG_LEVEL=error
DB_CONNECTION=mysql
diff --git a/.env.testing.example b/.env.testing.example
index bec41e3b..ecfb2ee2 100644
--- a/.env.testing.example
+++ b/.env.testing.example
@@ -3,7 +3,7 @@ APP_ENV=testing
APP_KEY=
APP_DEBUG=false
APP_URL=http://localhost
-APP_VERSION=7.0.5
+APP_VERSION=7.0.6
APP_LOCALE=ko
APP_FALLBACK_LOCALE=ko
diff --git a/.gitignore b/.gitignore
index 009482e0..30b9125b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -48,6 +48,8 @@ node_modules/
# Settings JSON files (환경별 설정)
/storage/app/settings/
+# 성능 계측 리포트 (g7:bench --report) — 측정값이 실행 머신 사양에 종속되므로 저장소에 축적하지 않는다
+/storage/app/benchmarks/
# 확장 프론트엔드 병합 번들 캐시 (version-in-path, 런타임 생성)
/storage/app/ext-bundles/
diff --git a/AGENTS.md b/AGENTS.md
index 43d3de89..37b3d34b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,7 +6,7 @@
-### 백엔드 [backend/](docs/backend/) (32개)
+### 백엔드 [backend/](docs/backend/) (34개)
| 문서 | 설명 | TL;DR 핵심 |
|------|------|-----------|
@@ -16,6 +16,7 @@
| [api-documentation.md](docs/backend/api-documentation.md) | API 레퍼런스 문서 규정 (API Documentation) | 모든 API 엔드포인트는 레퍼런스 문서 필수 — 메서드/URI/파라미터/응답 필드 + 요청·응답 예시 ... |
| [api-resources.md](docs/backend/api-resources.md) | API 리소스 | Resource: BaseApiResource 상속 필수 / Collection: BaseApiColl... |
| [authentication.md](docs/backend/authentication.md) | 인증 및 세션 처리 | Laravel Sanctum 토큰 전용 인증 (Bearer 토큰만 사용) |
+| [benchmark.md](docs/backend/benchmark.md) | 성능 계측 시스템 (Benchmark) | `g7:bench` 가 4축(list/screen/write/batch)을 잰다 — 계측 대상은 커맨드... |
| [broadcasting.md](docs/backend/broadcasting.md) | Broadcasting (실시간 이벤트) | Laravel Reverb 사용 (WebSocket) |
| [console-confirm.md](docs/backend/console-confirm.md) | 콘솔 yes/no 프롬프트 (ConsoleConfirm) | 콘솔 커맨드의 yes/no 프롬프트는 $this->unifiedConfirm() 사용 — Laravel... |
| [controllers.md](docs/backend/controllers.md) | 컨트롤러 계층 구조 | AdminBaseController / AuthBaseController / PublicBaseCont... |
@@ -32,6 +33,7 @@
| [language-pack-service.md](docs/backend/language-pack-service.md) | LanguagePackService (백엔드 Service 레이어) | LanguagePackService 가 install/activate/deactivate/uninsta... |
| [middleware.md](docs/backend/middleware.md) | 미들웨어 등록 규칙 | 인증 필요 미들웨어 → 전역 등록 금지! |
| [notification-system.md](docs/backend/notification-system.md) | 알림 시스템 (Notification System) | GenericNotification 범용 클래스 1개로 모든 알림 처리 (개별 클래스 불필요) |
+| [pagination.md](docs/backend/pagination.md) | 대용량 목록 페이지네이션 (Pagination) | 총 건수만 상한을 받는다 — 상한 이하면 정확, 초과면 "이상"(total_relation=at_least) |
| [response-helper.md](docs/backend/response-helper.md) | API 응답 규칙 (ResponseHelper) | 모든 API 응답은 ResponseHelper 사용 |
| [routing.md](docs/backend/routing.md) | 라우트 네이밍 및 경로 | 모든 라우트는 name() 필수: ->name('api.users.index') |
| [search-system.md](docs/backend/search-system.md) | Scout 검색 엔진 시스템 (Search System) | Laravel Scout + DatabaseFulltextEngine: MySQL FULLTEXT + ... |
@@ -114,7 +116,7 @@
| [module-assets.md](docs/extension/module-assets.md) | 모듈 프론트엔드 에셋 시스템 | module.json에 에셋 매니페스트 정의 (js, css, loading strategy) |
| [module-basics.md](docs/extension/module-basics.md) | 모듈 개발 기초 | 디렉토리: vendor-module (예: sirsoft-ecommerce) |
| [module-commands.md](docs/extension/module-commands.md) | 모듈 Artisan 커맨드 | 목록: php artisan module:list |
-| [module-i18n.md](docs/extension/module-i18n.md) | 모듈 다국어 시스템 | 백엔드: /lang/{locale}/*.php → __('vendor-module::key') |
+| [module-i18n.md](docs/extension/module-i18n.md) | 모듈 다국어 시스템 | 백엔드: /src/lang/{locale}/*.php → __('vendor-module::key') ... |
| [module-identity-settings.md](docs/extension/module-identity-settings.md) | 모듈/플러그인 본인인증(IDV) 설정 통합 가이드 | 정책/목적/메시지: module.php::getIdentity{Policies,Purposes,Mess... |
| [module-layouts.md](docs/extension/module-layouts.md) | 모듈 레이아웃 시스템 | 위치: modules/_bundled/vendor-module/resources/layouts/admi... |
| [module-routing.md](docs/extension/module-routing.md) | 모듈 라우트 규칙 | URL prefix 자동: /api/modules/[vendor-module]/... |
@@ -150,24 +152,28 @@
| 대상 | 진입점 | 문서/엔드포인트 |
|------|--------|----------------|
-| 코어 | [docs/backend/api/README.md](docs/backend/api/README.md) | 35 / 291 |
+| 코어 | [docs/backend/api/README.md](docs/backend/api/README.md) | 36 / 319 |
-### 확장 API 레퍼런스 (9개 확장, 자동 스캔)
+### 확장 API 레퍼런스 (13개 확장, 자동 스캔)
> 각 확장이 소유하는 API 문서 목차. `php artisan api:docgen` 이 생성하며, 이 표는 `{modules,plugins}/_bundled/*/docs/api/README.md` 를 패턴 스캔해 자동 편입된다(확장명 하드코딩 없음).
| 확장 | 유형 | API 문서 목차 | 문서/엔드포인트 |
|------|------|--------------|----------------|
-| `gnuboard7-hello_module` | 모듈 | [docs/api/](modules/_bundled/gnuboard7-hello_module/docs/api/README.md) | 1 / 2 |
+| `gnuboard7-hello_module` | 모듈 | [docs/api/](modules/_bundled/gnuboard7-hello_module/docs/api/README.md) | 1 / 7 |
| `sirsoft-board` | 모듈 | [docs/api/](modules/_bundled/sirsoft-board/docs/api/README.md) | 10 / 80 |
-| `sirsoft-ecommerce` | 모듈 | [docs/api/](modules/_bundled/sirsoft-ecommerce/docs/api/README.md) | 33 / 231 |
+| `sirsoft-ecommerce` | 모듈 | [docs/api/](modules/_bundled/sirsoft-ecommerce/docs/api/README.md) | 33 / 239 |
| `sirsoft-page` | 모듈 | [docs/api/](modules/_bundled/sirsoft-page/docs/api/README.md) | 2 / 17 |
| `sirsoft-ckeditor5` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-ckeditor5/docs/api/README.md) | 2 / 2 |
| `sirsoft-gdpr` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-gdpr/docs/api/README.md) | 4 / 15 |
| `sirsoft-marketing` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-marketing/docs/api/README.md) | 2 / 2 |
-| `sirsoft-pay_kginicis` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-pay_kginicis/docs/api/README.md) | 5 / 22 |
-| `sirsoft-verification_kginicis` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-verification_kginicis/docs/api/README.md) | 1 / 1 |
+| `sirsoft-pay_kginicis` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-pay_kginicis/docs/api/README.md) | 5 / 34 |
+| `sirsoft-pay_nhnkcp` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-pay_nhnkcp/docs/api/README.md) | 0 / 0 |
+| `sirsoft-pay_nicepayments` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-pay_nicepayments/docs/api/README.md) | 0 / 0 |
+| `sirsoft-tosspayments` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-tosspayments/docs/api/README.md) | 2 / 4 |
+| `sirsoft-verification_kginicis` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-verification_kginicis/docs/api/README.md) | 2 / 3 |
+| `sirsoft-verification_nhnkcp` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-verification_nhnkcp/docs/api/README.md) | 1 / 1 |
@@ -188,7 +194,7 @@
### ① 코어 → 확장 동기화 (`requires.g7_version`)
-- 트리거: 코어 공개 확장 표면(`app/Extension/Abstract*`, `HookManager`, `ExtensionManager`, `ModuleManager`, `PluginManager`, `TemplateManager`, `app/Contracts/Extension/**`, `app/Extension/Helpers/**`, `app/Seo/Contracts/**`, `app/ActivityLog/**` 공개 API, 루트 `CHANGELOG.md` Added/Changed/Removed) 수정
+- 트리거: 코어 공개 확장 표면(`app/Extension/Abstract*`, `HookManager`, `ExtensionManager`, `ModuleManager`, `PluginManager`, `TemplateManager`, `app/Contracts/Extension/**`, `app/Extension/Helpers/**`, `app/Repositories/Concerns/**`, `app/Seo/Contracts/**`, `app/ActivityLog/**` 공개 API, 루트 `CHANGELOG.md` Added/Changed/Removed) 수정
- 조치: 영향 받는 번들 확장의 `g7_version` 상향 + 각 확장 CHANGELOG 에 변경 기재
### ② 확장 → 확장 동기화 (`dependencies.{modules|plugins}`)
@@ -219,6 +225,8 @@
| `handler: "nav"` | `handler: "navigate"` |
| `handler: "setLocalState"` | `handler: "setState"` + `target: "local"` |
| `navigate` + `replace: true` (URL만 변경 시) | `handler: "replaceUrl"` |
+| `navigate` `params.path: "back"` (동작 키워드로 착각) | `handler: "navigateBack"` — path 는 주소로 해석되어 조용히 `/back` 으로 이동한다 |
+| `navigate` `params.url` / `href` / `to` 로 목적지 전달 | `params.path` (또는 액션 `target`) — 엔진은 이 둘만 읽는다. 다른 이름은 무시되어 목적지가 `undefined` 가 되고, 예외도 404 도 없이 버튼만 동작하지 않는다 |
| apiCall `params.target` (params 내부) | `target` 은 액션 top-level. params 내부 위치 시 URL 미해석 |
| apiCall `params.onSuccess` / `params.onError` (params 내부) | 액션 top-level. params 내부면 무시됨 |
| `refetchDataSource` `params.id` | `params.dataSourceId` 사용 |
@@ -261,6 +269,8 @@ Icon 은 `` 글리프라 박스 크기가 곧 `font-size` 다. `w-N h-N` 은
| `w-3.5 h-3.5` | 14 | `text-sm` |
| `w-4 h-4` | 16 | `text-base` |
| `w-5 h-5` | 20 | `text-xl` |
+| `w-6 h-6` | 24 | `text-2xl` |
+| `w-12 h-12` | 48 | `text-5xl` |
`size` prop 은 Font Awesome `fa-*` 클래스로 매핑되며 등가가 아니다 — `size="sm"` → `fa-sm` → `font-size: 0.875em`(상대값) + `line-height` 붕괴로 16px 이 12.25×0.88px 이 된다. 새 아이콘에는 써도 되지만, 기존 `w-N h-N` 의 치환용으로는 쓰지 않는다.
@@ -297,6 +307,201 @@ Icon 은 `` 글리프라 박스 크기가 곧 `font-size` 다. `w-N h-N` 은
| `AuthManager.updateConfig({ loginPath: '//evil.com/...' })` (protocol-relative) | `//` 시작 금지 (open redirect 방지) |
| 401 에러 페이지(`errors/401.json`)에서 직접 로그인 리다이렉트 구현 | 코어 `TemplateApp.showRouteError` 가드에 위임 (자동 처리) |
+### 정적 확장자 라우트 / 자산 URL 생성
+
+| 금지 | 올바른 사용 |
+|------|------------|
+| `Route::get('{id}/routes.json', ...)` (`.js`/`.css`/`.json`/`.map` 단일 등록) | `Route::dualSuffix('{id}/routes', 'json', ...)` — 확장자 형태 + 확장자 없는 형태 동시 등록 |
+| `Route::get('bundle.js', ...)` (접미사가 종류를 구분해 제거 불가) | `Route::dualSuffixSegment('bundle', 'js', ...)` (`bundle.js` + `bundle/js`) |
+| `Route::get('assets/{id}/{path}', ...)` (와일드카드 자산) | `Route::dualAsset('assets/{id}', ...)` (`.../{path}` + `?file=` 쿼리) |
+| 서버에서 `'/api/templates/assets/'.$id.'/'.$path` 문자열 조립 | `App\Support\AssetUrl::templateAsset($id, $path)` |
+| 프론트에서 `` `/api/templates/${id}/routes.json` `` 템플릿 리터럴 조립 | `resources/js/core/support/assetUrl.ts` 의 `suffixed()` / `templateAsset()` 등 |
+
+정규식 location 은 프리픽스 location 보다 먼저 매칭되므로, 정적 최적화 블록(`location ~* \.(js|css|json)$`)이 있는 서버에서는 확장자 붙은 동적 응답이 `try_files ... /index.php` 폴백 기회 없이 404 가 된다. 서버측 `AssetUrl` 과 프론트측 `assetUrl.ts` 는 동일 규칙을 공유하므로 한쪽만 바꾸면 그 자산만 404 가 된다. 상세: [routing.md](docs/backend/routing.md) "정적 확장자로 끝나는 동적 엔드포인트", [api/README.md](docs/backend/api/README.md) "자산 URL 이중 모드".
+
+### 라우트 캐시 안전성
+
+`route:cache` 가 걸리면 `RouteServiceProvider::boot()` 이 캐시 로드로 분기해 라우트 파일 자체가 실행되지 않는다. 클로저는 직렬화 형태로 복원되므로 문제가 아니다 (`routes/web.php` SPA catch-all 이 증거). 깨지는 것은 오토로드되지 않는 심볼 참조뿐이다.
+
+| 금지 | 올바른 사용 |
+|------|------------|
+| 라우트 파일에 전역 함수 선언 + 핸들러가 호출 | 로직을 클래스(`app/Support/…`)로 옮기고 핸들러는 위임만 |
+| 파일 스코프 변수를 핸들러가 `use` 없이 참조 | 클래스 상수 또는 `use ($var)` 로 클로저에 캡처 |
+| 벤더/프로바이더가 `boot()` 에서 조건부 등록하는 라우트에 의존 | 그 URI 를 G7 라우트 파일이 직접 소유 |
+
+전역 함수 위반은 `Call to undefined function` 500 인데 예외의 `file` 이 `laravel-serializable-closure://` 라 원인 파일이 스택에 드러나지 않는다. 프로바이더 등록분이 사라지는 이유는 별개다 — `Router::setCompiledRoutes()` 가 `booted` 콜백에서 라우트 컬렉션을 통째로 교체하므로 그보다 앞선 등록은 조건 충족 여부와 무관하게 폐기된다(프레임워크 자신의 `BroadcastManager::routes()` 는 `routesAreCached()` 가드를 갖지만 모든 패키지가 그렇지는 않다). 정적 검사가 라우트 파일의 전역 함수 선언을 차단한다. 상세: [routing.md](docs/backend/routing.md) "캐시 안전한 라우트 작성".
+
+### 목록 컨텍스트 왕복 (list context round-trip)
+
+페이지네이션 목록 화면과 그에 딸린 상세·형제 상세·작성/수정 폼·확인 모달은 하나의 목록 클러스터다. 이 클러스터 안에서의 이동은 URL 목록 상태(`page`/`search`/`category`/`filters[*]`/정렬/`per_page`)를 손실 없이 보존해야 한다.
+
+| 금지 | 올바른 사용 |
+|------|------------|
+| 클러스터 내 navigate 에 `mergeQuery` 누락 | `"params": { "path": "…", "mergeQuery": true, "query": {} }` |
+| 이전글/다음글 등 형제 상세 이동만 규약에서 누락 | 목록 진입 / 목록 복귀 / 형제 이동 / 폼 취소 / 삭제 후 복귀 전 leg 동일 적용 |
+| 현재 값을 그대로 다시 넘기는 키 열거 (`{"del": "{{query.del ?? ''}}"}`) | `mergeQuery` 가 이미 전부 나른다 — 열거는 중복이자 누락 위험 |
+| 덮어쓸 키만 남기지 않고 필터 키 전부 재열거 | 값을 바꿔야 하는 키만 남긴다 (페이지 되돌림은 `{"page": ""}`) |
+| 새로고침 버튼에 `mergeQuery: false` | 새로고침은 보던 목록을 다시 부르는 것 — 병합 유지 |
+| `mergeQuery` 를 표현식으로 분기 (`"{{cond}}"`) | boolean 리터럴 고정 — 분기마다 보존 여부가 갈리면 한쪽이 조용히 상태를 떨군다 |
+| `"path": "/board/{slug}/write?parent_id={{id}}"` (인라인 쿼리스트링) | 인라인 쿼리는 병합 시 버려진다 → `query` 객체로 옮긴다 |
+| `mergeQuery: true` + `query` 키 생략 | 의도를 드러내도록 `"query": {}` 를 함께 둔다 |
+| `"query": []` (배열 리터럴) | `"query": {}` — 동작은 같아 조용히 통과하지만, 나중에 덮어쓸 키를 넣으면 그 값이 버려진다 |
+| 목적지가 표현식이라 판정 불가한 이동을 무표시로 둠 (`"{{_global.shopBase}}/products"`) | 클러스터 내 이동이면 `mergeQuery: true`, 밖으로 나가는 이동이면 예외 주석으로 의도를 명시 |
+| 의도적 리셋(검색·필터 초기화 / 탭 전환 / 프리셋 적용)에 `mergeQuery: true` | 리셋은 병합하지 않는다 — 병합하면 초기화 버튼이 아무 일도 하지 않는다 |
+| 탭 전환(`onTabChange`)이나 겹치지 않는 다른 목록으로의 이동에 `mergeQuery: true` | 목록 정체성이 다르면 승계하지 않는다 — 남의 검색어·페이지가 얹혀 빈 화면이 열린다 |
+| 면제 주석은 "병합하지 않는다" 인데 코드는 `mergeQuery: true` | 주석과 코드를 일치시킨다 (주석은 사실이 아니라 선언일 뿐) |
+| 검색 실행·페이지 이동 액션에서 `query` 키를 비움 | 값을 바꾸는 액션은 그 값을 직접 넘긴다 (`{"page": "{{$args[0]}}"}`) — 병합만으로는 새 값이 전달되지 않는다 |
+| `path` 없이 `query` 만 바꾸는 액션에 `mergeQuery` 누락 (탭 전환 `{"tab": …}`, 항목 선택 `{"id": …, "mode": "view"}`) | `path` 생략은 "현재 주소에 작용" 이라 목록 화면 자신이 대상 — `mergeQuery: true` 없으면 지금 걸린 목록 상태가 통째로 날아간다 |
+
+의도적 리셋(검색 초기화 / 필터 초기화 / 탭 전환 / 프리셋 적용 / 다른 목록으로의 이동)은 예외다. 그 경우 액션 노드 `comment` 에 `audit:allow layout-list-context-navigate-merge-query <사유>` 를 남겨 의도를 코드에 기록한다. 상세: [actions-handlers-navigation.md "목록 컨텍스트 왕복 규약"](docs/frontend/actions-handlers-navigation.md)
+
+### 중첩 리소스 스코프 / 계층 무결성
+
+| 금지 | 올바른 사용 |
+|------|------------|
+| 중첩 라우트의 상위 리소스 ID 를 받아만 두고 조회에 미반영 | Repository where 절에 상위 스코프 반영(SSoT) + Service 가 상위 ID 전달 → 교차 접근 시 404 |
+| `$request->except(...)` / `->all()` 결과를 Service 쓰기 메서드로 전달 | `$request->validated()` 기준 (FormRequest 미정의 필드가 `$fillable` 로 새는 것 차단) |
+| 요청 배열 항목의 `Rule::exists` 에 상위 스코프 미부착 | `Rule::exists(Model::class,'id')->where('order_id', $order->id)` → 422 |
+| 수정/순서변경 FormRequest 의 `parent_id` 에 `Rule::exists` 만 부착 | 자손 전체를 검사하는 순환 방지 Rule 부착 (자기참조만 막는 Rule 은 `A→B→A` 통과) |
+| 같은 리소스의 두 엔드포인트가 서로 다른 검증 강도 | 부모 변경 경로 전부 동일 강도 — 약한 쪽이 우회로가 된다 |
+| 설정값이 정하는 한계를 Service 에서 리터럴로 재클램프 | Service 는 계산만, 상한 검증은 Rule 단일 책임 (이중 클램프 시 깊이 제한이 통째로 무력화) |
+| 계층 재귀(path/depth 재계산)에 방문 ID 가드 없음 | 방문 집합으로 유한 종료 — 검증 우회 경로/오염 데이터에서도 무한 루프 금지 |
+
+> 상세: [validation.md "계층 리소스 순환 참조" / "배열 항목의 상위 스코프"](docs/backend/validation.md), [service-repository.md "중첩 리소스 스코프" / "설정 기반 한계값"](docs/backend/service-repository.md)
+
+### 목록 응답의 하위 컬렉션
+
+목록은 화면이 그 행에서 **실제로 그리는 것**만 싣는다. 행마다 하위 컬렉션을 통째로 직렬화하면 한 페이지를 여는 것만으로 수백~수천 행이 응답에 실린다 (공개 #76 — 상품 100건 × 옵션 20건).
+
+| 금지 | 올바른 사용 |
+|------|------------|
+| `relationLoaded('x') ? $this->x : $this->whenLoaded('y')` (가짜 가드) | `whenLoaded('x', fn () => ...)` 하나만 — 로드 여부는 **Repository 가** 결정한다 |
+| Resource 는 `whenLoaded` 로 방어하는데 Repository 가 목록에서 무조건 eager load | 목록의 `relations:` 는 목록이 **실제로 직렬화하는** 관계만 |
+| 개수/합계를 PHP 컬렉션 연산으로 (`$this->options->where(...)->sum(...)`) | `withCount:` / `withSum`(`outerUsing:`) DB 집계 |
+| `toListArray()` 를 정의해 두고 컬렉션이 `toArray()` 를 호출 | 컨트롤러/컬렉션이 목록 표현을 **명시 호출** |
+| 목록 Resource 안에서 관계 재쿼리 (`$this->images()->first()`) | `relationLoaded` 분기로 로드된 컬렉션에서 고른다 |
+| 집계 별칭 존재 여부를 `!== null` 로 판정 | `array_key_exists($alias, $model->getAttributes())` — SUM 은 0건에서 NULL 이라 값 검사로는 "집계 안 함" 과 구분되지 않는다 |
+| 목록에서 뺀 값을 대체 경로 없이 제거 | 지연 로드 경로(배치 조회)를 먼저 만들고, 하위호환은 opt-in 파라미터(`?with_options=1`)로 |
+
+착수 전 **소비처를 실측**한다. 화면이 그 값을 실제로 순회·렌더하면 제거는 기능 축소다 — 계획서에 "안 쓴다" 고 적혀 있어도 레이아웃 JSON 을 열어 확인한다.
+
+> 상세: [api-resources.md](docs/backend/api-resources.md), [service-repository.md](docs/backend/service-repository.md)
+
+### 저장값 + 확장 카탈로그 병합 설정의 공개 응답
+
+설정 항목이 "운영자 저장값 + 확장이 훅으로 등록한 카탈로그" 의 병합으로 만들어지면, 저장값은 남아 있는데 카탈로그에서 항목이 사라지는 상태가 생긴다 — 그 확장을 삭제·비활성화했거나, 확장이 자기 기능 토글을 껐을 때다. 병합부는 이를 고아 항목으로 표시하지만 저장값의 `is_active` 는 참 그대로 남는다.
+
+| 금지 | 올바른 사용 |
+|------|------------|
+| 공개 응답이 저장값 플래그(`is_active`)만 보고 항목을 내보냄 | 카탈로그 소속(`_orphaned`)을 함께 판정 — 공급 확장이 더 이상 제공하지 않는 항목은 공개 응답에서 제거 |
+| 고아 항목을 관리자 응답에서도 제거 | 관리자 응답은 유지 — 운영자가 확인하고 지워야 할 대상이다 |
+| 소비 화면(레이아웃 JSON)마다 필터를 넣어 차단 | 공개 API 단일 지점에서 차단 — 화면마다 복제하면 템플릿 하나만 빠져도 같은 결함이 남는다 |
+| 같은 데이터를 내보내는 공개 엔드포인트가 서로 다른 게터를 사용 | 전 엔드포인트가 같은 공개 게터를 경유 — 한쪽이 raw `getSettings()` 를 쓰면 그 경로만 조용히 뚫린다 |
+| 항목 제거 후 배열 인덱스를 그대로 둠 | `array_values()` 로 재정렬 — 비연속 키는 JSON 객체로 직렬화되어 화면 반복이 깨진다 |
+
+이 결함은 예외도 경고도 로그도 남기지 않는다. 이미 제공 불가한 항목이 사용자 화면에서 선택 가능한 상태로 남아 있는 것이 유일한 증상이고, 관리자 화면은 고아 표시로 정상 차단하고 있어 양쪽을 나란히 보지 않으면 드러나지 않는다.
+
+> 상세: [module-settings.md](docs/extension/module-settings.md) "카탈로그 병합 설정의 공개 응답"
+
+### 목록 조회 컬럼 프루닝과 지연 조인
+
+| 금지 | 올바른 사용 |
+|------|------------|
+| `->paginate($perPage)` / `->paginate($perPage, ['*'])` (컬럼 목록 미지정) | 목록이 실제로 쓰는 컬럼만 명시. 깊은 OFFSET 이 가능한 목록은 `PaginatesWithDeferredJoin` |
+| 요청 값에서 온 정렬 컬럼을 그대로 `orderBy` 에 전달 | `ResolvesSortSpec` 으로 닫힌 집합 해석 (방향만 검사하는 `in_array` 는 보호가 아니다) |
+| 지연 조인의 `$query` 에 미리 `orderBy`/`with`/`select` 적용 | 필터/where 만 적용해 넘기고, 정렬·관계·컬럼은 trait 인자로 전달 |
+| 쿼리에 `with()` 만 하고 `relations:` 인자 생략 | 관계는 `relations:` 로 전달 — trait 이 inner 뿐 아니라 **outer 에서도** eager load 를 지우므로 관계가 조용히 사라진다 (예외·쿼리 오류 없이 응답에서 필드만 없어져 관계를 단언하지 않는 테스트는 전부 통과) |
+| 목록 SELECT 에 `SUBSTRING(content, 1, N)` 을 두고 프루닝했다고 간주 | 오버플로 페이지 읽기가 그대로 발생 — 잘라내기는 outer(`$columns`)에서만 |
+| 그룹 쿼리(`groupBy`)의 총 건수를 `count()` 로 계산 | `getCountForPagination()` (서브쿼리로 감싸 그룹 수를 센다) |
+| raw SQL 안에 테이블명·별칭을 문자열로 조립 | 테이블명은 `(new Model)->getTable()`, 프리픽스는 `DB::getTablePrefix()`, 별칭은 빌더(`join($table.' as uc', …)`)가 만들게 |
+| `whereRaw('1 = 0')` / `where($c, DB::raw("({$sub->toSql()})"))` + `mergeBindings` | `whereIn($key, [])` / `where($c, '=', $sub)` (빌더가 바인딩까지 처리) |
+| 화면 정렬 셀렉트에 게이트가 모르는 컬럼을 넣기 | `화면 옵션 ⊆ FormRequest 게이트 ⊆ Repository 화이트리스트` — 어긋나면 422 후 직전 목록이 남아 정렬된 것처럼 보인다 |
+| 분류값 필터의 허용 어휘를 화면·게이트·기록 지점에 각각 리터럴로 적기 | 어휘는 Enum 단일 출처에서 파생 — `화면 필터 옵션 = 라벨 키 = 실제 기록 어휘`. 부분집합이 되면 빠진 값으로 기록된 행이 어떤 필터 조합으로도 도달 불가하고, 라벨 키가 없는 값은 목록 셀에 원시 키 문자열로 노출된다 |
+| 목록 응답이 `last_page > 1` 인데 화면에 페이저·총건수가 없음 | 페이지 이동 컨트롤과 총건수를 함께 노출 — 없으면 1페이지 밖 행이 조용히 잘리고, 잘렸다는 사실조차 화면에 나타나지 않는다 |
+| 쿼리 파라미터 불리언에 `boolean` 규칙만 부착 | `prepareForValidation()` 으로 `"true"`/`"false"` 정규화 (쿼리는 문자열로 도착 — 화면이 그 형태로 보내면 목록 전체가 422). 단, 해석 불가한 값은 건드리지 말 것 |
+| 같은 화면의 개수 배지와 그 배지가 여는 목록이 서로 다른 엔드포인트 | 배지 계산과 목록 조회는 같은 스코프의 같은 데이터소스에서 |
+| 관계 테이블 컬럼 정렬을 `join`+`groupBy` 로 구현 | `SortsByRelatedColumn` 의 상관 서브쿼리 (1:N 조인은 원 행을 부풀려 총 건수·페이지 경계를 깨고, INNER 는 자식 없는 행을 지운다) |
+| 관계 정렬을 넣고 인덱스는 그대로 | `(외래키, 정렬컬럼)` 복합 인덱스 마이그레이션 동반 (서브쿼리가 행마다 실행된다) |
+| 페이지네이션 정렬을 비고유 컬럼(`created_at` 등)으로만 끝내기 | 정렬 마지막에 기본키를 덧붙여 전순서 보장 (동률 구간에서 인접 페이지가 같은 행을 중복 노출하고 다른 행을 누락한다) |
+
+> 상세: [service-repository.md "목록 조회 컬럼 프루닝과 지연 조인" / "정렬 컬럼 화이트리스트" / "화면 정렬 옵션은 게이트의 부분집합이어야 한다" / "관계 테이블 컬럼 기준 정렬" / "허용되는 Raw 쿼리"](docs/backend/service-repository.md)
+
+### 대용량 목록의 총 건수와 페이지 이동
+
+총 건수 상한과 페이지 이동 범위는 **별개 결정**이다. 묶으면 필요 없이 기능이 깎인다. 총 건수만 상한을 받고, "다음" 이동은 `per_page + 1` 실측으로 끝까지 열어 둔다. 계산이 불가능해지는 것은 마지막 페이지 번호 하나뿐이다.
+
+| ❌ 금지 | ✅ 올바른 사용 |
+|--------|---------------|
+| 같은 술어를 `count()` 한 번, `get()` 한 번 실행 | `BoundedPaginator::paginate()` 한 번 (총 건수 + 페이지를 한 번에) |
+| `paginate(PHP_INT_MAX)` 후 PHP `array_slice` | 실제 `page`/`per_page` 를 저장소까지 하달 |
+| `forPage($page, $perPage + 1)` | offset 은 `per_page` 기준으로 따로 계산 (안 그러면 페이지가 깊어질수록 경계가 밀린다) |
+| Scout `->keys()->all()` + 무제한 `whereIn` | 키워드 술어를 페이지 쿼리에 직접 밀어넣기 (`DatabaseFulltextEngine::whereFulltext`) |
+| FULLTEXT 원문 키워드를 raw 로 바인딩 | 코어 sanitizer 경유 — `+` `-` `*` `"` 입력이 파싱 오류로 500 이 된다 |
+| `whereDate` / `whereYear`+`whereMonth` | `FiltersByDateRange` 의 범위 조건 (컬럼에 함수를 씌우면 인덱스를 못 쓴다) |
+| 총 건수를 모르는데 `last_page` 를 1 로 채움 | `null` 로 내보내 화면이 마지막 페이지 점프만 감추게 한다 |
+| 상한값을 저장소·화면에 리터럴로 재기입 | `PaginationLimits` 단일 해석 + 확장은 `core.pagination.filter_*` 필터 훅으로만 조정 |
+| 결과 크기가 데이터 증가에 비례하는데 상한 없는 `->get()` / `->pluck()` | 목록은 페이지네이션, 순회는 `chunkById`/`lazyById`, 몇 건이면 `limit` — 운영자 등록 수에 묶인 설정성 테이블만 예외이며 그 근거를 코드에 남긴다 |
+| 배지·요약 건수를 `int` 하나로 돌려주기 | `BoundedPaginator::count()` 의 `BoundedCount` — 잘린 값과 정확한 값이 구분되지 않으면 잘린 10,000 이 "정확히 10,000 건" 으로 화면에 나간다 |
+| 여러 카테고리 건수를 합치며 정확도는 버리기 | 하나라도 부정확하면 합계도 부정확. 단, 특정 탭만 볼 때는 그 카테고리의 정확도만 본다 |
+| 정렬 마지막이 비고유 컬럼 | 기본키를 덧붙여 전순서 보장 (동률 구간에서 행이 겹치거나 샌다) |
+| 관련도순(`_ft_score`)에 커서 적용 | 계산값은 WHERE 절 경계로 쓸 수 없다 — offset 유지 (`KeysetPaginator::supports` 가 판정) |
+
+> 상세: [pagination.md](docs/backend/pagination.md)
+
+### 검색 인덱스 재생성(리인덱싱)
+
+| ❌ 금지 | ✅ 올바른 사용 |
+|--------|---------------|
+| 재생성을 자동 트리거(마이그레이션 종료·확장 업데이트 완료 등)에 연결 | 운영자가 **명시적으로 선택**했을 때만 수행. 인덱스 잠금·전체 재색인 비용이 운영 중 사이트를 멈춘다 |
+| 재생성 체크 상태를 전역에 남겨 다음 모달 진입에 이월 | 모달 진입 시드와 제출 후 초기화 **양쪽**에서 해제. 이월되면 운영자가 아무것도 누르지 않았는데 재생성이 수행되고, 서버 옵인 가드는 정상이라 HTTP 테스트로는 드러나지 않는다 |
+| 모듈·플러그인 모달이 같은 전역 키 공유 | 면마다 별도 키 (한쪽 체크가 다른 쪽으로 전이 금지) |
+| 응답 헬퍼가 `JsonResource::resolve()` 만 호출해 `additional()` 유실 | 부가 데이터를 응답 최상위에 병합 — 색인 누락은 오류 없이 "검색 0건" 으로만 나타나므로 응답 페이로드가 유일한 통로다 |
+| 재생성 수행을 곧 복구로 간주 | `remaining` 은 **재생성 후 재점검** 결과 — "재생성했다" 와 "복구됐다" 를 구분해 보고 |
+| 점검 커맨드의 비-0 종료를 "실행 실패" 로 표시 | 이상 발견 신호다. 종료 코드와 출력을 그대로 노출 |
+| 특정 엔진(FULLTEXT) 전용으로 점검·재생성 구현 | `SearchIndexMaintainer` 계약 + `core.search.index_maintainers` 훅 |
+| "점검 대상 0" 과 "점검 불가" 를 같은 문구로 보고 | 구분 보고 — 뭉뚱그리면 "인덱스가 다 정상" 으로 읽힌다 |
+
+> 상세: [search-system.md](docs/backend/search-system.md)
+
+### 검색 질의는 활성 엔진이 만든다
+
+검색 엔진은 `core.search.engine_drivers` 훅으로 교체 가능하다. 그런데 그 교체가 실제로 먹는 것은 **활성 엔진을 거치는 경로뿐**이다. 저장소가 구체 엔진 클래스를 지목하면 등록된 엔진은 호출될 기회 자체를 잃고, 오류도 경고도 없이 그 사이트의 검색만 조용히 다른 방식으로 동작한다.
+
+| ❌ 금지 | ✅ 올바른 사용 |
+|--------|---------------|
+| `DatabaseFulltextEngine::whereFulltext(...)` 등 구체 엔진 정적 호출 | `KeywordSearch::apply()` / `::applyAny()` (해석기가 활성 엔진에 위임) |
+| `DB::getDriverName() === 'pgsql'` 처럼 드라이버명을 코드에 비교 | 선언형 `config('core.search.*')` + `core.search.like_operators` 필터 훅 |
+| 매칭 ID 전량을 PHP 로 적재 후 `whereIn` (`search()->keys()->all()`) | 술어를 페이지 쿼리에 직접 부착 — ID 왕복도 목록 폭발도 없다 |
+| 엔진에게 페이지 번호를 넘겨 한 페이지만 받기 | 페이지네이션은 DB 담당. 엔진은 **키 집합 상한**만 책임진다 (`KeywordSearchContext`) |
+| 키 집합 상한을 총 건수 상한과 다른 값으로 두기 | 둘 다 `PaginationLimits::resultCap()` — 갈라지면 엔진이 돌려준 건수와 화면 총 건수의 근거가 달라진다 |
+| 부분일치 폴백을 "전문검색 없을 때의 임시방편" 으로 취급 | 전문검색 미제공 DBMS 에서는 **그것이 정상 경로** — 와일드카드 escape + 대소문자 규칙을 갖춘다 |
+| 확장이 `Model::search()` 를 쓰는 것을 금지로 오해 | Scout 경로는 그대로 유효하다. 새 계약은 대체가 아니라 **추가 통로** |
+
+정적 검사는 이 저장소 안만 볼 수 있다 — 외부 엔진이 상한을 지키는지는 강제할 수 없으므로, 코어는 **값을 손에 쥐어 주는 것**까지 하고 그 값이 도달하는지를 계약 테스트가 고정한다.
+
+> 상세: [search-system.md "키워드 술어는 활성 엔진이 만든다"](docs/backend/search-system.md)
+
+### 통화 단위는 설정이 정한다
+
+G7 은 **기본 통화**(상품·쿠폰·배송비 저장 기준), **표시 통화**(구매자가 고른 통화), **결제 통화**(PG 청구 통화)를 각각 따로 설정한다. 셋은 같을 수도, 모두 다를 수도 있다. 금액을 다루는 지점이 특정 통화를 전제하면 값은 맞고 **단위만 틀린** 금액이 나가며, 예외도 경고도 없다.
+
+| 금지 | 올바른 사용 |
+|--------|---------------|
+| 다국어 문구에 `:amount원` / `:amount円` | 문구는 `:amount` 로 중립, 호출부가 `ecommerce_format_price($amount, $currency)` 로 포맷해 전달 |
+| 레이아웃에서 `{{금액.toLocaleString()}}원` 조립 | 서버가 준 `*_formatted` / `multi_currency_*[통화].formatted` 를 그대로 출력 |
+| `formatCurrencyPrice($price, 'KRW')` (통화 코드 리터럴) | `formatBaseCurrency()` / `formatOrderCurrency()` (설정·주문 스냅샷이 통화를 정한다) |
+| `number_format($amount).'원'` | 같은 도메인의 통화 인지 헬퍼(`formatOrderChargeAmount()` 등) 경유 |
+| `_global.preferredCurrency ?? 'KRW'` | `_global.preferredCurrency ?? _global.defaultCurrency` (둘 다 없으면 `*_formatted` 로 내려간다) |
+| 통화표를 코드에 고정(기호·자릿수 5종 표 + 특정 통화 폴백) | 설정의 `symbol` / `decimal_places` 를 읽고, 미설정 시에만 폴백표 |
+| `code === 'KRW' ? 0자리 : 2자리` 식 코드 분기 | `decimal_places` 로 판정 (운영자가 추가한 0자리 통화도 포함) |
+| 통화 선택 입력의 기본값을 `"KRW"` 로 시드 | 설정의 `default_currency` — 마일리지처럼 **통화별 원장**을 쓰는 도메인은 표시가 아니라 **기록이 틀어진다** |
+
+언어는 통화가 아니다. 한국어 문구에 `원`, 일본어에 `円` 을 박으면 기본 통화가 다른 상점에서 UI 언어가 통화를 결정하게 된다 — 영어 문구가 `:amount` 로 중립인 것이 정답이다.
+
+주문·결제·환불 금액은 **거래 시점 통화로 동결**한다(`currency_snapshot.base_currency`). 운영자가 이후 기본 통화를 바꿔도 과거 주문의 표기는 불변이어야 한다.
+
+> 상세: [api-resources.md](docs/backend/api-resources.md), [service-repository.md](docs/backend/service-repository.md)
+
### Listener 데이터 접근
| 금지 | 올바른 사용 |
@@ -704,9 +909,15 @@ Controller → Request → Service → RepositoryInterface → Repository → Mo
절대 금지: DB CASCADE에 의존한 삭제 → Service에서 명시적 삭제 (훅/파일/로깅 보장)
절대 금지: 로케일 하드코딩 → config('app.supported_locales') 사용
필수: 마이그레이션 한국어 comment 필수, down() 구현 필수
+필수: FK 컬럼의 ->comment() 는 ->constrained()/->references()/->on() 앞에 둔다 (뒤에 두면 comment 가 컬럼이 아닌 FK 정의에 부착되어 조용히 사라진다)
+필수: 소스 교정만으로는 기설치본이 낫지 않는다 — 마이그레이션은 재실행되지 않으므로 업그레이드 스텝 백필을 함께 작성
+필수: 필터가 걸린 쿼리를 순회하며 그 행을 update/delete 하면 chunkById() (키셋 순회)
+절대 금지: 그 경우 chunk()/each()/lazy() 사용 — OFFSET 기반이라 처리된 행이 결과에서 이탈한 만큼 커서가 밀려 미처리 행을 조용히 건너뛴다 (250건/청크 100 → 100건 누락, 예외·로그 없음)
주의: ResponseHelper::success($messageKey, $data) — 메시지가 첫 번째 인수
```
+갱신값이 항상 필터 소속을 유지해 안전한 경우(예: `whereNotNull` + 갱신값이 항상 non-null)만 예외이며, 그 근거를 코드 주석에 남긴다. 정적 검사가 이 패턴을 검출한다.
+
> 상세 규칙 (API 리소스, ServiceProvider, validation, 인증, 활동 로그 등): [docs/backend/](docs/backend/) 각 문서 참조
### 컨트롤러 계층
@@ -750,7 +961,9 @@ BaseApiController (최상위)
필수: 확장 코드 변경 시 manifest 버전 업 (미변경 시 업데이트 감지 불가)
필수: 버전 업 시 CHANGELOG.md 기록 — Keep a Changelog 표준 (미기록 시 버전 업 불가)
필수: StorageInterface 사용 (Storage::disk() 직접 호출 금지)
+필수: ActionDispatcher 에 핸들러를 등록하는 확장은 재등록 진입점을 window 전역에 고정 이름으로 노출 — 모듈 window.__[Name].initModule, 플러그인 window.__[Name].initPlugin (미노출 시 로케일 전환 후 해당 확장 액션이 전부 무반응, 에러·토스트 없음). 진입점은 핸들러 재등록만 수행
필수: 확장 미들웨어는 getMiddleware() 로 부착 대상(targets) 명시 선언 (self-gate) — SP Kernel 미들웨어 그룹 직접 조작·라우트 파일 자기 미들웨어 FQCN 부착 금지, 무규율 전역 개입 금지
+필수: 라우트 정의를 바꾸는 지점은 App\Support\RouteCacheHelper::rebuild() 로 라우트 캐시 갱신 — 확장 설치/활성화/비활성화/삭제/업데이트, 코어 업데이트·업그레이드 스텝. route:clear/route:cache 를 각 지점에 직접 흩어 놓지 않는다 (누락 발생, 비우기만 하면 재생성되지 않아 성능 이점 영구 소실). 훅 캐시와 달리 라우트 캐시에는 스캔 폴백이 없어 캐시에 없는 라우트는 예외·경고 없이 404. 파일 교체 중인 코어 업데이트는 중간에 clear(), 끝에서 rebuild(). 템플릿·모듈 설정은 서버 라우트 무관 (상세: docs/backend/routing.md "라우트 캐시")
필수: 코어 레이아웃에 모듈 UI 주입은 layout_extensions만 사용
필수: 모든 확장 작업은 Artisan 커맨드로 수행
```
@@ -807,14 +1020,18 @@ public function createProduct(array $data): Product
| `*.json` (레이아웃만) | `{type}:update {id} --force` 실행 |
| `*.tsx`, `*.ts` + `*.json` | `{type}:build` + `{type}:update {id} --force` |
| `*.tsx`, `*.ts`만 | `{type}:build` + `{type}:update {id} --force` |
+| `lang-packs/_bundled/**` (번들 언어팩 콘텐츠/버전) | `language-pack:update {id} --force` (빌드 불필요) |
```bash
# 확장 업데이트 (_bundled → 활성 반영)
php artisan template:update sirsoft-admin_basic --force
php artisan module:update sirsoft-ecommerce --force
php artisan plugin:update sirsoft-payment --force
+php artisan language-pack:update g7-core-ja --force
```
+번들 언어팩도 `_bundled` 는 배포 원본일 뿐이다. 설치본(`lang-packs/{id}/`)을 갱신하지 않으면 새로 추가한 번역 키가 런타임에 존재하지 않아 해당 로케일이 조용히 기준 로케일로 폴백한다.
+
### 코어 3-번들 구조 + 공유 런타임 (engine-v1.51.0+)
`core:build` 는 코어 프론트엔드를 3개 IIFE 번들로 빌드한다:
@@ -971,6 +1188,7 @@ php artisan migrate:rollback
| `lang/**` | [database-guide.md](docs/database-guide.md) (다국어 섹션) |
| `routes/**` | [routing.md](docs/backend/routing.md) |
| `app/Seo/**` | [seo-system.md](docs/backend/seo-system.md) |
+| `app/Benchmark/**`, `config/benchmark.php` | [benchmark.md](docs/backend/benchmark.md) |
---
@@ -1003,3 +1221,8 @@ php artisan migrate:rollback
- **ResolvesActivityLogType**: `app/ActivityLog/Traits/ResolvesActivityLogType.php`
- **ChangeDetector**: `app/ActivityLog/ChangeDetector.php`
- **CoreActivityLogListener**: `app/Listeners/CoreActivityLogListener.php`
+- **BenchmarkProfileRegistry**: `app/Benchmark/BenchmarkProfileRegistry.php`
+- **성능 계측 DTO**: `app/Benchmark/DTO/{BenchmarkProfile,BenchmarkRunOptions,BenchmarkResult}.php`
+- **BenchmarkAxisRunner**: `app/Benchmark/Contracts/BenchmarkAxisRunner.php`
+- **성능 계측 축 실행기**: `app/Benchmark/Axes/{List,Screen,Write,Batch}AxisRunner.php`
+- **BenchmarkAxis**: `app/Enums/BenchmarkAxis.php`
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1e7ce37e..1a82be45 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,224 @@
형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)를 따르며,
[Semantic Versioning](https://semver.org/lang/ko/)을 준수합니다.
+## [7.0.6] - 2026-08-10
+
+### Security
+
+- 언어팩 안의 PHP 파일에 번역 배열 외의 코드가 들어 있으면 설치 단계에서 거부하도록 바꿨습니다. 언어팩의 PHP 파일은 활성화되면 사이트가 그대로 실행하므로, 파일을 만들거나 외부 명령을 실행하는 코드가 섞여 있으면 서버에서 임의 코드가 실행될 수 있었습니다. 이전에는 위험한 함수 몇 가지를 이름으로 골라 막았기 때문에 목록에 없는 함수나 함수 이름을 쓰지 않는 방식으로 우회할 수 있었습니다. 이제는 번역 배열만 통과시키므로 어떤 형태의 코드든 들어갈 수 없으며, 거부될 때는 어느 파일 몇 번째 줄이 문제인지 알려 드립니다. 함께 언어팩에 담을 수 있는 파일 형식을 `.json`·`.php`·`.md` 로 한정하고, PHP 파일은 정해진 언어 폴더 안에만 둘 수 있게 했습니다. (KISA 측에서 제보해주셨습니다 — KVE-2026-1678)
+- 언어팩을 설치하면서 곧바로 활성화하려면 언어팩 관리 권한이 필요하도록 바꿨습니다. 설치 권한과 활성화 권한은 원래 별도인데, 설치 요청에 '바로 켜기'를 함께 보내면 설치 권한만으로 활성화까지 되어 권한 경계가 무너져 있었습니다. 권한이 없으면 그 항목만 거부되고 설치 자체는 그대로 진행됩니다. 파일·URL·GitHub·번들 네 가지 설치 경로 모두 같은 기준을 적용하므로, 어느 경로로 설치하느냐에 따라 권한 경계가 달라지지 않습니다. 저장소에 동봉된 번들 언어팩의 재설치도 종전처럼 할 수 있으며, 다만 활성화 권한이 없으면 재설치한 언어팩이 꺼진 상태가 되어 다시 켜려면 관리 권한이 필요합니다. (KISA 측에서 제보해주셨습니다 — KVE-2026-1678)
+- 설치 마법사의 PHP·Composer 실행 경로 입력에서 실행 파일이 아닌 값을 넣지 못하도록 형식 검사를 강화했습니다. 이전에는 실행 파일 뒤에 다른 파일이나 옵션을 덧붙이는 형태가 통과해, 설치가 끝나지 않은 상태에서 서버의 임의 코드가 실행될 수 있었습니다. 정상적인 입력(멀티 PHP 환경의 "PHP 경로 Composer 경로" 형태, 시놀로지·cPanel·Plesk 등의 다양한 PHP 실행 파일 이름, Windows 경로)은 그대로 사용할 수 있으며, 파일 존재 여부를 미리 확인하지 않으므로 접근이 제한된 서버에서도 정상 경로가 거부되지 않습니다. (KISA 측에서 제보해주셨습니다 — KVE-2026-1677)
+- 아직 공개하지 않은 예약 작업 기능에서, Artisan 명령 예약의 실행 제한을 허용 목록 방식으로 바꿔 정식 공개에 대비했습니다. 종전에는 위험한 명령 몇 가지만 거부하고 나머지를 모두 허용했기 때문에, 예약 작업 권한을 위임받은 계정이 파일을 만들거나 데이터베이스 구조를 바꾸는 명령을 등록할 수 있었습니다. 이제 캐시 정리·큐 처리·만료 데이터 정리 같은 유지보수 명령만 등록할 수 있고, 각 명령에 붙일 수 있는 옵션도 정해진 것만 허용합니다. 설치된 모듈·플러그인이 제공하는 명령은 자동으로 허용됩니다. 등록이 거부되면 왜 거부됐는지(허용 목록 밖 / 형식 오류 / 허용되지 않은 옵션 / 추가 인자 불가)를 구분해 안내합니다. 이 기능은 현재 메뉴에 노출되지 않아 실제 사용 경로가 없습니다. (KISA 측에서 제보해주셨습니다 — KVE-2026-1679)
+- 같은 기능에서, 저장한 예약 작업 명령이 실행 직전에 다시 해석되면서 저장할 때 확인한 것과 다른 명령이 실행될 수 있던 경로도 함께 막았습니다. 명령을 따옴표나 역슬래시로 감싸면 검사 단계와 실행 단계가 서로 다른 명령으로 읽었습니다. 이제 명령 형식을 `명령명 --옵션[=값]` 으로 한정하고 실행할 때도 해석된 결과를 그대로 사용하므로, 확인한 명령과 실행되는 명령이 달라질 수 없습니다. (KISA 측에서 제보해주신 내용을 확인하는 과정에서 함께 발견했습니다 — KVE-2026-1679)
+- 보안 환경설정의 계정 잠금 시간을 `0`(무한대)으로 설정하면 실제로 무기한 잠기도록 수정했습니다. 화면 안내는 "0을 입력하면 무한대"였지만 실제로는 1분 뒤 자동 해제되어, 무차별 대입 시도를 영구 차단할 수 없었습니다. 무기한 잠긴 계정에는 남은 시간 대신 관리자 문의 안내가 표시됩니다. (#81 @jiwonpapa 님께서 제보해주셨습니다.)
+- 환경설정 > 보안에 비밀번호 최소 길이와 특수문자 필수 여부를 추가했습니다. 두 항목은 설정 화면에만 있고 실제로는 어디에도 적용되지 않던 값으로, 이제 비밀번호를 새로 정하는 모든 화면(회원가입·비밀번호 변경·재설정·프로필 수정·관리자의 회원 등록과 수정)에 적용됩니다. 로그인에는 적용하지 않습니다 — 정책을 올렸을 때 기존 비밀번호를 쓰는 회원이 자기 계정에 로그인조차 못 하게 되는 것을 막기 위함입니다. (#81 @jiwonpapa 님께서 제보해주셨습니다.)
+- 본인인증 메일의 인증번호 자리수 설정이 4~10 범위를 벗어나면 조용히 잘려 저장 값과 다르게 동작하던 문제를 수정했습니다. 이제 허용 범위가 설정 화면에 표시되고, 범위를 벗어난 값은 기본값(6자리)으로 처리하며 기록을 남깁니다. (#81 @jiwonpapa 님께서 제보해주셨습니다.)
+- 환경설정 > 보안의 로그인 시도 제한 항목에 IP 단위 요청 제한이 어떻게 계산되는지(설정값의 6배, 분당 최소 30회 보장) 안내를 추가했습니다. (#81 @jiwonpapa 님께서 제보해주셨습니다.)
+- 환경설정 > 업로드의 최대 파일 크기와 허용 파일 형식이 실제 업로드에 적용되도록 수정했습니다. 이전에는 설정을 바꿔도 어느 경로에서도 반영되지 않아, 허용 형식 목록에 없는 확장자(예: `.php`)도 업로드할 수 있었습니다. 허용 형식 목록을 비워 두면 종전처럼 형식을 제한하지 않습니다. (#81 @jiwonpapa 님께서 제보해주셨습니다.)
+- 허용 파일 형식을 저장해도 업로드 제한에 반영되지 않던 문제를 수정했습니다. 입력 칸은 `jpg,png,pdf` 처럼 쉼표로 구분한 한 줄이지만 적용 단계가 그 형태를 받아들이지 못해, 업로드 탭을 한 번이라도 저장하면 형식 제한이 저장 이전 목록으로 남았습니다. 저장은 성공하고 화면에도 값이 보여 어긋난 것을 알 방법이 없었습니다. 대문자나 앞의 점(`.JPG`, `.png`)은 자동으로 정리되며, 이미 저장되어 있던 값도 그대로 적용됩니다. (#81 @jiwonpapa 님께서 제보해주셨습니다.)
+- 업로드된 파일의 저장 확장자를 파일명이 아니라 파일 내용에서 판별하도록 바꿨습니다. 확장자만 바꿔 올린 파일이 원래 형식과 다르게 저장되던 문제가 해소됩니다. (#81 @jiwonpapa 님께서 제보해주셨습니다.)
+- 환경설정 > 본인인증의 '가입 후 본인확인' 정책을 켜면 회원가입 자체가 막혀 아무도 가입할 수 없던 문제를 수정했습니다. 이 정책은 가입은 받아들이고 계정을 '인증 대기' 상태로 둔 뒤 본인확인 안내를 보내는 설정인데, 안내를 보낸 직후 가입이 거절되어 '가입 전 본인확인' 정책과 구분이 없었습니다. 이제 설정한 대로 가입이 완료되고, 본인확인을 마치면 계정이 활성화됩니다. (안내 발송이 실패해도 가입은 유지되며 실패 사실은 기록에 남습니다.)
+- 보안 환경설정의 '2단계 인증'이 실제로 동작합니다. 이전에는 항목만 있고 켜도 아무 일이 일어나지 않아, 관리자는 2단계 인증이 걸린 줄 알지만 비밀번호 하나로 로그인됐습니다. 이제 켜 두면 비밀번호 확인 뒤 인증번호를 메일로 보내고, 그 번호를 확인해야 로그인이 완료됩니다. 번호를 확인하기 전에는 로그인 상태가 만들어지지 않습니다. 안내 메일 문구는 환경설정 > 본인인증에서 '로그인 2단계 인증' 목적을 골라 따로 지정할 수 있습니다. (#81 @jiwonpapa 님께서 제보해주셨습니다.)
+- 환경설정 > 업로드의 이미지 최대 가로/세로 크기와 품질이 실제 업로드에 적용됩니다. 이전에는 값을 저장해도 이미지를 줄이는 동작이 없어 원본이 그대로 저장됐습니다. 크기를 지정하지 않으면 종전처럼 줄이지 않으며, 지정한 크기 이내인 이미지는 다시 변환하지 않아 불필요한 화질 손실이 없습니다. (#81 @jiwonpapa 님께서 제보해주셨습니다.)
+- 회원 상세 화면에 계정 잠금 상태 표시와 잠금 해제 버튼을 추가했습니다. 무기한 잠긴 계정은 로그인 성공으로 풀 수 없으므로 관리자가 직접 해제할 수 있어야 합니다. 해제는 활동 로그에 남습니다. (사용자 수정 권한이 필요합니다.) (#81 @jiwonpapa 님께서 제보해주셨습니다.)
+
+### Added
+
+- 회원가입 시 휴대폰번호와 전화번호를 선택 항목으로 입력할 수 있습니다. 두 항목 모두 필수가 아니며, 입력하면 내 정보에서 확인·수정할 수 있습니다.
+
+#### 사이트맵
+
+- 게시글·상품이 수백만 건으로 늘어나도 사이트맵을 안정적으로 생성하도록 개선했습니다. 예전에는 사이트맵을 만들 때 전체 데이터를 한꺼번에 메모리에 올리다가 데이터가 많은 사이트에서 생성이 실패했지만, 이제 나눠 읽어 처리하므로 메모리 부족 없이 완성됩니다. (#79 @jiwonpapa 님께서 제보해주셨습니다.)
+- 사이트맵을 검색엔진 규격(파일당 5만 URL / 50MB)에 맞춰 여러 파일로 자동 분할하고, 이를 묶는 색인 파일을 함께 만듭니다. 한 파일에 담을 URL 수는 SEO 설정에서 조정할 수 있습니다.
+- 게시글·상품·페이지를 공개/비공개로 바꾸거나 삭제하면 사이트맵에서 해당 항목만 자동으로 더하거나 빼도록 바꿨습니다. 전체를 다시 만들지 않고 바뀐 부분만 반영하므로 항상 최신 상태가 빠르게 유지됩니다.
+- 검색엔진 봇이 사이트맵을 요청하면 미리 만들어 둔 파일을 그대로 내보내고, 요청을 받은 그 자리에서 새로 만들지 않도록 바꿨습니다. 아직 만들어진 사이트맵이 없으면 잠시 후 다시 요청하도록 안내하고 백그라운드에서 생성합니다.
+- 관리자 화면의 사이트맵 전체 재생성을 백그라운드 작업으로 처리하도록 바꾸고, 진행 상황(대기·생성 중·파일 작성·완료·실패)과 처리한 주소 수를 화면에서 확인할 수 있게 했습니다. 실시간 연결이 켜져 있으면 즉시 갱신되고, 꺼져 있으면 주기적으로 확인합니다.
+- 다국어 사이트를 위한 대체 언어 링크(hreflang)를 사이트맵에 넣을지 켜고 끌 수 있으며, 언어 수가 많을 때 링크가 과도하게 늘어나지 않도록 상한을 두었습니다.
+- 사이트맵의 갱신 빈도(changefreq) 값을 검색엔진 표준 어휘(always/hourly/daily/weekly/monthly/yearly/never)로 맞춰, 규격에 없는 값은 사이트맵에 출력되지 않도록 했습니다.
+- 관리자가 사이트맵 전체 재생성을 실행하면, 완료되거나 실패했을 때 실행한 관리자에게 알림을 보냅니다. 재생성이 오래 걸려 화면을 떠나 있어도 결과를 놓치지 않습니다. (기본은 앱 내 알림이며 관리자 알림 설정에서 이메일도 켤 수 있습니다. 매일 자동 생성이나 글·상품 변경에 따른 재생성은 알림을 보내지 않습니다.)
+
+#### 설치·서버 환경
+
+- 설치할 때 `root` 같은 데이터베이스 최고 권한 계정을 입력하면 설치가 진행되지 않고, 왜 사용할 수 없는지와 어떻게 해야 하는지를 함께 안내합니다. 최고 권한 계정 정보가 유출되면 데이터베이스 전체가 위험해지기 때문이며, 사이트 전용 데이터베이스 계정을 새로 만들어 필요한 권한만 부여해 입력하시면 됩니다. 읽기 전용 데이터베이스를 따로 쓰는 경우에도 동일하게 적용됩니다.
+- 일부 서버 설정에서 모든 페이지가 백지로 나오던 문제에 대응했습니다. 서버에 `.js`·`.css`·`.json` 주소를 가로채는 정적 파일 최적화 설정(aaPanel·CyberPanel·Plesk 기본 템플릿 등)이 있으면 G7 의 일부 주소가 PHP 에 전달되지 못해 화면이 뜨지 않았습니다. 이제 G7 이 확장자 없는 주소도 함께 제공하며, 화면이 뜨지 않으면 브라우저가 이를 감지해 자동으로 전환하므로 서버 설정을 바꾸지 않아도 사이트가 표시됩니다. (sir.kr 커뮤니티의 hang 님께서 제보해주셨습니다.)
+- 자산 파일 주소 방식을 설치 마법사가 자동으로 감지해 반영하고, 설치 후에도 관리자 > 환경설정 > 일반에서 바꿀 수 있습니다. 설치 2단계 서버 요구사항 화면에서 감지 결과를 미리 확인할 수 있고, 3단계에서 직접 고를 수도 있습니다. 화면이 아예 뜨지 않는 상황을 위해 `php artisan g7:asset-url-mode` 명령으로도 확인·전환할 수 있습니다. 검색엔진 봇은 자바스크립트를 실행하지 않으므로, 이 설정을 확정해 두면 봇에게도 올바른 주소가 전달됩니다.
+- 서버에 OPcache가 켜져 있는지를 설치 화면과 관리자 환경설정 > 정보에서 확인할 수 있습니다. OPcache는 PHP 코드 해석 결과를 재사용해 사이트 응답 속도를 크게 높여 주는 기능으로, 꺼져 있으면 성능이 떨어진다는 안내와 함께 설정 방법을 알려 드립니다. 꺼져 있어도 설치는 그대로 진행되므로 설치가 막히지 않습니다.
+
+#### 언어팩
+
+- 사이트에서 쓰기로 한 언어의 언어팩을 한 번에 채워 넣는 기능을 추가했습니다. 한국어·영어 외 언어(일본어 등)는 설치되어 있어야 화면에 표시되는데, 설치가 빠져 있으면 오류 없이 한국어로 대체되어 운영자가 눈치채기 어려웠습니다. 이제 언어팩 관리 목록과 명령으로 "설치가 필요한 언어"를 한 번에 채울 수 있고, 여러 번 실행해도 안전합니다.
+- 언어팩 관리 목록이 "설치되어 있다고 표시되지만 실제 파일이 없어 다른 언어로 대체되는" 상태를 눈에 띄게 보여주고, 그 자리에서 다시 설치할 수 있는 버튼을 제공합니다. 예전에는 목록에 정상으로 보이는데도 실제로는 번역이 적용되지 않는 경우를 발견하기 어려웠습니다. 파일이 사라진 언어팩은 화면의 다시 설치 버튼으로도, 언어팩을 채우는 명령으로도 복구할 수 있습니다.
+
+#### 목록 성능
+
+- 검색 인덱스가 실제로 내용을 담고 있는지 점검하고, 비어 있으면 다시 만들 수 있는 기능을 추가했습니다. 인덱스가 비면 검색은 오류 없이 "결과 없음" 만 돌려주기 때문에 그동안은 알아차릴 방법이 없었습니다. 관리자 > 개발 도구에서 「검색 인덱스 점검」 으로 확인할 수 있고, `php artisan search:index` 로도 실행됩니다. 점검·재생성 방식은 검색 엔진마다 다르므로, 다른 검색 엔진을 쓰는 확장도 자기 방식의 점검을 등록해 같은 화면에서 함께 다룰 수 있습니다.
+- 다시 만들기는 **선택할 때만** 실행됩니다. 인덱스를 다시 만드는 동안에는 해당 인덱스가 잠기거나 전체 재색인이 일어나 운영 중인 사이트에 영향을 주기 때문입니다. 확장·코어 업데이트 화면과 명령어에 「업데이트 후 검색 인덱스 재생성」 선택 항목을 두었고, 선택하지 않아도 색인이 비어 있으면 그 사실은 알려 드립니다. 사이트 규모가 크다면 선택하지 말고 접속이 적은 시간에 따로 실행하시길 권합니다.
+- 업데이트 화면의 「검색 인덱스 재생성」 선택이 그 창에서만 유효하도록 바로잡았습니다. 예전에는 한 번 선택하면 창을 닫거나 업데이트를 마친 뒤에도 선택이 남아 있어, 다음 확장을 업데이트할 때 아무것도 고르지 않았는데 인덱스 재생성이 다시 실행됐습니다.
+- 확장을 업데이트하면 색인이 비어 있는 검색 인덱스가 있는지 결과가 함께 전달되도록 바로잡았습니다. 예전에는 점검은 이루어졌지만 그 결과가 화면까지 오지 않아 운영자가 알 수 없었습니다.
+- 모듈·플러그인 업데이트 완료 안내에 확장 이름과 버전이 표시되지 않던 문제를 수정했습니다.
+- 모듈·플러그인 목록의 총 개수와 페이지 이동이 동작하지 않던 문제를 수정했습니다. 설치된 확장이 12개를 넘으면 2페이지 이후 항목이 화면에 나타나지 않았습니다.
+- `php artisan module:check-updates` 등 업데이트 확인 명령이 업데이트가 있는 확장을 「최신」 으로 표시하고 요약도 "업데이트 가능 0개" 로 알리던 문제를 수정했습니다.
+- 통신이 끊겨 요청이 전송되지 못했을 때 내부 식별 문구가 그대로 표시되던 것을 네트워크 오류 안내로 바꿨습니다.
+- 개발 도구에서 점검 명령이 이상을 발견해 알려 준 경우를 「실행 실패」 로 표시하던 것을 종료 코드 안내로 바꿨습니다. 점검은 정상 수행된 것이며, 발견된 내용은 출력에 그대로 표시됩니다.
+
+- 목록 화면이 뒤쪽 페이지로 갈수록 느려지는 문제를 구조적으로 해결할 수 있도록, 확장이 함께 쓸 수 있는 공통 조회 방식을 코어에 추가했습니다. 목록을 두 단계(먼저 이번 페이지에 해당하는 항목만 추려내고, 그 항목에 대해서만 본문·상세 정보를 읽기)로 나눠 읽으므로 게시글·주문·로그가 수십만 건으로 늘어나도 마지막 페이지 조회 비용이 첫 페이지와 비슷하게 유지됩니다. 목록 정렬 기준을 미리 정해 둔 항목으로만 해석하는 공통 처리도 함께 제공하므로, 확장이 목록 조회를 직접 만들 때 정렬 처리를 매번 새로 구현하지 않아도 됩니다. 주문 목록의 「발송일」처럼 정렬 기준이 다른 표에 있는 값일 때도 총 건수와 페이지 경계가 어긋나지 않게 조회하는 공통 처리를 함께 넣었습니다. (#74 @jiwonpapa 님께서 제보해주셨습니다.)
+
+#### 대용량 목록
+
+- 검색 결과나 목록이 아주 많을 때 화면이 열리지 않거나 서버가 멈추던 문제를 개선했습니다. 이제 총 건수는 일정 규모까지만 정확히 세고 그보다 많으면 "10,000건 이상" 처럼 표시하며, 다음 페이지로 넘기는 것은 끝까지 그대로 됩니다. 마지막 페이지로 바로 뛰는 버튼만 이때 감춰집니다 — 그 위치를 계산하려면 전체를 세야 하기 때문입니다. (#82 @jiwonpapa 님께서 제보해주셨습니다.)
+- 총 건수를 세는 범위와 주소로 직접 요청할 수 있는 최대 페이지 번호를 관리자 > 환경설정 > 고급에서 조정할 수 있습니다. 두 값 모두 0 으로 두면 제한하지 않습니다.
+- 검색 결과가 많아 총 건수를 정확히 세지 못한 경우, 검색어를 더 구체적으로 입력하면 정확한 건수를 볼 수 있다는 안내를 함께 표시합니다.
+- 활동 로그·알림 발송 기록·본인인증 기록·스케줄 실행 이력·회원 목록에도 같은 방식을 적용했습니다. 기록이 수십만 건 쌓여도 목록 첫 화면이 총 건수를 세는 비용에 끌려가지 않습니다.
+- 알림함도 같은 방식으로 조회합니다. 알림이 오래 쌓인 계정에서도 목록이 빠르게 열립니다.
+- 알림 발송 기록을 최신순으로 볼 때 뒤쪽 페이지를 이동하는 방식이 활동 로그와 동일해졌습니다. 몇 페이지를 넘겨도 속도가 일정하게 유지됩니다.
+- 검색 결과 화면에서 다른 분류의 건수 배지가 필요 없을 때는 그 숫자를 세는 작업을 건너뛸 수 있습니다.
+- 검색 결과의 탭 배지(게시글 N · 상품 N · 페이지 N)도 세지 못한 건수를 정확한 것처럼 표시하지 않습니다. 탭을 열어 본 목록과 배지의 숫자가 서로 다른 기준을 말하던 문제가 사라집니다.
+- 활동 로그 목록을 페이지 번호 대신 이어보기 방식으로도 조회할 수 있습니다. 기록이 많이 쌓인 사이트에서 뒤쪽으로 갈수록 느려지지 않습니다. 화면 동작은 그대로이며, 필요할 때만 쓰는 선택지입니다.
+- 통합 검색도 최신순·조회순·가격순처럼 목록 자체의 순서로 볼 때는 이어보기 방식으로 뒤쪽 페이지를 이동할 수 있습니다. 검색 결과가 아주 많아도 몇 페이지를 넘기든 속도가 일정합니다. 관련도순은 계산된 점수로 정렬하므로 종전의 페이지 번호 방식을 유지합니다. (#82 @jiwonpapa 님께서 제보해주셨습니다.)
+
+#### 성능 점검
+
+- 확장이 자기 성능 측정 대상을 직접 등록할 수 있게 했습니다. 모듈·플러그인이 자신의 목록 화면, 관리자 화면, 저장 동작, 정기 작업 중 속도를 재고 싶은 것을 선언해 두면, 사이트 관리자가 성능 점검을 실행할 때 코어 항목과 함께 측정됩니다. 확장을 설치하면 그 확장의 측정 대상이 자동으로 목록에 나타나고, 제거하면 함께 사라집니다. 화면 측정은 응답 시간과 함께 그 화면이 실행한 데이터베이스 조회 횟수를 보여주므로, 목록 자체는 빠른데 화면이 느린 원인을 찾을 수 있습니다.
+
+### Changed
+
+- 레이아웃 편집기의 파일 목록·버전 이력·확장 목록이 목록에 필요한 정보만 받아오도록 바꿨습니다. 예전에는 목록 한 번에 그 템플릿의 모든 레이아웃 본문과 버전마다의 본문 사본까지 함께 실려, 레이아웃이 많거나 저장을 자주 한 템플릿일수록 편집기 진입이 느려졌습니다. 편집 본문은 파일을 선택할 때 받아오므로 화면에 보이는 내용은 이전과 동일합니다. 버전 이력은 최근 100건까지 표시하며, 더 필요하면 조회 건수를 지정할 수 있습니다. (#76 @jordy-bitree 님께서 제보해주셨습니다.)
+- 역할 관리 목록과 메뉴 관리 목록이 화면에서 쓰지 않는 정보를 함께 내려주던 것을 정리했습니다. 역할 목록은 권한 전체 목록을 세 가지 형태로 중복해서, 메뉴 목록은 하위 메뉴마다 역할 정보를 함께 싣고 있었습니다. 역할의 권한은 역할 수정 화면에서 종전대로 확인·편집할 수 있습니다. (#76 @jordy-bitree 님께서 제보해주셨습니다.)
+- 레이아웃 버전 목록 조회에 건수 제한을 두었습니다. 허용 범위를 벗어난 값을 지정하면 안내 문구가 표시됩니다. 버전 이력의 '더 보기'는 조회 상한에 이르면 더 넓히지 않습니다. (#76 @jordy-bitree 님께서 제보해주셨습니다.)
+- 알림 정의 목록이 지금 보고 있는 채널의 템플릿만 받아오도록 바꿨습니다. 예전에는 정의마다 모든 채널의 제목과 본문이 함께 실려, 채널을 여러 개 쓰는 사이트일수록 목록이 무거웠습니다. 채널을 지정하지 않고 목록을 조회하면 템플릿 본문은 함께 오지 않으며, 전체 채널의 내용이 필요하면 정의 단건 조회를 이용하면 됩니다. 화면에 보이는 내용과 '되돌리기' 버튼 표시 조건은 이전과 동일합니다. (#76 @jordy-bitree 님께서 제보해주셨습니다.)
+- 본인인증 메시지 정의 목록이 대표 템플릿 한 건만 받아오도록 바꿨습니다. 전체 템플릿은 정의를 열었을 때 종전대로 받아옵니다. (#76 @jordy-bitree 님께서 제보해주셨습니다.)
+- 역할 목록에 할당된 권한 개수를 함께 표시할 수 있도록 집계 값을 제공합니다. 권한 목록 자체를 싣지 않고도 규모를 확인할 수 있습니다. (#76 @jordy-bitree 님께서 제보해주셨습니다.)
+- 페이지를 한 번 열 때마다 서버가 되풀이하던 준비 작업을 정리했습니다. 내부 동작 기록을 매 요청 400줄씩 남기던 부분, 환경설정 파일을 한 요청에서 스무 번 넘게 다시 읽던 부분, 이미 저장해 둔 목록을 매번 데이터베이스에서 다시 가져오던 부분을 없앴습니다. 화면에 보이는 내용은 그대로이며 응답이 빨라집니다. (#82 @jiwonpapa 님께서 제보해주셨습니다.)
+- 권한 확인이 화면 요소마다 데이터베이스를 다시 조회하던 것을 요청당 한 번으로 줄였습니다. 메뉴·버튼이 많은 화면일수록 체감 차이가 큽니다. 권한을 바꾸면 종전처럼 다음 요청부터 즉시 반영됩니다. (#82 @jiwonpapa 님께서 제보해주셨습니다.)
+- 게시글·상품·쿠폰 검색이 조건에 맞는 항목 전체를 먼저 메모리에 올린 뒤 다시 조회하던 방식을 없앴습니다. 검색 결과가 아주 많아도 메모리 사용량이 늘지 않습니다. (#82 @jiwonpapa 님께서 제보해주셨습니다.)
+- 플러그인으로 다른 검색엔진을 연결했을 때 게시판·상품·페이지 검색이 그 엔진을 쓰지 않고 기본 방식으로 동작하던 문제를 해소했습니다. 이제 연결한 검색엔진이 모든 검색 화면에 적용됩니다. 전문검색을 제공하지 않는 데이터베이스에서도 검색어의 `%` `_` 같은 기호를 입력한 글자 그대로 찾도록 개선했습니다.
+- 기간으로 걸러 보는 목록(주문·회원·쿠폰·스케줄 등)의 날짜 조건을 색인을 활용하는 방식으로 바꿨습니다. 기록이 많은 사이트에서 기간 검색이 빨라집니다.
+- 설치 직후 기록 수준(`LOG_LEVEL`) 기본값을 운영 기준(`error`)으로 바꿨습니다. 이전 기본값은 정상 동작까지 모두 기록해 로그 파일이 빠르게 커졌습니다. 관리자 > 환경설정 > 고급에서 조정할 수 있으며, 그 값이 이 항목보다 우선합니다.
+- 권장 서버 사양(CPU·메모리)을 시스템 요구사항 문서에 추가했습니다.
+
+- 활동 로그·알림 발송 이력·본인인증 기록·스케줄 실행 이력·회원 목록을 뒤쪽 페이지에서도 빠르게 열 수 있도록 조회 방식을 바꿨습니다. 예전에는 페이지가 뒤로 갈수록 건너뛰는 기록의 본문·변경 내역까지 함께 읽어 느려졌지만, 이제 현재 페이지에 해당하는 기록만 상세 정보를 읽습니다. 화면에 보이는 내용은 이전과 동일합니다. (#74 @jiwonpapa 님께서 제보해주셨습니다.)
+- 확장이 업로드 허용 형식을 넓힐 수 있도록 `core.attachment.allowed_extensions` 필터를 추가했습니다. 관리자 설정 목록을 기준으로, 확장이 자기 기능에 필요한 형식만 덧붙일 수 있습니다.
+- 활동 로그·알림 발송 이력·회원 목록의 정렬 색인을 정비했습니다. 같은 시각에 쌓인 기록이 많은 구간에서 순서를 정하느라 생기던 추가 작업이 사라져, 기록이 많은 사이트일수록 목록이 빨라집니다. 기존 사이트도 업데이트 시 자동으로 반영되며, 기록이 아주 많은 경우 이 과정에 수 분이 걸리고 그동안 해당 기록의 저장이 잠시 대기할 수 있습니다.
+- 확장이 검증 규칙을 추가할 때 쓰는 필터 이름 10개를 나머지 92개와 같은 규칙(`{대상}.{동작}_validation_rules`)으로 통일했습니다. 본인인증 메시지와 알림 관련 화면이 대상이며, 예전 이름(`...filter_index_rules` 형태)을 사용하던 확장은 새 이름으로 바꿔야 검증 규칙 추가가 계속 동작합니다. 코어와 기본 제공 확장에는 이 이름을 사용하던 곳이 없어 영향이 없습니다.
+- 같은 규칙에서 벗어나 있던 필터 이름 6개(플러그인 설정 저장, 비밀번호 재설정 토큰 확인, 비밀번호 확인, 변경사항 조회, 통합 검색, 프로필 사진 업로드)를 추가로 통일했습니다. 이번에는 예전 이름도 함께 계속 발행하므로 기존 확장은 수정 없이 그대로 동작하며, 예전 이름을 사용 중인 확장이 있으면 서버 기록에 한 번 안내가 남습니다. 새로 만드는 확장은 새 이름을 사용하세요.
+
+### Fixed
+
+#### 화면 동작
+
+- 화면에서 선택·클릭 같은 동작에 반응하도록 지정한 항목이 아무 반응도 하지 않던 문제를 수정했습니다. 오류나 경고 없이 조용히 동작하지 않아 원인을 찾기 어려웠습니다. 게시판 글쓰기의 분류 선택이 이에 해당해, 분류를 골라도 글에 반영되지 않았습니다. 함께, 반응은 하되 선택한 값만 비어 저장되던 경우도 수정했습니다.
+- 화면에서 고른 값이 모듈·플러그인이 제공하는 동작에는 전달되지 않던 문제를 수정했습니다. 값을 저장하는 방식이 두 가지인데 그중 한 가지로 저장하면 화면에는 선택한 것으로 표시되지만 확장 기능은 그 값을 읽지 못했고, 오류나 경고가 남지 않아 화면만 봐서는 알 수 없었습니다. 이제 어느 방식으로 저장하든 같은 값이 전달됩니다.
+
+#### 레이아웃 코드 편집
+
+- 레이아웃 코드 편집 화면이 파일 목록을 불러올 때 편집하지 않는 레이아웃의 본문까지 전부 내려받던 문제를 수정했습니다. 레이아웃이 많은 템플릿에서는 목록을 여는 것만으로 수십 MB가 브라우저에 쌓여 화면이 크게 느려지거나, 디버그 모드에서는 탭이 메모리 부족으로 종료됐습니다. 이제 목록에는 이름·설명·크기·수정일만 실리고 본문은 선택한 파일만 불러옵니다.
+
+#### 화면 편집기
+
+- 화면 편집기가 주소 일부를 설정으로 바꿀 수 있는 화면도 알아보도록 화면 인식 방식을 넓혔습니다. 예를 들어 쇼핑몰은 주소를 바꾸거나 주소 없이 운영할 수 있는데, 편집기는 주소가 한 토막 있는 경우만 인식해 그 외의 사이트에서는 해당 화면의 상태 미리보기 전환이 표시되지 않았습니다. 이제 확장이 "이 토막은 있을 수도 없을 수도 있다"고 알려 줄 수 있으며, 함께 배포되는 쇼핑몰에 이미 적용되어 있습니다.
+
+#### 설정 화면 입력
+
+- 설정 화면에서 여러 입력칸을 고친 뒤 다른 탭에 갔다 돌아오면, 먼저 고친 칸에 입력했던 값이 그대로 남던 문제를 수정했습니다. 저장된 값은 원래 값이라 화면에 보이는 값과 실제 값이 어긋났고, 새로고침해야 드러났습니다. 이제 탭을 오갈 때 모든 입력칸이 저장된 값으로 함께 돌아옵니다.
+
+#### 확장 업데이트
+
+- 속도 최적화를 적용한 사이트에서, 확장을 설치·활성화·업데이트해도 그 확장이 새로 추가한 주소가 동작하지 않던 문제를 수정했습니다. 예전에는 최적화 시점에 저장해 둔 주소 목록만 사용해 새 주소가 목록에 없었고, 화면에는 오류 대신 "페이지를 찾을 수 없음"만 나와 원인을 알기 어려웠습니다. 이제 확장을 설치·활성화·비활성화·삭제·업데이트할 때와 코어 업데이트 후에 주소 목록이 자동으로 다시 만들어집니다.
+- 코어를 업데이트하면 주소 목록 최적화가 꺼진 채로 남던 문제를 함께 수정했습니다. 업데이트 도중 목록을 비우기만 하고 다시 만들지 않아, 관리자가 직접 '시스템 최적화'를 실행할 때까지 사이트가 최적화 없이 동작했습니다.
+- 모듈·플러그인 업데이트에서 '수정 유지'를 선택해도 직접 고친 화면이 새 버전으로 덮어써지던 문제를 수정했습니다. 업데이트 과정이 보존 여부를 판단하기 전에 모든 화면을 파일 기준으로 먼저 되돌려, 비교할 수정본이 남지 않아 '수정 유지'가 항상 무효가 됐습니다. 이제 선택한 대로 수정한 화면이 그대로 유지됩니다.
+- 업데이트 전 표시되는 "수정된 레이아웃" 안내가 확인에 실패했을 때도 "수정된 레이아웃이 없습니다"라고 단언하던 문제를 수정했습니다. 네트워크가 끊긴 상태에서 그대로 '모두 교체'를 진행하면 직접 고친 화면이 사라질 수 있었습니다. 이제 확인하지 못했다는 사실과 함께 '수정 유지' 권장 안내가 표시됩니다.
+- 템플릿 업데이트 안내가 그 템플릿에 등록된 모듈·플러그인 화면의 수정까지 자기 것으로 세던 문제를 수정했습니다. 실제로 교체·보존되는 대상은 템플릿 자신의 화면뿐이라 표시 건수와 실제 동작이 어긋났습니다.
+- '업데이트 확인' 버튼을 눌러 업데이트가 발견돼도 항상 "모두 최신 상태입니다"라고 안내되던 문제를 수정했습니다. 모듈·플러그인·템플릿 관리 화면 모두에 해당합니다.
+- 업데이트 완료 안내에 확장 이름과 버전이 표시되지 않고 자리표시자 글자가 그대로 노출되던 문제를 수정했습니다.
+- 모듈·플러그인·템플릿 관리 화면의 목록 요약이 항상 "총 0개 중 1-0개 표시"로 나오고, 목록이 한 화면을 넘어도 다음 쪽으로 넘어갈 수 없던 문제를 수정했습니다.
+- 존재하지 않는 확장 이름으로 수정 화면 확인을 요청하면 "수정된 화면 없음"으로 응답하던 것을 "찾을 수 없음"으로 구분해 응답하도록 바꿨습니다.
+
+#### 관리자 화면
+
+- 템플릿 레이아웃 편집 화면의 파일 목록에서 이름·설명이 빈칸으로 보이던 문제를 수정했습니다. 번역 제외 표기를 쓴 글자가 화면 구성 요소의 본문 자리에서만 해석되지 않아 아무것도 출력되지 않았습니다.
+- 번역 제외 표기를 쓴 글자가 검색엔진 봇 화면에서 해석되지 않던 문제를 함께 수정했습니다. 일반 화면에는 값이 나오는데 봇 화면에서만 비어 보일 수 있었습니다.
+
+#### 검색엔진 봇 화면
+
+- 검색엔진 봇에게만 게시글·답글의 원글·댓글·페이지·상품 설명의 본문이 통째로 빈 채 전달되던 문제를 수정했습니다. 위지윅 편집기 플러그인이 켜져 있으면 본문 영역이 플러그인 화면으로 교체되는데, 봇용 화면을 만드는 쪽이 그 교체 규칙을 몰라 내용 없는 껍데기만 만들었습니다. 미리보기용 요약(메타 태그)에는 본문이 들어가 있어 겉으로는 정상으로 보였습니다. 이제 일반 화면과 봇용 화면이 같은 본문을 출력합니다. 업그레이드 시 이미 만들어져 있던 봇용 화면은 한 번 비워져 새로 만들어집니다. (#86 @koojunho 님께서 제보해주셨습니다.)
+- 봇용 화면이 자료를 불러오는 주소에 검색어 같은 값을 끼워 넣어 둔 경우, 그 값이 해석되지 않아 목록이 통째로 비어 있던 문제를 수정했습니다. 예전에는 주소 안의 글 번호만 해석했고 검색어·화면 초기값은 그대로 남아 조회에 실패했습니다.
+- 봇용 화면이 일반 화면과 다르게 해석하던 문법들을 일반 화면과 동일하게 맞췄습니다. 여러 조건을 묶은 표시 조건, 반복 목록의 다른 표기 방식, 글자만 넣은 조각, 데스크톱 전용으로 지정한 하위 구성·반복 목록, 지연 표기한 번역, 화면 시작 시 정해지는 초기값이 해당됩니다. 조건이 거짓인데도 내용이 노출되거나, 화면에는 보이는 내용이 봇에게만 사라지던 차이가 없어집니다.
+- 봇용 화면에서 값 대신 `true`/`false` 가 출력되던 문제를 수정했습니다. 두 값 중 채워진 쪽을 쓰는 표기(`||`)가 값이 아니라 참·거짓으로 계산되어, 검색 화면 주소에 검색어 대신 `true` 가 들어가는 등의 증상이 있었습니다. 화면에 넣은 값이 참·거짓이거나 비어 있을 때도 봇용 화면에만 `false` 같은 글자가 그대로 노출되던 문제를 함께 수정했습니다.
+- 검색엔진 봇용 화면에 넣는 사용자 작성 본문을 일반 화면과 같은 기준으로 정리하도록 수정했습니다. 예전에는 봇용 화면에만 본문이 아무 검사 없이 들어가, 글에 넣어 둔 스크립트나 외부 프레임이 봇용 주소로 접속했을 때 실제로 실행될 수 있었습니다. 또 서식 없이 글자로만 저장한 글의 태그가 봇용 화면에서만 서식으로 해석되어 두 화면의 본문이 달라 보였습니다. 이제 서식 없는 글은 글자 그대로, 서식 있는 글은 위험한 요소를 걷어낸 뒤 표시되며, 일반 화면과 결과가 같습니다. 게시글·답글·페이지·상품 설명 모두에 적용됩니다.
+- 봇용 화면의 선택 상자(정렬·분류 등)에 항목 이름 대신 내부 식별자가 글자로 노출되던 문제를 수정했습니다. 이제 일반 화면과 같이 선택 항목의 이름이 표시됩니다.
+- 봇용 화면에만 일반 화면에 없는 내용이 나타나거나, 반대로 있어야 할 내용이 사라지던 경우를 정리했습니다. 값이 비어 있을 때 대신 다른 내용을 채워 넣던 동작, 화면 폭 조건이 여러 개 겹칠 때 적용 순서가 달라지던 동작, 알아볼 수 없는 형태의 표시 조건을 봇용 화면에서만 숨기던 동작이 해당됩니다.
+
+#### 화면 표시·목록 상태
+
+- 건수가 아주 많아 총 건수를 끝까지 세지 못하는 목록에서 항목 번호가 0 이나 음수로 표시되던 문제를 수정했습니다. 번호를 지어내지 않고 「-」로 표시하며, 총 건수를 정확히 센 목록의 번호는 종전과 동일합니다.
+- 활동 로그 목록의 총 건수가 끝까지 세지 못한 값인데도 정확한 숫자처럼 표시되던 문제를 수정했습니다. 이제 그 경우 「이상」 표시가 함께 나옵니다.
+
+- 목록 표의 각 칸에 넣은 날짜·숫자 서식이 적용되지 않아 값이 비어 보이던 문제를 수정했습니다. 같은 서식을 일반 화면에서 쓰면 정상이었지만 목록 표의 칸 안에서는 값이 사라지거나(날짜 서식) 서식이 빠진 원래 값이 그대로 나왔습니다(숫자·대문자 서식). 목록 표와 카드 목록, 펼침 영역 등 반복해서 그려지는 모든 자리에서 서식이 정상 적용됩니다. (#87 @glitter-gim 님께서 제보해주셨습니다.)
+- 위 문제와 같은 뿌리에서 비롯된 화면 표시 오류를 함께 정리했습니다. 같은 방식으로 작성한 값이 어디에 놓이느냐(목록 칸·본문·표시 조건·버튼 동작)에 따라 다르게 해석되던 것을 한 가지 기준으로 통일했으며, 아래 항목이 그 결과입니다. 대부분 오류 메시지 없이 값이 비거나 잘못 보이던 증상이라 눈치채기 어려웠습니다.
+- 행마다 달라지는 조건(예: "활성 상태인 항목만 표시")을 목록에 걸면 해당하는 행만 걸러지지 않고 **목록 전체가 사라지던** 문제를 수정했습니다. 이제 행마다 조건을 따져 표시하며, 검색엔진 봇이 보는 화면에도 같은 규칙이 적용됩니다.
+- 관리자 목록의 여러 개 고를 수 있는 상태·분류 필터처럼 항목 이름에 대괄호가 들어가는 값이 화면에 따라 비어 보이던 문제를 수정했습니다. 선택한 조건이 화면에 표시되지 않거나 조건 표시가 사라지던 증상이 해소됩니다.
+- 값 하나를 계산하다 실패하면 그 값이 속한 영역 전체가 그려지지 않던 문제를 수정했습니다. 이제 문제가 된 자리만 비고 나머지는 정상 표시됩니다.
+- 계산식에 날짜·숫자 서식을 함께 걸면 원본 값이 바뀌어도 처음 계산된 값이 계속 표시되던 문제를 수정했습니다.
+- 목록 칸이나 합계 행 안에서 번역 문구가 문장 중간에 들어간 경우 번역되지 않고 원본 키가 그대로 보이던 문제, 그리고 일부 표시 값에 `{{ }}` 기호가 섞여 나오던 문제를 수정했습니다.
+- 목록 칸이나 합계 행에서 '번역하지 않고 원문 그대로 표시'로 지정한 값에 보이지 않는 특수문자가 함께 출력되던 문제를 수정했습니다. 화면에서는 빈칸이나 깨진 글자로 보였고, 값을 복사해 붙여넣을 때 따라붙었습니다.
+- 목록 표·카드의 셀에서 `true`/`false` 같은 값을 직접 쓴 자리가 비어 보이던 문제를 수정했습니다. 같은 값을 표시 조건에 쓰면 정상 동작해서, 같은 작성이 놓인 자리에 따라 갈렸습니다.
+- 레이아웃 코드 편집 화면의 파일 목록과 선택한 파일 설명에 번역되지 않은 내부 표기(`$t:…` 나 `{{ … }}`)가 그대로 보이던 문제를 수정했습니다. 다른 템플릿의 레이아웃을 편집할 때 그 템플릿의 번역을 찾지 못해 생긴 문제로, 이제 해당 템플릿의 번역으로 표시하며 번역을 찾을 수 없으면 파일 이름을 대신 보여줍니다.
+- 목록 화면에서 글이나 항목을 열어 보고 돌아올 때 보고 있던 페이지·검색어·필터가 사라지던 문제를 화면 엔진 차원에서 함께 수정했습니다. '현재 주소의 조건을 유지한다'고 지정해도 덧붙일 값이 없으면 유지가 아예 동작하지 않아 조건이 통째로 사라지던 동작을 바로잡았습니다. (#75 @jiwonpapa 님께서 제보해주셨습니다.)
+
+#### 확장·데이터베이스 안정성
+
+- 관리자 역할 관리·언어팩 관리·알림 목록에서 같은 시각에 등록된 항목이 여러 건일 때, 페이지를 넘기면 같은 항목이 두 번 보이고 다른 항목은 아예 보이지 않던 문제를 수정했습니다. 이제 페이지를 모두 넘겨도 목록에 있는 항목이 빠짐없이 한 번씩만 나옵니다.
+- 메뉴 관리 목록에서 검색 조건을 하나도 걸지 않은 채 정렬만 바꾸면 순서가 그대로이던 문제를 수정했습니다. 검색 조건이 있을 때만 정렬이 반영되고 있었으며, 이제 조건 유무와 관계없이 선택한 정렬이 적용됩니다.
+- 메뉴 관리 검색에서 한글 메뉴명으로 찾으면 결과가 나오지 않던 문제를 수정했습니다. 이제 한국어·영어 어느 쪽 메뉴명으로도 검색되고, 이름 정렬도 화면에 보이는 글자 기준으로 정렬됩니다.
+- 목록의 열 제목을 눌렀을 때 지금 보고 있는 페이지의 줄만 순서가 바뀌면서 전체가 정렬된 것처럼 보이던 문제를 수정했습니다. 페이지를 나눠 불러오는 목록에서 열 제목 정렬을 지원하지 않는 화면은 이제 정렬 표시를 띄우지 않으므로, 정렬 결과를 잘못 읽을 일이 없습니다. 정렬은 화면 위쪽의 정렬 선택으로 이용할 수 있습니다.
+- 언어팩 관리 목록이 모듈의 내장 번역을 실제 화면에 쓰이지 않는 위치 기준으로 보여주던 문제를 수정했습니다. 그 결과 일부 모듈의 한국어·영어 내장 번역이 목록에 아예 나오지 않았고, 번역 대상으로 표시된 문구를 고쳐도 화면에 반영되지 않았습니다. 이제 목록과 실제 화면의 문구 출처가 같습니다.
+- 데이터베이스 연결이 일시적으로 끊기거나 확장 설치가 중간에 실패한 직후 확장 목록을 다시 만들면, 설치된 모듈·플러그인 정보가 통째로 비워지면서 게시판·쇼핑몰 등 모든 확장 화면이 500 오류를 내던 문제를 수정했습니다. 이제 확장 폴더가 그대로 남아 있는데 목록만 비어 있으면 기존 정보를 지우지 않고 보존하며, 왜 갱신하지 않았는지 로그에 남깁니다.
+- 확장 목록이 손상된 상태에서 복구 명령을 실행하면 목록은 되살아나지만 확장 기능 연결이 비어 있는 채로 남아, 명령을 두 번 실행해야 완전히 복구되던 문제를 수정했습니다. 이제 한 번 실행으로 모두 복구됩니다.
+- 데이터베이스에서 일부 컬럼의 설명이 비어 있던 문제를 바로잡았습니다. 회원·작성자 등 다른 표를 가리키는 컬럼이 대상이며, 업그레이드하면 이미 운영 중인 데이터베이스에도 설명이 채워집니다(직접 적어 넣은 설명은 그대로 둡니다).
+- 본인인증 진행 상태를 조회하는 화면용 응답에 지금까지의 인증 시도 횟수가 함께 실려 나가던 것을 빼도록 바로잡았습니다. 원래 내보내지 않기로 한 값이며, 잠금 직전까지 시도 횟수를 맞춰 보는 데 쓰일 수 있었습니다. 화면 동작에는 영향이 없습니다.
+- 플러그인 설정 화면이 저장된 비밀값(암호화 키·API 시크릿 등)을 다시 내려받던 것을 가려서 표시하도록 바로잡았습니다. 값이 저장되어 있다는 표시만 보여주며, 그 항목을 건드리지 않고 저장하면 저장된 값이 그대로 유지됩니다.
+- 데이터베이스 계정 설정이 잘못되었을 때 아무 설명 없이 빈 화면만 뜨던 문제를 수정했습니다. 이전에는 최고 권한 계정을 쓰거나 사용자명이 비어 있으면 사이트 기능이 통째로 동작을 멈추면서도 화면에는 아무 안내가 없어 원인을 알 수 없었습니다. 이제 무엇이 잘못되었고 어떻게 고쳐야 하는지 설명하는 전용 안내 화면이 나타납니다. 서버 관리 명령은 평소대로 실행되므로 이 상태에서도 설정을 고칠 수 있습니다.
+- 모듈·플러그인의 연동 기능이 실행된 뒤로 같은 요청의 나머지 처리가 요청 정보를 잃어버리던 문제를 수정했습니다. 백그라운드 작업을 별도 프로세스로 돌리지 않는 설정에서 이 현상이 나타나, 뒤이어 실행되는 연동 기능이 필요한 정보를 찾지 못하고 조용히 건너뛰었습니다. 대표적으로 비회원 장바구니에 담아 두고 로그인하면 담은 상품이 사라졌습니다.
+- 모듈·플러그인 업데이트가 실패하거나 도중에 중단된 뒤, 확장은 정상인데 그 관리자 화면만 "페이지를 찾을 수 없습니다"로 나오고 하루가 지나야 돌아오던 문제를 수정했습니다. 업데이트가 진행되는 동안 사이트를 열어 본 사람이 있으면 그 순간의 "이 확장은 사용 중이 아님" 상태가 기억되는데, 실패로 끝나면 그 기억이 정리되지 않았습니다. 이제 실패로 끝나도 즉시 정리되며, 잘못된 상태가 애초에 기억되지 않도록 함께 보완했습니다.
+- 데이터가 많은 사이트를 업그레이드할 때 기존 데이터를 채워 넣는 작업이 일부 행을 건너뛰던 문제를 수정했습니다. 100건씩 나눠 처리하면서 처리한 행이 대상 목록에서 빠지는 만큼 다음 묶음의 시작 위치가 밀려, 250건이면 100건이 처리되지 않은 채 남았습니다. 레이아웃 원본 대조값 채우기와 `json:convert-unicode` 명령이 대상이며, 이제 건수와 무관하게 전건이 처리됩니다. (#84 @glitter-gim 님께서 제보해주셨습니다.)
+
+#### 개발자 도구
+
+- 디버그 모드에서 개발자 도구의 상태 내려받기가 오류를 내며 실패하던 문제를 수정했습니다. 모듈·플러그인을 설치하거나 켜고 끄면 사이트가 라우트 정보를 미리 만들어 두는데, 그 상태에서는 상태 내려받기 기능이 필요한 코드를 찾지 못했습니다. 확장을 한 번이라도 건드린 사이트에서는 항상 실패했습니다.
+- 같은 조건에서 브라우저 콘솔 로그 수집이 조용히 멈추던 문제를 수정했습니다. 로그를 받는 주소가 사라진 상태였는데 실패가 화면에도 기록에도 남지 않아, 디버그 모드를 켜 두었는데도 `storage/logs/browser.log` 만 비어 있었습니다.
+- 관리자 환경설정에서만 디버그 모드를 켰을 때(`.env` 는 꺼진 상태) 개발자 도구 요청이 접근 거부 대신 오류로 응답하던 문제를 수정했습니다.
+- 개발자 도구 응답 문구가 사이트 언어와 무관하게 항상 한국어로만 나오던 것을 사이트 언어를 따르도록 바꿨습니다.
+
+#### 설정 저장·입력 검증
+
+- 모듈·플러그인 설정의 숫자 항목이 숫자가 아닌 형태로 보관되어 있어도, 조회 시 설정 기본값과 같은 숫자 형태로 처리합니다. 이전에는 저장된 형태에 따라 기한 계산 같은 후속 처리에서 오류가 발생할 수 있었습니다. 숫자가 아닌 값, 참/거짓 항목, 목록 항목은 그대로 유지됩니다. 설정 안에 다시 묶여 있는 하위 항목까지 같은 규칙이 적용됩니다.
+- SEO 설정의 캐시 항목(SEO 캐시 사용·유지 시간, Sitemap 캐시 유지 시간)이 저장해도 적용되지 않던 문제를 수정했습니다. 이제 고급 설정의 캐시 값이 기준이 되고, SEO 설정에서 값을 지정하면 그 값이 우선하며, 비워두면 고급 설정을 따릅니다. 업그레이드 시 기존에 기본값과 다르게 지정해 두셨던 값은 그대로 살아나 이제부터 실제로 적용되므로 SEO 캐시 동작이 달라질 수 있습니다. 기본값 그대로였던 항목은 "지정 안 함"으로 정리되어 동작이 바뀌지 않습니다.
+- 한글로 쓴 설명이 글자 수 제한에 걸리지 않는데도 "너무 깁니다" 로 거부되던 문제를 수정했습니다. 글자 수를 바이트 단위로 세는 바람에 한글 한 글자가 세 글자로 계산되어, 500자 제한에서 167자만 넘어도 저장이 막혔습니다. 역할·권한·모듈·플러그인·템플릿 설명에 모두 해당합니다.
+- 사용하던 언어팩을 끈 뒤 기존에 작성해 둔 내용을 수정하려 하면 저장이 통째로 막히던 문제를 수정했습니다. 꺼진 언어로 입력해 둔 번역이 남아 있으면 "지원하지 않는 언어" 로 거부되었습니다. 이제 그 번역은 그대로 보존한 채 수정할 수 있고, 언어팩을 다시 켜면 번역도 함께 되살아납니다.
+- 알림 템플릿에서 제목을 비워 둘 수 있는데도 저장할 때 제목을 요구하던 문제를 수정했습니다. 제목 개념이 없는 발송 수단에서도 템플릿을 저장할 수 있습니다.
+- 알림 정의에 존재하지 않는 발송 수단 이름이 그대로 저장되던 문제를 수정했습니다. 이제 사용할 수 없는 수단은 저장 시 안내와 함께 막히며, 플러그인이 추가한 수단은 정상적으로 선택할 수 있습니다. 수단을 제공하던 플러그인을 껐더라도 이미 저장된 설정은 계속 수정할 수 있습니다.
+- 등록한 일정이 하나라도 있으면 일정 관리 목록이 열리지 않고 "총 0개"로만 표시되던 문제를 수정했습니다. 실행 이력 화면도 동일한 원인으로 열리지 않았으며, 이제 두 화면 모두 정상적으로 목록을 보여줍니다.
+
+#### 안내 문구·주소 처리
+
+- 일부 안내가 실제 문장 대신 내부 식별자(`messages.auth.unauthenticated` 같은 문자열)로 표시되던 문제를 수정했습니다. 로그인하지 않았거나 역할 권한이 없어 요청이 거절될 때, 메뉴에 역할을 지정할 때, 확장 식별자를 잘못 입력했을 때, 활동 로그를 기간·유형으로 검색할 때가 해당됩니다.
+- 회원 정보 수정, 권한·메뉴 설정, 본인인증, 알림 설정 등 여러 화면에서 처리를 마친 뒤 표시되는 안내 문구가 번역된 문장 대신 내부 식별자가 그대로 보이던 문제를 수정했습니다. 이제 성공·실패·권한 없음 등 모든 안내가 사용 중인 언어에 맞는 문장으로 표시됩니다.
+- 환경설정 저장이 실패했을 때 안내 문구에 항목 이름이 `security.password min length` 같은 내부 식별자로 표시되던 문제를 수정했습니다. 보안·업로드·SEO·고급·드라이버·메일 등 모든 설정 항목이 화면에 보이는 한글 항목명으로 안내됩니다.
+- 플러그인을 GitHub 주소나 ZIP 파일로 설치할 때의 입력 안내가 내부 식별자로 표시되던 문제를 수정했습니다. 주소 형식이 잘못됐거나, ZIP이 아닌 파일을 올렸거나, 파일 용량을 초과했을 때 정상 문장으로 안내합니다.
+- 목록의 열 제목을 눌러 정렬할 때, 이미 다른 열로 정렬 중이었다면 화살표는 새로 누른 열에 표시되면서 실제 정렬은 이전 열 기준으로 바뀌던 문제를 수정했습니다. 표시와 실제 정렬 기준이 어긋나 결과를 신뢰할 수 없었으며, 이제 누른 열 기준으로 한 번에 정렬됩니다.
+- 목록에서 뒤쪽 페이지를 보던 중 정렬을 바꾸면 이전 페이지 번호에 그대로 머물러, 정렬을 바꿨는데 엉뚱한 구간이 보이거나 빈 목록이 나오던 문제를 수정했습니다. 이제 정렬을 바꾸면 항상 첫 페이지부터 보여줍니다. 사용자 관리·게시판 신고현황·페이지 관리 목록이 해당됩니다.
+- 사용자 관리 목록에서 "페이지당 개수"가 10개로 표시되는데 실제로는 15개가 나오던 문제를 수정했습니다. 표시된 값과 실제 목록 건수가 일치합니다. 일정 관리 목록에서도 표시가 20개 목록을 10개로 잘못 안내하던 문제를 함께 바로잡았습니다.
+- 알림 발송 이력에서 정렬을 "수신자명순" 또는 "제목순"으로 바꾸면 목록이 비면서 오류 안내가 뜨던 문제를 수정했습니다. 화면이 제공하는 정렬인데 서버가 거부하고 있었으며, 이제 두 정렬 모두 정상 동작합니다. 많은 이력에서도 빠르게 정렬되도록 색인을 함께 추가했습니다.
+- 마이페이지 활동 목록에서 한 페이지에 표시할 개수를 0이나 음수로 요청하면 서버 오류가 나던 문제를 수정했습니다. 이제 허용 범위(1~100)로 자동 조정됩니다.
+- 레이아웃 편집기 화면이 정상 동작하는데도 서버가 "페이지 없음"(404)으로 응답하던 문제를 수정했습니다. 화면은 그대로 보였지만 브라우저 캐싱과 서버 접속 기록에서 없는 페이지로 취급되던 상태입니다.
+- 주소 끝에 슬래시가 붙은 형태(예: `/admin/`)로 접속하면 화면이 "페이지 없음"(404)으로 뜨던 문제를 수정했습니다. 특히 로그인이 풀린 상태에서 이렇게 접속하면 로그인 화면으로 넘어가지 않고 404가 나타났습니다. 이제 끝 슬래시가 있어도 정상적으로 같은 페이지로 연결됩니다.
+
+#### 메뉴·플러그인 설정 무결성
+
+- 메뉴를 수정할 때 자기 자신의 하위 메뉴 아래로 옮길 수 있던 문제를 수정했습니다. 이렇게 옮기면 메뉴 트리가 끊어져 관리자 화면에서 되돌릴 수 없었습니다. 메뉴 순서 변경 화면과 동일한 기준이 적용됩니다.
+- 플러그인 설정을 저장할 때, 그 플러그인이 제공하지 않는 항목까지 설정 파일에 함께 기록되던 문제를 수정했습니다. 이제 플러그인이 실제로 제공하는 설정 항목만 저장됩니다.
+- 문자·알림톡처럼 확장 기능이 추가하는 알림 발송 수단을 그 확장을 끈 뒤에도 발송 대상으로 삼아, 발송 이력에 "건너뜀"으로 남던 문제를 수정했습니다. 이제 확장을 끄면 해당 발송 수단은 발송 대상에서 완전히 제외되어 이력에도 남지 않고, 다시 켜면 알림 설정 그대로 복구됩니다.
+
## [7.0.5] - 2026-07-16
### Added
@@ -43,6 +261,7 @@
- 화면 구성 파일이 목록을 만들어 내는 과정에서 다국어 이름을 골라 쓸 때, 사이트를 어떤 언어로 보고 있든 항상 한국어 이름이 선택되던 문제를 수정했습니다. 이제 보고 있는 언어의 이름이 표시됩니다. 헤더의 배송국가 선택처럼 화면이 처음 열릴 때 목록을 만들어 두는 곳이 여기에 해당합니다.
- 메뉴를 눌러 화면을 이동했을 때, 필요한 정보를 여러 갈래로 나눠 받아오는 화면에서 먼저 도착한 정보가 뒤늦게 도착한 정보에 덮여 사라지는 경우가 있었습니다. 그 탓에 목록이 있어야 할 자리가 간헐적으로 비어 보이고 새로고침하면 정상으로 돌아오곤 했습니다. 이제 어느 정보가 먼저 도착하든 모두 반영됩니다. 이커머스 환경설정의 배송설정 탭에서 배송가능 국가 목록이 비어 보이던 것이 여기에 해당합니다.
- 이미 설치를 마친 환경의 설정 파일(`.env`)을 새 서버로 복사해, 데이터베이스가 아직 비어 있는 상태에서 설치를 이어가려 할 때 `php artisan migrate`로 테이블을 만들기도 전에 부팅 단계에서 오류가 나며 중단되던 문제를 수정했습니다. 이제 데이터베이스 작업 명령이 실행되는 동안에는 테이블 존재 여부를 실제로 확인하므로, 기존 서버의 설정을 재사용하는 신규 배포에서도 설치가 정상적으로 진행됩니다. (#41 @GyusoonKim 님께서 제보해주셨습니다.)
+- 활동 로그 기록에 실패했을 때 그 기록을 유발한 요청까지 함께 실패하던 문제를 수정했습니다. 결제 입금통보 같은 외부 콜백이 활동 로그 문제로 오류를 반환하는 일이 없어집니다.
## [7.0.2] - 2026-07-08
@@ -1375,7 +1594,6 @@ abort 발생 시 운영자에게 수동 재개 명령 (`php artisan core:execute
- 휴대폰 인증, 아이핀 인증 등 본인인증 기능 제공
- 사용자 관리 화면 레이아웃 확장 (본인인증 상세/폼)
- 역할 기반 접근 제어 (본인인증 관리자)
-- 다국어 지원 (ko, en)
#### 템플릿: sirsoft-admin_basic (관리자)
@@ -1411,7 +1629,6 @@ abort 발생 시 운영자에게 수동 재개 명령 (`php artisan core:execute
- CMS 페이지 표시 화면
- 에러 페이지 (403, 404, 500, 503)
- 점검 모드(maintenance) 전용 페이지
-- 반응형 레이아웃 (데스크톱/태블릿/모바일)
#### 다국어 시스템 (i18n)
diff --git a/INSTALL.md b/INSTALL.md
index 6c55f3cf..0a5d6d57 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -77,6 +77,49 @@ server {
}
```
+#### 정적 파일 최적화 블록을 함께 쓰는 경우
+
+아래처럼 확장자로 캐시 규칙을 거는 블록(aaPanel · CyberPanel · Plesk 기본 템플릿에
+포함되어 있습니다)을 함께 사용한다면 주의가 필요합니다.
+
+```nginx
+location ~* \.(js|css|json|png|jpg|svg|woff2?)$ {
+ expires max;
+ access_log off;
+}
+```
+
+nginx 는 **정규식 location 을 프리픽스 location(`location /`)보다 먼저** 매칭합니다.
+G7 은 일부 동적 엔드포인트에 `.js` · `.css` · `.json` 확장자를 쓰므로, 위 블록 안에
+PHP 핸들러가 없으면 그 요청들이 `try_files ... /index.php` 폴백에 닿지 못하고
+nginx 가 직접 파일을 찾다가 404 를 반환합니다. 증상은 **모든 페이지가 백지**입니다.
+
+해결 방법은 두 가지이며, 아무것도 하지 않아도 G7 이 스스로 복구합니다.
+
+1. **그대로 두기** — 브라우저가 자산 로드 실패를 감지하면 확장자 없는 주소로 자동
+ 전환합니다. 설치 마법사도 설치 시점에 이를 감지해 설정에 반영합니다.
+ 설치 후 확정하려면 `php artisan g7:asset-url-mode extensionless` 를 실행하거나
+ 관리자 > 환경설정 > 일반에서 "자산 파일 주소 방식" 을 변경하세요.
+ (검색엔진 봇은 JavaScript 를 실행하지 않으므로, SEO 를 쓴다면 이 확정을 권장합니다.)
+
+2. **`/api/` 를 정규식 블록보다 우선시키기** — `^~` 는 정규식 location 보다 우선하므로
+ 아래 블록을 추가하면 `/api/` 요청이 항상 PHP 로 갑니다. 확장자 기반 캐시 최적화를
+ 정적 파일에만 그대로 유지할 수 있습니다.
+
+```nginx
+location ^~ /api/ {
+ try_files $uri $uri/ /index.php?$query_string;
+}
+```
+
+서버가 동적 응답을 가로채는지는 아래 두 요청을 비교해 확인할 수 있습니다.
+첫 번째만 실패하면 가로채는 것입니다.
+
+```bash
+curl -i https://example.com/api/system/asset-probe.js
+curl -i https://example.com/api/system/asset-probe
+```
+
### 3단계: 설치 마법사 실행
브라우저에서 접속합니다.
@@ -246,7 +289,7 @@ unzip g7-release.zip
# 압축 해제 결과 확인 — 루트 디렉토리가 g7이 아니면 이름 변경
ls -la
-# (필요 시) mv g7-7.0.5 g7
+# (필요 시) mv g7-7.0.6 g7
# ZIP 파일 정리 (선택)
rm g7-release.zip
diff --git a/README.md b/README.md
index 8a4c6494..ae189eca 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
-
+
@@ -316,7 +316,7 @@ HookManager::doAction('sirsoft-ecommerce.order.after_confirm', $order);
| 가상 보호 행 | 코어/번들 확장에 내장된 한국어/영어는 별도 설치 없이 항상 활성/보호 상태로 노출 (수정/제거 차단) |
| 보안 | 언어 번역 외의 PHP 실행 코드 포함 시 설치 차단 |
-공식 일본어(ja) 번들 14종(코어 + 주요 모듈/플러그인/템플릿) 이 즉시 사용 가능하며, 인스톨러 4단계에서 모듈/플러그인/템플릿 선택과 종속된 언어팩 카드가 자동 연동되어 함께 설치할 수 있습니다.
+공식 일본어(ja) 번들 16종(코어 + 주요 모듈/플러그인/템플릿) 이 즉시 사용 가능하며, 인스톨러 4단계에서 모듈/플러그인/템플릿 선택과 종속된 언어팩 카드가 자동 연동되어 함께 설치할 수 있습니다.
> 상세: [docs/extension/language-packs.md](docs/extension/language-packs.md)
@@ -390,7 +390,9 @@ cp .env.example .env
| **sirsoft-pay_kginicis** | KG이니시스 결제 연동 |
| **sirsoft-pay_nicepayments** | 나이스페이먼츠 결제 연동 (통합결제창) |
| **sirsoft-pay_nhnkcp** | NHN KCP 결제 연동 (Standard Pay) |
+| **sirsoft-tosspayments** | 토스페이먼츠 결제 연동 |
| **sirsoft-verification_kginicis** | KG이니시스 본인인증 |
+| **sirsoft-verification_nhnkcp** | NHN KCP 휴대폰 본인확인 |
| **sirsoft-daum_postcode** | 다음 우편번호 검색 |
| **sirsoft-marketing** | 마케팅 도구 |
| **sirsoft-ckeditor5** | CKEditor 5 에디터 |
@@ -420,7 +422,9 @@ cp .env.example .env
| **g7-plugin-sirsoft-pay_kginicis-ja** | KG이니시스 결제 플러그인 일본어 |
| **g7-plugin-sirsoft-pay_nicepayments-ja** | 나이스페이먼츠 결제 플러그인 일본어 |
| **g7-plugin-sirsoft-pay_nhnkcp-ja** | NHN KCP 결제 플러그인 일본어 |
+| **g7-plugin-sirsoft-tosspayments-ja** | 토스페이먼츠 플러그인 일본어 |
| **g7-plugin-sirsoft-verification_kginicis-ja** | KG이니시스 본인인증 플러그인 일본어 |
+| **g7-plugin-sirsoft-verification_nhnkcp-ja** | NHN KCP 휴대폰 본인확인 플러그인 일본어 |
| **g7-template-sirsoft-admin_basic-ja** | 관리자 기본 템플릿 일본어 |
| **g7-template-sirsoft-basic-ja** | 사용자 기본 템플릿 일본어 |
diff --git a/app/ActivityLog/Traits/ResolvesActivityLogType.php b/app/ActivityLog/Traits/ResolvesActivityLogType.php
index d0268296..e977b0e0 100644
--- a/app/ActivityLog/Traits/ResolvesActivityLogType.php
+++ b/app/ActivityLog/Traits/ResolvesActivityLogType.php
@@ -44,8 +44,8 @@ trait ResolvesActivityLogType
* properties.extension_origin 에 자동 주입합니다 (loggable 미지정 케이스의
* action 라벨 namespace fallback 용).
*
- * @param string $action 액션명 (예: 'user.create')
- * @param array $context Monolog context 배열
+ * @param string $action 액션명 (예: 'user.create')
+ * @param array $context Monolog context 배열
*/
protected function logActivity(string $action, array $context): void
{
@@ -58,9 +58,13 @@ trait ResolvesActivityLogType
$context['properties'] = $properties;
}
+ // 활동 로그는 부수 기록이다 — 실패해도 그것을 유발한 요청(결제 콜백 등)까지
+ // 죽여서는 안 된다. 채널 해석 실패는 Exception 이 아니라 Error 로 오므로
+ // (\Log::channel() 이 null 을 반환하면 "->info() on null" = \Error)
+ // Throwable 로 받아야 가드가 실제로 동작한다.
try {
Log::channel('activity')->info($action, $context);
- } catch (\Exception $e) {
+ } catch (\Throwable $e) {
Log::error('Failed to record activity log', [
'action' => $action,
'error' => $e->getMessage(),
diff --git a/app/Benchmark/Axes/BatchAxisRunner.php b/app/Benchmark/Axes/BatchAxisRunner.php
new file mode 100644
index 00000000..7d50b0fe
--- /dev/null
+++ b/app/Benchmark/Axes/BatchAxisRunner.php
@@ -0,0 +1,141 @@
+ null;
+
+ if ($profile->mutates() && ! $options->allowWrite) {
+ return BenchmarkResult::skipped($profile, '데이터를 변경하는 배치입니다. --allow-write 를 붙여 실행하세요.');
+ }
+
+ $command = (string) $profile->option('command');
+ $arguments = (array) $profile->option('arguments', []);
+
+ if (! array_key_exists($command, Artisan::all())) {
+ return BenchmarkResult::skipped($profile, "등록되지 않은 커맨드: {$command} (해당 확장이 설치되어 있는지 확인)");
+ }
+
+ $notify("배치 실행: {$command}");
+
+ // 피크 메모리는 프로세스 단위 누적값이라 감소하지 않는다. 실행 전 값을 함께
+ // 기록해야 "이 배치가 피크를 밀어올렸는지"를 판정할 수 있다.
+ $peakBefore = memory_get_peak_usage(true);
+ $usageBefore = memory_get_usage(true);
+ $buffer = new BufferedOutput;
+
+ $start = microtime(true);
+
+ try {
+ $collected = $this->collector->collect(
+ static fn () => Artisan::call($command, $arguments, $buffer)
+ );
+ $exitCode = (int) $collected['value'];
+ $queries = $collected['queries'];
+ } catch (\Throwable $e) {
+ return BenchmarkResult::skipped($profile, '계측 실패: '.$e->getMessage());
+ }
+
+ $elapsedMs = (microtime(true) - $start) * 1000;
+ $peakAfter = memory_get_peak_usage(true);
+ $usageAfter = memory_get_usage(true);
+ $summary = $this->collector->summarize($queries);
+
+ $notes = [
+ sprintf('실행 전 피크 %s → 실행 후 피크 %s', $this->formatBytes($peakBefore), $this->formatBytes($peakAfter)),
+ ];
+
+ if ($peakAfter <= $peakBefore) {
+ $notes[] = '이 배치가 프로세스 피크를 밀어올리지 않았습니다 (실행 전 피크가 이미 더 높음).';
+ }
+
+ if ($exitCode !== 0) {
+ $notes[] = "커맨드가 실패 종료했습니다 (exit={$exitCode}) — 시간·메모리는 실패 지점까지의 값입니다.";
+ }
+
+ $output = trim($buffer->fetch());
+
+ if ($output !== '') {
+ $notes[] = '커맨드 출력: '.$output;
+ }
+
+ return new BenchmarkResult(
+ profile: $profile,
+ headers: ['커맨드', '종료코드', '소요(ms)', '피크 메모리', '메모리 증가', '쿼리(건)'],
+ rows: [[
+ $command,
+ (string) $exitCode,
+ number_format($elapsedMs, 1),
+ $this->formatBytes($peakAfter),
+ $this->formatBytes(max(0, $usageAfter - $usageBefore)),
+ number_format($summary['count']),
+ ]],
+ metrics: [
+ 'command' => $command,
+ 'arguments' => $arguments,
+ 'exit_code' => $exitCode,
+ 'elapsed_ms' => round($elapsedMs, 2),
+ 'peak_memory_before_bytes' => $peakBefore,
+ 'peak_memory_after_bytes' => $peakAfter,
+ 'memory_delta_bytes' => $usageAfter - $usageBefore,
+ 'query_count' => $summary['count'],
+ 'db_ms' => $summary['db_ms'],
+ ],
+ notes: $notes,
+ );
+ }
+
+ /**
+ * 바이트를 사람이 읽는 단위로 바꿉니다.
+ *
+ * @param int $bytes 바이트
+ * @return string 포맷된 문자열
+ */
+ private function formatBytes(int $bytes): string
+ {
+ if ($bytes >= 1024 ** 3) {
+ return number_format($bytes / 1024 ** 3, 2).' GB';
+ }
+
+ if ($bytes >= 1024 ** 2) {
+ return number_format($bytes / 1024 ** 2, 1).' MB';
+ }
+
+ return number_format($bytes / 1024, 1).' KB';
+ }
+}
diff --git a/app/Benchmark/Axes/ListAxisRunner.php b/app/Benchmark/Axes/ListAxisRunner.php
new file mode 100644
index 00000000..ed701f49
--- /dev/null
+++ b/app/Benchmark/Axes/ListAxisRunner.php
@@ -0,0 +1,350 @@
+
+ */
+ private const FILTER_OPERATORS = ['=', '!=', '<>', '<', '<=', '>', '>=', 'like', 'in', 'not in'];
+
+ public function __construct(private readonly SyntheticSeeder $seeder) {}
+
+ /**
+ * {@inheritDoc}
+ */
+ public function axis(): BenchmarkAxis
+ {
+ return BenchmarkAxis::ListQuery;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public function run(BenchmarkProfile $profile, BenchmarkRunOptions $options, ?\Closure $onProgress = null): BenchmarkResult
+ {
+ $notify = $onProgress ?? static fn (string $message) => null;
+ $table = (string) $profile->option('table');
+
+ if (! Schema::hasTable($table)) {
+ return BenchmarkResult::skipped($profile, "테이블이 없습니다: {$table} (해당 확장이 설치되어 있는지 확인)");
+ }
+
+ if (($options->fresh || $options->seed > 0) && app()->environment('production')) {
+ return BenchmarkResult::skipped($profile, '운영 환경에서는 시딩/비움을 사용할 수 없습니다.');
+ }
+
+ $filterError = $this->validateFilters((array) $profile->option('filters', []));
+
+ if ($filterError !== null) {
+ return BenchmarkResult::skipped($profile, $filterError);
+ }
+
+ if ($options->fresh) {
+ $this->seeder->truncate($table);
+ $notify("비움: {$table}");
+ }
+
+ $columns = $this->existingColumns($table, (array) $profile->option('columns', ['*']));
+ $order = $this->existingOrder($table, (array) $profile->option('order', [['id', 'desc']]));
+
+ if ($options->seed > 0) {
+ $notify("시딩: {$table} ".number_format($options->seed).' 건');
+ $this->seeder->seed(
+ $table,
+ $options->seed,
+ (array) $profile->option('seed_overrides', []),
+ fn (int $inserted, int $total) => $notify(sprintf(' 시딩 %s / %s', number_format($inserted), number_format($total))),
+ // 정렬 기준 컬럼은 nullable 이어도 채운다 — 비워두면 합성 행이 전부 동률이 되어
+ // 계측이 정렬 인덱스가 아니라 tie-break 경로를 잰다.
+ array_column($order, 0),
+ );
+ }
+
+ $rows = [];
+ $notes = [];
+
+ foreach ($options->offsets as $offset) {
+ $allMs = $this->measure($profile, ['*'], $order, $offset, $options->runs);
+ $listMs = $this->measure($profile, $columns, $order, $offset, $options->runs);
+ $idOnlyMs = $this->measure($profile, ['id'], $order, $offset, $options->runs);
+
+ $rows[] = [
+ 'offset' => $offset,
+ 'all_ms' => $allMs,
+ 'list_ms' => $listMs,
+ 'id_only_ms' => $idOnlyMs,
+ 'ratio' => $idOnlyMs > 0 ? round($allMs / $idOnlyMs, 1) : null,
+ ];
+
+ if ($options->explain) {
+ $notes[] = "EXPLAIN @ OFFSET {$offset} — 목록 컬럼";
+
+ foreach ($this->explain($profile, $columns, $order, $offset) as $line) {
+ $notes[] = ' '.$line;
+ }
+
+ // 지연 조인의 inner 가 실제로 어떤 계획을 타는지가 인덱스 설계의 근거다
+ $notes[] = "EXPLAIN @ OFFSET {$offset} — ID 만 (지연 조인 inner)";
+
+ foreach ($this->explain($profile, ['id'], $order, $offset) as $line) {
+ $notes[] = ' '.$line;
+ }
+ }
+ }
+
+ return new BenchmarkResult(
+ profile: $profile,
+ headers: ['OFFSET', '전체 컬럼(ms)', '목록 컬럼(ms)', 'ID만(ms)', '전체÷ID'],
+ rows: array_map(fn (array $row) => [
+ number_format($row['offset']),
+ number_format($row['all_ms'], 1),
+ number_format($row['list_ms'], 1),
+ number_format($row['id_only_ms'], 1),
+ $row['ratio'] !== null ? $row['ratio'].'×' : '-',
+ ], $rows),
+ metrics: [
+ 'table' => $table,
+ 'columns' => $columns,
+ 'runs' => $options->runs,
+ 'offsets' => $rows,
+ ],
+ notes: $notes,
+ );
+ }
+
+ /**
+ * 스키마에 실제로 존재하는 컬럼만 남깁니다.
+ *
+ * `['*']` 는 "목록이 전 컬럼을 그대로 노출한다" 는 선언입니다. 응답 계약상 넓은 컬럼을
+ * 뺄 수 없는 목록(활동 로그의 changes, 알림 발송 이력의 body 등)이 여기 해당하며, 이
+ * 경우 계측의 비교 축은 select * vs select id 가 됩니다. 확장 버전에 따라 컬럼 구성이
+ * 달라도 계측이 죽지 않도록 스키마에 없는 컬럼은 걸러냅니다.
+ *
+ * @param string $table 테이블명
+ * @param array $columns 후보 컬럼
+ * @return array 존재하는 컬럼 목록
+ */
+ private function existingColumns(string $table, array $columns): array
+ {
+ if ($columns === ['*']) {
+ return Schema::getColumnListing($table);
+ }
+
+ $existing = array_values(array_filter(
+ $columns,
+ fn (mixed $column) => is_string($column) && Schema::hasColumn($table, $column)
+ ));
+
+ return $existing === [] ? ['id'] : $existing;
+ }
+
+ /**
+ * 스키마에 존재하는 정렬 컬럼만 남깁니다.
+ *
+ * @param string $table 테이블명
+ * @param array $order 후보 정렬
+ * @return array 적용 가능한 정렬 목록
+ */
+ private function existingOrder(string $table, array $order): array
+ {
+ $existing = array_values(array_filter(
+ $order,
+ fn (mixed $spec) => is_array($spec) && isset($spec[0]) && Schema::hasColumn($table, (string) $spec[0])
+ ));
+
+ return $existing === [] ? [['id', 'desc']] : $existing;
+ }
+
+ /**
+ * 한 조합을 여러 번 실행해 중앙값(ms)을 돌려줍니다.
+ *
+ * `DB::enableQueryLog()` 는 오버헤드와 메모리 누적이 있어 쓰지 않고 직접 시간을 잽니다.
+ *
+ * @param BenchmarkProfile $profile 프로파일
+ * @param array $columns select 컬럼
+ * @param array $order 정렬
+ * @param int $offset OFFSET
+ * @param int $runs 측정 횟수
+ * @return float 중앙값 (밀리초)
+ */
+ private function measure(BenchmarkProfile $profile, array $columns, array $order, int $offset, int $runs): float
+ {
+ // 첫 회는 캐시 워밍 성격이라 버린다
+ $this->buildQuery($profile, $columns, $order, $offset)->get();
+
+ $samples = [];
+
+ for ($i = 0; $i < max(1, $runs); $i++) {
+ $start = microtime(true);
+ $this->buildQuery($profile, $columns, $order, $offset)->get();
+ $samples[] = (microtime(true) - $start) * 1000;
+ }
+
+ sort($samples);
+
+ return $samples[intdiv(count($samples), 2)];
+ }
+
+ /**
+ * 계측 대상 쿼리를 조립합니다.
+ *
+ * @param BenchmarkProfile $profile 프로파일
+ * @param array $columns select 컬럼
+ * @param array $order 정렬
+ * @param int $offset OFFSET
+ * @return Builder 조립된 쿼리
+ */
+ private function buildQuery(BenchmarkProfile $profile, array $columns, array $order, int $offset): Builder
+ {
+ $table = (string) $profile->option('table');
+ $query = DB::table($table)->select($columns);
+
+ if ($profile->option('soft_delete', false) && Schema::hasColumn($table, 'deleted_at')) {
+ $query->whereNull('deleted_at');
+ }
+
+ $this->applyFilters($query, $table, (array) $profile->option('filters', []));
+
+ foreach ($order as $spec) {
+ $query->orderBy($spec[0], $spec[1] ?? 'asc');
+ }
+
+ return $query->offset($offset)->limit(self::PAGE_LIMIT);
+ }
+
+ /**
+ * 선언된 필터를 계측 쿼리에 적용합니다.
+ *
+ * 값이 `[연산자, 값]` 형태면 그 연산자로, 그 밖에는 등가 비교로 해석합니다. 등가 비교만
+ * 지원하면 화면이 실제로 거는 필터를 선언할 방법이 없는 목록이 생깁니다 — 주문 목록은
+ * 상태 미지정 시 임시 주문 상태를 `NOT IN` 으로 제외하므로, 그것을 선언하지 못하면
+ * 계측이 화면과 다른 인덱스를 타게 됩니다.
+ *
+ * 연산자는 닫힌 집합으로 해석합니다. 임의 문자열을 그대로 넘기면 선언 오타가 조용히
+ * 통과하거나 의도치 않은 SQL 이 조립됩니다.
+ *
+ * @param Builder $query 계측 쿼리
+ * @param string $table 대상 테이블
+ * @param array $filters 선언된 필터
+ */
+ private function applyFilters(Builder $query, string $table, array $filters): void
+ {
+ foreach ($filters as $column => $declared) {
+ if (! Schema::hasColumn($table, (string) $column)) {
+ continue;
+ }
+
+ // [연산자, 값] 형태가 아니면 등가 비교 (배열 값을 IN 으로 오해석하지 않도록 형태로 판정)
+ if (! is_array($declared) || count($declared) !== 2 || ! is_string($declared[0])) {
+ $query->where($column, $declared);
+
+ continue;
+ }
+
+ [$operator, $value] = $declared;
+
+ match (strtolower($operator)) {
+ '=' => $query->where($column, '=', $value),
+ '!=', '<>' => $query->where($column, '!=', $value),
+ '<' => $query->where($column, '<', $value),
+ '<=' => $query->where($column, '<=', $value),
+ '>' => $query->where($column, '>', $value),
+ '>=' => $query->where($column, '>=', $value),
+ 'like' => $query->where($column, 'like', $value),
+ 'in' => $query->whereIn($column, (array) $value),
+ 'not in' => $query->whereNotIn($column, (array) $value),
+ // 도달 불가 — run() 이 실행 전에 연산자를 검증해 거부한다
+ default => null,
+ };
+ }
+ }
+
+ /**
+ * 선언된 필터의 연산자를 실행 전에 검증합니다.
+ *
+ * 알 수 없는 연산자를 조용히 무시하면 그 필터가 빠진 채로 측정되어, 화면과 다른 것을
+ * 재면서도 정상 측정으로 보고됩니다. 실행 전에 사유와 함께 거부합니다.
+ *
+ * @param array $filters 선언된 필터
+ * @return string|null 실패 사유 (문제 없으면 null)
+ */
+ private function validateFilters(array $filters): ?string
+ {
+ foreach ($filters as $column => $declared) {
+ if (! is_array($declared) || count($declared) !== 2 || ! is_string($declared[0])) {
+ continue;
+ }
+
+ if (! in_array(strtolower($declared[0]), self::FILTER_OPERATORS, true)) {
+ return sprintf(
+ '필터 %s 의 연산자를 알 수 없습니다: %s (허용: %s)',
+ $column,
+ $declared[0],
+ implode(', ', self::FILTER_OPERATORS)
+ );
+ }
+ }
+
+ return null;
+ }
+
+ /**
+ * 실행 계획을 수집합니다.
+ *
+ * @param BenchmarkProfile $profile 프로파일
+ * @param array $columns select 컬럼
+ * @param array $order 정렬
+ * @param int $offset OFFSET
+ * @return array 실행 계획 요약 줄 목록
+ */
+ private function explain(BenchmarkProfile $profile, array $columns, array $order, int $offset): array
+ {
+ $query = $this->buildQuery($profile, $columns, $order, $offset);
+
+ try {
+ $plan = DB::select('EXPLAIN '.$query->toSql(), $query->getBindings());
+ } catch (\Throwable $e) {
+ return ['실행 계획 수집 실패: '.$e->getMessage()];
+ }
+
+ return array_map(function ($row) {
+ $row = (array) $row;
+
+ return sprintf(
+ 'type=%s key=%s rows=%s filtered=%s extra=%s',
+ $row['type'] ?? '-',
+ $row['key'] ?? '-',
+ $row['rows'] ?? '-',
+ $row['filtered'] ?? '-',
+ $row['Extra'] ?? '-'
+ );
+ }, $plan);
+ }
+}
diff --git a/app/Benchmark/Axes/ScreenAxisRunner.php b/app/Benchmark/Axes/ScreenAxisRunner.php
new file mode 100644
index 00000000..787cadec
--- /dev/null
+++ b/app/Benchmark/Axes/ScreenAxisRunner.php
@@ -0,0 +1,261 @@
+mutates() && ! $options->allowWrite) {
+ return BenchmarkResult::skipped($profile, '데이터를 변경하는 화면입니다. --allow-write 를 붙여 실행하세요.');
+ }
+
+ [$uri, $uriError] = $this->resolveUri($profile);
+
+ if ($uriError !== null) {
+ return BenchmarkResult::skipped($profile, $uriError);
+ }
+
+ // `--as` 로 지정한 계정은 트랜잭션 진입 전에 확인한다 — 없는 계정으로 계측을 시작하면
+ // 롤백 구간 안에서 실패해 사유만 흐려진다.
+ if ($options->asUser !== null && $this->identity->findExistingUser($options->asUser) === null) {
+ return BenchmarkResult::skipped($profile, "계측에 사용할 계정을 찾을 수 없습니다: {$options->asUser}");
+ }
+
+ $method = strtoupper((string) $profile->option('method', 'GET'));
+ $query = (array) $profile->option('query', []);
+ $query['per_page'] ??= $options->perPage;
+
+ // 데이터를 변경하는 화면은 반복 측정 시 2회차부터 조건이 달라진다(중복 키, 재고 소진).
+ // 롤백은 계측 종료 시 한 번이므로 회차 간에는 되돌려지지 않는다 → 1회만 잰다.
+ $runs = $profile->mutates() ? 1 : max(1, $options->runs);
+ $notes = [];
+
+ if ($profile->mutates()) {
+ $notes[] = '데이터 변경 화면이라 1회만 측정했습니다 (회차 간 조건 변화 방지).';
+ }
+
+ try {
+ $measured = $this->identity->withRolledBackTransaction(
+ fn () => $this->measure($profile, (string) $uri, $method, $query, $runs, $options, $onProgress)
+ );
+ } catch (\Throwable $e) {
+ return BenchmarkResult::skipped($profile, '계측 실패: '.$e->getMessage());
+ }
+
+ $summary = $measured['summary'];
+
+ foreach ($summary['n_plus_one'] as $candidate) {
+ $notes[] = sprintf('N+1 후보 %d회: %s', $candidate['count'], $candidate['sql']);
+ }
+
+ if ($summary['n_plus_one'] === []) {
+ $notes[] = 'N+1 후보 없음 (같은 SQL 5회 이상 반복 없음).';
+ }
+
+ return new BenchmarkResult(
+ profile: $profile,
+ headers: ['요청', '상태', '응답(ms)', '쿼리(건)', 'DB(ms)'],
+ rows: [[
+ $method.' '.$uri,
+ (string) $measured['status'],
+ number_format($measured['total_ms'], 1),
+ number_format($summary['count']),
+ number_format($summary['db_ms'], 1),
+ ]],
+ metrics: [
+ 'uri' => $uri,
+ 'method' => $method,
+ 'query' => $query,
+ 'status' => $measured['status'],
+ 'runs' => $runs,
+ 'total_ms' => $measured['total_ms'],
+ 'query_count' => $summary['count'],
+ 'db_ms' => $summary['db_ms'],
+ 'n_plus_one' => $summary['n_plus_one'],
+ 'acting_user' => $measured['acting_user'],
+ ],
+ notes: $notes,
+ );
+ }
+
+ /**
+ * 계측 대상 URI 를 해석합니다.
+ *
+ * 라우트명 선언을 권장하는 이유는 두 가지입니다 — 프리픽스를 문자열로 조립하지 않아도
+ * 되고, 라우트가 사라지면 계측이 조용히 404 를 재는 대신 사유를 남기고 건너뜁니다.
+ *
+ * 예외를 던지지 않고 사유 문자열을 함께 돌려주는 이유는, 이 축의 실패 계약이
+ * `BenchmarkResult::skipped` 이기 때문입니다 — 던지고 곧바로 잡는 우회로를 만들지 않습니다.
+ *
+ * @param BenchmarkProfile $profile 프로파일
+ * @return array{0: string|null, 1: string|null} [경로, 실패 사유]
+ */
+ private function resolveUri(BenchmarkProfile $profile): array
+ {
+ $routeName = $profile->option('route');
+
+ if (is_string($routeName) && $routeName !== '') {
+ if (Route::getRoutes()->getByName($routeName) === null) {
+ return [null, "등록되지 않은 라우트명: {$routeName} (해당 확장이 설치되어 있는지 확인)"];
+ }
+
+ return [route($routeName, (array) $profile->option('route_params', []), false), null];
+ }
+
+ return ['/'.ltrim((string) $profile->option('uri'), '/'), null];
+ }
+
+ /**
+ * 내부 요청을 반복 실행해 응답 시간 중앙값과 쿼리 요약을 냅니다.
+ *
+ * @param BenchmarkProfile $profile 프로파일
+ * @param string $uri 경로
+ * @param string $method HTTP 메서드
+ * @param array $query 쿼리스트링
+ * @param int $runs 측정 횟수
+ * @param BenchmarkRunOptions $options 실행 옵션
+ * @param \Closure|null $onProgress 진행 콜백
+ * @return array{status: int, total_ms: float, summary: array, acting_user: array} 계측 결과
+ */
+ private function measure(
+ BenchmarkProfile $profile,
+ string $uri,
+ string $method,
+ array $query,
+ int $runs,
+ BenchmarkRunOptions $options,
+ ?\Closure $onProgress,
+ ): array {
+ $notify = $onProgress ?? static fn (string $message) => null;
+
+ $issued = $this->identity->issueToken(
+ (array) $profile->option('permissions', []),
+ $options->asUser !== null ? $this->identity->findExistingUser($options->asUser) : null
+ );
+
+ $notify(sprintf(
+ '인증: %s (%s)',
+ $issued['user']->email,
+ $issued['ephemeral'] ? '계측용 임시 계정 — 종료 시 롤백' : '지정 계정'
+ ));
+
+ $samples = [];
+ $status = 0;
+ $queries = [];
+
+ // 첫 회는 라우트 매칭·컨테이너 해석 워밍이라 버린다 (측정 회차와 별도로 1회 더 실행)
+ for ($i = 0; $i <= $runs; $i++) {
+ $collected = $this->collector->collect(
+ fn () => $this->dispatch($uri, $method, $query, $issued['token'])
+ );
+
+ /** @var array{status: int, ms: float} $outcome */
+ $outcome = $collected['value'];
+ $status = $outcome['status'];
+
+ if ($i === 0) {
+ continue;
+ }
+
+ $samples[] = $outcome['ms'];
+ $queries = $collected['queries'];
+ }
+
+ sort($samples);
+
+ return [
+ 'status' => $status,
+ 'total_ms' => $samples[intdiv(count($samples), 2)],
+ 'summary' => $this->collector->summarize($queries),
+ 'acting_user' => [
+ 'id' => $issued['user']->id,
+ 'email' => $issued['user']->email,
+ 'ephemeral' => $issued['ephemeral'],
+ ],
+ ];
+ }
+
+ /**
+ * 내부 요청 1회를 처리하고 소요 시간을 잽니다.
+ *
+ * 커널이 컨테이너의 `request` 인스턴스와 인증 가드 상태를 갈아치우므로, 처리 후
+ * 원상 복구합니다 — 복구하지 않으면 이어지는 회차/프로파일이 앞 요청의 인증 상태를
+ * 물려받아 계측이 서로 오염됩니다.
+ *
+ * @param string $uri 경로
+ * @param string $method HTTP 메서드
+ * @param array $query 쿼리스트링/바디
+ * @param string $token Sanctum 토큰
+ * @return array{status: int, ms: float} 상태 코드와 소요 시간
+ */
+ private function dispatch(string $uri, string $method, array $query, string $token): array
+ {
+ $previousRequest = app()->bound('request') ? app('request') : null;
+
+ $request = Request::create($uri, $method, $query);
+ $request->headers->set('Accept', 'application/json');
+ $request->headers->set('Authorization', 'Bearer '.$token);
+
+ $start = microtime(true);
+
+ try {
+ $response = app(HttpKernel::class)->handle($request);
+ $status = $response->getStatusCode();
+ // 스트리밍 응답은 본문 생성까지가 사용자 체감 시간이라 여기서 소비한다
+ $response->getContent();
+ } finally {
+ $ms = (microtime(true) - $start) * 1000;
+
+ Auth::forgetGuards();
+
+ if ($previousRequest !== null) {
+ app()->instance('request', $previousRequest);
+ }
+ }
+
+ return ['status' => $status, 'ms' => $ms];
+ }
+}
diff --git a/app/Benchmark/Axes/WriteAxisRunner.php b/app/Benchmark/Axes/WriteAxisRunner.php
new file mode 100644
index 00000000..ca92dc20
--- /dev/null
+++ b/app/Benchmark/Axes/WriteAxisRunner.php
@@ -0,0 +1,227 @@
+ null;
+
+ if (! $options->allowWrite) {
+ return BenchmarkResult::skipped($profile, '쓰기 축입니다. --allow-write 를 붙여 실행하세요.');
+ }
+
+ $resolved = [];
+
+ foreach (['callback', 'prepare', 'cleanup'] as $field) {
+ if ($field !== 'callback' && $profile->option($field) === null) {
+ $resolved[$field] = null;
+
+ continue;
+ }
+
+ [$callable, $error] = $this->resolveCallable($profile->option($field), $profile, $field);
+
+ if ($error !== null) {
+ return BenchmarkResult::skipped($profile, $error);
+ }
+
+ $resolved[$field] = $callable;
+ }
+
+ $callback = $resolved['callback'];
+ $prepare = $resolved['prepare'];
+ $cleanup = $resolved['cleanup'];
+
+ $runs = max(1, $options->runs);
+
+ try {
+ $measured = $this->identity->withRolledBackTransaction(
+ fn () => $this->measure($callback, $prepare, $runs, $onProgress)
+ );
+ } catch (\Throwable $e) {
+ return BenchmarkResult::skipped($profile, '계측 실패: '.$e->getMessage());
+ } finally {
+ if ($cleanup !== null) {
+ // 트랜잭션 롤백으로 되돌지 않는 잔여물(파일·캐시)을 정리한다.
+ // 정리 실패가 계측 결과를 삼키면 안 되므로 사유만 알린다.
+ try {
+ $cleanup();
+ } catch (\Throwable $e) {
+ $notify('cleanup 실패: '.$e->getMessage());
+ }
+ }
+ }
+
+ $summary = $this->collector->summarize($measured['queries']);
+
+ return new BenchmarkResult(
+ profile: $profile,
+ headers: ['첫 회(ms)', '중앙값(ms)', '회차', '쿼리(건)', 'DB(ms)'],
+ rows: [[
+ number_format($measured['first_ms'], 1),
+ number_format($measured['median_ms'], 1),
+ (string) $runs,
+ number_format($summary['count']),
+ number_format($summary['db_ms'], 1),
+ ]],
+ metrics: [
+ 'first_ms' => $measured['first_ms'],
+ 'median_ms' => $measured['median_ms'],
+ 'runs' => $runs,
+ 'samples_ms' => $measured['samples'],
+ 'query_count' => $summary['count'],
+ 'db_ms' => $summary['db_ms'],
+ 'n_plus_one' => $summary['n_plus_one'],
+ ],
+ notes: array_merge(
+ ['계측으로 생긴 행은 롤백했습니다.'],
+ array_map(
+ fn (array $candidate) => sprintf('반복 쿼리 %d회: %s', $candidate['count'], $candidate['sql']),
+ $summary['n_plus_one']
+ )
+ ),
+ );
+ }
+
+ /**
+ * 선언된 콜백을 호출 가능한 형태로 해석합니다.
+ *
+ * 예외를 던지지 않고 사유 문자열을 함께 돌려주는 이유는, 이 축의 실패 계약이
+ * `BenchmarkResult::skipped` 이기 때문입니다 — 던지고 곧바로 잡는 우회로를 만들지 않습니다.
+ *
+ * @param mixed $declared 선언값
+ * @param BenchmarkProfile $profile 프로파일 (오류 메시지용)
+ * @param string $field 선언 필드명 (오류 메시지용)
+ * @return array{0: callable|null, 1: string|null} [해석된 콜백, 실패 사유]
+ */
+ private function resolveCallable(mixed $declared, BenchmarkProfile $profile, string $field): array
+ {
+ $where = $profile->qualifiedKey().' 의 '.$field;
+
+ if ($declared instanceof \Closure) {
+ return [null, "{$where}: 클로저는 쓸 수 없습니다 (config:cache 불가). 'Fqcn' 또는 ['Fqcn', 'method'] 형식으로 선언하세요."];
+ }
+
+ if (is_string($declared)) {
+ if (! class_exists($declared)) {
+ return [null, "{$where}: 클래스를 찾을 수 없습니다 — {$declared}"];
+ }
+
+ $instance = app($declared);
+
+ if (! is_callable($instance)) {
+ return [null, "{$where}: {$declared} 에 __invoke() 가 없습니다."];
+ }
+
+ return [$instance, null];
+ }
+
+ if (is_array($declared) && count($declared) === 2 && is_string($declared[0]) && is_string($declared[1])) {
+ [$class, $method] = $declared;
+
+ if (! class_exists($class)) {
+ return [null, "{$where}: 클래스를 찾을 수 없습니다 — {$class}"];
+ }
+
+ $instance = app($class);
+
+ if (! method_exists($instance, $method)) {
+ return [null, "{$where}: {$class}::{$method}() 가 없습니다."];
+ }
+
+ return [[$instance, $method], null];
+ }
+
+ return [null, "{$where}: 'Fqcn' 또는 ['Fqcn', 'method'] 형식이어야 합니다."];
+ }
+
+ /**
+ * 콜백을 반복 실행해 첫 회 시간과 중앙값을 냅니다.
+ *
+ * 첫 회를 버리지 않고 따로 보고하는 이유는, 저장 경로에서는 첫 회가 포함하는 비용
+ * (클래스 로딩, 설정 해석, 관계 초기 조회)이 실사용에서도 발생하기 때문입니다.
+ * 쿼리 요약은 마지막 회차 기준입니다 — 첫 회는 위 초기화 쿼리가 섞입니다.
+ *
+ * `prepare` 는 계측 구간 **밖**에서 회차마다 실행합니다. 저장 경로에는 선행 상태가
+ * 필요한 경우가 많고(주문 생성에는 임시 주문이 필요하고 임시 주문은 1회만 전환됨),
+ * 그 준비 비용이 측정값에 섞이면 재려던 것을 재지 못하게 됩니다.
+ *
+ * @param callable $callback 저장 경로 콜백 (prepare 반환값을 인자로 받음)
+ * @param callable|null $prepare 회차별 선행 준비 콜백 (계측 제외, 회차 번호를 인자로 받음)
+ * @param int $runs 측정 횟수
+ * @param \Closure|null $onProgress 진행 콜백
+ * @return array{first_ms: float, median_ms: float, samples: array, queries: array} 계측 결과
+ */
+ private function measure(callable $callback, ?callable $prepare, int $runs, ?\Closure $onProgress): array
+ {
+ $notify = $onProgress ?? static fn (string $message) => null;
+ $samples = [];
+ $queries = [];
+
+ for ($i = 1; $i <= $runs; $i++) {
+ $notify("쓰기 계측 {$i} / {$runs}");
+
+ $context = $prepare !== null ? $prepare($i) : null;
+
+ $start = microtime(true);
+ $collected = $this->collector->collect(static function () use ($callback, $context) {
+ $callback($context);
+ });
+ $samples[] = (microtime(true) - $start) * 1000;
+ $queries = $collected['queries'];
+ }
+
+ $sorted = $samples;
+ sort($sorted);
+
+ return [
+ 'first_ms' => $samples[0],
+ 'median_ms' => $sorted[intdiv(count($sorted), 2)],
+ 'samples' => $samples,
+ 'queries' => $queries,
+ ];
+ }
+}
diff --git a/app/Benchmark/BenchmarkIdentity.php b/app/Benchmark/BenchmarkIdentity.php
new file mode 100644
index 00000000..cb2af9c1
--- /dev/null
+++ b/app/Benchmark/BenchmarkIdentity.php
@@ -0,0 +1,144 @@
+ 0` 분기), 읽기/쓰기 분리 환경에서도 계측 요청이 이 계정을 인증할 수
+ * 있습니다. 운영 DB 에서도 잔여 계정이 생기지 않는 이유가 이 롤백입니다.
+ */
+class BenchmarkIdentity
+{
+ /**
+ * 롤백되는 트랜잭션 안에서 콜백을 실행합니다.
+ *
+ * 계측이 만든 계정·토큰과, 계측 대상이 만든 행까지 함께 되돌립니다. 쓰기 축의 결과를
+ * 되돌리는 것도 같은 장치를 씁니다.
+ *
+ * @param \Closure $callback 트랜잭션 안에서 실행할 작업
+ * @return mixed 콜백 반환값
+ */
+ public function withRolledBackTransaction(\Closure $callback): mixed
+ {
+ DB::beginTransaction();
+
+ try {
+ return $callback();
+ } finally {
+ // 계측 결과 산출 여부와 무관하게 되돌린다 — 예외로 빠져나가도 잔여 데이터 없음
+ DB::rollBack();
+ }
+ }
+
+ /**
+ * 계측에 사용할 Sanctum 토큰을 발급합니다.
+ *
+ * 호출 전에 `--as` 계정 존재를 `findExistingUser()` 로 확인해야 합니다 — 계정 부재는
+ * 계측 실패가 아니라 실행 전 판정 대상이라 이 메서드는 그 경우를 다루지 않습니다.
+ *
+ * @param array $permissions 임시 계정에 부여할 권한 식별자 목록
+ * @param User|null $actor `--as` 로 확인된 기존 계정 (null 이면 임시 계정 생성)
+ * @return array{token: string, user: User, ephemeral: bool} 토큰과 인증 주체
+ */
+ public function issueToken(array $permissions = [], ?User $actor = null): array
+ {
+ $user = $actor ?? $this->makeEphemeralAdmin($permissions);
+
+ return [
+ 'token' => $user->createToken('g7-bench-'.Str::random(8))->plainTextToken,
+ 'user' => $user,
+ 'ephemeral' => $actor === null,
+ ];
+ }
+
+ /**
+ * 지정된 기존 계정을 찾습니다.
+ *
+ * @param string $identifier 계정 ID 또는 이메일
+ * @return User|null 찾은 계정 (없으면 null)
+ */
+ public function findExistingUser(string $identifier): ?User
+ {
+ return ctype_digit($identifier)
+ ? User::find((int) $identifier)
+ : User::where('email', $identifier)->first();
+ }
+
+ /**
+ * 선언된 권한만 가진 임시 관리자를 생성합니다.
+ *
+ * 권한을 프로파일 선언에서 받는 이유는, 계측 대상 화면이 요구하는 권한만 주어야
+ * 미들웨어 통과 여부까지 실제와 같아지기 때문입니다(전권 계정으로 재면 권한 검사
+ * 비용과 분기가 달라집니다).
+ *
+ * @param array $permissions 권한 식별자 목록
+ * @return User 생성된 임시 관리자
+ */
+ private function makeEphemeralAdmin(array $permissions): User
+ {
+ $user = User::factory()->create();
+
+ $permissionIds = [];
+
+ foreach ($permissions as $identifier) {
+ $identifier = (string) $identifier;
+
+ $permission = Permission::firstOrCreate(
+ ['identifier' => $identifier],
+ [
+ 'name' => json_encode(['ko' => $identifier, 'en' => $identifier]),
+ 'description' => json_encode(['ko' => $identifier, 'en' => $identifier]),
+ 'extension_type' => ExtensionOwnerType::Core,
+ 'extension_identifier' => 'core',
+ 'type' => 'admin',
+ ]
+ );
+
+ $permissionIds[] = $permission->id;
+ }
+
+ $benchRole = Role::create([
+ 'identifier' => 'g7_bench_'.Str::random(8),
+ 'name' => json_encode(['ko' => '성능 계측 전용', 'en' => 'Benchmark Only']),
+ 'description' => json_encode(['ko' => '성능 계측 임시 역할', 'en' => 'Temporary benchmark role']),
+ 'is_active' => true,
+ ]);
+
+ $adminRole = Role::firstOrCreate(
+ ['identifier' => 'admin'],
+ [
+ 'name' => json_encode(['ko' => '관리자', 'en' => 'Admin']),
+ 'description' => json_encode(['ko' => '시스템 관리자', 'en' => 'System Admin']),
+ 'extension_type' => ExtensionOwnerType::Core,
+ 'extension_identifier' => 'core',
+ 'type' => 'admin',
+ 'is_active' => true,
+ ]
+ );
+
+ if ($permissionIds !== []) {
+ $benchRole->permissions()->sync($permissionIds);
+ }
+
+ $user->roles()->attach($adminRole->id, ['assigned_at' => now(), 'assigned_by' => null]);
+ $user->roles()->attach($benchRole->id, ['assigned_at' => now(), 'assigned_by' => null]);
+
+ return $user->fresh();
+ }
+}
diff --git a/app/Benchmark/BenchmarkProfileRegistry.php b/app/Benchmark/BenchmarkProfileRegistry.php
new file mode 100644
index 00000000..93ac970c
--- /dev/null
+++ b/app/Benchmark/BenchmarkProfileRegistry.php
@@ -0,0 +1,275 @@
+|null
+ */
+ private ?array $profiles = null;
+
+ /**
+ * 수집 중 발생한 선언 오류 메시지
+ *
+ * @var array
+ */
+ private array $warnings = [];
+
+ public function __construct(
+ private readonly ModuleManagerInterface $moduleManager,
+ private readonly PluginManagerInterface $pluginManager,
+ ) {}
+
+ /**
+ * 모든 프로파일을 정규화 키 기준으로 반환합니다.
+ *
+ * @return array 정규화 키 → 프로파일
+ */
+ public function all(): array
+ {
+ if ($this->profiles !== null) {
+ return $this->profiles;
+ }
+
+ $profiles = [];
+
+ foreach ($this->collectCore() as $profile) {
+ $profiles[$profile->qualifiedKey()] = $profile;
+ }
+
+ foreach ($this->collectExtensions() as $profile) {
+ $profiles[$profile->qualifiedKey()] = $profile;
+ }
+
+ return $this->profiles = $profiles;
+ }
+
+ /**
+ * 특정 축의 프로파일만 반환합니다.
+ *
+ * @param BenchmarkAxis $axis 대상 축
+ * @return array 정규화 키 → 프로파일
+ */
+ public function byAxis(BenchmarkAxis $axis): array
+ {
+ return array_filter($this->all(), fn (BenchmarkProfile $profile) => $profile->axis === $axis);
+ }
+
+ /**
+ * 키로 프로파일을 해석합니다.
+ *
+ * 정규화 키(`sirsoft-ecommerce/orders`)를 우선 대조하고, 없으면 짧은 키로 찾습니다.
+ * 짧은 키가 둘 이상의 확장에서 선언돼 모호하면 후보 목록을 사유로 돌려줍니다 —
+ * 임의로 하나를 고르면 어느 확장의 목록을 잰 것인지 알 수 없게 됩니다.
+ *
+ * @param string $key 프로파일 키 (정규화 키 또는 짧은 키)
+ * @return array{0: BenchmarkProfile|null, 1: string|null} [찾은 프로파일, 실패 사유]
+ */
+ public function resolve(string $key): array
+ {
+ $profiles = $this->all();
+
+ if (isset($profiles[$key])) {
+ return [$profiles[$key], null];
+ }
+
+ $matches = array_filter($profiles, fn (BenchmarkProfile $profile) => $profile->key === $key);
+
+ if ($matches === []) {
+ return [null, "등록되지 않은 프로파일: {$key} (--list-profiles 로 목록 확인)"];
+ }
+
+ if (count($matches) > 1) {
+ $candidates = implode(', ', array_keys($matches));
+
+ return [null, "프로파일 키가 모호합니다: {$key} — 다음 중 하나로 지정하세요: {$candidates}"];
+ }
+
+ return [reset($matches), null];
+ }
+
+ /**
+ * 키로 프로파일을 찾습니다. (해석 실패 시 null)
+ *
+ * 사유가 필요하면 `resolve()` 를 씁니다.
+ *
+ * @param string $key 프로파일 키 (정규화 키 또는 짧은 키)
+ * @return BenchmarkProfile|null 찾은 프로파일
+ */
+ public function find(string $key): ?BenchmarkProfile
+ {
+ return $this->resolve($key)[0];
+ }
+
+ /**
+ * 수집 중 무시된 선언의 사유 목록을 반환합니다.
+ *
+ * @return array 경고 메시지
+ */
+ public function warnings(): array
+ {
+ $this->all();
+
+ return $this->warnings;
+ }
+
+ /**
+ * 코어 프로파일을 수집합니다.
+ *
+ * @return array 코어 프로파일 목록
+ */
+ private function collectCore(): array
+ {
+ $declared = config('benchmark.profiles', []);
+
+ return $this->normalize(is_array($declared) ? $declared : [], 'core', 'core');
+ }
+
+ /**
+ * 활성 모듈/플러그인 프로파일을 수집합니다.
+ *
+ * @return array 확장 프로파일 목록
+ */
+ private function collectExtensions(): array
+ {
+ $profiles = [];
+
+ foreach ($this->moduleManager->getActiveModules() as $module) {
+ $profiles = array_merge(
+ $profiles,
+ $this->normalize($this->extract($module), 'module', $module->getIdentifier())
+ );
+ }
+
+ foreach ($this->pluginManager->getActivePlugins() as $plugin) {
+ $profiles = array_merge(
+ $profiles,
+ $this->normalize($this->extract($plugin), 'plugin', $plugin->getIdentifier())
+ );
+ }
+
+ return $profiles;
+ }
+
+ /**
+ * 확장의 `getBenchmarkProfiles()` 선언을 격리 호출로 읽습니다.
+ *
+ * @param object $extension 확장 인스턴스
+ * @return array 선언 배열 (실패 시 빈 배열)
+ */
+ private function extract(object $extension): array
+ {
+ if (! method_exists($extension, 'getBenchmarkProfiles')) {
+ return [];
+ }
+
+ try {
+ $declared = $extension->getBenchmarkProfiles();
+ } catch (\Throwable $e) {
+ $this->warnings[] = sprintf(
+ '%s: getBenchmarkProfiles() 호출 실패 — %s',
+ method_exists($extension, 'getIdentifier') ? $extension->getIdentifier() : $extension::class,
+ $e->getMessage()
+ );
+
+ return [];
+ }
+
+ return is_array($declared) ? $declared : [];
+ }
+
+ /**
+ * 선언 배열을 검증해 프로파일 객체로 정규화합니다.
+ *
+ * @param array $declared 선언 배열 (키 → 정의)
+ * @param string $sourceKind 출처 종류 (core|module|plugin)
+ * @param string $sourceIdentifier 출처 식별자
+ * @return array 정규화된 프로파일 목록
+ */
+ private function normalize(array $declared, string $sourceKind, string $sourceIdentifier): array
+ {
+ $profiles = [];
+
+ foreach ($declared as $key => $definition) {
+ if (! is_string($key) || $key === '') {
+ $this->warnings[] = "{$sourceIdentifier}: 프로파일 키는 빈 문자열이 아닌 문자열이어야 합니다.";
+
+ continue;
+ }
+
+ if (! is_array($definition)) {
+ $this->warnings[] = "{$sourceIdentifier}/{$key}: 프로파일 정의는 배열이어야 합니다.";
+
+ continue;
+ }
+
+ $axis = BenchmarkAxis::tryFrom((string) ($definition['type'] ?? ''));
+
+ if ($axis === null) {
+ $this->warnings[] = sprintf(
+ '%s/%s: 알 수 없는 type — %s (허용: %s)',
+ $sourceIdentifier,
+ $key,
+ var_export($definition['type'] ?? null, true),
+ implode('|', BenchmarkAxis::values())
+ );
+
+ continue;
+ }
+
+ $missing = array_values(array_filter(
+ $axis->requiredOptions(),
+ fn (array $group) => array_filter(
+ $group,
+ fn (string $option) => isset($definition[$option])
+ ) === []
+ ));
+
+ if ($missing !== []) {
+ $this->warnings[] = sprintf(
+ '%s/%s: %s 축 필수 옵션 누락 — %s',
+ $sourceIdentifier,
+ $key,
+ $axis->value,
+ implode(', ', array_map(fn (array $group) => implode('|', $group), $missing))
+ );
+
+ continue;
+ }
+
+ $label = $definition['label'] ?? null;
+ unset($definition['type'], $definition['label']);
+
+ $profiles[] = new BenchmarkProfile(
+ key: $key,
+ axis: $axis,
+ sourceKind: $sourceKind,
+ sourceIdentifier: $sourceIdentifier,
+ options: $definition,
+ label: is_string($label) ? $label : null,
+ );
+ }
+
+ return $profiles;
+ }
+}
diff --git a/app/Benchmark/BenchmarkReporter.php b/app/Benchmark/BenchmarkReporter.php
new file mode 100644
index 00000000..08443a76
--- /dev/null
+++ b/app/Benchmark/BenchmarkReporter.php
@@ -0,0 +1,226 @@
+ 항목 → 값
+ */
+ public function environment(): array
+ {
+ return [
+ 'APP_ENV' => (string) config('app.env'),
+ 'G7 버전' => (string) config('app.version'),
+ 'DB 연결' => (string) config('database.default'),
+ 'DB 스키마' => $this->databaseName(),
+ 'DB 버전' => $this->databaseVersion(),
+ 'PHP 버전' => PHP_VERSION,
+ 'OPcache' => function_exists('opcache_get_status') && @opcache_get_status(false) !== false ? 'on' : 'off',
+ 'memory_limit' => (string) ini_get('memory_limit'),
+ 'config:cache' => app()->configurationIsCached() ? 'on' : 'off',
+ '실행 머신' => php_uname('s').' '.php_uname('r').' / '.php_uname('m'),
+ ];
+ }
+
+ /**
+ * JSON 으로 직렬화합니다.
+ *
+ * @param array $results 계측 결과
+ * @param BenchmarkRunOptions $options 실행 옵션
+ * @param array $warnings 프로파일 수집 경고
+ * @return string JSON 문자열
+ */
+ public function toJson(array $results, BenchmarkRunOptions $options, array $warnings = []): string
+ {
+ return (string) json_encode([
+ 'generated_at' => now()->toIso8601String(),
+ 'environment' => $this->environment(),
+ 'options' => $options->toArray(),
+ 'warnings' => $warnings,
+ 'results' => array_map(fn (BenchmarkResult $result) => $result->toArray(), $results),
+ ], JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
+ }
+
+ /**
+ * 마크다운 리포트를 만듭니다.
+ *
+ * @param array $results 계측 결과
+ * @param BenchmarkRunOptions $options 실행 옵션
+ * @param array $warnings 프로파일 수집 경고
+ * @return string 마크다운 문서
+ */
+ public function toMarkdown(array $results, BenchmarkRunOptions $options, array $warnings = []): string
+ {
+ $lines = [
+ '# G7 성능 점검 리포트',
+ '',
+ '- 생성 시각: '.now()->toDateTimeString(),
+ '',
+ '## 실행 환경',
+ '',
+ '| 항목 | 값 |',
+ '| ------ | ------ |',
+ ];
+
+ foreach ($this->environment() as $name => $value) {
+ $lines[] = "| {$name} | {$value} |";
+ }
+
+ $lines[] = '';
+ $lines[] = '계측값은 위 환경에 종속됩니다. 다른 리포트와 비교할 때는 환경이 같은지 먼저 확인하세요.';
+ $lines[] = '';
+ $lines[] = '## 실행 조건';
+ $lines[] = '';
+ $lines[] = '| 항목 | 값 |';
+ $lines[] = '| ------ | ------ |';
+
+ foreach ($options->toArray() as $name => $value) {
+ $lines[] = sprintf('| %s | %s |', $name, $this->stringify($value));
+ }
+
+ if ($warnings !== []) {
+ $lines[] = '';
+ $lines[] = '## 무시된 프로파일 선언';
+ $lines[] = '';
+
+ foreach ($warnings as $warning) {
+ $lines[] = '- '.$warning;
+ }
+ }
+
+ foreach (BenchmarkAxis::cases() as $axis) {
+ $axisResults = array_values(array_filter(
+ $results,
+ fn (BenchmarkResult $result) => $result->profile->axis === $axis
+ ));
+
+ if ($axisResults === []) {
+ continue;
+ }
+
+ $lines[] = '';
+ $lines[] = sprintf('## %s (%s)', $axis->label(), $axis->value);
+
+ foreach ($axisResults as $result) {
+ $lines = array_merge($lines, $this->markdownSection($result));
+ }
+ }
+
+ return implode("\n", $lines)."\n";
+ }
+
+ /**
+ * 결과 1건의 마크다운 절을 만듭니다.
+ *
+ * @param BenchmarkResult $result 계측 결과
+ * @return array 마크다운 줄 목록
+ */
+ private function markdownSection(BenchmarkResult $result): array
+ {
+ $title = $result->profile->qualifiedKey();
+
+ if ($result->profile->label !== null) {
+ $title .= ' — '.$result->profile->label;
+ }
+
+ $lines = ['', '### '.$title, ''];
+
+ if ($result->skipped) {
+ $lines[] = '측정하지 않음: '.$result->skipReason;
+
+ return $lines;
+ }
+
+ $lines[] = '| '.implode(' | ', $result->headers).' |';
+ $lines[] = '| '.implode(' | ', array_fill(0, count($result->headers), '------')).' |';
+
+ foreach ($result->rows as $row) {
+ $lines[] = '| '.implode(' | ', $row).' |';
+ }
+
+ if ($result->notes !== []) {
+ $lines[] = '';
+
+ foreach ($result->notes as $note) {
+ // 실행 계획/SQL 은 표 안에서 깨지므로 코드 스팬으로 감싼다
+ $lines[] = '- '.(str_contains($note, '|') ? '`'.$note.'`' : $note);
+ }
+ }
+
+ return $lines;
+ }
+
+ /**
+ * 옵션 값을 표에 넣을 문자열로 바꿉니다.
+ *
+ * @param mixed $value 옵션 값
+ * @return string 표시 문자열
+ */
+ private function stringify(mixed $value): string
+ {
+ return match (true) {
+ is_bool($value) => $value ? 'true' : 'false',
+ is_array($value) => implode(', ', array_map(fn (mixed $item) => (string) $item, $value)),
+ $value === null => '-',
+ default => (string) $value,
+ };
+ }
+
+ /**
+ * 계측이 사용한 DB 스키마명을 반환합니다.
+ *
+ * 읽기/쓰기 분리 설정에서는 스키마명이 `write`/`read` 하위에만 있어 최상위 `database`
+ * 가 비어 있습니다. 리포트에 스키마가 비면 어느 DB 를 잰 것인지 알 수 없으므로
+ * 세 위치를 순서대로 확인합니다.
+ *
+ * @return string 스키마명 (확인 불가 시 '-')
+ */
+ private function databaseName(): string
+ {
+ $connection = (string) config('database.default');
+
+ foreach (['database', 'write.database', 'read.database'] as $key) {
+ $name = config("database.connections.{$connection}.{$key}");
+
+ if (is_string($name) && $name !== '') {
+ return $name;
+ }
+ }
+
+ return '-';
+ }
+
+ /**
+ * DB 서버 버전을 조회합니다.
+ *
+ * @return string DB 버전 (조회 실패 시 '-')
+ */
+ private function databaseVersion(): string
+ {
+ try {
+ $row = DB::selectOne('select version() as version');
+
+ return (string) ($row->version ?? '-');
+ } catch (\Throwable) {
+ return '-';
+ }
+ }
+}
diff --git a/app/Benchmark/Contracts/BenchmarkAxisRunner.php b/app/Benchmark/Contracts/BenchmarkAxisRunner.php
new file mode 100644
index 00000000..1c264b26
--- /dev/null
+++ b/app/Benchmark/Contracts/BenchmarkAxisRunner.php
@@ -0,0 +1,34 @@
+ $options 축 고유 옵션
+ * @param string|null $label 표시용 설명
+ */
+ public function __construct(
+ public string $key,
+ public BenchmarkAxis $axis,
+ public string $sourceKind,
+ public string $sourceIdentifier,
+ public array $options = [],
+ public ?string $label = null,
+ ) {}
+
+ /**
+ * 출처를 포함한 전역 고유 키를 반환합니다.
+ *
+ * 서로 다른 확장이 같은 키(`orders` 등)를 선언할 수 있으므로 충돌 시에는 이 키로
+ * 지목합니다. 커맨드는 짧은 키가 유일할 때만 짧은 키를 허용합니다.
+ *
+ * @return string `{출처}/{키}` 형태의 정규화 키
+ */
+ public function qualifiedKey(): string
+ {
+ return $this->sourceIdentifier.'/'.$this->key;
+ }
+
+ /**
+ * 축 고유 옵션 값을 읽습니다.
+ *
+ * @param string $name 옵션 키
+ * @param mixed $default 미선언 시 기본값
+ * @return mixed 옵션 값
+ */
+ public function option(string $name, mixed $default = null): mixed
+ {
+ return $this->options[$name] ?? $default;
+ }
+
+ /**
+ * 이 프로파일 실행이 데이터를 변경하는지 판정합니다.
+ *
+ * 축 기본값을 쓰되, 프로파일이 `mutating` 을 명시하면 그 선언을 따릅니다.
+ * `screen` 축은 GET 이 아니면 변경으로 봅니다.
+ *
+ * @return bool 데이터 변경 여부
+ */
+ public function mutates(): bool
+ {
+ $declared = $this->options['mutating'] ?? null;
+
+ if (is_bool($declared)) {
+ return $declared;
+ }
+
+ if ($this->axis === BenchmarkAxis::Screen) {
+ return strtoupper((string) $this->option('method', 'GET')) !== 'GET';
+ }
+
+ return $this->axis->mutatesByDefault();
+ }
+
+ /**
+ * 배열로 직렬화합니다. (`--json` / 리포트 출력용)
+ *
+ * @return array 직렬화 결과
+ */
+ public function toArray(): array
+ {
+ return [
+ 'key' => $this->key,
+ 'qualified_key' => $this->qualifiedKey(),
+ 'axis' => $this->axis->value,
+ 'source' => ['kind' => $this->sourceKind, 'identifier' => $this->sourceIdentifier],
+ 'label' => $this->label,
+ 'options' => $this->options,
+ ];
+ }
+}
diff --git a/app/Benchmark/DTO/BenchmarkResult.php b/app/Benchmark/DTO/BenchmarkResult.php
new file mode 100644
index 00000000..a39170ca
--- /dev/null
+++ b/app/Benchmark/DTO/BenchmarkResult.php
@@ -0,0 +1,68 @@
+ $headers 표 헤더
+ * @param array> $rows 표 행 (표시용 문자열)
+ * @param array $metrics 기계 판독용 원시 수치
+ * @param array $notes 부가 설명 줄 (실행 계획, N+1 후보 등)
+ * @param bool $skipped 실행하지 않았는지 여부
+ * @param string|null $skipReason 실행하지 않은 사유
+ */
+ public function __construct(
+ public BenchmarkProfile $profile,
+ public array $headers = [],
+ public array $rows = [],
+ public array $metrics = [],
+ public array $notes = [],
+ public bool $skipped = false,
+ public ?string $skipReason = null,
+ ) {}
+
+ /**
+ * 실행하지 않은 결과를 만듭니다.
+ *
+ * 실패/건너뜀을 결과 목록에서 빼면 리포트가 "전부 측정됨"으로 읽히므로, 사유를 담은
+ * 결과로 남겨 표와 JSON 양쪽에 드러냅니다.
+ *
+ * @param BenchmarkProfile $profile 대상 프로파일
+ * @param string $reason 건너뛴 사유
+ * @return self 건너뜀 결과
+ */
+ public static function skipped(BenchmarkProfile $profile, string $reason): self
+ {
+ return new self(profile: $profile, skipped: true, skipReason: $reason);
+ }
+
+ /**
+ * 배열로 직렬화합니다.
+ *
+ * @return array 직렬화 결과
+ */
+ public function toArray(): array
+ {
+ return [
+ 'profile' => $this->profile->qualifiedKey(),
+ 'axis' => $this->profile->axis->value,
+ 'label' => $this->profile->label,
+ 'source' => ['kind' => $this->profile->sourceKind, 'identifier' => $this->profile->sourceIdentifier],
+ 'skipped' => $this->skipped,
+ 'skip_reason' => $this->skipReason,
+ 'headers' => $this->headers,
+ 'rows' => $this->rows,
+ 'metrics' => $this->metrics,
+ 'notes' => $this->notes,
+ ];
+ }
+}
diff --git a/app/Benchmark/DTO/BenchmarkRunOptions.php b/app/Benchmark/DTO/BenchmarkRunOptions.php
new file mode 100644
index 00000000..f93366b3
--- /dev/null
+++ b/app/Benchmark/DTO/BenchmarkRunOptions.php
@@ -0,0 +1,52 @@
+ $offsets 측정할 OFFSET 목록 (list 축)
+ * @param int $runs 측정 횟수 (첫 회는 버림)
+ * @param int $seed 계측 전 합성 행 시딩 건수 (0 = 시딩 안 함, list 축)
+ * @param bool $fresh 시딩 전 대상 테이블 비움 (list 축)
+ * @param bool $explain 실행 계획 수집 (list 축)
+ * @param bool $allowWrite 데이터 변경 축 실행 허용
+ * @param string|null $asUser 계측에 사용할 기존 계정 (ID 또는 이메일, screen 축)
+ * @param int $perPage 목록/화면 1페이지 건수
+ */
+ public function __construct(
+ public array $offsets = [0],
+ public int $runs = 3,
+ public int $seed = 0,
+ public bool $fresh = false,
+ public bool $explain = false,
+ public bool $allowWrite = false,
+ public ?string $asUser = null,
+ public int $perPage = 20,
+ ) {}
+
+ /**
+ * 배열로 직렬화합니다. (리포트의 실행 조건 기재용)
+ *
+ * @return array 직렬화 결과
+ */
+ public function toArray(): array
+ {
+ return [
+ 'offsets' => $this->offsets,
+ 'runs' => $this->runs,
+ 'seed' => $this->seed,
+ 'fresh' => $this->fresh,
+ 'explain' => $this->explain,
+ 'allow_write' => $this->allowWrite,
+ 'as_user' => $this->asUser,
+ 'per_page' => $this->perPage,
+ ];
+ }
+}
diff --git a/app/Benchmark/ListIndexAdvisor.php b/app/Benchmark/ListIndexAdvisor.php
new file mode 100644
index 00000000..e0123728
--- /dev/null
+++ b/app/Benchmark/ListIndexAdvisor.php
@@ -0,0 +1,203 @@
+ $options 목록 프로파일 옵션
+ * @return array 선행 컬럼 순서 (등치 → deleted_at → 정렬 → 기본키)
+ */
+ public function requiredColumns(array $options, string $keyName = 'id'): array
+ {
+ $leading = [];
+
+ foreach (($options['filters'] ?? []) as $column => $declared) {
+ if (is_array($declared) && count($declared) === 2 && is_string($declared[0])) {
+ // [연산자, 값] 형태 — 등치만 선행 컬럼 자격이 있다
+ if (in_array(strtolower($declared[0]), self::EQUALITY_OPERATORS, true)) {
+ $leading[] = (string) $column;
+ }
+
+ continue;
+ }
+
+ // 값만 준 형태는 등가 비교
+ $leading[] = (string) $column;
+ }
+
+ if ($options['soft_delete'] ?? false) {
+ $leading[] = 'deleted_at';
+ }
+
+ foreach (($options['order'] ?? []) as $spec) {
+ $column = is_array($spec) ? ($spec[0] ?? null) : $spec;
+
+ if (is_string($column) && $column !== '') {
+ $leading[] = $column;
+ }
+ }
+
+ // 정렬 끝에 기본키가 없으면 동률 구간에서 filesort 가 남는다
+ if (end($leading) !== $keyName) {
+ $leading[] = $keyName;
+ }
+
+ return array_values(array_unique($leading));
+ }
+
+ /**
+ * 도출한 색인이 실제 스키마에 있는지 대조합니다.
+ *
+ * @param array $options 목록 프로파일 옵션
+ * @return array{
+ * table: string|null,
+ * required: array,
+ * satisfied_by: string|null,
+ * partial_by: string|null,
+ * status: string
+ * } status: satisfied | tiebreak_missing | missing | table_absent | not_applicable
+ */
+ public function inspect(array $options, string $keyName = 'id'): array
+ {
+ $table = $options['table'] ?? null;
+ $required = $this->requiredColumns($options, $keyName);
+
+ $result = [
+ 'table' => $table,
+ 'required' => $required,
+ 'satisfied_by' => null,
+ 'partial_by' => null,
+ 'status' => 'not_applicable',
+ ];
+
+ if (! is_string($table) || $table === '') {
+ return $result;
+ }
+
+ if (! Schema::hasTable($table)) {
+ $result['status'] = 'table_absent';
+
+ return $result;
+ }
+
+ // 기본키를 뺀 형태 — 색인은 있으나 tie-break 만 빠진 경우를 구분한다.
+ // 이 둘은 처방이 다르다: 전자는 색인 신설, 후자는 기존 색인에 기본키를 덧붙이는 교체.
+ $withoutKey = $required;
+ if (end($withoutKey) === $keyName) {
+ array_pop($withoutKey);
+ }
+
+ foreach (Schema::getIndexes($table) as $index) {
+ $columns = $index['columns'] ?? [];
+
+ if ($result['satisfied_by'] === null && $this->hasPrefix($columns, $required)) {
+ $result['satisfied_by'] = $index['name'];
+ }
+
+ if ($this->hasPrefix($columns, $withoutKey)) {
+ // UNIQUE 색인은 값이 중복되지 않으므로 그 컬럼만으로 이미 전순서다.
+ // 기본키를 덧붙일 필요가 없고, 붙여도 filesort 가 줄지 않는다.
+ if ($result['satisfied_by'] === null && ($index['unique'] ?? false)) {
+ $result['satisfied_by'] = $index['name'];
+ }
+
+ if ($result['partial_by'] === null) {
+ $result['partial_by'] = $index['name'];
+ }
+ }
+ }
+
+ $result['status'] = match (true) {
+ $result['satisfied_by'] !== null => 'satisfied',
+ $result['partial_by'] !== null => 'tiebreak_missing',
+ default => 'missing',
+ };
+
+ return $result;
+ }
+
+ /**
+ * 프로파일에 선언된 면제 사유를 돌려줍니다.
+ *
+ * 행 수가 고정되거나 상한이 작아 색인이 불필요한 목록은 프로파일에 사유를 적어 면제한다.
+ * 사유 없는 면제를 허용하지 않는 이유는, 면제가 쌓이면 검사 자체가 무의미해지는데
+ * 사유가 없으면 나중에 그 판단이 여전히 옳은지 확인할 방법이 없기 때문이다.
+ *
+ * @param array $options 목록 프로파일 옵션
+ * @return string|null 면제 사유 (없으면 null)
+ */
+ public function exemptionReason(array $options): ?string
+ {
+ $reason = $options['index_exempt'] ?? null;
+
+ return is_string($reason) && trim($reason) !== '' ? trim($reason) : null;
+ }
+
+ /**
+ * 프로파일 목록을 한 번에 점검합니다.
+ *
+ * @param array $profiles 목록 축 프로파일
+ * @return array> 프로파일별 점검 결과
+ */
+ public function inspectAll(array $profiles): array
+ {
+ $rows = [];
+
+ foreach ($profiles as $key => $profile) {
+ $options = $profile->options ?? [];
+
+ $rows[] = array_merge(
+ ['profile' => is_string($key) ? $key : $profile->qualifiedKey()],
+ $this->inspect($options),
+ ['exemption' => $this->exemptionReason($options)]
+ );
+ }
+
+ return $rows;
+ }
+
+ /**
+ * 인덱스 컬럼이 요구 목록을 선행 프리픽스로 포함하는지 판정합니다.
+ *
+ * @param array $columns 인덱스 컬럼 순서
+ * @param array $required 요구 선행 컬럼
+ */
+ private function hasPrefix(array $columns, array $required): bool
+ {
+ if ($required === [] || count($columns) < count($required)) {
+ return false;
+ }
+
+ return array_slice(array_values($columns), 0, count($required)) === array_values($required);
+ }
+}
diff --git a/app/Benchmark/QueryCollector.php b/app/Benchmark/QueryCollector.php
new file mode 100644
index 00000000..9d51691e
--- /dev/null
+++ b/app/Benchmark/QueryCollector.php
@@ -0,0 +1,102 @@
+
+ */
+ private array $queries = [];
+
+ public function __construct()
+ {
+ DB::listen(function (QueryExecuted $event) {
+ if (! $this->collecting) {
+ return;
+ }
+
+ $this->queries[] = ['sql' => $event->sql, 'time' => (float) $event->time];
+ });
+ }
+
+ /**
+ * 콜백 실행 구간의 쿼리를 수집합니다.
+ *
+ * @template TReturn
+ *
+ * @param \Closure(): TReturn $callback 계측 대상 작업
+ * @return array{value: TReturn, queries: array} 반환값과 수집 결과
+ */
+ public function collect(\Closure $callback): array
+ {
+ $this->queries = [];
+ $this->collecting = true;
+
+ try {
+ $value = $callback();
+ } finally {
+ $this->collecting = false;
+ }
+
+ return ['value' => $value, 'queries' => $this->queries];
+ }
+
+ /**
+ * 수집된 쿼리를 요약합니다.
+ *
+ * @param array $queries 수집 결과
+ * @return array{count: int, db_ms: float, n_plus_one: array} 요약
+ */
+ public function summarize(array $queries): array
+ {
+ $grouped = [];
+
+ foreach ($queries as $query) {
+ $grouped[$query['sql']] = ($grouped[$query['sql']] ?? 0) + 1;
+ }
+
+ arsort($grouped);
+
+ $candidates = [];
+
+ foreach ($grouped as $sql => $count) {
+ if ($count < self::N_PLUS_ONE_THRESHOLD) {
+ continue;
+ }
+
+ $candidates[] = ['count' => $count, 'sql' => $sql];
+ }
+
+ return [
+ 'count' => count($queries),
+ 'db_ms' => round(array_sum(array_column($queries, 'time')), 2),
+ 'n_plus_one' => $candidates,
+ ];
+ }
+}
diff --git a/app/Benchmark/SyntheticSeeder.php b/app/Benchmark/SyntheticSeeder.php
new file mode 100644
index 00000000..74ba17ac
--- /dev/null
+++ b/app/Benchmark/SyntheticSeeder.php
@@ -0,0 +1,234 @@
+ $overrides 컬럼별 고정값 (실제 조회 조건과 맞추기 위한 지정)
+ * @param \Closure|null $onProgress 진행 콜백 (int $inserted, int $total)
+ * @param array $requiredColumns nullable 이어도 반드시 채울 컬럼 (계측이 정렬 기준으로 삼는 컬럼)
+ */
+ public function seed(string $table, int $count, array $overrides = [], ?\Closure $onProgress = null, array $requiredColumns = []): void
+ {
+ $fillable = $this->fillableColumns($table);
+ $required = $this->requiredColumnDefinitions($table, $requiredColumns, $fillable);
+
+ $chunk = [];
+ $inserted = 0;
+
+ for ($i = 1; $i <= $count; $i++) {
+ $chunk[] = $this->synthesizeRow($table, array_merge($fillable, $required), $overrides, $i);
+
+ if (count($chunk) >= self::CHUNK_SIZE) {
+ $this->insert($table, $chunk);
+ $inserted += count($chunk);
+ $chunk = [];
+
+ if ($onProgress !== null) {
+ $onProgress($inserted, $count);
+ }
+ }
+ }
+
+ if ($chunk !== []) {
+ $this->insert($table, $chunk);
+ $inserted += count($chunk);
+
+ if ($onProgress !== null) {
+ $onProgress($inserted, $count);
+ }
+ }
+ }
+
+ /**
+ * 대상 테이블을 비웁니다.
+ *
+ * 다른 테이블이 FK 로 참조하면 TRUNCATE 가 거부되므로 제약을 잠시 내립니다.
+ *
+ * @param string $table 대상 테이블
+ */
+ public function truncate(string $table): void
+ {
+ Schema::withoutForeignKeyConstraints(function () use ($table) {
+ DB::table($table)->truncate();
+ });
+ }
+
+ /**
+ * 값을 반드시 채워야 하는 컬럼 목록을 반환합니다.
+ *
+ * @param string $table 대상 테이블
+ * @return array> Schema::getColumns() 항목 목록
+ */
+ private function fillableColumns(string $table): array
+ {
+ return array_values(array_filter(
+ Schema::getColumns($table),
+ fn (array $column) => ! ($column['auto_increment'] ?? false)
+ && ! $column['nullable']
+ && ($column['default'] === null)
+ ));
+ }
+
+ /**
+ * 계측이 정렬 기준으로 삼는 컬럼의 정의를 반환합니다.
+ *
+ * `fillableColumns()` 는 "NOT NULL + 기본값 없음" 만 남기므로, Laravel 기본 `timestamps()`
+ * 처럼 nullable 로 선언된 `created_at` 계열은 여기서 빠진다. 그런데 목록 프로파일 대부분이
+ * `created_at` 으로 정렬하므로, 그대로 두면 합성 행이 전부 NULL 동률이 되어 계측이
+ * 정렬 인덱스가 아니라 tie-break 경로를 재게 된다.
+ *
+ * @param string $table 대상 테이블
+ * @param array $names 반드시 채울 컬럼명 목록
+ * @param array> $already 이미 채우기로 한 컬럼 목록
+ * @return array> 추가로 채울 컬럼 정의 목록
+ */
+ private function requiredColumnDefinitions(string $table, array $names, array $already): array
+ {
+ if ($names === []) {
+ return [];
+ }
+
+ $covered = array_column($already, 'name');
+ $columns = collect(Schema::getColumns($table))->keyBy('name');
+
+ $extra = [];
+
+ foreach (array_unique($names) as $name) {
+ if (in_array($name, $covered, true) || ! $columns->has($name)) {
+ continue;
+ }
+
+ $column = $columns->get($name);
+
+ // auto increment 키는 DB 가 채운다
+ if ($column['auto_increment'] ?? false) {
+ continue;
+ }
+
+ $extra[] = $column;
+ }
+
+ return $extra;
+ }
+
+ /**
+ * 합성 행 1건을 만듭니다.
+ *
+ * @param string $table 대상 테이블
+ * @param array> $fillable 채워야 하는 컬럼 목록
+ * @param array $overrides 컬럼별 고정값
+ * @param int $index 행 인덱스 (고유값 생성용)
+ * @return array 합성 행
+ */
+ private function synthesizeRow(string $table, array $fillable, array $overrides, int $index): array
+ {
+ $row = [];
+
+ foreach ($fillable as $column) {
+ $row[$column['name']] = array_key_exists($column['name'], $overrides)
+ ? $overrides[$column['name']]
+ : $this->synthesizeValue($column, $index);
+ }
+
+ // NULL 허용 컬럼이라 위 루프에서 빠졌더라도, 실제 조회 조건에 쓰이는 컬럼은
+ // 채워야 계측이 화면과 같은 인덱스를 타게 된다.
+ foreach ($overrides as $name => $value) {
+ if (! array_key_exists($name, $row) && Schema::hasColumn($table, $name)) {
+ $row[$name] = $value;
+ }
+ }
+
+ return $row;
+ }
+
+ /**
+ * 합성 행을 삽입합니다. (외래키 제약 일시 해제)
+ *
+ * @param string $table 대상 테이블
+ * @param array> $chunk 삽입할 행 묶음
+ */
+ private function insert(string $table, array $chunk): void
+ {
+ Schema::withoutForeignKeyConstraints(function () use ($table, $chunk) {
+ DB::table($table)->insert($chunk);
+ });
+ }
+
+ /**
+ * 컬럼 타입에 맞는 합성 값을 만듭니다.
+ *
+ * @param array $column Schema::getColumns() 항목
+ * @param int $index 행 인덱스 (고유값 생성용)
+ * @return mixed 합성 값
+ */
+ private function synthesizeValue(array $column, int $index): mixed
+ {
+ $type = strtolower((string) ($column['type_name'] ?? $column['type'] ?? 'varchar'));
+
+ return match (true) {
+ str_contains($type, 'int') => $index,
+ str_contains($type, 'decimal'), str_contains($type, 'float'), str_contains($type, 'double') => 1000,
+ str_contains($type, 'bool'), str_contains($type, 'tinyint') => 0,
+ str_contains($type, 'json') => '{}',
+ // 시간 컬럼을 한 값으로 채우면 정렬이 전부 동률이 되어 filesort 가 지배해 버린다.
+ // 정렬 인덱스 효과를 재는 것이 목적이므로 행마다 값을 분산시킨다.
+ str_contains($type, 'date'), str_contains($type, 'time') => now()->subMinutes($index),
+ str_contains($type, 'text') => str_repeat('벤치마크 본문 ', 100),
+ default => $this->synthesizeString($column, $index),
+ };
+ }
+
+ /**
+ * 문자열 컬럼의 선언 길이에 맞는 합성 값을 만듭니다.
+ *
+ * 컬럼 길이를 무시하고 고정 길이 문자열을 넣으면 `varchar(10)` 류(신고 대상 타입,
+ * 우편번호, 로그 타입 등)에서 "Data too long" 으로 시딩 자체가 실패한다.
+ *
+ * @param array $column Schema::getColumns() 항목
+ * @param int $index 행 인덱스 (고유값 생성용)
+ * @return string 합성 문자열
+ */
+ private function synthesizeString(array $column, int $index): string
+ {
+ $length = 40;
+
+ // type 은 'varchar(10)' 형태로 선언 길이를 담고 있다
+ if (preg_match('/\((\d+)\)/', (string) ($column['type'] ?? ''), $m) === 1) {
+ $length = max(1, (int) $m[1]);
+ }
+
+ // 짧은 컬럼은 고유성 확보가 우선이라 인덱스 자체를 문자열로 쓴다
+ if ($length <= 12) {
+ return substr((string) $index, -$length);
+ }
+
+ return substr("bench-{$index}-".Str::random(8), 0, $length);
+ }
+}
diff --git a/app/Console/Commands/ApiDocgenCommand.php b/app/Console/Commands/ApiDocgenCommand.php
index a6596c00..53c07d72 100644
--- a/app/Console/Commands/ApiDocgenCommand.php
+++ b/app/Console/Commands/ApiDocgenCommand.php
@@ -126,6 +126,7 @@ class ApiDocgenCommand extends Command
$stats = ['files' => 0, 'endpoints' => 0, 'probed' => 0, 'skipped' => 0, 'examples' => 0];
$checkFindings = [];
+ $skippedProbes = [];
$examplesOnly = (bool) $this->option('examples-only');
// 대상(코어/확장)별 README 목차 항목 누적: readmeKey => ['label' => ..., 'entries' => [...]]
@@ -136,6 +137,17 @@ class ApiDocgenCommand extends Command
$sectionKeys = [];
$exampleBlocks = [];
+ // `Route::match(['get','post'], ...)->name('x')` 는 하나의 라우트명으로 두 엔드포인트를
+ // 등록한다. 생성 블록 키가 라우트명뿐이면 한 문서에 같은 키가 둘 생겨, 블록 조회(strpos)가
+ // 언제나 첫 블록만 잡아 두 번째 블록의 사람 서술이 재생성마다 유실된다.
+ // 문서 안에서 중복되는 라우트명만 골라 키에 메서드를 붙인다 (나머지 키는 그대로 — 전 문서의
+ // 키를 바꾸면 기존 블록과 대조가 어긋나 사람 서술이 통째로 사라진다).
+ $nameCounts = array_count_values(array_map(
+ static fn (array $r): string => $r['name'] ?: $r['uri'],
+ $items,
+ ));
+ $duplicatedNames = array_keys(array_filter($nameCounts, static fn (int $n): bool => $n > 1));
+
// 목차용 도메인 파일 항목 (소유별). 예시-only/check 모드에서도 목차는 최신화한다.
$owner = $items[0]['owner'];
$readmeKey = $this->readmeFile($owner);
@@ -156,10 +168,14 @@ class ApiDocgenCommand extends Command
$stats['probed']++;
} else {
$stats['skipped']++;
- $checkFindings[] = "{$route['method']} {$route['uri']} — {$probeMeta['skipped_reason']}";
+ // 실측 제외는 설계상 정상이다 — 부수효과 쓰기·미치환 path·검증 실패는 의도적으로
+ // 호출하지 않고, 그 자리는 사람이 코드 근거로 채운다. drift 로 세면 문서가 완전해도
+ // --check 가 통과할 수 없어 기준이 무의미해진다. 정보로만 남긴다.
+ $skippedProbes[] = "{$route['method']} {$route['uri']} — {$probeMeta['skipped_reason']}";
}
- $key = $route['name'] ?: $route['uri'];
+ $methodScopedKey = in_array($route['name'] ?: $route['uri'], $duplicatedNames, true);
+ $key = $scaffolder->generatedKey($route, $methodScopedKey);
if ($examplesOnly) {
// 표·서술을 건드리지 않고 예시 2블록만 산출 (SSoT=스캐폴더 예시 메서드).
@@ -179,7 +195,7 @@ class ApiDocgenCommand extends Command
}
$commentMap = $this->columnComments($route, $commentResolver, $sampleMap);
- $sections[] = $scaffolder->endpointSection($route, $request, $schema, $probeMeta, $commentMap);
+ $sections[] = $scaffolder->endpointSection($route, $request, $schema, $probeMeta, $commentMap, $methodScopedKey);
$sectionKeys[] = $key;
$stats['endpoints']++;
}
@@ -187,6 +203,12 @@ class ApiDocgenCommand extends Command
if ($this->option('check')) {
if (! File::exists($file)) {
$checkFindings[] = "문서 파일 없음: {$file}";
+ } else {
+ // 실측 불가 자리를 사람이 채우지 않고 마커로 남겨 두면 문서가 미완이다.
+ // (규정: docs/backend/api-documentation.md "미채움 마커 5종")
+ foreach ($this->unfilledMarkers(File::get($file)) as $marker) {
+ $checkFindings[] = "미채움 마커: {$file} — {$marker}";
+ }
}
continue;
@@ -216,6 +238,15 @@ class ApiDocgenCommand extends Command
$header = $this->documentHeader($file, $items[0]);
$existing = File::exists($file) ? File::get($file) : null;
+
+ // 기존 문서는 중복 라우트명 블록을 구 키(라우트명만)로 갖고 있다. 그대로 두면 새 키
+ // (라우트명::메서드)와 대조되지 않아 이번 재생성에서 그 블록의 사람 서술이 유실된다.
+ // 병합 전에 구 키를 등장 순서대로 새 키로 승격한다 — 문서 내 블록 순서는 $items 순서와
+ // 같으므로(같은 그룹을 같은 순서로 순회) 메서드 대응이 어긋나지 않는다.
+ if ($existing !== null && $duplicatedNames !== []) {
+ $existing = $this->migrateDuplicateBlockKeys($existing, $items, $duplicatedNames, $scaffolder);
+ }
+
$content = $scaffolder->mergeDocument($existing, $header, $sections, $sectionKeys);
File::ensureDirectoryExists(dirname($file));
@@ -253,8 +284,20 @@ class ApiDocgenCommand extends Command
}
if ($this->option('check')) {
+ // 실측 제외는 정상 동작이므로 참고 정보로만 표시한다 (drift 아님).
+ if ($skippedProbes !== []) {
+ $this->line('실측 제외 '.count($skippedProbes).'건 (정상 — 해당 자리는 사람이 작성):');
+ foreach (array_slice($skippedProbes, 0, 10) as $s) {
+ $this->line(' · '.$s);
+ }
+ if (count($skippedProbes) > 10) {
+ $this->line(' · ... 외 '.(count($skippedProbes) - 10).'건');
+ }
+ $this->newLine();
+ }
+
if ($checkFindings !== []) {
- $this->warn('실측 제외/문서 누락 '.count($checkFindings).'건:');
+ $this->warn('drift '.count($checkFindings).'건:');
foreach (array_slice($checkFindings, 0, 50) as $f) {
$this->line(' - '.$f);
}
@@ -899,6 +942,92 @@ class ApiDocgenCommand extends Command
return base_path("{$base}/_bundled/{$owner['id']}/docs/api/README.md");
}
+ /**
+ * 문서에 남아 있는 미채움 마커를 수집합니다.
+ *
+ * `api:docgen` 은 실측 불가한 자리에 "사람이 작성하세요" 마커를 남긴다. 실측 불가는 그 자리를
+ * 비워둘 사유가 아니며, 컨트롤러/Resource/FormRequest/Enum/lang 을 읽어 채우는 것이 규정이다
+ * (docs/backend/api-documentation.md "미채움 마커 5종"). 마커가 남아 있으면 문서는 미완이다.
+ *
+ * 잔량 전수 집계는 `check-api-doc-unfilled.cjs` 가 담당하고, 여기서는 `--check` 가 자기 scope
+ * 문서의 미완을 drift 로 잡기 위해 마커 종류만 요약한다.
+ *
+ * @param string $content 문서 내용
+ * @return array 발견된 마커 요약 (종류 => 건수)
+ */
+ private function unfilledMarkers(string $content): array
+ {
+ $markers = [
+ '실측 제외:' => '실측 제외 (응답 필드 표 / 응답 예시)',
+ 'TODO: 용도' => '요청 파라미터 설명',
+ 'TODO: 설명' => '응답 필드 설명',
+ '실측 응답에 필드 없음' => '빈 목록 관측 (응답 필드 표)',
+ '대표 에러 없음' => '도메인 특이 에러',
+ ];
+
+ $found = [];
+
+ foreach ($markers as $needle => $label) {
+ $count = substr_count($content, $needle);
+
+ if ($count > 0) {
+ $found[] = "{$label} {$count}건";
+ }
+ }
+
+ return $found;
+ }
+
+ /**
+ * 기존 문서의 중복 생성 블록 키를 메서드 스코프 키로 승격합니다.
+ *
+ * `Route::match(['get','post'], ...)->name('x')` 로 등록된 라우트는 한 문서에 같은
+ * `@generated:start:x` 블록을 둘 만든다. 새 키(`x::get` / `x::post`)로 재생성하면 구 키를
+ * 가진 기존 블록과 대조되지 않아 그 블록의 사람 서술이 유실되므로, 병합 전에 구 키를
+ * 등장 순서대로 새 키로 바꿔 준다.
+ *
+ * 문서 내 블록 순서는 `$items` 순서와 같다(같은 그룹을 같은 순서로 순회해 생성했다).
+ * 따라서 n 번째 구 키 블록에는 그 라우트명을 가진 n 번째 라우트의 메서드를 붙인다.
+ *
+ * @param string $existing 기존 문서 내용
+ * @param array> $items 이 문서의 라우트 목록 (문서 순서)
+ * @param array $duplicatedNames 문서 안에서 중복되는 라우트명
+ * @param ApiDocScaffolder $scaffolder 키 생성기
+ * @return string 키가 승격된 문서 내용
+ */
+ private function migrateDuplicateBlockKeys(
+ string $existing,
+ array $items,
+ array $duplicatedNames,
+ ApiDocScaffolder $scaffolder
+ ): string {
+ foreach ($duplicatedNames as $name) {
+ $methods = array_values(array_map(
+ static fn (array $r): string => $r['method'],
+ array_filter($items, static fn (array $r): bool => ($r['name'] ?: $r['uri']) === $name),
+ ));
+
+ $marker = '';
+ $offset = 0;
+
+ foreach ($methods as $method) {
+ $pos = strpos($existing, $marker, $offset);
+
+ if ($pos === false) {
+ break;
+ }
+
+ $newKey = $scaffolder->generatedKey(['name' => $name, 'uri' => $name, 'method' => $method], true);
+ $newMarker = '';
+
+ $existing = substr_replace($existing, $newMarker, $pos, strlen($marker));
+ $offset = $pos + strlen($newMarker);
+ }
+ }
+
+ return $existing;
+ }
+
/**
* 문서 헤더(제목 + TL;DR)를 생성합니다.
*
@@ -923,7 +1052,7 @@ class ApiDocgenCommand extends Command
```text
1. 이 문서는 실제 API 호출로 실측한 {$domain} 엔드포인트 레퍼런스입니다
- 2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(curl) + 실측 응답 필드 표 + 응답 예시(envelope)
+ 2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다
diff --git a/app/Console/Commands/AssetUrlModeCommand.php b/app/Console/Commands/AssetUrlModeCommand.php
new file mode 100644
index 00000000..8122e771
--- /dev/null
+++ b/app/Console/Commands/AssetUrlModeCommand.php
@@ -0,0 +1,125 @@
+argument('mode');
+
+ if ($requested === null) {
+ $this->showStatus($current);
+
+ return Command::SUCCESS;
+ }
+
+ if (! in_array($requested, [AssetUrl::MODE_EXTENSION, AssetUrl::MODE_EXTENSIONLESS], true)) {
+ $this->error(__('asset_url_mode.invalid', ['mode' => $requested]));
+
+ return Command::FAILURE;
+ }
+
+ if ($requested === $current) {
+ $this->info(__('asset_url_mode.already', ['mode' => $current]));
+
+ return Command::SUCCESS;
+ }
+
+ $saved = $settingsService->saveSettings([
+ '_tab' => 'general',
+ 'general' => ['asset_url_mode' => $requested],
+ ]);
+
+ if (! $saved) {
+ $this->error(__('asset_url_mode.save_failed'));
+
+ return Command::FAILURE;
+ }
+
+ // SEO 프리렌더 캐시에는 생성 시점의 자산 URL 이 그대로 구워져 있다.
+ // 모드를 바꾸면 그 URL 들이 전부 어긋나므로 함께 비운다 (계획서 §알려진 한계).
+ $seoCacheManager->clearAll();
+
+ $this->info(__('asset_url_mode.switched', ['from' => $current, 'to' => $requested]));
+ $this->line(__('asset_url_mode.seo_cache_cleared'));
+
+ return Command::SUCCESS;
+ }
+
+ /**
+ * 현재 모드와 진단 안내를 출력합니다.
+ *
+ * @param string $current 현재 모드
+ */
+ private function showStatus(string $current): void
+ {
+ $this->line('');
+ $this->line(' '.__('asset_url_mode.current', ['mode' => $current]));
+ $this->line('');
+
+ // audit:allow asset-url-builder-required reason: 두 모드의 URL 형태를 나란히
+ // 보여주는 대조표라 빌더로 생성할 수 없다 (빌더는 현재 모드 하나만 만든다).
+ $rows = $current === AssetUrl::MODE_EXTENSION
+ ? [
+ ['/api/templates/{id}/routes.json', '/api/templates/{id}/routes'],
+ ['/api/modules/bundle.js', '/api/modules/bundle/js'],
+ ['/api/templates/assets/{id}/js/a.js', '/api/templates/assets/{id}?file=js/a.js'],
+ ]
+ : [
+ ['/api/templates/{id}/routes', '/api/templates/{id}/routes.json'],
+ ['/api/modules/bundle/js', '/api/modules/bundle.js'],
+ ['/api/templates/assets/{id}?file=js/a.js', '/api/templates/assets/{id}/js/a.js'],
+ ];
+
+ $this->table(
+ [__('asset_url_mode.table.in_use'), __('asset_url_mode.table.alternative')],
+ $rows,
+ );
+
+ $this->line(' '.__('asset_url_mode.diagnose_title'));
+ $this->line(' curl -i '.rtrim(config('app.url'), '/').'/api/system/asset-probe.js');
+ $this->line(' curl -i '.rtrim(config('app.url'), '/').'/api/system/asset-probe');
+ $this->line('');
+ $this->line(' '.__('asset_url_mode.diagnose_hint'));
+ $this->line('');
+ $this->line(' '.__('asset_url_mode.switch_hint'));
+ $this->line('');
+ }
+}
diff --git a/app/Console/Commands/BenchCommand.php b/app/Console/Commands/BenchCommand.php
new file mode 100644
index 00000000..45618db1
--- /dev/null
+++ b/app/Console/Commands/BenchCommand.php
@@ -0,0 +1,395 @@
+ $runners 축 실행기 목록 (컨테이너 태그 주입)
+ */
+ public function __construct(
+ private readonly BenchmarkProfileRegistry $registry,
+ private readonly BenchmarkReporter $reporter,
+ private readonly iterable $runners,
+ ) {
+ parent::__construct();
+ }
+
+ /**
+ * 커맨드를 실행합니다.
+ *
+ * @return int 종료 코드
+ */
+ public function handle(): int
+ {
+ $this->applyDatabaseOverride();
+
+ if ($this->option('list-profiles')) {
+ return $this->listProfiles();
+ }
+
+ [$profiles, $selectionError] = $this->selectProfiles();
+
+ if ($selectionError !== null) {
+ $this->error($selectionError);
+
+ return self::FAILURE;
+ }
+
+ if ($profiles === []) {
+ $this->error('계측할 프로파일이 없습니다. --profile / --axis / --all 중 하나를 지정하세요.');
+
+ return self::FAILURE;
+ }
+
+ $options = $this->runOptions();
+
+ // 계측 결과가 환경에 좌우되므로 실행 환경을 먼저 드러낸다
+ if (! $this->option('json')) {
+ foreach ($this->reporter->environment() as $name => $value) {
+ $this->line(sprintf(' %-14s %s', $name, $value));
+ }
+
+ $this->newLine();
+ }
+
+ $this->reportCollectionWarnings();
+
+ $results = [];
+
+ foreach ($profiles as $profile) {
+ $results[] = $this->runProfile($profile, $options);
+ }
+
+ return $this->output($results, $options);
+ }
+
+ /**
+ * 계측용 데이터베이스 지정을 반영합니다.
+ *
+ * 계측은 대량 시딩을 동반하므로 개발 DB 대신 폐기 가능한 DB 를 지정할 수 있어야 합니다.
+ * config 가 캐시된 환경에서는 `.env` / `--env` 로 연결을 바꿀 수 없어 런타임 치환이
+ * 유일한 수단입니다.
+ */
+ private function applyDatabaseOverride(): void
+ {
+ $database = (string) $this->option('database');
+
+ if ($database === '') {
+ return;
+ }
+
+ $connection = config('database.default');
+
+ config([
+ "database.connections.{$connection}.database" => $database,
+ "database.connections.{$connection}.write.database" => $database,
+ "database.connections.{$connection}.read.database" => $database,
+ ]);
+
+ DB::purge($connection);
+ }
+
+ /**
+ * 등록된 프로파일 목록을 출력합니다.
+ *
+ * @return int 종료 코드
+ */
+ private function listProfiles(): int
+ {
+ $profiles = $this->registry->all();
+
+ if ($this->option('json')) {
+ $this->line((string) json_encode(
+ array_map(fn (BenchmarkProfile $profile) => $profile->toArray(), array_values($profiles)),
+ JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
+ ));
+
+ return self::SUCCESS;
+ }
+
+ $this->table(
+ ['프로파일', '축', '출처', '설명'],
+ array_map(fn (BenchmarkProfile $profile) => [
+ $profile->qualifiedKey(),
+ $profile->axis->value,
+ $profile->sourceKind,
+ $profile->label ?? '-',
+ ], array_values($profiles))
+ );
+
+ $this->reportCollectionWarnings();
+
+ return self::SUCCESS;
+ }
+
+ /**
+ * 실행할 프로파일을 고릅니다.
+ *
+ * @return array{0: array, 1: string|null} [실행 대상, 실패 사유]
+ */
+ private function selectProfiles(): array
+ {
+ $keys = array_filter((array) $this->option('profile'), 'strlen');
+
+ if ($keys !== []) {
+ $selected = [];
+
+ foreach ($keys as $key) {
+ [$profile, $error] = $this->registry->resolve((string) $key);
+
+ if ($error !== null) {
+ return [[], $error];
+ }
+
+ $selected[] = $profile;
+ }
+
+ return [$selected, null];
+ }
+
+ $axisOption = (string) $this->option('axis');
+
+ if ($axisOption !== '') {
+ $axis = BenchmarkAxis::tryFrom($axisOption);
+
+ if ($axis === null) {
+ return [[], "알 수 없는 축: {$axisOption} (허용: ".implode('|', BenchmarkAxis::values()).')'];
+ }
+
+ return [array_values($this->registry->byAxis($axis)), null];
+ }
+
+ return [$this->option('all') ? array_values($this->registry->all()) : [], null];
+ }
+
+ /**
+ * 커맨드 옵션을 실행 옵션으로 해석합니다.
+ *
+ * @return BenchmarkRunOptions 실행 옵션
+ */
+ private function runOptions(): BenchmarkRunOptions
+ {
+ $asUser = (string) $this->option('as');
+
+ return new BenchmarkRunOptions(
+ offsets: $this->parseOffsets(),
+ runs: max(1, (int) $this->option('runs')),
+ seed: max(0, (int) $this->option('seed')),
+ fresh: (bool) $this->option('fresh'),
+ explain: (bool) $this->option('explain'),
+ allowWrite: (bool) $this->option('allow-write'),
+ asUser: $asUser === '' ? null : $asUser,
+ perPage: max(1, (int) $this->option('per-page')),
+ );
+ }
+
+ /**
+ * OFFSET 목록을 파싱합니다.
+ *
+ * @return array 오름차순 정렬된 OFFSET 목록
+ */
+ private function parseOffsets(): array
+ {
+ $offsets = array_map('intval', array_filter(explode(',', (string) $this->option('offsets')), 'strlen'));
+ sort($offsets);
+
+ return $offsets === [] ? [0] : $offsets;
+ }
+
+ /**
+ * 프로파일 1건을 계측합니다.
+ *
+ * @param BenchmarkProfile $profile 대상 프로파일
+ * @param BenchmarkRunOptions $options 실행 옵션
+ * @return BenchmarkResult 계측 결과
+ */
+ private function runProfile(BenchmarkProfile $profile, BenchmarkRunOptions $options): BenchmarkResult
+ {
+ $runner = $this->runnerFor($profile->axis);
+
+ if ($runner === null) {
+ return BenchmarkResult::skipped($profile, "축 실행기가 없습니다: {$profile->axis->value}");
+ }
+
+ if (! $this->option('json')) {
+ $this->line(sprintf('▶ %s (%s)', $profile->qualifiedKey(), $profile->axis->label()));
+ }
+
+ $onProgress = $this->option('json')
+ ? null
+ : fn (string $message) => $this->line(' '.$message);
+
+ return $runner->run($profile, $options, $onProgress);
+ }
+
+ /**
+ * 축에 대응하는 실행기를 찾습니다.
+ *
+ * @param BenchmarkAxis $axis 대상 축
+ * @return BenchmarkAxisRunner|null 실행기 (없으면 null)
+ */
+ private function runnerFor(BenchmarkAxis $axis): ?BenchmarkAxisRunner
+ {
+ foreach ($this->runners as $runner) {
+ if ($runner->axis() === $axis) {
+ return $runner;
+ }
+ }
+
+ return null;
+ }
+
+ /**
+ * 무시된 프로파일 선언을 알립니다.
+ *
+ * 선언 오류를 조용히 버리면 그 대상이 계측 사각으로 남으므로 매 실행에 드러냅니다.
+ */
+ private function reportCollectionWarnings(): void
+ {
+ if ($this->option('json')) {
+ return;
+ }
+
+ foreach ($this->registry->warnings() as $warning) {
+ $this->warn('무시된 프로파일 선언 — '.$warning);
+ }
+ }
+
+ /**
+ * 계측 결과를 출력합니다.
+ *
+ * @param array $results 계측 결과
+ * @param BenchmarkRunOptions $options 실행 옵션
+ * @return int 종료 코드
+ */
+ private function output(array $results, BenchmarkRunOptions $options): int
+ {
+ $warnings = $this->registry->warnings();
+
+ if ($this->option('json')) {
+ $this->line($this->reporter->toJson($results, $options, $warnings));
+ } else {
+ foreach ($results as $result) {
+ $this->newLine();
+ $this->line(sprintf('%s (%s)', $result->profile->qualifiedKey(), $result->profile->axis->label()));
+
+ if ($result->skipped) {
+ $this->warn(' 측정하지 않음: '.$result->skipReason);
+
+ continue;
+ }
+
+ $this->table($result->headers, $result->rows);
+
+ foreach ($result->notes as $note) {
+ $this->line(' '.$note);
+ }
+ }
+ }
+
+ if ($this->wantsReport()) {
+ $path = $this->writeReport($results, $options, $warnings);
+ $this->newLine();
+ $this->info('리포트 저장: '.$path);
+ }
+
+ // 전부 건너뛴 실행을 성공으로 보고하면 "측정했다"로 읽히므로 실패로 돌려준다
+ $measured = array_filter($results, fn (BenchmarkResult $result) => ! $result->skipped);
+
+ return $measured === [] ? self::FAILURE : self::SUCCESS;
+ }
+
+ /**
+ * 리포트 출력이 요청되었는지 판정합니다.
+ *
+ * `--report` 는 값이 선택이라 `option()` 만으로는 "미지정"과 "값 없이 지정"을
+ * 구분할 수 없으므로 원시 입력을 확인합니다.
+ *
+ * @return bool 리포트 출력 여부
+ */
+ private function wantsReport(): bool
+ {
+ return $this->input->hasParameterOption('--report')
+ || $this->input->hasParameterOption('--report=')
+ || (string) $this->option('report') !== '';
+ }
+
+ /**
+ * 마크다운 리포트를 저장합니다.
+ *
+ * @param array $results 계측 결과
+ * @param BenchmarkRunOptions $options 실행 옵션
+ * @param array $warnings 프로파일 수집 경고
+ * @return string 저장된 절대 경로
+ */
+ private function writeReport(array $results, BenchmarkRunOptions $options, array $warnings): string
+ {
+ $given = (string) $this->option('report');
+
+ $path = $given !== ''
+ ? $given
+ : storage_path(self::REPORT_DIR.'/bench-'.now()->format('Ymd-His').'.md');
+
+ $directory = dirname($path);
+
+ if (! is_dir($directory)) {
+ mkdir($directory, 0755, true);
+ }
+
+ file_put_contents($path, $this->reporter->toMarkdown($results, $options, $warnings));
+
+ return $path;
+ }
+}
diff --git a/app/Console/Commands/ConvertJsonUnicodeEscapes.php b/app/Console/Commands/ConvertJsonUnicodeEscapes.php
index e631005c..84c07b1b 100644
--- a/app/Console/Commands/ConvertJsonUnicodeEscapes.php
+++ b/app/Console/Commands/ConvertJsonUnicodeEscapes.php
@@ -109,7 +109,7 @@ class ConvertJsonUnicodeEscapes extends Command
/**
* 테이블 존재 여부를 확인합니다.
*
- * @param string $table 테이블명 (프리픽스 포함)
+ * @param string $table 테이블명 (프리픽스 포함)
* @return bool 존재 여부
*/
private function tableExists(string $table): bool
@@ -126,10 +126,10 @@ class ConvertJsonUnicodeEscapes extends Command
/**
* 특정 테이블의 특정 컬럼을 변환합니다.
*
- * @param string $table 테이블명
- * @param string $column 컬럼명
- * @param int $chunkSize 청크 크기
- * @param bool $dryRun 드라이런 모드
+ * @param string $table 테이블명
+ * @param string $column 컬럼명
+ * @param int $chunkSize 청크 크기
+ * @param bool $dryRun 드라이런 모드
* @return array{int, int} [변환 건수, 스킵 건수]
*/
private function processColumn(string $table, string $column, int $chunkSize, bool $dryRun): array
@@ -152,11 +152,13 @@ class ConvertJsonUnicodeEscapes extends Command
$this->components->twoColumnDetail("{$table}.{$column}", "대상 {$total}건 처리 중...");
+ // chunkById(키셋 순회) 필수 — 콜백이 필터 조건 컬럼을 UTF-8 로 다시 써서 처리된
+ // 행이 `LIKE '%\u%'` 결과에서 이탈한다. OFFSET 기반 chunk() 는 그만큼 앞으로 밀려
+ // 아직 변환되지 않은 행을 건너뛴다. (대상 테이블 8종 모두 `id` auto-increment PK)
DB::table($table)
->whereNotNull($column)
->where($column, 'LIKE', '%\\\\u%')
- ->orderBy('id')
- ->chunk($chunkSize, function ($rows) use ($table, $column, $dryRun, &$converted, &$skipped) {
+ ->chunkById($chunkSize, function ($rows) use ($table, $column, $dryRun, &$converted, &$skipped) {
foreach ($rows as $row) {
$original = $row->{$column};
$decoded = json_decode($original, true);
diff --git a/app/Console/Commands/Core/Concerns/BundledExtensionUpdatePrompt.php b/app/Console/Commands/Core/Concerns/BundledExtensionUpdatePrompt.php
index ee1858cd..768695de 100644
--- a/app/Console/Commands/Core/Concerns/BundledExtensionUpdatePrompt.php
+++ b/app/Console/Commands/Core/Concerns/BundledExtensionUpdatePrompt.php
@@ -7,6 +7,7 @@ use App\Extension\ModuleManager;
use App\Extension\PluginManager;
use App\Extension\TemplateManager;
use App\Extension\Vendor\VendorMode;
+use App\Search\SearchIndexMaintenanceManager;
use App\Services\CoreUpdateService;
use App\Services\LanguagePackService;
use Illuminate\Support\Facades\File;
@@ -109,6 +110,10 @@ trait BundledExtensionUpdatePrompt
// 확장별 전략 오버라이드
$strategies = $this->collectPerExtensionStrategies($updates, $globalStrategy, $force);
+ // 검색 인덱스 재생성 여부 — 인덱스 잠금·재색인 비용이 있어 운영 중인 사이트에서는
+ // 기본값(아니오)을 유지하고 유지보수 시간에 별도로 수행하는 것이 안전하다.
+ $rebuildSearchIndex = $this->askRebuildSearchIndex($force);
+
// 일괄 실행
return $this->executeBulkUpdate(
$moduleManager,
@@ -116,6 +121,7 @@ trait BundledExtensionUpdatePrompt
$templateManager,
$updates,
$strategies,
+ $rebuildSearchIndex,
);
}
@@ -200,8 +206,11 @@ trait BundledExtensionUpdatePrompt
TemplateManager $templateManager,
array $updates,
array $strategies,
+ bool $rebuildSearchIndex = false,
): array {
$manifest = $this->buildBundledUpdateManifest($updates, $strategies);
+ // 운영자의 선택을 매니페스트에 실어 spawn 자식과 in-process fallback 이 같은 결정을 따르게 한다
+ $manifest['rebuild_search_index'] = $rebuildSearchIndex;
if ($this->bundledManifestIsEmpty($manifest)) {
return ['success' => 0, 'failed' => 0, 'skipped' => 0, 'has_updates' => false];
}
@@ -228,6 +237,7 @@ trait BundledExtensionUpdatePrompt
$templateManager,
$updates,
$strategies,
+ $rebuildSearchIndex,
);
}
@@ -385,6 +395,7 @@ trait BundledExtensionUpdatePrompt
TemplateManager $templateManager,
array $updates,
array $strategies,
+ bool $rebuildSearchIndex = false,
): array {
$success = 0;
$failed = 0;
@@ -452,6 +463,8 @@ trait BundledExtensionUpdatePrompt
$this->newLine();
$this->info("업데이트 완료: 성공 {$success}, 실패 {$failed}");
+ $this->runSearchIndexRebuildIfRequested($rebuildSearchIndex);
+
return [
'success' => $success,
'failed' => $failed,
@@ -460,4 +473,60 @@ trait BundledExtensionUpdatePrompt
];
}
+ /**
+ * 검색 인덱스 재생성 여부를 운영자에게 확인합니다.
+ *
+ * 재생성은 인덱스 잠금 또는 전체 재색인을 유발하므로 기본값은 "아니오" 입니다.
+ * `--force` (무인 실행) 시에도 묻지 않고 수행하지 않습니다 — 무인 실행이
+ * 대용량 테이블을 잠그는 일이 없어야 합니다. 필요하면 `core:update
+ * --rebuild-search-index` 로 명시하거나 이후 `search:index --repair` 를 실행합니다.
+ *
+ * @param bool $force 강제(무인) 실행 여부
+ * @return bool 재생성 수행 여부
+ */
+ private function askRebuildSearchIndex(bool $force): bool
+ {
+ // 커맨드가 옵션으로 이미 선택을 받았으면 그대로 따른다
+ if ($this->hasOption('rebuild-search-index') && (bool) $this->option('rebuild-search-index')) {
+ return true;
+ }
+
+ if ($force) {
+ return false;
+ }
+
+ $manager = app(SearchIndexMaintenanceManager::class);
+
+ // 점검을 제공하지 않는 엔진에서는 물을 것이 없다
+ if (! $manager->hasMaintainer() || $manager->unavailableReason() !== null) {
+ return false;
+ }
+
+ $this->newLine();
+ $this->line(' '.__('search.index.rebuild_cost_warning'));
+
+ return $this->unifiedConfirm(__('search.index.rebuild_after_bulk_confirm'), false);
+ }
+
+ /**
+ * 요청이 있었으면 검색 인덱스를 재생성합니다.
+ *
+ * @param bool $requested 재생성 요청 여부
+ * @return void
+ */
+ private function runSearchIndexRebuildIfRequested(bool $requested): void
+ {
+ if (! $requested) {
+ return;
+ }
+
+ $report = app(SearchIndexMaintenanceManager::class)->repairStale();
+
+ $this->newLine();
+ $this->info('검색 인덱스: '.$report->summary());
+
+ foreach ($report->failed as $identifier => $message) {
+ $this->warn(' '.__('search.index.rebuild_failed_item', ['index' => $identifier, 'error' => $message]));
+ }
+ }
}
diff --git a/app/Console/Commands/Core/CoreUpdateCommand.php b/app/Console/Commands/Core/CoreUpdateCommand.php
index b15986f7..bb15fdb2 100644
--- a/app/Console/Commands/Core/CoreUpdateCommand.php
+++ b/app/Console/Commands/Core/CoreUpdateCommand.php
@@ -17,6 +17,7 @@ use App\Extension\Vendor\Exceptions\VendorInstallException;
use App\Extension\Vendor\VendorMode;
use App\Services\CoreUpdateService;
use App\Support\ConfigCacheHelper;
+use App\Support\RouteCacheHelper;
use Illuminate\Console\Command;
use Illuminate\Support\Facades\Log;
@@ -34,7 +35,8 @@ class CoreUpdateCommand extends Command
{--local : 로컬 코드베이스를 업데이트 소스로 사용 (GitHub 스킵)}
{--source= : 수동 업데이트용 소스 디렉토리 경로 (GitHub 다운로드 대신 지정 디렉토리 사용)}
{--zip= : 수동 업데이트용 ZIP 파일 경로 (GitHub 다운로드 대신 지정 ZIP 추출 사용)}
- {--vendor-mode=auto : vendor 설치 모드 (auto|composer|bundled)}';
+ {--vendor-mode=auto : vendor 설치 모드 (auto|composer|bundled)}
+ {--rebuild-search-index : 번들 확장 일괄 업데이트 후 색인이 누락된 검색 인덱스를 재생성 (인덱스가 잠기거나 재색인됩니다 — 운영 중에는 유지보수 시간에 수행하세요)}';
protected $description = '그누보드7 코어를 최신 버전으로 업데이트합니다';
@@ -542,6 +544,11 @@ class CoreUpdateCommand extends Command
// 상태를 가드하고 실패를 안전하게 흡수한다.
ConfigCacheHelper::rebuild();
+ // 라우트 캐시도 같은 이유로 되살린다. 코어 업데이트는 routes/*.php 와 vendor 를
+ // 교체하므로 흐름 중간에 비우는 것이 맞지만, 비운 채로 끝내면 이후 모든 요청이
+ // 라우트를 다시 등록한다. 재생성은 파일이 전부 안착한 이 지점에서만 안전하다.
+ RouteCacheHelper::rebuild();
+
$log('정리 완료');
$bar->finish();
diff --git a/app/Console/Commands/Core/ExecuteBundledUpdatesCommand.php b/app/Console/Commands/Core/ExecuteBundledUpdatesCommand.php
index 66dfb893..d01375ba 100644
--- a/app/Console/Commands/Core/ExecuteBundledUpdatesCommand.php
+++ b/app/Console/Commands/Core/ExecuteBundledUpdatesCommand.php
@@ -2,10 +2,12 @@
namespace App\Console\Commands\Core;
+use App\Extension\ExtensionManager;
use App\Extension\ModuleManager;
use App\Extension\PluginManager;
use App\Extension\TemplateManager;
use App\Extension\Vendor\VendorMode;
+use App\Search\SearchIndexMaintenanceManager;
use App\Services\LanguagePackService;
use Illuminate\Console\Command;
use Illuminate\Support\Facades\File;
@@ -45,7 +47,8 @@ class ExecuteBundledUpdatesCommand extends Command
protected $signature = 'core:execute-bundled-updates
{--manifest= : 업데이트 매니페스트 JSON 파일 경로 (필수)}
- {--force : 강제 업데이트 플래그 (확장 매니저 update 호출에 전달)}';
+ {--force : 강제 업데이트 플래그 (확장 매니저 update 호출에 전달)}
+ {--rebuild-search-index : 일괄 업데이트 후 검색 인덱스 재생성 (매니페스트의 선택보다 우선)}';
protected $description = '번들 확장 일괄 업데이트를 실행합니다 (CoreUpdateCommand 내부용 — fresh PHP 프로세스에서 호출)';
@@ -63,7 +66,7 @@ class ExecuteBundledUpdatesCommand extends Command
// (Artisan::call 대신 직접 메서드 호출 — nested Artisan::call 이 outer 명령의
// output buffer 를 덮어쓰는 Laravel 동작 회피)
try {
- app(\App\Extension\ExtensionManager::class)->updateComposerAutoload();
+ app(ExtensionManager::class)->updateComposerAutoload();
} catch (\Throwable $e) {
Log::warning('bundled update spawn 자식: updateComposerAutoload 호출 실패', [
'error' => $e->getMessage(),
@@ -77,6 +80,9 @@ class ExecuteBundledUpdatesCommand extends Command
return self::FAILURE;
}
+ // 부모(core:update)가 운영자 선택을 매니페스트에 실어 보낸다 — 자식이 임의로 정하지 않는다
+ $rebuildSearchIndex = (bool) $this->option('rebuild-search-index') || (bool) ($manifest['rebuild_search_index'] ?? false);
+
$modules = $manifest['modules'] ?? [];
$plugins = $manifest['plugins'] ?? [];
$templates = $manifest['templates'] ?? [];
@@ -166,6 +172,17 @@ class ExecuteBundledUpdatesCommand extends Command
$this->newLine();
$this->info("업데이트 완료: 성공 {$success}, 실패 {$failed}");
+ // 검색 인덱스 재생성 — 운영자가 부모 단계에서 선택했을 때만 수행 (인덱스 잠금·재색인 비용)
+ if ($rebuildSearchIndex) {
+ $report = app(SearchIndexMaintenanceManager::class)->repairStale();
+ $this->newLine();
+ $this->info('검색 인덱스: '.$report->summary());
+
+ foreach ($report->failed as $identifier => $message) {
+ $this->warn(' '.__('search.index.rebuild_failed_item', ['index' => $identifier, 'error' => $message]));
+ }
+ }
+
// 부모 프로세스가 결과를 복원할 수 있도록 표식 라인으로 페이로드 출력
$this->line(self::RESULT_PREFIX.json_encode([
'success' => $success,
@@ -174,5 +191,4 @@ class ExecuteBundledUpdatesCommand extends Command
return $failed > 0 ? self::FAILURE : self::SUCCESS;
}
-
}
diff --git a/app/Console/Commands/Core/ExecuteUpgradeStepsCommand.php b/app/Console/Commands/Core/ExecuteUpgradeStepsCommand.php
index 04c37a98..66c09a83 100644
--- a/app/Console/Commands/Core/ExecuteUpgradeStepsCommand.php
+++ b/app/Console/Commands/Core/ExecuteUpgradeStepsCommand.php
@@ -12,6 +12,8 @@ use App\Extension\PluginManager;
use App\Extension\TemplateManager;
use App\Extension\Traits\ClearsTemplateCaches;
use App\Services\CoreUpdateService;
+use App\Support\ConfigCacheHelper;
+use App\Support\RouteCacheHelper;
use Illuminate\Console\Command;
use Illuminate\Support\Facades\Log;
@@ -251,7 +253,10 @@ class ExecuteUpgradeStepsCommand extends Command
// 비활성 상태로 남는다. 모든 upgrade step + 번들 확장 업데이트가 config 소스를
// 변경했을 수 있으니, 캐시 정리 세트의 마지막에 config 캐시를 재생성한다.
// spawn 자식·steps-only 는 이 블록을 스킵하고 부모(CoreUpdateCommand)가 재생성한다.
- \App\Support\ConfigCacheHelper::rebuild();
+ ConfigCacheHelper::rebuild();
+ // 라우트 캐시도 같은 이유로 되살린다 — 업그레이드 스텝이나 번들 확장 업데이트가
+ // 라우트를 바꿨을 수 있고, 비운 채로 끝내면 이후 모든 요청이 라우트를 재등록한다.
+ RouteCacheHelper::rebuild();
// 업그레이드 스텝 단독 실행 시에도 코어 lang/routes/layout 변경이
// 프론트엔드 캐시 stale 로 가려지지 않도록 `ext.cache_version` bump.
// spawn 자식·steps-only 모드에서는 부모가 처리하므로 스킵.
diff --git a/app/Console/Commands/Extension/UpdateAutoloadCommand.php b/app/Console/Commands/Extension/UpdateAutoloadCommand.php
index ff3501db..e61bbcd1 100644
--- a/app/Console/Commands/Extension/UpdateAutoloadCommand.php
+++ b/app/Console/Commands/Extension/UpdateAutoloadCommand.php
@@ -41,6 +41,12 @@ class UpdateAutoloadCommand extends Command
$this->info('오토로드 파일이 성공적으로 생성되었습니다.');
$this->line(' → bootstrap/cache/autoload-extensions.php');
+ // 방금 생성한 PSR-4 매핑을 현재 프로세스의 ClassLoader 에 즉시 반영.
+ // 이 커맨드는 매핑이 깨진 상태를 복구하는 경로이기도 한데, 재등록 없이 아래
+ // loadModules/loadPlugins 를 호출하면 부팅 시점의 (깨진) 매핑으로 확장 클래스를
+ // 찾지 못해 훅 캐시가 modules/plugins 0건으로 생성된다 — 모든 확장 훅이 조용히 소실.
+ $extensionManager->reregisterRuntimeAutoload();
+
// 오토로드 캐시와 동일 생명주기의 정적 훅 매핑 캐시도 함께 재생성.
// 코어 업데이트(clearAllCaches → 이 커맨드) 시 코어 리스너 추가/변경/삭제가
// 캐시에 반영되도록 보장한다 (미갱신 시 stale 매핑으로 훅 발화 누락/과잉 위험).
diff --git a/app/Console/Commands/LanguagePack/ListLanguagePackCommand.php b/app/Console/Commands/LanguagePack/ListLanguagePackCommand.php
index 7e82a798..c36d8e8f 100644
--- a/app/Console/Commands/LanguagePack/ListLanguagePackCommand.php
+++ b/app/Console/Commands/LanguagePack/ListLanguagePackCommand.php
@@ -2,13 +2,16 @@
namespace App\Console\Commands\LanguagePack;
-use App\Contracts\Repositories\LanguagePackRepositoryInterface;
+use App\Models\LanguagePack;
+use App\Services\LanguagePackService;
use Illuminate\Console\Command;
/**
- * 설치된 언어팩 목록을 출력합니다.
+ * 언어팩 목록을 출력합니다.
*
- * 모듈/플러그인/템플릿의 list 커맨드와 동일한 운영 도구.
+ * 모듈/플러그인/템플릿의 list 커맨드와 동일한 운영 도구. Service::list() 를 경유하므로
+ * 설치된 DB 행뿐 아니라 "번들에 있으나 미설치"(uninstalled) 및 "active 로 기록됐으나
+ * 설치본 파일 부재(드리프트)" 상태를 함께 표면화한다(이슈 #496).
*/
class ListLanguagePackCommand extends Command
{
@@ -20,13 +23,13 @@ class ListLanguagePackCommand extends Command
/**
* @var string
*/
- protected $description = '설치된 언어팩 목록을 출력합니다.';
+ protected $description = '언어팩 목록을 출력합니다 (미설치 번들 및 드리프트 상태 포함).';
/**
- * @param LanguagePackRepositoryInterface $repository Repository
+ * @param LanguagePackService $service 언어팩 Service
*/
public function __construct(
- private readonly LanguagePackRepositoryInterface $repository,
+ private readonly LanguagePackService $service,
) {
parent::__construct();
}
@@ -43,11 +46,11 @@ class ListLanguagePackCommand extends Command
$filters['scope'] = $scope;
}
- $paginator = $this->repository->paginate($filters, 100);
+ $paginator = $this->service->list($filters, 100);
$packs = $paginator->items();
if (empty($packs)) {
- $this->info('설치된 언어팩이 없습니다.');
+ $this->info('언어팩이 없습니다.');
return self::SUCCESS;
}
@@ -61,7 +64,7 @@ class ListLanguagePackCommand extends Command
$pack->locale,
$pack->vendor,
$pack->version,
- $pack->status,
+ $this->formatStatus($pack),
];
}
@@ -72,4 +75,19 @@ class ListLanguagePackCommand extends Command
return self::SUCCESS;
}
+
+ /**
+ * 표시용 상태 문자열을 만듭니다. 드리프트(active + 설치본 부재)는 명시적으로 표기합니다.
+ *
+ * @param LanguagePack $pack 대상 팩
+ * @return string 표시 상태
+ */
+ private function formatStatus(LanguagePack $pack): string
+ {
+ if ((bool) $pack->getAttribute('files_missing')) {
+ return $pack->status.' (파일 없음)';
+ }
+
+ return (string) $pack->status;
+ }
}
diff --git a/app/Console/Commands/LanguagePack/ProvisionLanguagePackCommand.php b/app/Console/Commands/LanguagePack/ProvisionLanguagePackCommand.php
new file mode 100644
index 00000000..76d5a505
--- /dev/null
+++ b/app/Console/Commands/LanguagePack/ProvisionLanguagePackCommand.php
@@ -0,0 +1,150 @@
+resolveTargetLocales();
+ if (empty($targetLocales)) {
+ $this->info('프로비저닝 대상 로케일이 없습니다 (base locale 외 supported_locales 미선언).');
+
+ return self::SUCCESS;
+ }
+
+ $scopeFilter = array_values(array_filter(array_map('strval', (array) $this->option('scope'))));
+ $autoActivate = ! (bool) $this->option('no-activate');
+
+ $inScope = fn (LanguagePack $pack) => in_array($pack->locale, $targetLocales, true)
+ && (empty($scopeFilter) || in_array($pack->scope, $scopeFilter, true));
+
+ // 미설치 번들(신규 프로비저닝) + 드리프트 설치 행(수동 복구) 이 모두 대상이다.
+ // 드리프트 행은 슬롯이 점유돼 있어 getUninstalledBundledPacks() 가 잡지 못하므로 따로 합친다.
+ $candidates = $this->service->getUninstalledBundledPacks()->filter($inScope)
+ ->concat($this->service->getDriftedInstalledPacks()->filter($inScope))
+ ->values();
+
+ if ($candidates->isEmpty()) {
+ $this->info(sprintf(
+ '설치하거나 복구할 번들 언어팩이 없습니다 (로케일: %s). 이미 프로비저닝된 상태입니다.',
+ implode(', ', $targetLocales),
+ ));
+
+ return self::SUCCESS;
+ }
+
+ $installed = 0;
+ $repaired = 0;
+ $skipped = 0;
+ $failed = 0;
+
+ foreach ($candidates as $pack) {
+ $identifier = (string) ($pack->getAttribute('bundled_identifier') ?? $pack->identifier);
+ $blockedReason = $pack->getAttribute('install_blocked_reason');
+
+ // 대상 확장 미설치/미활성 등으로 설치가 불가한 팩은 best-effort 로 건너뛴다.
+ if ($blockedReason !== null && $blockedReason !== '') {
+ $this->warn(sprintf('건너뜀 (설치 불가: %s): %s', $blockedReason, $identifier));
+ $skipped++;
+
+ continue;
+ }
+
+ try {
+ $isRepair = (bool) $pack->getAttribute('files_missing');
+ $result = $this->service->installFromBundled($identifier, $autoActivate);
+ $this->info(sprintf(
+ '%s: %s v%s (status=%s)',
+ $isRepair ? '복구' : '설치',
+ $result->identifier,
+ $result->version,
+ $result->status,
+ ));
+ $isRepair ? $repaired++ : $installed++;
+ } catch (Throwable $e) {
+ $this->warn(sprintf('실패 (건너뜀): %s — %s', $identifier, $e->getMessage()));
+ $failed++;
+ }
+ }
+
+ $this->info(sprintf(
+ '프로비저닝 완료 — 설치 %d, 복구 %d, 건너뜀 %d, 실패 %d',
+ $installed,
+ $repaired,
+ $skipped,
+ $failed,
+ ));
+
+ // 성과가 하나도 없고 실패만 있었다면 실패로 보고 (멱등 재실행/전량 스킵은 성공).
+ return $installed === 0 && $repaired === 0 && $failed > 0 ? self::FAILURE : self::SUCCESS;
+ }
+
+ /**
+ * 프로비저닝 대상 로케일을 해석합니다.
+ *
+ * `--locale` 지정 시 그 값, 미지정 시 `config('app.supported_locales')` 에서 base locale(ko/en)을 제외한 집합.
+ *
+ * @return array 대상 로케일 목록 (base locale 제외)
+ */
+ private function resolveTargetLocales(): array
+ {
+ $explicit = array_values(array_filter(array_map('strval', (array) $this->option('locale'))));
+ $source = ! empty($explicit)
+ ? $explicit
+ : array_map('strval', (array) config('app.supported_locales', []));
+
+ return array_values(array_unique(array_filter(
+ $source,
+ fn (string $locale) => $locale !== '' && ! LanguagePackBaseLocales::isBaseLocale($locale),
+ )));
+ }
+}
diff --git a/app/Console/Commands/Module/CheckModuleUpdatesCommand.php b/app/Console/Commands/Module/CheckModuleUpdatesCommand.php
index 45997dbf..f8937df4 100644
--- a/app/Console/Commands/Module/CheckModuleUpdatesCommand.php
+++ b/app/Console/Commands/Module/CheckModuleUpdatesCommand.php
@@ -116,7 +116,7 @@ class CheckModuleUpdatesCommand extends Command
$updateCount = 0;
foreach ($result['details'] as $detail) {
- $isUpdate = $detail['update_available'] ?? false;
+ $isUpdate = (bool) ($detail['update_available'] ?? true);
if ($isUpdate) {
$updateCount++;
}
@@ -143,7 +143,7 @@ class CheckModuleUpdatesCommand extends Command
$this->table($headers, $tableData);
$this->newLine();
$this->info(__('modules.commands.check_updates.summary', [
- 'total' => count($result['details']),
+ 'total' => $result['checked_count'] ?? count($result['details']),
'updates' => $updateCount,
]));
diff --git a/app/Console/Commands/Module/InstallModuleCommand.php b/app/Console/Commands/Module/InstallModuleCommand.php
index 297e1d71..a681d8a1 100644
--- a/app/Console/Commands/Module/InstallModuleCommand.php
+++ b/app/Console/Commands/Module/InstallModuleCommand.php
@@ -3,6 +3,7 @@
namespace App\Console\Commands\Module;
use App\Console\Commands\Traits\HasProgressBar;
+use App\Console\Commands\Traits\RebuildsSearchIndex;
use App\Contracts\Repositories\ModuleRepositoryInterface;
use App\Enums\ExtensionOwnerType;
use App\Extension\ModuleManager;
@@ -17,6 +18,7 @@ use Illuminate\Support\Facades\Validator;
class InstallModuleCommand extends Command
{
use HasProgressBar;
+ use RebuildsSearchIndex;
/**
* The name and signature of the console command.
@@ -24,7 +26,8 @@ class InstallModuleCommand extends Command
protected $signature = 'module:install
{identifier : 설치할 모듈 식별자}
{--vendor-mode=auto : Vendor 설치 모드 (auto|composer|bundled)}
- {--force : 이미 설치된 경우에도 _bundled/_pending 원본으로 활성 디렉토리를 덮어쓰고 재설치 (불완전 설치 복구)}';
+ {--force : 이미 설치된 경우에도 _bundled/_pending 원본으로 활성 디렉토리를 덮어쓰고 재설치 (불완전 설치 복구)}
+ {--rebuild-search-index : 완료 후 색인이 누락된 검색 인덱스를 재생성 (인덱스가 잠기거나 재색인됩니다 — 운영 중에는 유지보수 시간에 수행하세요)}';
/**
* The console command description.
@@ -114,6 +117,9 @@ class InstallModuleCommand extends Command
Log::info(__('modules.commands.install.success', ['module' => $identifier]));
+ // 검색 인덱스 재생성은 운영자가 선택했을 때만 수행한다 (인덱스 잠금·재색인 비용)
+ $this->handleSearchIndexRebuild();
+
return Command::SUCCESS;
}
diff --git a/app/Console/Commands/Module/UpdateModuleCommand.php b/app/Console/Commands/Module/UpdateModuleCommand.php
index d87444c2..e04b8d04 100644
--- a/app/Console/Commands/Module/UpdateModuleCommand.php
+++ b/app/Console/Commands/Module/UpdateModuleCommand.php
@@ -4,6 +4,7 @@ namespace App\Console\Commands\Module;
use App\Console\Commands\Traits\HasProgressBar;
use App\Console\Commands\Traits\HasUnifiedConfirm;
+use App\Console\Commands\Traits\RebuildsSearchIndex;
use App\Contracts\Repositories\ModuleRepositoryInterface;
use App\Enums\LayoutSourceType;
use App\Extension\ModuleManager;
@@ -16,6 +17,7 @@ class UpdateModuleCommand extends Command
{
use HasProgressBar;
use HasUnifiedConfirm;
+ use RebuildsSearchIndex;
/**
* The name and signature of the console command.
@@ -26,7 +28,8 @@ class UpdateModuleCommand extends Command
{--vendor-mode=auto : Vendor 설치 모드 (auto|composer|bundled)}
{--layout-strategy=overwrite : 레이아웃 전략 (overwrite|keep)}
{--source=auto : 업데이트 소스 (auto|bundled|github) — bundled 는 _bundled 만 사용(GitHub 우회)}
- {--zip= : 외부 ZIP 파일 경로 (지정 시 GitHub/번들 우회 + 버전은 module.json 기준)}';
+ {--zip= : 외부 ZIP 파일 경로 (지정 시 GitHub/번들 우회 + 버전은 module.json 기준)}
+ {--rebuild-search-index : 완료 후 색인이 누락된 검색 인덱스를 재생성 (인덱스가 잠기거나 재색인됩니다 — 운영 중에는 유지보수 시간에 수행하세요)}';
/**
* The console command description.
@@ -203,6 +206,9 @@ class UpdateModuleCommand extends Command
'layout_strategy' => $layoutStrategy,
]);
+ // 검색 인덱스 재생성은 운영자가 선택했을 때만 수행한다 (인덱스 잠금·재색인 비용)
+ $this->handleSearchIndexRebuild();
+
return Command::SUCCESS;
}
diff --git a/app/Console/Commands/PlaywrightIssueToken.php b/app/Console/Commands/PlaywrightIssueToken.php
index dec5d9b8..d64b9670 100644
--- a/app/Console/Commands/PlaywrightIssueToken.php
+++ b/app/Console/Commands/PlaywrightIssueToken.php
@@ -37,10 +37,15 @@ use Illuminate\Support\Facades\Config;
class PlaywrightIssueToken extends Command
{
protected $signature = 'playwright:issue-token
- {--permissions=* : 부여할 권한 식별자 (예: core.templates.layouts.edit). 다중 지정 가능}';
+ {--permissions=* : 부여할 권한 식별자 (예: core.templates.layouts.edit). 다중 지정 가능}
+ {--no-admin-role : admin 역할을 부여하지 않고 지정한 권한만 가진 계정을 만든다 (권한 분기 검증용)}
+ {--gc-hours=6 : 이 시간(시)보다 오래된 playwright 테스트 유저/역할을 발급 전 정리. 0 이면 정리 안 함}';
protected $description = 'Playwright E2E 용 Sanctum 토큰 발급 (CLI + G7_PLAYWRIGHT_BYPASS 3중 가드)';
+ /** 테스트 전용 역할 식별자 접두사 */
+ private const TEST_ROLE_PREFIX = 'playwright_test_';
+
public function handle(): int
{
// ① CLI 한정 — production 웹 요청에서 절대 도달 불가
@@ -61,9 +66,20 @@ class PlaywrightIssueToken extends Command
// SettingsServiceProvider::applyDebugConfig 는 bypass flag 가 있으면 settings JSON 덮어쓰기를 이미 건너뛴 상태.
Config::set('app.debug', true);
+ // 발급 전 오래된 테스트 아티팩트 정리 — 이 커맨드는 호출마다 유저 1명 + 역할 1개를
+ // 새로 만들지만 회수 주체가 없어 그대로 누적된다. 정리하지 않으면 회원/역할 관리 화면이
+ // 테스트 잔재로 뒤덮인다(실측: 발급 2974회 → 유저 2974명·역할 2974개 잔존).
+ // 시간 임계값을 두어 동시 실행 중인 다른 워커의 계정은 건드리지 않는다.
+ $gcHours = (int) $this->option('gc-hours');
+ if ($gcHours > 0) {
+ $this->pruneStaleTestArtifacts($gcHours);
+ }
+
$permissions = $this->option('permissions') ?: [];
- $user = $this->makeAdminUser($permissions);
+ // --no-admin-role: 지정한 권한만 가진 계정을 만든다.
+ // 기본값(플래그 없음)은 종전대로 admin 역할을 함께 부여한다 — 기존 spec 무영향.
+ $user = $this->makeAdminUser($permissions, ! $this->option('no-admin-role'));
$token = $user->createToken('playwright-'.uniqid())->plainTextToken;
$this->line($token);
@@ -71,6 +87,54 @@ class PlaywrightIssueToken extends Command
return self::SUCCESS;
}
+ /**
+ * 임계 시간보다 오래된 playwright 테스트 유저/역할을 정리한다.
+ *
+ * 대상: `playwright_test_*` 역할과, 그 역할이 유일한 확장 역할인 유저(= 이 커맨드가
+ * factory 로 만든 계정). 실제 회원과 구분되도록 반드시 역할 소유 관계로만 판별한다.
+ *
+ * chunkById(키셋 순회) 필수 — 콜백이 순회 대상 행을 삭제하므로 OFFSET 기반 chunk()/each()
+ * 는 다음 페이지가 줄어든 결과 집합을 지나쳐 일부를 건너뛴다.
+ *
+ * @param int $hours 이 시간보다 오래된 아티팩트만 정리
+ * @return void
+ */
+ private function pruneStaleTestArtifacts(int $hours): void
+ {
+ $threshold = now()->subHours($hours);
+ $roles = 0;
+ $users = 0;
+
+ Role::where('identifier', 'like', self::TEST_ROLE_PREFIX.'%')
+ ->where('created_at', '<', $threshold)
+ ->chunkById(100, function ($chunk) use (&$roles, &$users) {
+ foreach ($chunk as $role) {
+ // 이 역할을 가진 유저 중, 다른 playwright 역할이 없는 계정만 제거 대상
+ foreach ($role->users()->get() as $user) {
+ $otherTestRoles = $user->roles()
+ ->where('roles.id', '!=', $role->id)
+ ->where('roles.identifier', 'like', self::TEST_ROLE_PREFIX.'%')
+ ->count();
+ if ($otherTestRoles === 0) {
+ $user->tokens()->delete();
+ $user->roles()->detach();
+ $user->forceDelete();
+ $users++;
+ }
+ }
+
+ $role->permissions()->detach();
+ $role->users()->detach();
+ $role->delete();
+ $roles++;
+ }
+ });
+
+ if ($roles > 0) {
+ $this->info("[gc] playwright 테스트 잔재 정리: 역할 {$roles}건, 유저 {$users}건");
+ }
+ }
+
/**
* 권한 식별자 배열로 관리자 유저를 생성하고 권한을 부여한다.
*
@@ -78,19 +142,32 @@ class PlaywrightIssueToken extends Command
* 1. User factory 로 신규 유저 생성
* 2. 권한 식별자별로 Permission 행 보장 (firstOrCreate)
* 3. uniqid 접미사로 격리된 test role 생성 + 권한 sync
- * 4. admin role 보장 (firstOrCreate) + 유저-역할 부여
+ * 4. (withAdminRole 일 때만) admin role 보장 (firstOrCreate) + 유저-역할 부여
+ *
+ * `withAdminRole = false` 는 **권한 분기(읽기 전용 등) 검증 전용**이다. 기본값 true 는
+ * admin 역할을 함께 붙이므로, 요청한 권한만 가진 세션을 만들 수 없다 —
+ * admin 역할이 사이트의 전체 권한을 보유하기 때문에 `--permissions` 로 좁혀도
+ * 화면은 항상 최대 권한으로 렌더된다(실측: admin 역할 권한 263건).
+ *
+ * @param array $permissions 부여할 권한 식별자 목록
+ * @param bool $withAdminRole admin 역할 동반 부여 여부
+ * @return User 생성된 유저
*/
- private function makeAdminUser(array $permissions): User
+ private function makeAdminUser(array $permissions, bool $withAdminRole = true): User
{
$user = User::factory()->create();
$permissionIds = [];
foreach ($permissions as $identifier) {
+ // Role/Permission 의 name·description 은 모델에서 array 로 캐스팅된다.
+ // 여기서 json_encode 한 문자열을 넣으면 Eloquent 가 한 번 더 인코딩해
+ // 이중 인코딩된 값이 저장되고, 관리자 화면(역할 선택 등)에 JSON 원문이
+ // `{"ko":"\uXXXX…"}` 형태로 그대로 노출된다. 배열을 그대로 넘긴다.
$permission = Permission::firstOrCreate(
['identifier' => $identifier],
[
- 'name' => json_encode(['ko' => $identifier, 'en' => $identifier]),
- 'description' => json_encode(['ko' => $identifier, 'en' => $identifier]),
+ 'name' => ['ko' => $identifier, 'en' => $identifier],
+ 'description' => ['ko' => $identifier, 'en' => $identifier],
'extension_type' => ExtensionOwnerType::Core,
'extension_identifier' => 'core',
'type' => 'admin',
@@ -101,28 +178,33 @@ class PlaywrightIssueToken extends Command
$testRole = Role::create([
'identifier' => 'playwright_test_'.uniqid(),
- 'name' => json_encode(['ko' => 'Playwright 테스트 관리자', 'en' => 'Playwright Test Admin']),
- 'description' => json_encode(['ko' => 'E2E 자동화 전용', 'en' => 'E2E automation only']),
+ 'name' => ['ko' => 'Playwright 테스트 관리자', 'en' => 'Playwright Test Admin'],
+ 'description' => ['ko' => 'E2E 자동화 전용', 'en' => 'E2E automation only'],
'is_active' => true,
]);
- $adminRole = Role::firstOrCreate(
- ['identifier' => 'admin'],
- [
- 'name' => json_encode(['ko' => '관리자', 'en' => 'Admin']),
- 'description' => json_encode(['ko' => '시스템 관리자', 'en' => 'System Admin']),
- 'extension_type' => ExtensionOwnerType::Core,
- 'extension_identifier' => 'core',
- 'type' => 'admin',
- 'is_active' => true,
- ]
- );
-
if (! empty($permissionIds)) {
$testRole->permissions()->sync($permissionIds);
}
- $user->roles()->attach($adminRole->id, ['assigned_at' => now(), 'assigned_by' => null]);
+ if ($withAdminRole) {
+ $adminRole = Role::firstOrCreate(
+ ['identifier' => 'admin'],
+ [
+ 'name' => ['ko' => '관리자', 'en' => 'Admin'],
+ 'description' => ['ko' => '시스템 관리자', 'en' => 'System Admin'],
+ 'extension_type' => ExtensionOwnerType::Core,
+ 'extension_identifier' => 'core',
+ 'type' => 'admin',
+ 'is_active' => true,
+ ]
+ );
+
+ $user->roles()->attach($adminRole->id, ['assigned_at' => now(), 'assigned_by' => null]);
+ }
+
+ // test role 은 항상 부여한다 — GC(pruneStaleTestArtifacts)가 이 역할로 테스트 계정을
+ // 식별하므로, 빠지면 --no-admin-role 로 만든 계정이 영구 잔존한다.
$user->roles()->attach($testRole->id, ['assigned_at' => now(), 'assigned_by' => null]);
return $user->fresh();
diff --git a/app/Console/Commands/PlaywrightSeedLayout.php b/app/Console/Commands/PlaywrightSeedLayout.php
new file mode 100644
index 00000000..812a3599
--- /dev/null
+++ b/app/Console/Commands/PlaywrightSeedLayout.php
@@ -0,0 +1,377 @@
+
+ */
+ private const DEFAULT_TARGETS = [
+ 'sirsoft-basic' => '/e2e-sandbox',
+ 'sirsoft-admin_basic' => '*/admin/e2e-sandbox',
+ ];
+
+ public function __construct(
+ private LayoutRepositoryInterface $layoutRepository,
+ private TemplateRepositoryInterface $templateRepository
+ ) {
+ parent::__construct();
+ }
+
+ /**
+ * 커맨드를 실행합니다.
+ *
+ * @return int 종료 코드 (0 성공)
+ */
+ public function handle(): int
+ {
+ // ① CLI 한정 — production 웹 요청에서 절대 도달 불가
+ if (php_sapi_name() !== 'cli') {
+ $this->error('CLI 전용 커맨드입니다. (현재 SAPI: '.php_sapi_name().')');
+
+ return self::FAILURE;
+ }
+
+ // ② 명시 옵트인 — 환경변수 없이는 production 호출 실수 차단
+ if (env('G7_PLAYWRIGHT_BYPASS') !== '1') {
+ $this->error('G7_PLAYWRIGHT_BYPASS=1 환경변수가 필요합니다. (예: PowerShell — $env:G7_PLAYWRIGHT_BYPASS=\'1\')');
+
+ return self::FAILURE;
+ }
+
+ // settings JSON 이 debug 를 덮어써도 시드 작업이 막히지 않도록 인라인 강제
+ // (PlaywrightIssueToken 과 동일 근거 — bypass flag 인지 시 SettingsServiceProvider 는 이미 우회 상태).
+ Config::set('app.debug', true);
+
+ $remove = (bool) $this->option('remove');
+ $targets = $this->resolveTargets();
+
+ if ($targets === []) {
+ $this->error('대상 템플릿이 없습니다.');
+
+ return self::FAILURE;
+ }
+
+ foreach ($targets as $identifier => $routePath) {
+ if (! $this->processTemplate($identifier, $routePath, $remove)) {
+ return self::FAILURE;
+ }
+ }
+
+ return self::SUCCESS;
+ }
+
+ /**
+ * `--template` 옵션을 기본 대상 목록과 대조해 처리 대상을 결정합니다.
+ *
+ * @return array identifier => 라우트 경로
+ */
+ private function resolveTargets(): array
+ {
+ $requested = $this->option('template') ?: [];
+
+ if ($requested === []) {
+ return self::DEFAULT_TARGETS;
+ }
+
+ $targets = [];
+ foreach ($requested as $identifier) {
+ if (! isset(self::DEFAULT_TARGETS[$identifier])) {
+ $this->warn("시드 라우트 경로가 정의되지 않은 템플릿입니다 — 건너뜁니다: {$identifier}");
+
+ continue;
+ }
+ $targets[$identifier] = self::DEFAULT_TARGETS[$identifier];
+ }
+
+ return $targets;
+ }
+
+ /**
+ * 템플릿 1개에 대해 시드 레이아웃 설치 또는 제거를 수행합니다.
+ *
+ * @param string $identifier 템플릿 identifier
+ * @param string $routePath 시드 라우트 경로
+ * @param bool $remove true 면 제거, false 면 설치
+ * @return bool 성공 여부
+ */
+ private function processTemplate(string $identifier, string $routePath, bool $remove): bool
+ {
+ $templateDir = base_path("templates/{$identifier}");
+
+ // 활성 디렉토리가 없으면 그 템플릿은 설치되지 않은 것 — 조용히 건너뛴다
+ // (E2E 대상 템플릿이 환경마다 다를 수 있으므로 실패로 취급하지 않는다).
+ if (! File::isDirectory($templateDir)) {
+ $this->warn("활성 템플릿 디렉토리가 없어 건너뜁니다: {$identifier}");
+
+ return true;
+ }
+
+ $template = $this->templateRepository->findByIdentifier($identifier);
+ if (! $template) {
+ $this->warn("템플릿이 DB 에 없어 건너뜁니다: {$identifier}");
+
+ return true;
+ }
+
+ $layoutPath = "{$templateDir}/layouts/".self::LAYOUT_NAME.'.json';
+
+ if ($remove) {
+ if (File::exists($layoutPath)) {
+ File::delete($layoutPath);
+ }
+ $this->removeSeedRoute($identifier, $templateDir);
+ $this->layoutRepository->deleteByName($template->id, self::LAYOUT_NAME);
+ } else {
+ $fixturePath = base_path(
+ 'tests/Playwright/fixtures/seed-layouts/'.$identifier.'.'.self::LAYOUT_NAME.'.json'
+ );
+ if (! File::exists($fixturePath)) {
+ $this->error("시드 레이아웃 fixture 가 없습니다: {$fixturePath}");
+
+ return false;
+ }
+
+ $content = json_decode((string) File::get($fixturePath), true);
+ if (json_last_error() !== JSON_ERROR_NONE || ! is_array($content)) {
+ $this->error("시드 레이아웃 fixture 파싱 실패: {$fixturePath}");
+
+ return false;
+ }
+
+ File::copy($fixturePath, $layoutPath);
+ $this->addSeedRoute($identifier, $templateDir, $routePath);
+
+ $this->layoutRepository->updateOrCreate(
+ ['template_id' => $template->id, 'name' => self::LAYOUT_NAME],
+ [
+ 'content' => $content,
+ 'source_type' => 'template',
+ 'original_content_hash' => $this->computeContentHash($content),
+ 'original_content_size' => $this->computeContentSize($content),
+ ]
+ );
+ }
+
+ // 편집기/공개 서빙 캐시에서 시드 레이아웃 키를 지운다. 삭제 경로에서도 캐시가 남으면
+ // 편집기가 stale 문서를 계속 받는다.
+ $this->forgetSeedLayoutCache($template->id, $identifier);
+
+ $this->info(($remove ? '제거' : '설치')." 완료: {$identifier} ({$routePath})");
+
+ return true;
+ }
+
+ /**
+ * 활성 routes.json 에 시드 라우트를 추가합니다.
+ *
+ * 재작성은 JSON 재직렬화라 원본의 주석 그룹 사이 빈 줄 같은 서식이 사라진다. 그래서 첫
+ * 설치 시 원본을 `.playwright-backup` 으로 보관하고, 제거 때 그 파일을 그대로 되돌린다
+ * (바이트 동일 복원). 백업이 이미 있으면 덮어쓰지 않는다 — 비정상 종료로 시드가 남은 상태의
+ * routes.json 을 "원본" 으로 굳히지 않기 위함.
+ *
+ * @param string $identifier 템플릿 identifier
+ * @param string $templateDir 활성 템플릿 디렉토리 절대 경로
+ * @param string $routePath 등록할 시드 라우트 경로
+ */
+ private function addSeedRoute(string $identifier, string $templateDir, string $routePath): void
+ {
+ $path = "{$templateDir}/routes.json";
+ $routes = $this->readRoutes($identifier, $path);
+ if ($routes === null) {
+ return;
+ }
+
+ $backupPath = $path.self::ROUTES_BACKUP_SUFFIX;
+ if (! File::exists($backupPath)) {
+ File::copy($path, $backupPath);
+ }
+
+ // 마커 항목을 먼저 걷어내 반복 실행이 라우트를 중복 추가하지 않게 한다.
+ $entries = $this->withoutSeedRoutes($routes);
+ $entries[] = [
+ '_marker' => self::ROUTE_MARKER,
+ '_comment' => 'Playwright E2E 전용 시드 화면 — playwright:seed-layout 이 설치/제거한다. 제품 라우트가 아니다.',
+ 'path' => $routePath,
+ 'layout' => self::LAYOUT_NAME,
+ 'auth_required' => str_starts_with($routePath, '*/admin'),
+ 'meta' => [
+ 'title' => 'E2E Sandbox',
+ ],
+ ];
+
+ $routes['routes'] = $entries;
+
+ File::put(
+ $path,
+ json_encode($routes, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)."\n"
+ );
+ }
+
+ /**
+ * 활성 routes.json 에서 시드 라우트를 제거합니다.
+ *
+ * 백업이 있으면 그것을 그대로 복원해 서식까지 원상 복구한다. 백업이 없으면(다른 경로로 시드가
+ * 들어간 경우) 마커 항목만 걷어낸 재직렬화로 대체한다.
+ *
+ * @param string $identifier 템플릿 identifier
+ * @param string $templateDir 활성 템플릿 디렉토리 절대 경로
+ */
+ private function removeSeedRoute(string $identifier, string $templateDir): void
+ {
+ $path = "{$templateDir}/routes.json";
+ $backupPath = $path.self::ROUTES_BACKUP_SUFFIX;
+
+ if (File::exists($backupPath)) {
+ File::put($path, File::get($backupPath));
+ File::delete($backupPath);
+
+ return;
+ }
+
+ $routes = $this->readRoutes($identifier, $path);
+ if ($routes === null) {
+ return;
+ }
+
+ $routes['routes'] = $this->withoutSeedRoutes($routes);
+
+ File::put(
+ $path,
+ json_encode($routes, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)."\n"
+ );
+ }
+
+ /**
+ * routes.json 을 디코드해 반환합니다 (부재/파싱 실패 시 경고 후 null).
+ *
+ * @param string $identifier 템플릿 identifier (경고 메시지용)
+ * @param string $path routes.json 절대 경로
+ * @return array|null 디코드 결과
+ */
+ private function readRoutes(string $identifier, string $path): ?array
+ {
+ if (! File::exists($path)) {
+ $this->warn("routes.json 이 없어 라우트 처리를 건너뜁니다: {$identifier}");
+
+ return null;
+ }
+
+ $routes = json_decode((string) File::get($path), true);
+ if (json_last_error() !== JSON_ERROR_NONE || ! is_array($routes)) {
+ $this->warn("routes.json 을 파싱할 수 없어 라우트 처리를 건너뜁니다: {$identifier}");
+
+ return null;
+ }
+
+ return $routes;
+ }
+
+ /**
+ * 라우트 배열에서 시드 마커가 붙은 항목을 제외해 반환합니다.
+ *
+ * @param array $routes 디코드된 routes.json
+ * @return array 마커 항목이 제거된 라우트 배열
+ */
+ private function withoutSeedRoutes(array $routes): array
+ {
+ return array_values(array_filter(
+ $routes['routes'] ?? [],
+ fn ($route) => ! is_array($route) || ($route['_marker'] ?? null) !== self::ROUTE_MARKER
+ ));
+ }
+
+ /**
+ * 시드 레이아웃의 캐시 키를 삭제합니다.
+ *
+ * `InvalidatesLayoutCache::forgetLayoutCacheKeys` 는 레이아웃 객체의
+ * `template_id` / `name` / `source_type` / `source_identifier` 만 읽으므로,
+ * 삭제 후(모델 부재) 에도 동일 형태의 경량 객체로 호출할 수 있다.
+ *
+ * @param int $templateId 템플릿 ID
+ * @param string $identifier 템플릿 identifier (버전 포함 공개 서빙 키에 사용)
+ */
+ private function forgetSeedLayoutCache(int $templateId, string $identifier): void
+ {
+ $this->forgetLayoutCacheKeys(
+ (object) [
+ 'template_id' => $templateId,
+ 'name' => self::LAYOUT_NAME,
+ 'source_type' => null,
+ 'source_identifier' => null,
+ ],
+ $identifier
+ );
+ }
+}
diff --git a/app/Console/Commands/Plugin/CheckPluginUpdatesCommand.php b/app/Console/Commands/Plugin/CheckPluginUpdatesCommand.php
index 8e41bbcc..17356375 100644
--- a/app/Console/Commands/Plugin/CheckPluginUpdatesCommand.php
+++ b/app/Console/Commands/Plugin/CheckPluginUpdatesCommand.php
@@ -116,7 +116,7 @@ class CheckPluginUpdatesCommand extends Command
$updateCount = 0;
foreach ($result['details'] as $detail) {
- $isUpdate = $detail['update_available'] ?? false;
+ $isUpdate = (bool) ($detail['update_available'] ?? true);
if ($isUpdate) {
$updateCount++;
}
@@ -143,7 +143,7 @@ class CheckPluginUpdatesCommand extends Command
$this->table($headers, $tableData);
$this->newLine();
$this->info(__('plugins.commands.check_updates.summary', [
- 'total' => count($result['details']),
+ 'total' => $result['checked_count'] ?? count($result['details']),
'updates' => $updateCount,
]));
diff --git a/app/Console/Commands/Plugin/InstallPluginCommand.php b/app/Console/Commands/Plugin/InstallPluginCommand.php
index d4ab9488..47869484 100644
--- a/app/Console/Commands/Plugin/InstallPluginCommand.php
+++ b/app/Console/Commands/Plugin/InstallPluginCommand.php
@@ -3,6 +3,7 @@
namespace App\Console\Commands\Plugin;
use App\Console\Commands\Traits\HasProgressBar;
+use App\Console\Commands\Traits\RebuildsSearchIndex;
use App\Contracts\Repositories\PluginRepositoryInterface;
use App\Enums\ExtensionOwnerType;
use App\Extension\PluginManager;
@@ -16,6 +17,7 @@ use Illuminate\Support\Facades\Validator;
class InstallPluginCommand extends Command
{
use HasProgressBar;
+ use RebuildsSearchIndex;
/**
* The name and signature of the console command.
@@ -23,7 +25,8 @@ class InstallPluginCommand extends Command
protected $signature = 'plugin:install
{identifier : 설치할 플러그인 식별자}
{--vendor-mode=auto : Vendor 설치 모드 (auto|composer|bundled)}
- {--force : 이미 설치된 경우에도 _bundled/_pending 원본으로 활성 디렉토리를 덮어쓰고 재설치 (불완전 설치 복구)}';
+ {--force : 이미 설치된 경우에도 _bundled/_pending 원본으로 활성 디렉토리를 덮어쓰고 재설치 (불완전 설치 복구)}
+ {--rebuild-search-index : 완료 후 색인이 누락된 검색 인덱스를 재생성 (인덱스가 잠기거나 재색인됩니다 — 운영 중에는 유지보수 시간에 수행하세요)}';
/**
* The console command description.
@@ -111,6 +114,9 @@ class InstallPluginCommand extends Command
Log::info(__('plugins.commands.install.success', ['plugin' => $identifier]));
+ // 검색 인덱스 재생성은 운영자가 선택했을 때만 수행한다 (인덱스 잠금·재색인 비용)
+ $this->handleSearchIndexRebuild();
+
return Command::SUCCESS;
}
diff --git a/app/Console/Commands/Plugin/UpdatePluginCommand.php b/app/Console/Commands/Plugin/UpdatePluginCommand.php
index 82e95e3f..1a5038f9 100644
--- a/app/Console/Commands/Plugin/UpdatePluginCommand.php
+++ b/app/Console/Commands/Plugin/UpdatePluginCommand.php
@@ -4,6 +4,7 @@ namespace App\Console\Commands\Plugin;
use App\Console\Commands\Traits\HasProgressBar;
use App\Console\Commands\Traits\HasUnifiedConfirm;
+use App\Console\Commands\Traits\RebuildsSearchIndex;
use App\Contracts\Repositories\PluginRepositoryInterface;
use App\Enums\LayoutSourceType;
use App\Extension\PluginManager;
@@ -16,6 +17,7 @@ class UpdatePluginCommand extends Command
{
use HasProgressBar;
use HasUnifiedConfirm;
+ use RebuildsSearchIndex;
/**
* The name and signature of the console command.
@@ -26,7 +28,8 @@ class UpdatePluginCommand extends Command
{--vendor-mode=auto : Vendor 설치 모드 (auto|composer|bundled)}
{--layout-strategy=overwrite : 레이아웃 전략 (overwrite|keep)}
{--source=auto : 업데이트 소스 (auto|bundled|github) — bundled 는 _bundled 만 사용(GitHub 우회)}
- {--zip= : 외부 ZIP 파일 경로 (지정 시 GitHub/번들 우회 + 버전은 plugin.json 기준)}';
+ {--zip= : 외부 ZIP 파일 경로 (지정 시 GitHub/번들 우회 + 버전은 plugin.json 기준)}
+ {--rebuild-search-index : 완료 후 색인이 누락된 검색 인덱스를 재생성 (인덱스가 잠기거나 재색인됩니다 — 운영 중에는 유지보수 시간에 수행하세요)}';
/**
* The console command description.
@@ -202,6 +205,9 @@ class UpdatePluginCommand extends Command
'layout_strategy' => $layoutStrategy,
]);
+ // 검색 인덱스 재생성은 운영자가 선택했을 때만 수행한다 (인덱스 잠금·재색인 비용)
+ $this->handleSearchIndexRebuild();
+
return Command::SUCCESS;
}
diff --git a/app/Console/Commands/Search/SearchIndexCommand.php b/app/Console/Commands/Search/SearchIndexCommand.php
new file mode 100644
index 00000000..82e0dd10
--- /dev/null
+++ b/app/Console/Commands/Search/SearchIndexCommand.php
@@ -0,0 +1,194 @@
+driver();
+ $filters = $this->parseFilters();
+
+ if (! $manager->hasMaintainer()) {
+ $this->components->warn(__('search.index.no_maintainer', ['driver' => $driver]));
+
+ return self::SUCCESS;
+ }
+
+ if (($reason = $manager->unavailableReason()) !== null) {
+ $this->components->warn($reason);
+
+ return self::SUCCESS;
+ }
+
+ $results = $manager->inspect($filters);
+
+ if ($results === []) {
+ $this->components->warn(__('search.index.no_targets', ['driver' => $driver]));
+
+ return self::SUCCESS;
+ }
+
+ $report = null;
+
+ if ($this->option('repair')) {
+ $targets = array_values(array_filter($results, fn (SearchIndexHealth $h) => $h->needsRebuild()));
+
+ if ($targets !== [] && $this->confirmRebuild($targets)) {
+ $report = $manager->repairStale($filters);
+ $results = $manager->inspect($filters);
+ }
+ }
+
+ if ($this->option('json')) {
+ $this->line((string) json_encode([
+ 'driver' => $driver,
+ 'results' => array_map(fn (SearchIndexHealth $h) => $h->toArray(), $results),
+ 'repair' => $report?->toArray(),
+ ], JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT));
+ } else {
+ $this->render($driver, $results, $report?->summary());
+ }
+
+ $remaining = array_filter($results, fn (SearchIndexHealth $h) => $h->needsRebuild());
+
+ return ($remaining === [] && ($report === null || $report->failed === [])) ? self::SUCCESS : self::FAILURE;
+ }
+
+ /**
+ * `--filter=key=value` 옵션을 연관 배열로 해석합니다.
+ *
+ * @return array
+ */
+ private function parseFilters(): array
+ {
+ $filters = [];
+
+ foreach ((array) $this->option('filter') as $raw) {
+ if (! is_string($raw) || ! str_contains($raw, '=')) {
+ continue;
+ }
+
+ [$key, $value] = explode('=', $raw, 2);
+ $key = trim($key);
+
+ if ($key !== '') {
+ $filters[$key] = trim($value);
+ }
+ }
+
+ return $filters;
+ }
+
+ /**
+ * 재생성 대상을 보여 주고 진행 여부를 확인합니다.
+ *
+ * @param array $targets 재생성 대상
+ * @return bool 진행 여부
+ */
+ private function confirmRebuild(array $targets): bool
+ {
+ $this->newLine();
+ $this->components->info(__('search.index.rebuild_targets', ['count' => count($targets)]));
+
+ foreach ($targets as $target) {
+ $this->line(' - '.$target->identifier.' ('.$target->measurement.')');
+ }
+
+ $this->components->warn(__('search.index.rebuild_cost_warning'));
+
+ if ($this->unifiedConfirm(__('search.index.rebuild_confirm'), true)) {
+ return true;
+ }
+
+ $this->components->info(__('search.index.rebuild_skipped'));
+
+ return false;
+ }
+
+ /**
+ * 판정 결과를 표로 출력합니다.
+ *
+ * @param string $driver 드라이버명
+ * @param array $results 판정 결과
+ * @param string|null $repairSummary 재생성 요약 (수행했을 때만)
+ * @return void
+ */
+ private function render(string $driver, array $results, ?string $repairSummary): void
+ {
+ $rows = array_map(fn (SearchIndexHealth $health) => [
+ $health->identifier,
+ 'status->consoleColor().'>'.$health->status->label().'',
+ $health->measurement,
+ ], $results);
+
+ $this->newLine();
+ $this->line(' '.__('search.index.driver_label', ['driver' => $driver]));
+ $this->table([__('search.index.col.index'), __('search.index.col.status'), __('search.index.col.measurement')], $rows);
+
+ $counts = [];
+ foreach (SearchIndexStatus::cases() as $case) {
+ $counts[$case->value] = count(array_filter($results, fn (SearchIndexHealth $h) => $h->status === $case));
+ }
+
+ $this->line(' '.__('search.index.counts', [
+ 'healthy' => $counts[SearchIndexStatus::Healthy->value],
+ 'degraded' => $counts[SearchIndexStatus::Degraded->value],
+ 'stale' => $counts[SearchIndexStatus::Stale->value],
+ 'skipped' => $counts[SearchIndexStatus::Skipped->value],
+ 'total' => count($results),
+ ]));
+
+ if ($repairSummary !== null) {
+ $this->newLine();
+ $this->components->info($repairSummary);
+ }
+
+ if ($counts[SearchIndexStatus::Stale->value] > 0 && ! $this->option('repair')) {
+ $this->newLine();
+ $this->components->warn(__('search.index.stale_hint'));
+ }
+
+ if ($counts[SearchIndexStatus::Degraded->value] > 0) {
+ $this->line(' '.__('search.index.degraded_hint').'');
+ }
+ }
+}
diff --git a/app/Console/Commands/SeoGenerateSitemapCommand.php b/app/Console/Commands/SeoGenerateSitemapCommand.php
index 1198e680..9bf5f1aa 100644
--- a/app/Console/Commands/SeoGenerateSitemapCommand.php
+++ b/app/Console/Commands/SeoGenerateSitemapCommand.php
@@ -2,6 +2,7 @@
namespace App\Console\Commands;
+use App\Enums\SitemapGenerationMode;
use App\Jobs\GenerateSitemapJob;
use Illuminate\Console\Command;
use Illuminate\Support\Facades\Config;
@@ -17,7 +18,10 @@ class SeoGenerateSitemapCommand extends Command
/**
* @var string 커맨드 시그니처
*/
- protected $signature = 'seo:generate-sitemap {--sync : 큐 드라이버를 무시하고 동기 실행}';
+ protected $signature = 'seo:generate-sitemap
+ {--sync : 큐 드라이버를 무시하고 동기 실행}
+ {--rebuild : 저장소 상태와 무관하게 전체 재생성 (--mode=full 과 동일)}
+ {--mode=auto : 재생성 모드 (full|auto|incremental)}';
/**
* @var string 커맨드 설명
@@ -31,6 +35,14 @@ class SeoGenerateSitemapCommand extends Command
*/
public function handle(): int
{
+ $mode = $this->resolveMode();
+ if ($mode === null) {
+ $allowed = implode(', ', array_map(fn (SitemapGenerationMode $m): string => $m->value, SitemapGenerationMode::cases()));
+ $this->error('잘못된 모드입니다. 허용: '.$allowed);
+
+ return Command::INVALID;
+ }
+
$forceSync = (bool) $this->option('sync');
// queue.default 는 SettingsServiceProvider 가 drivers.queue_driver 와 동기화하되,
// testing 환경에서는 phpunit.xml 값을 보존하므로 격리가 유지된다.
@@ -38,13 +50,29 @@ class SeoGenerateSitemapCommand extends Command
$isSyncDriver = $connection === 'sync';
if ($forceSync || $isSyncDriver) {
- GenerateSitemapJob::dispatchSync();
- $this->info('Sitemap이 생성되었습니다.');
+ GenerateSitemapJob::dispatchSync($mode);
+ $this->info("Sitemap이 생성되었습니다. (모드: {$mode->value})");
} else {
- GenerateSitemapJob::dispatch();
- $this->info('Sitemap 생성이 큐에 디스패치되었습니다.');
+ GenerateSitemapJob::dispatch($mode);
+ $this->info("Sitemap 생성이 큐에 디스패치되었습니다. (모드: {$mode->value})");
}
return Command::SUCCESS;
}
+
+ /**
+ * --rebuild / --mode 옵션으로부터 재생성 모드를 해석합니다.
+ *
+ * --rebuild 는 --mode 보다 우선하며 Full 로 강제합니다.
+ *
+ * @return SitemapGenerationMode|null 재생성 모드 (유효하지 않으면 null)
+ */
+ private function resolveMode(): ?SitemapGenerationMode
+ {
+ if ((bool) $this->option('rebuild')) {
+ return SitemapGenerationMode::Full;
+ }
+
+ return SitemapGenerationMode::tryFrom((string) $this->option('mode'));
+ }
}
diff --git a/app/Console/Commands/Template/CheckTemplateUpdatesCommand.php b/app/Console/Commands/Template/CheckTemplateUpdatesCommand.php
index ea17ed92..de4f66bd 100644
--- a/app/Console/Commands/Template/CheckTemplateUpdatesCommand.php
+++ b/app/Console/Commands/Template/CheckTemplateUpdatesCommand.php
@@ -116,7 +116,7 @@ class CheckTemplateUpdatesCommand extends Command
$updateCount = 0;
foreach ($result['details'] as $detail) {
- $isUpdate = $detail['update_available'] ?? false;
+ $isUpdate = (bool) ($detail['update_available'] ?? true);
if ($isUpdate) {
$updateCount++;
}
@@ -143,7 +143,7 @@ class CheckTemplateUpdatesCommand extends Command
$this->table($headers, $tableData);
$this->newLine();
$this->info(__('templates.commands.check_updates.summary', [
- 'total' => count($result['details']),
+ 'total' => $result['checked_count'] ?? count($result['details']),
'updates' => $updateCount,
]));
diff --git a/app/Console/Commands/Traits/RebuildsSearchIndex.php b/app/Console/Commands/Traits/RebuildsSearchIndex.php
new file mode 100644
index 00000000..1cee0e28
--- /dev/null
+++ b/app/Console/Commands/Traits/RebuildsSearchIndex.php
@@ -0,0 +1,114 @@
+hasMaintainer() || $manager->unavailableReason() !== null) {
+ return null;
+ }
+
+ $requested ??= (bool) $this->option('rebuild-search-index');
+
+ if ($requested) {
+ $report = $manager->repairStale();
+ $this->reportRebuild($report);
+
+ return $report;
+ }
+
+ $this->warnStale($manager->inspect());
+
+ return null;
+ }
+
+ /**
+ * 재생성하지 않은 경우, 색인 누락 사실만 안내합니다.
+ *
+ * @param array $results 점검 결과
+ * @return void
+ */
+ private function warnStale(array $results): void
+ {
+ $stale = array_values(array_filter($results, fn (SearchIndexHealth $h) => $h->needsRebuild()));
+
+ if ($stale === []) {
+ return;
+ }
+
+ $this->newLine();
+ $this->warn('⚠️ '.__('search.index.stale_after_update', ['count' => count($stale)]));
+
+ foreach ($stale as $health) {
+ $this->line(' - '.$health->identifier);
+ }
+
+ $this->line(' '.__('search.index.stale_hint'));
+ }
+
+ /**
+ * 재생성 보고를 콘솔에 출력합니다.
+ *
+ * @param SearchIndexRepairReport $report 재생성 보고
+ * @return void
+ */
+ private function reportRebuild(SearchIndexRepairReport $report): void
+ {
+ $this->newLine();
+
+ if (! $report->didRebuild()) {
+ $this->info('✅ '.$report->summary());
+
+ return;
+ }
+
+ $this->info('✅ '.$report->summary());
+
+ foreach ($report->repaired as $identifier) {
+ $this->line(' '.__('search.index.rebuilt_item', ['index' => $identifier]));
+ }
+
+ foreach ($report->failed as $identifier => $message) {
+ $this->error(' '.__('search.index.rebuild_failed_item', ['index' => $identifier, 'error' => $message]));
+ }
+
+ foreach ($report->remaining as $identifier) {
+ $this->warn(' '.__('search.index.still_stale_item', ['index' => $identifier]));
+ }
+ }
+}
diff --git a/app/Contracts/Pagination/BoundedTotalAware.php b/app/Contracts/Pagination/BoundedTotalAware.php
new file mode 100644
index 00000000..72cf351f
--- /dev/null
+++ b/app/Contracts/Pagination/BoundedTotalAware.php
@@ -0,0 +1,39 @@
+ $ids 삭제할 활동 로그 ID 목록
+ * @param array $ids 삭제할 활동 로그 ID 목록
* @return int 삭제된 건수
*/
public function deleteMany(array $ids): int;
diff --git a/app/Contracts/Repositories/LayoutExtensionVersionRepositoryInterface.php b/app/Contracts/Repositories/LayoutExtensionVersionRepositoryInterface.php
index 9e05cc67..1800a6b0 100644
--- a/app/Contracts/Repositories/LayoutExtensionVersionRepositoryInterface.php
+++ b/app/Contracts/Repositories/LayoutExtensionVersionRepositoryInterface.php
@@ -24,7 +24,20 @@ interface LayoutExtensionVersionRepositoryInterface
* @param int $extensionId 레이아웃 확장 ID
* @return Collection 버전 컬렉션
*/
- public function getVersions(int $extensionId): Collection;
+ public function getVersions(int $extensionId, int $limit = 100): Collection;
+
+ /**
+ * 확장의 특정 버전 번호 조회 (본문 포함)
+ *
+ * 목록(getVersions)은 경량 조회라 `content` 를 담지 않고 건수 상한이 있다. 단건은 그
+ * 대체 경로이므로 반드시 전용 조회를 쓴다 — 목록 조회를 재사용하면 본문이 사라지고
+ * 상한 밖의 오래된 버전을 찾지 못한다.
+ *
+ * @param int $extensionId 레이아웃 확장 ID
+ * @param int $version 버전 번호
+ * @return TemplateLayoutExtensionVersion|null 찾은 버전 모델 또는 null
+ */
+ public function findVersionByNumber(int $extensionId, int $version): ?TemplateLayoutExtensionVersion;
/**
* 확장 ID 목록의 현재(최신) 버전 번호 맵 조회
diff --git a/app/Contracts/Repositories/LayoutRepositoryInterface.php b/app/Contracts/Repositories/LayoutRepositoryInterface.php
index 492313eb..c675d249 100644
--- a/app/Contracts/Repositories/LayoutRepositoryInterface.php
+++ b/app/Contracts/Repositories/LayoutRepositoryInterface.php
@@ -6,6 +6,7 @@ use App\Enums\LayoutSourceType;
use App\Models\TemplateLayout;
use App\Models\TemplateLayoutVersion;
use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Support\Collection as SupportCollection;
interface LayoutRepositoryInterface
{
@@ -17,6 +18,17 @@ interface LayoutRepositoryInterface
*/
public function getByTemplateId(int $templateId): Collection;
+ /**
+ * 목록 표시용 경량 레이아웃 행 조회
+ *
+ * 본문(`content`)을 반환에 포함하지 않는다 — 설명·크기 등 본문 파생값만 계산해 담는다.
+ * 편집 대상 본문은 상세 조회가 제공한다.
+ *
+ * @param int $templateId 템플릿 ID
+ * @return Collection 목록 행 배열 컬렉션
+ */
+ public function getListByTemplateId(int $templateId): SupportCollection;
+
/**
* 특정 레이아웃 조회 (템플릿 ID와 이름으로)
*
@@ -26,6 +38,19 @@ interface LayoutRepositoryInterface
*/
public function findByName(int $templateId, string $name): ?TemplateLayout;
+ /**
+ * 특정 레이아웃을 영구 삭제 (템플릿 ID와 이름으로)
+ *
+ * soft delete 가 아닌 `forceDelete` 다. 이름으로 재등록될 수 있는 레이아웃
+ * (파일 → DB 동기화 대상) 은 soft delete 잔여 행이 남으면 재등록이 충돌하므로
+ * 파일 기준 동기화 경로와 동일하게 영구 삭제한다.
+ *
+ * @param int $templateId 템플릿 ID
+ * @param string $name 레이아웃 이름
+ * @return bool 삭제 여부 (대상 부재 시 false)
+ */
+ public function deleteByName(int $templateId, string $name): bool;
+
/**
* ID로 레이아웃 조회
*
@@ -113,12 +138,16 @@ interface LayoutRepositoryInterface
public function updateContent(int $id, array $content, int $newLockVersion): TemplateLayout;
/**
- * 특정 레이아웃의 모든 버전 조회
+ * 특정 레이아웃의 최근 버전 목록 조회 (최신순)
+ *
+ * 버전 행은 저장할 때마다 쌓이고 정리되지 않으므로 조회 건수에 상한이 있습니다.
+ * 목록이 쓰지 않는 `content`(버전마다 레이아웃 본문 사본)는 조회하지 않습니다.
*
* @param int $layoutId 레이아웃 ID
+ * @param int $limit 조회할 최대 버전 수
* @return Collection 버전 컬렉션
*/
- public function getVersionsByLayoutId(int $layoutId): Collection;
+ public function getVersionsByLayoutId(int $layoutId, int $limit = 100): Collection;
/**
* 특정 버전 조회
diff --git a/app/Contracts/Repositories/NotificationLogRepositoryInterface.php b/app/Contracts/Repositories/NotificationLogRepositoryInterface.php
index e53edf92..0673c73d 100644
--- a/app/Contracts/Repositories/NotificationLogRepositoryInterface.php
+++ b/app/Contracts/Repositories/NotificationLogRepositoryInterface.php
@@ -5,6 +5,7 @@ namespace App\Contracts\Repositories;
use App\Models\NotificationLog;
use App\Models\User;
use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Pagination\CursorPaginator;
use Illuminate\Pagination\LengthAwarePaginator;
interface NotificationLogRepositoryInterface
@@ -44,5 +45,5 @@ interface NotificationLogRepositoryInterface
*
* @param User|null $scopeUser 스코프 적용 대상 사용자 (null이면 스코프 미적용)
*/
- public function getPaginated(array $filters = [], int $perPage = 20, ?User $scopeUser = null): LengthAwarePaginator;
+ public function getPaginated(array $filters = [], int $perPage = 20, ?User $scopeUser = null): LengthAwarePaginator|CursorPaginator;
}
diff --git a/app/Contracts/Repositories/SeoCacheStatRepositoryInterface.php b/app/Contracts/Repositories/SeoCacheStatRepositoryInterface.php
new file mode 100644
index 00000000..c8b7cda9
--- /dev/null
+++ b/app/Contracts/Repositories/SeoCacheStatRepositoryInterface.php
@@ -0,0 +1,43 @@
+ $attributes 기록할 속성 (url, locale, layout_name, module_identifier, type, response_time_ms)
+ */
+ public function record(array $attributes): void;
+
+ /**
+ * 전체 캐시 통계를 집계합니다.
+ *
+ * @param Carbon|null $since 집계 시작 시점 (null 이면 전체 기간)
+ * @return array{total: int, hits: int, misses: int, avg_response_time_ms: float|null} 집계 결과
+ */
+ public function aggregate(?Carbon $since = null): array;
+
+ /**
+ * 지정한 컬럼으로 그룹화하여 캐시 통계를 집계합니다.
+ *
+ * @param string $groupBy 그룹 기준 컬럼 (layout_name | module_identifier)
+ * @param Carbon|null $since 집계 시작 시점 (null 이면 전체 기간)
+ * @return array 그룹별 집계 결과
+ */
+ public function aggregateGrouped(string $groupBy, ?Carbon $since = null): array;
+
+ /**
+ * 기준 시점보다 오래된 통계 레코드를 삭제합니다.
+ *
+ * @param Carbon $cutoff 기준 시점
+ * @return int 삭제된 레코드 수
+ */
+ public function deleteOlderThan(Carbon $cutoff): int;
+}
diff --git a/app/Contracts/Repositories/SitemapUrlRepositoryInterface.php b/app/Contracts/Repositories/SitemapUrlRepositoryInterface.php
new file mode 100644
index 00000000..3e97a5b9
--- /dev/null
+++ b/app/Contracts/Repositories/SitemapUrlRepositoryInterface.php
@@ -0,0 +1,62 @@
+ $entries URL 항목
+ */
+ public function upsertForResource(string $type, string $id, array $entries): void;
+
+ /**
+ * 한 리소스의 사이트맵 URL 행을 모두 제거합니다(비공개/삭제 시).
+ *
+ * @param string $type 리소스 유형
+ * @param string $id 리소스 PK (문자열)
+ */
+ public function removeForResource(string $type, string $id): void;
+
+ /**
+ * 공개(is_visible) URL 을 id 순으로 스트리밍합니다(유계 메모리).
+ *
+ * @param string|null $contributor 기여자 식별자로 스코핑 (null = 전체)
+ * @return iterable URL 순회자
+ */
+ public function streamVisible(?string $contributor = null): iterable;
+
+ /**
+ * 공개(is_visible) URL 총 개수를 반환합니다.
+ *
+ * @return int 공개 URL 수
+ */
+ public function countVisible(): int;
+
+ /**
+ * 한 기여자의 모든 사이트맵 URL 행을 전량 대체합니다(전체 재생성).
+ *
+ * 기여자 스코프로 기존 행을 제거한 뒤 스트림을 청크 삽입하여
+ * 대용량에서도 메모리를 유계로 유지합니다.
+ *
+ * @param string $contributor 기여자 식별자
+ * @param iterable $entries URL 항목 스트림
+ * @return int 삽입된 행 수 (진행상황 누적 URL 표기용 — count 쿼리 없이 스트림 누적)
+ */
+ public function replaceAllForContributor(string $contributor, iterable $entries): int;
+}
diff --git a/app/Contracts/Repositories/UserRepositoryInterface.php b/app/Contracts/Repositories/UserRepositoryInterface.php
index 703811aa..d6726dbf 100644
--- a/app/Contracts/Repositories/UserRepositoryInterface.php
+++ b/app/Contracts/Repositories/UserRepositoryInterface.php
@@ -144,17 +144,21 @@ interface UserRepositoryInterface
* `locked_until` 을 현재 시각 + $minutes 로 설정하고 `failed_login_attempts` 를
* 0 으로 리셋합니다 (다음 잠금 윈도우 시작점). 잠금 해제 시각을 반환합니다.
*
+ * `$minutes <= 0` 은 보안 환경설정의 "0 = 무한대" 규약에 따라 영구 잠금으로 처리하며,
+ * 이때 `locked_until` 은 NULL, `locked_permanently` 는 true 가 되고 null 을 반환합니다.
+ *
* @param User $user 잠글 사용자
- * @param int $minutes 잠금 유지 시간(분)
- * @return Carbon 잠금 해제 시각
+ * @param int $minutes 잠금 유지 시간(분). 0 이하는 무기한
+ * @return Carbon|null 잠금 해제 시각 (영구 잠금은 null)
*/
- public function lockAccount(User $user, int $minutes): Carbon;
+ public function lockAccount(User $user, int $minutes): ?Carbon;
/**
* 사용자의 모든 로그인 시도 추적 컬럼을 초기화합니다.
*
- * 정상 로그인 성공 시 호출됩니다 (`failed_login_attempts=0`,
- * `locked_until=null`, `last_failed_login_at=null`).
+ * 정상 로그인 성공 시 또는 관리자 수동 해제 시 호출됩니다
+ * (`failed_login_attempts=0`, `locked_until=null`, `locked_permanently=false`,
+ * `last_failed_login_at=null`).
*
* @param User $user 대상 사용자
*/
@@ -163,10 +167,55 @@ interface UserRepositoryInterface
/**
* 사용자의 계정이 현재 시점에 잠금 상태인지 판정합니다.
*
- * `locked_until` 이 NULL 이거나 현재 시각보다 과거이면 false 를 반환합니다.
+ * `locked_permanently` 가 true 면 항상 true 입니다. 그 외에는 `locked_until` 이
+ * NULL 이거나 현재 시각보다 과거이면 false 를 반환합니다.
*
* @param User $user 대상 사용자
* @return bool 잠금 여부
*/
public function isLocked(User $user): bool;
+
+ /**
+ * UUID 로 사용자를 찾습니다.
+ *
+ * @param string $uuid 사용자 UUID
+ * @return User|null 찾은 사용자 모델 또는 null
+ */
+ public function findByUuid(string $uuid): ?User;
+
+ /**
+ * UUID 목록에 해당하는 사용자의 정수 ID 배열을 반환합니다.
+ *
+ * @param array $uuids 사용자 UUID 배열
+ * @return array 사용자 ID 배열
+ */
+ public function getIdsByUuids(array $uuids): array;
+
+ /**
+ * 사용자 ID 목록에 해당하는 이름을 ID 로 색인해 반환합니다.
+ *
+ * 목록 화면이 작성자 이름을 행마다 조회하면 N+1 이 되므로, 표시에 필요한
+ * 이름만 한 번에 모아 오기 위한 배치 조회입니다.
+ *
+ * @param array $ids 사용자 ID 배열
+ * @return array 사용자 ID => 이름
+ */
+ public function getNamesByIds(array $ids): array;
+
+ /**
+ * 사용자 ID 목록의 지정 컬럼을 일괄 갱신합니다.
+ *
+ * @param array $ids 사용자 ID 배열
+ * @param array $data 갱신할 컬럼 값
+ * @return int 갱신된 행 수
+ */
+ public function updateManyByIds(array $ids, array $data): int;
+
+ /**
+ * 사용자 ID 목록의 인증 토큰을 모두 삭제합니다.
+ *
+ * @param array $ids 사용자 ID 배열
+ * @return int 삭제된 토큰 수
+ */
+ public function deleteTokensByUserIds(array $ids): int;
}
diff --git a/app/Enums/BenchmarkAxis.php b/app/Enums/BenchmarkAxis.php
new file mode 100644
index 00000000..9b6bc53d
--- /dev/null
+++ b/app/Enums/BenchmarkAxis.php
@@ -0,0 +1,93 @@
+ '목록 조회',
+ self::Screen => '화면 응답',
+ self::Write => '쓰기 작업',
+ self::Batch => '배치 작업',
+ };
+ }
+
+ /**
+ * 프로파일 선언에서 반드시 채워야 하는 옵션 키 목록
+ *
+ * 각 원소는 "대안 그룹"이며, 그룹마다 최소 하나가 선언되어야 합니다
+ * (`screen` 축은 라우트명 또는 URI 중 하나). 레지스트리가 이 목록으로 선언을
+ * 검증하며, 누락된 선언은 사유와 함께 경고로 드러내고 목록에서 제외합니다
+ * (조용히 버리면 계측 사각이 됩니다).
+ *
+ * @return array> 필수 옵션 대안 그룹 목록
+ */
+ public function requiredOptions(): array
+ {
+ return match ($this) {
+ self::ListQuery => [['table']],
+ self::Screen => [['route', 'uri']],
+ self::Write => [['callback']],
+ self::Batch => [['command']],
+ };
+ }
+
+ /**
+ * 기본적으로 데이터를 변경하는 축인지 여부
+ *
+ * true 인 축은 `--allow-write` 없이는 실행을 거부합니다. `screen` 축은 선언한
+ * HTTP 메서드에 따라 달라지므로 프로파일 단위로 다시 판정합니다.
+ *
+ * @return bool 데이터 변경 축 여부
+ */
+ public function mutatesByDefault(): bool
+ {
+ return match ($this) {
+ self::ListQuery, self::Screen => false,
+ self::Write, self::Batch => true,
+ };
+ }
+
+ /**
+ * 모든 값 배열
+ *
+ * @return array 축 값 목록
+ */
+ public static function values(): array
+ {
+ return array_column(self::cases(), 'value');
+ }
+}
diff --git a/app/Enums/IdentityVerificationPurpose.php b/app/Enums/IdentityVerificationPurpose.php
index 32fc9a21..b720fe62 100644
--- a/app/Enums/IdentityVerificationPurpose.php
+++ b/app/Enums/IdentityVerificationPurpose.php
@@ -5,10 +5,15 @@ namespace App\Enums;
/**
* 본인인증 코어 purpose Enum.
*
- * 코어가 계약으로 보장하는 4종 — `MailIdentityProvider` 가 모두 지원합니다.
+ * 코어가 계약으로 보장하는 5종 — `MailIdentityProvider` 가 모두 지원합니다.
* 모듈/플러그인은 `AbstractModule::getIdentityPurposes()` / `AbstractPlugin::getIdentityPurposes()`
* 로 추가 purpose 를 선언할 수 있으며, 그 값은 `IdentityVerificationManager::declaredPurposes`
- * 레지스트리에 string 으로 머지됩니다 — 본 enum 에는 코어 4종만 정의합니다.
+ * 레지스트리에 string 으로 머지됩니다 — 본 enum 에는 코어 5종만 정의합니다.
+ *
+ * case 를 추가하면 `IdentityVerificationManager::$corePurposes` 등록과
+ * `lang/{ko,en}/identity.php` 의 `purposes.{value}` 라벨을 함께 추가해야 합니다.
+ * 하나라도 빠지면 `label()` 이 i18n 키 원문을 그대로 돌려주고, 관리자 화면의
+ * 목적 목록에서 그 목적이 통째로 빠집니다.
*
* @since 7.0.0-beta.5
*/
@@ -26,6 +31,15 @@ enum IdentityVerificationPurpose: string
/** 민감 작업 (결제 등) */
case SensitiveAction = 'sensitive_action';
+ /**
+ * 로그인 2단계 인증
+ *
+ * 비밀번호 확인을 통과한 뒤 한 단계를 더 요구하는 용도입니다. 다른 purpose 와 달리
+ * 이 challenge 는 **아직 로그인하지 않은 주체**를 대상으로 하므로, 검증을 마치기
+ * 전까지 토큰이 발급되지 않습니다.
+ */
+ case Login = 'login';
+
/**
* 코어 purpose 값 배열.
*
diff --git a/app/Enums/SearchIndexStatus.php b/app/Enums/SearchIndexStatus.php
new file mode 100644
index 00000000..b6b0cf55
--- /dev/null
+++ b/app/Enums/SearchIndexStatus.php
@@ -0,0 +1,59 @@
+value);
+ }
+
+ /**
+ * 콘솔 출력용 색상명을 반환합니다.
+ *
+ * @return string Symfony 콘솔 색상명
+ */
+ public function consoleColor(): string
+ {
+ return match ($this) {
+ self::Healthy => 'green',
+ self::Degraded => 'yellow',
+ self::Stale => 'red',
+ self::Skipped => 'gray',
+ };
+ }
+
+ /**
+ * 모든 케이스의 string 값 목록.
+ *
+ * @return array
+ */
+ public static function allValues(): array
+ {
+ return array_column(self::cases(), 'value');
+ }
+}
diff --git a/app/Enums/SitemapChangeFreq.php b/app/Enums/SitemapChangeFreq.php
new file mode 100644
index 00000000..28c2046c
--- /dev/null
+++ b/app/Enums/SitemapChangeFreq.php
@@ -0,0 +1,70 @@
+ 값 Enum (sitemaps.org 폐쇄 어휘)
+ *
+ * https://www.sitemaps.org/protocol.html 의 는 크롤러에게 페이지 갱신
+ * 빈도를 알려주는 힌트로, 허용 값이 7개로 고정된 폐쇄 어휘다. 이 Enum 이 그 SSoT 이며,
+ * 잘못된 문자열이 사이트맵 XML 에 유입되는 것을 저장(SitemapIndexer)과 렌더
+ * (SitemapXmlRenderer) 두 경계에서 차단한다.
+ *
+ * 기여자(getUrlsLazy)·리스너·정적 URL 은 리터럴 문자열 대신 이 Enum 의 case 를 사용해
+ * 오타를 작성 시점에 잡는다.
+ */
+enum SitemapChangeFreq: string
+{
+ /**
+ * 접근할 때마다 변경 (예: 실시간 시세)
+ */
+ case Always = 'always';
+
+ /**
+ * 시간 단위 변경
+ */
+ case Hourly = 'hourly';
+
+ /**
+ * 일 단위 변경
+ */
+ case Daily = 'daily';
+
+ /**
+ * 주 단위 변경
+ */
+ case Weekly = 'weekly';
+
+ /**
+ * 월 단위 변경
+ */
+ case Monthly = 'monthly';
+
+ /**
+ * 연 단위 변경
+ */
+ case Yearly = 'yearly';
+
+ /**
+ * 사실상 변경 없음 (예: 보관 URL)
+ */
+ case Never = 'never';
+
+ /**
+ * 임의 문자열을 유효한 changefreq 값으로 정규화합니다.
+ *
+ * 대소문자·앞뒤 공백을 흡수하고, 폐쇄 어휘에 없는 값은 null 로 떨어뜨려
+ * 사이트맵 XML 에 비표준 값이 출력되는 것을 방지합니다.
+ *
+ * @param string|null $value 검증할 원본 값
+ * @return string|null 유효하면 정규화된 값, 아니면 null
+ */
+ public static function normalize(?string $value): ?string
+ {
+ if ($value === null || trim($value) === '') {
+ return null;
+ }
+
+ return self::tryFrom(strtolower(trim($value)))?->value;
+ }
+}
diff --git a/app/Enums/SitemapGenerationMode.php b/app/Enums/SitemapGenerationMode.php
new file mode 100644
index 00000000..32384d88
--- /dev/null
+++ b/app/Enums/SitemapGenerationMode.php
@@ -0,0 +1,48 @@
+ self::Full,
+ self::Incremental => self::Incremental,
+ self::Auto => $visibleCount === 0 ? self::Full : self::Incremental,
+ };
+ }
+}
diff --git a/app/Enums/TotalRelation.php b/app/Enums/TotalRelation.php
new file mode 100644
index 00000000..d7212976
--- /dev/null
+++ b/app/Enums/TotalRelation.php
@@ -0,0 +1,60 @@
+
+ */
+ public static function values(): array
+ {
+ return array_column(self::cases(), 'value');
+ }
+
+ /**
+ * 유효한 값인지 확인합니다.
+ *
+ * @param string $value 검증할 값
+ * @return bool 유효 여부
+ */
+ public static function isValid(string $value): bool
+ {
+ return in_array($value, self::values(), true);
+ }
+
+ /**
+ * 총 건수가 정확한지 여부를 반환합니다.
+ *
+ * @return bool 정확하면 true
+ */
+ public function isExact(): bool
+ {
+ return $this === self::Exact;
+ }
+
+ /**
+ * 다국어 라벨을 반환합니다.
+ *
+ * @return string lang 키 해석 결과
+ */
+ public function label(): string
+ {
+ return __('pagination.total_relation.'.$this->value);
+ }
+}
diff --git a/app/Exceptions/Auth/AccountLockedException.php b/app/Exceptions/Auth/AccountLockedException.php
index 71ba0fec..192c7772 100644
--- a/app/Exceptions/Auth/AccountLockedException.php
+++ b/app/Exceptions/Auth/AccountLockedException.php
@@ -12,6 +12,10 @@ use Symfony\Component\HttpKernel\Exception\HttpException;
* HTTP 423 Locked 응답으로 매핑되며, 프론트엔드 토스트는 다국어 키
* `auth.account_locked` 로 잔여 분(`minutes` 플레이스홀더)을 노출합니다.
*
+ * `login_lockout_time = 0`(무한대) 으로 잠긴 계정은 해제 시각이 없으므로
+ * `lockedUntil` / `remainingMinutes` 가 모두 null 입니다. 이 경우 프론트엔드는
+ * 잔여 시간 대신 `auth.account_locked_permanently` 안내를 노출합니다.
+ *
* 컨트롤러는 본 예외를 별도로 catch 하여 ResponseHelper 응답을 만들거나,
* 글로벌 예외 핸들러가 자동으로 423 JSON 응답으로 변환합니다.
*
@@ -20,15 +24,26 @@ use Symfony\Component\HttpKernel\Exception\HttpException;
class AccountLockedException extends HttpException
{
public function __construct(
- public readonly Carbon $lockedUntil,
- public readonly int $remainingMinutes,
+ public readonly ?Carbon $lockedUntil,
+ public readonly ?int $remainingMinutes,
?string $message = null,
) {
parent::__construct(
423,
- $message ?? 'auth.account_locked',
+ $message ?? ($lockedUntil === null ? 'auth.account_locked_permanently' : 'auth.account_locked'),
null,
- ['Retry-After' => max(1, $remainingMinutes * 60)]
+ // 영구 잠금은 재시도 시점을 제시할 수 없으므로 Retry-After 를 붙이지 않는다.
+ $remainingMinutes === null ? [] : ['Retry-After' => max(1, $remainingMinutes * 60)]
);
}
+
+ /**
+ * 영구 잠금 여부를 반환합니다.
+ *
+ * @return bool 해제 시각이 없는 무기한 잠금이면 true
+ */
+ public function isPermanent(): bool
+ {
+ return $this->lockedUntil === null;
+ }
}
diff --git a/app/Exceptions/ScheduleExecutionException.php b/app/Exceptions/ScheduleExecutionException.php
new file mode 100644
index 00000000..4cde5bce
--- /dev/null
+++ b/app/Exceptions/ScheduleExecutionException.php
@@ -0,0 +1,80 @@
+reasonCode = $reasonCode;
+
+ return $exception;
+ }
+
+ /**
+ * 허용되지 않은 쉘 명령
+ *
+ * @return self 생성된 예외
+ */
+ public static function shellNotAllowed(): self
+ {
+ return new self(__('schedule.shell_not_allowed'));
+ }
+
+ /**
+ * 쉘 명령 실행 실패
+ *
+ * @param string $errorOutput 프로세스 표준 에러 출력
+ * @param int $exitCode 프로세스 종료 코드
+ * @return self 생성된 예외
+ */
+ public static function shellCommandFailed(string $errorOutput, int $exitCode): self
+ {
+ return new self($errorOutput !== '' ? $errorOutput : __('schedule.shell_command_failed'), $exitCode);
+ }
+
+ /**
+ * 공개되지 않은(내부망) URL 호출 차단
+ *
+ * @return self 생성된 예외
+ */
+ public static function urlNotPublic(): self
+ {
+ return new self(__('schedule.url_not_public'));
+ }
+
+ /**
+ * HTTP 요청 실패
+ *
+ * @param int $status 응답 상태 코드
+ * @return self 생성된 예외
+ */
+ public static function httpRequestFailed(int $status): self
+ {
+ return new self(__('schedule.http_request_failed', ['status' => $status]), $status);
+ }
+}
diff --git a/app/Extension/AbstractModule.php b/app/Extension/AbstractModule.php
index c0347f53..66fea241 100644
--- a/app/Extension/AbstractModule.php
+++ b/app/Extension/AbstractModule.php
@@ -749,6 +749,38 @@ abstract class AbstractModule implements CacheableExtensionInterface, ModuleInte
return [];
}
+ /**
+ * 성능 계측 프로파일 정의를 반환합니다.
+ *
+ * 이 모듈이 소유한 목록/화면/저장 경로/배치 중 성능을 재고 싶은 대상을 선언합니다.
+ * `g7:bench` 커맨드가 코어 `config/benchmark.php` 선언과 함께 수집합니다
+ * (`App\Benchmark\BenchmarkProfileRegistry`). 계측 대상을 코어 커맨드에 하드코딩하지
+ * 않는 이유는, 확장이 설치·제거되는 설치본마다 실제로 존재하는 대상이 다르기
+ * 때문입니다. 키는 모듈 내부에서만 고유하면 되고, 다른 확장과 겹치면 커맨드가
+ * `{식별자}/{키}` 로 지목합니다.
+ *
+ * `write` 축의 `callback` 은 클로저를 쓸 수 없습니다 — 코어 선언과 스키마를 공유하고
+ * 코어 쪽은 `config:cache` 대상이므로, 형식을 `'Fqcn'`(invokable) 또는
+ * `['Fqcn', 'method']` 로 통일합니다.
+ *
+ * @return array> 프로파일 키 → 정의
+ * [
+ * 'orders' => [
+ * 'type' => 'list', // list | screen | write | batch
+ * 'label' => '주문 목록',
+ * 'table' => 'ecommerce_orders',
+ * 'columns' => ['id', 'order_number', ...],
+ * 'order' => [['ordered_at', 'desc']],
+ * 'filters' => ['order_status' => 'paid'],
+ * 'soft_delete' => true,
+ * ],
+ * ]
+ */
+ public function getBenchmarkProfiles(): array
+ {
+ return [];
+ }
+
/**
* 모듈 설치 시 실행할 시더 클래스 목록 반환
*
diff --git a/app/Extension/AbstractPlugin.php b/app/Extension/AbstractPlugin.php
index 3e811cd6..1d41aa54 100644
--- a/app/Extension/AbstractPlugin.php
+++ b/app/Extension/AbstractPlugin.php
@@ -658,6 +658,37 @@ abstract class AbstractPlugin implements CacheableExtensionInterface, PluginInte
return [];
}
+ /**
+ * 성능 계측 프로파일 정의를 반환합니다.
+ *
+ * 이 플러그인이 소유한 목록/화면/저장 경로/배치 중 성능을 재고 싶은 대상을 선언합니다.
+ * `g7:bench` 커맨드가 코어 `config/benchmark.php` 선언과 함께 수집합니다
+ * (`App\Benchmark\BenchmarkProfileRegistry`). 계측 대상을 코어 커맨드에 하드코딩하지
+ * 않는 이유는, 확장이 설치·제거되는 설치본마다 실제로 존재하는 대상이 다르기
+ * 때문입니다. 키는 플러그인 내부에서만 고유하면 되고, 다른 확장과 겹치면 커맨드가
+ * `{식별자}/{키}` 로 지목합니다.
+ *
+ * `write` 축의 `callback` 은 클로저를 쓸 수 없습니다 — 코어 선언과 스키마를 공유하고
+ * 코어 쪽은 `config:cache` 대상이므로, 형식을 `'Fqcn'`(invokable) 또는
+ * `['Fqcn', 'method']` 로 통일합니다.
+ *
+ * @return array> 프로파일 키 → 정의
+ * [
+ * 'consent_history' => [
+ * 'type' => 'list', // list | screen | write | batch
+ * 'label' => '동의 이력 목록',
+ * 'table' => 'gdpr_user_consent_histories',
+ * 'columns' => ['*'],
+ * 'order' => [['created_at', 'desc']],
+ * 'soft_delete' => false,
+ * ],
+ * ]
+ */
+ public function getBenchmarkProfiles(): array
+ {
+ return [];
+ }
+
/**
* 플러그인 설치 시 실행할 시더 클래스 목록 반환
*
diff --git a/app/Extension/ExtensionManager.php b/app/Extension/ExtensionManager.php
index aa085ff1..8facbd27 100644
--- a/app/Extension/ExtensionManager.php
+++ b/app/Extension/ExtensionManager.php
@@ -106,7 +106,7 @@ class ExtensionManager
* 매핑을 즉시 유효화한다. 기존 매핑에 경로가 추가되거나 새 네임스페이스가
* 등록되며, 동일 매핑은 중복 없이 merge 된다.
*/
- protected function reregisterRuntimeAutoload(): void
+ public function reregisterRuntimeAutoload(): void
{
if (! class_exists(ClassLoader::class, false)) {
return;
@@ -135,6 +135,14 @@ class ExtensionManager
*/
public function generateAutoloadFile(): void
{
+ // 테스트 환경에서는 실 캐시 파일을 재생성하지 않는다.
+ // testing DB 의 활성 확장 구성은 개발 DB 와 다르므로, 어떤 경로로든 실 캐시가
+ // 재생성되면 개발 환경 PSR-4 매핑이 testing 기준으로 교체되어 모든 모듈/플러그인
+ // 라우트가 500 이 된다. 생성 로직 자체를 검증하는 테스트는 경로를 치환해 사용한다.
+ if ($this->writesRealCacheFileDuringTests()) {
+ return;
+ }
+
// 모듈별 오토로드 수집
$moduleAutoloads = $this->collectModuleAutoloads();
@@ -170,6 +178,24 @@ class ExtensionManager
// 즉시 경로를 반환하도록 한다(성능). 클래스 로딩은 여전히 lazy — 사용 시점에만 include.
$srcClassmap = $this->buildSourceClassmap($psr4);
+ // 공집합 산출물로 정상 매핑을 덮어쓰지 않는다.
+ // 이 매핑은 "DB 설치 목록 × 디스크 활성 디렉토리" 교집합이라, DB 쪽만 일시적으로
+ // 비어도(테이블 부재 · 설치 실패로 행 미기록 · 다른 DB 접속) 교집합이 공집합이 된다.
+ // 디스크에 설치 형태의 확장 디렉토리가 남아 있는데 매핑이 0건이면 DB 쪽 조회를
+ // 신뢰할 수 없다는 뜻이므로, 기존 파일을 보존하고 경고만 남긴다.
+ // (정상적인 0건 — 신규 설치 직후 · 마지막 확장 삭제 — 은 디스크도 함께 비어 통과)
+ $extensionDirectories = empty($psr4) ? $this->findInstalledExtensionDirectories() : [];
+
+ if (empty($psr4) && ! empty($extensionDirectories)) {
+ Log::warning('확장 오토로드 매핑이 0건으로 산출되어 기존 캐시를 보존합니다', [
+ 'path' => $this->autoloadFilePath,
+ 'extension_directories' => $extensionDirectories,
+ 'hint' => '확장 테이블(modules/plugins) 조회 결과가 비어 있습니다. DB 연결·마이그레이션 상태를 확인한 뒤 extension:update-autoload 를 다시 실행하세요.',
+ ]);
+
+ return;
+ }
+
// 파일 내용 생성
$content = $this->buildAutoloadFileContent($psr4, $classmap, $files, $vendorAutoloads, $srcClassmap);
@@ -192,6 +218,52 @@ class ExtensionManager
]);
}
+ /**
+ * 현재 호출이 테스트 환경에서 실 캐시 파일을 건드리는지 판정합니다.
+ *
+ * 경로가 치환된(임시 경로) 인스턴스는 생성 로직 검증용이므로 통과시킨다.
+ *
+ * @return bool 테스트 환경에서 실 캐시 파일을 쓰려는 경우 true
+ */
+ protected function writesRealCacheFileDuringTests(): bool
+ {
+ return app()->environment('testing')
+ && $this->autoloadFilePath === base_path('bootstrap/cache/autoload-extensions.php');
+ }
+
+ /**
+ * 디스크에서 설치 형태를 갖춘 확장 디렉토리를 찾습니다.
+ *
+ * `_bundled` / `_pending` 등 내부 디렉토리는 제외하고, composer.json 을 가진
+ * 활성 디렉토리만 센다 (설치된 확장이 남긴 흔적).
+ *
+ * @return array 확장 식별자 목록 (예: `modules/sirsoft-board`)
+ */
+ protected function findInstalledExtensionDirectories(): array
+ {
+ $found = [];
+
+ foreach (['modules' => $this->modulesPath, 'plugins' => $this->pluginsPath] as $type => $basePath) {
+ if (! File::isDirectory($basePath)) {
+ continue;
+ }
+
+ foreach (File::directories($basePath) as $dir) {
+ $name = basename($dir);
+
+ if (str_starts_with($name, '_')) {
+ continue;
+ }
+
+ if (File::exists($dir.'/composer.json')) {
+ $found[] = $type.'/'.$name;
+ }
+ }
+ }
+
+ return $found;
+ }
+
/**
* 오토로드 파일 내용을 생성합니다.
*
@@ -1183,7 +1255,7 @@ PHP;
return $pharPath;
}
- throw new \RuntimeException(__('exceptions.extension.composer_binary_not_found'));
+ throw new \RuntimeException(__('exceptions.vendor.composer_binary_not_found'));
}
/**
diff --git a/app/Extension/HookListenerRegistrar.php b/app/Extension/HookListenerRegistrar.php
index 685e3ef7..280498db 100644
--- a/app/Extension/HookListenerRegistrar.php
+++ b/app/Extension/HookListenerRegistrar.php
@@ -124,15 +124,10 @@ class HookListenerRegistrar
self::addQueuedAction($hookName, $listenerClass, $method, $priority);
}
- Log::info('훅 리스너 등록 완료', [
- 'hook' => $hookName,
- 'listener' => $listenerClass,
- 'method' => $method,
- 'priority' => $priority,
- 'type' => $type,
- 'sync' => $forceSync,
- 'source' => $source,
- ]);
+ // 등록 성공은 로그로 남기지 않는다. 리스너 112개 × 구독 400건이 요청마다 부팅되므로
+ // 한 줄씩만 남겨도 매 요청 400줄이 쌓인다. 기본 설치가 production + LOG_LEVEL 조합상
+ // 이 줄들을 그대로 기록하므로, 정상 동작을 알리는 데 드는 비용이 동작 자체보다 커진다.
+ // 등록 실패는 아래 catch 에서 계속 기록한다.
}
}
diff --git a/app/Extension/HookManager.php b/app/Extension/HookManager.php
index 6af97a4b..9d214950 100644
--- a/app/Extension/HookManager.php
+++ b/app/Extension/HookManager.php
@@ -19,6 +19,13 @@ class HookManager implements HookManagerInterface
private static array $dispatching = [];
+ /**
+ * 구 훅 이름 사용 경고를 이미 남긴 훅 이름 집합 — 요청마다 한 번씩만 경고합니다.
+ *
+ * @var array
+ */
+ private static array $legacyHookNoticeShown = [];
+
/**
* 현재 실행 중인 훅 이름 스택 — 정책 Listener 등 "어느 훅에서 호출되었는지" 알아야 하는
* 단일 핸들러 패턴에 사용됩니다. (내부 전용)
@@ -362,4 +369,43 @@ class HookManager implements HookManagerInterface
return static::applyFilters($hookName, $value, ...$args);
}
+
+ /**
+ * 표준 이름과 구 이름을 함께 발행하는 Filter 실행
+ *
+ * 이름이 표준(`core.{대상}.{동작}_validation_rules`)과 어긋난 채 이미 공개된 훅을 표준 이름으로
+ * 옮길 때 사용합니다. 표준 이름을 먼저 적용하고 그 결과에 구 이름을 다시 적용하므로,
+ * 새로 구독하는 확장과 구 이름을 구독 중인 기존 확장이 함께 동작합니다.
+ *
+ * 구 이름에 실제 구독자가 있을 때만 한 번 경고를 남깁니다 — 개명 사실을 확장 개발자가 알 수 있게
+ * 하되, 구독자가 없는 환경에서 로그를 어지럽히지 않기 위함입니다.
+ *
+ * @param string $hookName 표준 훅 이름
+ * @param string $legacyHookName 구 훅 이름 (하위호환용)
+ * @param mixed $value 필터링할 값
+ * @param mixed ...$args 필터에 전달할 추가 인자
+ * @return mixed 필터링된 값
+ */
+ public static function applyFiltersWithLegacyName(
+ string $hookName,
+ string $legacyHookName,
+ mixed $value = null,
+ ...$args
+ ): mixed {
+ $value = static::applyFilters($hookName, $value, ...$args);
+
+ if (! isset(self::$filters[$legacyHookName])) {
+ return $value;
+ }
+
+ if (! isset(self::$legacyHookNoticeShown[$legacyHookName])) {
+ self::$legacyHookNoticeShown[$legacyHookName] = true;
+ Log::warning('구 훅 이름 사용 중 — 표준 이름으로 옮겨 주세요', [
+ 'legacy' => $legacyHookName,
+ 'standard' => $hookName,
+ ]);
+ }
+
+ return static::applyFilters($legacyHookName, $value, ...$args);
+ }
}
diff --git a/app/Extension/IdentityVerification/IdentityVerificationManager.php b/app/Extension/IdentityVerification/IdentityVerificationManager.php
index 761dd6bc..05836573 100644
--- a/app/Extension/IdentityVerification/IdentityVerificationManager.php
+++ b/app/Extension/IdentityVerification/IdentityVerificationManager.php
@@ -38,9 +38,13 @@ class IdentityVerificationManager
/**
* 코어 기본 purpose 목록.
*
- * `signup` / `password_reset` / `self_update` / `sensitive_action` — 이 4종은
+ * `signup` / `password_reset` / `self_update` / `sensitive_action` / `login` — 이 5종은
* 코어가 계약으로 보장하며 `MailIdentityProvider` 가 모두 지원합니다.
*
+ * `IdentityVerificationPurpose` 에 case 를 추가하면 이 레지스트리에도 반드시 등록해야
+ * 합니다. 등록하지 않으면 `getAllPurposes()` 에서 빠져 관리자가 그 목적의 메시지 템플릿·
+ * 정책을 만들 수 없고, `hasPurpose()` 도 false 가 됩니다.
+ *
* @var array>
*/
protected array $corePurposes = [
@@ -76,6 +80,14 @@ class IdentityVerificationManager
'source_type' => IdentityPolicySourceType::Core->value,
'source_identifier' => 'core',
],
+ IdentityVerificationPurpose::Login->value => [
+ 'label' => 'identity.purposes.login.label',
+ 'description' => 'identity.purposes.login.description',
+ 'default_provider' => null,
+ 'allowed_channels' => [IdentityVerificationChannel::Email->value],
+ 'source_type' => IdentityPolicySourceType::Core->value,
+ 'source_identifier' => 'core',
+ ],
];
/**
@@ -87,7 +99,6 @@ class IdentityVerificationManager
* 프로바이더를 등록합니다.
*
* @param IdentityVerificationInterface $provider IDV 프로바이더 인스턴스
- * @return void
*/
public function register(IdentityVerificationInterface $provider): void
{
@@ -98,7 +109,6 @@ class IdentityVerificationManager
* 프로바이더 등록을 해제합니다.
*
* @param string $id 프로바이더 식별자 (예: g7:core.mail)
- * @return void
*/
public function unregister(string $id): void
{
@@ -249,7 +259,6 @@ class IdentityVerificationManager
* @param array> $purposes key => metadata 매핑
* @param string|null $sourceType 'module' | 'plugin' | 'admin' (미명시 시 'admin' 으로 마킹)
* @param string|null $sourceIdentifier source 식별자 (module/plugin id; 미명시 시 'admin')
- * @return void
*/
public function registerDeclaredPurposes(array $purposes, ?string $sourceType = null, ?string $sourceIdentifier = null): void
{
@@ -284,7 +293,6 @@ class IdentityVerificationManager
* @param array $meta label/description/allowed_channels 등 메타데이터
* @param string|null $sourceType 'module' | 'plugin' | 'admin' (미명시 시 'admin')
* @param string|null $sourceIdentifier source 식별자 (미명시 시 'admin')
- * @return void
*/
public function registerPurpose(string $key, array $meta, ?string $sourceType = null, ?string $sourceIdentifier = null): void
{
diff --git a/app/Extension/IdentityVerification/Providers/MailIdentityProvider.php b/app/Extension/IdentityVerification/Providers/MailIdentityProvider.php
index 968a8d9c..4a4ba975 100644
--- a/app/Extension/IdentityVerification/Providers/MailIdentityProvider.php
+++ b/app/Extension/IdentityVerification/Providers/MailIdentityProvider.php
@@ -29,6 +29,15 @@ use Illuminate\Support\Str;
*/
class MailIdentityProvider implements IdentityVerificationInterface
{
+ /** @var int 인증코드 최소 길이 */
+ public const MIN_CODE_LENGTH = 4;
+
+ /** @var int 인증코드 최대 길이 */
+ public const MAX_CODE_LENGTH = 10;
+
+ /** @var int 인증코드 기본 길이 (경계 위반 시 폴백) */
+ public const DEFAULT_CODE_LENGTH = 6;
+
public const ID = 'g7:core.mail';
/**
@@ -314,7 +323,11 @@ class MailIdentityProvider implements IdentityVerificationInterface
'code_length' => [
'label' => __('identity.providers.mail.settings.code_length'),
'type' => 'integer',
- 'default' => 6,
+ 'default' => self::DEFAULT_CODE_LENGTH,
+ // 경계는 스키마가 선언한다 — 서비스가 자체 상수로 조용히 클램프하면
+ // 관리자가 설정한 값이 화면 안내와 다르게 동작한다.
+ 'min' => self::MIN_CODE_LENGTH,
+ 'max' => self::MAX_CODE_LENGTH,
'help' => __('identity.providers.mail.settings.code_length_help'),
],
'from_address' => [
@@ -345,9 +358,30 @@ class MailIdentityProvider implements IdentityVerificationInterface
return $purpose === 'password_reset' ? 'link' : 'text_code';
}
+ /**
+ * 지정 길이의 숫자 인증코드를 생성합니다.
+ *
+ * 경계를 벗어난 값은 조용히 클램프하지 않습니다 — 클램프는 관리자가 설정한 값과
+ * 실제 동작을 어긋나게 만듭니다. 다만 런타임 인증 흐름을 중단시키는 것은 위험하므로
+ * 예외 대신 경고 로그 + 스키마 기본값 폴백으로 처리합니다.
+ *
+ * @param int $length 요청 코드 길이
+ * @return string 생성된 숫자 코드
+ */
protected function generateNumericCode(int $length): string
{
- $length = max(4, min(10, $length));
+ if ($length < self::MIN_CODE_LENGTH || $length > self::MAX_CODE_LENGTH) {
+ Log::warning('IDV 인증코드 길이가 허용 범위를 벗어나 기본값으로 대체됨', [
+ 'provider_id' => self::ID,
+ 'requested' => $length,
+ 'min' => self::MIN_CODE_LENGTH,
+ 'max' => self::MAX_CODE_LENGTH,
+ 'applied' => self::DEFAULT_CODE_LENGTH,
+ ]);
+
+ $length = self::DEFAULT_CODE_LENGTH;
+ }
+
$code = '';
for ($i = 0; $i < $length; $i++) {
$code .= (string) random_int(0, 9);
diff --git a/app/Extension/ModuleManager.php b/app/Extension/ModuleManager.php
index 5defac44..f3b4ce63 100644
--- a/app/Extension/ModuleManager.php
+++ b/app/Extension/ModuleManager.php
@@ -30,6 +30,7 @@ use App\Extension\Helpers\GithubHelper;
use App\Extension\Helpers\IdentityMessageSyncHelper;
use App\Extension\Helpers\IdentityPolicySyncHelper;
use App\Extension\Helpers\NotificationSyncHelper;
+use App\Extension\Testing\ExtensionTestAllowlist;
use App\Extension\Vendor\Exceptions\VendorInstallException;
use App\Extension\Vendor\VendorInstallContext;
use App\Extension\Vendor\VendorInstallResult;
@@ -41,6 +42,8 @@ use App\Models\Plugin;
use App\Models\Template;
use App\Providers\CoreServiceProvider;
use App\Services\LayoutExtensionService;
+use App\Support\AssetUrl;
+use App\Support\RouteCacheHelper;
use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\Auth;
@@ -515,6 +518,7 @@ class ModuleManager implements ModuleManagerInterface
// 확장 캐시 버전 증가 (프론트엔드가 새로운 캐시로 요청하도록)
$this->incrementExtensionCacheVersion();
+ RouteCacheHelper::rebuild();
// 확장 미들웨어 인덱스 무효화 — 새 모듈의 미들웨어 선언이 즉시 게이트에 반영.
ExtensionMiddlewareRegistry::flush();
@@ -644,6 +648,7 @@ class ModuleManager implements ModuleManagerInterface
// 확장 기능 캐시 버전 증가 (프론트엔드 캐시 무효화)
$this->incrementExtensionCacheVersion();
+ RouteCacheHelper::rebuild();
// 모듈 상태 캐시 무효화
self::invalidateModuleStatusCache();
@@ -786,6 +791,7 @@ class ModuleManager implements ModuleManagerInterface
// 확장 기능 캐시 버전 증가 (프론트엔드 캐시 무효화)
$this->incrementExtensionCacheVersion();
+ RouteCacheHelper::rebuild();
// 모듈 자체 캐시 전체 정리
$this->flushModuleCache($module);
@@ -966,6 +972,7 @@ class ModuleManager implements ModuleManagerInterface
// 확장 기능 캐시 버전 증가 (프론트엔드 캐시 무효화)
$this->incrementExtensionCacheVersion();
+ RouteCacheHelper::rebuild();
// 모듈 자체 캐시 전체 정리
$this->flushModuleCache($module);
@@ -1066,8 +1073,8 @@ class ModuleManager implements ModuleManagerInterface
if (isset($builtPaths['js']) || isset($builtPaths['css'])) {
$assets = [
- 'js' => isset($builtPaths['js']) ? "/api/modules/assets/{$identifier}/".$builtPaths['js'] : null,
- 'css' => isset($builtPaths['css']) ? "/api/modules/assets/{$identifier}/".$builtPaths['css'] : null,
+ 'js' => isset($builtPaths['js']) ? AssetUrl::moduleAsset($identifier, $builtPaths['js']) : null,
+ 'css' => isset($builtPaths['css']) ? AssetUrl::moduleAsset($identifier, $builtPaths['css']) : null,
'priority' => $loadingConfig['priority'] ?? 100,
];
}
@@ -1156,8 +1163,8 @@ class ModuleManager implements ModuleManagerInterface
if (isset($builtPaths['js']) || isset($builtPaths['css'])) {
$assets = [
- 'js' => isset($builtPaths['js']) ? "/api/modules/assets/{$identifier}/".$builtPaths['js'] : null,
- 'css' => isset($builtPaths['css']) ? "/api/modules/assets/{$identifier}/".$builtPaths['css'] : null,
+ 'js' => isset($builtPaths['js']) ? AssetUrl::moduleAsset($identifier, $builtPaths['js']) : null,
+ 'css' => isset($builtPaths['css']) ? AssetUrl::moduleAsset($identifier, $builtPaths['css']) : null,
'priority' => $loadingConfig['priority'] ?? 100,
];
}
@@ -1304,8 +1311,8 @@ class ModuleManager implements ModuleManagerInterface
if (isset($builtPaths['js']) || isset($builtPaths['css'])) {
$assets = [
- 'js' => isset($builtPaths['js']) ? "/api/modules/assets/{$identifier}/".$builtPaths['js'] : null,
- 'css' => isset($builtPaths['css']) ? "/api/modules/assets/{$identifier}/".$builtPaths['css'] : null,
+ 'js' => isset($builtPaths['js']) ? AssetUrl::moduleAsset($identifier, $builtPaths['js']) : null,
+ 'css' => isset($builtPaths['css']) ? AssetUrl::moduleAsset($identifier, $builtPaths['css']) : null,
'priority' => $loadingConfig['priority'] ?? 100,
];
}
@@ -1427,11 +1434,22 @@ class ModuleManager implements ModuleManagerInterface
return null;
}
- try {
- require_once $moduleFile;
+ $namespace = $this->convertDirectoryToNamespace($moduleName);
+ $moduleClass = "Modules\\{$namespace}\\Module";
- $namespace = $this->convertDirectoryToNamespace($moduleName);
- $moduleClass = "Modules\\{$namespace}\\Module";
+ try {
+ // 같은 모듈의 활성 디렉토리 사본이 이미 로드돼 있으면 `_bundled`/`_pending`
+ // 파일을 그대로 require 할 수 없다 — 같은 FQN 을 두 번 선언하게 되어
+ // "Cannot declare class ..., because the name is already in use" 로 죽는다.
+ // 이것은 Error 라 아래 catch(\Exception) 에 걸리지 않아 프로세스가 그대로 종료된다.
+ //
+ // 파일 내용을 임시 클래스명으로 eval 해 번들 쪽 메타데이터를 얻는다
+ // (loadModuleFromDirectory / getFreshModuleInstance 와 동일한 처리).
+ if (class_exists($moduleClass, false)) {
+ return $this->evalFreshModule($moduleFile, $moduleClass, dirname($moduleFile));
+ }
+
+ require_once $moduleFile;
if (class_exists($moduleClass)) {
$module = new $moduleClass;
@@ -1439,7 +1457,7 @@ class ModuleManager implements ModuleManagerInterface
return $module;
}
}
- } catch (\Exception $e) {
+ } catch (\Throwable $e) {
Log::debug("Failed to load bundled module instance for {$moduleName}: ".$e->getMessage());
}
@@ -2981,6 +2999,13 @@ class ModuleManager implements ModuleManagerInterface
return;
}
+ // 테스트 allowlist 확인 — allowlist 밖 모듈은 ServiceProvider 가 등록되지 않으므로
+ // 리스너만 등록하면 훅 발화 시 Repository 바인딩이 없어 컨테이너 해석이 실패한다.
+ // (모듈 등록 행은 테스트 프로세스 간 DB 에 남을 수 있어 활성 판정만으로는 부족하다)
+ if (ExtensionTestAllowlist::isActive() && ! ExtensionTestAllowlist::isAllowed('module', $module->getIdentifier())) {
+ return;
+ }
+
// 모듈 활성화 상태 확인 (비활성화된 모듈의 훅은 등록하지 않음)
$activeIdentifiers = self::getActiveModuleIdentifiers();
if (! in_array($module->getIdentifier(), $activeIdentifiers, true)) {
@@ -3951,9 +3976,11 @@ class ModuleManager implements ModuleManagerInterface
$moduleRecords = $this->moduleRepository->getAllKeyedByIdentifier();
$details = [];
$updatedCount = 0;
+ $checkedCount = 0;
foreach ($moduleRecords as $identifier => $record) {
$result = $this->checkModuleUpdate($identifier);
+ $checkedCount++;
// DB 갱신
$updateData = [
@@ -3977,6 +4004,7 @@ class ModuleManager implements ModuleManagerInterface
$updatedCount++;
$details[] = [
'identifier' => $identifier,
+ 'update_available' => true,
'current_version' => $result['current_version'],
'latest_version' => $result['latest_version'],
'update_source' => $result['update_source'],
@@ -3986,6 +4014,7 @@ class ModuleManager implements ModuleManagerInterface
return [
'updated_count' => $updatedCount,
+ 'checked_count' => $checkedCount,
'details' => $details,
];
}
@@ -4471,7 +4500,11 @@ class ModuleManager implements ModuleManagerInterface
$onProgress?->__invoke('layout', '레이아웃 갱신 중...');
if ($previousStatus === ExtensionStatus::Active->value && $module) {
$preserveModified = ($layoutStrategy === 'keep');
- $this->registerModuleLayouts($identifier);
+ // registerModuleLayouts() 를 여기서 호출하지 않는다 — 그 메서드는 전략을
+ // 모른 채 모든 레이아웃의 content 와 original_content_hash 를 파일 기준으로
+ // 덮어써서, 뒤따르는 refreshModuleLayouts($preserveModified) 가 비교할
+ // "사용자 수정본" 을 이미 지워버린다(= keep 전략이 항상 무효화).
+ // 신규 레이아웃 생성은 refreshModuleLayouts 의 created 분기가 담당한다.
$this->registerLayoutExtensions($module);
$this->refreshModuleLayouts($identifier, $preserveModified);
}
@@ -4484,6 +4517,7 @@ class ModuleManager implements ModuleManagerInterface
$this->clearAllTemplateLanguageCaches();
$this->clearAllTemplateRoutesCaches();
$this->incrementExtensionCacheVersion();
+ RouteCacheHelper::rebuild();
self::invalidateModuleStatusCache();
// 훅 발행: 모듈 업데이트 완료 (Artisan 직접 호출 시에도 리스너 트리거)
@@ -4534,6 +4568,11 @@ class ModuleManager implements ModuleManagerInterface
'updated_at' => now(),
]);
+ // 상태 캐시 무효화 (성공 경로와 동일) — updating 창에서 누군가 활성 목록을 읽었다면
+ // 그 목록에는 이 모듈이 빠져 있다. 여기서 비우지 않으면 상태를 되돌려 놓고도
+ // 캐시 TTL(기본 하루) 동안 이 모듈의 화면이 계속 404 로 남는다.
+ self::invalidateModuleStatusCache();
+
throw new \RuntimeException(
__('modules.errors.update_failed', [
'module' => $identifier,
diff --git a/app/Extension/PluginManager.php b/app/Extension/PluginManager.php
index 197ee9b1..192185ff 100644
--- a/app/Extension/PluginManager.php
+++ b/app/Extension/PluginManager.php
@@ -29,6 +29,7 @@ use App\Extension\Helpers\GithubHelper;
use App\Extension\Helpers\IdentityMessageSyncHelper;
use App\Extension\Helpers\IdentityPolicySyncHelper;
use App\Extension\Helpers\NotificationSyncHelper;
+use App\Extension\Testing\ExtensionTestAllowlist;
use App\Extension\Vendor\Exceptions\VendorInstallException;
use App\Extension\Vendor\VendorInstallContext;
use App\Extension\Vendor\VendorInstallResult;
@@ -41,6 +42,8 @@ use App\Models\Template;
use App\Providers\CoreServiceProvider;
use App\Services\DriverRegistryService;
use App\Services\LayoutExtensionService;
+use App\Support\AssetUrl;
+use App\Support\RouteCacheHelper;
use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\Auth;
@@ -493,6 +496,7 @@ class PluginManager implements PluginManagerInterface
// 확장 캐시 버전 증가 (프론트엔드가 새로운 캐시로 요청하도록)
$this->incrementExtensionCacheVersion();
+ RouteCacheHelper::rebuild();
// 확장 미들웨어 인덱스 무효화 — 새 플러그인의 미들웨어 선언이 즉시 게이트에 반영.
ExtensionMiddlewareRegistry::flush();
@@ -625,6 +629,7 @@ class PluginManager implements PluginManagerInterface
// 확장 기능 캐시 버전 증가 (프론트엔드 캐시 무효화)
$this->incrementExtensionCacheVersion();
+ RouteCacheHelper::rebuild();
// 플러그인 상태 캐시 무효화
self::invalidatePluginStatusCache();
@@ -770,6 +775,7 @@ class PluginManager implements PluginManagerInterface
// 확장 기능 캐시 버전 증가 (프론트엔드 캐시 무효화)
$this->incrementExtensionCacheVersion();
+ RouteCacheHelper::rebuild();
// 플러그인 자체 캐시 전체 정리
$this->flushPluginCache($plugin);
@@ -994,6 +1000,7 @@ class PluginManager implements PluginManagerInterface
// 확장 기능 캐시 버전 증가 (프론트엔드 캐시 무효화)
$this->incrementExtensionCacheVersion();
+ RouteCacheHelper::rebuild();
// 플러그인 자체 캐시 전체 정리
$this->flushPluginCache($plugin);
@@ -1094,8 +1101,8 @@ class PluginManager implements PluginManagerInterface
if (isset($builtPaths['js']) || isset($builtPaths['css'])) {
$assets = [
- 'js' => isset($builtPaths['js']) ? "/api/plugins/assets/{$identifier}/".$builtPaths['js'] : null,
- 'css' => isset($builtPaths['css']) ? "/api/plugins/assets/{$identifier}/".$builtPaths['css'] : null,
+ 'js' => isset($builtPaths['js']) ? AssetUrl::pluginAsset($identifier, $builtPaths['js']) : null,
+ 'css' => isset($builtPaths['css']) ? AssetUrl::pluginAsset($identifier, $builtPaths['css']) : null,
'priority' => $loadingConfig['priority'] ?? 100,
];
}
@@ -1190,8 +1197,8 @@ class PluginManager implements PluginManagerInterface
if (isset($builtPaths['js']) || isset($builtPaths['css'])) {
$assets = [
- 'js' => isset($builtPaths['js']) ? "/api/plugins/assets/{$identifier}/".$builtPaths['js'] : null,
- 'css' => isset($builtPaths['css']) ? "/api/plugins/assets/{$identifier}/".$builtPaths['css'] : null,
+ 'js' => isset($builtPaths['js']) ? AssetUrl::pluginAsset($identifier, $builtPaths['js']) : null,
+ 'css' => isset($builtPaths['css']) ? AssetUrl::pluginAsset($identifier, $builtPaths['css']) : null,
'priority' => $loadingConfig['priority'] ?? 100,
];
}
@@ -1268,8 +1275,8 @@ class PluginManager implements PluginManagerInterface
if (isset($builtPaths['js']) || isset($builtPaths['css'])) {
$assets = [
- 'js' => isset($builtPaths['js']) ? "/api/plugins/assets/{$identifier}/".$builtPaths['js'] : null,
- 'css' => isset($builtPaths['css']) ? "/api/plugins/assets/{$identifier}/".$builtPaths['css'] : null,
+ 'js' => isset($builtPaths['js']) ? AssetUrl::pluginAsset($identifier, $builtPaths['js']) : null,
+ 'css' => isset($builtPaths['css']) ? AssetUrl::pluginAsset($identifier, $builtPaths['css']) : null,
'priority' => $loadingConfig['priority'] ?? 100,
];
}
@@ -1428,11 +1435,21 @@ class PluginManager implements PluginManagerInterface
return null;
}
- try {
- require_once $pluginFile;
+ $namespace = $this->convertDirectoryToNamespace($pluginName);
+ $pluginClass = "Plugins\\{$namespace}\\Plugin";
- $namespace = $this->convertDirectoryToNamespace($pluginName);
- $pluginClass = "Plugins\\{$namespace}\\Plugin";
+ try {
+ // 같은 플러그인의 활성 디렉토리 사본이 이미 로드돼 있으면 `_bundled`/`_pending`
+ // 파일을 그대로 require 할 수 없다 — 같은 FQN 을 두 번 선언하게 되어
+ // "Cannot declare class ..., because the name is already in use" 로 죽는다.
+ // 이것은 Error 라 아래 catch(\Exception) 에 걸리지 않아 프로세스가 그대로 종료된다.
+ //
+ // 파일 내용을 임시 클래스명으로 eval 해 번들 쪽 메타데이터를 얻는다.
+ if (class_exists($pluginClass, false)) {
+ return $this->evalFreshPlugin($pluginFile, $pluginClass, dirname($pluginFile));
+ }
+
+ require_once $pluginFile;
if (class_exists($pluginClass)) {
$plugin = new $pluginClass;
@@ -1440,7 +1457,7 @@ class PluginManager implements PluginManagerInterface
return $plugin;
}
}
- } catch (\Exception $e) {
+ } catch (\Throwable $e) {
Log::debug("Failed to load bundled plugin instance for {$pluginName}: ".$e->getMessage());
}
@@ -2817,6 +2834,13 @@ class PluginManager implements PluginManagerInterface
protected function registerPluginHookListeners(PluginInterface $plugin): void
{
+ // 테스트 allowlist 확인 — allowlist 밖 플러그인은 ServiceProvider 가 등록되지 않으므로
+ // 리스너만 등록하면 훅 발화 시 의존 바인딩이 없어 컨테이너 해석이 실패한다.
+ // (플러그인 등록 행은 테스트 프로세스 간 DB 에 남을 수 있어 활성 판정만으로는 부족하다)
+ if (ExtensionTestAllowlist::isActive() && ! ExtensionTestAllowlist::isAllowed('plugin', $plugin->getIdentifier())) {
+ return;
+ }
+
// 플러그인 활성화 상태 확인 (비활성화된 플러그인의 훅은 등록하지 않음)
$activeIdentifiers = self::getActivePluginIdentifiers();
if (! in_array($plugin->getIdentifier(), $activeIdentifiers, true)) {
@@ -4134,9 +4158,11 @@ class PluginManager implements PluginManagerInterface
$pluginRecords = $this->pluginRepository->getAllKeyedByIdentifier();
$details = [];
$updatedCount = 0;
+ $checkedCount = 0;
foreach ($pluginRecords as $identifier => $record) {
$result = $this->checkPluginUpdate($identifier);
+ $checkedCount++;
// DB 갱신
$updateData = [
@@ -4160,6 +4186,7 @@ class PluginManager implements PluginManagerInterface
$updatedCount++;
$details[] = [
'identifier' => $identifier,
+ 'update_available' => true,
'current_version' => $result['current_version'],
'latest_version' => $result['latest_version'],
'update_source' => $result['update_source'],
@@ -4169,6 +4196,7 @@ class PluginManager implements PluginManagerInterface
return [
'updated_count' => $updatedCount,
+ 'checked_count' => $checkedCount,
'details' => $details,
];
}
@@ -4652,7 +4680,11 @@ class PluginManager implements PluginManagerInterface
$onProgress?->__invoke('layout', '레이아웃 갱신 중...');
if ($previousStatus === ExtensionStatus::Active->value && $plugin) {
$preserveModified = ($layoutStrategy === 'keep');
- $this->registerPluginLayouts($identifier);
+ // registerPluginLayouts() 를 여기서 호출하지 않는다 — 그 메서드는 전략을
+ // 모른 채 모든 레이아웃의 content 와 original_content_hash 를 파일 기준으로
+ // 덮어써서, 뒤따르는 refreshPluginLayouts($preserveModified) 가 비교할
+ // "사용자 수정본" 을 이미 지워버린다(= keep 전략이 항상 무효화).
+ // 신규 레이아웃 생성은 refreshPluginLayouts 의 created 분기가 담당한다.
$this->registerLayoutExtensions($plugin);
$this->refreshPluginLayouts($identifier, $preserveModified);
}
@@ -4665,6 +4697,7 @@ class PluginManager implements PluginManagerInterface
$this->clearAllTemplateLanguageCaches();
$this->clearAllTemplateRoutesCaches();
$this->incrementExtensionCacheVersion();
+ RouteCacheHelper::rebuild();
self::invalidatePluginStatusCache();
// 훅 발행: 플러그인 업데이트 완료 (Artisan 직접 호출 시에도 리스너 트리거)
@@ -4715,6 +4748,11 @@ class PluginManager implements PluginManagerInterface
'updated_at' => now(),
]);
+ // 상태 캐시 무효화 (성공 경로와 동일) — updating 창에서 누군가 활성 목록을 읽었다면
+ // 그 목록에는 이 플러그인이 빠져 있다. 여기서 비우지 않으면 상태를 되돌려 놓고도
+ // 캐시 TTL(기본 하루) 동안 이 플러그인의 화면이 계속 404 로 남는다.
+ self::invalidatePluginStatusCache();
+
throw new \RuntimeException(
__('plugins.errors.update_failed', [
'plugin' => $identifier,
diff --git a/app/Extension/TemplateManager.php b/app/Extension/TemplateManager.php
index 4767727f..15b2a6b2 100644
--- a/app/Extension/TemplateManager.php
+++ b/app/Extension/TemplateManager.php
@@ -2685,9 +2685,11 @@ class TemplateManager implements TemplateManagerInterface
$templateRecords = $this->templateRepository->getAllKeyedByIdentifier();
$details = [];
$updatedCount = 0;
+ $checkedCount = 0;
foreach ($templateRecords as $identifier => $record) {
$result = $this->checkTemplateUpdate($identifier);
+ $checkedCount++;
$updateData = [
'update_available' => $result['update_available'],
@@ -2711,6 +2713,7 @@ class TemplateManager implements TemplateManagerInterface
$updatedCount++;
$details[] = [
'identifier' => $identifier,
+ 'update_available' => true,
'current_version' => $result['current_version'],
'latest_version' => $result['latest_version'],
'update_source' => $result['update_source'],
@@ -2720,6 +2723,7 @@ class TemplateManager implements TemplateManagerInterface
return [
'updated_count' => $updatedCount,
+ 'checked_count' => $checkedCount,
'details' => $details,
];
}
@@ -2806,7 +2810,15 @@ class TemplateManager implements TemplateManagerInterface
];
}
- $allLayouts = $this->layoutRepository->getByTemplateId($record->id);
+ // 템플릿 자신이 소유한 레이아웃만 센다 — getByTemplateId() 는 같은 template_id 에
+ // 등록된 모듈/플러그인 소유 레이아웃까지 반환해서, 남의 확장 수정본이 템플릿
+ // 업데이트 모달에 자기 것으로 집계된다. 실제 갱신 범위(refreshTemplateLayouts)는
+ // source_type='template' + source_identifier=null 뿐이므로 표시와 동작이 어긋난다.
+ $allLayouts = $this->layoutRepository->getByTemplateIdWithFilter(
+ $record->id,
+ 'template',
+ null
+ );
$modifiedLayouts = $allLayouts->filter(function ($layout) {
if (! $layout->original_content_hash) {
return false; // hash 없으면 (레거시 데이터) 미수정 취급
diff --git a/app/Extension/Testing/ExtensionTestAllowlist.php b/app/Extension/Testing/ExtensionTestAllowlist.php
index 7efb9564..f803ca09 100644
--- a/app/Extension/Testing/ExtensionTestAllowlist.php
+++ b/app/Extension/Testing/ExtensionTestAllowlist.php
@@ -2,6 +2,9 @@
namespace App\Extension\Testing;
+use App\Extension\HookListenerRegistrar;
+use App\Extension\HookManager;
+
/**
* 테스트 환경 확장 로딩 allowlist
*
@@ -50,6 +53,8 @@ class ExtensionTestAllowlist
*/
public static function set(array $extensions): void
{
+ $previous = self::signature();
+
self::$plugins = [];
self::$modules = [];
self::$configured = true;
@@ -63,6 +68,27 @@ class ExtensionTestAllowlist
self::$modules[] = basename($extension);
}
}
+
+ if (self::signature() !== $previous) {
+ self::forgetRegisteredHooks();
+ }
+ }
+
+ /**
+ * allowlist 가 바뀌었을 때 남아 있는 훅 등록을 비웁니다.
+ *
+ * `HookManager` 의 훅/필터 맵과 `HookListenerRegistrar` 의 등록 이력은 static 이라
+ * 테스트 클래스가 바뀌어도 프로세스에 그대로 남습니다. 앞 클래스가 허용했던 확장의
+ * 리스너가 남아 있으면, 그 확장을 배선하지 않은 다음 클래스의 앱에서 훅이 발화할 때
+ * `app($listenerClass)` 해석이 실패합니다 (Filter 훅은 동기 실행이라 그대로 500 이 된다).
+ *
+ * 비운 직후 새 앱이 부팅되며 코어·허용 확장 리스너를 다시 등록하므로, 이 초기화는
+ * "이번 allowlist 에 맞는 등록만 남긴다" 는 의미가 됩니다.
+ */
+ private static function forgetRegisteredHooks(): void
+ {
+ HookManager::resetAll();
+ HookListenerRegistrar::clear();
}
/**
@@ -77,6 +103,25 @@ class ExtensionTestAllowlist
self::$configured = false;
}
+ /**
+ * 현재 allowlist 를 비교 가능한 문자열로 반환합니다.
+ *
+ * @return string allowlist 서명 (미설정이면 빈 문자열)
+ */
+ private static function signature(): string
+ {
+ if (! self::$configured) {
+ return '';
+ }
+
+ $modules = self::$modules;
+ $plugins = self::$plugins;
+ sort($modules);
+ sort($plugins);
+
+ return 'm:'.implode(',', $modules).'|p:'.implode(',', $plugins);
+ }
+
/**
* 가드 활성 여부를 반환합니다.
*
diff --git a/app/Extension/Traits/CachesModuleStatus.php b/app/Extension/Traits/CachesModuleStatus.php
index 73a1b88e..dcb3051c 100644
--- a/app/Extension/Traits/CachesModuleStatus.php
+++ b/app/Extension/Traits/CachesModuleStatus.php
@@ -29,16 +29,49 @@ trait CachesModuleStatus
return [];
}
- return self::resolveStatusCache()->remember(
+ return self::rememberNonEmpty(
'ext.modules.active_identifiers',
fn () => Module::where('status', ExtensionStatus::Active->value)
->pluck('identifier')
- ->toArray(),
- (int) g7_core_settings('cache.extension_status_ttl', 86400),
- ['ext.status', 'ext.modules']
+ ->toArray()
);
}
+ /**
+ * 목록 캐시를 조회하되, 빈 결과는 캐시에 남기지 않습니다.
+ *
+ * 확장 상태는 install/activate/update 도중 잠시 active 가 아닌 값으로 바뀐다. 그 창에서
+ * 누가 이 목록을 읽으면 빈 배열이 TTL(기본 하루) 동안 굳어, 작업이 끝난 뒤에도 모든 확장이
+ * 꺼진 것처럼 동작한다 — 관리자 화면이 통째로 404 가 되고 스스로 회복되지 않는다.
+ * 빈 결과는 재계산 비용이 사실상 없는 단순 조회이므로 캐시하지 않는 편이 안전하다.
+ *
+ * @param string $key 캐시 키
+ * @param \Closure $resolver 목록 계산 클로저
+ * @return array 조회된 identifier 배열
+ */
+ private static function rememberNonEmpty(string $key, \Closure $resolver): array
+ {
+ $cache = self::resolveStatusCache();
+ $cached = $cache->get($key);
+
+ if (is_array($cached) && $cached !== []) {
+ return $cached;
+ }
+
+ $fresh = $resolver();
+
+ if ($fresh !== []) {
+ $cache->put(
+ $key,
+ $fresh,
+ (int) g7_core_settings('cache.extension_status_ttl', 86400),
+ ['ext.status', 'ext.modules']
+ );
+ }
+
+ return $fresh;
+ }
+
/**
* 설치된 모듈 (active + inactive) identifier 목록을 조회합니다.
*
@@ -50,14 +83,12 @@ trait CachesModuleStatus
return [];
}
- return self::resolveStatusCache()->remember(
+ return self::rememberNonEmpty(
'ext.modules.installed_identifiers',
fn () => Module::whereIn('status', [
ExtensionStatus::Active->value,
ExtensionStatus::Inactive->value,
- ])->pluck('identifier')->toArray(),
- (int) g7_core_settings('cache.extension_status_ttl', 86400),
- ['ext.status', 'ext.modules']
+ ])->pluck('identifier')->toArray()
);
}
diff --git a/app/Extension/Traits/CachesPluginStatus.php b/app/Extension/Traits/CachesPluginStatus.php
index de1caa82..14ce9b16 100644
--- a/app/Extension/Traits/CachesPluginStatus.php
+++ b/app/Extension/Traits/CachesPluginStatus.php
@@ -29,16 +29,49 @@ trait CachesPluginStatus
return [];
}
- return self::resolvePluginStatusCache()->remember(
+ return self::rememberNonEmptyPluginList(
'ext.plugins.active_identifiers',
fn () => Plugin::where('status', ExtensionStatus::Active->value)
->pluck('identifier')
- ->toArray(),
- (int) g7_core_settings('cache.extension_status_ttl', 86400),
- ['ext.status', 'ext.plugins']
+ ->toArray()
);
}
+ /**
+ * 목록 캐시를 조회하되, 빈 결과는 캐시에 남기지 않습니다.
+ *
+ * 확장 상태는 install/activate/update 도중 잠시 active 가 아닌 값으로 바뀐다. 그 창에서
+ * 누가 이 목록을 읽으면 빈 배열이 TTL(기본 하루) 동안 굳어, 작업이 끝난 뒤에도 모든
+ * 플러그인이 꺼진 것처럼 동작하며 스스로 회복되지 않는다. 빈 결과는 재계산 비용이 사실상
+ * 없는 단순 조회이므로 캐시하지 않는 편이 안전하다.
+ *
+ * @param string $key 캐시 키
+ * @param \Closure $resolver 목록 계산 클로저
+ * @return array 조회된 identifier 배열
+ */
+ private static function rememberNonEmptyPluginList(string $key, \Closure $resolver): array
+ {
+ $cache = self::resolvePluginStatusCache();
+ $cached = $cache->get($key);
+
+ if (is_array($cached) && $cached !== []) {
+ return $cached;
+ }
+
+ $fresh = $resolver();
+
+ if ($fresh !== []) {
+ $cache->put(
+ $key,
+ $fresh,
+ (int) g7_core_settings('cache.extension_status_ttl', 86400),
+ ['ext.status', 'ext.plugins']
+ );
+ }
+
+ return $fresh;
+ }
+
/**
* 설치된 플러그인 (active + inactive) identifier 목록을 조회합니다.
*
@@ -50,14 +83,12 @@ trait CachesPluginStatus
return [];
}
- return self::resolvePluginStatusCache()->remember(
+ return self::rememberNonEmptyPluginList(
'ext.plugins.installed_identifiers',
fn () => Plugin::whereIn('status', [
ExtensionStatus::Active->value,
ExtensionStatus::Inactive->value,
- ])->pluck('identifier')->toArray(),
- (int) g7_core_settings('cache.extension_status_ttl', 86400),
- ['ext.status', 'ext.plugins']
+ ])->pluck('identifier')->toArray()
);
}
diff --git a/app/Extension/Traits/CachesTemplateStatus.php b/app/Extension/Traits/CachesTemplateStatus.php
index 746e06cd..e581ec7b 100644
--- a/app/Extension/Traits/CachesTemplateStatus.php
+++ b/app/Extension/Traits/CachesTemplateStatus.php
@@ -29,13 +29,11 @@ trait CachesTemplateStatus
return [];
}
- return self::resolveTemplateStatusCache()->remember(
+ return self::rememberNonEmptyTemplateList(
'ext.templates.active_identifiers',
fn () => Template::where('status', ExtensionStatus::Active->value)
->pluck('identifier')
- ->toArray(),
- (int) g7_core_settings('cache.extension_status_ttl', 86400),
- ['ext.status', 'ext.templates']
+ ->toArray()
);
}
@@ -51,14 +49,12 @@ trait CachesTemplateStatus
return [];
}
- return self::resolveTemplateStatusCache()->remember(
+ return self::rememberNonEmptyTemplateList(
"ext.templates.active_identifiers_{$type}",
fn () => Template::where('status', ExtensionStatus::Active->value)
->where('type', $type)
->pluck('identifier')
- ->toArray(),
- (int) g7_core_settings('cache.extension_status_ttl', 86400),
- ['ext.status', 'ext.templates']
+ ->toArray()
);
}
@@ -73,17 +69,50 @@ trait CachesTemplateStatus
return [];
}
- return self::resolveTemplateStatusCache()->remember(
+ return self::rememberNonEmptyTemplateList(
'ext.templates.installed_identifiers',
fn () => Template::whereIn('status', [
ExtensionStatus::Active->value,
ExtensionStatus::Inactive->value,
- ])->pluck('identifier')->toArray(),
- (int) g7_core_settings('cache.extension_status_ttl', 86400),
- ['ext.status', 'ext.templates']
+ ])->pluck('identifier')->toArray()
);
}
+ /**
+ * 목록 캐시를 조회하되, 빈 결과는 캐시에 남기지 않습니다.
+ *
+ * 확장 상태는 install/activate/update 도중 잠시 active 가 아닌 값으로 바뀐다. 그 창에서
+ * 누가 이 목록을 읽으면 빈 배열이 TTL(기본 하루) 동안 굳어, 작업이 끝난 뒤에도 모든
+ * 템플릿이 꺼진 것처럼 동작하며 스스로 회복되지 않는다. 빈 결과는 재계산 비용이 사실상
+ * 없는 단순 조회이므로 캐시하지 않는 편이 안전하다.
+ *
+ * @param string $key 캐시 키
+ * @param \Closure $resolver 목록 계산 클로저
+ * @return array 조회된 identifier 배열
+ */
+ private static function rememberNonEmptyTemplateList(string $key, \Closure $resolver): array
+ {
+ $cache = self::resolveTemplateStatusCache();
+ $cached = $cache->get($key);
+
+ if (is_array($cached) && $cached !== []) {
+ return $cached;
+ }
+
+ $fresh = $resolver();
+
+ if ($fresh !== []) {
+ $cache->put(
+ $key,
+ $fresh,
+ (int) g7_core_settings('cache.extension_status_ttl', 86400),
+ ['ext.status', 'ext.templates']
+ );
+ }
+
+ return $fresh;
+ }
+
/**
* 템플릿 상태 캐시를 무효화합니다.
* 템플릿 상태 변경 시 (install, activate, deactivate, uninstall) 호출해야 합니다.
diff --git a/app/Helpers/PermissionHelper.php b/app/Helpers/PermissionHelper.php
index b8c4c32c..de3656c4 100644
--- a/app/Helpers/PermissionHelper.php
+++ b/app/Helpers/PermissionHelper.php
@@ -2,7 +2,6 @@
namespace App\Helpers;
-use App\Enums\ScopeType;
use App\Models\Permission;
use App\Models\User;
use App\Providers\AuthServiceProvider;
@@ -26,6 +25,20 @@ class PermissionHelper
*/
protected static array $permissionCache = [];
+ /**
+ * 권한 스코프 캐시를 무효화합니다.
+ *
+ * 캐시는 프로세스 수명 동안 유지되므로, 권한 행이 다시 만들어지는 시점
+ * (권한 재시드 · 코어 업데이트 · 확장 install) 에 비워 주어야 한다.
+ * 테스트에서는 매 케이스마다 DB 가 초기화되는데 캐시만 남아, 앞 케이스가 심은
+ * `resource_route_key = null` 이 뒤 케이스로 새어 스코프 검사가 통째로 건너뛰어진다
+ * (개별 실행은 통과하고 스위트에서만 어긋나는 형태로 드러난다).
+ */
+ public static function clearPermissionScopeCache(): void
+ {
+ self::$permissionCache = [];
+ }
+
/**
* 단일 권한 체크
*
@@ -104,7 +117,6 @@ class PermissionHelper
* @param Builder $query Eloquent 쿼리 빌더
* @param string $permission 권한 식별자
* @param User|null $user 사용자 (null이면 현재 인증 사용자)
- * @return void
*/
public static function applyPermissionScope(Builder $query, string $permission, ?User $user = null): void
{
diff --git a/app/Helpers/ResponseHelper.php b/app/Helpers/ResponseHelper.php
index f83a3ea6..77283cac 100644
--- a/app/Helpers/ResponseHelper.php
+++ b/app/Helpers/ResponseHelper.php
@@ -21,7 +21,7 @@ class ResponseHelper
/**
* 성공 응답을 생성합니다.
*
- * @param string $messageKey 메시지 키 (기본값: 'messages.success')
+ * @param string $messageKey 메시지 키 (기본값: 'common.success')
* @param mixed $data 응답 데이터
* @param int $statusCode HTTP 상태 코드 (기본값: 200)
* @param array $messageParams 메시지 매개변수
@@ -29,7 +29,7 @@ class ResponseHelper
* @return JsonResponse JSON 응답
*/
public static function success(
- string $messageKey = 'messages.success',
+ string $messageKey = 'common.success',
mixed $data = null,
int $statusCode = 200,
array $messageParams = [],
@@ -45,7 +45,7 @@ class ResponseHelper
/**
* 실패 응답을 생성합니다.
*
- * @param string $messageKey 메시지 키 (기본값: 'messages.failed')
+ * @param string $messageKey 메시지 키 (기본값: 'common.failed')
* @param int $statusCode HTTP 상태 코드 (기본값: 400)
* @param mixed $errors 오류 정보
* @param array $messageParams 메시지 매개변수
@@ -53,7 +53,7 @@ class ResponseHelper
* @return JsonResponse JSON 응답
*/
public static function error(
- string $messageKey = 'messages.failed',
+ string $messageKey = 'common.failed',
int $statusCode = 400,
mixed $errors = null,
array $messageParams = [],
@@ -87,14 +87,14 @@ class ResponseHelper
* 입력 검증 실패 응답을 생성합니다.
*
* @param mixed $errors 검증 오류 정보
- * @param string $messageKey 메시지 키 (기본값: 'messages.validation_failed')
+ * @param string $messageKey 메시지 키 (기본값: 'common.validation_failed')
* @param array $messageParams 메시지 매개변수
* @param string $domain 번역 도메인 (기본값: 'core')
* @return JsonResponse 422 상태 코드를 가진 JSON 응답
*/
public static function validationError(
mixed $errors,
- string $messageKey = 'messages.validation_failed',
+ string $messageKey = 'common.validation_failed',
array $messageParams = [],
string $domain = 'core'
): JsonResponse {
@@ -108,13 +108,13 @@ class ResponseHelper
/**
* 인증 실패 응답을 생성합니다.
*
- * @param string $messageKey 메시지 키 (기본값: 'messages.unauthorized')
+ * @param string $messageKey 메시지 키 (기본값: 'common.unauthorized')
* @param array $messageParams 메시지 매개변수
* @param string $domain 번역 도메인 (기본값: 'core')
* @return JsonResponse 401 상태 코드를 가진 JSON 응답
*/
public static function unauthorized(
- string $messageKey = 'messages.unauthorized',
+ string $messageKey = 'common.unauthorized',
array $messageParams = [],
string $domain = 'core'
): JsonResponse {
@@ -127,13 +127,13 @@ class ResponseHelper
/**
* 권한 부족 응답을 생성합니다.
*
- * @param string $messageKey 멤시지 키 (기본값: 'messages.forbidden')
+ * @param string $messageKey 멤시지 키 (기본값: 'common.forbidden')
* @param array $messageParams 멤시지 매개변수
* @param string $domain 번역 도메인 (기본값: 'core')
* @return JsonResponse 403 상태 코드를 가진 JSON 응답
*/
public static function forbidden(
- string $messageKey = 'messages.forbidden',
+ string $messageKey = 'common.forbidden',
array $messageParams = [],
string $domain = 'core'
): JsonResponse {
@@ -146,13 +146,13 @@ class ResponseHelper
/**
* 리소스를 찾을 수 없음 응답을 생성합니다.
*
- * @param string $messageKey 멤시지 키 (기본값: 'messages.not_found')
+ * @param string $messageKey 멤시지 키 (기본값: 'common.not_found')
* @param array $messageParams 멤시지 매개변수
* @param string $domain 번역 도메인 (기본값: 'core')
* @return JsonResponse 404 상태 코드를 가진 JSON 응답
*/
public static function notFound(
- string $messageKey = 'messages.not_found',
+ string $messageKey = 'common.not_found',
array $messageParams = [],
string $domain = 'core'
): JsonResponse {
@@ -165,14 +165,14 @@ class ResponseHelper
/**
* 서버 내부 오류 응답을 생성합니다.
*
- * @param string $messageKey 멤시지 키 (기본값: 'messages.error_occurred')
+ * @param string $messageKey 멤시지 키 (기본값: 'common.error_occurred')
* @param mixed $error 오류 정보 (디버그 모드에서만 표시)
* @param array $messageParams 멤시지 매개변수
* @param string $domain 번역 도메인 (기본값: 'core')
* @return JsonResponse 500 상태 코드를 가진 JSON 응답
*/
public static function serverError(
- string $messageKey = 'messages.error_occurred',
+ string $messageKey = 'common.error_occurred',
mixed $error = null,
array $messageParams = [],
string $domain = 'core'
@@ -335,7 +335,13 @@ class ResponseHelper
/**
* JSON Resource를 사용한 성공 응답을 생성합니다.
*
- * @param string $messageKey 멤시지 키 (기본값: 'messages.success')
+ * `$resource->additional([...])` 로 실은 부가 데이터는 응답 최상위에 함께 나갑니다.
+ * `JsonResource::resolve()` 는 리소스 본문만 돌려주므로, 그것만 쓰면 호출자가 실은
+ * 부가 데이터가 조용히 사라집니다 — 예를 들어 확장 업데이트 응답의 `search_index`
+ * (색인 누락 안내)가 사라지면 검색이 0건을 돌려주는 사실을 운영자가 알 방법이 없습니다.
+ * `success`/`message`/`data` 키는 부가 데이터로 덮어쓰지 않습니다.
+ *
+ * @param string $messageKey 메시지 키 (기본값: 'common.success')
* @param JsonResource|ResourceCollection|null $resource JSON 리소스
* @param int $statusCode HTTP 상태 코드 (기본값: 200)
* @param array $messageParams 멤시지 매개변수
@@ -343,7 +349,7 @@ class ResponseHelper
* @return JsonResponse JSON 응답
*/
public static function successWithResource(
- string $messageKey = 'messages.success',
+ string $messageKey = 'common.success',
JsonResource|ResourceCollection|null $resource = null,
int $statusCode = 200,
array $messageParams = [],
@@ -351,11 +357,19 @@ class ResponseHelper
): JsonResponse {
$data = $resource ? $resource->resolve() : null;
- return response()->json([
+ $payload = [
'success' => true,
'message' => self::trans($messageKey, $messageParams, $domain),
'data' => $data,
- ], $statusCode, [], self::JSON_ENCODE_OPTIONS);
+ ];
+
+ $additional = $resource instanceof JsonResource ? (array) $resource->additional : [];
+
+ if ($additional !== []) {
+ $payload += array_diff_key($additional, $payload);
+ }
+
+ return response()->json($payload, $statusCode, [], self::JSON_ENCODE_OPTIONS);
}
/**
@@ -401,14 +415,14 @@ class ResponseHelper
/**
* 페이지네이션된 리소스 응답을 생성합니다.
*
- * @param string $messageKey 멤시지 키 (기본값: 'messages.success')
+ * @param string $messageKey 메시지 키 (기본값: 'common.success')
* @param ResourceCollection|null $collection 페이지네이션된 리소스 컬렉션
* @param array $messageParams 멤시지 매개변수
* @param string $domain 번역 도메인 (기본값: 'core')
* @return JsonResponse 페이지네이션 메타 데이터를 포함한 JSON 응답
*/
public static function successWithPagination(
- string $messageKey = 'messages.success',
+ string $messageKey = 'common.success',
?ResourceCollection $collection = null,
array $messageParams = [],
string $domain = 'core'
diff --git a/app/Helpers/TimezoneHelper.php b/app/Helpers/TimezoneHelper.php
index b34a3bfc..7398a140 100644
--- a/app/Helpers/TimezoneHelper.php
+++ b/app/Helpers/TimezoneHelper.php
@@ -198,4 +198,31 @@ class TimezoneHelper
return Carbon::parse($normalized, static::getSiteTimezone())->utc();
}
+
+ /**
+ * 기간 필터의 **종료값**을 사이트 기본 타임존 기준으로 해석하여 UTC Carbon을 반환합니다.
+ *
+ * `` 는 시각 없이 'Y-m-d' 만 보낸다. 이 값을 그대로 datetime 비교에 쓰면
+ * '00:00:00' 으로 해석되어 **종료일 당일이 통째로 빠진다**. 시각이 없는 입력만 그날 끝
+ * (23:59:59)까지 확장하고, 시각이 함께 온 입력은 그 시각 그대로 둔다.
+ *
+ * 예: '2026-03-15' + Asia/Seoul → 2026-03-15 23:59:59 KST → 2026-03-15 14:59:59 UTC
+ * '2026-03-15 09:30' + Asia/Seoul → 2026-03-15 00:30:00 UTC (확장하지 않음)
+ *
+ * @param string|null $dateTimeString Y-m-d 또는 Y-m-d\TH:i / Y-m-d H:i:s 형식
+ * @return Carbon|null UTC Carbon 인스턴스
+ */
+ public static function fromSiteRangeEnd(?string $dateTimeString): ?Carbon
+ {
+ if (! $dateTimeString) {
+ return null;
+ }
+
+ $normalized = trim(str_replace('T', ' ', $dateTimeString));
+ $dateOnly = preg_match('/^\d{4}-\d{2}-\d{2}$/', $normalized) === 1;
+
+ $parsed = Carbon::parse($normalized, static::getSiteTimezone());
+
+ return ($dateOnly ? $parsed->endOfDay() : $parsed)->utc();
+ }
}
diff --git a/app/Http/Controllers/Api/Admin/AdminTemplateAssetController.php b/app/Http/Controllers/Api/Admin/AdminTemplateAssetController.php
index d53ac9a9..05283b03 100644
--- a/app/Http/Controllers/Api/Admin/AdminTemplateAssetController.php
+++ b/app/Http/Controllers/Api/Admin/AdminTemplateAssetController.php
@@ -8,6 +8,7 @@ use App\Extension\Helpers\EditorSpecAssembler;
use App\Http\Controllers\Api\Base\AdminBaseController;
use App\Services\PermissionService;
use App\Services\TemplateService;
+use App\Support\AssetUrl;
use Illuminate\Http\JsonResponse;
use Symfony\Component\HttpFoundation\Response;
@@ -88,17 +89,19 @@ class AdminTemplateAssetController extends AdminBaseController
}
$extensionCacheVersion = (int) app(CacheInterface::class)->get('ext.cache_version', 0);
- $version = $extensionCacheVersion > 0 ? "?v={$extensionCacheVersion}" : '';
+ $version = $extensionCacheVersion > 0 ? $extensionCacheVersion : null;
return $this->success(
__('templates.messages.editor_assets_retrieved'),
[
'identifier' => $identifier,
- 'js' => ["/api/templates/assets/{$identifier}/js/components.iife.js{$version}"],
+ 'js' => [AssetUrl::templateAsset($identifier, 'js/components.iife.js', $version)],
// CSS 는 편집기 전용 엔드포인트로 — 다크 셀렉터를 프리뷰 마커로 치환해 서빙
// 일반 자산 서빙은 원본.
+ // URI 가 `components` 가 아니라 `component-styles` 인 이유: 확장자를 떼면
+ // `editor/components.json` 의 확장자 없는 형태와 충돌한다.
'css' => $cssAvailable
- ? ["/api/admin/templates/{$identifier}/editor/components.css{$version}"]
+ ? [AssetUrl::suffixed("/api/admin/templates/{$identifier}/editor/component-styles", 'css', $version)]
: [],
'manifest_present' => true,
'manifest_source' => $jsSource,
diff --git a/app/Http/Controllers/Api/Admin/AuthController.php b/app/Http/Controllers/Api/Admin/AuthController.php
index 90fbbec6..439f274d 100644
--- a/app/Http/Controllers/Api/Admin/AuthController.php
+++ b/app/Http/Controllers/Api/Admin/AuthController.php
@@ -4,11 +4,11 @@ namespace App\Http\Controllers\Api\Admin;
use App\Exceptions\Auth\AccountLockedException;
use App\Http\Controllers\Api\Base\AdminBaseController;
+use App\Http\Requests\Auth\AuthenticatedRequest;
use App\Http\Requests\Auth\LoginRequest;
use App\Http\Resources\UserResource;
use App\Services\AuthService;
use Illuminate\Http\JsonResponse;
-use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;
class AuthController extends AdminBaseController
@@ -22,7 +22,7 @@ class AuthController extends AdminBaseController
/**
* 관리자를 로그인시킵니다.
*
- * @param LoginRequest $request 로그인 요청 데이터
+ * @param LoginRequest $request 로그인 요청 데이터
* @return JsonResponse 로그인 결과와 관리자 정보, 토큰을 포함한 JSON 응답
*/
public function login(LoginRequest $request): JsonResponse
@@ -36,7 +36,7 @@ class AuthController extends AdminBaseController
$user = $data['user'];
// 관리자 권한 확인
- if (!$user->isAdmin()) {
+ if (! $user->isAdmin()) {
return $this->forbidden('auth.admin_required');
}
@@ -45,10 +45,17 @@ class AuthController extends AdminBaseController
return $this->success('auth.admin_login_success', $data);
} catch (AccountLockedException $e) {
- return $this->error('auth.account_locked', 423, [
- 'locked_until' => $e->lockedUntil->toIso8601String(),
- 'retry_after_seconds' => $e->remainingMinutes * 60,
- ], ['minutes' => $e->remainingMinutes]);
+ // 영구 잠금(무한대 설정)은 해제 시각·잔여 시간이 없다 — null 그대로 노출.
+ return $this->error(
+ $e->isPermanent() ? 'auth.account_locked_permanently' : 'auth.account_locked',
+ 423,
+ [
+ 'locked_until' => $e->lockedUntil?->toIso8601String(),
+ 'retry_after_seconds' => $e->remainingMinutes === null ? null : $e->remainingMinutes * 60,
+ 'permanent' => $e->isPermanent(),
+ ],
+ ['minutes' => $e->remainingMinutes]
+ );
} catch (ValidationException $e) {
return $this->unauthorized('auth.login_failed');
}
@@ -57,10 +64,10 @@ class AuthController extends AdminBaseController
/**
* 관리자를 로그아웃시킵니다.
*
- * @param Request $request HTTP 요청
+ * @param AuthenticatedRequest $request 인증 세션 요청 (본문 입력 없음)
* @return JsonResponse 로그아웃 성공 메시지
*/
- public function logout(Request $request): JsonResponse
+ public function logout(AuthenticatedRequest $request): JsonResponse
{
$this->authService->logout($request->user());
@@ -70,10 +77,10 @@ class AuthController extends AdminBaseController
/**
* 현재 로그인된 관리자의 정보를 반환합니다.
*
- * @param Request $request HTTP 요청
+ * @param AuthenticatedRequest $request 인증 세션 요청 (본문 입력 없음)
* @return JsonResponse 관리자 정보를 포함한 JSON 응답
*/
- public function user(Request $request): JsonResponse
+ public function user(AuthenticatedRequest $request): JsonResponse
{
$user = $request->user();
@@ -89,10 +96,10 @@ class AuthController extends AdminBaseController
/**
* 관리자의 인증 토큰을 갱신합니다.
*
- * @param Request $request HTTP 요청
+ * @param AuthenticatedRequest $request 인증 세션 요청 (본문 입력 없음)
* @return JsonResponse 새로운 토큰과 관리자 정보를 포함한 JSON 응답
*/
- public function refresh(Request $request): JsonResponse
+ public function refresh(AuthenticatedRequest $request): JsonResponse
{
try {
$data = $this->authService->refreshToken($request->user());
@@ -101,6 +108,7 @@ class AuthController extends AdminBaseController
if (isset($data['user'])) {
$data['user'] = new UserResource($data['user']);
}
+
return $this->success('common.success', $data);
} catch (ValidationException $e) {
return $this->unauthorized('auth.unauthenticated');
diff --git a/app/Http/Controllers/Api/Admin/Identity/AdminIdentityLogController.php b/app/Http/Controllers/Api/Admin/Identity/AdminIdentityLogController.php
index 59c00b67..07e2b7ee 100644
--- a/app/Http/Controllers/Api/Admin/Identity/AdminIdentityLogController.php
+++ b/app/Http/Controllers/Api/Admin/Identity/AdminIdentityLogController.php
@@ -2,6 +2,7 @@
namespace App\Http\Controllers\Api\Admin\Identity;
+use App\Enums\PermissionType;
use App\Http\Controllers\Api\Base\AdminBaseController;
use App\Http\Requests\Identity\AdminIdentityLogIndexRequest;
use App\Http\Requests\Identity\AdminIdentityLogPurgeRequest;
@@ -45,7 +46,7 @@ class AdminIdentityLogController extends AdminBaseController
$paginated = $this->logService->search($filters, (int) ($validated['per_page'] ?? 20));
- return $this->success('messages.success', [
+ return $this->success('common.success', [
'data' => IdentityLogResource::collection(collect($paginated->items()))->resolve(),
'pagination' => [
'current_page' => $paginated->currentPage(),
@@ -59,7 +60,7 @@ class AdminIdentityLogController extends AdminBaseController
'abilities' => [
'can_purge' => $request->user()?->hasPermission(
'core.admin.identity.logs.purge',
- \App\Enums\PermissionType::Admin,
+ PermissionType::Admin,
) ?? false,
],
]);
@@ -76,7 +77,7 @@ class AdminIdentityLogController extends AdminBaseController
$days = (int) ($request->validated()['older_than_days'] ?? 180);
$count = $this->logService->purge($days);
- return $this->success('messages.success', [
+ return $this->success('common.success', [
'purged_count' => $count,
'older_than_days' => $days,
]);
diff --git a/app/Http/Controllers/Api/Admin/Identity/AdminIdentityPolicyController.php b/app/Http/Controllers/Api/Admin/Identity/AdminIdentityPolicyController.php
index 277c8886..7df11c8a 100644
--- a/app/Http/Controllers/Api/Admin/Identity/AdminIdentityPolicyController.php
+++ b/app/Http/Controllers/Api/Admin/Identity/AdminIdentityPolicyController.php
@@ -60,7 +60,7 @@ class AdminIdentityPolicyController extends AdminBaseController
$paginated = $this->policyService->search($filters, $perPage);
$collection = (new PolicyCollection($paginated))->toArray($request);
- return $this->success('messages.success', [
+ return $this->success('common.success', [
'data' => $collection['data'],
'abilities' => $collection['abilities'] ?? [],
'meta' => [
@@ -83,7 +83,7 @@ class AdminIdentityPolicyController extends AdminBaseController
$policy = $this->policyService->createAdminPolicy($request->validated());
return $this->success(
- 'messages.created',
+ 'common.created',
(new PolicyResource($policy))->toArray($request),
201,
);
@@ -101,7 +101,7 @@ class AdminIdentityPolicyController extends AdminBaseController
$policy = $this->policyService->findById($id);
if (! $policy) {
- return $this->error('messages.not_found', 404);
+ return $this->error('common.not_found', 404);
}
$validated = $request->validated();
@@ -119,13 +119,13 @@ class AdminIdentityPolicyController extends AdminBaseController
}
if (! $this->policyService->updatePolicy($policy, $validated)) {
- return $this->error('messages.failed', 500);
+ return $this->error('common.failed', 500);
}
$policy->refresh();
return $this->success(
- 'messages.updated',
+ 'common.updated',
(new PolicyResource($policy))->toArray($request),
);
}
@@ -142,16 +142,16 @@ class AdminIdentityPolicyController extends AdminBaseController
$policy = $this->policyService->findById($id);
if (! $policy) {
- return $this->error('messages.not_found', 404);
+ return $this->error('common.not_found', 404);
}
if ($policy->source_type !== IdentityPolicySourceType::Admin) {
- return $this->forbidden('messages.cannot_delete_system_resource');
+ return $this->forbidden('identity.errors.cannot_delete_system_policy');
}
return $this->policyService->deleteAdminPolicy($policy)
- ? $this->success('messages.deleted')
- : $this->error('messages.failed', 500);
+ ? $this->success('common.deleted')
+ : $this->error('common.failed', 500);
}
/**
@@ -170,7 +170,7 @@ class AdminIdentityPolicyController extends AdminBaseController
$policy = $this->policyService->findById($id);
if (! $policy) {
- return $this->error('messages.not_found', 404);
+ return $this->error('common.not_found', 404);
}
if ($policy->source_type === IdentityPolicySourceType::Admin) {
@@ -184,6 +184,6 @@ class AdminIdentityPolicyController extends AdminBaseController
return $this->error('identity.errors.reset_field_failed', 422);
}
- return $this->successWithResource('messages.success', new PolicyResource($policy->fresh()));
+ return $this->successWithResource('common.success', new PolicyResource($policy->fresh()));
}
}
diff --git a/app/Http/Controllers/Api/Admin/Identity/AdminIdentityProviderController.php b/app/Http/Controllers/Api/Admin/Identity/AdminIdentityProviderController.php
index 42fbe090..44ff405d 100644
--- a/app/Http/Controllers/Api/Admin/Identity/AdminIdentityProviderController.php
+++ b/app/Http/Controllers/Api/Admin/Identity/AdminIdentityProviderController.php
@@ -5,9 +5,9 @@ namespace App\Http\Controllers\Api\Admin\Identity;
use App\Extension\HookManager;
use App\Extension\IdentityVerification\IdentityVerificationManager;
use App\Http\Controllers\Api\Base\AdminBaseController;
+use App\Http\Requests\Identity\AdminIdentityProviderIndexRequest;
use App\Http\Resources\Identity\ProviderResource;
use Illuminate\Http\JsonResponse;
-use Illuminate\Http\Request;
/**
* 관리자 — IDV 프로바이더 조회 + 설정 스키마 수집 컨트롤러.
@@ -28,10 +28,10 @@ class AdminIdentityProviderController extends AdminBaseController
/**
* 등록된 프로바이더 목록과 각 프로바이더의 설정 스키마를 반환합니다.
*
- * @param Request $request HTTP 요청
+ * @param AdminIdentityProviderIndexRequest $request 검증된 요청 (파라미터 없음)
* @return JsonResponse 프로바이더 목록 (settings_schema 포함)
*/
- public function index(Request $request): JsonResponse
+ public function index(AdminIdentityProviderIndexRequest $request): JsonResponse
{
$providers = array_values($this->manager->all());
@@ -48,6 +48,6 @@ class AdminIdentityProviderController extends AdminBaseController
return $resource + ['settings_schema' => is_array($schema) ? $schema : []];
}, $providers);
- return $this->success('messages.success', $rows);
+ return $this->success('common.success', $rows);
}
}
diff --git a/app/Http/Controllers/Api/Admin/LayoutController.php b/app/Http/Controllers/Api/Admin/LayoutController.php
index 79b456a0..8ee039cb 100644
--- a/app/Http/Controllers/Api/Admin/LayoutController.php
+++ b/app/Http/Controllers/Api/Admin/LayoutController.php
@@ -4,8 +4,10 @@ namespace App\Http\Controllers\Api\Admin;
use App\Exceptions\ConcurrentModificationException;
use App\Http\Controllers\Api\Base\AdminBaseController;
+use App\Http\Requests\Admin\LayoutVersionListRequest;
use App\Http\Requests\Layout\StoreLayoutPreviewRequest;
use App\Http\Requests\Layout\UpdateLayoutContentRequest;
+use App\Http\Resources\LayoutListResource;
use App\Http\Resources\LayoutResource;
use App\Http\Resources\LayoutVersionResource;
use App\Services\LayoutPreviewService;
@@ -38,15 +40,26 @@ class LayoutController extends AdminBaseController
return $this->notFound('common.not_found');
}
- $layouts = $this->layoutService->getLayoutsByTemplateId($template->id);
+ // 목록은 본문(`content`)을 담지 않는 경량 조회를 쓴다 — 파일 목록 화면은 이름·설명·
+ // 크기·수정일만 표시하고, 편집 대상 본문은 상세 엔드포인트가 따로 제공한다.
+ // 종전에는 목록·상세가 같은 Resource 를 공용해 102개 레이아웃의 본문이 전부 실렸고
+ // (응답 18.30MB 중 content 17.41MB), 디버그 모드에서 렌더러가 메모리 한계를 넘었다.
+ $layouts = $this->layoutService->getLayoutListByTemplateId($template->id);
// 레이아웃 이름 → 라우트 path 매핑 — 코드 편집기가 파일 선택 시 ?route= URL
// 동기화 / 위지윅에서 넘어온 ?route= 로 해당 파일 복원에 사용한다.
$routePathMap = $this->templateService->getLayoutRoutePathMap($templateName);
- $collection = LayoutResource::collection($layouts);
+ // 레이아웃 설명(`meta.description`)은 그 레이아웃을 소유한 템플릿의 사전 키를 쓴다.
+ // 코드 편집 화면은 관리자 템플릿 사전으로 렌더하므로 유저 템플릿 키를 알지 못해,
+ // 해석하지 않고 내보내면 설명 칸에 `$t:user.…` 가 원문으로 노출된다.
+ $translations = $this->resolveTemplateTranslations($templateName);
+
+ $collection = LayoutListResource::collection($layouts);
$collection->collection->transform(
- fn (LayoutResource $resource) => $resource->withRoutePathMap($routePathMap)
+ fn (LayoutListResource $resource) => $resource
+ ->withRoutePathMap($routePathMap)
+ ->withTranslations($translations)
);
return $this->success('common.success', $collection);
@@ -75,7 +88,8 @@ class LayoutController extends AdminBaseController
return $this->success(
'common.success',
- new LayoutResource($layout)
+ (new LayoutResource($layout))
+ ->withTranslations($this->resolveTemplateTranslations($templateName))
);
}
@@ -104,7 +118,8 @@ class LayoutController extends AdminBaseController
return $this->success(
'common.success',
- new LayoutResource($layout)
+ (new LayoutResource($layout))
+ ->withTranslations($this->resolveTemplateTranslations($templateName))
);
} catch (ConcurrentModificationException $e) {
DB::rollBack();
@@ -134,11 +149,12 @@ class LayoutController extends AdminBaseController
/**
* 레이아웃의 모든 버전 목록 조회
*
+ * @param LayoutVersionListRequest $request 버전 목록 조회 요청 (limit)
* @param string $templateName 템플릿 identifier
* @param string $name 레이아웃 이름
* @return JsonResponse 버전 목록 응답
*/
- public function versions(string $templateName, string $name): JsonResponse
+ public function versions(LayoutVersionListRequest $request, string $templateName, string $name): JsonResponse
{
$template = $this->templateService->findByIdentifier($templateName);
@@ -152,12 +168,19 @@ class LayoutController extends AdminBaseController
return $this->notFound('common.not_found');
}
- $versions = $this->layoutService->getLayoutVersions($template->id, $name);
-
- return $this->success(
- 'common.success',
- LayoutVersionResource::collection($versions)
+ $versions = $this->layoutService->getLayoutVersions(
+ $template->id,
+ $name,
+ (int) ($request->validated()['limit'] ?? LayoutVersionListRequest::DEFAULT_LIMIT)
);
+
+ // 목록은 경량 표현만 내려준다 — 분해된 본문은 버전 비교 diff 전용이라 단건 조회가 공급한다.
+ $items = $versions
+ ->map(fn ($version) => (new LayoutVersionResource($version))->toListArray($request))
+ ->values()
+ ->all();
+
+ return $this->success('common.success', $items);
}
/**
@@ -259,4 +282,25 @@ class LayoutController extends AdminBaseController
);
}
}
+
+ /**
+ * 목록 설명 해석에 쓸 소유 템플릿 사전을 로드합니다.
+ *
+ * 활성 로케일 기준이며, 로드에 실패하면 빈 배열을 돌려준다 — 그 경우
+ * {@see LayoutListResource} 가 레이아웃 이름으로 폴백하므로 목록은 계속 그려진다.
+ *
+ * @param string $templateName 템플릿 식별자
+ * @return array 템플릿 프론트엔드 다국어 데이터
+ */
+ private function resolveTemplateTranslations(string $templateName): array
+ {
+ $result = $this->templateService->getLanguageDataWithModules(
+ $templateName,
+ app()->getLocale()
+ );
+
+ return ($result['success'] ?? false) && is_array($result['data'] ?? null)
+ ? $result['data']
+ : [];
+ }
}
diff --git a/app/Http/Controllers/Api/Admin/LayoutExtensionController.php b/app/Http/Controllers/Api/Admin/LayoutExtensionController.php
index 51bdf5fa..2233e296 100644
--- a/app/Http/Controllers/Api/Admin/LayoutExtensionController.php
+++ b/app/Http/Controllers/Api/Admin/LayoutExtensionController.php
@@ -4,6 +4,7 @@ namespace App\Http\Controllers\Api\Admin;
use App\Exceptions\ConcurrentModificationException;
use App\Http\Controllers\Api\Base\AdminBaseController;
+use App\Http\Requests\Admin\LayoutVersionListRequest;
use App\Http\Requests\Layout\StoreLayoutExtensionPreviewRequest;
use App\Http\Requests\Layout\UpdateLayoutExtensionContentRequest;
use App\Http\Resources\LayoutExtensionResource;
@@ -58,7 +59,11 @@ class LayoutExtensionController extends AdminBaseController
$this->layoutExtensionService->getExtensionHostLayouts($extension)
);
}
- $group['extensions'] = LayoutExtensionResource::collection($group['extensions']);
+ // 목록은 경량 표현만 내려준다 — 편집 본문(content)은 단건 조회가 공급한다.
+ $group['extensions'] = collect($group['extensions'])
+ ->map(fn ($extension) => (new LayoutExtensionResource($extension))->toListArray(request()))
+ ->values()
+ ->all();
return $group;
}, $groups);
@@ -156,11 +161,12 @@ class LayoutExtensionController extends AdminBaseController
/**
* 레이아웃 확장의 모든 버전 목록 조회
*
+ * @param LayoutVersionListRequest $request 버전 목록 조회 요청 (limit)
* @param string $templateName 템플릿 identifier
* @param int $extensionId 확장 ID
* @return JsonResponse 버전 목록 응답
*/
- public function versions(string $templateName, int $extensionId): JsonResponse
+ public function versions(LayoutVersionListRequest $request, string $templateName, int $extensionId): JsonResponse
{
$extension = $this->resolveExtension($templateName, $extensionId);
@@ -168,9 +174,18 @@ class LayoutExtensionController extends AdminBaseController
return $this->notFound('common.not_found');
}
- $versions = $this->layoutExtensionService->getExtensionVersions($extensionId);
+ $versions = $this->layoutExtensionService->getExtensionVersions(
+ $extensionId,
+ (int) ($request->validated()['limit'] ?? LayoutVersionListRequest::DEFAULT_LIMIT)
+ );
- return $this->success('common.success', LayoutExtensionVersionResource::collection($versions));
+ // 목록은 경량 표현만 내려준다 — 확장 본문은 버전 비교 diff 전용이라 단건 조회가 공급한다.
+ $items = $versions
+ ->map(fn ($version) => (new LayoutExtensionVersionResource($version))->toListArray($request))
+ ->values()
+ ->all();
+
+ return $this->success('common.success', $items);
}
/**
diff --git a/app/Http/Controllers/Api/Admin/MenuController.php b/app/Http/Controllers/Api/Admin/MenuController.php
index 2ea4e92f..1672b8b0 100644
--- a/app/Http/Controllers/Api/Admin/MenuController.php
+++ b/app/Http/Controllers/Api/Admin/MenuController.php
@@ -29,18 +29,22 @@ class MenuController extends AdminBaseController
parent::__construct();
}
+ /**
+ * 관리용 메뉴 목록을 조회합니다.
+ *
+ * @param MenuListRequest $request 목록 필터·정렬 요청
+ * @return JsonResponse 메뉴 컬렉션을 담은 JSON 응답
+ */
public function index(MenuListRequest $request): JsonResponse
{
try {
$filters = $request->validated();
$user = Auth::user();
- // 필터가 있으면 필터링된 메뉴 조회, 없으면 전체 조회
- if (isset($filters['is_active']) || ! empty($filters['filters'])) {
- $menus = $this->menuService->getFilteredMenusForManagement($filters, $user);
- } else {
- $menus = $this->menuService->getTopLevelMenusForManagement($user);
- }
+ // 필터 유무와 무관하게 같은 경로로 조회한다. 예전에는 필터가 없으면 filters 를
+ // 받지 않는 메서드로 분기했는데, 그 경로는 sort_by/sort_order 를 통째로 버려
+ // "필터를 하나라도 걸어야 정렬이 먹는" 상태가 됐다 (#492 D-22).
+ $menus = $this->menuService->getFilteredMenusForManagement($filters, $user);
return $this->successWithResource(
'menu.fetch_success',
diff --git a/app/Http/Controllers/Api/Admin/ModuleController.php b/app/Http/Controllers/Api/Admin/ModuleController.php
index 7cf5d4ac..74ffb478 100644
--- a/app/Http/Controllers/Api/Admin/ModuleController.php
+++ b/app/Http/Controllers/Api/Admin/ModuleController.php
@@ -3,9 +3,12 @@
namespace App\Http\Controllers\Api\Admin;
use App\Enums\LanguagePackScope;
+use App\Extension\Vendor\VendorMode;
use App\Http\Controllers\Api\Base\AdminBaseController;
use App\Http\Controllers\Concerns\InjectsExtensionLanguagePacks;
use App\Http\Controllers\Concerns\OrchestratesCascadeInstall;
+use App\Http\Controllers\Concerns\RebuildsSearchIndexOnDemand;
+use App\Http\Requests\Extension\ChangelogRequest;
use App\Http\Requests\Module\ActivateModuleRequest;
use App\Http\Requests\Module\DeactivateModuleRequest;
use App\Http\Requests\Module\IndexModuleRequest;
@@ -16,10 +19,10 @@ use App\Http\Requests\Module\PerformModuleUpdateRequest;
use App\Http\Requests\Module\PreviewModuleManifestRequest;
use App\Http\Requests\Module\RefreshModuleLayoutsRequest;
use App\Http\Requests\Module\UninstallModuleRequest;
-use App\Http\Requests\Extension\ChangelogRequest;
use App\Http\Resources\ModuleCollection;
use App\Http\Resources\ModuleResource;
use App\Services\Extension\ExtensionInstallPreviewBuilder;
+use App\Services\LanguagePack\LanguagePackBundledRegistrar;
use App\Services\LicenseService;
use App\Services\ModuleService;
use App\Services\TemplateService;
@@ -36,6 +39,7 @@ class ModuleController extends AdminBaseController
{
use InjectsExtensionLanguagePacks;
use OrchestratesCascadeInstall;
+ use RebuildsSearchIndexOnDemand;
public function __construct(
private ModuleService $moduleService,
@@ -169,7 +173,7 @@ class ModuleController extends AdminBaseController
public function installPreview(string $moduleName, ExtensionInstallPreviewBuilder $builder): JsonResponse
{
try {
- $preview = $builder->build(\App\Enums\LanguagePackScope::Module, $moduleName);
+ $preview = $builder->build(LanguagePackScope::Module, $moduleName);
return $this->success('module.fetch_success', $preview);
} catch (\Exception $e) {
@@ -188,7 +192,7 @@ class ModuleController extends AdminBaseController
try {
$validated = $request->validated();
$moduleName = $validated['module_name'];
- $vendorMode = \App\Extension\Vendor\VendorMode::fromStringOrAuto(
+ $vendorMode = VendorMode::fromStringOrAuto(
$validated['vendor_mode'] ?? null
);
@@ -253,7 +257,7 @@ class ModuleController extends AdminBaseController
$moduleInfo = $result['module_info'] ?? null;
// 요구사항 #7: 재활성화 시 cascade 비활성화됐던 언어팩 목록 응답에 포함 (요구사항 #8: 빈 배열이면 모달 표시 안 함)
- $pendingLanguagePacks = app(\App\Services\LanguagePack\LanguagePackBundledRegistrar::class)
+ $pendingLanguagePacks = app(LanguagePackBundledRegistrar::class)
->getPendingForReactivation('module', $moduleName);
if ($moduleInfo) {
@@ -490,6 +494,13 @@ class ModuleController extends AdminBaseController
public function checkModifiedLayouts(string $moduleName): JsonResponse
{
try {
+ // 미존재 식별자는 404 로 구분한다. 존재 확인 없이 조회하면 레이아웃 0건과
+ // 모듈 부재가 똑같이 "수정된 레이아웃 없음" 으로 보고되어, 오타·제거된 모듈이
+ // 조용히 "수정 없음" 으로 통과한다 (show/uninstall-info 와 동일 규약).
+ if (! $this->moduleService->getModuleInfo($moduleName)) {
+ return $this->error('module.not_found', 404, null, ['module' => $moduleName]);
+ }
+
$result = $this->moduleService->checkModifiedLayouts($moduleName);
return $this->success('modules.check_modified_layouts_success', $result);
@@ -515,23 +526,43 @@ class ModuleController extends AdminBaseController
{
try {
$validated = $request->validated();
- $vendorMode = \App\Extension\Vendor\VendorMode::fromStringOrAuto(
+ $vendorMode = VendorMode::fromStringOrAuto(
$validated['vendor_mode'] ?? null
);
$layoutStrategy = $validated['layout_strategy'] ?? 'overwrite';
$force = (bool) ($validated['force'] ?? false);
$result = $this->moduleService->updateModule($moduleName, $vendorMode, $layoutStrategy, $force);
+ // 검색 인덱스 재생성은 운영자가 체크했을 때만 수행한다 — 인덱스 잠금·재색인 비용이
+ // 있어 운영 중인 사이트에서 업데이트만으로 발생해서는 안 된다.
+ $searchIndex = $this->rebuildSearchIndexIfRequested(
+ (bool) ($validated['rebuild_search_index'] ?? false)
+ );
+
$moduleInfo = $result['module_info'] ?? null;
+ // 메시지 치환 파라미터를 반드시 전달한다 — 누락 시 ":module"/":version"
+ // 플레이스홀더가 그대로 사용자에게 노출된다.
+ $messageParams = [
+ 'module' => $moduleName,
+ 'version' => (string) ($result['to_version'] ?? data_get($moduleInfo, 'version') ?? ''),
+ ];
+
if ($moduleInfo) {
return $this->successWithResource(
'modules.update_success',
- new ModuleResource($moduleInfo)
+ (new ModuleResource($moduleInfo))->additional(['search_index' => $searchIndex]),
+ 200,
+ $messageParams
);
}
- return $this->success('modules.update_success', $result);
+ return $this->success(
+ 'modules.update_success',
+ $result + ['search_index' => $searchIndex],
+ 200,
+ $messageParams
+ );
} catch (ValidationException $e) {
// Service/Manager에서 이미 번역된 메시지를 errors에 포함하므로
// 첫 번째 에러를 top-level message로 직접 사용 (이중 래핑 방지)
@@ -601,7 +632,7 @@ class ModuleController extends AdminBaseController
/**
* 모듈의 라이선스 파일 내용을 반환합니다.
*
- * @param string $identifier 모듈 식별자
+ * @param string $identifier 모듈 식별자
* @return JsonResponse
*/
public function license(string $identifier): JsonResponse
diff --git a/app/Http/Controllers/Api/Admin/PluginController.php b/app/Http/Controllers/Api/Admin/PluginController.php
index c9dbd370..0fcc883e 100644
--- a/app/Http/Controllers/Api/Admin/PluginController.php
+++ b/app/Http/Controllers/Api/Admin/PluginController.php
@@ -3,24 +3,27 @@
namespace App\Http\Controllers\Api\Admin;
use App\Enums\LanguagePackScope;
+use App\Extension\Vendor\VendorMode;
use App\Helpers\PermissionHelper;
use App\Http\Controllers\Api\Base\AdminBaseController;
use App\Http\Controllers\Concerns\InjectsExtensionLanguagePacks;
use App\Http\Controllers\Concerns\OrchestratesCascadeInstall;
+use App\Http\Controllers\Concerns\RebuildsSearchIndexOnDemand;
+use App\Http\Requests\Extension\ChangelogRequest;
use App\Http\Requests\Plugin\ActivatePluginRequest;
use App\Http\Requests\Plugin\DeactivatePluginRequest;
use App\Http\Requests\Plugin\IndexPluginRequest;
use App\Http\Requests\Plugin\InstallPluginFromFileRequest;
-use App\Http\Requests\Plugin\PreviewPluginManifestRequest;
use App\Http\Requests\Plugin\InstallPluginFromGithubRequest;
use App\Http\Requests\Plugin\InstallPluginRequest;
use App\Http\Requests\Plugin\PerformPluginUpdateRequest;
+use App\Http\Requests\Plugin\PreviewPluginManifestRequest;
use App\Http\Requests\Plugin\RefreshPluginLayoutsRequest;
use App\Http\Requests\Plugin\UninstallPluginRequest;
-use App\Http\Requests\Extension\ChangelogRequest;
use App\Http\Resources\PluginCollection;
use App\Http\Resources\PluginResource;
use App\Services\Extension\ExtensionInstallPreviewBuilder;
+use App\Services\LanguagePack\LanguagePackBundledRegistrar;
use App\Services\LicenseService;
use App\Services\PluginService;
use App\Services\TemplateService;
@@ -37,6 +40,7 @@ class PluginController extends AdminBaseController
{
use InjectsExtensionLanguagePacks;
use OrchestratesCascadeInstall;
+ use RebuildsSearchIndexOnDemand;
public function __construct(
private PluginService $pluginService,
@@ -177,7 +181,7 @@ class PluginController extends AdminBaseController
try {
$validated = $request->validated();
$pluginName = $validated['plugin_name'];
- $vendorMode = \App\Extension\Vendor\VendorMode::fromStringOrAuto(
+ $vendorMode = VendorMode::fromStringOrAuto(
$validated['vendor_mode'] ?? null
);
@@ -242,7 +246,7 @@ class PluginController extends AdminBaseController
$pluginInfo = $result['plugin_info'] ?? null;
// 요구사항 #7: 재활성화 시 cascade 비활성화됐던 언어팩 목록 응답에 포함
- $pendingLanguagePacks = app(\App\Services\LanguagePack\LanguagePackBundledRegistrar::class)
+ $pendingLanguagePacks = app(LanguagePackBundledRegistrar::class)
->getPendingForReactivation('plugin', $pluginName);
if ($pluginInfo) {
@@ -498,6 +502,12 @@ class PluginController extends AdminBaseController
public function checkModifiedLayouts(string $pluginName): JsonResponse
{
try {
+ // 미존재 식별자는 404 로 구분한다. 존재 확인 없이 조회하면 레이아웃 0건과
+ // 플러그인 부재가 똑같이 "수정된 레이아웃 없음" 으로 보고된다.
+ if (! $this->pluginService->getPluginInfo($pluginName)) {
+ return $this->error('plugins.not_found', 404, null, ['plugin' => $pluginName]);
+ }
+
$result = $this->pluginService->checkModifiedLayouts($pluginName);
return $this->success('plugins.check_modified_layouts_success', $result);
@@ -523,23 +533,42 @@ class PluginController extends AdminBaseController
{
try {
$validated = $request->validated();
- $vendorMode = \App\Extension\Vendor\VendorMode::fromStringOrAuto(
+ $vendorMode = VendorMode::fromStringOrAuto(
$validated['vendor_mode'] ?? null
);
$layoutStrategy = $validated['layout_strategy'] ?? 'overwrite';
$force = (bool) ($validated['force'] ?? false);
$result = $this->pluginService->updatePlugin($pluginName, $vendorMode, $layoutStrategy, $force);
+ // 검색 인덱스 재생성은 운영자가 체크했을 때만 수행한다 — 인덱스 잠금·재색인 비용이
+ // 있어 운영 중인 사이트에서 업데이트만으로 발생해서는 안 된다.
+ $searchIndex = $this->rebuildSearchIndexIfRequested(
+ (bool) ($validated['rebuild_search_index'] ?? false)
+ );
+
$pluginInfo = $result['plugin_info'] ?? null;
+ // 성공 메시지는 ":plugin"/":version" 치환자를 쓰므로 값을 함께 넘긴다
+ $messageParams = [
+ 'plugin' => $pluginName,
+ 'version' => (string) ($result['to_version'] ?? data_get($pluginInfo, 'version') ?? ''),
+ ];
+
if ($pluginInfo) {
return $this->successWithResource(
'plugins.update_success',
- new PluginResource($pluginInfo)
+ (new PluginResource($pluginInfo))->additional(['search_index' => $searchIndex]),
+ 200,
+ $messageParams
);
}
- return $this->success('plugins.update_success', $result);
+ return $this->success(
+ 'plugins.update_success',
+ $result + ['search_index' => $searchIndex],
+ 200,
+ $messageParams
+ );
} catch (ValidationException $e) {
// Service/Manager에서 이미 번역된 메시지를 errors에 포함하므로
// 첫 번째 에러를 top-level message로 직접 사용 (이중 래핑 방지)
@@ -623,7 +652,7 @@ class PluginController extends AdminBaseController
/**
* 플러그인의 라이선스 파일 내용을 반환합니다.
*
- * @param string $identifier 플러그인 식별자
+ * @param string $identifier 플러그인 식별자
* @return JsonResponse
*/
public function license(string $identifier): JsonResponse
diff --git a/app/Http/Controllers/Api/Admin/PluginSettingsController.php b/app/Http/Controllers/Api/Admin/PluginSettingsController.php
index 7ab28df7..192a5335 100644
--- a/app/Http/Controllers/Api/Admin/PluginSettingsController.php
+++ b/app/Http/Controllers/Api/Admin/PluginSettingsController.php
@@ -2,9 +2,11 @@
namespace App\Http\Controllers\Api\Admin;
+use App\Extension\PluginManager;
use App\Http\Controllers\Api\Base\AdminBaseController;
use App\Http\Requests\Admin\UpdatePluginSettingsRequest;
use App\Services\PluginSettingsService;
+use App\Support\SensitiveSettingMask;
use Illuminate\Http\JsonResponse;
/**
@@ -18,13 +20,35 @@ class PluginSettingsController extends AdminBaseController
* PluginSettingsController 생성자
*
* @param PluginSettingsService $pluginSettingsService 플러그인 설정 서비스
+ * @param PluginManager $pluginManager 설정 스키마(sensitive 플래그) 조회용
*/
public function __construct(
- private PluginSettingsService $pluginSettingsService
+ private PluginSettingsService $pluginSettingsService,
+ private PluginManager $pluginManager
) {
parent::__construct();
}
+ /**
+ * 응답에 실을 설정에서 민감값을 마스크로 치환한다.
+ *
+ * 이 응답은 관리자 화면으로 나가므로 암호화 키·시크릿의 평문이 브라우저·개발자 도구·프록시
+ * 로그에 남지 않아야 한다. 값이 저장되어 있다는 사실만 마스크로 알린다. 운영자가 값을 건드리지
+ * 않으면 화면이 마스크를 그대로 되돌려 보내고, 저장 단계가 그것을 걸러 기존 값을 보존한다.
+ *
+ * @param string $identifier 플러그인 식별자
+ * @param array $settings 복호화된 설정
+ * @return array 마스킹된 설정
+ */
+ private function maskSensitive(string $identifier, array $settings): array
+ {
+ $plugin = $this->pluginManager->getPlugin($identifier);
+
+ return $plugin === null
+ ? $settings
+ : SensitiveSettingMask::apply($settings, $plugin->getSettingsSchema());
+ }
+
/**
* 플러그인 설정을 조회합니다.
*
@@ -39,7 +63,7 @@ class PluginSettingsController extends AdminBaseController
return $this->notFound('plugins.not_found');
}
- return $this->success('messages.success', $settings);
+ return $this->success('common.success', $this->maskSensitive($identifier, $settings));
}
/**
@@ -51,12 +75,11 @@ class PluginSettingsController extends AdminBaseController
*/
public function update(UpdatePluginSettingsRequest $request, string $identifier): JsonResponse
{
- // validated()가 빈 배열이면 all()에서 설정값을 가져옴
- // (PluginManager에 등록되지 않은 플러그인의 경우)
+ // 검증을 통과한 필드만 저장한다. 과거에는 validated() 가 비면 all() 로 폴백했으나,
+ // 그 명분이던 "PluginManager 미등록 플러그인" 은 PluginSettingsService::save() 가
+ // 이미 false 로 차단하므로 도달할 수 없었고, 실제로는 설정 스키마 밖의 키가
+ // 그대로 설정 파일에 병합되는 경로로만 동작했다 (mass-assignment).
$settings = $request->validated();
- if (empty($settings)) {
- $settings = $request->all();
- }
$result = $this->pluginSettingsService->save($identifier, $settings);
@@ -66,7 +89,7 @@ class PluginSettingsController extends AdminBaseController
return $this->success(
'plugins.settings.updated',
- $this->pluginSettingsService->get($identifier)
+ $this->maskSensitive($identifier, $this->pluginSettingsService->get($identifier) ?? [])
);
}
@@ -86,6 +109,6 @@ class PluginSettingsController extends AdminBaseController
return $this->notFound('plugins.not_found');
}
- return $this->success('messages.success', $layout);
+ return $this->success('common.success', $layout);
}
}
diff --git a/app/Http/Controllers/Api/Admin/SeoCacheController.php b/app/Http/Controllers/Api/Admin/SeoCacheController.php
index c449ab55..c0ebee0c 100644
--- a/app/Http/Controllers/Api/Admin/SeoCacheController.php
+++ b/app/Http/Controllers/Api/Admin/SeoCacheController.php
@@ -2,13 +2,17 @@
namespace App\Http\Controllers\Api\Admin;
+use App\Enums\SitemapGenerationMode;
use App\Http\Controllers\Api\Base\AdminBaseController;
use App\Http\Requests\Admin\SeoCacheClearRequest;
+use App\Jobs\GenerateSitemapJob;
use App\Seo\Contracts\SeoCacheManagerInterface;
use App\Seo\SeoCacheStatsService;
use App\Seo\SitemapManager;
+use App\Seo\SitemapProgress;
use Carbon\Carbon;
use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\Auth;
/**
* SEO 캐시 관리 컨트롤러
@@ -20,7 +24,8 @@ class SeoCacheController extends AdminBaseController
public function __construct(
private SeoCacheStatsService $statsService,
private SeoCacheManagerInterface $cacheManager,
- private SitemapManager $sitemapManager
+ private SitemapManager $sitemapManager,
+ private SitemapProgress $sitemapProgress
) {
parent::__construct();
}
@@ -43,9 +48,9 @@ class SeoCacheController extends AdminBaseController
'by_module' => $this->statsService->getStatsByModule($since),
];
- return $this->success('messages.success', $data);
+ return $this->success('common.success', $data);
} catch (\Exception $e) {
- return $this->error('messages.error_occurred', 500, $e->getMessage());
+ return $this->error('common.error_occurred', 500, $e->getMessage());
}
}
@@ -54,7 +59,7 @@ class SeoCacheController extends AdminBaseController
*
* 레이아웃 또는 모듈 지정 시 해당 캐시만, 미지정 시 전체 캐시를 삭제합니다.
*
- * @param SeoCacheClearRequest $request 캐시 삭제 요청
+ * @param SeoCacheClearRequest $request 캐시 삭제 요청
* @return JsonResponse 삭제 결과를 포함한 JSON 응답
*/
public function clearCache(SeoCacheClearRequest $request): JsonResponse
@@ -65,14 +70,14 @@ class SeoCacheController extends AdminBaseController
if ($layout) {
$count = $this->cacheManager->invalidateByLayout($layout);
- return $this->success('messages.success', ['cleared' => $count]);
+ return $this->success('common.success', ['cleared' => $count]);
}
$this->cacheManager->clearAll();
- return $this->success('messages.success', ['cleared' => 'all']);
+ return $this->success('common.success', ['cleared' => 'all']);
} catch (\Exception $e) {
- return $this->error('messages.error_occurred', 500, $e->getMessage());
+ return $this->error('common.error_occurred', 500, $e->getMessage());
}
}
@@ -87,38 +92,49 @@ class SeoCacheController extends AdminBaseController
{
try {
// Phase 5의 SeoDeclarationCollector 구현 후 실제 워밍업 로직 추가 예정
- return $this->success('messages.success', [
+ return $this->success('common.success', [
'status' => 'dispatched',
'message' => __('seo.warmup_dispatched'),
]);
} catch (\Exception $e) {
- return $this->error('messages.error_occurred', 500, $e->getMessage());
+ return $this->error('common.error_occurred', 500, $e->getMessage());
}
}
/**
- * Sitemap XML 을 즉시 재생성합니다.
+ * Sitemap XML 재생성을 큐에 예약합니다.
*
- * 큐 드라이버와 무관하게 동기 실행되며, 생성 완료 후 last_updated_at 을 갱신합니다.
+ * 대용량(수백만 URL) 사이트에서 요청 스레드 동기 생성은 메모리/타임아웃 붕괴를 일으키므로
+ * 큐 잡으로 위임합니다. 응답은 예약 시점의 상태이며, 실제 완료 시각은 이후 갱신됩니다.
*
- * @return JsonResponse 재생성 결과 JSON 응답
+ * @return JsonResponse 예약 결과 JSON 응답
*/
public function regenerateSitemap(): JsonResponse
{
- $result = $this->sitemapManager->regenerate();
-
- if ($result['success']) {
- return $this->success('seo.sitemap_regenerated', $result['data'] ?? null);
+ if (! (bool) g7_core_settings('seo.sitemap_enabled', true)) {
+ return $this->error('seo.sitemap_disabled', 400);
}
- $messageKey = match ($result['status']) {
- 'disabled' => 'seo.sitemap_disabled',
- default => 'seo.sitemap_regenerate_failed',
- };
+ // 관리자 수동 재생성은 항상 전체(Full) — 현 생성 상태와 무관하게 전량 재생성 (D7)
+ // 실행한 관리자 ID 를 함께 실어, 완료/실패 시 그 관리자에게만 알림이 발송되게 한다.
+ GenerateSitemapJob::dispatch(SitemapGenerationMode::Full, Auth::id());
- $statusCode = $result['status'] === 'disabled' ? 400 : 500;
+ // 큐 대기 중에도 UI 가 'queued' 를 표시하도록 즉시 기록
+ $this->sitemapProgress->start(SitemapGenerationMode::Full->value);
- return $this->error($messageKey, $statusCode, $result['message'] ?? null);
+ return $this->success('seo.sitemap_regenerate_dispatched', $this->sitemapManager->getStatus());
+ }
+
+ /**
+ * Sitemap 재생성 진행상황과 실시간 연결 가능 여부를 조회합니다.
+ *
+ * SEO 탭 진입 시 초기 로드용이며, 폴링(Reverb OFF)일 때 주기적으로 재조회됩니다.
+ *
+ * @return JsonResponse 진행상황(progress) + last_updated_at + realtime_enabled 를 포함한 JSON 응답
+ */
+ public function sitemapStatus(): JsonResponse
+ {
+ return $this->success('messages.success', $this->sitemapManager->getStatus());
}
/**
@@ -133,9 +149,9 @@ class SeoCacheController extends AdminBaseController
try {
$urls = $this->cacheManager->getCachedUrls();
- return $this->success('messages.success', ['urls' => $urls, 'count' => count($urls)]);
+ return $this->success('common.success', ['urls' => $urls, 'count' => count($urls)]);
} catch (\Exception $e) {
- return $this->error('messages.error_occurred', 500, $e->getMessage());
+ return $this->error('common.error_occurred', 500, $e->getMessage());
}
}
}
diff --git a/app/Http/Controllers/Api/Admin/SettingsController.php b/app/Http/Controllers/Api/Admin/SettingsController.php
index f3f3fc9e..c3e6d14f 100644
--- a/app/Http/Controllers/Api/Admin/SettingsController.php
+++ b/app/Http/Controllers/Api/Admin/SettingsController.php
@@ -42,6 +42,7 @@ class SettingsController extends AdminBaseController
try {
$settings = $this->settingsService->getAllSettings();
$settings['available_drivers'] = $this->driverRegistryService->getAllAvailableDrivers();
+ $settings['_meta'] = ['limits' => config('core.settings_limits', [])];
return $this->success('settings.fetch_success',
(new SettingsResource($settings))->toArray(request())
@@ -69,6 +70,7 @@ class SettingsController extends AdminBaseController
// 저장 후 전체 설정 반환 (관리자 UI 상태 업데이트용)
$allSettings = $this->settingsService->getAllSettings();
$allSettings['available_drivers'] = $this->driverRegistryService->getAllAvailableDrivers();
+ $allSettings['_meta'] = ['limits' => config('core.settings_limits', [])];
return $this->success('settings.save_success', [
'settings' => $allSettings,
diff --git a/app/Http/Controllers/Api/Admin/TemplateController.php b/app/Http/Controllers/Api/Admin/TemplateController.php
index eb3dcdc7..8eeabc3a 100644
--- a/app/Http/Controllers/Api/Admin/TemplateController.php
+++ b/app/Http/Controllers/Api/Admin/TemplateController.php
@@ -7,20 +7,21 @@ use App\Helpers\PermissionHelper;
use App\Http\Controllers\Api\Base\AdminBaseController;
use App\Http\Controllers\Concerns\InjectsExtensionLanguagePacks;
use App\Http\Controllers\Concerns\OrchestratesCascadeInstall;
+use App\Http\Requests\Extension\ChangelogRequest;
use App\Http\Requests\Template\ActivateTemplateRequest;
use App\Http\Requests\Template\DeactivateTemplateRequest;
use App\Http\Requests\Template\IndexTemplateRequest;
use App\Http\Requests\Template\InstallTemplateFromFileRequest;
-use App\Http\Requests\Template\PreviewTemplateManifestRequest;
use App\Http\Requests\Template\InstallTemplateFromGithubRequest;
use App\Http\Requests\Template\InstallTemplateRequest;
use App\Http\Requests\Template\PerformTemplateUpdateRequest;
+use App\Http\Requests\Template\PreviewTemplateManifestRequest;
use App\Http\Requests\Template\RefreshTemplateLayoutsRequest;
use App\Http\Requests\Template\UninstallTemplateRequest;
-use App\Http\Requests\Extension\ChangelogRequest;
use App\Http\Resources\TemplateCollection;
use App\Http\Resources\TemplateResource;
use App\Services\Extension\ExtensionInstallPreviewBuilder;
+use App\Services\LanguagePack\LanguagePackBundledRegistrar;
use App\Services\LicenseService;
use App\Services\TemplateService;
use Illuminate\Http\JsonResponse;
@@ -215,7 +216,7 @@ class TemplateController extends AdminBaseController
$templateInfo = $result['template_info'] ?? null;
// 요구사항 #7: 재활성화 시 cascade 비활성화됐던 언어팩 목록 응답에 포함
- $pendingLanguagePacks = app(\App\Services\LanguagePack\LanguagePackBundledRegistrar::class)
+ $pendingLanguagePacks = app(LanguagePackBundledRegistrar::class)
->getPendingForReactivation('template', $templateName);
if ($templateInfo) {
@@ -435,6 +436,12 @@ class TemplateController extends AdminBaseController
public function checkModifiedLayouts(string $templateName): JsonResponse
{
try {
+ // 미존재 식별자는 404 로 구분한다. 존재 확인 없이 조회하면 레이아웃 0건과
+ // 템플릿 부재가 똑같이 "수정된 레이아웃 없음" 으로 보고된다.
+ if (! $this->templateService->getTemplateInfo($templateName)) {
+ return $this->error('templates.not_found', 404, null, ['template' => $templateName]);
+ }
+
$result = $this->templateService->checkModifiedLayouts($templateName);
return $this->success('templates.check_modified_layouts_success', $result);
@@ -466,14 +473,23 @@ class TemplateController extends AdminBaseController
$templateInfo = $result['template_info'] ?? null;
+ // 메시지 치환 파라미터를 반드시 전달한다 — 누락 시 ":template"/":version"
+ // 플레이스홀더가 그대로 사용자에게 노출된다.
+ $messageParams = [
+ 'template' => $templateName,
+ 'version' => $result['to_version'] ?? ($templateInfo['version'] ?? ''),
+ ];
+
if ($templateInfo) {
return $this->successWithResource(
'templates.update_success',
- new TemplateResource($templateInfo)
+ new TemplateResource($templateInfo),
+ 200,
+ $messageParams
);
}
- return $this->success('templates.update_success', $result);
+ return $this->success('templates.update_success', $result, 200, $messageParams);
} catch (ValidationException $e) {
// Service/Manager에서 이미 번역된 메시지를 errors에 포함하므로
// 첫 번째 에러를 top-level message로 직접 사용 (이중 래핑 방지)
@@ -516,7 +532,7 @@ class TemplateController extends AdminBaseController
/**
* 템플릿의 라이선스 파일 내용을 반환합니다.
*
- * @param string $identifier 템플릿 식별자
+ * @param string $identifier 템플릿 식별자
* @return JsonResponse
*/
public function license(string $identifier): JsonResponse
diff --git a/app/Http/Controllers/Api/Admin/UserController.php b/app/Http/Controllers/Api/Admin/UserController.php
index b399270d..65baa1b1 100644
--- a/app/Http/Controllers/Api/Admin/UserController.php
+++ b/app/Http/Controllers/Api/Admin/UserController.php
@@ -129,6 +129,30 @@ class UserController extends AdminBaseController
}
}
+ /**
+ * 사용자의 계정 잠금을 해제합니다.
+ *
+ * 로그인 실패 누적으로 잠긴 계정(특히 잠금 시간 0 = 무한대 설정으로 영구 잠긴 계정)을
+ * 관리자가 수동으로 풀어 줍니다. 이 경로가 없으면 영구 잠금 계정은 성공 로그인 자체가
+ * 불가하므로 복구 수단이 없습니다.
+ *
+ * @param User $user 잠금을 해제할 사용자 모델
+ * @return JsonResponse 갱신된 사용자 정보를 포함한 JSON 응답
+ */
+ public function unlock(User $user): JsonResponse
+ {
+ try {
+ $unlocked = $this->userService->unlockAccount($user);
+
+ return $this->successWithResource(
+ 'auth.account_unlocked',
+ new UserResource($unlocked)
+ );
+ } catch (Exception $e) {
+ return $this->error('user.update_failed', 500, $e, ['error' => $e->getMessage()]);
+ }
+ }
+
/**
* 사용자를 삭제합니다.
*
diff --git a/app/Http/Controllers/Api/Auth/AuthController.php b/app/Http/Controllers/Api/Auth/AuthController.php
index 4f5e0d40..d481397e 100644
--- a/app/Http/Controllers/Api/Auth/AuthController.php
+++ b/app/Http/Controllers/Api/Auth/AuthController.php
@@ -4,15 +4,16 @@ namespace App\Http\Controllers\Api\Auth;
use App\Exceptions\Auth\AccountLockedException;
use App\Http\Controllers\Api\Base\AuthBaseController;
+use App\Http\Requests\Auth\AuthenticatedRequest;
use App\Http\Requests\Auth\ForgotPasswordRequest;
use App\Http\Requests\Auth\LoginRequest;
use App\Http\Requests\Auth\RegisterRequest;
use App\Http\Requests\Auth\ResetPasswordRequest;
+use App\Http\Requests\Auth\TwoFactorChallengeRequest;
use App\Http\Requests\Auth\ValidateResetTokenRequest;
use App\Http\Resources\UserResource;
use App\Services\AuthService;
use Illuminate\Http\JsonResponse;
-use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;
class AuthController extends AuthBaseController
@@ -26,6 +27,8 @@ class AuthController extends AuthBaseController
// 공개 인증 엔드포인트를 제외한 나머지에만 인증 미들웨어 적용
$this->middleware('auth:sanctum')->except([
'login',
+ // 2단계 인증 확인은 아직 토큰이 없는 상태에서 호출된다 — 주체는 challenge 가 식별한다
+ 'verifyTwoFactor',
'register',
'forgotPassword',
'resetPassword',
@@ -47,20 +50,59 @@ class AuthController extends AuthBaseController
$request->validated()['password']
);
+ // 2단계 인증이 켜져 있으면 아직 토큰이 없다 — 인증 코드 확인 단계로 안내한다
+ if ($data['two_factor_required'] ?? false) {
+ return $this->success('auth.two_factor_required', $data);
+ }
+
// 사용자 정보는 Resource로, 토큰은 그대로
$data['user'] = new UserResource($data['user']);
return $this->success('auth.login_success', $data);
} catch (AccountLockedException $e) {
- return $this->error('auth.account_locked', 423, [
- 'locked_until' => $e->lockedUntil->toIso8601String(),
- 'retry_after_seconds' => $e->remainingMinutes * 60,
- ], ['minutes' => $e->remainingMinutes]);
+ // 영구 잠금(무한대 설정)은 해제 시각·잔여 시간이 없다 — null 그대로 노출.
+ return $this->error(
+ $e->isPermanent() ? 'auth.account_locked_permanently' : 'auth.account_locked',
+ 423,
+ [
+ 'locked_until' => $e->lockedUntil?->toIso8601String(),
+ 'retry_after_seconds' => $e->remainingMinutes === null ? null : $e->remainingMinutes * 60,
+ 'permanent' => $e->isPermanent(),
+ ],
+ ['minutes' => $e->remainingMinutes]
+ );
} catch (ValidationException $e) {
return $this->unauthorized('auth.login_failed');
}
}
+ /**
+ * 2단계 인증 코드를 확인하고 로그인을 완료합니다.
+ *
+ * 비밀번호 확인 단계(`login`)는 토큰 대신 challenge 를 돌려주며, 이 엔드포인트가
+ * 코드 확인에 성공해야 비로소 토큰이 발급됩니다.
+ *
+ * @param TwoFactorChallengeRequest $request challenge 확인 요청
+ * @return JsonResponse 로그인 결과와 사용자 정보, 토큰을 포함한 JSON 응답
+ */
+ public function verifyTwoFactor(TwoFactorChallengeRequest $request): JsonResponse
+ {
+ $validated = $request->validated();
+
+ try {
+ $data = $this->authService->completeTwoFactor(
+ $validated['challenge_id'],
+ ['code' => $validated['code']]
+ );
+
+ $data['user'] = new UserResource($data['user']);
+
+ return $this->success('auth.login_success', $data);
+ } catch (ValidationException $e) {
+ return $this->unauthorized('auth.two_factor_failed');
+ }
+ }
+
/**
* 새로운 사용자를 등록시킵니다.
*
@@ -84,10 +126,10 @@ class AuthController extends AuthBaseController
/**
* 사용자를 로그아웃시킵니다. (현재 디바이스만)
*
- * @param Request $request HTTP 요청
+ * @param AuthenticatedRequest $request 인증 세션 요청 (본문 입력 없음)
* @return JsonResponse 로그아웃 성공 메시지
*/
- public function logout(Request $request): JsonResponse
+ public function logout(AuthenticatedRequest $request): JsonResponse
{
$this->authService->logout($request->user());
@@ -97,10 +139,10 @@ class AuthController extends AuthBaseController
/**
* 모든 디바이스에서 사용자를 로그아웃시킵니다.
*
- * @param Request $request HTTP 요청
+ * @param AuthenticatedRequest $request 인증 세션 요청 (본문 입력 없음)
* @return JsonResponse 로그아웃 성공 메시지
*/
- public function logoutFromAllDevices(Request $request): JsonResponse
+ public function logoutFromAllDevices(AuthenticatedRequest $request): JsonResponse
{
$this->authService->logoutFromAllDevices($request->user());
@@ -110,10 +152,10 @@ class AuthController extends AuthBaseController
/**
* 현재 로그인된 사용자의 정보를 반환합니다.
*
- * @param Request $request HTTP 요청
+ * @param AuthenticatedRequest $request 인증 세션 요청 (본문 입력 없음)
* @return JsonResponse 사용자 정보를 포함한 JSON 응답
*/
- public function user(Request $request): JsonResponse
+ public function user(AuthenticatedRequest $request): JsonResponse
{
$user = $request->user();
@@ -131,10 +173,10 @@ class AuthController extends AuthBaseController
/**
* 사용자의 인증 토큰을 갱신합니다.
*
- * @param Request $request HTTP 요청
+ * @param AuthenticatedRequest $request 인증 세션 요청 (본문 입력 없음)
* @return JsonResponse 새로운 토큰과 사용자 정보를 포함한 JSON 응답
*/
- public function refresh(Request $request): JsonResponse
+ public function refresh(AuthenticatedRequest $request): JsonResponse
{
$data = $this->authService->refreshToken($request->user());
diff --git a/app/Http/Controllers/Api/Base/AuthBaseController.php b/app/Http/Controllers/Api/Base/AuthBaseController.php
index 52432b15..1a2abdc0 100644
--- a/app/Http/Controllers/Api/Base/AuthBaseController.php
+++ b/app/Http/Controllers/Api/Base/AuthBaseController.php
@@ -2,6 +2,7 @@
namespace App\Http\Controllers\Api\Base;
+use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\Log;
/**
@@ -21,7 +22,7 @@ abstract class AuthBaseController extends BaseApiController
/**
* 사용자 소유권을 확인합니다.
*
- * @param int $userId 확인할 사용자 ID
+ * @param int $userId 확인할 사용자 ID
* @return bool
*/
protected function isOwner(int $userId): bool
@@ -32,7 +33,7 @@ abstract class AuthBaseController extends BaseApiController
/**
* 사용자가 특정 리소스에 접근할 수 있는지 확인합니다.
*
- * @param mixed $resource 접근하려는 리소스
+ * @param mixed $resource 접근하려는 리소스
* @return bool
*/
protected function canAccessResource($resource): bool
@@ -48,8 +49,8 @@ abstract class AuthBaseController extends BaseApiController
/**
* 사용자 활동을 기록합니다.
*
- * @param string $action 수행한 작업
- * @param array $data 관련 데이터
+ * @param string $action 수행한 작업
+ * @param array $data 관련 데이터
* @return void
*/
protected function logUserActivity(string $action, array $data = []): void
@@ -58,20 +59,20 @@ abstract class AuthBaseController extends BaseApiController
Log::info("User Activity: {$action}", [
'user_id' => $this->getCurrentUser()?->uuid,
'data' => $data,
- 'timestamp' => now()
+ 'timestamp' => now(),
]);
}
/**
* 리소스 소유권을 확인하고, 소유자가 아니면 Forbidden 응답을 반환합니다.
*
- * @param mixed $resource 확인할 리소스
- * @param string $messageKey 오류 메시지 키
- * @return \Illuminate\Http\JsonResponse|null 소유자이면 null, 아니면 Forbidden 응답
+ * @param mixed $resource 확인할 리소스
+ * @param string $messageKey 오류 메시지 키
+ * @return JsonResponse|null 소유자이면 null, 아니면 Forbidden 응답
*/
protected function checkOwnership($resource, string $messageKey = 'common.forbidden')
{
- if (!$this->canAccessResource($resource)) {
+ if (! $this->canAccessResource($resource)) {
return $this->forbidden($messageKey);
}
@@ -81,14 +82,21 @@ abstract class AuthBaseController extends BaseApiController
/**
* API 사용량을 기록합니다.
*
- * @param string $endpoint 엔드포인트
- * @param array $data 관련 데이터
+ * @param string $endpoint 엔드포인트
+ * @param array $data 관련 데이터
* @return void
*/
protected function logApiUsage(string $endpoint, array $data = []): void
{
// TODO: API 사용량 통계 시스템 구현
- Log::info("Auth API Usage: {$endpoint}", [
+ //
+ // PublicBaseController 와 같은 이유로 디버그 모드에서만 기록한다.
+ // 통계 시스템이 서기 전까지 요청마다 로그 파일에 줄을 쌓지 않는다.
+ if (! config('app.debug')) {
+ return;
+ }
+
+ Log::debug("Auth API Usage: {$endpoint}", [
'user_id' => $this->getCurrentUser()?->uuid,
'ip' => request()->ip(),
'user_agent' => request()->userAgent(),
diff --git a/app/Http/Controllers/Api/Base/PublicBaseController.php b/app/Http/Controllers/Api/Base/PublicBaseController.php
index 84c1ccfd..cc108813 100644
--- a/app/Http/Controllers/Api/Base/PublicBaseController.php
+++ b/app/Http/Controllers/Api/Base/PublicBaseController.php
@@ -3,9 +3,7 @@
namespace App\Http\Controllers\Api\Base;
use App\Contracts\Extension\CacheInterface;
-use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\Log;
-use Symfony\Component\HttpFoundation\BinaryFileResponse;
/**
* 공개 API용 베이스 컨트롤러
@@ -27,9 +25,9 @@ abstract class PublicBaseController extends BaseApiController
* 이는 확장 설치 직후·활성화 전 등의 일시적 상태에서 얻은 "not found" 같은
* 에러 응답이 영구 캐시되어 복구 후에도 잘못된 응답을 반환하는 문제를 방지한다.
*
- * @param string $key 캐시 키
- * @param callable $callback 데이터 생성 콜백
- * @param int $ttl 캐시 유지 시간 (초)
+ * @param string $key 캐시 키
+ * @param callable $callback 데이터 생성 콜백
+ * @param int $ttl 캐시 유지 시간 (초)
* @return mixed
*/
protected function cached(string $key, callable $callback, int $ttl = 3600)
@@ -54,18 +52,27 @@ abstract class PublicBaseController extends BaseApiController
/**
* API 사용량을 기록합니다.
*
- * @param string $endpoint 엔드포인트
- * @param array $data 관련 데이터
+ * @param string $endpoint 엔드포인트
+ * @param array $data 관련 데이터
* @return void
*/
protected function logApiUsage(string $endpoint, array $data = []): void
{
// TODO: API 사용량 통계 시스템 구현
- Log::info("Public API Usage: {$endpoint}", [
+ //
+ // 호출 지점은 레이아웃·확장 번들·정적 자산처럼 페이지 로드마다 여러 번 열리는
+ // 공개 엔드포인트다. 통계 시스템이 서기 전까지 이 자리가 요청마다 로그 파일에
+ // 줄을 쌓지 않도록, 디버그 모드에서만 기록한다. 기본 설치는 APP_DEBUG=false 이므로
+ // 아무것도 쓰지 않는다.
+ if (! config('app.debug')) {
+ return;
+ }
+
+ Log::debug("Public API Usage: {$endpoint}", [
'ip' => request()->ip(),
'user_agent' => request()->userAgent(),
'data' => $data,
- 'timestamp' => now()
+ 'timestamp' => now(),
]);
}
@@ -80,8 +87,7 @@ abstract class PublicBaseController extends BaseApiController
'ip' => request()->ip(),
'user_agent' => request()->userAgent(),
'referer' => request()->header('referer'),
- 'timestamp' => now()
+ 'timestamp' => now(),
];
}
}
-
diff --git a/app/Http/Controllers/Api/Identity/IdentityVerificationController.php b/app/Http/Controllers/Api/Identity/IdentityVerificationController.php
index a8df7880..2d898b0c 100644
--- a/app/Http/Controllers/Api/Identity/IdentityVerificationController.php
+++ b/app/Http/Controllers/Api/Identity/IdentityVerificationController.php
@@ -2,6 +2,7 @@
namespace App\Http\Controllers\Api\Identity;
+use App\Enums\IdentityOriginType;
use App\Extension\IdentityVerification\IdentityVerificationManager;
use App\Http\Controllers\Api\Base\PublicBaseController;
use App\Http\Requests\Identity\CancelChallengeRequest;
@@ -15,6 +16,7 @@ use App\Http\Requests\Identity\VerifyChallengeRequest;
use App\Http\Resources\Identity\ChallengeResource;
use App\Http\Resources\Identity\ProviderResource;
use App\Models\IdentityVerificationLog;
+use App\Models\User;
use App\Services\IdentityPolicyService;
use App\Services\IdentityVerificationService;
use Illuminate\Http\JsonResponse;
@@ -53,7 +55,7 @@ class IdentityVerificationController extends PublicBaseController
$user = $request->user();
$target = $user ?: ($validated['target'] ?? []);
- if (! ($user instanceof \App\Models\User) && empty($target['email']) && empty($target['phone'])) {
+ if (! ($user instanceof User) && empty($target['email']) && empty($target['phone'])) {
return $this->error('identity.errors.missing_target', 422);
}
@@ -68,7 +70,7 @@ class IdentityVerificationController extends PublicBaseController
context: [
'ip_address' => $request->ip(),
'user_agent' => substr((string) $request->userAgent(), 0, 512),
- 'origin_type' => \App\Enums\IdentityOriginType::Api->value,
+ 'origin_type' => IdentityOriginType::Api->value,
'origin_identifier' => '/api/identity/challenges',
],
providerId: $providerId,
@@ -136,7 +138,7 @@ class IdentityVerificationController extends PublicBaseController
*
* @param CancelChallengeRequest $request 검증된 요청
* @param IdentityVerificationLog $challenge 라우트 모델 바인딩으로 resolve 된 challenge 로그
- * @return JsonResponse
+ * @return JsonResponse 취소 결과
*/
public function cancel(CancelChallengeRequest $request, IdentityVerificationLog $challenge): JsonResponse
{
@@ -159,7 +161,8 @@ class IdentityVerificationController extends PublicBaseController
*
* @param ShowChallengeRequest $request 검증된 요청
* @param IdentityVerificationLog $challenge 라우트 모델 바인딩으로 resolve 된 challenge 로그
- * @return JsonResponse
+ * @return JsonResponse 공개 안전 상태 필드
+ *
* @since engine-v1.46.0
*/
public function show(ShowChallengeRequest $request, IdentityVerificationLog $challenge): JsonResponse
@@ -170,7 +173,7 @@ class IdentityVerificationController extends PublicBaseController
return $this->error('identity.errors.challenge_not_found', 404);
}
- return $this->success('messages.success', $status);
+ return $this->success('common.success', $status);
}
/**
@@ -188,6 +191,7 @@ class IdentityVerificationController extends PublicBaseController
* @param IdentityCallbackRequest $request 검증된 요청
* @param string $providerId 콜백을 보낸 provider 식별자
* @return JsonResponse|RedirectResponse
+ *
* @since engine-v1.46.0
*/
public function callback(IdentityCallbackRequest $request, string $providerId)
@@ -271,7 +275,7 @@ class IdentityVerificationController extends PublicBaseController
$providers,
);
- return $this->success('messages.success', $data);
+ return $this->success('common.success', $data);
}
/**
@@ -300,7 +304,7 @@ class IdentityVerificationController extends PublicBaseController
];
}
- return $this->success('messages.success', $data);
+ return $this->success('common.success', $data);
}
/**
@@ -353,11 +357,11 @@ class IdentityVerificationController extends PublicBaseController
$policy = $this->policyService->resolve($scope, $target);
if (! $policy || ! $policy->enabled) {
- return $this->success('messages.success', null);
+ return $this->success('common.success', null);
}
// 민감 필드는 노출하지 않고 UI 힌트에 필요한 최소 필드만 반환
- return $this->success('messages.success', [
+ return $this->success('common.success', [
'policy_key' => $policy->key,
'scope' => $policy->scope,
'target' => $policy->target,
diff --git a/app/Http/Controllers/Api/Public/AssetProbeController.php b/app/Http/Controllers/Api/Public/AssetProbeController.php
new file mode 100644
index 00000000..e30d6250
--- /dev/null
+++ b/app/Http/Controllers/Api/Public/AssetProbeController.php
@@ -0,0 +1,74 @@
+ 'application/javascript; charset=utf-8',
+ 'Cache-Control' => 'no-store, no-cache, must-revalidate, max-age=0',
+ 'Pragma' => 'no-cache',
+ 'X-Content-Type-Options' => 'nosniff',
+ ]);
+ }
+}
diff --git a/app/Http/Controllers/Api/Public/PublicModuleController.php b/app/Http/Controllers/Api/Public/PublicModuleController.php
index 85de88f1..ffecc46e 100644
--- a/app/Http/Controllers/Api/Public/PublicModuleController.php
+++ b/app/Http/Controllers/Api/Public/PublicModuleController.php
@@ -71,14 +71,16 @@ class PublicModuleController extends PublicBaseController
*
* @param ServeModuleAssetRequest $request 검증된 요청 (경로, 확장자 검증 완료)
* @param string $identifier 모듈 식별자 (vendor-module 형식)
- * @param string $path 에셋 경로 (dist/js/module.iife.js 등)
* @return BinaryFileResponse|JsonResponse|Response 파일 응답 또는 에러 응답
*/
public function serveAsset(
ServeModuleAssetRequest $request,
- string $identifier,
- string $path
+ string $identifier
): BinaryFileResponse|JsonResponse|Response {
+ // 파일 경로는 FormRequest 에서 받는다 — 확장자 모드는 `{path}` 라우트 세그먼트,
+ // 확장자 없는 모드는 `?file=` 쿼리로 오며 prepareForValidation() 이 이를 흡수한다.
+ $path = (string) $request->validated('path');
+
// FormRequest에서 이미 보안 검증 완료
// API 사용량 기록
$this->logApiUsage('modules.assets', ['identifier' => $identifier, 'path' => $path]);
diff --git a/app/Http/Controllers/Api/Public/PublicPluginController.php b/app/Http/Controllers/Api/Public/PublicPluginController.php
index b187f984..b062b2a6 100644
--- a/app/Http/Controllers/Api/Public/PublicPluginController.php
+++ b/app/Http/Controllers/Api/Public/PublicPluginController.php
@@ -70,14 +70,16 @@ class PublicPluginController extends PublicBaseController
*
* @param ServePluginAssetRequest $request 검증된 요청 (경로, 확장자 검증 완료)
* @param string $identifier 플러그인 식별자 (vendor-plugin 형식)
- * @param string $path 에셋 경로 (dist/js/plugin.iife.js 등)
* @return BinaryFileResponse|JsonResponse|Response 파일 응답 또는 에러 응답
*/
public function serveAsset(
ServePluginAssetRequest $request,
- string $identifier,
- string $path
+ string $identifier
): BinaryFileResponse|JsonResponse|Response {
+ // 파일 경로는 FormRequest 에서 받는다 — 확장자 모드는 `{path}` 라우트 세그먼트,
+ // 확장자 없는 모드는 `?file=` 쿼리로 오며 prepareForValidation() 이 이를 흡수한다.
+ $path = (string) $request->validated('path');
+
// FormRequest에서 이미 보안 검증 완료
// API 사용량 기록
$this->logApiUsage('plugins.assets', ['identifier' => $identifier, 'path' => $path]);
diff --git a/app/Http/Controllers/Api/Public/PublicSearchController.php b/app/Http/Controllers/Api/Public/PublicSearchController.php
index 551187a3..5bcf8cce 100644
--- a/app/Http/Controllers/Api/Public/PublicSearchController.php
+++ b/app/Http/Controllers/Api/Public/PublicSearchController.php
@@ -2,9 +2,11 @@
namespace App\Http\Controllers\Api\Public;
+use App\Enums\TotalRelation;
use App\Extension\HookManager;
use App\Http\Controllers\Api\Base\PublicBaseController;
use App\Http\Requests\Public\SearchRequest;
+use App\Support\Query\PaginationLimits;
use Illuminate\Http\JsonResponse;
/**
@@ -18,7 +20,7 @@ class PublicSearchController extends PublicBaseController
/**
* 통합 검색 수행
*
- * @param SearchRequest $request HTTP 요청
+ * @param SearchRequest $request HTTP 요청
* @return JsonResponse 검색 결과
*/
public function search(SearchRequest $request): JsonResponse
@@ -36,6 +38,14 @@ class PublicSearchController extends PublicBaseController
return $this->success(__('search.empty_keyword'), $this->buildEmptyResponse());
}
+ // 특정 탭을 보는 중이라면, 다른 탭의 배지 건수를 아예 세지 않을 수 있다.
+ // 기본값은 세는 쪽이다 — 탭 배지가 화면 요소라 끄면 숫자가 사라진다. 다만 배지가
+ // 필요 없는 화면(더 보기 페이지 등)은 with_counts=false 로 그 비용을 없앤다.
+ // 전체 탭은 배지가 화면의 주 정보라 이 값과 무관하게 항상 센다.
+ $includeInactiveCounts = $type === 'all'
+ ? true
+ : $request->boolean('with_counts', true);
+
// 검색 컨텍스트 구성 (모듈별 파라미터는 request 전체를 전달하여 각 모듈이 직접 처리)
$context = [
'q' => $q,
@@ -44,6 +54,10 @@ class PublicSearchController extends PublicBaseController
'page' => $page,
'per_page' => $perPage,
'all_tab_limit' => 5,
+ // 커서는 특정 탭을 볼 때만 의미가 있다. 전체 탭은 카테고리마다 몇 건씩만
+ // 보여 주므로 깊은 페이지 자체가 없고, 카테고리별 커서를 하나로 합칠 수도 없다.
+ 'cursor' => $type === 'all' ? null : ($validated['cursor'] ?? null),
+ 'include_inactive_counts' => $includeInactiveCounts,
'user' => $request->user(),
'request' => $request,
];
@@ -56,8 +70,14 @@ class PublicSearchController extends PublicBaseController
// 프론트엔드용 응답 구조로 변환 (훅을 통해 모듈이 처리)
$response = $this->buildResponse($q, $results, $context);
+ // 총 건수가 상한에 걸렸으면 "N건" 이 아니라 "N건 이상" 으로 알린다.
+ // 세지 않은 값을 정확한 것처럼 말하지 않는다.
+ $messageKey = ($response['total_is_exact'] ?? true)
+ ? 'search.results_found'
+ : 'search.results_found_at_least';
+
return $this->success(
- __('search.results_found', ['count' => number_format($response['total'])]),
+ __($messageKey, ['count' => number_format($response['total'])]),
$response
);
}
@@ -72,6 +92,9 @@ class PublicSearchController extends PublicBaseController
return [
'q' => '',
'total' => 0,
+ 'total_relation' => TotalRelation::Exact->value,
+ 'total_is_exact' => true,
+ 'result_cap' => null,
];
}
@@ -81,9 +104,9 @@ class PublicSearchController extends PublicBaseController
* 코어는 기본 응답 구조만 생성하고,
* 각 모듈이 core.search.build_response 훅을 통해 자신의 카테고리 응답을 구성합니다.
*
- * @param string $q 검색어
- * @param array $results Hook에서 반환된 검색 결과
- * @param array $context 검색 컨텍스트
+ * @param string $q 검색어
+ * @param array $results Hook에서 반환된 검색 결과
+ * @param array $context 검색 컨텍스트
* @return array 프론트엔드용 응답 구조
*/
private function buildResponse(string $q, array $results, array $context): array
@@ -97,8 +120,15 @@ class PublicSearchController extends PublicBaseController
// 모듈은 $results에서 자신의 데이터를 가져와 $response에 추가
$response = HookManager::applyFilters('core.search.build_response', $response, $results, $context);
- // 전체 합계를 항상 보존 (탭 UI에서 전체 건수 표시용)
+ // 전체 합계를 항상 보존 (탭 UI에서 전체 건수 표시용).
+ // "전체" 탭 배지도 잘린 합계인지 알아야 하므로 정확도를 함께 붙인다.
$response['all_count'] = $response['total'];
+ $response['all_count_is_exact'] = $this->resolveTotalAccuracy($results)['total_is_exact'];
+
+ // 탭 배지는 카테고리마다 하나씩 그려지므로 정확도도 카테고리마다 필요하다.
+ // 모듈이 각자 자기 키를 내보내면 어떤 배지는 정확도를 받고 어떤 배지는 못 받아,
+ // 상한에 걸린 숫자가 그 배지에서만 정확한 값처럼 보인다. 코어가 일괄로 붙인다.
+ $response['counts_are_exact'] = $this->resolveCategoryAccuracy($results);
// 특정 탭 조회 시 total을 해당 탭의 count로 설정
$type = $context['type'] ?? 'all';
@@ -109,13 +139,14 @@ class PublicSearchController extends PublicBaseController
}
}
- return $response;
+ // 정확도 메타 — 전체 탭은 카테고리 합집합, 특정 탭은 그 카테고리 하나만 본다.
+ return array_merge($response, $this->resolveTotalAccuracy($results, $type));
}
/**
* 전체 검색 결과 수 계산
*
- * @param array $results Hook에서 반환된 검색 결과
+ * @param array $results Hook에서 반환된 검색 결과
* @return int 전체 결과 수
*/
private function calculateTotal(array $results): int
@@ -127,4 +158,60 @@ class PublicSearchController extends PublicBaseController
return $total;
}
+
+ /**
+ * 카테고리별 총 건수 정확도를 모읍니다.
+ *
+ * 탭 배지는 카테고리 수만큼 그려지므로 정확도도 그 수만큼 있어야 합니다. 하나라도
+ * 빠지면 그 배지에서만 상한에 걸린 숫자가 정확한 값처럼 보이고, 오류로는 드러나지
+ * 않은 채 그냥 틀린 숫자로 남습니다.
+ *
+ * @param array $results Hook에서 반환된 검색 결과
+ * @return array 카테고리 => 정확 여부
+ */
+ private function resolveCategoryAccuracy(array $results): array
+ {
+ $accuracy = [];
+
+ foreach ($results as $category => $categoryData) {
+ $accuracy[$category] = ($categoryData['total_is_exact'] ?? true) === true;
+ }
+
+ return $accuracy;
+ }
+
+ /**
+ * 응답 전체의 총 건수 정확도를 정합니다.
+ *
+ * 전체 탭에서는 카테고리 중 하나라도 상한에 걸리면 합계도 "이상" 이다 — 정확한
+ * 카테고리 몇 개를 더해 봐야 전체가 정확해지지 않는다.
+ *
+ * 특정 탭을 보는 중이면 `total` 이 그 카테고리 건수로 바뀌므로 정확도도 그 카테고리
+ * 하나만 본다. 다른 카테고리가 잘렸다는 이유로 정확한 값을 "이상" 이라 말하지 않는다.
+ *
+ * @param array $results Hook에서 반환된 검색 결과
+ * @param string $type 조회 탭 (all 이면 전체 합계)
+ * @return array{total_relation: string, total_is_exact: bool, result_cap: int|null} 정확도 메타
+ */
+ private function resolveTotalAccuracy(array $results, string $type = 'all'): array
+ {
+ $scoped = ($type !== 'all' && array_key_exists($type, $results))
+ ? [$results[$type]]
+ : $results;
+
+ $isExact = true;
+
+ foreach ($scoped as $categoryData) {
+ if (($categoryData['total_is_exact'] ?? true) === false) {
+ $isExact = false;
+ break;
+ }
+ }
+
+ return [
+ 'total_relation' => $isExact ? TotalRelation::Exact->value : TotalRelation::AtLeast->value,
+ 'total_is_exact' => $isExact,
+ 'result_cap' => PaginationLimits::resultCap('search'),
+ ];
+ }
}
diff --git a/app/Http/Controllers/Api/Public/PublicTemplateController.php b/app/Http/Controllers/Api/Public/PublicTemplateController.php
index ee62eb1c..13d39d9e 100644
--- a/app/Http/Controllers/Api/Public/PublicTemplateController.php
+++ b/app/Http/Controllers/Api/Public/PublicTemplateController.php
@@ -2,6 +2,7 @@
namespace App\Http\Controllers\Api\Public;
+use App\Contracts\Extension\CacheInterface;
use App\Enums\ExtensionStatus;
use App\Extension\Helpers\EditorSpecAssembler;
use App\Extension\Traits\ClearsTemplateCaches;
@@ -12,6 +13,7 @@ use App\Services\TemplateLayoutAttachmentService;
use App\Services\TemplateService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Response;
+use Illuminate\Support\Facades\Log;
use Symfony\Component\HttpFoundation\BinaryFileResponse;
/**
@@ -40,22 +42,36 @@ class PublicTemplateController extends PublicBaseController
// 캐시 버전을 키에 포함하여 모듈/플러그인 변경 시 캐시 무효화
$cacheVersion = request()->query('v', 0);
- // 캐싱된 응답 반환 (1시간 유효)
- $routesData = $this->cached(
- "template.routes.{$identifier}.v{$cacheVersion}",
- function () use ($identifier) {
- // Service에서 템플릿 + 모듈 routes 데이터 병합 조회
- $result = $this->templateService->getRoutesDataWithModules($identifier);
+ // 확장 업데이트 중에는 활성 디렉토리가 잠시 비어 그 모듈의 라우트가 통째로 빠진다.
+ // 그 순간의 응답을 버전 키에 캐시하면 업데이트가 끝난 뒤에도 캐시가 만료될 때까지
+ // 해당 모듈의 모든 화면이 404 로 남는다 — 버전은 이미 올라간 뒤라 스스로 회복되지 않는다.
+ // 따라서 열화 스냅샷은 그대로 응답하되 캐시에 남기지 않는다.
+ $buildRoutes = function () use ($identifier) {
+ $result = $this->templateService->getRoutesDataWithModules($identifier);
- // 에러 처리
- if (! $result['success']) {
- return ['error' => $result['error']];
- }
+ if (! $result['success']) {
+ return ['error' => $result['error']];
+ }
- return ['success' => true, 'data' => $result['data']];
- },
- 3600
- );
+ return ['success' => true, 'data' => $result['data']];
+ };
+
+ $cacheKey = "template.routes.{$identifier}.v{$cacheVersion}";
+ $cache = app(CacheInterface::class);
+ $routesData = $cache->get($cacheKey);
+
+ if ($routesData === null) {
+ $routesData = $buildRoutes();
+
+ if ($this->templateService->lastRouteMergeWasDegraded()) {
+ Log::warning('라우트 병합이 열화 상태여서 캐시하지 않습니다 (확장 업데이트 진행 중 추정)', [
+ 'template' => $identifier,
+ 'cache_version' => $cacheVersion,
+ ]);
+ } else {
+ $cache->put($cacheKey, $routesData, 3600);
+ }
+ }
// 에러 응답 처리
if (isset($routesData['error'])) {
@@ -88,13 +104,16 @@ class PublicTemplateController extends PublicBaseController
/**
* 템플릿 정적 파일 서빙
*
- * @param ServeTemplateAssetRequest $request 요청 (FormRequest 검증)
+ * @param ServeTemplateAssetRequest $request 요청 (FormRequest 검증, 파일 경로 `path` 포함)
* @param string $identifier 템플릿 식별자
- * @param string $path 요청 경로
* @return BinaryFileResponse|JsonResponse|Response 파일 응답 또는 에러
*/
- public function serveAsset(ServeTemplateAssetRequest $request, string $identifier, string $path): BinaryFileResponse|JsonResponse|Response
+ public function serveAsset(ServeTemplateAssetRequest $request, string $identifier): BinaryFileResponse|JsonResponse|Response
{
+ // 파일 경로는 FormRequest 에서 받는다 — 확장자 모드는 `{path}` 라우트 세그먼트,
+ // 확장자 없는 모드는 `?file=` 쿼리로 오며 prepareForValidation() 이 이를 흡수한다.
+ $path = (string) $request->validated('path');
+
// FormRequest에서 이미 보안 검증 완료
// API 사용량 기록
$this->logApiUsage('templates.assets', ['identifier' => $identifier, 'path' => $path]);
diff --git a/app/Http/Controllers/Api/Public/SitemapController.php b/app/Http/Controllers/Api/Public/SitemapController.php
index 9a5d6e88..fdd6d2d6 100644
--- a/app/Http/Controllers/Api/Public/SitemapController.php
+++ b/app/Http/Controllers/Api/Public/SitemapController.php
@@ -4,42 +4,92 @@ namespace App\Http\Controllers\Api\Public;
use App\Contracts\Extension\CacheInterface;
use App\Http\Controllers\Controller;
-use App\Seo\SitemapGenerator;
-use Illuminate\Http\Response;
+use App\Jobs\GenerateSitemapJob;
+use App\Seo\SitemapFileStore;
+use App\Seo\SitemapManager;
+use Symfony\Component\HttpFoundation\StreamedResponse;
/**
* Sitemap XML 컨트롤러
*
- * sitemap.xml 요청을 처리하여 캐시된 또는 실시간 생성된
- * Sitemap XML을 반환합니다.
+ * 비공개 디스크에 커밋된 sitemap 인덱스/자식 파일을 스트리밍으로 서빙합니다.
+ * 봇 요청 스레드에서 sitemap 을 생성하지 않으며(대용량에서 OOM/타임아웃 원인),
+ * 신선도가 만료되면 생성 잡만 예약하고 기존 세트(stale)를 그대로 내보냅니다.
*/
class SitemapController extends Controller
{
/**
- * sitemap.xml을 반환합니다.
- *
- * 캐시가 있으면 캐시된 XML, 없으면 실시간 생성 후 캐시 저장.
- *
- * @param SitemapGenerator $generator Sitemap 생성기
- * @param CacheInterface $cache 코어 캐시 드라이버
+ * 세트가 없어 503 을 반환할 때 봇에 안내할 재시도 간격 (초)
*/
- public function index(SitemapGenerator $generator, CacheInterface $cache): Response
+ private const RETRY_AFTER_SECONDS = 120;
+
+ /**
+ * sitemapindex 를 반환합니다.
+ *
+ * 커밋된 세트가 있으면 스트리밍하고, 신선도(메타 캐시)가 만료되었으면
+ * 생성 잡을 예약합니다. 세트가 전혀 없으면 503 + Retry-After 를 반환합니다.
+ *
+ * @param SitemapFileStore $store sitemap 파일 저장소 (읽기측)
+ * @param CacheInterface $cache 코어 캐시 드라이버
+ * @return StreamedResponse sitemapindex 스트림
+ */
+ public function index(SitemapFileStore $store, CacheInterface $cache): StreamedResponse
{
- $enabled = (bool) g7_core_settings('seo.sitemap_enabled', true);
- if (! $enabled) {
+ $this->assertSitemapEnabled();
+
+ $isFresh = $cache->get(SitemapManager::META_CACHE_KEY) !== null;
+
+ if ($isFresh) {
+ $response = $store->indexResponse();
+ if ($response !== null) {
+ return $response;
+ }
+ }
+
+ // 신선도 만료 또는 세트 부재 — 생성은 큐에 맡긴다 (ShouldBeUnique 로 중복 디스패치 방지).
+ GenerateSitemapJob::dispatch();
+
+ $serveStale = (bool) g7_core_settings('seo.sitemap_serve_stale_on_miss', true);
+
+ if ($serveStale) {
+ $response = $store->indexResponse();
+ if ($response !== null) {
+ return $response;
+ }
+ }
+
+ abort(503, __('seo.sitemap_not_ready'), ['Retry-After' => (string) self::RETRY_AFTER_SECONDS]);
+ }
+
+ /**
+ * 자식 sitemap 을 반환합니다.
+ *
+ * gzip 여부는 manifest 가 결정하므로 `.xml` / `.xml.gz` 요청을 같은 액션에서 처리합니다.
+ *
+ * @param int $n 자식 번호 (1부터)
+ * @param SitemapFileStore $store sitemap 파일 저장소 (읽기측)
+ * @return StreamedResponse 자식 sitemap 스트림
+ */
+ public function child(int $n, SitemapFileStore $store): StreamedResponse
+ {
+ $this->assertSitemapEnabled();
+
+ $response = $store->childResponse($n);
+
+ if ($response === null) {
abort(404);
}
- $xml = $cache->get('seo.sitemap');
+ return $response;
+ }
- if (! $xml) {
- $xml = $generator->generate();
- $ttl = (int) g7_core_settings('cache.seo_sitemap_ttl', g7_core_settings('seo.sitemap_cache_ttl', 86400));
- $cache->put('seo.sitemap', $xml, $ttl);
+ /**
+ * Sitemap 기능이 비활성화되어 있으면 404 로 중단합니다.
+ */
+ private function assertSitemapEnabled(): void
+ {
+ if (! (bool) g7_core_settings('seo.sitemap_enabled', true)) {
+ abort(404);
}
-
- return response($xml, 200, [
- 'Content-Type' => 'application/xml',
- ]);
}
}
diff --git a/app/Http/Controllers/Concerns/RebuildsSearchIndexOnDemand.php b/app/Http/Controllers/Concerns/RebuildsSearchIndexOnDemand.php
new file mode 100644
index 00000000..98ae4497
--- /dev/null
+++ b/app/Http/Controllers/Concerns/RebuildsSearchIndexOnDemand.php
@@ -0,0 +1,46 @@
+|null 응답에 실을 페이로드 (점검 불가 엔진이면 null)
+ */
+ protected function rebuildSearchIndexIfRequested(bool $requested): ?array
+ {
+ $manager = app(SearchIndexMaintenanceManager::class);
+
+ // 점검을 제공하지 않는 엔진에서는 실을 정보가 없다 (검색 자체는 정상 동작)
+ if (! $manager->hasMaintainer() || $manager->unavailableReason() !== null) {
+ return null;
+ }
+
+ if ($requested) {
+ return ['rebuilt' => true] + $manager->repairStale()->toArray();
+ }
+
+ $stale = array_values(array_filter($manager->inspect(), fn ($health) => $health->needsRebuild()));
+
+ return [
+ 'rebuilt' => false,
+ 'driver' => $manager->driver(),
+ 'stale' => array_map(fn ($health) => $health->identifier, $stale),
+ 'stale_count' => count($stale),
+ ];
+ }
+}
diff --git a/app/Http/Middleware/Concerns/DetectsRequestLocale.php b/app/Http/Middleware/Concerns/DetectsRequestLocale.php
new file mode 100644
index 00000000..58ef71f5
--- /dev/null
+++ b/app/Http/Middleware/Concerns/DetectsRequestLocale.php
@@ -0,0 +1,42 @@
+header('Accept-Language');
+ if ($acceptLanguage) {
+ $languages = explode(',', $acceptLanguage);
+ foreach ($languages as $language) {
+ $lang = trim(explode(';', $language)[0]);
+ if (strpos($lang, '-') !== false) {
+ $lang = explode('-', $lang)[0];
+ }
+ if (in_array($lang, $supportedLocales)) {
+ return $lang;
+ }
+ }
+ }
+
+ return config('app.locale', 'ko');
+ }
+}
diff --git a/app/Http/Middleware/DatabaseCredentialGuard.php b/app/Http/Middleware/DatabaseCredentialGuard.php
new file mode 100644
index 00000000..26aa69de
--- /dev/null
+++ b/app/Http/Middleware/DatabaseCredentialGuard.php
@@ -0,0 +1,85 @@
+resolveUsername();
+
+ if (PrivilegedDatabaseAccounts::isUsable($username)) {
+ return $next($request);
+ }
+
+ // SetLocale 미실행 상태이므로 로케일을 자체 감지한다.
+ // API/HTML 분기보다 먼저 적용해야 JSON 메시지도 활성 로케일을 반영한다.
+ app()->setLocale($this->detectLocale($request));
+
+ if ($request->expectsJson() || $request->is('api/*')) {
+ return response()->json([
+ 'success' => false,
+ 'message' => __('database_credential.message'),
+ ], 503);
+ }
+
+ // 확장·템플릿이 로딩되지 않은 상태이므로 템플릿 뷰나 errors/layout 을
+ // 쓸 수 없다. DB/JS 무의존 자체 완결 정적 페이지를 반환한다.
+ return response()->view('database-credential-error', [
+ // 실제 계정명은 전달하지 않는다 — 미인증 공개 페이지이므로 정보 유출.
+ 'reason' => PrivilegedDatabaseAccounts::isBlocked($username) ? 'blocked' : 'empty',
+ ], 503);
+ }
+
+ /**
+ * 현재 DB 커넥션 설정에서 사용자명을 해석합니다.
+ *
+ * DB::connection() 을 거치지 않고 config 배열만 읽습니다. 이 가드는 DB 설정이
+ * 잘못된 상황에서 동작해야 하므로, 판정을 위해 커넥션을 해석하는 것 자체가
+ * 새로운 실패 지점이 됩니다. read/write 우선순위 규칙은
+ * PrivilegedDatabaseAccounts 가 CoreServiceProvider 와 공유합니다.
+ *
+ * @return string|null 해석된 사용자명 (없으면 null)
+ */
+ protected function resolveUsername(): ?string
+ {
+ $connection = config('database.default');
+
+ return PrivilegedDatabaseAccounts::resolveUsername(
+ config("database.connections.{$connection}", [])
+ );
+ }
+}
diff --git a/app/Http/Middleware/MaintenanceModePage.php b/app/Http/Middleware/MaintenanceModePage.php
index 3c036c80..b183dd58 100644
--- a/app/Http/Middleware/MaintenanceModePage.php
+++ b/app/Http/Middleware/MaintenanceModePage.php
@@ -2,6 +2,7 @@
namespace App\Http\Middleware;
+use App\Http\Middleware\Concerns\DetectsRequestLocale;
use Closure;
use Illuminate\Foundation\Http\MaintenanceModeBypassCookie;
use Illuminate\Http\Request;
@@ -9,6 +10,8 @@ use Symfony\Component\HttpFoundation\Response;
class MaintenanceModePage
{
+ use DetectsRequestLocale;
+
/**
* Maintenance 모드일 때 전용 정적 페이지를 렌더링합니다.
*
@@ -76,31 +79,4 @@ class MaintenanceModePage
return MaintenanceModeBypassCookie::isValid($cookie, $data['secret']);
}
-
- /**
- * 로케일을 감지합니다. SetLocale 미들웨어의 로직을 준용합니다.
- *
- * @param Request $request HTTP 요청
- * @return string 감지된 로케일
- */
- protected function detectLocale(Request $request): string
- {
- $supportedLocales = config('app.supported_locales', ['ko', 'en']);
-
- $acceptLanguage = $request->header('Accept-Language');
- if ($acceptLanguage) {
- $languages = explode(',', $acceptLanguage);
- foreach ($languages as $language) {
- $lang = trim(explode(';', $language)[0]);
- if (strpos($lang, '-') !== false) {
- $lang = explode('-', $lang)[0];
- }
- if (in_array($lang, $supportedLocales)) {
- return $lang;
- }
- }
- }
-
- return config('app.locale', 'ko');
- }
}
diff --git a/app/Http/Middleware/PermissionMiddleware.php b/app/Http/Middleware/PermissionMiddleware.php
index 32a75e38..2c31a3d5 100644
--- a/app/Http/Middleware/PermissionMiddleware.php
+++ b/app/Http/Middleware/PermissionMiddleware.php
@@ -6,6 +6,7 @@ use App\Enums\PermissionType;
use App\Helpers\PermissionHelper;
use App\Helpers\ResponseHelper;
use App\Models\Role;
+use App\Support\GuestRoleResolver;
use Closure;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Http\Request;
@@ -14,13 +15,6 @@ use Symfony\Component\HttpFoundation\Response;
class PermissionMiddleware
{
- /**
- * guest role 캐시
- *
- * @var Role|null
- */
- protected static $guestRoleCache = null;
-
/**
* 특정 권한을 가진 사용자 또는 비회원(guest)의 접근을 허용합니다.
*
@@ -125,10 +119,9 @@ class PermissionMiddleware
return false;
}
- return $guestRole->permissions()
- ->where('identifier', $permission)
- ->where('type', $type)
- ->exists();
+ // 적재해 둔 권한 컬렉션에서 판정한다. permissions() 로 빌더를 다시 열면
+ // 캐시해 둔 의미가 사라져 판정마다 쿼리가 나간다.
+ return GuestRoleResolver::hasPermission($permission, $type);
}
/**
@@ -138,13 +131,7 @@ class PermissionMiddleware
*/
protected function getGuestRole(): ?Role
{
- if (self::$guestRoleCache === null) {
- self::$guestRoleCache = Role::where('identifier', 'guest')
- ->with('permissions')
- ->first();
- }
-
- return self::$guestRoleCache;
+ return GuestRoleResolver::resolve();
}
/**
@@ -158,7 +145,7 @@ class PermissionMiddleware
*/
public static function clearGuestRoleCache(): void
{
- self::$guestRoleCache = null;
+ GuestRoleResolver::flush();
}
/**
diff --git a/app/Http/Middleware/RoleMiddleware.php b/app/Http/Middleware/RoleMiddleware.php
index f8549503..33676b03 100644
--- a/app/Http/Middleware/RoleMiddleware.php
+++ b/app/Http/Middleware/RoleMiddleware.php
@@ -13,17 +13,17 @@ class RoleMiddleware
/**
* 특정 역할을 가진 사용자만 접근을 허용합니다.
*
- * @param Request $request HTTP 요청
- * @param Closure $next 다음 미들웨어
- * @param string $role 필요한 역할명
- * @param bool $requireAll 여러 역할시 모두 필요한지 여부
+ * @param Request $request HTTP 요청
+ * @param Closure $next 다음 미들웨어
+ * @param string $role 필요한 역할명
+ * @param bool $requireAll 여러 역할시 모두 필요한지 여부
* @return Response HTTP 응답
*/
public function handle(Request $request, Closure $next, string $role, bool $requireAll = true): Response
{
// 인증되지 않은 사용자
- if (!Auth::check()) {
- return ResponseHelper::unauthorized('messages.auth.unauthenticated');
+ if (! Auth::check()) {
+ return ResponseHelper::unauthorized('auth.unauthenticated');
}
$user = Auth::user();
@@ -31,16 +31,16 @@ class RoleMiddleware
// 역할 확인
if (count($roles) === 1) {
- if (!$user->hasRole($roles[0])) {
- return ResponseHelper::forbidden('messages.auth.role_denied', [
- 'required_role' => $roles[0]
+ if (! $user->hasRole($roles[0])) {
+ return ResponseHelper::forbidden('auth.role_denied', [
+ 'required_role' => $roles[0],
]);
}
} else {
- if (!$user->hasRoles($roles, $requireAll)) {
- return ResponseHelper::forbidden('messages.auth.role_denied', [
+ if (! $user->hasRoles($roles, $requireAll)) {
+ return ResponseHelper::forbidden('auth.role_denied', [
'required_roles' => $roles,
- 'require_all' => $requireAll
+ 'require_all' => $requireAll,
]);
}
}
diff --git a/app/Http/Middleware/StartApiSession.php b/app/Http/Middleware/StartApiSession.php
index 6223191a..b43ac58a 100644
--- a/app/Http/Middleware/StartApiSession.php
+++ b/app/Http/Middleware/StartApiSession.php
@@ -3,9 +3,11 @@
namespace App\Http\Middleware;
use Closure;
+use Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse;
+use Illuminate\Cookie\Middleware\EncryptCookies;
use Illuminate\Http\Request;
use Illuminate\Pipeline\Pipeline;
-use Illuminate\Support\Facades\Log;
+use Illuminate\Session\Middleware\StartSession;
use Symfony\Component\HttpFoundation\Response;
/**
@@ -23,34 +25,16 @@ class StartApiSession
/**
* 요청을 처리합니다.
*
- * @param Request $request HTTP 요청
- * @param Closure $next 다음 미들웨어
+ * @param Request $request HTTP 요청
+ * @param Closure $next 다음 미들웨어
* @return Response HTTP 응답
*/
public function handle(Request $request, Closure $next): Response
{
- Log::info('[StartApiSession] 미들웨어 시작', ['url' => $request->url()]);
-
return (new Pipeline(app()))
->send($request)
->through($this->sessionPipeline())
- ->then(function ($request) use ($next) {
- Log::info('[StartApiSession] 세션 파이프라인 완료', [
- 'hasSession' => $request->hasSession(),
- 'sessionStarted' => $request->hasSession() ? $request->session()->isStarted() : false,
- 'sessionId' => $request->hasSession() ? $request->session()->getId() : null,
- ]);
-
- $response = $next($request);
-
- Log::info('[StartApiSession] 컨트롤러 응답 후', [
- 'status' => $response->getStatusCode(),
- 'cookies' => collect($response->headers->getCookies())->map(fn($c) => $c->getName())->all(),
- 'webGuardCheck' => \Illuminate\Support\Facades\Auth::guard('web')->check(),
- ]);
-
- return $response;
- });
+ ->then(fn ($request) => $next($request));
}
/**
@@ -63,9 +47,9 @@ class StartApiSession
protected function sessionPipeline(): array
{
return [
- \Illuminate\Cookie\Middleware\EncryptCookies::class,
- \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
- \Illuminate\Session\Middleware\StartSession::class,
+ EncryptCookies::class,
+ AddQueuedCookiesToResponse::class,
+ StartSession::class,
];
}
}
diff --git a/app/Http/Requests/ActivityLog/ActivityLogIndexRequest.php b/app/Http/Requests/ActivityLog/ActivityLogIndexRequest.php
index 243fdc43..0b52df4d 100644
--- a/app/Http/Requests/ActivityLog/ActivityLogIndexRequest.php
+++ b/app/Http/Requests/ActivityLog/ActivityLogIndexRequest.php
@@ -4,6 +4,7 @@ namespace App\Http\Requests\ActivityLog;
use App\Enums\ActivityLogType;
use App\Extension\HookManager;
+use App\Models\User;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
@@ -33,7 +34,7 @@ class ActivityLogIndexRequest extends FormRequest
'log_type' => ['nullable', 'array'],
'log_type.*' => ['string', Rule::in(ActivityLogType::values())],
'action' => ['nullable', 'string', 'max:100'],
- 'user_id' => ['nullable', 'integer', Rule::exists('users', 'id')],
+ 'user_id' => ['nullable', 'integer', Rule::exists(User::class, 'id')],
'loggable_type' => ['nullable', 'string', 'max:255'],
'search' => ['nullable', 'string', 'max:255'],
'search_type' => ['nullable', 'string', Rule::in(['all', 'action', 'description', 'ip_address'])],
@@ -41,8 +42,15 @@ class ActivityLogIndexRequest extends FormRequest
'date_from' => ['nullable', 'date'],
'date_to' => ['nullable', 'date', 'after_or_equal:date_from'],
'per_page' => ['nullable', 'integer', 'min:1', 'max:100'],
+ // 게이트는 화면이 제공하는 정렬만 연다. ActivityLogRepository::SORTABLE_COLUMNS 는
+ // 이보다 넓게(id·user_id 포함) 두어, 확장이 이 규칙을 훅으로 넓혔을 때 저장소가
+ // 조용히 기본 정렬로 되돌리지 않도록 한다 (service-repository.md "정렬 컬럼 화이트리스트").
'sort_by' => ['nullable', 'string', Rule::in(['created_at', 'action', 'log_type'])],
'sort_order' => ['nullable', 'string', Rule::in(['asc', 'desc'])],
+ // 커서를 주면 목록이 키셋 방식으로 응답한다. 로그는 계속 쌓이기만 하므로 깊은
+ // 페이지를 OFFSET 으로 훑으면 건너뛸 행을 실제로 읽어야 한다.
+ // 형식이 깨진 값은 KeysetPaginator 가 첫 페이지로 되돌리므로 여기서는 길이만 본다.
+ 'cursor' => ['nullable', 'string', 'max:500'],
];
return HookManager::applyFilters('core.activity_log.index_validation_rules', $rules, $this);
diff --git a/app/Http/Requests/Admin/Identity/AdminIdentityMessageDefinitionIndexRequest.php b/app/Http/Requests/Admin/Identity/AdminIdentityMessageDefinitionIndexRequest.php
index 3d8ed7ec..b5a18f45 100644
--- a/app/Http/Requests/Admin/Identity/AdminIdentityMessageDefinitionIndexRequest.php
+++ b/app/Http/Requests/Admin/Identity/AdminIdentityMessageDefinitionIndexRequest.php
@@ -15,7 +15,7 @@ class AdminIdentityMessageDefinitionIndexRequest extends FormRequest
/**
* 권한 확인 (미들웨어에서 처리).
*
- * @return bool
+ * @return bool 항상 true (권한은 라우트 permission 미들웨어가 담당)
*/
public function authorize(): bool
{
@@ -25,7 +25,7 @@ class AdminIdentityMessageDefinitionIndexRequest extends FormRequest
/**
* 검증 규칙.
*
- * @return array
+ * @return array 검증 규칙 배열
*/
public function rules(): array
{
@@ -50,7 +50,7 @@ class AdminIdentityMessageDefinitionIndexRequest extends FormRequest
];
return HookManager::applyFilters(
- 'core.identity.message_definition.filter_index_rules',
+ 'core.identity.message_definition.index_validation_rules',
$rules
);
}
@@ -58,7 +58,7 @@ class AdminIdentityMessageDefinitionIndexRequest extends FormRequest
/**
* 검증 메시지.
*
- * @return array
+ * @return array 검증 오류 메시지 배열
*/
public function messages(): array
{
diff --git a/app/Http/Requests/Admin/Identity/StoreIdentityMessageDefinitionRequest.php b/app/Http/Requests/Admin/Identity/StoreIdentityMessageDefinitionRequest.php
index d8c18ab0..1b798cf4 100644
--- a/app/Http/Requests/Admin/Identity/StoreIdentityMessageDefinitionRequest.php
+++ b/app/Http/Requests/Admin/Identity/StoreIdentityMessageDefinitionRequest.php
@@ -27,7 +27,7 @@ class StoreIdentityMessageDefinitionRequest extends FormRequest
/**
* 라우트 permission 미들웨어가 담당하므로 true 고정.
*
- * @return bool
+ * @return bool 항상 true (권한은 라우트 permission 미들웨어가 담당)
*/
public function authorize(): bool
{
@@ -37,7 +37,7 @@ class StoreIdentityMessageDefinitionRequest extends FormRequest
/**
* 검증 규칙을 반환합니다.
*
- * @return array
+ * @return array 검증 규칙 배열
*/
public function rules(): array
{
@@ -65,15 +65,13 @@ class StoreIdentityMessageDefinitionRequest extends FormRequest
];
return HookManager::applyFilters(
- 'core.identity.message_definition.filter_store_rules',
+ 'core.identity.message_definition.store_validation_rules',
$rules,
);
}
/**
* provider_id 가 등록된 IDV 프로바이더인지 확인하는 closure 룰.
- *
- * @return Closure
*/
protected function providerExistsRule(): Closure
{
@@ -91,8 +89,6 @@ class StoreIdentityMessageDefinitionRequest extends FormRequest
/**
* scope_value 가 source_type='admin' 인 IdentityPolicy.key 와 일치하는지 확인.
- *
- * @return Closure
*/
protected function adminPolicyKeyRule(): Closure
{
@@ -113,8 +109,6 @@ class StoreIdentityMessageDefinitionRequest extends FormRequest
/**
* (provider_id, scope_type, scope_value) 조합 중복 검사.
- *
- * @return Closure
*/
protected function scopeUniqueRule(): Closure
{
diff --git a/app/Http/Requests/Admin/Identity/UpdateIdentityMessageDefinitionRequest.php b/app/Http/Requests/Admin/Identity/UpdateIdentityMessageDefinitionRequest.php
index 05b343bb..e2d63ead 100644
--- a/app/Http/Requests/Admin/Identity/UpdateIdentityMessageDefinitionRequest.php
+++ b/app/Http/Requests/Admin/Identity/UpdateIdentityMessageDefinitionRequest.php
@@ -18,7 +18,7 @@ class UpdateIdentityMessageDefinitionRequest extends FormRequest
/**
* 권한 확인 (미들웨어에서 처리).
*
- * @return bool
+ * @return bool 항상 true (권한은 미들웨어에서 검증)
*/
public function authorize(): bool
{
@@ -28,20 +28,22 @@ class UpdateIdentityMessageDefinitionRequest extends FormRequest
/**
* 검증 규칙.
*
- * @return array
+ * @return array 필드별 검증 규칙
*/
public function rules(): array
{
$rules = [
'name' => ['sometimes', 'array', new LocaleRequiredTranslatable(maxLength: 200)],
'description' => ['sometimes', 'nullable', 'array', new TranslatableField(maxLength: 1000)],
+ // audit:allow formrequest-sometimes-array-min-inert reason: 채널 0개는 유효한 상태가 아니다.
+ // 발송 채널을 모두 해제하면 본인인증 메시지가 전달되지 않으므로 오류를 노출하는 것이 올바른 동작이다.
'channels' => ['sometimes', 'array', 'min:1'],
'channels.*' => ['string', 'max:20'],
'is_active' => ['sometimes', 'boolean'],
];
return HookManager::applyFilters(
- 'core.identity.message_definition.filter_update_rules',
+ 'core.identity.message_definition.update_validation_rules',
$rules,
$this->route('definition')
);
diff --git a/app/Http/Requests/Admin/Identity/UpdateIdentityMessageTemplateRequest.php b/app/Http/Requests/Admin/Identity/UpdateIdentityMessageTemplateRequest.php
index 8330b484..e7856459 100644
--- a/app/Http/Requests/Admin/Identity/UpdateIdentityMessageTemplateRequest.php
+++ b/app/Http/Requests/Admin/Identity/UpdateIdentityMessageTemplateRequest.php
@@ -18,7 +18,7 @@ class UpdateIdentityMessageTemplateRequest extends FormRequest
/**
* 권한 확인 (미들웨어에서 처리).
*
- * @return bool
+ * @return bool 항상 true (권한은 라우트 permission 미들웨어가 담당)
*/
public function authorize(): bool
{
@@ -28,7 +28,7 @@ class UpdateIdentityMessageTemplateRequest extends FormRequest
/**
* 검증 규칙.
*
- * @return array
+ * @return array 검증 규칙 배열
*/
public function rules(): array
{
@@ -39,7 +39,7 @@ class UpdateIdentityMessageTemplateRequest extends FormRequest
];
return HookManager::applyFilters(
- 'core.identity.message_template.filter_update_rules',
+ 'core.identity.message_template.update_validation_rules',
$rules,
$this->route('template')
);
diff --git a/app/Http/Requests/Admin/LayoutVersionListRequest.php b/app/Http/Requests/Admin/LayoutVersionListRequest.php
new file mode 100644
index 00000000..d4b7afbc
--- /dev/null
+++ b/app/Http/Requests/Admin/LayoutVersionListRequest.php
@@ -0,0 +1,61 @@
+ 검증 규칙
+ */
+ public function rules(): array
+ {
+ $rules = [
+ 'limit' => ['nullable', 'integer', 'min:1', 'max:'.self::MAX_LIMIT],
+ ];
+
+ // 모듈/플러그인이 목록 조회 파라미터를 확장할 수 있도록 훅을 노출한다
+ return HookManager::applyFilters('core.layout_version.list_validation_rules', $rules, $this);
+ }
+
+ /**
+ * 검증 오류 메시지 커스터마이징
+ *
+ * @return array 오류 메시지
+ */
+ public function messages(): array
+ {
+ return [
+ 'limit.integer' => __('validation.layout_version.limit.integer'),
+ 'limit.min' => __('validation.layout_version.limit.min'),
+ 'limit.max' => __('validation.layout_version.limit.max', ['max' => self::MAX_LIMIT]),
+ ];
+ }
+}
diff --git a/app/Http/Requests/Admin/UpdatePluginSettingsRequest.php b/app/Http/Requests/Admin/UpdatePluginSettingsRequest.php
index 3cd0a073..2b25a1e6 100644
--- a/app/Http/Requests/Admin/UpdatePluginSettingsRequest.php
+++ b/app/Http/Requests/Admin/UpdatePluginSettingsRequest.php
@@ -106,7 +106,21 @@ class UpdatePluginSettingsRequest extends FormRequest
$rules[$field] = $fieldRules;
}
- return HookManager::applyFilters('core.plugin_settings.update_rules', $rules, $identifier);
+ // 표준 이름(`core.{대상}.{동작}_validation_rules`)으로 발행하되, 이미 공개돼 구독 중일 수 있는
+ // 구 이름(`core.plugin_settings.update_rules`)도 함께 발행한다 — 구 이름을 구독하는 제3자
+ // 확장이 조용히 멈추지 않도록 한다. 구 이름은 구독자가 있을 때만 1회 경고가 남는다.
+ //
+ // 3번째 인자로 이번 요청의 입력값을 함께 넘긴다. 확장이 "현재 입력한 모드에 따라
+ // 다른 필드를 필수로 만드는" 조건부 규칙을 만들려면 입력값이 필요한데, 그것이 없어
+ // 확장이 request() 를 직접 들여다보던 것을 없애기 위함이다.
+ // 기존 2인자 구독자는 그대로 동작한다(초과 인자는 무시된다).
+ return HookManager::applyFiltersWithLegacyName(
+ 'core.plugin_settings.update_validation_rules',
+ 'core.plugin_settings.update_rules',
+ $rules,
+ $identifier,
+ $this->all(),
+ );
}
/**
diff --git a/app/Http/Requests/Attachment/UploadAttachmentRequest.php b/app/Http/Requests/Attachment/UploadAttachmentRequest.php
index 88bdc844..0acb70f7 100644
--- a/app/Http/Requests/Attachment/UploadAttachmentRequest.php
+++ b/app/Http/Requests/Attachment/UploadAttachmentRequest.php
@@ -29,10 +29,18 @@ class UploadAttachmentRequest extends FormRequest
*/
public function rules(): array
{
- $maxSize = config('attachment.max_size', 10) * 1024; // MB to KB
+ // config/attachment.max_file_size 는 KB 단위 (관리자 설정 MB → KB 변환은 SettingsServiceProvider 담당)
+ $maxSize = (int) config('attachment.max_file_size', 10240);
+ $extensions = $this->allowedExtensions();
+
+ $fileRules = ['required', 'file', 'max:'.$maxSize];
+ // 목록이 비면 확장자 제한 없음 (탈출구) — 빈 규칙을 붙이면 전 파일이 거부된다
+ if ($extensions !== []) {
+ $fileRules[] = 'extensions:'.implode(',', $extensions);
+ }
$rules = [
- 'file' => ['required', 'file', 'max:' . $maxSize],
+ 'file' => $fileRules,
'attachmentable_type' => ['nullable', 'string', 'max:255'],
'attachmentable_id' => ['nullable', 'integer', 'min:1'],
'collection' => ['sometimes', 'string', 'max:100'],
@@ -54,7 +62,8 @@ class UploadAttachmentRequest extends FormRequest
return [
'file.required' => __('attachment.validation.file_required'),
'file.file' => __('attachment.validation.file_invalid'),
- 'file.max' => __('attachment.validation.file_max', ['max' => config('attachment.max_size', 10)]),
+ 'file.max' => __('attachment.validation.file_max', ['max' => (int) config('attachment.max_file_size', 10240) / 1024]),
+ 'file.extensions' => __('attachment.validation.file_extension_invalid', ['extensions' => implode(', ', $this->allowedExtensions())]),
'attachmentable_type.string' => __('attachment.validation.type_invalid'),
'attachmentable_id.integer' => __('attachment.validation.id_invalid'),
];
@@ -62,8 +71,6 @@ class UploadAttachmentRequest extends FormRequest
/**
* 검증 전 데이터 준비
- *
- * @return void
*/
protected function prepareForValidation(): void
{
@@ -72,4 +79,25 @@ class UploadAttachmentRequest extends FormRequest
'source_type' => $this->source_type ?? AttachmentSourceType::Core->value,
]);
}
+
+ /**
+ * 허용 확장자 목록을 반환합니다 (소문자 정규화 + 확장 훅 적용).
+ *
+ * 빈 배열은 "확장자 제한 없음" 을 의미합니다.
+ *
+ * @return array 허용 확장자 목록
+ */
+ protected function allowedExtensions(): array
+ {
+ $extensions = (array) config('attachment.allowed_extensions', []);
+
+ $extensions = array_values(array_filter(array_map(
+ static fn ($ext) => strtolower(trim(ltrim((string) $ext, '.'))),
+ $extensions
+ )));
+
+ return array_values(array_unique(
+ (array) HookManager::applyFilters('core.attachment.allowed_extensions', $extensions, $this)
+ ));
+ }
}
diff --git a/app/Http/Requests/Attachment/UploadBatchAttachmentRequest.php b/app/Http/Requests/Attachment/UploadBatchAttachmentRequest.php
index 32af6a4b..ef985e99 100644
--- a/app/Http/Requests/Attachment/UploadBatchAttachmentRequest.php
+++ b/app/Http/Requests/Attachment/UploadBatchAttachmentRequest.php
@@ -29,11 +29,19 @@ class UploadBatchAttachmentRequest extends FormRequest
*/
public function rules(): array
{
- $maxSize = config('attachment.max_size', 10) * 1024; // MB to KB
+ // config/attachment.max_file_size 는 KB 단위 (관리자 설정 MB → KB 변환은 SettingsServiceProvider 담당)
+ $maxSize = (int) config('attachment.max_file_size', 10240);
+ $extensions = $this->allowedExtensions();
+
+ $fileRules = ['file', 'max:'.$maxSize];
+ // 목록이 비면 확장자 제한 없음 (탈출구) — 빈 규칙을 붙이면 전 파일이 거부된다
+ if ($extensions !== []) {
+ $fileRules[] = 'extensions:'.implode(',', $extensions);
+ }
$rules = [
'files' => ['required', 'array', 'min:1'],
- 'files.*' => ['file', 'max:' . $maxSize],
+ 'files.*' => $fileRules,
'attachmentable_type' => ['nullable', 'string', 'max:255'],
'attachmentable_id' => ['nullable', 'integer', 'min:1'],
'collection' => ['sometimes', 'string', 'max:100'],
@@ -57,7 +65,8 @@ class UploadBatchAttachmentRequest extends FormRequest
'files.array' => __('attachment.validation.files_array'),
'files.min' => __('attachment.validation.files_min'),
'files.*.file' => __('attachment.validation.file_invalid'),
- 'files.*.max' => __('attachment.validation.file_max', ['max' => config('attachment.max_size', 10)]),
+ 'files.*.max' => __('attachment.validation.file_max', ['max' => (int) config('attachment.max_file_size', 10240) / 1024]),
+ 'files.*.extensions' => __('attachment.validation.file_extension_invalid', ['extensions' => implode(', ', $this->allowedExtensions())]),
'attachmentable_type.string' => __('attachment.validation.type_invalid'),
'attachmentable_id.integer' => __('attachment.validation.id_invalid'),
];
@@ -65,8 +74,6 @@ class UploadBatchAttachmentRequest extends FormRequest
/**
* 검증 전 데이터 준비
- *
- * @return void
*/
protected function prepareForValidation(): void
{
@@ -75,4 +82,25 @@ class UploadBatchAttachmentRequest extends FormRequest
'source_type' => $this->source_type ?? AttachmentSourceType::Core->value,
]);
}
+
+ /**
+ * 허용 확장자 목록을 반환합니다 (소문자 정규화 + 확장 훅 적용).
+ *
+ * 빈 배열은 "확장자 제한 없음" 을 의미합니다.
+ *
+ * @return array 허용 확장자 목록
+ */
+ protected function allowedExtensions(): array
+ {
+ $extensions = (array) config('attachment.allowed_extensions', []);
+
+ $extensions = array_values(array_filter(array_map(
+ static fn ($ext) => strtolower(trim(ltrim((string) $ext, '.'))),
+ $extensions
+ )));
+
+ return array_values(array_unique(
+ (array) HookManager::applyFilters('core.attachment.allowed_extensions', $extensions, $this)
+ ));
+ }
}
diff --git a/app/Http/Requests/Auth/AuthenticatedRequest.php b/app/Http/Requests/Auth/AuthenticatedRequest.php
new file mode 100644
index 00000000..6d67f246
--- /dev/null
+++ b/app/Http/Requests/Auth/AuthenticatedRequest.php
@@ -0,0 +1,38 @@
+ 빈 배열 (본문 입력 없음)
+ */
+ public function rules(): array
+ {
+ return [];
+ }
+}
diff --git a/app/Http/Requests/Auth/LoginRequest.php b/app/Http/Requests/Auth/LoginRequest.php
index 2926d4a8..aed4f22b 100644
--- a/app/Http/Requests/Auth/LoginRequest.php
+++ b/app/Http/Requests/Auth/LoginRequest.php
@@ -3,12 +3,15 @@
namespace App\Http\Requests\Auth;
use App\Extension\HookManager;
+use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Foundation\Http\FormRequest;
class LoginRequest extends FormRequest
{
/**
* Determine if the user is authorized to make this request.
+ *
+ * @return bool 항상 true (권한은 미들웨어에서 검증)
*/
public function authorize(): bool
{
@@ -18,13 +21,15 @@ class LoginRequest extends FormRequest
/**
* Get the validation rules that apply to the request.
*
- * @return array|string>
+ * @return array|string>
*/
public function rules(): array
{
$rules = [
'email' => 'required|email',
- 'password' => 'required|string|min:6',
+ // 로그인은 기존 비밀번호를 대조하는 행위이지 새 정책을 강제하는 지점이 아니다.
+ // 길이 규칙을 두면 정책 미달 비밀번호에 422 를 주어 미인증 공격자에게 그 사실을 누설한다.
+ 'password' => 'required|string',
];
// 모듈/플러그인이 validation rules를 동적으로 추가할 수 있도록 훅 제공
@@ -42,7 +47,6 @@ class LoginRequest extends FormRequest
'email.required' => __('validation.auth.email.required'),
'email.email' => __('validation.auth.email.email'),
'password.required' => __('validation.auth.password.required'),
- 'password.min' => __('validation.auth.password.min'),
];
}
}
diff --git a/app/Http/Requests/Auth/RegisterRequest.php b/app/Http/Requests/Auth/RegisterRequest.php
index 31e8e6bb..5e119ba9 100644
--- a/app/Http/Requests/Auth/RegisterRequest.php
+++ b/app/Http/Requests/Auth/RegisterRequest.php
@@ -4,6 +4,8 @@ namespace App\Http\Requests\Auth;
use App\Extension\HookManager;
use App\Models\User;
+use App\Rules\PasswordPolicy;
+use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
@@ -11,6 +13,8 @@ class RegisterRequest extends FormRequest
{
/**
* Determine if the user is authorized to make this request.
+ *
+ * @return bool 항상 true (권한은 미들웨어 체인에서 처리)
*/
public function authorize(): bool
{
@@ -20,7 +24,7 @@ class RegisterRequest extends FormRequest
/**
* Get the validation rules that apply to the request.
*
- * @return array|string>
+ * @return array|string>
*/
public function rules(): array
{
@@ -28,8 +32,10 @@ class RegisterRequest extends FormRequest
'name' => 'required|string|max:255',
'nickname' => 'nullable|string|max:50',
'email' => ['required', 'string', 'email', 'max:255', Rule::unique(User::class)],
- 'password' => 'required|string|min:8|confirmed',
- 'language' => 'nullable|string|in:' . implode(',', config('app.supported_locales', ['ko', 'en'])),
+ 'password' => ['required', 'string', 'confirmed', PasswordPolicy::rule()],
+ 'mobile' => ['nullable', 'string', 'max:20', 'regex:/^[0-9\-\+\(\)\s]+$/'],
+ 'phone' => ['nullable', 'string', 'max:20', 'regex:/^[0-9\-\+\(\)\s]+$/'],
+ 'language' => 'nullable|string|in:'.implode(',', config('app.supported_locales', ['ko', 'en'])),
'agree_terms' => 'accepted',
'agree_privacy' => 'accepted',
];
@@ -55,6 +61,10 @@ class RegisterRequest extends FormRequest
'password.required' => __('validation.auth.password.required'),
'password.min' => __('validation.auth.password.min'),
'password.confirmed' => __('validation.auth.password.confirmed'),
+ 'mobile.max' => __('validation.auth.mobile.max'),
+ 'mobile.regex' => __('validation.auth.mobile.regex'),
+ 'phone.max' => __('validation.auth.phone.max'),
+ 'phone.regex' => __('validation.auth.phone.regex'),
'agree_terms.accepted' => __('validation.auth.agree_terms.accepted'),
'agree_privacy.accepted' => __('validation.auth.agree_privacy.accepted'),
];
diff --git a/app/Http/Requests/Auth/ResetPasswordRequest.php b/app/Http/Requests/Auth/ResetPasswordRequest.php
index 8975ec1a..4f83b208 100644
--- a/app/Http/Requests/Auth/ResetPasswordRequest.php
+++ b/app/Http/Requests/Auth/ResetPasswordRequest.php
@@ -4,6 +4,8 @@ namespace App\Http\Requests\Auth;
use App\Extension\HookManager;
use App\Models\User;
+use App\Rules\PasswordPolicy;
+use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
@@ -11,6 +13,8 @@ class ResetPasswordRequest extends FormRequest
{
/**
* Determine if the user is authorized to make this request.
+ *
+ * @return bool 항상 true (권한은 미들웨어에서 검증)
*/
public function authorize(): bool
{
@@ -20,14 +24,14 @@ class ResetPasswordRequest extends FormRequest
/**
* Get the validation rules that apply to the request.
*
- * @return array|string>
+ * @return array|string>
*/
public function rules(): array
{
$rules = [
'token' => 'required|string',
'email' => ['required', 'email', Rule::exists(User::class, 'email')],
- 'password' => 'required|string|min:8|confirmed',
+ 'password' => ['required', 'string', 'confirmed', PasswordPolicy::rule()],
];
// 모듈/플러그인이 validation rules를 동적으로 추가할 수 있도록 훅 제공
diff --git a/app/Http/Requests/Auth/TwoFactorChallengeRequest.php b/app/Http/Requests/Auth/TwoFactorChallengeRequest.php
new file mode 100644
index 00000000..f1043207
--- /dev/null
+++ b/app/Http/Requests/Auth/TwoFactorChallengeRequest.php
@@ -0,0 +1,58 @@
+ 검증 규칙
+ */
+ public function rules(): array
+ {
+ $rules = [
+ 'challenge_id' => ['required', 'string', 'uuid'],
+ // 코드 자리수는 프로바이더 설정에 따라 달라지므로 상·하한만 느슨하게 두고
+ // 정확한 일치 판정은 프로바이더가 수행한다.
+ 'code' => ['required', 'string', 'min:4', 'max:16'],
+ ];
+
+ // 확장이 자체 2단계 수단(앱 OTP·SMS 등)을 붙일 때 입력 필드를 추가할 수 있도록 개방한다
+ return HookManager::applyFilters('core.auth.two_factor_validation_rules', $rules, $this);
+ }
+
+ /**
+ * 검증 실패 메시지를 반환합니다.
+ *
+ * @return array 검증 메시지
+ */
+ public function messages(): array
+ {
+ return [
+ 'challenge_id.required' => __('validation.auth.two_factor.challenge_required'),
+ 'challenge_id.uuid' => __('validation.auth.two_factor.challenge_invalid'),
+ 'code.required' => __('validation.auth.two_factor.code_required'),
+ ];
+ }
+}
diff --git a/app/Http/Requests/Auth/ValidateResetTokenRequest.php b/app/Http/Requests/Auth/ValidateResetTokenRequest.php
index 7a4cd8a9..531799eb 100644
--- a/app/Http/Requests/Auth/ValidateResetTokenRequest.php
+++ b/app/Http/Requests/Auth/ValidateResetTokenRequest.php
@@ -13,11 +13,13 @@ class ValidateResetTokenRequest extends FormRequest
/**
* Determine if the user is authorized to make this request.
*
+ * 공개 엔드포인트이므로 항상 통과시킨다 — 접근 제어는 미들웨어가 담당한다.
+ *
* @return bool
*/
public function authorize(): bool
{
- return true; // 공개 엔드포인트
+ return true;
}
/**
@@ -32,7 +34,8 @@ class ValidateResetTokenRequest extends FormRequest
'email' => 'required|email',
];
- return HookManager::applyFilters(
+ return HookManager::applyFiltersWithLegacyName(
+ 'core.auth.validate_reset_token_validation_rules',
'core.auth.validate_reset_token_rules',
$rules,
$this
diff --git a/app/Http/Requests/Auth/VerifyPasswordRequest.php b/app/Http/Requests/Auth/VerifyPasswordRequest.php
index 578b4470..fb30c3fc 100644
--- a/app/Http/Requests/Auth/VerifyPasswordRequest.php
+++ b/app/Http/Requests/Auth/VerifyPasswordRequest.php
@@ -9,6 +9,8 @@ class VerifyPasswordRequest extends FormRequest
{
/**
* Determine if the user is authorized to make this request.
+ *
+ * @return bool
*/
public function authorize(): bool
{
@@ -27,6 +29,9 @@ class VerifyPasswordRequest extends FormRequest
];
// 모듈/플러그인이 validation rules를 동적으로 추가할 수 있도록 훅 제공
- return HookManager::applyFilters('core.auth.verify_password_rules', $rules);
+ return HookManager::applyFiltersWithLegacyName(
+ 'core.auth.verify_password_validation_rules',
+ 'core.auth.verify_password_rules',
+ $rules);
}
}
diff --git a/app/Http/Requests/Extension/ChangelogRequest.php b/app/Http/Requests/Extension/ChangelogRequest.php
index 4bf6da1e..89cd72e1 100644
--- a/app/Http/Requests/Extension/ChangelogRequest.php
+++ b/app/Http/Requests/Extension/ChangelogRequest.php
@@ -14,6 +14,8 @@ class ChangelogRequest extends FormRequest
{
/**
* Determine if the user is authorized to make this request.
+ *
+ * @return bool
*/
public function authorize(): bool
{
@@ -33,7 +35,10 @@ class ChangelogRequest extends FormRequest
'to_version' => 'nullable|string|regex:/^\d+\.\d+\.\d+(-[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*)?$/|required_with:from_version',
];
- return HookManager::applyFilters('core.extension.changelog_rules', $rules);
+ return HookManager::applyFiltersWithLegacyName(
+ 'core.extension.changelog_validation_rules',
+ 'core.extension.changelog_rules',
+ $rules);
}
/**
diff --git a/app/Http/Requests/Identity/AdminIdentityProviderIndexRequest.php b/app/Http/Requests/Identity/AdminIdentityProviderIndexRequest.php
new file mode 100644
index 00000000..514f1788
--- /dev/null
+++ b/app/Http/Requests/Identity/AdminIdentityProviderIndexRequest.php
@@ -0,0 +1,38 @@
+> 검증 규칙 (요청 파라미터 없음)
+ */
+ public function rules(): array
+ {
+ return [];
+ }
+}
diff --git a/app/Http/Requests/Identity/PurposesIndexRequest.php b/app/Http/Requests/Identity/PurposesIndexRequest.php
index f17ff486..1d937e55 100644
--- a/app/Http/Requests/Identity/PurposesIndexRequest.php
+++ b/app/Http/Requests/Identity/PurposesIndexRequest.php
@@ -7,14 +7,14 @@ use Illuminate\Foundation\Http\FormRequest;
/**
* 등록된 IDV purpose 목록 조회 요청 (GET /api/identity/purposes).
*
- * 코어 4종 + 활성 모듈/플러그인 declarative purpose + filter 훅 확장 결과를 반환.
+ * 코어 5종 + 활성 모듈/플러그인 declarative purpose + filter 훅 확장 결과를 반환.
*/
class PurposesIndexRequest extends FormRequest
{
/**
* 요청 권한 — 공개 엔드포인트.
*
- * @return bool
+ * @return bool 항상 true (인증 불필요)
*/
public function authorize(): bool
{
diff --git a/app/Http/Requests/LanguagePack/InstallFromBundledRequest.php b/app/Http/Requests/LanguagePack/InstallFromBundledRequest.php
index 73ce0a83..bdee367c 100644
--- a/app/Http/Requests/LanguagePack/InstallFromBundledRequest.php
+++ b/app/Http/Requests/LanguagePack/InstallFromBundledRequest.php
@@ -2,6 +2,8 @@
namespace App\Http\Requests\LanguagePack;
+use App\Extension\HookManager;
+use App\Rules\LanguagePack\RequiresActivationPermission;
use Illuminate\Foundation\Http\FormRequest;
/**
@@ -29,15 +31,27 @@ class InstallFromBundledRequest extends FormRequest
*/
public function rules(): array
{
- return [
+ $rules = [
'identifier' => [
'required',
'string',
'max:200',
'regex:/^[a-zA-Z0-9._\-]+$/',
],
- 'auto_activate' => ['nullable', 'boolean'],
+ /*
+ * 외부 소스(파일·URL·GitHub)와 동일하게 활성화 권한 게이트를 건다 (PO 결정, 2026-08-04).
+ * 설치(install)와 활성화(manage)를 별도 권한으로 두는 정책을 네 경로 전부에 같은 강도로
+ * 적용해, "어느 경로로 들어오느냐" 가 권한 경계를 바꾸지 않게 한다.
+ *
+ * 부수 효과: 관리자 화면에서 auto_activate 를 보내는 곳이 번들 재설치 모달 하나뿐이므로,
+ * 설치 권한만 가진 운영자가 활성 팩을 재설치하면 그 팩이 installed 로 내려간다.
+ * 다시 켜려면 언어팩 관리 권한이 필요하다 — 의도된 동작이다.
+ */
+ 'auto_activate' => ['nullable', 'boolean', new RequiresActivationPermission],
];
+
+ // 모듈/플러그인이 validation rules 를 동적으로 추가할 수 있도록 훅 제공
+ return HookManager::applyFilters('core.language_packs.install_from_bundled_validation_rules', $rules, $this);
}
/**
diff --git a/app/Http/Requests/LanguagePack/InstallFromFileRequest.php b/app/Http/Requests/LanguagePack/InstallFromFileRequest.php
index 3545275f..38d282da 100644
--- a/app/Http/Requests/LanguagePack/InstallFromFileRequest.php
+++ b/app/Http/Requests/LanguagePack/InstallFromFileRequest.php
@@ -2,6 +2,8 @@
namespace App\Http\Requests\LanguagePack;
+use App\Extension\HookManager;
+use App\Rules\LanguagePack\RequiresActivationPermission;
use Illuminate\Foundation\Http\FormRequest;
/**
@@ -26,10 +28,14 @@ class InstallFromFileRequest extends FormRequest
*/
public function rules(): array
{
- return [
+ $rules = [
'file' => ['required', 'file', 'max:10240', 'mimetypes:application/zip,application/x-zip-compressed,application/octet-stream'],
- 'auto_activate' => ['nullable', 'boolean'],
+ // 설치 권한만으로 활성화까지 수행하지 못하게 한다 — 활성 팩만 require 경로에 배선된다.
+ 'auto_activate' => ['nullable', 'boolean', new RequiresActivationPermission],
];
+
+ // 모듈/플러그인이 validation rules 를 동적으로 추가할 수 있도록 훅 제공
+ return HookManager::applyFilters('core.language_packs.install_from_file_validation_rules', $rules, $this);
}
/**
diff --git a/app/Http/Requests/LanguagePack/InstallFromGithubRequest.php b/app/Http/Requests/LanguagePack/InstallFromGithubRequest.php
index fd0b3b1e..2e5595cd 100644
--- a/app/Http/Requests/LanguagePack/InstallFromGithubRequest.php
+++ b/app/Http/Requests/LanguagePack/InstallFromGithubRequest.php
@@ -2,6 +2,8 @@
namespace App\Http\Requests\LanguagePack;
+use App\Extension\HookManager;
+use App\Rules\LanguagePack\RequiresActivationPermission;
use Illuminate\Foundation\Http\FormRequest;
/**
@@ -26,14 +28,18 @@ class InstallFromGithubRequest extends FormRequest
*/
public function rules(): array
{
- return [
+ $rules = [
'github_url' => [
'required',
'url',
'regex:/^https?:\/\/(www\.)?github\.com\/[a-zA-Z0-9\-_]+\/[a-zA-Z0-9\-_]+\/?$/',
],
- 'auto_activate' => ['nullable', 'boolean'],
+ // 설치 권한만으로 활성화까지 수행하지 못하게 한다 — 활성 팩만 require 경로에 배선된다.
+ 'auto_activate' => ['nullable', 'boolean', new RequiresActivationPermission],
];
+
+ // 모듈/플러그인이 validation rules 를 동적으로 추가할 수 있도록 훅 제공
+ return HookManager::applyFilters('core.language_packs.install_from_github_validation_rules', $rules, $this);
}
/**
diff --git a/app/Http/Requests/LanguagePack/InstallFromUrlRequest.php b/app/Http/Requests/LanguagePack/InstallFromUrlRequest.php
index 47549fdb..c0bde012 100644
--- a/app/Http/Requests/LanguagePack/InstallFromUrlRequest.php
+++ b/app/Http/Requests/LanguagePack/InstallFromUrlRequest.php
@@ -3,6 +3,7 @@
namespace App\Http\Requests\LanguagePack;
use App\Extension\HookManager;
+use App\Rules\LanguagePack\RequiresActivationPermission;
use App\Rules\PublicOutboundUrl;
use Illuminate\Foundation\Http\FormRequest;
@@ -32,7 +33,8 @@ class InstallFromUrlRequest extends FormRequest
// 원격 코드를 내려받는 지점이므로 https 고정 + 내부 주소 허용 설정과 무관하게 항상 차단
'url' => ['required', 'url', 'max:500', new PublicOutboundUrl(schemes: ['https'], allowInternalOptIn: false)],
'checksum' => ['nullable', 'string', 'regex:/^[a-f0-9]{64}$/i'],
- 'auto_activate' => ['nullable', 'boolean'],
+ // 설치 권한만으로 활성화까지 수행하지 못하게 한다 — 활성 팩만 require 경로에 배선된다.
+ 'auto_activate' => ['nullable', 'boolean', new RequiresActivationPermission],
];
// 모듈/플러그인이 validation rules 를 동적으로 추가할 수 있도록 훅 제공
diff --git a/app/Http/Requests/Menu/UpdateMenuRequest.php b/app/Http/Requests/Menu/UpdateMenuRequest.php
index 050dec58..46de4417 100644
--- a/app/Http/Requests/Menu/UpdateMenuRequest.php
+++ b/app/Http/Requests/Menu/UpdateMenuRequest.php
@@ -4,10 +4,10 @@ namespace App\Http\Requests\Menu;
use App\Extension\HookManager;
use App\Models\Menu;
-use App\Models\Module;
use App\Models\Role;
use App\Rules\LocaleRequiredTranslatable;
-use App\Rules\NotSelfParent;
+use App\Rules\NotCircularParent;
+use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
@@ -17,6 +17,8 @@ class UpdateMenuRequest extends FormRequest
* 사용자가 이 요청을 수행할 권한이 있는지 확인
*
* 권한 체크는 라우트의 permission 미들웨어에서 수행됩니다.
+ *
+ * @return bool 권한 검증 결과 (항상 true)
*/
public function authorize(): bool
{
@@ -26,7 +28,7 @@ class UpdateMenuRequest extends FormRequest
/**
* 요청에 적용할 검증 규칙
*
- * @return array|string>
+ * @return array|string>
*/
public function rules(): array
{
@@ -38,7 +40,9 @@ class UpdateMenuRequest extends FormRequest
'slug' => ['required', 'string', 'max:255', Rule::unique(Menu::class, 'slug')->ignore($menuId)],
'url' => 'nullable|string|max:500',
'icon' => 'nullable|string|max:100',
- 'parent_id' => ['nullable', 'integer', Rule::exists(Menu::class, 'id'), new NotSelfParent($menuId)],
+ // 순서 변경 엔드포인트(UpdateMenuOrderRequest)와 동일하게 자손 전체를 검사한다.
+ // NotCircularParent 생성자는 int non-nullable 이므로 $menuId 가 있을 때만 부착한다.
+ 'parent_id' => ['nullable', 'integer', Rule::exists(Menu::class, 'id')],
'order' => 'nullable|integer|min:0',
'is_active' => 'nullable|boolean',
'extension_type' => 'nullable|string|in:core,module,plugin',
@@ -47,6 +51,10 @@ class UpdateMenuRequest extends FormRequest
'roles.*' => ['integer', Rule::exists(Role::class, 'id')],
];
+ if ($menuId !== null) {
+ $rules['parent_id'][] = new NotCircularParent((int) $menuId);
+ }
+
// 모듈/플러그인이 validation rules를 동적으로 추가할 수 있도록 훅 제공
return HookManager::applyFilters('core.menu.update_validation_rules', $rules, $this);
}
diff --git a/app/Http/Requests/Module/PerformModuleUpdateRequest.php b/app/Http/Requests/Module/PerformModuleUpdateRequest.php
index 72dba137..f51e27a5 100644
--- a/app/Http/Requests/Module/PerformModuleUpdateRequest.php
+++ b/app/Http/Requests/Module/PerformModuleUpdateRequest.php
@@ -3,6 +3,7 @@
namespace App\Http\Requests\Module;
use App\Extension\HookManager;
+use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Foundation\Http\FormRequest;
/**
@@ -28,7 +29,7 @@ class PerformModuleUpdateRequest extends FormRequest
/**
* 요청에 적용할 검증 규칙
*
- * @return array|string>
+ * @return array|string>
*/
public function rules(): array
{
@@ -37,6 +38,8 @@ class PerformModuleUpdateRequest extends FormRequest
'vendor_mode' => ['nullable', 'string', 'in:auto,composer,bundled'],
// 코어 버전 비호환 강제 우회 플래그
'force' => ['nullable', 'boolean'],
+ // 업데이트 후 검색 인덱스 재생성 여부 — 인덱스 잠금·재색인 비용이 있어 기본은 미수행
+ 'rebuild_search_index' => ['nullable', 'boolean'],
];
return HookManager::applyFilters('core.module.perform_update_validation_rules', $rules, $this);
diff --git a/app/Http/Requests/Notification/NotificationBatchReadRequest.php b/app/Http/Requests/Notification/NotificationBatchReadRequest.php
index 4ac40f8f..3acd0159 100644
--- a/app/Http/Requests/Notification/NotificationBatchReadRequest.php
+++ b/app/Http/Requests/Notification/NotificationBatchReadRequest.php
@@ -9,6 +9,8 @@ class NotificationBatchReadRequest extends FormRequest
{
/**
* 권한 확인 (미들웨어에서 처리).
+ *
+ * @return bool 항상 true (권한은 라우트 permission 미들웨어가 담당)
*/
public function authorize(): bool
{
@@ -17,6 +19,8 @@ class NotificationBatchReadRequest extends FormRequest
/**
* 검증 규칙을 반환합니다.
+ *
+ * @return array 검증 규칙 배열
*/
public function rules(): array
{
@@ -26,7 +30,7 @@ class NotificationBatchReadRequest extends FormRequest
];
return HookManager::applyFilters(
- 'core.notification.filter_batch_read_rules',
+ 'core.notification.batch_read_validation_rules',
$rules
);
}
diff --git a/app/Http/Requests/Notification/NotificationIndexRequest.php b/app/Http/Requests/Notification/NotificationIndexRequest.php
index 69b0d15d..3ce47956 100644
--- a/app/Http/Requests/Notification/NotificationIndexRequest.php
+++ b/app/Http/Requests/Notification/NotificationIndexRequest.php
@@ -9,6 +9,8 @@ class NotificationIndexRequest extends FormRequest
{
/**
* 권한 확인 (미들웨어에서 처리).
+ *
+ * @return bool 항상 true (권한은 라우트 permission 미들웨어가 담당)
*/
public function authorize(): bool
{
@@ -17,6 +19,8 @@ class NotificationIndexRequest extends FormRequest
/**
* 검증 규칙을 반환합니다.
+ *
+ * @return array 검증 규칙 배열
*/
public function rules(): array
{
@@ -28,7 +32,7 @@ class NotificationIndexRequest extends FormRequest
];
return HookManager::applyFilters(
- 'core.notification.filter_index_rules',
+ 'core.notification.index_validation_rules',
$rules
);
}
diff --git a/app/Http/Requests/NotificationDefinition/NotificationDefinitionIndexRequest.php b/app/Http/Requests/NotificationDefinition/NotificationDefinitionIndexRequest.php
index 6a761835..c7b5e095 100644
--- a/app/Http/Requests/NotificationDefinition/NotificationDefinitionIndexRequest.php
+++ b/app/Http/Requests/NotificationDefinition/NotificationDefinitionIndexRequest.php
@@ -10,7 +10,7 @@ class NotificationDefinitionIndexRequest extends FormRequest
/**
* 권한 확인 (미들웨어에서 처리).
*
- * @return bool
+ * @return bool 항상 true (권한은 라우트 permission 미들웨어가 담당)
*/
public function authorize(): bool
{
@@ -20,7 +20,7 @@ class NotificationDefinitionIndexRequest extends FormRequest
/**
* 검증 규칙을 반환합니다.
*
- * @return array
+ * @return array 검증 규칙 배열
*/
public function rules(): array
{
@@ -29,6 +29,11 @@ class NotificationDefinitionIndexRequest extends FormRequest
'extension_type' => ['nullable', 'string', 'in:core,module,plugin'],
'extension_identifier' => ['nullable', 'string', 'max:100'],
'channel' => ['nullable', 'string', 'max:50'],
+ // 목록에 실을 템플릿을 한 채널로 좁힌다. `channel` 과 다르다 — `channel` 은 정의 행
+ // 자체를 거르지만(그 채널을 지원하지 않는 정의는 목록에서 사라진다), 이 값은 행은
+ // 그대로 두고 각 행에 딸려오는 템플릿만 좁힌다. 화면이 한 번에 한 채널만 그리므로
+ // 나머지 채널의 제목·본문은 전송할 이유가 없다.
+ 'template_channel' => ['nullable', 'string', 'max:50'],
'is_active' => ['nullable', 'boolean'],
'per_page' => ['nullable', 'integer', 'min:1', 'max:100'],
'sort_by' => ['nullable', 'string', 'in:id,type,extension_type,is_active,created_at,updated_at'],
@@ -36,7 +41,7 @@ class NotificationDefinitionIndexRequest extends FormRequest
];
return HookManager::applyFilters(
- 'core.notification_definition.filter_index_rules',
+ 'core.notification_definition.index_validation_rules',
$rules
);
}
@@ -44,7 +49,7 @@ class NotificationDefinitionIndexRequest extends FormRequest
/**
* 검증 메시지를 반환합니다.
*
- * @return array
+ * @return array 검증 오류 메시지 배열
*/
public function messages(): array
{
diff --git a/app/Http/Requests/NotificationDefinition/UpdateNotificationDefinitionRequest.php b/app/Http/Requests/NotificationDefinition/UpdateNotificationDefinitionRequest.php
index 4a9d4a5e..5c7815a9 100644
--- a/app/Http/Requests/NotificationDefinition/UpdateNotificationDefinitionRequest.php
+++ b/app/Http/Requests/NotificationDefinition/UpdateNotificationDefinitionRequest.php
@@ -2,7 +2,10 @@
namespace App\Http\Requests\NotificationDefinition;
+use App\Contracts\Repositories\NotificationDefinitionRepositoryInterface;
use App\Extension\HookManager;
+use App\Models\NotificationDefinition;
+use App\Rules\AvailableNotificationChannel;
use Illuminate\Foundation\Http\FormRequest;
class UpdateNotificationDefinitionRequest extends FormRequest
@@ -10,7 +13,7 @@ class UpdateNotificationDefinitionRequest extends FormRequest
/**
* 권한 확인 (미들웨어에서 처리).
*
- * @return bool
+ * @return bool 항상 true (권한은 미들웨어에서 검증)
*/
public function authorize(): bool
{
@@ -20,22 +23,47 @@ class UpdateNotificationDefinitionRequest extends FormRequest
/**
* 검증 규칙을 반환합니다.
*
- * @return array
+ * @return array 필드별 검증 규칙
*/
public function rules(): array
{
$rules = [
+ // audit:allow formrequest-sometimes-array-min-inert reason: 채널 0개는 유효한 상태가 아니다.
+ // 발송 채널을 모두 해제하면 알림이 사라지므로, 저장을 막고 오류를 노출하는 것이 올바른 동작이다.
'channels' => ['sometimes', 'array', 'min:1'],
- 'channels.*' => ['string', 'max:50'],
+ // 허용 채널 목록은 config + filter_available_channels 훅으로 런타임 결정되므로
+ // 요청 클래스에 하드코딩하지 않는다. 이미 저장된 채널은 통과시켜, 채널 제공
+ // 플러그인이 비활성화된 뒤에도 기존 레코드 수정이 막히지 않게 한다.
+ 'channels.*' => ['string', 'max:50', new AvailableNotificationChannel($this->persistedChannels())],
'hooks' => ['sometimes', 'array'],
'hooks.*' => ['string', 'max:255'],
'is_active' => ['sometimes', 'boolean'],
];
return HookManager::applyFilters(
- 'core.notification_definition.filter_update_rules',
+ 'core.notification_definition.update_validation_rules',
$rules,
$this->route('definition')
);
}
+
+ /**
+ * 수정 대상 알림 정의에 이미 저장되어 있는 채널 목록을 반환합니다.
+ *
+ * @return array 저장된 채널 식별자 목록
+ */
+ private function persistedChannels(): array
+ {
+ $definition = $this->route('definition');
+
+ if (! $definition instanceof NotificationDefinition) {
+ $definition = is_numeric($definition)
+ ? app(NotificationDefinitionRepositoryInterface::class)->findById((int) $definition)
+ : null;
+ }
+
+ $channels = $definition?->channels;
+
+ return is_array($channels) ? array_values(array_filter($channels, 'is_string')) : [];
+ }
}
diff --git a/app/Http/Requests/NotificationLog/NotificationLogIndexRequest.php b/app/Http/Requests/NotificationLog/NotificationLogIndexRequest.php
index 020c3070..ac691f3d 100644
--- a/app/Http/Requests/NotificationLog/NotificationLogIndexRequest.php
+++ b/app/Http/Requests/NotificationLog/NotificationLogIndexRequest.php
@@ -12,6 +12,8 @@ class NotificationLogIndexRequest extends FormRequest
{
/**
* 권한 확인 (미들웨어에서 처리).
+ *
+ * @return bool 항상 true (권한은 라우트 permission 미들웨어가 담당)
*/
public function authorize(): bool
{
@@ -20,6 +22,8 @@ class NotificationLogIndexRequest extends FormRequest
/**
* 검증 규칙을 반환합니다.
+ *
+ * @return array 검증 규칙 배열
*/
public function rules(): array
{
@@ -32,12 +36,18 @@ class NotificationLogIndexRequest extends FormRequest
'extension_type' => ['nullable', 'string', 'in:core,module,plugin'],
'status' => ['nullable', 'string', Rule::enum(NotificationLogStatus::class)],
'per_page' => ['nullable', 'integer', 'min:1', 'max:100'],
- 'sort_by' => ['nullable', 'string', 'in:id,channel,notification_type,status,sent_at,created_at'],
+ // 허용 집합은 NotificationLogRepository::SORTABLE_COLUMNS 와 동일해야 한다.
+ // 게이트가 더 좁으면 화면 정렬 셀렉트가 제공하는 옵션(수신자명순/제목순)이 422 로 막힌다.
+ 'sort_by' => ['nullable', 'string', 'in:id,channel,notification_type,status,sent_at,created_at,recipient_name,subject'],
'sort_order' => ['nullable', 'string', 'in:asc,desc'],
+ // 커서를 주면 목록이 키셋 방식으로 응답한다. 로그는 계속 쌓이기만 하므로 깊은
+ // 페이지를 OFFSET 으로 훑으면 건너뛸 행을 실제로 읽어야 한다.
+ // 형식이 깨진 값은 KeysetPaginator 가 첫 페이지로 되돌리므로 여기서는 길이만 본다.
+ 'cursor' => ['nullable', 'string', 'max:500'],
];
return HookManager::applyFilters(
- 'core.notification_log.filter_index_rules',
+ 'core.notification_log.index_validation_rules',
$rules
);
}
diff --git a/app/Http/Requests/NotificationTemplate/UpdateNotificationTemplateRequest.php b/app/Http/Requests/NotificationTemplate/UpdateNotificationTemplateRequest.php
index 286e8dc7..31f5f7f3 100644
--- a/app/Http/Requests/NotificationTemplate/UpdateNotificationTemplateRequest.php
+++ b/app/Http/Requests/NotificationTemplate/UpdateNotificationTemplateRequest.php
@@ -11,7 +11,7 @@ class UpdateNotificationTemplateRequest extends FormRequest
/**
* 권한 확인 (미들웨어에서 처리).
*
- * @return bool
+ * @return bool 항상 true (권한은 미들웨어에서 검증)
*/
public function authorize(): bool
{
@@ -21,12 +21,14 @@ class UpdateNotificationTemplateRequest extends FormRequest
/**
* 검증 규칙을 반환합니다.
*
- * @return array
+ * @return array 필드별 검증 규칙
*/
public function rules(): array
{
$rules = [
- 'subject' => ['required', 'array', new LocaleRequiredTranslatable(maxLength: 500)],
+ // subject 컬럼은 nullable 이다 (제목 개념이 없는 채널이 존재).
+ // 스키마와 정합하도록 미전송/null 을 허용한다.
+ 'subject' => ['sometimes', 'nullable', 'array', new LocaleRequiredTranslatable(maxLength: 500)],
'body' => ['required', 'array', new LocaleRequiredTranslatable(maxLength: 65535)],
'click_url' => ['nullable', 'string', 'max:500'],
'recipients' => ['sometimes', 'nullable', 'array'],
@@ -38,7 +40,7 @@ class UpdateNotificationTemplateRequest extends FormRequest
];
return HookManager::applyFilters(
- 'core.notification_template.filter_update_rules',
+ 'core.notification_template.update_validation_rules',
$rules,
$this->route('template')
);
@@ -47,7 +49,7 @@ class UpdateNotificationTemplateRequest extends FormRequest
/**
* 검증 메시지를 반환합니다.
*
- * @return array
+ * @return array 규칙별 오류 메시지
*/
public function messages(): array
{
diff --git a/app/Http/Requests/Plugin/PerformPluginUpdateRequest.php b/app/Http/Requests/Plugin/PerformPluginUpdateRequest.php
index 572ef5b4..df7ec969 100644
--- a/app/Http/Requests/Plugin/PerformPluginUpdateRequest.php
+++ b/app/Http/Requests/Plugin/PerformPluginUpdateRequest.php
@@ -3,6 +3,7 @@
namespace App\Http\Requests\Plugin;
use App\Extension\HookManager;
+use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Foundation\Http\FormRequest;
/**
@@ -28,7 +29,7 @@ class PerformPluginUpdateRequest extends FormRequest
/**
* 요청에 적용할 검증 규칙
*
- * @return array|string>
+ * @return array|string>
*/
public function rules(): array
{
@@ -37,6 +38,8 @@ class PerformPluginUpdateRequest extends FormRequest
'vendor_mode' => ['nullable', 'string', 'in:auto,composer,bundled'],
// 코어 버전 비호환 강제 우회 플래그 (위험 인지 후 사용자 명시 필요)
'force' => ['nullable', 'boolean'],
+ // 업데이트 후 검색 인덱스 재생성 여부 — 인덱스 잠금·재색인 비용이 있어 기본은 미수행
+ 'rebuild_search_index' => ['nullable', 'boolean'],
];
return HookManager::applyFilters('core.plugin.perform_update_validation_rules', $rules, $this);
diff --git a/app/Http/Requests/Public/Module/ServeModuleAssetRequest.php b/app/Http/Requests/Public/Module/ServeModuleAssetRequest.php
index 411ff198..9d2002cc 100644
--- a/app/Http/Requests/Public/Module/ServeModuleAssetRequest.php
+++ b/app/Http/Requests/Public/Module/ServeModuleAssetRequest.php
@@ -4,6 +4,7 @@ namespace App\Http\Requests\Public\Module;
use App\Rules\AllowedModuleFileType;
use App\Rules\SafeModulePath;
+use App\Support\Routing\DualExtensionRoute;
use Illuminate\Foundation\Http\FormRequest;
class ServeModuleAssetRequest extends FormRequest
@@ -12,6 +13,8 @@ class ServeModuleAssetRequest extends FormRequest
* 사용자가 이 요청을 수행할 권한이 있는지 확인
*
* 권한 체크는 라우트의 permission 미들웨어에서 수행됩니다.
+ *
+ * @return bool 항상 true (권한은 미들웨어 책임)
*/
public function authorize(): bool
{
@@ -21,8 +24,11 @@ class ServeModuleAssetRequest extends FormRequest
/**
* 요청에 적용할 검증 규칙
*
- * @return array
+ * @return array 검증 규칙 배열
*/
+ // audit:allow core-formrequest-hook-filter reason: 자산 서빙 경로 검증은 파일시스템
+ // 화이트리스트(SafeModulePath + AllowedModuleFileType)가 유일한 방어선이다.
+ // 확장이 필터로 규칙을 대체할 수 있으면 경로 탈출·임의 파일 읽기가 열린다.
public function rules(): array
{
// 모듈 식별자로부터 기준 경로 구성 (모듈 루트)
@@ -35,7 +41,7 @@ class ServeModuleAssetRequest extends FormRequest
'required',
'string',
new SafeModulePath($basePath),
- new AllowedModuleFileType(),
+ new AllowedModuleFileType,
],
];
}
@@ -45,10 +51,11 @@ class ServeModuleAssetRequest extends FormRequest
*/
protected function prepareForValidation(): void
{
- // 라우트 파라미터를 검증 데이터에 병합
+ // 라우트 파라미터를 검증 데이터에 병합.
+ // 확장자 없는 모드에서는 파일 경로가 `?file=` 쿼리로 온다 (경로 확장자 회피).
$this->merge([
'identifier' => $this->route('identifier'),
- 'path' => $this->route('path'),
+ 'path' => $this->route('path') ?? $this->query(DualExtensionRoute::FILE_QUERY_PARAM),
]);
}
diff --git a/app/Http/Requests/Public/Plugin/ServePluginAssetRequest.php b/app/Http/Requests/Public/Plugin/ServePluginAssetRequest.php
index b2af81a1..c4543607 100644
--- a/app/Http/Requests/Public/Plugin/ServePluginAssetRequest.php
+++ b/app/Http/Requests/Public/Plugin/ServePluginAssetRequest.php
@@ -4,6 +4,7 @@ namespace App\Http\Requests\Public\Plugin;
use App\Rules\AllowedPluginFileType;
use App\Rules\SafePluginPath;
+use App\Support\Routing\DualExtensionRoute;
use Illuminate\Foundation\Http\FormRequest;
class ServePluginAssetRequest extends FormRequest
@@ -12,6 +13,8 @@ class ServePluginAssetRequest extends FormRequest
* 사용자가 이 요청을 수행할 권한이 있는지 확인
*
* 권한 체크는 라우트의 permission 미들웨어에서 수행됩니다.
+ *
+ * @return bool 항상 true (권한은 미들웨어 책임)
*/
public function authorize(): bool
{
@@ -21,8 +24,11 @@ class ServePluginAssetRequest extends FormRequest
/**
* 요청에 적용할 검증 규칙
*
- * @return array
+ * @return array 검증 규칙 배열
*/
+ // audit:allow core-formrequest-hook-filter reason: 자산 서빙 경로 검증은 파일시스템
+ // 화이트리스트(SafePluginPath + AllowedPluginFileType)가 유일한 방어선이다.
+ // 확장이 필터로 규칙을 대체할 수 있으면 경로 탈출·임의 파일 읽기가 열린다.
public function rules(): array
{
// 플러그인 식별자로부터 기준 경로 구성 (플러그인 루트)
@@ -35,7 +41,7 @@ class ServePluginAssetRequest extends FormRequest
'required',
'string',
new SafePluginPath($basePath),
- new AllowedPluginFileType(),
+ new AllowedPluginFileType,
],
];
}
@@ -48,7 +54,7 @@ class ServePluginAssetRequest extends FormRequest
// 라우트 파라미터를 검증 데이터에 병합
$this->merge([
'identifier' => $this->route('identifier'),
- 'path' => $this->route('path'),
+ 'path' => $this->route('path') ?? $this->query(DualExtensionRoute::FILE_QUERY_PARAM),
]);
}
diff --git a/app/Http/Requests/Public/SearchRequest.php b/app/Http/Requests/Public/SearchRequest.php
index 47845067..54582355 100644
--- a/app/Http/Requests/Public/SearchRequest.php
+++ b/app/Http/Requests/Public/SearchRequest.php
@@ -3,6 +3,8 @@
namespace App\Http\Requests\Public;
use App\Extension\HookManager;
+use App\Support\Query\PaginationLimits;
+use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Foundation\Http\FormRequest;
/**
@@ -15,16 +17,38 @@ class SearchRequest extends FormRequest
{
/**
* Determine if the user is authorized to make this request.
+ *
+ * @return bool
*/
public function authorize(): bool
{
return true;
}
+ /**
+ * 검증 전에 쿼리 파라미터를 정규화합니다.
+ *
+ * 쿼리스트링은 언제나 문자열로 도착하므로 `with_counts=false` 가 `boolean` 규칙에
+ * 걸려 422 가 된다. 해석 가능한 값만 캐스팅하고, 그 외(오타 등)는 손대지 않아
+ * 규칙이 그대로 걸러내게 둔다 — null 로 바꾸면 오타가 "미지정" 으로 통과한다.
+ */
+ protected function prepareForValidation(): void
+ {
+ if (! $this->has('with_counts')) {
+ return;
+ }
+
+ $normalized = filter_var($this->input('with_counts'), FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);
+
+ if ($normalized !== null) {
+ $this->merge(['with_counts' => $normalized]);
+ }
+ }
+
/**
* Get the validation rules that apply to the request.
*
- * @return array|string>
+ * @return array|string>
*/
public function rules(): array
{
@@ -33,13 +57,29 @@ class SearchRequest extends FormRequest
'q' => ['nullable', 'string', 'min:2', 'max:200'],
'type' => ['nullable', 'string'],
'sort' => ['nullable', 'string'],
- 'page' => ['nullable', 'integer', 'min:1'],
+ // 페이지 상한은 남용 차단용이다. 정상 탐색은 has_more_pages 로 계속 열려 있고,
+ // 임의의 큰 페이지 번호를 직접 던져 초대형 OFFSET 을 만드는 것만 막는다.
+ 'page' => array_filter([
+ 'nullable',
+ 'integer',
+ 'min:1',
+ ($maxPage = PaginationLimits::maxPage('search')) !== null ? 'max:'.$maxPage : null,
+ ]),
'per_page' => ['nullable', 'integer', 'min:1', 'max:100'],
+ // 깊은 페이지를 OFFSET 없이 넘기기 위한 커서. 형식이 깨진 값은
+ // KeysetPaginator 가 첫 페이지로 되돌리므로 여기서는 길이만 본다.
+ 'cursor' => ['nullable', 'string', 'max:500'],
+ // 특정 탭만 볼 때 다른 탭의 배지 건수를 세지 않게 하는 스위치.
+ // 배지를 그리지 않는 화면에서 그 집계 비용을 없앤다 (기본값은 세는 쪽).
+ 'with_counts' => ['nullable', 'boolean'],
];
// 모듈/플러그인이 validation rules를 동적으로 추가할 수 있도록 훅 제공
// 예: sort의 in 규칙, board_slug 등 모듈별 파라미터
- return HookManager::applyFilters('core.search.validation_rules', $rules, $this);
+ return HookManager::applyFiltersWithLegacyName(
+ 'core.search.index_validation_rules',
+ 'core.search.validation_rules',
+ $rules, $this);
}
/**
@@ -54,6 +94,7 @@ class SearchRequest extends FormRequest
'q.max' => __('search.validation.q_max'),
'page.integer' => __('search.validation.page_integer'),
'page.min' => __('search.validation.page_min'),
+ 'page.max' => __('search.validation.page_max'),
'per_page.integer' => __('search.validation.per_page_integer'),
'per_page.min' => __('search.validation.per_page_min'),
'per_page.max' => __('search.validation.per_page_max'),
diff --git a/app/Http/Requests/Public/Template/ServeTemplateAssetRequest.php b/app/Http/Requests/Public/Template/ServeTemplateAssetRequest.php
index a8f21904..8902303e 100644
--- a/app/Http/Requests/Public/Template/ServeTemplateAssetRequest.php
+++ b/app/Http/Requests/Public/Template/ServeTemplateAssetRequest.php
@@ -4,6 +4,7 @@ namespace App\Http\Requests\Public\Template;
use App\Rules\AllowedTemplateFileType;
use App\Rules\SafeTemplatePath;
+use App\Support\Routing\DualExtensionRoute;
use Illuminate\Foundation\Http\FormRequest;
class ServeTemplateAssetRequest extends FormRequest
@@ -12,6 +13,8 @@ class ServeTemplateAssetRequest extends FormRequest
* 사용자가 이 요청을 수행할 권한이 있는지 확인
*
* 권한 체크는 라우트의 permission 미들웨어에서 수행됩니다.
+ *
+ * @return bool 항상 true (권한은 미들웨어 책임)
*/
public function authorize(): bool
{
@@ -20,7 +23,13 @@ class ServeTemplateAssetRequest extends FormRequest
/**
* 요청에 적용할 검증 규칙
+ *
+ * @return array 검증 규칙 배열
*/
+ // audit:allow core-formrequest-hook-filter reason: 자산 서빙 경로 검증은 파일시스템
+ // 화이트리스트(SafeTemplatePath + AllowedTemplateFileType)가 유일한 방어선이다.
+ // 확장이 필터로 규칙을 대체할 수 있으면 경로 탈출·임의 파일 읽기가 열린다.
+ // 확장 가능한 "동적 필드" 가 없는 요청이라 룰의 취지(필드 확장)도 해당하지 않는다.
public function rules(): array
{
// 템플릿 식별자로부터 기준 경로 구성
@@ -33,7 +42,7 @@ class ServeTemplateAssetRequest extends FormRequest
'required',
'string',
new SafeTemplatePath($basePath),
- new AllowedTemplateFileType(),
+ new AllowedTemplateFileType,
],
];
}
@@ -43,10 +52,13 @@ class ServeTemplateAssetRequest extends FormRequest
*/
protected function prepareForValidation(): void
{
- // 라우트 파라미터를 검증 데이터에 병합
+ // 라우트 파라미터를 검증 데이터에 병합.
+ // 확장자 없는 모드에서는 파일 경로가 경로 세그먼트가 아니라 `?file=` 쿼리로 온다
+ // (nginx 정적 최적화 블록이 URL 경로의 확장자만 보고 가로채는 것을 회피).
+ // 어느 형태로 오든 컨트롤러는 동일하게 `path` 만 본다.
$this->merge([
'identifier' => $this->route('identifier'),
- 'path' => $this->route('path'),
+ 'path' => $this->route('path') ?? $this->query(DualExtensionRoute::FILE_QUERY_PARAM),
]);
}
@@ -64,4 +76,4 @@ class ServeTemplateAssetRequest extends FormRequest
'path.string' => __('validation.asset.path.string'),
];
}
-}
\ No newline at end of file
+}
diff --git a/app/Http/Requests/Settings/SaveSettingsRequest.php b/app/Http/Requests/Settings/SaveSettingsRequest.php
index 7708710b..ddcd5384 100644
--- a/app/Http/Requests/Settings/SaveSettingsRequest.php
+++ b/app/Http/Requests/Settings/SaveSettingsRequest.php
@@ -5,6 +5,8 @@ namespace App\Http\Requests\Settings;
use App\Extension\HookManager;
use App\Models\Attachment;
use App\Search\Engines\DatabaseFulltextEngine;
+use App\Support\AllowedExtensions;
+use App\Support\AssetUrl;
use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Contracts\Validation\Validator;
use Illuminate\Foundation\Http\FormRequest;
@@ -105,6 +107,28 @@ class SaveSettingsRequest extends FormRequest
'advanced.geoip_enabled',
'advanced.geoip_auto_update_enabled',
]);
+
+ $this->normalizeAllowedExtensions();
+ }
+
+ /**
+ * 허용 확장자를 저장 형태(소문자 확장자 배열)로 정규화합니다.
+ *
+ * 화면 입력 칸은 콤마로 구분한 한 줄 텍스트라 이 값은 문자열로 들어온다. 문자열 그대로
+ * 저장하면 업로드 제한을 적용하는 지점이 그 값을 쓰지 못해, 저장은 성공하는데 제한은
+ * 종전 목록으로 남는다. 형태 판정은 저장 경로 진입 전 이 한 곳에서만 수행한다.
+ */
+ private function normalizeAllowedExtensions(): void
+ {
+ $upload = $this->input('upload', []);
+
+ if (! is_array($upload) || ! array_key_exists('allowed_extensions', $upload)) {
+ return;
+ }
+
+ $upload['allowed_extensions'] = AllowedExtensions::normalize($upload['allowed_extensions']);
+
+ $this->merge(['upload' => $upload]);
}
/**
@@ -174,6 +198,13 @@ class SaveSettingsRequest extends FormRequest
'general.language' => $this->getTabRules($tab, 'general', [Rule::in(config('app.supported_locales', ['ko', 'en']))]),
'general.currency' => ['nullable', 'string', 'max:10'],
'general.maintenance_mode' => ['nullable', 'boolean'],
+ // 자산 URL 방식 — 정적 최적화 서버 대응 (이슈 #486).
+ // 임의 문자열이 들어오면 AssetUrl::mode() 가 기본값으로 폴백하지만,
+ // 저장 단계에서 막아 설정 파일에 뜻 모를 값이 남지 않게 한다.
+ 'general.asset_url_mode' => ['nullable', 'string', Rule::in([
+ AssetUrl::MODE_EXTENSION,
+ AssetUrl::MODE_EXTENSIONLESS,
+ ])],
'general.site_logo' => ['nullable', 'array'],
'general.site_logo.*' => ['integer', Rule::exists(Attachment::class, 'id')],
@@ -194,11 +225,11 @@ class SaveSettingsRequest extends FormRequest
'mail.from_name' => $this->getTabRules($tab, 'mail', 'string|max:255'),
// 업로드 설정
- 'upload.max_file_size' => $this->getTabRules($tab, 'upload', 'integer|min:1|max:1024'),
+ 'upload.max_file_size' => $this->getTabRules($tab, 'upload', 'integer|min:'.config('core.settings_limits.upload_max_file_size_min', 1).'|max:'.config('core.settings_limits.upload_max_file_size_max', 1024)),
'upload.allowed_extensions' => $this->getAllowedExtensionsRules($tab),
- 'upload.image_max_width' => ['nullable', 'integer', 'min:100', 'max:10000'],
- 'upload.image_max_height' => ['nullable', 'integer', 'min:100', 'max:10000'],
- 'upload.image_quality' => ['nullable', 'integer', 'min:1', 'max:100'],
+ 'upload.image_max_width' => ['nullable', 'integer', 'min:'.config('core.settings_limits.upload_image_max_width_min', 100), 'max:'.config('core.settings_limits.upload_image_max_width_max', 10000)],
+ 'upload.image_max_height' => ['nullable', 'integer', 'min:'.config('core.settings_limits.upload_image_max_height_min', 100), 'max:'.config('core.settings_limits.upload_image_max_height_max', 10000)],
+ 'upload.image_quality' => ['nullable', 'integer', 'min:'.config('core.settings_limits.upload_image_quality_min', 1), 'max:'.config('core.settings_limits.upload_image_quality_max', 100)],
// SEO 설정
'seo.meta_title_suffix' => ['nullable', 'string', 'max:100'],
@@ -212,14 +243,20 @@ class SaveSettingsRequest extends FormRequest
'seo.bot_detection_enabled' => ['nullable', 'boolean'],
'seo.bot_detection_library_enabled' => ['nullable', 'boolean'],
'seo.og_default_site_name' => ['nullable', 'string', 'max:200'],
- 'seo.og_image_default_width' => ['nullable', 'integer', 'min:0', 'max:8000'],
- 'seo.og_image_default_height' => ['nullable', 'integer', 'min:0', 'max:8000'],
+ 'seo.og_image_default_width' => ['nullable', 'integer', 'min:'.config('core.settings_limits.seo_og_image_default_width_min', 0), 'max:'.config('core.settings_limits.seo_og_image_default_width_max', 8000)],
+ 'seo.og_image_default_height' => ['nullable', 'integer', 'min:'.config('core.settings_limits.seo_og_image_default_height_min', 0), 'max:'.config('core.settings_limits.seo_og_image_default_height_max', 8000)],
'seo.twitter_default_card' => ['nullable', 'string', Rule::in(['summary', 'summary_large_image', 'app', 'player', ''])],
'seo.twitter_default_site' => ['nullable', 'string', 'max:50'],
'seo.cache_enabled' => ['nullable', 'boolean'],
- 'seo.cache_ttl' => ['nullable', 'integer', 'min:60', 'max:86400'],
+ 'seo.cache_ttl' => ['nullable', 'integer', 'min:'.config('core.settings_limits.seo_cache_ttl_min', 60), 'max:'.config('core.settings_limits.seo_cache_ttl_max', 86400)],
'seo.sitemap_enabled' => ['nullable', 'boolean'],
- 'seo.sitemap_cache_ttl' => ['nullable', 'integer', 'min:3600', 'max:604800'],
+ 'seo.sitemap_cache_ttl' => ['nullable', 'integer', 'min:'.config('core.settings_limits.seo_sitemap_cache_ttl_min', 3600), 'max:'.config('core.settings_limits.seo_sitemap_cache_ttl_max', 604800)],
+ // 분할 기준. 상한 50000 은 sitemaps.org 프로토콜 제한이며 SitemapWriter 가 동일 값으로 클램프합니다.
+ 'seo.sitemap_urls_per_file' => ['nullable', 'integer', 'min:'.config('core.settings_limits.seo_sitemap_urls_per_file_min', 1000), 'max:'.config('core.settings_limits.seo_sitemap_urls_per_file_max', 50000)],
+ 'seo.sitemap_gzip' => ['nullable', 'boolean'],
+ 'seo.sitemap_serve_stale_on_miss' => ['nullable', 'boolean'],
+ 'seo.sitemap_max_urls_per_contributor' => ['nullable', 'integer', 'min:0'],
+ 'seo.sitemap_hreflang_enabled' => ['nullable', 'boolean'],
'seo.sitemap_schedule' => ['nullable', 'string', Rule::in(['hourly', 'daily', 'weekly'])],
'seo.sitemap_schedule_time' => ['nullable', 'string', 'regex:/^\d{2}:\d{2}$/'],
'seo.generator_enabled' => ['nullable', 'boolean'],
@@ -229,8 +266,18 @@ class SaveSettingsRequest extends FormRequest
'security.force_https' => $this->getTabRules($tab, 'security', 'boolean'),
'security.login_attempt_enabled' => $this->getTabRules($tab, 'security', 'boolean'),
'security.auth_token_lifetime' => $this->getSecurityTabAuthTokenRules($tab),
- 'security.max_login_attempts' => ['nullable', 'integer', 'min:0', 'max:100'],
- 'security.login_lockout_time' => ['nullable', 'integer', 'min:0', 'max:1440'],
+ 'security.max_login_attempts' => ['nullable', 'integer', 'min:'.config('core.settings_limits.security_max_login_attempts_min', 0), 'max:'.config('core.settings_limits.security_max_login_attempts_max', 100)],
+ 'security.login_lockout_time' => ['nullable', 'integer', 'min:'.config('core.settings_limits.security_login_lockout_time_min', 0), 'max:'.config('core.settings_limits.security_login_lockout_time_max', 1440)],
+ // 비밀번호 정책 — 저장 규칙이 없어 whitelist 에서 탈락하던 고아 설정을 배선.
+ // 경계값은 config('core.settings_limits') 가 SSoT — 설정 화면도 같은 값을 받아 쓴다.
+ 'security.password_min_length' => [
+ 'nullable',
+ 'integer',
+ 'min:'.config('core.settings_limits.security_password_min_length_min', 6),
+ 'max:'.config('core.settings_limits.security_password_min_length_max', 64),
+ ],
+ 'security.require_password_special_char' => ['nullable', 'boolean'],
+ 'security.two_factor_auth' => ['nullable', 'boolean'],
// 신규 설정이므로 미전송(기존 클라이언트)을 허용한다 — 미전송 시 기본값 false 유지
'security.allow_internal_outbound_urls' => ['nullable', 'boolean'],
@@ -242,6 +289,9 @@ class SaveSettingsRequest extends FormRequest
'advanced.stats_cache_ttl' => $this->getAdvancedTabCacheTtlRules($tab),
'advanced.seo_cache_enabled' => $this->getTabRules($tab, 'advanced', 'boolean'),
'advanced.seo_cache_ttl' => $this->getAdvancedTabCacheTtlRules($tab),
+ // 신규 설정이므로 미전송(기존 클라이언트)을 허용한다 — 미전송/미지정 시 코드 기본값 유지.
+ // 범위는 SEO 탭의 오버라이드 칸(seo.sitemap_cache_ttl)과 동일하게 맞춘다.
+ 'advanced.seo_sitemap_cache_ttl' => ['nullable', 'integer', 'min:'.config('core.settings_limits.advanced_seo_sitemap_cache_ttl_min', 3600), 'max:'.config('core.settings_limits.advanced_seo_sitemap_cache_ttl_max', 604800)],
// 디버그 설정 (advanced 탭)
'advanced.debug_mode' => $this->getTabRules($tab, 'advanced', 'boolean'),
@@ -258,6 +308,10 @@ class SaveSettingsRequest extends FormRequest
'advanced.geoip_license_key' => ['nullable', 'string', 'max:200', 'regex:/^[A-Za-z0-9_]+$/'],
'advanced.geoip_auto_update_enabled' => ['nullable', 'boolean'],
+ // 목록 한계값 (advanced 탭) — 0 은 무제한
+ 'advanced.pagination_result_cap' => ['nullable', 'integer', 'min:'.config('core.settings_limits.advanced_pagination_result_cap_min', 0), 'max:'.config('core.settings_limits.advanced_pagination_result_cap_max', 1000000)],
+ 'advanced.pagination_max_page' => ['nullable', 'integer', 'min:'.config('core.settings_limits.advanced_pagination_max_page_min', 0), 'max:'.config('core.settings_limits.advanced_pagination_max_page_max', 100000)],
+
// 드라이버 설정 (drivers 탭)
'drivers.storage_driver' => $this->getTabRules($tab, 'drivers', [Rule::in(self::SUPPORTED_STORAGE_DRIVERS)]),
'drivers.s3_bucket' => ['nullable', 'string', 'max:255'],
@@ -267,35 +321,35 @@ class SaveSettingsRequest extends FormRequest
'drivers.s3_url' => ['nullable', 'url', 'max:500'],
'drivers.cache_driver' => $this->getTabRules($tab, 'drivers', [Rule::in(self::SUPPORTED_CACHE_DRIVERS)]),
'drivers.redis_host' => ['nullable', 'string', 'max:255'],
- 'drivers.redis_port' => ['nullable', 'integer', 'min:1', 'max:65535'],
+ 'drivers.redis_port' => ['nullable', 'integer', 'min:'.config('core.settings_limits.drivers_redis_port_min', 1), 'max:'.config('core.settings_limits.drivers_redis_port_max', 65535)],
'drivers.redis_password' => ['nullable', 'string', 'max:255'],
- 'drivers.redis_database' => ['nullable', 'integer', 'min:0', 'max:15'],
+ 'drivers.redis_database' => ['nullable', 'integer', 'min:'.config('core.settings_limits.drivers_redis_database_min', 0), 'max:'.config('core.settings_limits.drivers_redis_database_max', 15)],
'drivers.memcached_host' => ['nullable', 'string', 'max:255'],
- 'drivers.memcached_port' => ['nullable', 'integer', 'min:1', 'max:65535'],
+ 'drivers.memcached_port' => ['nullable', 'integer', 'min:'.config('core.settings_limits.drivers_memcached_port_min', 1), 'max:'.config('core.settings_limits.drivers_memcached_port_max', 65535)],
'drivers.session_driver' => $this->getTabRules($tab, 'drivers', [Rule::in(self::SUPPORTED_SESSION_DRIVERS)]),
- 'drivers.session_lifetime' => ['nullable', 'integer', 'min:1', 'max:43200'], // 1분 ~ 30일
+ 'drivers.session_lifetime' => ['nullable', 'integer', 'min:'.config('core.settings_limits.drivers_session_lifetime_min', 1), 'max:'.config('core.settings_limits.drivers_session_lifetime_max', 43200)], // 1분 ~ 30일
'drivers.queue_driver' => $this->getTabRules($tab, 'drivers', [Rule::in(self::SUPPORTED_QUEUE_DRIVERS)]),
'drivers.websocket_enabled' => ['nullable', 'boolean'],
'drivers.websocket_app_id' => [Rule::requiredIf(fn () => $this->boolean('drivers.websocket_enabled')), 'nullable', 'string', 'max:255'],
'drivers.websocket_app_key' => [Rule::requiredIf(fn () => $this->boolean('drivers.websocket_enabled')), 'nullable', 'string', 'max:255'],
'drivers.websocket_app_secret' => [Rule::requiredIf(fn () => $this->boolean('drivers.websocket_enabled')), 'nullable', 'string', 'max:255'],
'drivers.websocket_host' => ['nullable', 'string', 'max:255'],
- 'drivers.websocket_port' => ['nullable', 'integer', 'min:1', 'max:65535'],
+ 'drivers.websocket_port' => ['nullable', 'integer', 'min:'.config('core.settings_limits.drivers_websocket_port_min', 1), 'max:'.config('core.settings_limits.drivers_websocket_port_max', 65535)],
'drivers.websocket_scheme' => ['nullable', Rule::in(self::SUPPORTED_WEBSOCKET_SCHEMES)],
'drivers.websocket_verify_ssl' => ['nullable', 'boolean'],
'drivers.websocket_server_host' => ['nullable', 'string', 'max:255'],
- 'drivers.websocket_server_port' => ['nullable', 'integer', 'min:1', 'max:65535'],
+ 'drivers.websocket_server_port' => ['nullable', 'integer', 'min:'.config('core.settings_limits.drivers_websocket_server_port_min', 1), 'max:'.config('core.settings_limits.drivers_websocket_server_port_max', 65535)],
'drivers.websocket_server_scheme' => ['nullable', Rule::in(self::SUPPORTED_WEBSOCKET_SCHEMES)],
'drivers.search_engine_driver' => ['nullable', Rule::in($this->getSupportedSearchEngineDrivers())],
'drivers.log_driver' => $this->getTabRules($tab, 'drivers', [Rule::in(self::SUPPORTED_LOG_DRIVERS)]),
'drivers.log_level' => $this->getTabRules($tab, 'drivers', [Rule::in(self::SUPPORTED_LOG_LEVELS)]),
- 'drivers.log_days' => ['nullable', 'integer', 'min:1', 'max:365'],
+ 'drivers.log_days' => ['nullable', 'integer', 'min:'.config('core.settings_limits.drivers_log_days_min', 1), 'max:'.config('core.settings_limits.drivers_log_days_max', 365)],
// 본인인증(IDV) provider 기술 파라미터 — 정책 분기는 IdentityPolicy 로 흡수됨
'identity.default_provider' => ['nullable', 'string', 'max:100'],
'identity.purpose_providers' => ['sometimes', 'array'],
- 'identity.challenge_ttl_minutes' => $this->getTabRules($tab, 'identity', 'integer|min:1|max:1440'),
- 'identity.max_attempts' => $this->getTabRules($tab, 'identity', 'integer|min:1|max:20'),
+ 'identity.challenge_ttl_minutes' => $this->getTabRules($tab, 'identity', 'integer|min:'.config('core.settings_limits.identity_challenge_ttl_minutes_min', 1).'|max:'.config('core.settings_limits.identity_challenge_ttl_minutes_max', 1440)),
+ 'identity.max_attempts' => $this->getTabRules($tab, 'identity', 'integer|min:'.config('core.settings_limits.identity_max_attempts_min', 1).'|max:'.config('core.settings_limits.identity_max_attempts_max', 20)),
];
// 모듈/플러그인이 validation rules를 동적으로 추가할 수 있도록 훅 제공
@@ -357,8 +411,8 @@ class SaveSettingsRequest extends FormRequest
return [
'nullable',
'integer',
- 'min:0',
- 'max:3600',
+ 'min:'.config('core.settings_limits.security_auth_token_lifetime_min', 0),
+ 'max:'.config('core.settings_limits.security_auth_token_lifetime_max', 3600),
function ($attribute, $value, $fail) {
// 0은 무한대를 의미하므로 허용, 그 외에는 30 이상이어야 함
if ($value !== null && $value !== 0 && $value < 30) {
@@ -419,8 +473,8 @@ class SaveSettingsRequest extends FormRequest
return array_merge($baseRules, [
'integer',
- 'min:0',
- 'max:14400',
+ 'min:'.config('core.settings_limits.advanced_cache_ttl_min', 0),
+ 'max:'.config('core.settings_limits.advanced_cache_ttl_max', 14400),
]);
}
@@ -605,6 +659,14 @@ class SaveSettingsRequest extends FormRequest
'seo.sitemap_cache_ttl.integer' => __('validation.settings.sitemap_cache_ttl_integer'),
'seo.sitemap_cache_ttl.min' => __('validation.settings.sitemap_cache_ttl_min'),
'seo.sitemap_cache_ttl.max' => __('validation.settings.sitemap_cache_ttl_max'),
+ 'seo.sitemap_urls_per_file.integer' => __('validation.settings.sitemap_urls_per_file_integer'),
+ 'seo.sitemap_urls_per_file.min' => __('validation.settings.sitemap_urls_per_file_min'),
+ 'seo.sitemap_urls_per_file.max' => __('validation.settings.sitemap_urls_per_file_max'),
+ 'seo.sitemap_gzip.boolean' => __('validation.settings.sitemap_gzip_boolean'),
+ 'seo.sitemap_serve_stale_on_miss.boolean' => __('validation.settings.sitemap_serve_stale_on_miss_boolean'),
+ 'seo.sitemap_max_urls_per_contributor.integer' => __('validation.settings.sitemap_max_urls_per_contributor_integer'),
+ 'seo.sitemap_max_urls_per_contributor.min' => __('validation.settings.sitemap_max_urls_per_contributor_min'),
+ 'seo.sitemap_hreflang_enabled.boolean' => __('validation.settings.sitemap_hreflang_enabled_boolean'),
'seo.sitemap_schedule.in' => __('validation.settings.sitemap_schedule_invalid'),
'seo.sitemap_schedule_time.regex' => __('validation.settings.sitemap_schedule_time_invalid'),
@@ -639,12 +701,15 @@ class SaveSettingsRequest extends FormRequest
'advanced.stats_cache_ttl.integer' => __('validation.settings.stats_cache_ttl_integer'),
'advanced.stats_cache_ttl.min' => __('validation.settings.stats_cache_ttl_min'),
'advanced.stats_cache_ttl.max' => __('validation.settings.stats_cache_ttl_max'),
- 'advanced.seo_cache_enabled.required' => __('validation.settings.seo_cache_enabled_required'),
- 'advanced.seo_cache_enabled.boolean' => __('validation.settings.seo_cache_enabled_boolean'),
- 'advanced.seo_cache_ttl.required' => __('validation.settings.seo_cache_ttl_required'),
- 'advanced.seo_cache_ttl.integer' => __('validation.settings.seo_cache_ttl_integer'),
- 'advanced.seo_cache_ttl.min' => __('validation.settings.seo_cache_ttl_min'),
- 'advanced.seo_cache_ttl.max' => __('validation.settings.seo_cache_ttl_max'),
+ 'advanced.seo_cache_enabled.required' => __('validation.settings.advanced_seo_cache_enabled_required'),
+ 'advanced.seo_cache_enabled.boolean' => __('validation.settings.advanced_seo_cache_enabled_boolean'),
+ 'advanced.seo_cache_ttl.required' => __('validation.settings.advanced_seo_cache_ttl_required'),
+ 'advanced.seo_cache_ttl.integer' => __('validation.settings.advanced_seo_cache_ttl_integer'),
+ 'advanced.seo_cache_ttl.min' => __('validation.settings.advanced_seo_cache_ttl_min'),
+ 'advanced.seo_cache_ttl.max' => __('validation.settings.advanced_seo_cache_ttl_max'),
+ 'advanced.seo_sitemap_cache_ttl.integer' => __('validation.settings.seo_sitemap_cache_ttl_integer'),
+ 'advanced.seo_sitemap_cache_ttl.min' => __('validation.settings.seo_sitemap_cache_ttl_min'),
+ 'advanced.seo_sitemap_cache_ttl.max' => __('validation.settings.seo_sitemap_cache_ttl_max'),
// 디버그 설정
'advanced.debug_mode.required' => __('validation.settings.debug_mode_required'),
@@ -652,6 +717,14 @@ class SaveSettingsRequest extends FormRequest
'advanced.sql_query_log.required' => __('validation.settings.sql_query_log_required'),
'advanced.sql_query_log.boolean' => __('validation.settings.sql_query_log_boolean'),
+ // 목록 한계값
+ 'advanced.pagination_result_cap.integer' => __('validation.settings.pagination_result_cap_integer'),
+ 'advanced.pagination_result_cap.min' => __('validation.settings.pagination_result_cap_min'),
+ 'advanced.pagination_result_cap.max' => __('validation.settings.pagination_result_cap_max'),
+ 'advanced.pagination_max_page.integer' => __('validation.settings.pagination_max_page_integer'),
+ 'advanced.pagination_max_page.min' => __('validation.settings.pagination_max_page_min'),
+ 'advanced.pagination_max_page.max' => __('validation.settings.pagination_max_page_max'),
+
// 코어 업데이트 설정
'advanced.core_update_github_url.url' => __('validation.settings.core_update_github_url_invalid'),
'advanced.core_update_github_url.max' => __('validation.settings.core_update_github_url_max'),
@@ -752,6 +825,122 @@ class SaveSettingsRequest extends FormRequest
'identity.purpose_providers' => __('validation.attributes.identity_purpose_providers'),
'identity.challenge_ttl_minutes' => __('validation.attributes.identity_challenge_ttl_minutes'),
'identity.max_attempts' => __('validation.attributes.identity_max_attempts'),
+ // notifications
+ 'notifications.channels' => __('validation.attributes.channels'),
+ // general
+ 'general.currency' => __('validation.attributes.currency'),
+ 'general.maintenance_mode' => __('validation.attributes.maintenance_mode'),
+ 'general.asset_url_mode' => __('validation.attributes.asset_url_mode'),
+ 'general.site_logo' => __('validation.attributes.site_logo'),
+ // mail
+ 'mail.mailer' => __('validation.attributes.mailer'),
+ 'mail.host' => __('validation.attributes.host'),
+ 'mail.port' => __('validation.attributes.port'),
+ 'mail.username' => __('validation.attributes.username'),
+ 'mail.password' => __('validation.attributes.password'),
+ 'mail.encryption' => __('validation.attributes.encryption'),
+ 'mail.mailgun_domain' => __('validation.attributes.mailgun_domain'),
+ 'mail.mailgun_secret' => __('validation.attributes.mailgun_secret'),
+ 'mail.mailgun_endpoint' => __('validation.attributes.mailgun_endpoint'),
+ 'mail.ses_key' => __('validation.attributes.ses_key'),
+ 'mail.ses_secret' => __('validation.attributes.ses_secret'),
+ 'mail.ses_region' => __('validation.attributes.ses_region'),
+ 'mail.from_address' => __('validation.attributes.from_address'),
+ 'mail.from_name' => __('validation.attributes.from_name'),
+ // upload
+ 'upload.max_file_size' => __('validation.attributes.max_file_size'),
+ 'upload.allowed_extensions' => __('validation.attributes.allowed_extensions'),
+ 'upload.image_max_width' => __('validation.attributes.image_max_width'),
+ 'upload.image_max_height' => __('validation.attributes.image_max_height'),
+ 'upload.image_quality' => __('validation.attributes.image_quality'),
+ // seo
+ 'seo.meta_title_suffix' => __('validation.attributes.meta_title_suffix'),
+ 'seo.meta_description' => __('validation.attributes.meta_description'),
+ 'seo.meta_keywords' => __('validation.attributes.meta_keywords'),
+ 'seo.google_analytics_id' => __('validation.attributes.google_analytics_id'),
+ 'seo.google_site_verification' => __('validation.attributes.google_site_verification'),
+ 'seo.naver_site_verification' => __('validation.attributes.naver_site_verification'),
+ 'seo.bot_user_agents' => __('validation.attributes.bot_user_agents'),
+ 'seo.bot_detection_enabled' => __('validation.attributes.bot_detection_enabled'),
+ 'seo.bot_detection_library_enabled' => __('validation.attributes.bot_detection_library_enabled'),
+ 'seo.og_default_site_name' => __('validation.attributes.og_default_site_name'),
+ 'seo.og_image_default_width' => __('validation.attributes.og_image_default_width'),
+ 'seo.og_image_default_height' => __('validation.attributes.og_image_default_height'),
+ 'seo.twitter_default_card' => __('validation.attributes.twitter_default_card'),
+ 'seo.twitter_default_site' => __('validation.attributes.twitter_default_site'),
+ 'seo.cache_enabled' => __('validation.attributes.seo_page_cache_enabled'),
+ 'seo.cache_ttl' => __('validation.attributes.cache_ttl'),
+ 'seo.sitemap_enabled' => __('validation.attributes.sitemap_enabled'),
+ 'seo.sitemap_cache_ttl' => __('validation.attributes.sitemap_cache_ttl'),
+ 'seo.sitemap_urls_per_file' => __('validation.attributes.sitemap_urls_per_file'),
+ 'seo.sitemap_gzip' => __('validation.attributes.sitemap_gzip'),
+ 'seo.sitemap_serve_stale_on_miss' => __('validation.attributes.sitemap_serve_stale_on_miss'),
+ 'seo.sitemap_max_urls_per_contributor' => __('validation.attributes.sitemap_max_urls_per_contributor'),
+ 'seo.sitemap_hreflang_enabled' => __('validation.attributes.sitemap_hreflang_enabled'),
+ 'seo.sitemap_schedule' => __('validation.attributes.sitemap_schedule'),
+ 'seo.sitemap_schedule_time' => __('validation.attributes.sitemap_schedule_time'),
+ 'seo.generator_enabled' => __('validation.attributes.generator_enabled'),
+ 'seo.generator_content' => __('validation.attributes.generator_content'),
+ // security
+ 'security.force_https' => __('validation.attributes.force_https'),
+ 'security.login_attempt_enabled' => __('validation.attributes.login_attempt_enabled'),
+ 'security.auth_token_lifetime' => __('validation.attributes.auth_token_lifetime'),
+ 'security.max_login_attempts' => __('validation.attributes.max_login_attempts'),
+ 'security.login_lockout_time' => __('validation.attributes.login_lockout_time'),
+ 'security.password_min_length' => __('validation.attributes.password_min_length'),
+ 'security.require_password_special_char' => __('validation.attributes.require_password_special_char'),
+ 'security.two_factor_auth' => __('validation.attributes.two_factor_auth'),
+ 'security.allow_internal_outbound_urls' => __('validation.attributes.allow_internal_outbound_urls'),
+ // advanced
+ 'advanced.cache_enabled' => __('validation.attributes.advanced_cache_enabled'),
+ 'advanced.layout_cache_enabled' => __('validation.attributes.layout_cache_enabled'),
+ 'advanced.layout_cache_ttl' => __('validation.attributes.layout_cache_ttl'),
+ 'advanced.stats_cache_enabled' => __('validation.attributes.stats_cache_enabled'),
+ 'advanced.stats_cache_ttl' => __('validation.attributes.stats_cache_ttl'),
+ 'advanced.seo_cache_enabled' => __('validation.attributes.seo_cache_enabled'),
+ 'advanced.seo_cache_ttl' => __('validation.attributes.seo_cache_ttl'),
+ 'advanced.seo_sitemap_cache_ttl' => __('validation.attributes.seo_sitemap_cache_ttl'),
+ 'advanced.debug_mode' => __('validation.attributes.debug_mode'),
+ 'advanced.sql_query_log' => __('validation.attributes.sql_query_log'),
+ 'advanced.core_update_github_url' => __('validation.attributes.core_update_github_url'),
+ 'advanced.core_update_github_token' => __('validation.attributes.core_update_github_token'),
+ 'advanced.geoip_enabled' => __('validation.attributes.geoip_enabled'),
+ 'advanced.geoip_license_key' => __('validation.attributes.geoip_license_key'),
+ 'advanced.geoip_auto_update_enabled' => __('validation.attributes.geoip_auto_update_enabled'),
+ 'advanced.pagination_result_cap' => __('validation.attributes.pagination_result_cap'),
+ 'advanced.pagination_max_page' => __('validation.attributes.pagination_max_page'),
+ // drivers
+ 'drivers.storage_driver' => __('validation.attributes.storage_driver'),
+ 'drivers.s3_bucket' => __('validation.attributes.s3_bucket'),
+ 'drivers.s3_region' => __('validation.attributes.s3_region'),
+ 'drivers.s3_access_key' => __('validation.attributes.s3_access_key'),
+ 'drivers.s3_secret_key' => __('validation.attributes.s3_secret_key'),
+ 'drivers.s3_url' => __('validation.attributes.s3_url'),
+ 'drivers.cache_driver' => __('validation.attributes.cache_driver'),
+ 'drivers.redis_host' => __('validation.attributes.redis_host'),
+ 'drivers.redis_port' => __('validation.attributes.redis_port'),
+ 'drivers.redis_password' => __('validation.attributes.redis_password'),
+ 'drivers.redis_database' => __('validation.attributes.redis_database'),
+ 'drivers.memcached_host' => __('validation.attributes.memcached_host'),
+ 'drivers.memcached_port' => __('validation.attributes.memcached_port'),
+ 'drivers.session_driver' => __('validation.attributes.session_driver'),
+ 'drivers.session_lifetime' => __('validation.attributes.session_lifetime'),
+ 'drivers.queue_driver' => __('validation.attributes.queue_driver'),
+ 'drivers.websocket_enabled' => __('validation.attributes.websocket_enabled'),
+ 'drivers.websocket_app_id' => __('validation.attributes.websocket_app_id'),
+ 'drivers.websocket_app_key' => __('validation.attributes.websocket_app_key'),
+ 'drivers.websocket_app_secret' => __('validation.attributes.websocket_app_secret'),
+ 'drivers.websocket_host' => __('validation.attributes.websocket_host'),
+ 'drivers.websocket_port' => __('validation.attributes.websocket_port'),
+ 'drivers.websocket_scheme' => __('validation.attributes.websocket_scheme'),
+ 'drivers.websocket_verify_ssl' => __('validation.attributes.websocket_verify_ssl'),
+ 'drivers.websocket_server_host' => __('validation.attributes.websocket_server_host'),
+ 'drivers.websocket_server_port' => __('validation.attributes.websocket_server_port'),
+ 'drivers.websocket_server_scheme' => __('validation.attributes.websocket_server_scheme'),
+ 'drivers.search_engine_driver' => __('validation.attributes.search_engine_driver'),
+ 'drivers.log_driver' => __('validation.attributes.log_driver'),
+ 'drivers.log_level' => __('validation.attributes.log_level'),
+ 'drivers.log_days' => __('validation.attributes.log_days'),
];
}
}
diff --git a/app/Http/Requests/User/ChangePasswordRequest.php b/app/Http/Requests/User/ChangePasswordRequest.php
index ad81dcdc..af3bd322 100644
--- a/app/Http/Requests/User/ChangePasswordRequest.php
+++ b/app/Http/Requests/User/ChangePasswordRequest.php
@@ -3,8 +3,9 @@
namespace App\Http\Requests\User;
use App\Extension\HookManager;
+use App\Rules\PasswordPolicy;
+use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Foundation\Http\FormRequest;
-use Illuminate\Validation\Rules\Password;
/**
* 비밀번호 변경 요청 클래스
@@ -15,6 +16,8 @@ class ChangePasswordRequest extends FormRequest
{
/**
* Determine if the user is authorized to make this request.
+ *
+ * @return bool 항상 true (권한은 미들웨어에서 검증)
*/
public function authorize(): bool
{
@@ -24,13 +27,13 @@ class ChangePasswordRequest extends FormRequest
/**
* Get the validation rules that apply to the request.
*
- * @return array|string>
+ * @return array|string>
*/
public function rules(): array
{
$rules = [
'current_password' => ['required', 'string', 'current_password:sanctum'],
- 'password' => ['required', 'string', 'confirmed', Password::min(8)],
+ 'password' => ['required', 'string', 'confirmed', PasswordPolicy::rule()],
'password_confirmation' => ['required', 'string'],
];
@@ -54,4 +57,4 @@ class ChangePasswordRequest extends FormRequest
'password_confirmation.required' => __('user.validation.password_confirmation_required'),
];
}
-}
\ No newline at end of file
+}
diff --git a/app/Http/Requests/User/CreateUserRequest.php b/app/Http/Requests/User/CreateUserRequest.php
index e0d5f595..e59cac4d 100644
--- a/app/Http/Requests/User/CreateUserRequest.php
+++ b/app/Http/Requests/User/CreateUserRequest.php
@@ -5,14 +5,17 @@ namespace App\Http\Requests\User;
use App\Extension\HookManager;
use App\Models\Role;
use App\Models\User;
+use App\Rules\PasswordPolicy;
+use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
-use Illuminate\Validation\Rules\Password;
class CreateUserRequest extends FormRequest
{
/**
* Determine if the user is authorized to make this request.
+ *
+ * @return bool 항상 true (권한은 미들웨어에서 검증)
*/
public function authorize(): bool
{
@@ -22,7 +25,7 @@ class CreateUserRequest extends FormRequest
/**
* Get the validation rules that apply to the request.
*
- * @return array|string>
+ * @return array|string>
*/
public function rules(): array
{
@@ -33,7 +36,7 @@ class CreateUserRequest extends FormRequest
'name' => 'required|string|max:255',
'nickname' => 'nullable|string|max:50',
'email' => ['required', 'email', Rule::unique(User::class, 'email'), 'max:255'],
- 'password' => ['required', 'confirmed', Password::min(8)],
+ 'password' => ['required', 'confirmed', PasswordPolicy::rule()],
'language' => 'nullable|string|in:'.$supportedLocales,
'country' => 'nullable|string|size:2|alpha',
'timezone' => ['nullable', 'string', 'timezone'],
@@ -122,8 +125,6 @@ class CreateUserRequest extends FormRequest
* 유효성 검사를 위해 데이터를 준비합니다.
*
* role_ids와 roles가 동시에 전송될 경우 role_ids를 우선하여 roles를 제거합니다.
- *
- * @return void
*/
protected function prepareForValidation(): void
{
diff --git a/app/Http/Requests/User/UpdateProfileRequest.php b/app/Http/Requests/User/UpdateProfileRequest.php
index 3db5feee..fd7cdbf2 100644
--- a/app/Http/Requests/User/UpdateProfileRequest.php
+++ b/app/Http/Requests/User/UpdateProfileRequest.php
@@ -4,6 +4,8 @@ namespace App\Http\Requests\User;
use App\Extension\HookManager;
use App\Models\User;
+use App\Rules\PasswordPolicy;
+use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Support\Facades\Auth;
use Illuminate\Validation\Rule;
@@ -19,6 +21,8 @@ class UpdateProfileRequest extends FormRequest
{
/**
* Determine if the user is authorized to make this request.
+ *
+ * @return bool 항상 true (권한은 미들웨어에서 검증)
*/
public function authorize(): bool
{
@@ -28,7 +32,7 @@ class UpdateProfileRequest extends FormRequest
/**
* Get the validation rules that apply to the request.
*
- * @return array|string>
+ * @return array|string>
*/
public function rules(): array
{
@@ -40,7 +44,7 @@ class UpdateProfileRequest extends FormRequest
'name' => ['required', 'string', 'max:255'],
'nickname' => ['nullable', 'string', 'max:50'],
'email' => ['required', 'email', 'max:255', Rule::unique(User::class, 'email')->ignore($userId)],
- 'password' => ['nullable', 'confirmed', Password::min(8)],
+ 'password' => ['nullable', 'confirmed', PasswordPolicy::rule()],
'current_password' => ['required_with:password', 'current_password'],
'language' => ['nullable', 'string', Rule::in($supportedLocales)],
'country' => ['nullable', 'string', 'size:2', 'alpha'],
@@ -124,5 +128,4 @@ class UpdateProfileRequest extends FormRequest
]);
}
}
-
}
diff --git a/app/Http/Requests/User/UpdateUserRequest.php b/app/Http/Requests/User/UpdateUserRequest.php
index 677e2fae..ff4b5f4d 100644
--- a/app/Http/Requests/User/UpdateUserRequest.php
+++ b/app/Http/Requests/User/UpdateUserRequest.php
@@ -5,14 +5,17 @@ namespace App\Http\Requests\User;
use App\Extension\HookManager;
use App\Models\Role;
use App\Models\User;
+use App\Rules\PasswordPolicy;
+use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
-use Illuminate\Validation\Rules\Password;
class UpdateUserRequest extends FormRequest
{
/**
* Determine if the user is authorized to make this request.
+ *
+ * @return bool 항상 true (권한은 permission 미들웨어에서 검증)
*/
public function authorize(): bool
{
@@ -24,8 +27,6 @@ class UpdateUserRequest extends FormRequest
*
* API 응답에서 로드된 roles(객체 배열)와 사용자가 선택한 role_ids가
* 동시에 전송될 수 있으므로, role_ids가 있으면 roles를 제거합니다.
- *
- * @return void
*/
protected function prepareForValidation(): void
{
@@ -37,7 +38,7 @@ class UpdateUserRequest extends FormRequest
/**
* Get the validation rules that apply to the request.
*
- * @return array|string>
+ * @return array|string>
*/
public function rules(): array
{
@@ -54,7 +55,7 @@ class UpdateUserRequest extends FormRequest
'max:255',
Rule::unique(User::class, 'email')->ignore($userId),
],
- 'password' => ['nullable', 'confirmed', Password::min(8)],
+ 'password' => ['nullable', 'confirmed', PasswordPolicy::rule()],
'language' => 'nullable|string|in:'.$supportedLocales,
'country' => 'nullable|string|size:2|alpha',
'timezone' => ['nullable', 'string', 'timezone'],
diff --git a/app/Http/Requests/User/UploadAvatarRequest.php b/app/Http/Requests/User/UploadAvatarRequest.php
index 11d9413d..9c55a20a 100644
--- a/app/Http/Requests/User/UploadAvatarRequest.php
+++ b/app/Http/Requests/User/UploadAvatarRequest.php
@@ -24,6 +24,8 @@ class UploadAvatarRequest extends FormRequest
/**
* Determine if the user is authorized to make this request.
+ *
+ * @return bool
*/
public function authorize(): bool
{
@@ -46,7 +48,10 @@ class UploadAvatarRequest extends FormRequest
],
];
- return HookManager::applyFilters('core.user.upload_avatar_rules', $rules);
+ return HookManager::applyFiltersWithLegacyName(
+ 'core.user.upload_avatar_validation_rules',
+ 'core.user.upload_avatar_rules',
+ $rules);
}
/**
diff --git a/app/Http/Resources/ActivityLogCollection.php b/app/Http/Resources/ActivityLogCollection.php
index d17d5014..79930efa 100644
--- a/app/Http/Resources/ActivityLogCollection.php
+++ b/app/Http/Resources/ActivityLogCollection.php
@@ -3,7 +3,6 @@
namespace App\Http\Resources;
use Illuminate\Http\Request;
-use Illuminate\Pagination\LengthAwarePaginator;
/**
* 활동 로그 컬렉션 리소스
@@ -36,15 +35,10 @@ class ActivityLogCollection extends BaseApiCollection
'data' => $this->mapWithRowNumber(function ($activityLog) {
return (new ActivityLogResource($activityLog))->toArray(request());
}),
- 'pagination' => $this->resource instanceof LengthAwarePaginator ? [
- 'current_page' => $this->resource->currentPage(),
- 'last_page' => $this->resource->lastPage(),
- 'per_page' => $this->resource->perPage(),
- 'total' => $this->resource->total(),
- 'from' => $this->resource->firstItem(),
- 'to' => $this->resource->lastItem(),
- 'has_more_pages' => $this->resource->hasMorePages(),
- ] : null,
+ // 메타를 손으로 조립하면 정확도 필드(total_relation·total_is_exact·result_cap)가
+ // 빠진다. 그러면 상한에 걸려 잘린 건수가 화면에서 정확한 값처럼 읽힌다
+ // (실측: 실제 88,792 건이 "10000건" 으로 표기). 표준 메타 한 곳만 쓴다.
+ ...$this->paginationMeta(),
...($abilities ? ['abilities' => $abilities] : []),
];
}
diff --git a/app/Http/Resources/Admin/Identity/IdentityMessageDefinitionCollection.php b/app/Http/Resources/Admin/Identity/IdentityMessageDefinitionCollection.php
index 55e43ca4..4afb8622 100644
--- a/app/Http/Resources/Admin/Identity/IdentityMessageDefinitionCollection.php
+++ b/app/Http/Resources/Admin/Identity/IdentityMessageDefinitionCollection.php
@@ -36,15 +36,8 @@ class IdentityMessageDefinitionCollection extends BaseApiCollection
'data' => $this->mapWithRowNumber(function ($definition) use ($request) {
return (new IdentityMessageDefinitionResource($definition))->toArray($request);
}, $sortOrder),
- 'pagination' => [
- 'current_page' => $this->currentPage(),
- 'last_page' => $this->lastPage(),
- 'per_page' => $this->perPage(),
- 'total' => $this->total(),
- 'from' => $this->firstItem(),
- 'to' => $this->lastItem(),
- 'has_more_pages' => $this->hasMorePages(),
- ],
+ // 표준 메타를 쓴다 — 페이지 결과의 형태를 스스로 판정해 그 형태가 아는 값만 낸다.
+ ...$this->paginationMeta(),
...($abilities ? ['abilities' => $abilities] : []),
];
}
diff --git a/app/Http/Resources/Admin/Identity/IdentityMessageDefinitionResource.php b/app/Http/Resources/Admin/Identity/IdentityMessageDefinitionResource.php
index e82e5469..9b44bb60 100644
--- a/app/Http/Resources/Admin/Identity/IdentityMessageDefinitionResource.php
+++ b/app/Http/Resources/Admin/Identity/IdentityMessageDefinitionResource.php
@@ -4,6 +4,7 @@ namespace App\Http\Resources\Admin\Identity;
use App\Http\Resources\BaseApiResource;
use Illuminate\Http\Request;
+use Illuminate\Http\Resources\MissingValue;
/**
* IDV 메시지 정의 리소스.
@@ -60,9 +61,25 @@ class IdentityMessageDefinitionResource extends BaseApiResource
'is_active' => (bool) $this->getValue('is_active'),
'is_default' => (bool) $this->getValue('is_default'),
'user_overrides' => $this->getValue('user_overrides'),
- 'templates' => $this->relationLoaded('templates')
- ? IdentityMessageTemplateResource::collection($this->templates)
- : null,
+ // 목록은 대표 템플릿 1건만 로드하고(firstTemplate), 단건은 전체를 로드한다(templates).
+ // 화면 계약은 양쪽 모두 `templates` 배열이라 여기서 하나로 합류시킨다 —
+ // 로드된 쪽을 쓰고, 어느 쪽도 로드되지 않았으면 키 자체를 내보내지 않는다.
+ //
+ // 대표 템플릿 분기는 `whenLoaded` 로 쓸 수 없다. `whenLoaded($relation, $value)` 는
+ // 관계가 로드됐어도 값이 null 이면 $value 를 평가하지 않고 그대로 null 을 돌려준다
+ // (HasOne 이 0건이면 null). 그러면 "로드하지 않음"(null)과 "로드했더니 0건"(빈 배열)이
+ // 같은 값이 되어 소비자가 둘을 구분할 수 없다 — 관계 로드 여부는 직접 판정한다.
+ 'templates' => $this->whenLoaded(
+ 'templates',
+ fn () => IdentityMessageTemplateResource::collection($this->templates),
+ fn () => $this->resource->relationLoaded('firstTemplate')
+ ? ($this->firstTemplate
+ ? IdentityMessageTemplateResource::collection(collect([$this->firstTemplate]))
+ : [])
+ : new MissingValue,
+ ),
+ // 목록이 대표 1건만 싣기 때문에, "템플릿이 더 있는가" 는 배열 길이로 알 수 없다.
+ 'templates_count' => $this->whenHas('templates_count', fn () => (int) $this->templates_count),
...$this->formatTimestamps(),
...$this->resourceMeta($request),
];
diff --git a/app/Http/Resources/BaseApiCollection.php b/app/Http/Resources/BaseApiCollection.php
index 132a15b2..bc57f662 100644
--- a/app/Http/Resources/BaseApiCollection.php
+++ b/app/Http/Resources/BaseApiCollection.php
@@ -2,10 +2,15 @@
namespace App\Http\Resources;
+use App\Contracts\Pagination\BoundedTotalAware;
use App\Helpers\PermissionHelper;
use App\Http\Resources\Traits\HasRowNumber;
+use App\Support\Query\BoundedPage;
+use App\Support\Query\KeysetPaginator;
+use Illuminate\Contracts\Pagination\LengthAwarePaginator as LengthAwarePaginatorContract;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\ResourceCollection;
+use Illuminate\Pagination\CursorPaginator;
/**
* API 컬렉션 리소스 기본 클래스
@@ -61,24 +66,74 @@ abstract class BaseApiCollection extends ResourceCollection
* 정확히 판정할 수 있도록 노출합니다. 전체 조회(get) 등 paginator 가 아닌
* 경우에는 빈 배열을 반환하므로 toArray 에서 array_merge 로 안전하게 합칠 수 있습니다.
*
+ * 페이지 결과는 세 형태 중 하나이며, 형태를 스스로 판정해 그 형태가 실제로 아는
+ * 값만 내보냅니다. 모르는 값을 0 이나 1 로 채우면 화면이 그것을 사실로 읽습니다.
+ *
+ * | 형태 | 예 | total | last_page | 추가 |
+ * |---|---|---|---|---|
+ * | 전체건수형 | `paginate()` | 정확 | 정확 | — |
+ * | 상한형 | {@see BoundedPage} | 정확 또는 하한 | 하한이면 null | `total_relation` `total_is_exact` `result_cap` |
+ * | 단순형 | `simplePaginate()` / `cursorPaginate()` | 없음 | 없음 | 커서면 `next_cursor` `prev_cursor` |
+ *
+ * 기존 필드는 하나도 제거하지 않으므로, 표준 `paginate()` 를 쓰는 기존 컬렉션의
+ * 응답은 이전과 완전히 동일합니다.
+ *
* @return array ['pagination' => [...]] 또는 빈 배열
*/
protected function paginationMeta(): array
{
- if (! method_exists($this->resource, 'currentPage')) {
+ $resource = $this->resource;
+
+ if ($resource instanceof CursorPaginator) {
+ return ['pagination' => $this->cursorPaginationMeta($resource)];
+ }
+
+ if (! method_exists($resource, 'currentPage')) {
return [];
}
+ $meta = [
+ 'current_page' => $resource->currentPage(),
+ 'per_page' => $resource->perPage(),
+ 'from' => $resource->firstItem(),
+ 'to' => $resource->lastItem(),
+ 'has_more_pages' => $resource->hasMorePages(),
+ ];
+
+ // 단순형(simplePaginate)은 총 건수를 아예 세지 않으므로 total/last_page 를 내보내지 않는다.
+ if ($resource instanceof LengthAwarePaginatorContract) {
+ $meta['last_page'] = $resource->lastPage();
+ $meta['total'] = $resource->total();
+ }
+
+ if ($resource instanceof BoundedTotalAware) {
+ $meta['total_relation'] = $resource->totalRelation()->value;
+ $meta['total_is_exact'] = $resource->totalRelation()->isExact();
+ $meta['result_cap'] = $resource->resultCap();
+ }
+
+ return ['pagination' => $meta];
+ }
+
+ /**
+ * 커서 페이지의 pagination 메타를 만듭니다.
+ *
+ * 커서 방식은 총 건수와 페이지 번호를 계산하지 않습니다. 대신 앞뒤 이동 커서를
+ * 그대로 실어 보내며, 화면은 이 값으로 이전/다음 버튼을 만듭니다.
+ *
+ * 인코딩은 {@see KeysetPaginator} 를 거칩니다. 커서 문자열의 형식은 디코딩과 짝을
+ * 이뤄야 하므로, 한쪽만 여기서 직접 만들면 표준이 두 벌이 됩니다.
+ *
+ * @param CursorPaginator $resource 커서 페이지 결과
+ * @return array pagination 메타
+ */
+ private function cursorPaginationMeta(CursorPaginator $resource): array
+ {
return [
- 'pagination' => [
- 'current_page' => $this->resource->currentPage(),
- 'last_page' => $this->resource->lastPage(),
- 'per_page' => $this->resource->perPage(),
- 'total' => $this->resource->total(),
- 'from' => $this->resource->firstItem(),
- 'to' => $this->resource->lastItem(),
- 'has_more_pages' => $this->resource->hasMorePages(),
- ],
+ 'per_page' => $resource->perPage(),
+ 'has_more_pages' => $resource->hasMorePages(),
+ 'next_cursor' => KeysetPaginator::nextCursor($resource),
+ 'prev_cursor' => KeysetPaginator::previousCursor($resource),
];
}
}
diff --git a/app/Http/Resources/BaseApiResource.php b/app/Http/Resources/BaseApiResource.php
index 4217539f..b4b4a765 100644
--- a/app/Http/Resources/BaseApiResource.php
+++ b/app/Http/Resources/BaseApiResource.php
@@ -5,13 +5,16 @@ namespace App\Http\Resources;
use App\Helpers\TimezoneHelper;
use App\Http\Resources\Traits\HasAbilityCheck;
use Carbon\Carbon;
+use Illuminate\Database\Eloquent\Model;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;
+use Illuminate\Http\Resources\MissingValue;
use Illuminate\Support\Facades\App;
class BaseApiResource extends JsonResource
{
use HasAbilityCheck;
+
/**
* 리소스를 배열로 변환합니다.
*
@@ -122,6 +125,76 @@ class BaseApiResource extends JsonResource
];
}
+ /**
+ * 조건부 필드(`when()`)가 걸러지지 않은 배열에서 미충족 항목을 제거합니다.
+ *
+ * `toArray()` 결과는 Laravel 이 응답 직전에 `filter()` 로 `MissingValue` 를 걷어내지만,
+ * `toListArray()` 처럼 **배열을 그대로 컨트롤러에 넘기는 경로**는 그 단계를 거치지 않는다.
+ * 그대로 두면 조건 미충족 필드가 `"updated_at": {}` 같은 빈 객체로 응답에 실린다
+ * (예: `UPDATED_AT = null` 인 모델의 타임스탬프).
+ *
+ * @param array $data 직렬화 결과
+ * @return array 미충족 항목이 제거된 배열
+ */
+ protected function withoutMissing(array $data): array
+ {
+ return array_filter($data, fn ($value) => ! $value instanceof MissingValue);
+ }
+
+ /**
+ * 쿼리에서 계산된 집계 별칭(`withCount`/`withSum` 등)이 실제로 실려 있는지 판정합니다.
+ *
+ * 값 검사(`!== null`, `> 0`)로는 판정할 수 없다. SUM 은 대상 0건에서 NULL 을 돌려주고
+ * COUNT 는 0 을 돌려주므로, "집계하지 않았다" 와 "집계했더니 비어 있다" 가 구분되지 않는다.
+ * 속성 키의 존재 여부만이 두 상황을 가른다.
+ *
+ * @param string $alias 집계 별칭 (예: `options_count`)
+ * @return bool 집계가 실려 있는지 여부
+ */
+ protected function hasAggregate(string $alias): bool
+ {
+ $model = $this->unwrapResource();
+
+ return $model instanceof Model && array_key_exists($alias, $model->getAttributes());
+ }
+
+ /**
+ * 집계 별칭 값을 반환합니다. 집계가 실려 있지 않으면 기본값을 돌려줍니다.
+ *
+ * @param string $alias 집계 별칭
+ * @param mixed $default 집계 부재 시 사용할 값
+ * @return mixed 집계 값 또는 기본값
+ */
+ protected function aggregate(string $alias, mixed $default = null): mixed
+ {
+ $model = $this->unwrapResource();
+
+ if (! $model instanceof Model || ! array_key_exists($alias, $model->getAttributes())) {
+ return $default;
+ }
+
+ return $model->getAttributes()[$alias];
+ }
+
+ /**
+ * 리소스 래핑을 벗겨 원본 모델을 반환합니다.
+ *
+ * Resource 가 Resource 를 감싸는 경우(컬렉션 매핑 등)가 있어 한 겹만 벗기면 모델에
+ * 닿지 못한다.
+ *
+ * @return mixed 래핑이 제거된 리소스 본체
+ */
+ private function unwrapResource(): mixed
+ {
+ $model = $this->resource;
+
+ while ($model instanceof JsonResource) {
+ $model = $model->resource;
+ }
+
+ return $model;
+ }
+
/**
* datetime 값을 사용자 timezone으로 변환하여 ISO8601 문자열로 반환합니다.
*
diff --git a/app/Http/Resources/LanguagePackResource.php b/app/Http/Resources/LanguagePackResource.php
index 08826f3a..77e6ee05 100644
--- a/app/Http/Resources/LanguagePackResource.php
+++ b/app/Http/Resources/LanguagePackResource.php
@@ -3,9 +3,12 @@
namespace App\Http\Resources;
use App\Enums\LanguagePackOrigin;
+use App\Extension\Helpers\ChangelogParser;
use App\Helpers\TimezoneHelper;
use Carbon\Carbon;
use Illuminate\Http\Request;
+use Illuminate\Support\Facades\App;
+use Illuminate\Support\Facades\DB;
/**
* 언어팩 단건 API 리소스.
@@ -46,6 +49,8 @@ class LanguagePackResource extends BaseApiResource
'github_changelog_url' => $this->resolveManifestField('github_changelog_url'),
'bundled_identifier' => $this->getValue('bundled_identifier'),
'install_blocked_reason' => $this->getValue('install_blocked_reason'),
+ 'files_missing' => (bool) $this->getValue('files_missing', false),
+ 'bundled_source_available' => (bool) $this->getValue('bundled_source_available', false),
'target_name' => $this->resolveTargetName(),
'installed_at' => $this->formatTimestamp('installed_at'),
'activated_at' => $this->formatTimestamp('activated_at'),
@@ -82,7 +87,7 @@ class LanguagePackResource extends BaseApiResource
return null;
}
- $locale = \Illuminate\Support\Facades\App::getLocale();
+ $locale = App::getLocale();
$fallback = (string) config('app.fallback_locale', 'ko');
foreach ([$locale, $fallback, 'ko', 'en'] as $candidate) {
@@ -153,7 +158,7 @@ class LanguagePackResource extends BaseApiResource
$directoryPath = str_replace(base_path().DIRECTORY_SEPARATOR, '', $directory);
$changelogPath = $directory.DIRECTORY_SEPARATOR.'CHANGELOG.md';
if (is_file($changelogPath)) {
- $changelogEntries = \App\Extension\Helpers\ChangelogParser::parse($changelogPath);
+ $changelogEntries = ChangelogParser::parse($changelogPath);
}
} catch (\Throwable $e) {
$directoryPath = null;
@@ -185,6 +190,10 @@ class LanguagePackResource extends BaseApiResource
* 미설치 번들 가상 행(`status === uninstalled`)은 활성/비활성/제거 액션이
* 무의미하므로 `can_install` 만 노출합니다. 모듈/플러그인 행 액션과 동일 패턴.
*
+ * 드리프트 행(설치본 파일 부재 + 번들 소스 실재)은 설치 행이지만 "재설치로 복구" 가
+ * 유효한 액션이므로 `can_install` 을 함께 노출합니다. 이 플래그가 없으면 화면이
+ * 복구 버튼을 켤 근거가 없어, 드리프트가 보이기만 하고 고칠 수 없는 상태로 남습니다.
+ *
* @return array
*/
protected function abilityMap(): array
@@ -195,11 +204,17 @@ class LanguagePackResource extends BaseApiResource
];
}
- return [
+ $map = [
'can_activate' => 'core.language_packs.manage',
'can_deactivate' => 'core.language_packs.manage',
'can_uninstall' => 'core.language_packs.manage',
];
+
+ if ($this->getValue('files_missing') && $this->getValue('bundled_source_available')) {
+ $map['can_install'] = 'core.language_packs.install';
+ }
+
+ return $map;
}
/**
@@ -248,7 +263,7 @@ class LanguagePackResource extends BaseApiResource
return null;
}
- $row = \Illuminate\Support\Facades\DB::table($table)
+ $row = DB::table($table)
->where('identifier', $target)
->first(['name']);
if (! $row || ! $row->name) {
@@ -260,7 +275,7 @@ class LanguagePackResource extends BaseApiResource
return is_string($row->name) ? $row->name : null;
}
- $locale = \Illuminate\Support\Facades\App::getLocale();
+ $locale = App::getLocale();
return $decoded[$locale] ?? $decoded[config('app.fallback_locale', 'ko')] ?? (reset($decoded) ?: null);
}
diff --git a/app/Http/Resources/LayoutExtensionResource.php b/app/Http/Resources/LayoutExtensionResource.php
index 36a3dde6..fc8deb79 100644
--- a/app/Http/Resources/LayoutExtensionResource.php
+++ b/app/Http/Resources/LayoutExtensionResource.php
@@ -69,6 +69,56 @@ class LayoutExtensionResource extends BaseApiResource
];
}
+ /**
+ * 목록용 경량 배열로 변환합니다.
+ *
+ * 확장 목록은 라우트 트리에 "어느 화면에 어떤 확장이 붙어 있는가" 를 그리는 데 쓰입니다.
+ * 편집 본문(`content`)은 그 화면이 쓰지 않고 단건 조회가 공급하는데, 목록에 실리면 템플릿에
+ * 등록된 **모든 확장의 JSON 전문**이 한 응답에 담깁니다.
+ *
+ * 수정 여부(`is_modified`)와 크기(`size`/`size_formatted`)는 본문에서 계산하므로 값은 그대로
+ * 유지합니다 — 본문을 직렬화하지 않을 뿐, 계산은 서버에서 수행해 결과만 내려줍니다.
+ * (목록 화면이 확장마다 크기를 표시하므로 빼면 전 행이 `0 B` 로 보인다.)
+ *
+ * @param Request $request 요청 객체
+ * @return array 목록용 직렬화 결과
+ */
+ public function toListArray(Request $request): array
+ {
+ $content = $this->getValue('content', []);
+ $contentJson = is_array($content) ? json_encode($content, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) : '{}';
+
+ $extensionType = $this->getValue('extension_type');
+ $sourceType = $this->getValue('source_type');
+
+ // 이 배열은 컨트롤러가 그대로 응답에 싣는다 — Laravel 의 MissingValue 제거 단계를 거치지
+ // 않으므로 조건부 필드를 직접 걸러낸다.
+ return $this->withoutMissing([
+ 'id' => $this->getValue('id'),
+ 'extension_type' => $extensionType?->value ?? $extensionType,
+ 'target_name' => $this->getValue('target_name'),
+ 'source_type' => $sourceType?->value ?? $sourceType,
+ 'source_identifier' => $this->getValue('source_identifier'),
+ 'source_label' => $this->getValue('source_label', $this->getValue('source_identifier')),
+ 'is_override' => (bool) $this->getValue(
+ 'is_override',
+ ($sourceType?->value ?? $sourceType) === 'template'
+ ),
+ 'priority' => $this->getValue('priority'),
+ 'is_active' => (bool) $this->getValue('is_active'),
+ 'is_modified' => $this->resolveIsModified($content),
+ 'size' => strlen($contentJson),
+ 'size_formatted' => $this->formatFileSize(strlen($contentJson)),
+ 'host_layouts' => $this->getValue('host_layouts', []),
+ 'current_version' => $this->getValue('current_version') !== null
+ ? (int) $this->getValue('current_version')
+ : null,
+
+ ...$this->formatTimestamps(),
+ ...$this->resourceMeta($request),
+ ]);
+ }
+
/**
* 리소스별 권한 매핑을 반환합니다.
*
diff --git a/app/Http/Resources/LayoutExtensionVersionResource.php b/app/Http/Resources/LayoutExtensionVersionResource.php
index b83fb3e0..d8cb79e1 100644
--- a/app/Http/Resources/LayoutExtensionVersionResource.php
+++ b/app/Http/Resources/LayoutExtensionVersionResource.php
@@ -39,6 +39,33 @@ class LayoutExtensionVersionResource extends BaseApiResource
];
}
+ /**
+ * 목록용 경량 배열로 변환합니다.
+ *
+ * 버전 히스토리 패널이 쓰는 값은 버전 번호·변경 요약·저장자·저장 시각뿐입니다. 확장 본문
+ * (`content`)은 버전 비교 diff 전용이라 단건 조회가 공급합니다. 목록에 실으면 **버전마다**
+ * 확장 본문 사본이 실려, 저장을 반복한 확장일수록 목록 응답이 선형으로 커집니다.
+ * (레이아웃 본체 LayoutVersionResource 와 동일 정책)
+ *
+ * @param Request $request 요청 객체
+ * @return array 목록용 직렬화 결과
+ */
+ public function toListArray(Request $request): array
+ {
+ // 이 배열은 컨트롤러가 그대로 응답에 싣는다 — Laravel 의 MissingValue 제거 단계를 거치지
+ // 않으므로 조건부 필드를 직접 걸러낸다 (이 모델은 UPDATED_AT 이 없어 updated_at 이 미충족).
+ return $this->withoutMissing([
+ 'id' => $this->getValue('id'),
+ 'extension_id' => $this->getValue('extension_id'),
+ 'version' => $this->getValue('version'),
+ 'changes_summary' => $this->formatChangesSummary($this->getValue('changes_summary', [])),
+ 'created_by_name' => $this->resolveCreatorName(),
+
+ ...$this->formatTimestamps(),
+ ...$this->resourceMeta($request),
+ ]);
+ }
+
/**
* 저장자 이름을 해석합니다.
*
diff --git a/app/Http/Resources/LayoutListResource.php b/app/Http/Resources/LayoutListResource.php
new file mode 100644
index 00000000..bf8ddb71
--- /dev/null
+++ b/app/Http/Resources/LayoutListResource.php
@@ -0,0 +1,130 @@
+ 레이아웃 이름 → 라우트 path 매핑 */
+ private array $routePathMap = [];
+
+ /** @var array 소유 템플릿의 프론트엔드 다국어 사전 (점 표기 중첩) */
+ private array $translations = [];
+
+ /**
+ * 라우트 path 매핑을 주입합니다.
+ *
+ * @param array $routePathMap 레이아웃 이름 → 라우트 path
+ * @return $this
+ */
+ public function withRoutePathMap(array $routePathMap): self
+ {
+ $this->routePathMap = $routePathMap;
+
+ return $this;
+ }
+
+ /**
+ * 설명 해석에 쓸 소유 템플릿 사전을 주입합니다.
+ *
+ * @param array $translations 템플릿 프론트엔드 다국어 데이터
+ * @return $this
+ */
+ public function withTranslations(array $translations): self
+ {
+ $this->translations = $translations;
+
+ return $this;
+ }
+
+ /**
+ * 목록 행을 배열로 변환합니다.
+ *
+ * @param Request $request 요청 객체
+ * @return array 목록 행 데이터
+ */
+ public function toArray(Request $request): array
+ {
+ $name = $this->getValue('name');
+ $size = (int) $this->getValue('size', 0);
+
+ return [
+ 'id' => $this->getValue('id'),
+ 'template_id' => $this->getValue('template_id'),
+ 'name' => $name,
+ 'description' => LayoutDescription::resolve($this->getValue('description'), $name, $this->translations),
+
+ // 이 레이아웃을 사용하는 라우트의 path (routes.json 기준). 파일 선택 시 ?route=
+ // 동기화 / 위지윅에서 넘어온 ?route= 로 해당 파일 복원에 사용.
+ 'route_path' => $this->routePathMap[$name] ?? null,
+
+ 'size' => $size,
+ 'size_formatted' => $this->formatFileSize($size),
+ 'has_update' => false,
+
+ // 낙관적 잠금 — 편집 진입 후 저장 요청에 expected_lock_version 으로 전달
+ 'lock_version' => (int) $this->getValue('lock_version', 0),
+
+ // 상세 응답(LayoutResource)의 formatTimestamps() 와 같은 규약 — 사용자 timezone
+ // 기준 문자열이다. 원시 ISO 를 그대로 내보내면 목록의 수정일 표기만 형식이 달라진다.
+ 'created_at' => $this->formatDateTimeStringForUser($this->toCarbon($this->getValue('created_at'))),
+ 'updated_at' => $this->formatDateTimeStringForUser($this->toCarbon($this->getValue('updated_at'))),
+ ];
+ }
+
+ /**
+ * 값을 Carbon 인스턴스로 변환합니다.
+ *
+ * 경량 조회는 배열 행을 넘기므로 값이 Carbon 일 수도, 문자열일 수도, null 일 수도 있다.
+ *
+ * @param mixed $value 변환할 값
+ * @return Carbon|null 변환된 Carbon 또는 null
+ */
+ private function toCarbon(mixed $value): ?Carbon
+ {
+ if ($value === null || $value === '') {
+ return null;
+ }
+
+ return $value instanceof Carbon ? $value : Carbon::parse($value);
+ }
+
+ /**
+ * 파일 크기를 사람이 읽는 단위로 변환합니다.
+ *
+ * @param int $bytes 바이트 수
+ * @return string 변환된 크기 문자열
+ */
+ private function formatFileSize(int $bytes): string
+ {
+ if ($bytes < 1024) {
+ return $bytes.' B';
+ }
+
+ if ($bytes < 1048576) {
+ return round($bytes / 1024, 1).' KB';
+ }
+
+ return round($bytes / 1048576, 1).' MB';
+ }
+}
diff --git a/app/Http/Resources/LayoutResource.php b/app/Http/Resources/LayoutResource.php
index c7c2e53c..c8be3f80 100644
--- a/app/Http/Resources/LayoutResource.php
+++ b/app/Http/Resources/LayoutResource.php
@@ -2,6 +2,7 @@
namespace App\Http\Resources;
+use App\Support\LayoutDescription;
use Illuminate\Http\Request;
class LayoutResource extends BaseApiResource
@@ -16,6 +17,22 @@ class LayoutResource extends BaseApiResource
*/
protected array $routePathMap = [];
+ /** @var array 소유 템플릿의 프론트엔드 다국어 사전 */
+ protected array $translations = [];
+
+ /**
+ * 설명 해석에 쓸 소유 템플릿 사전을 주입합니다.
+ *
+ * @param array $translations 템플릿 프론트엔드 다국어 데이터
+ * @return $this
+ */
+ public function withTranslations(array $translations): static
+ {
+ $this->translations = $translations;
+
+ return $this;
+ }
+
/**
* 레이아웃 이름 → 라우트 path 매핑을 주입합니다.
*
@@ -45,7 +62,9 @@ class LayoutResource extends BaseApiResource
'id' => $this->getValue('id'),
'template_id' => $this->getValue('template_id'),
'name' => $name,
- 'description' => $content['meta']['description'] ?? $name,
+ // 설명은 소유 템플릿 사전 키를 쓰므로 서버가 해석한다 — 목록(LayoutListResource)과
+ // 같은 규칙이어야 파일 목록과 선택 파일 헤더의 표기가 어긋나지 않는다.
+ 'description' => LayoutDescription::resolve($content['meta']['description'] ?? null, $name, $this->translations),
'endpoint' => $content['endpoint'] ?? null,
// 이 레이아웃을 사용하는 라우트의 path (routes.json 기준). 코드 편집기가
// 파일 선택 시 ?route= 동기화 / 위지윅에서 넘어온 ?route= 복원에 사용.
diff --git a/app/Http/Resources/LayoutVersionResource.php b/app/Http/Resources/LayoutVersionResource.php
index c5554efc..98b3298a 100644
--- a/app/Http/Resources/LayoutVersionResource.php
+++ b/app/Http/Resources/LayoutVersionResource.php
@@ -2,6 +2,7 @@
namespace App\Http\Resources;
+use App\Models\User;
use Illuminate\Http\Request;
class LayoutVersionResource extends BaseApiResource
@@ -64,6 +65,36 @@ class LayoutVersionResource extends BaseApiResource
return $payload;
}
+ /**
+ * 목록용 경량 배열로 변환합니다.
+ *
+ * 버전 히스토리 패널이 쓰는 값은 버전 번호·변경 요약·저장자·저장 시각뿐입니다
+ * (`LayoutVersionSummary`). 분해된 본문(`components`/`data_sources`/`metadata`/`endpoint`)은
+ * 버전 비교 diff 전용이라 단건 조회가 공급합니다. 목록에 실으면 **버전마다** 레이아웃 본문
+ * 사본이 실려, 저장을 반복한 레이아웃일수록 목록 응답이 선형으로 커집니다.
+ *
+ * 종전 주석은 "목록에는 content 를 제외한다" 고 했지만 실제로 제외된 것은 `full_content`
+ * 하나뿐이었습니다 — 분해된 키들이 그대로 남아 사실상 본문이 다 실렸습니다.
+ *
+ * @param Request $request 현재 요청
+ * @return array 목록용 직렬화 결과
+ */
+ public function toListArray(Request $request): array
+ {
+ // 이 배열은 컨트롤러가 그대로 응답에 싣는다 — Laravel 의 MissingValue 제거 단계를 거치지
+ // 않으므로 조건부 필드를 직접 걸러낸다 (이 모델은 UPDATED_AT 이 없어 updated_at 이 미충족).
+ return $this->withoutMissing([
+ 'id' => $this->getValue('id'),
+ 'layout_id' => $this->getValue('layout_id'),
+ 'version' => $this->getValue('version'),
+ 'changes_summary' => $this->formatChangesSummary($this->getValue('changes_summary', [])),
+ 'created_by_name' => $this->resolveCreatorName(),
+
+ ...$this->formatTimestamps(),
+ ...$this->resourceMeta($request),
+ ]);
+ }
+
/**
* 저장자 이름을 해석합니다.
*
@@ -77,7 +108,7 @@ class LayoutVersionResource extends BaseApiResource
$creator = $this->whenLoaded('creator');
// whenLoaded 미로딩 시 MissingValue 반환 → 삼항으로 null 처리 (MissingValue 누출 방지).
- return $creator instanceof \App\Models\User ? $creator->name : null;
+ return $creator instanceof User ? $creator->name : null;
}
/**
diff --git a/app/Http/Resources/MenuResource.php b/app/Http/Resources/MenuResource.php
index cc78b0ff..069933ce 100644
--- a/app/Http/Resources/MenuResource.php
+++ b/app/Http/Resources/MenuResource.php
@@ -38,7 +38,7 @@ class MenuResource extends BaseApiResource
'children' => $this->whenLoaded('children', function () {
return $this->children->map(function ($child) {
- return [
+ $data = [
'id' => $child->id,
'name' => $child->name, // 다국어 객체 그대로 반환
'slug' => $child->slug,
@@ -49,14 +49,23 @@ class MenuResource extends BaseApiResource
'parent_id' => $child->parent_id,
'extension_type' => $child->extension_type?->value,
'extension_identifier' => $child->extension_identifier,
- 'roles' => $child->relationLoaded('roles') ? $child->roles->map(function ($role) {
+ ];
+
+ // 역할은 로드된 경우에만 싣는다. 미로드 시 `[]` 를 돌려주면 "역할 제한이
+ // 없다" 는 사실이 아닌 단언이 되어, 화면이 그 값을 그대로 저장에 실어
+ // 보내면 해당 메뉴의 역할 제한이 통째로 지워진다. 키 자체를 생략해
+ // 소비 측이 "모른다" 를 구분할 수 있게 한다 (단건 조회로 보강).
+ if ($child->relationLoaded('roles')) {
+ $data['roles'] = $child->roles->map(function ($role) {
return [
'id' => $role->id,
'name' => $role->name,
'permission_type' => $role->pivot->permission_type ?? null,
];
- }) : [],
- ];
+ })->values();
+ }
+
+ return $data;
})->sortBy('order')->values();
}),
diff --git a/app/Http/Resources/NotificationDefinitionCollection.php b/app/Http/Resources/NotificationDefinitionCollection.php
index 95868d79..aa65961f 100644
--- a/app/Http/Resources/NotificationDefinitionCollection.php
+++ b/app/Http/Resources/NotificationDefinitionCollection.php
@@ -19,7 +19,7 @@ class NotificationDefinitionCollection extends BaseApiCollection
/**
* 컬렉션을 배열로 변환합니다.
*
- * @param Request $request
+ * @param Request $request
* @return array
*/
public function toArray(Request $request): array
@@ -31,15 +31,8 @@ class NotificationDefinitionCollection extends BaseApiCollection
'data' => $this->mapWithRowNumber(function ($definition) use ($request) {
return (new NotificationDefinitionResource($definition))->toArray($request);
}, $sortOrder),
- 'pagination' => [
- 'current_page' => $this->currentPage(),
- 'last_page' => $this->lastPage(),
- 'per_page' => $this->perPage(),
- 'total' => $this->total(),
- 'from' => $this->firstItem(),
- 'to' => $this->lastItem(),
- 'has_more_pages' => $this->hasMorePages(),
- ],
+ // 표준 메타를 쓴다 — 페이지 결과의 형태를 스스로 판정해 그 형태가 아는 값만 낸다.
+ ...$this->paginationMeta(),
...($abilities ? ['abilities' => $abilities] : []),
];
}
diff --git a/app/Http/Resources/NotificationDefinitionResource.php b/app/Http/Resources/NotificationDefinitionResource.php
index 2e967444..591fd062 100644
--- a/app/Http/Resources/NotificationDefinitionResource.php
+++ b/app/Http/Resources/NotificationDefinitionResource.php
@@ -20,12 +20,15 @@ class NotificationDefinitionResource extends BaseApiResource
/**
* 리소스를 배열로 변환합니다.
*
- * @param Request $request
+ * @param Request $request
* @return array
*/
public function toArray(Request $request): array
{
- return [
+ // 컬렉션(NotificationDefinitionCollection)이 이 배열을 그대로 응답에 실어 Laravel 의
+ // MissingValue 제거 단계를 거치지 않는다 — 미충족 조건부 필드를 직접 걸러낸다.
+ // (걸러내지 않으면 `"templates": {}` 같은 빈 객체가 응답에 남는다)
+ return $this->withoutMissing([
'id' => $this->getValue('id'),
'type' => $this->getValue('type'),
'hook_prefix' => $this->getValue('hook_prefix'),
@@ -38,11 +41,19 @@ class NotificationDefinitionResource extends BaseApiResource
'hooks' => $this->getValue('hooks'),
'is_active' => (bool) $this->getValue('is_active'),
'is_default' => (bool) $this->getValue('is_default'),
- 'templates' => $this->relationLoaded('templates')
- ? NotificationTemplateResource::collection($this->templates)
- : null,
+ 'templates' => $this->whenLoaded(
+ 'templates',
+ fn () => NotificationTemplateResource::collection($this->templates)
+ ),
+ // 목록이 템플릿을 한 채널로 좁혀 싣기 때문에, "커스터마이즈된 템플릿이 있는가" 는
+ // 배열을 훑어서는 알 수 없다 (다른 채널만 수정한 경우를 놓친다). 되돌리기 버튼
+ // 노출 조건이 이 값에 의존하므로 집계로 내려보낸다.
+ 'has_customized_templates' => $this->whenHas(
+ 'customized_templates_count',
+ fn () => (int) $this->customized_templates_count > 0
+ ),
...$this->formatTimestamps(),
...$this->resourceMeta($request),
- ];
+ ]);
}
}
diff --git a/app/Http/Resources/NotificationLogCollection.php b/app/Http/Resources/NotificationLogCollection.php
index c0047cc3..651fed46 100644
--- a/app/Http/Resources/NotificationLogCollection.php
+++ b/app/Http/Resources/NotificationLogCollection.php
@@ -19,7 +19,7 @@ class NotificationLogCollection extends BaseApiCollection
/**
* 컬렉션을 배열로 변환합니다.
*
- * @param Request $request
+ * @param Request $request
* @return array
*/
public function toArray(Request $request): array
@@ -31,15 +31,10 @@ class NotificationLogCollection extends BaseApiCollection
'data' => $this->mapWithRowNumber(function ($log) use ($request) {
return (new NotificationLogResource($log))->toArray($request);
}, $sortOrder),
- 'pagination' => [
- 'current_page' => $this->resource->currentPage(),
- 'last_page' => $this->resource->lastPage(),
- 'per_page' => $this->resource->perPage(),
- 'total' => $this->resource->total(),
- 'from' => $this->resource->firstItem(),
- 'to' => $this->resource->lastItem(),
- 'has_more_pages' => $this->resource->hasMorePages(),
- ],
+ // 표준 메타를 쓴다. 이 목록은 커서 요청이면 CursorPaginator 로, 그 외에는 상한형
+ // 페이지로 온다. 손으로 조립하면 커서 결과에 없는 total()/lastPage() 를 불러
+ // 그 요청만 500 이 되고, 상한형에서는 정확도 메타가 빠진다.
+ ...$this->paginationMeta(),
...($abilities ? ['abilities' => $abilities] : []),
];
}
diff --git a/app/Http/Resources/RoleResource.php b/app/Http/Resources/RoleResource.php
index 6f844e8d..b3758dc7 100644
--- a/app/Http/Resources/RoleResource.php
+++ b/app/Http/Resources/RoleResource.php
@@ -37,6 +37,14 @@ class RoleResource extends BaseApiResource
$this->resource->users_count !== null,
fn () => $this->resource->users_count
),
+ // 목록은 권한 배열 3종을 싣지 않는다. 그 대신 "몇 개가 할당됐는가" 는 집계로 남긴다
+ // — 목록 화면이 권한 규모를 보여주면서도 권한 트리를 전송하지 않게 하는 대체 경로다.
+ // 값 검사(`!== null`)가 아니라 별칭 존재 여부로 판정한다: COUNT 는 0건에서도 0 을
+ // 돌려주므로 "집계하지 않았다" 와 "집계했더니 0" 이 구분되지 않는다.
+ 'permissions_count' => $this->whenHas(
+ 'permissions_count',
+ fn () => (int) $this->resource->permissions_count
+ ),
'permission_ids' => $this->when(
$this->resource->relationLoaded('permissions'),
fn () => $this->resource->permissions->pluck('id')->toArray()
diff --git a/app/Http/Resources/Traits/HasRowNumber.php b/app/Http/Resources/Traits/HasRowNumber.php
index e6ad272b..fd9fd304 100644
--- a/app/Http/Resources/Traits/HasRowNumber.php
+++ b/app/Http/Resources/Traits/HasRowNumber.php
@@ -2,6 +2,7 @@
namespace App\Http\Resources\Traits;
+use App\Contracts\Pagination\BoundedTotalAware;
use Illuminate\Pagination\LengthAwarePaginator;
use Illuminate\Support\Collection;
@@ -57,7 +58,7 @@ trait HasRowNumber
* @param int $total 전체 항목 수
* @param int $perPage 페이지당 항목 수
* @param int $currentPage 현재 페이지 번호
- * @return int 계산된 순번
+ * @return int|null 계산된 순번 (총 건수가 잘린 내림차순이면 null)
*/
protected function calculateRowNumber(
int $index,
@@ -65,13 +66,22 @@ trait HasRowNumber
int $total,
int $perPage,
int $currentPage
- ): int {
+ ): ?int {
if ($sortOrder === 'asc') {
// 오름차순: 1, 2, 3, ... (페이지별 연속)
// 예: 2페이지 → ((2-1) * 10) + 0 + 1 = 11, 12, 13, ...
+ // offset 만으로 정해지므로 총 건수가 잘려도 그대로 정확하다.
return (($currentPage - 1) * $perPage) + $index + 1;
}
+ // 내림차순 순번은 "전체 몇 건 중 몇 번째" 라 총 건수를 알아야 나온다. 총 건수가
+ // 상한에 걸려 잘렸으면 그 값으로 역산한 순번은 첫 페이지부터 이미 틀리고, 상한을
+ // 넘어선 페이지에서는 0 과 음수까지 내려간다. 틀린 숫자를 내보내는 것보다
+ // 내보내지 않는 편이 낫으므로 `last_page` 와 같은 원칙으로 null 을 돌려준다.
+ if ($this->resource instanceof BoundedTotalAware && ! $this->resource->totalRelation()->isExact()) {
+ return null;
+ }
+
// 내림차순: total, total-1, ... (역순)
// 예: 총 30개, 2페이지 → 30 - ((2-1) * 10) - 0 = 20, 19, 18, ...
return $total - (($currentPage - 1) * $perPage) - $index;
diff --git a/app/Http/Resources/UserNotificationCollection.php b/app/Http/Resources/UserNotificationCollection.php
index ecd1da1c..6da48dcd 100644
--- a/app/Http/Resources/UserNotificationCollection.php
+++ b/app/Http/Resources/UserNotificationCollection.php
@@ -5,14 +5,16 @@ namespace App\Http\Resources;
use App\Contracts\Repositories\NotificationDefinitionRepositoryInterface;
use Illuminate\Http\Request;
+/**
+ * 알림함 컬렉션
+ */
class UserNotificationCollection extends BaseApiCollection
{
-
/**
* 컬렉션을 배열로 변환합니다.
*
- * @param Request $request
- * @return array
+ * @param Request $request HTTP 요청
+ * @return array 변환된 배열
*/
public function toArray(Request $request): array
{
@@ -29,15 +31,10 @@ class UserNotificationCollection extends BaseApiCollection
->withTypeLabelMap($typeLabelMap)
->toArray($request);
}, $sortOrder),
- 'pagination' => [
- 'current_page' => $this->resource->currentPage(),
- 'last_page' => $this->resource->lastPage(),
- 'per_page' => $this->resource->perPage(),
- 'total' => $this->resource->total(),
- 'from' => $this->resource->firstItem(),
- 'to' => $this->resource->lastItem(),
- 'has_more_pages' => $this->resource->hasMorePages(),
- ],
+ // 표준 메타를 쓴다. 손으로 조립하면 페이지 결과의 형태(전체건수형/상한형/단순형)를
+ // 구분하지 못해, 상한에 걸려 잘린 총 건수가 정확한 값처럼 나가고 마지막 페이지도
+ // 계산할 수 없는데 숫자가 채워진다.
+ ...$this->paginationMeta(),
];
}
}
diff --git a/app/Http/Resources/UserResource.php b/app/Http/Resources/UserResource.php
index 6abc8929..3c397b3b 100644
--- a/app/Http/Resources/UserResource.php
+++ b/app/Http/Resources/UserResource.php
@@ -260,6 +260,14 @@ class UserResource extends BaseApiResource
'blocked_at' => $this->getValue('blocked_at')
? $this->formatDateTimeStringForUser($this->getValue('blocked_at'))
: null,
+ // 로그인 실패 누적 잠금 상태 — 관리자만 확인·해제할 수 있어야 하므로 관리자 응답에만 노출
+ 'failed_login_attempts' => (int) ($this->getValue('failed_login_attempts') ?? 0),
+ 'locked_permanently' => (bool) $this->getValue('locked_permanently'),
+ 'locked_until' => $this->getValue('locked_until')
+ ? $this->formatDateTimeStringForUser($this->getValue('locked_until'))
+ : null,
+ 'is_locked' => (bool) $this->getValue('locked_permanently')
+ || ($this->getValue('locked_until') !== null && $this->resource->locked_until?->isFuture()),
]);
// Filter 훅: 모듈이 자신의 데이터를 응답에 병합
diff --git a/app/Http/View/Composers/TemplateComposer.php b/app/Http/View/Composers/TemplateComposer.php
index 5d565fb3..716dfbd1 100644
--- a/app/Http/View/Composers/TemplateComposer.php
+++ b/app/Http/View/Composers/TemplateComposer.php
@@ -8,17 +8,18 @@ use App\Extension\PluginManager;
use App\Extension\TemplateManager;
use App\Extension\Traits\ClearsTemplateCaches;
use App\Http\View\Composers\Traits\CollectsActiveExtensionMeta;
+use App\Http\View\Composers\Traits\CollectsExtensionAssets;
use App\Http\View\Composers\Traits\CollectsTemplateExternals;
use App\Services\ModuleSettingsService;
use App\Services\PluginSettingsService;
use App\Services\SettingsService;
use App\Services\TemplateService;
-use Illuminate\Support\Facades\Log;
use Illuminate\View\View;
class TemplateComposer
{
use CollectsActiveExtensionMeta;
+ use CollectsExtensionAssets;
use CollectsTemplateExternals;
/**
@@ -115,156 +116,4 @@ class TemplateComposer
$view->with('appConfig', $appConfig);
$view->with('templateExternals', $templateExternals);
}
-
- /**
- * 확장 프론트엔드 병합 번들 URL을 계산합니다.
- *
- * 활성 global 에셋(JS/CSS)이 하나라도 있는 타입만 해당 번들 URL을 채우고,
- * 없으면 null을 두어 프론트가 로드를 스킵하게 한다. URL은 same-origin
- * (`/api/...`)이어야 gdpr preblocker 의 same-origin 통과 규칙에 자기 차단되지
- * 않는다(CDN 호스팅 금지).
- *
- * @param array $moduleAssets 수집된 모듈 개별 에셋 맵
- * @param array $pluginAssets 수집된 플러그인 개별 에셋 맵
- * @param int $version 확장 캐시 버전
- * @return array{moduleJs: ?string, moduleCss: ?string, pluginJs: ?string, pluginCss: ?string}
- */
- private function buildExtensionBundleUrls(array $moduleAssets, array $pluginAssets, int $version): array
- {
- $hasJs = static fn (array $assets): bool => ! empty(array_filter($assets, fn ($a) => ! empty($a['js'])));
- $hasCss = static fn (array $assets): bool => ! empty(array_filter($assets, fn ($a) => ! empty($a['css'])));
-
- return [
- 'moduleJs' => $hasJs($moduleAssets) ? "/api/modules/bundle.js?v={$version}" : null,
- 'moduleCss' => $hasCss($moduleAssets) ? "/api/modules/bundle.css?v={$version}" : null,
- 'pluginJs' => $hasJs($pluginAssets) ? "/api/plugins/bundle.js?v={$version}" : null,
- 'pluginCss' => $hasCss($pluginAssets) ? "/api/plugins/bundle.css?v={$version}" : null,
- ];
- }
-
- /**
- * 활성화된 모듈의 프론트엔드 에셋 정보를 수집합니다.
- *
- * @return array
- */
- private function collectModuleAssets(): array
- {
- $assets = [];
-
- try {
- // ModuleManager에서 활성화된 모듈 목록 조회
- $activeModules = $this->moduleManager->getActiveModules();
-
- // 캐시 버전 조회 (브라우저 캐시 무효화용)
- $cacheVersion = ClearsTemplateCaches::getExtensionCacheVersion();
-
- foreach ($activeModules as $identifier => $module) {
- // 모듈에 에셋이 있는지 확인
- if (! $module->hasAssets()) {
- continue;
- }
-
- $builtPaths = $module->getBuiltAssetPaths();
- $loadingConfig = $module->getAssetLoadingConfig();
- $assetConfig = $module->getAssets();
-
- // global 전략인 경우에만 수집 (layout, lazy는 레이아웃에서 처리)
- if ($loadingConfig['strategy'] !== 'global') {
- continue;
- }
-
- $moduleAsset = [
- 'priority' => $loadingConfig['priority'],
- ];
-
- // JS 빌드 경로 (캐시 버전 파라미터 추가)
- if (! empty($builtPaths['js'])) {
- $moduleAsset['js'] = "/api/modules/assets/{$identifier}/".$builtPaths['js']."?v={$cacheVersion}";
- }
-
- // CSS 빌드 경로 (캐시 버전 파라미터 추가)
- if (! empty($builtPaths['css'])) {
- $moduleAsset['css'] = "/api/modules/assets/{$identifier}/".$builtPaths['css']."?v={$cacheVersion}";
- }
-
- // 외부 스크립트 (조건부 로드용)
- if (! empty($assetConfig['external'])) {
- $moduleAsset['external'] = $assetConfig['external'];
- }
-
- $assets[$identifier] = $moduleAsset;
- }
-
- // 우선순위 기준 정렬 (낮을수록 먼저)
- uasort($assets, fn ($a, $b) => $a['priority'] <=> $b['priority']);
- } catch (\Exception $e) {
- // 에러 발생 시 빈 배열 반환 (에셋 로드 실패해도 앱 진행)
- Log::warning('Failed to collect module assets: '.$e->getMessage());
- }
-
- return $assets;
- }
-
- /**
- * 활성화된 플러그인의 프론트엔드 에셋 정보를 수집합니다.
- *
- * @return array
- */
- private function collectPluginAssets(): array
- {
- $assets = [];
-
- try {
- // PluginManager에서 활성화된 플러그인 목록 조회
- $activePlugins = $this->pluginManager->getActivePlugins();
-
- // 캐시 버전 조회 (브라우저 캐시 무효화용)
- $cacheVersion = ClearsTemplateCaches::getExtensionCacheVersion();
-
- foreach ($activePlugins as $identifier => $plugin) {
- // 플러그인에 에셋이 있는지 확인
- if (! $plugin->hasAssets()) {
- continue;
- }
-
- $builtPaths = $plugin->getBuiltAssetPaths();
- $loadingConfig = $plugin->getAssetLoadingConfig();
- $assetConfig = $plugin->getAssets();
-
- // global 전략인 경우에만 수집 (layout, lazy는 레이아웃에서 처리)
- if ($loadingConfig['strategy'] !== 'global') {
- continue;
- }
-
- $pluginAsset = [
- 'priority' => $loadingConfig['priority'],
- ];
-
- // JS 빌드 경로 (캐시 버전 파라미터 추가)
- if (! empty($builtPaths['js'])) {
- $pluginAsset['js'] = "/api/plugins/assets/{$identifier}/".$builtPaths['js']."?v={$cacheVersion}";
- }
-
- // CSS 빌드 경로 (캐시 버전 파라미터 추가)
- if (! empty($builtPaths['css'])) {
- $pluginAsset['css'] = "/api/plugins/assets/{$identifier}/".$builtPaths['css']."?v={$cacheVersion}";
- }
-
- // 외부 스크립트 (조건부 로드용)
- if (! empty($assetConfig['external'])) {
- $pluginAsset['external'] = $assetConfig['external'];
- }
-
- $assets[$identifier] = $pluginAsset;
- }
-
- // 우선순위 기준 정렬 (낮을수록 먼저)
- uasort($assets, fn ($a, $b) => $a['priority'] <=> $b['priority']);
- } catch (\Exception $e) {
- // 에러 발생 시 빈 배열 반환 (에셋 로드 실패해도 앱 진행)
- Log::warning('Failed to collect plugin assets: '.$e->getMessage());
- }
-
- return $assets;
- }
}
diff --git a/app/Http/View/Composers/Traits/CollectsExtensionAssets.php b/app/Http/View/Composers/Traits/CollectsExtensionAssets.php
new file mode 100644
index 00000000..bb009985
--- /dev/null
+++ b/app/Http/View/Composers/Traits/CollectsExtensionAssets.php
@@ -0,0 +1,143 @@
+ $moduleAssets 수집된 모듈 개별 에셋 맵
+ * @param array $pluginAssets 수집된 플러그인 개별 에셋 맵
+ * @param int $version 확장 캐시 버전
+ * @return array{moduleJs: ?string, moduleCss: ?string, pluginJs: ?string, pluginCss: ?string} 번들 URL 맵
+ */
+ private function buildExtensionBundleUrls(array $moduleAssets, array $pluginAssets, int $version): array
+ {
+ $hasJs = static fn (array $assets): bool => ! empty(array_filter($assets, fn ($a) => ! empty($a['js'])));
+ $hasCss = static fn (array $assets): bool => ! empty(array_filter($assets, fn ($a) => ! empty($a['css'])));
+
+ return [
+ 'moduleJs' => $hasJs($moduleAssets) ? AssetUrl::extensionBundle('modules', 'js', $version) : null,
+ 'moduleCss' => $hasCss($moduleAssets) ? AssetUrl::extensionBundle('modules', 'css', $version) : null,
+ 'pluginJs' => $hasJs($pluginAssets) ? AssetUrl::extensionBundle('plugins', 'js', $version) : null,
+ 'pluginCss' => $hasCss($pluginAssets) ? AssetUrl::extensionBundle('plugins', 'css', $version) : null,
+ ];
+ }
+
+ /**
+ * 활성화된 모듈의 프론트엔드 에셋 정보를 수집합니다.
+ *
+ * @return array 식별자별 에셋 맵
+ */
+ private function collectModuleAssets(): array
+ {
+ return $this->collectExtensionAssets(
+ 'modules',
+ fn () => $this->moduleManager->getActiveModules(),
+ 'Failed to collect module assets: '
+ );
+ }
+
+ /**
+ * 활성화된 플러그인의 프론트엔드 에셋 정보를 수집합니다.
+ *
+ * @return array 식별자별 에셋 맵
+ */
+ private function collectPluginAssets(): array
+ {
+ return $this->collectExtensionAssets(
+ 'plugins',
+ fn () => $this->pluginManager->getActivePlugins(),
+ 'Failed to collect plugin assets: '
+ );
+ }
+
+ /**
+ * 확장 에셋 수집 공통 구현.
+ *
+ * 모듈/플러그인은 수집 대상 조회 방법과 로그 문구만 다르고 나머지 로직이 동일하다.
+ *
+ * @param string $type `modules` 또는 `plugins`
+ * @param callable $activeResolver 활성 확장 목록을 반환하는 콜백
+ * @param string $logPrefix 실패 시 경고 로그 접두사
+ * @return array 식별자별 에셋 맵
+ */
+ private function collectExtensionAssets(string $type, callable $activeResolver, string $logPrefix): array
+ {
+ $assets = [];
+
+ try {
+ $active = $activeResolver();
+
+ // 캐시 버전 조회 (브라우저 캐시 무효화용)
+ $cacheVersion = ClearsTemplateCaches::getExtensionCacheVersion();
+
+ foreach ($active as $identifier => $extension) {
+ // 확장에 에셋이 있는지 확인
+ if (! $extension->hasAssets()) {
+ continue;
+ }
+
+ $builtPaths = $extension->getBuiltAssetPaths();
+ $loadingConfig = $extension->getAssetLoadingConfig();
+ $assetConfig = $extension->getAssets();
+
+ // global 전략인 경우에만 수집 (layout, lazy는 레이아웃에서 처리)
+ if ($loadingConfig['strategy'] !== 'global') {
+ continue;
+ }
+
+ $asset = [
+ 'priority' => $loadingConfig['priority'],
+ ];
+
+ // JS 빌드 경로 (캐시 버전 파라미터 추가)
+ if (! empty($builtPaths['js'])) {
+ $asset['js'] = AssetUrl::extensionAsset($type, $identifier, $builtPaths['js'], $cacheVersion);
+ }
+
+ // CSS 빌드 경로 (캐시 버전 파라미터 추가)
+ if (! empty($builtPaths['css'])) {
+ $asset['css'] = AssetUrl::extensionAsset($type, $identifier, $builtPaths['css'], $cacheVersion);
+ }
+
+ // 외부 스크립트 (조건부 로드용)
+ if (! empty($assetConfig['external'])) {
+ $asset['external'] = $assetConfig['external'];
+ }
+
+ $assets[$identifier] = $asset;
+ }
+
+ // 우선순위 기준 정렬 (낮을수록 먼저)
+ uasort($assets, fn ($a, $b) => $a['priority'] <=> $b['priority']);
+ } catch (\Exception $e) {
+ // 에러 발생 시 빈 배열 반환 (에셋 로드 실패해도 앱 진행)
+ Log::warning($logPrefix.$e->getMessage());
+ }
+
+ return $assets;
+ }
+}
diff --git a/app/Http/View/Composers/UserTemplateComposer.php b/app/Http/View/Composers/UserTemplateComposer.php
index d145b0b1..5188e100 100644
--- a/app/Http/View/Composers/UserTemplateComposer.php
+++ b/app/Http/View/Composers/UserTemplateComposer.php
@@ -8,12 +8,12 @@ use App\Extension\PluginManager;
use App\Extension\TemplateManager;
use App\Extension\Traits\ClearsTemplateCaches;
use App\Http\View\Composers\Traits\CollectsActiveExtensionMeta;
+use App\Http\View\Composers\Traits\CollectsExtensionAssets;
use App\Http\View\Composers\Traits\CollectsTemplateExternals;
use App\Services\ModuleSettingsService;
use App\Services\PluginSettingsService;
use App\Services\SettingsService;
use App\Services\TemplateService;
-use Illuminate\Support\Facades\Log;
use Illuminate\View\View;
/**
@@ -24,6 +24,7 @@ use Illuminate\View\View;
class UserTemplateComposer
{
use CollectsActiveExtensionMeta;
+ use CollectsExtensionAssets;
use CollectsTemplateExternals;
/**
@@ -121,156 +122,4 @@ class UserTemplateComposer
$view->with('appConfig', $appConfig);
$view->with('templateExternals', $templateExternals);
}
-
- /**
- * 확장 프론트엔드 병합 번들 URL을 계산합니다.
- *
- * 활성 global 에셋(JS/CSS)이 하나라도 있는 타입만 해당 번들 URL을 채우고,
- * 없으면 null을 두어 프론트가 로드를 스킵하게 한다. URL은 same-origin
- * (`/api/...`)이어야 gdpr preblocker 의 same-origin 통과 규칙에 자기 차단되지
- * 않는다(CDN 호스팅 금지).
- *
- * @param array $moduleAssets 수집된 모듈 개별 에셋 맵
- * @param array $pluginAssets 수집된 플러그인 개별 에셋 맵
- * @param int $version 확장 캐시 버전
- * @return array{moduleJs: ?string, moduleCss: ?string, pluginJs: ?string, pluginCss: ?string}
- */
- private function buildExtensionBundleUrls(array $moduleAssets, array $pluginAssets, int $version): array
- {
- $hasJs = static fn (array $assets): bool => ! empty(array_filter($assets, fn ($a) => ! empty($a['js'])));
- $hasCss = static fn (array $assets): bool => ! empty(array_filter($assets, fn ($a) => ! empty($a['css'])));
-
- return [
- 'moduleJs' => $hasJs($moduleAssets) ? "/api/modules/bundle.js?v={$version}" : null,
- 'moduleCss' => $hasCss($moduleAssets) ? "/api/modules/bundle.css?v={$version}" : null,
- 'pluginJs' => $hasJs($pluginAssets) ? "/api/plugins/bundle.js?v={$version}" : null,
- 'pluginCss' => $hasCss($pluginAssets) ? "/api/plugins/bundle.css?v={$version}" : null,
- ];
- }
-
- /**
- * 활성화된 모듈의 프론트엔드 에셋 정보를 수집합니다.
- *
- * @return array
- */
- private function collectModuleAssets(): array
- {
- $assets = [];
-
- try {
- // ModuleManager에서 활성화된 모듈 목록 조회
- $activeModules = $this->moduleManager->getActiveModules();
-
- // 캐시 버전 조회 (브라우저 캐시 무효화용)
- $cacheVersion = ClearsTemplateCaches::getExtensionCacheVersion();
-
- foreach ($activeModules as $identifier => $module) {
- // 모듈에 에셋이 있는지 확인
- if (! $module->hasAssets()) {
- continue;
- }
-
- $builtPaths = $module->getBuiltAssetPaths();
- $loadingConfig = $module->getAssetLoadingConfig();
- $assetConfig = $module->getAssets();
-
- // global 전략인 경우에만 수집 (layout, lazy는 레이아웃에서 처리)
- if ($loadingConfig['strategy'] !== 'global') {
- continue;
- }
-
- $moduleAsset = [
- 'priority' => $loadingConfig['priority'],
- ];
-
- // JS 빌드 경로 (캐시 버전 파라미터 추가)
- if (! empty($builtPaths['js'])) {
- $moduleAsset['js'] = "/api/modules/assets/{$identifier}/".$builtPaths['js']."?v={$cacheVersion}";
- }
-
- // CSS 빌드 경로 (캐시 버전 파라미터 추가)
- if (! empty($builtPaths['css'])) {
- $moduleAsset['css'] = "/api/modules/assets/{$identifier}/".$builtPaths['css']."?v={$cacheVersion}";
- }
-
- // 외부 스크립트 (조건부 로드용)
- if (! empty($assetConfig['external'])) {
- $moduleAsset['external'] = $assetConfig['external'];
- }
-
- $assets[$identifier] = $moduleAsset;
- }
-
- // 우선순위 기준 정렬 (낮을수록 먼저)
- uasort($assets, fn ($a, $b) => $a['priority'] <=> $b['priority']);
- } catch (\Exception $e) {
- // 에러 발생 시 빈 배열 반환 (에셋 로드 실패해도 앱 진행)
- Log::warning('Failed to collect module assets: '.$e->getMessage());
- }
-
- return $assets;
- }
-
- /**
- * 활성화된 플러그인의 프론트엔드 에셋 정보를 수집합니다.
- *
- * @return array
- */
- private function collectPluginAssets(): array
- {
- $assets = [];
-
- try {
- // PluginManager에서 활성화된 플러그인 목록 조회
- $activePlugins = $this->pluginManager->getActivePlugins();
-
- // 캐시 버전 조회 (브라우저 캐시 무효화용)
- $cacheVersion = ClearsTemplateCaches::getExtensionCacheVersion();
-
- foreach ($activePlugins as $identifier => $plugin) {
- // 플러그인에 에셋이 있는지 확인
- if (! $plugin->hasAssets()) {
- continue;
- }
-
- $builtPaths = $plugin->getBuiltAssetPaths();
- $loadingConfig = $plugin->getAssetLoadingConfig();
- $assetConfig = $plugin->getAssets();
-
- // global 전략인 경우에만 수집 (layout, lazy는 레이아웃에서 처리)
- if ($loadingConfig['strategy'] !== 'global') {
- continue;
- }
-
- $pluginAsset = [
- 'priority' => $loadingConfig['priority'],
- ];
-
- // JS 빌드 경로 (캐시 버전 파라미터 추가)
- if (! empty($builtPaths['js'])) {
- $pluginAsset['js'] = "/api/plugins/assets/{$identifier}/".$builtPaths['js']."?v={$cacheVersion}";
- }
-
- // CSS 빌드 경로 (캐시 버전 파라미터 추가)
- if (! empty($builtPaths['css'])) {
- $pluginAsset['css'] = "/api/plugins/assets/{$identifier}/".$builtPaths['css']."?v={$cacheVersion}";
- }
-
- // 외부 스크립트 (조건부 로드용)
- if (! empty($assetConfig['external'])) {
- $pluginAsset['external'] = $assetConfig['external'];
- }
-
- $assets[$identifier] = $pluginAsset;
- }
-
- // 우선순위 기준 정렬 (낮을수록 먼저)
- uasort($assets, fn ($a, $b) => $a['priority'] <=> $b['priority']);
- } catch (\Exception $e) {
- // 에러 발생 시 빈 배열 반환 (에셋 로드 실패해도 앱 진행)
- Log::warning('Failed to collect plugin assets: '.$e->getMessage());
- }
-
- return $assets;
- }
}
diff --git a/app/Jobs/DispatchHookListenerJob.php b/app/Jobs/DispatchHookListenerJob.php
index 3bcee7a6..9371090f 100644
--- a/app/Jobs/DispatchHookListenerJob.php
+++ b/app/Jobs/DispatchHookListenerJob.php
@@ -1,10 +1,14 @@
context);
+ // 큐 드라이버가 sync 면 이 Job 은 원 HTTP 요청과 **같은 컨테이너**에서 실행된다.
+ // restore() 가 재구성 Request 를 바인딩하면 그 뒤로 이어지는 같은 요청의 코드는
+ // 헤더·입력·메서드가 전부 지워진 가짜 GET 요청을 보게 된다 — 뒤 순위 훅 리스너가
+ // 전송 헤더를 읽지 못해 조용히 건너뛰는 사고가 여기서 난다.
+ // 워커 프로세스에서는 원래 바인딩이 없어 아래 원복이 아무 일도 하지 않는다.
+ $previousRequest = app()->bound('request') ? app('request') : null;
- $args = HookArgumentSerializer::deserialize($this->serializedArgs);
- app($this->listenerClass)->{$this->method}(...$args);
+ try {
+ HookContextCapture::restore($this->context);
+
+ $args = HookArgumentSerializer::deserialize($this->serializedArgs);
+
+ try {
+ $listener = app($this->listenerClass);
+ } catch (BindingResolutionException $e) {
+ // 리스너를 만들 수 없다는 것은 그 확장이 이 런타임에 배선되지 않았다는 뜻이다.
+ // Action 훅은 부가 작업이므로 호출자의 작업까지 함께 실패시키지 않고 기록만 남긴다
+ // (큐 드라이버가 sync 인 환경에서 원 요청이 500 이 되는 것을 막는다).
+ Log::warning('훅 리스너를 해석할 수 없어 건너뜁니다 (확장 미배선)', [
+ 'listener' => $this->listenerClass,
+ 'method' => $this->method,
+ 'exception' => $e->getMessage(),
+ ]);
+
+ return;
+ }
+
+ $listener->{$this->method}(...$args);
+ } finally {
+ if ($previousRequest !== null) {
+ app()->instance('request', $previousRequest);
+ }
+ }
}
/**
* Job 실패 시 로그를 기록합니다.
*
* @param \Throwable $exception 발생한 예외
- * @return void
*/
public function failed(\Throwable $exception): void
{
@@ -76,8 +102,6 @@ class DispatchHookListenerJob implements ShouldQueue
/**
* Job의 표시 이름을 반환합니다.
- *
- * @return string
*/
public function displayName(): string
{
diff --git a/app/Jobs/GenerateSitemapJob.php b/app/Jobs/GenerateSitemapJob.php
index df419daf..be491038 100644
--- a/app/Jobs/GenerateSitemapJob.php
+++ b/app/Jobs/GenerateSitemapJob.php
@@ -2,8 +2,12 @@
namespace App\Jobs;
+use App\Enums\SitemapGenerationMode;
+use App\Extension\HookManager;
use App\Seo\SitemapManager;
+use App\Seo\SitemapProgress;
use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldBeUnique;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
@@ -13,22 +17,82 @@ use Illuminate\Support\Facades\Log;
/**
* Sitemap XML 생성 큐 잡
*
- * 스케줄러 또는 Artisan 커맨드에서 디스패치되며,
+ * 스케줄러, Artisan 커맨드, 관리자 수동 재생성, 봇 요청 캐시 미스에서 디스패치되며,
* 실제 생성 로직은 SitemapManager 서비스에 위임합니다.
+ *
+ * 대용량(수백만 URL) 생성은 수 분~수십 분이 걸리므로 동시 실행을 막고(ShouldBeUnique)
+ * 타임아웃/재시도 한계를 넉넉히 잡되, 재시도가 무한히 누적되지 않도록 retryUntil 로 제한합니다.
*/
-class GenerateSitemapJob implements ShouldQueue
+class GenerateSitemapJob implements ShouldBeUnique, ShouldQueue
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+ /**
+ * @var string 전용 큐 이름 — 대용량·장시간 사이트맵 생성을 default 큐에서 분리한다.
+ *
+ * 이 큐에는 반드시 워커를 1개만 배치한다(동시 중복 생성 방지). 그러면
+ * 긴 생성 작업이 default 큐의 방송/알림을 막지 않아 진행상황이 실시간으로 흐르고,
+ * 워커가 1개뿐이라 잡이 동시에 두 번 실행되지 않는다.
+ */
+ public const QUEUE = 'sitemap';
+
/**
* @var int 최대 재시도 횟수
*/
public int $tries = 3;
/**
- * @var int 타임아웃 (초)
+ * @var int 타임아웃 (초) — 대용량 스트리밍 생성 대응
*/
- public int $timeout = 300;
+ public int $timeout = 1800;
+
+ /**
+ * @var int 재시도 대기 시간 (초)
+ */
+ public int $backoff = 120;
+
+ /**
+ * @var int 유니크 락 유지 시간 (초) — 잡이 비정상 종료해도 이 시간 후 자동 해제
+ */
+ public int $uniqueFor = 900;
+
+ /**
+ * GenerateSitemapJob 생성자
+ *
+ * @param SitemapGenerationMode $mode 재생성 모드 — SitemapManager 로 전달
+ * @param int|null $triggeredBy 관리자 수동 재생성을 실행한 사용자 ID(스케줄러/증분/봇 = null).
+ * 완료/실패 알림의 수신자(수동 실행자) 판정에 사용됩니다.
+ */
+ public function __construct(
+ public SitemapGenerationMode $mode = SitemapGenerationMode::Auto,
+ public ?int $triggeredBy = null,
+ ) {
+ $this->onQueue(self::QUEUE);
+ }
+
+ /**
+ * 유니크 락 식별자를 반환합니다.
+ *
+ * 봇 요청 캐시 미스마다 디스패치되어도 큐에는 한 건만 남도록 고정 키를 사용합니다.
+ *
+ * @return string 유니크 락 키
+ */
+ public function uniqueId(): string
+ {
+ return 'seo-sitemap';
+ }
+
+ /**
+ * 재시도 마감 시각을 반환합니다.
+ *
+ * timeout(1800초) × tries(3) 만큼 재시도가 누적되는 것을 막습니다.
+ *
+ * @return \DateTime 재시도 마감 시각
+ */
+ public function retryUntil(): \DateTime
+ {
+ return now()->addMinutes(30)->toDateTime();
+ }
/**
* Sitemap 을 생성하고 캐시에 저장합니다.
@@ -37,7 +101,7 @@ class GenerateSitemapJob implements ShouldQueue
*/
public function handle(SitemapManager $manager): void
{
- $result = $manager->regenerate();
+ $result = $manager->regenerate($this->mode, $this->triggeredBy);
if (($result['status'] ?? null) === 'disabled') {
Log::info('[SEO] Sitemap generation skipped (disabled)');
@@ -62,6 +126,18 @@ class GenerateSitemapJob implements ShouldQueue
*/
public function failed(\Throwable $exception): void
{
+ // 잡 최종 실패(재시도 소진/타임아웃) 시 진행상황을 'failed' 로 고정 — 무한 running 방지
+ app(SitemapProgress::class)->fail($exception->getMessage());
+
+ // 최종 실패 전용 훅 — 매 시도마다 발화하는 core.seo.sitemap.after_regenerate_failed 와 달리
+ // 재시도가 모두 소진된 뒤 딱 한 번만 발화한다. 재시도 중 성공하면 발화하지 않으므로
+ // 실패 알림이 중복되거나(각 시도) 결국 성공했는데도 발송되는 일이 없다.
+ HookManager::doAction('core.seo.sitemap.regenerate_failed_final', [
+ 'success' => false,
+ 'status' => 'failed',
+ 'message' => $exception->getMessage(),
+ ], $this->triggeredBy);
+
Log::error('[SEO] Sitemap generation failed', [
'error' => $exception->getMessage(),
]);
diff --git a/app/Listeners/CoreActivityLogListener.php b/app/Listeners/CoreActivityLogListener.php
index 4717b492..ef1fbdcf 100644
--- a/app/Listeners/CoreActivityLogListener.php
+++ b/app/Listeners/CoreActivityLogListener.php
@@ -8,8 +8,10 @@ use App\Contracts\Extension\HookListenerInterface;
use App\Contracts\Repositories\ActivityLogRepositoryInterface;
use App\Contracts\Repositories\ScheduleRepositoryInterface;
use App\Contracts\Repositories\UserRepositoryInterface;
-use App\Models\ActivityLog;
+use App\Extension\IdentityVerification\DTO\VerificationChallenge;
+use App\Extension\IdentityVerification\DTO\VerificationResult;
use App\Models\Attachment;
+use App\Models\IdentityVerificationLog;
use App\Models\Schedule;
use App\Models\User;
use Illuminate\Database\Eloquent\Model;
@@ -65,6 +67,7 @@ class CoreActivityLogListener implements HookListenerInterface
'core.auth.record_consents' => ['method' => 'handleAuthRecordConsents', 'priority' => 20],
'core.auth.login_failed' => ['method' => 'handleAuthLoginFailed', 'priority' => 20],
'core.auth.account_locked' => ['method' => 'handleAuthAccountLocked', 'priority' => 20],
+ 'core.auth.account_unlocked' => ['method' => 'handleAuthAccountUnlocked', 'priority' => 20],
// ─── IdentityVerification (IDV) ───
// DTO(VerificationChallenge/VerificationResult) 를 인자로 받으므로 sync 실행 필수
@@ -145,7 +148,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 훅 이벤트 처리 (기본 핸들러)
*
- * @param mixed ...$args 훅에서 전달된 인수들
+ * @param mixed ...$args 훅에서 전달된 인수들
*/
public function handle(...$args): void
{
@@ -159,8 +162,8 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 사용자 생성 후 로그 기록
*
- * @param User $user 생성된 사용자
- * @param array $originalData 원본 요청 데이터
+ * @param User $user 생성된 사용자
+ * @param array $originalData 원본 요청 데이터
*/
public function handleUserAfterCreate(User $user, array $originalData): void
{
@@ -175,9 +178,9 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 사용자 수정 후 로그 기록
*
- * @param User $user 수정된 사용자
- * @param array $originalData 원본 요청 데이터
- * @param array|null $snapshot 수정 전 스냅샷
+ * @param User $user 수정된 사용자
+ * @param array $originalData 원본 요청 데이터
+ * @param array|null $snapshot 수정 전 스냅샷
*/
public function handleUserAfterUpdate(User $user, array $originalData, ?array $snapshot = null): void
{
@@ -194,7 +197,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 사용자 삭제 후 로그 기록
*
- * @param array $userData 삭제된 사용자 데이터
+ * @param array $userData 삭제된 사용자 데이터
*/
public function handleUserAfterDelete(array $userData): void
{
@@ -213,7 +216,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 사용자 탈퇴 후 로그 기록
*
- * @param User $user 탈퇴한 사용자
+ * @param User $user 탈퇴한 사용자
*/
public function handleUserAfterWithdraw(User $user): void
{
@@ -227,7 +230,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 사용자 상세 조회 후 로그 기록
*
- * @param User $user 조회된 사용자
+ * @param User $user 조회된 사용자
*/
public function handleUserAfterShow(User $user): void
{
@@ -241,7 +244,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 사용자 목록 조회 후 로그 기록
*
- * @param int $count 조회된 총 사용자 수
+ * @param int $count 조회된 총 사용자 수
*/
public function handleUserAfterList(int $count): void
{
@@ -254,8 +257,8 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 사용자 검색 후 로그 기록
*
- * @param string $query 검색어
- * @param int $count 검색 결과 수
+ * @param string $query 검색어
+ * @param int $count 검색 결과 수
*/
public function handleUserAfterSearch(string $query, int $count): void
{
@@ -268,10 +271,10 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 사용자 일괄 상태 변경 후 로그 기록
*
- * @param array $uuids 대상 UUID 목록
- * @param string $status 변경된 상태
- * @param int $updatedCount 변경된 수
- * @param array $snapshots 변경 전 스냅샷 (uuid => snapshot)
+ * @param array $uuids 대상 UUID 목록
+ * @param string $status 변경된 상태
+ * @param int $updatedCount 변경된 수
+ * @param array $snapshots 변경 전 스냅샷 (uuid => snapshot)
*/
public function handleUserAfterBulkUpdate(array $uuids, string $status, int $updatedCount, array $snapshots = []): void
{
@@ -303,8 +306,8 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 관리자 로그인 후 로그 기록
*
- * @param User $user 로그인한 사용자
- * @param array $loginData 로그인 데이터
+ * @param User $user 로그인한 사용자
+ * @param array $loginData 로그인 데이터
*/
public function handleAuthAfterLogin(User $user, array $loginData): void
{
@@ -318,7 +321,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 로그아웃 로그 기록
*
- * @param User $user 로그아웃한 사용자
+ * @param User $user 로그아웃한 사용자
*/
public function handleAuthLogout(User $user): void
{
@@ -332,8 +335,8 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 회원가입 후 로그 기록
*
- * @param User $user 등록된 사용자
- * @param array $registrationData 등록 데이터
+ * @param User $user 등록된 사용자
+ * @param array $registrationData 등록 데이터
*/
public function handleAuthRegister(User $user, array $registrationData): void
{
@@ -347,7 +350,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 비밀번호 찾기 요청 로그 기록
*
- * @param User $user 요청한 사용자
+ * @param User $user 요청한 사용자
*/
public function handleAuthForgotPassword(User $user): void
{
@@ -361,7 +364,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 비밀번호 재설정 로그 기록
*
- * @param User $user 재설정한 사용자
+ * @param User $user 재설정한 사용자
*/
public function handleAuthResetPassword(User $user): void
{
@@ -375,10 +378,10 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 이용약관 동의 기록 로그
*
- * @param User $user 동의한 사용자
- * @param array $data 동의 데이터
- * @param string|null $agreedAt 동의 시각 (DispatchHookListenerJob 역직렬화 과정에서 null 가능)
- * @param string|null $ip IP 주소
+ * @param User $user 동의한 사용자
+ * @param array $data 동의 데이터
+ * @param string|null $agreedAt 동의 시각 (DispatchHookListenerJob 역직렬화 과정에서 null 가능)
+ * @param string|null $ip IP 주소
*/
public function handleAuthRecordConsents(User $user, array $data, ?string $agreedAt = null, ?string $ip = null): void
{
@@ -393,8 +396,8 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 로그인 실패 로그 기록 (사용자 존재 여부와 무관)
*
- * @param string $email 시도된 이메일
- * @param array $context IP/UA/시각 등 부가 정보
+ * @param string $email 시도된 이메일
+ * @param array $context IP/UA/시각 등 부가 정보
*/
public function handleAuthLoginFailed(string $email, array $context = []): void
{
@@ -408,14 +411,19 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 계정 잠금 로그 기록
*
- * @param User $user 잠긴 사용자
- * @param array $context attempts/locked_until/lockout_minutes/IP
+ * @param User $user 잠긴 사용자
+ * @param array $context attempts/locked_until/lockout_minutes/IP
*/
public function handleAuthAccountLocked(User $user, array $context = []): void
{
+ // 영구 잠금(무한대)은 차단 분(minutes)이 없으므로 별도 문구를 사용한다.
+ $permanent = ($context['permanent'] ?? false) || ($context['locked_until'] ?? null) === null;
+
$this->logActivity('auth.account_locked', [
'loggable' => $user,
- 'description_key' => 'activity_log.description.auth_account_locked',
+ 'description_key' => $permanent
+ ? 'activity_log.description.auth_account_locked_permanently'
+ : 'activity_log.description.auth_account_locked',
'description_params' => [
'attempts' => $context['attempts'] ?? null,
'minutes' => $context['lockout_minutes'] ?? null,
@@ -425,6 +433,22 @@ class CoreActivityLogListener implements HookListenerInterface
]);
}
+ /**
+ * 계정 잠금 해제 로그 기록 (관리자 수동 해제)
+ *
+ * @param User $user 잠금이 해제된 사용자
+ * @param array $context IP 등 부가 정보
+ */
+ public function handleAuthAccountUnlocked(User $user, array $context = []): void
+ {
+ $this->logActivity('auth.account_unlocked', [
+ 'loggable' => $user,
+ 'description_key' => 'activity_log.description.auth_account_unlocked',
+ 'description_params' => ['email' => $user->email],
+ 'ip_address' => $context['ip_address'] ?? null,
+ ]);
+ }
+
// ═══════════════════════════════════════════
// Role 핸들러
// ═══════════════════════════════════════════
@@ -432,7 +456,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 역할 생성 후 로그 기록
*
- * @param Model $role 생성된 역할
+ * @param Model $role 생성된 역할
*/
public function handleRoleAfterCreate(Model $role): void
{
@@ -447,8 +471,8 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 역할 수정 후 로그 기록
*
- * @param Model $role 수정된 역할
- * @param array|null $snapshot 수정 전 스냅샷
+ * @param Model $role 수정된 역할
+ * @param array|null $snapshot 수정 전 스냅샷
*/
public function handleRoleAfterUpdate(Model $role, ?array $snapshot = null): void
{
@@ -465,7 +489,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 역할 삭제 후 로그 기록
*
- * @param int $roleId 삭제된 역할 ID
+ * @param int $roleId 삭제된 역할 ID
*/
public function handleRoleAfterDelete(int $roleId): void
{
@@ -479,9 +503,9 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 역할 권한 동기화 후 로그 기록
*
- * @param Model $role 역할
- * @param array $previousPermissions 이전 권한 목록
- * @param array $currentPermissions 현재 권한 목록
+ * @param Model $role 역할
+ * @param array $previousPermissions 이전 권한 목록
+ * @param array $currentPermissions 현재 권한 목록
*/
public function handleRoleAfterSyncPermissions(Model $role, array $previousPermissions, array $currentPermissions): void
{
@@ -499,7 +523,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 역할 상태 전환 후 로그 기록
*
- * @param Model $role 역할
+ * @param Model $role 역할
*/
public function handleRoleAfterToggleStatus(Model $role): void
{
@@ -517,7 +541,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 메뉴 생성 후 로그 기록
*
- * @param Model $menu 생성된 메뉴
+ * @param Model $menu 생성된 메뉴
*/
public function handleMenuAfterCreate(Model $menu): void
{
@@ -532,8 +556,8 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 메뉴 수정 후 로그 기록
*
- * @param Model $menu 수정된 메뉴
- * @param array|null $snapshot 수정 전 스냅샷
+ * @param Model $menu 수정된 메뉴
+ * @param array|null $snapshot 수정 전 스냅샷
*/
public function handleMenuAfterUpdate(Model $menu, ?array $snapshot = null): void
{
@@ -550,7 +574,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 메뉴 삭제 후 로그 기록
*
- * @param int $menuId 삭제된 메뉴 ID
+ * @param int $menuId 삭제된 메뉴 ID
*/
public function handleMenuAfterDelete(int $menuId): void
{
@@ -564,7 +588,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 메뉴 순서 변경 후 로그 기록
*
- * @param array $orderData 순서 데이터
+ * @param array $orderData 순서 데이터
*/
public function handleMenuAfterUpdateOrder(array $orderData): void
{
@@ -576,7 +600,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 메뉴 상태 전환 후 로그 기록
*
- * @param Model $menu 메뉴
+ * @param Model $menu 메뉴
*/
public function handleMenuAfterToggleStatus(Model $menu): void
{
@@ -590,9 +614,9 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 메뉴 역할 동기화 후 로그 기록
*
- * @param Model $menu 메뉴
- * @param array $previousRoles 이전 역할 목록
- * @param array $currentRoles 현재 역할 목록
+ * @param Model $menu 메뉴
+ * @param array $previousRoles 이전 역할 목록
+ * @param array $currentRoles 현재 역할 목록
*/
public function handleMenuAfterSyncRoles(Model $menu, array $previousRoles, array $currentRoles): void
{
@@ -614,9 +638,9 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 설정 저장 후 로그 기록
*
- * @param string $tab 설정 탭
- * @param array $settings 저장된 설정
- * @param bool $result 저장 결과
+ * @param string $tab 설정 탭
+ * @param array $settings 저장된 설정
+ * @param bool $result 저장 결과
*/
public function handleSettingsAfterSave(string $tab, array $settings, bool $result): void
{
@@ -629,9 +653,9 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 개별 설정 변경 후 로그 기록
*
- * @param string $key 설정 키
- * @param mixed $value 설정 값
- * @param bool $result 저장 결과
+ * @param string $key 설정 키
+ * @param mixed $value 설정 값
+ * @param bool $result 저장 결과
*/
public function handleSettingsAfterSet(string $key, mixed $value, bool $result): void
{
@@ -648,7 +672,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 스케줄 생성 후 로그 기록
*
- * @param Model $schedule 생성된 스케줄
+ * @param Model $schedule 생성된 스케줄
*/
public function handleScheduleAfterCreate(Model $schedule): void
{
@@ -662,8 +686,8 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 스케줄 수정 후 로그 기록
*
- * @param Model $schedule 수정된 스케줄
- * @param array|null $snapshot 수정 전 스냅샷
+ * @param Model $schedule 수정된 스케줄
+ * @param array|null $snapshot 수정 전 스냅샷
*/
public function handleScheduleAfterUpdate(Model $schedule, ?array $snapshot = null): void
{
@@ -680,7 +704,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 스케줄 삭제 후 로그 기록
*
- * @param int $scheduleId 삭제된 스케줄 ID
+ * @param int $scheduleId 삭제된 스케줄 ID
*/
public function handleScheduleAfterDelete(int $scheduleId): void
{
@@ -694,8 +718,8 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 스케줄 수동 실행 후 로그 기록
*
- * @param Model $schedule 실행된 스케줄
- * @param Model $history 실행 이력
+ * @param Model $schedule 실행된 스케줄
+ * @param Model $history 실행 이력
*/
public function handleScheduleAfterRun(Model $schedule, Model $history): void
{
@@ -709,10 +733,10 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 스케줄 일괄 상태 변경 후 로그 기록
*
- * @param array $ids 대상 ID 목록
- * @param bool $isActive 활성화 여부
- * @param int $updatedCount 변경된 수
- * @param array $snapshots 변경 전 스냅샷 (id => snapshot)
+ * @param array $ids 대상 ID 목록
+ * @param bool $isActive 활성화 여부
+ * @param int $updatedCount 변경된 수
+ * @param array $snapshots 변경 전 스냅샷 (id => snapshot)
*/
public function handleScheduleAfterBulkUpdate(array $ids, bool $isActive, int $updatedCount, array $snapshots = []): void
{
@@ -740,9 +764,9 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 스케줄 일괄 삭제 후 로그 기록
*
- * @param array $ids 대상 ID 목록
- * @param int $deletedCount 삭제된 수
- * @param array $snapshots 삭제 전 스냅샷 (id => snapshot)
+ * @param array $ids 대상 ID 목록
+ * @param int $deletedCount 삭제된 수
+ * @param array $snapshots 삭제 전 스냅샷 (id => snapshot)
*/
public function handleScheduleAfterBulkDelete(array $ids, int $deletedCount, array $snapshots = []): void
{
@@ -769,7 +793,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 첨부파일 업로드 후 로그 기록
*
- * @param Model $attachment 업로드된 첨부파일
+ * @param Model $attachment 업로드된 첨부파일
*/
public function handleAttachmentAfterUpload(Model $attachment): void
{
@@ -782,7 +806,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 첨부파일 삭제 후 로그 기록
*
- * @param Model|null $attachment 삭제된 첨부파일 (DispatchHookListenerJob 역직렬화 과정에서 null 가능)
+ * @param Model|null $attachment 삭제된 첨부파일 (DispatchHookListenerJob 역직렬화 과정에서 null 가능)
*/
public function handleAttachmentAfterDelete(?Model $attachment = null): void
{
@@ -794,10 +818,10 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 첨부파일 일괄 삭제 후 로그 기록 (per-item)
*
- * @param string $identifier 식별자
- * @param int $count 삭제된 수
- * @param array $ids 삭제된 첨부파일 ID 목록
- * @param array $snapshots 삭제 전 스냅샷 (keyBy id)
+ * @param string $identifier 식별자
+ * @param int $count 삭제된 수
+ * @param array $ids 삭제된 첨부파일 ID 목록
+ * @param array $snapshots 삭제 전 스냅샷 (keyBy id)
*/
public function handleAttachmentAfterBulkDelete(string $identifier, int $count, array $ids = [], array $snapshots = []): void
{
@@ -825,8 +849,8 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 모듈 설치 후 로그 기록
*
- * @param string $moduleName 모듈 식별자
- * @param array $moduleInfo 모듈 정보
+ * @param string $moduleName 모듈 식별자
+ * @param array $moduleInfo 모듈 정보
*/
public function handleModuleAfterInstall(string $moduleName, array $moduleInfo): void
{
@@ -840,8 +864,8 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 모듈 활성화 후 로그 기록
*
- * @param string $moduleName 모듈 식별자
- * @param array $moduleInfo 모듈 정보
+ * @param string $moduleName 모듈 식별자
+ * @param array $moduleInfo 모듈 정보
*/
public function handleModuleAfterActivate(string $moduleName, array $moduleInfo): void
{
@@ -854,7 +878,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 모듈 비활성화 후 로그 기록
*
- * @param string $moduleName 모듈 식별자
+ * @param string $moduleName 모듈 식별자
*/
public function handleModuleAfterDeactivate(string $moduleName): void
{
@@ -867,9 +891,9 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 모듈 제거 후 로그 기록
*
- * @param string $moduleName 모듈 식별자
- * @param array $moduleInfo 모듈 정보
- * @param bool $deleteData 데이터 삭제 여부
+ * @param string $moduleName 모듈 식별자
+ * @param array $moduleInfo 모듈 정보
+ * @param bool $deleteData 데이터 삭제 여부
*/
public function handleModuleAfterUninstall(string $moduleName, array $moduleInfo, bool $deleteData): void
{
@@ -883,9 +907,9 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 모듈 업데이트 후 로그 기록
*
- * @param string $moduleName 모듈 식별자
- * @param array $result 업데이트 결과 배열 (['success' => bool, ...])
- * @param array $moduleInfo 모듈 정보
+ * @param string $moduleName 모듈 식별자
+ * @param array $result 업데이트 결과 배열 (['success' => bool, ...])
+ * @param array $moduleInfo 모듈 정보
*/
public function handleModuleAfterUpdate(string $moduleName, array $result, array $moduleInfo): void
{
@@ -899,8 +923,8 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 모듈 레이아웃 갱신 후 로그 기록
*
- * @param string $moduleName 모듈 식별자
- * @param array $result 갱신 결과
+ * @param string $moduleName 모듈 식별자
+ * @param array $result 갱신 결과
*/
public function handleModuleAfterRefreshLayouts(string $moduleName, array $result): void
{
@@ -917,8 +941,8 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 플러그인 설치 후 로그 기록
*
- * @param string $pluginName 플러그인 식별자
- * @param array $pluginInfo 플러그인 정보
+ * @param string $pluginName 플러그인 식별자
+ * @param array $pluginInfo 플러그인 정보
*/
public function handlePluginAfterInstall(string $pluginName, array $pluginInfo): void
{
@@ -932,8 +956,8 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 플러그인 활성화 후 로그 기록
*
- * @param string $pluginName 플러그인 식별자
- * @param array $pluginInfo 플러그인 정보
+ * @param string $pluginName 플러그인 식별자
+ * @param array $pluginInfo 플러그인 정보
*/
public function handlePluginAfterActivate(string $pluginName, array $pluginInfo): void
{
@@ -946,7 +970,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 플러그인 비활성화 후 로그 기록
*
- * @param string $pluginName 플러그인 식별자
+ * @param string $pluginName 플러그인 식별자
*/
public function handlePluginAfterDeactivate(string $pluginName): void
{
@@ -959,9 +983,9 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 플러그인 제거 후 로그 기록
*
- * @param string $pluginName 플러그인 식별자
- * @param bool $deleteData 데이터 삭제 여부
- * @param bool $result 제거 결과
+ * @param string $pluginName 플러그인 식별자
+ * @param bool $deleteData 데이터 삭제 여부
+ * @param bool $result 제거 결과
*/
public function handlePluginAfterUninstall(string $pluginName, bool $deleteData, bool $result): void
{
@@ -975,9 +999,9 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 플러그인 업데이트 후 로그 기록
*
- * @param string $pluginName 플러그인 식별자
- * @param array $result 업데이트 결과 배열 (['success' => bool, ...])
- * @param array $pluginInfo 플러그인 정보
+ * @param string $pluginName 플러그인 식별자
+ * @param array $result 업데이트 결과 배열 (['success' => bool, ...])
+ * @param array $pluginInfo 플러그인 정보
*/
public function handlePluginAfterUpdate(string $pluginName, array $result, array $pluginInfo): void
{
@@ -995,8 +1019,8 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 템플릿 설치 후 로그 기록
*
- * @param string $identifier 템플릿 식별자
- * @param array $templateInfo 템플릿 정보
+ * @param string $identifier 템플릿 식별자
+ * @param array $templateInfo 템플릿 정보
*/
public function handleTemplateAfterInstall(string $identifier, array $templateInfo): void
{
@@ -1010,7 +1034,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 템플릿 활성화 후 로그 기록
*
- * @param array $templateInfo 템플릿 정보
+ * @param array $templateInfo 템플릿 정보
*/
public function handleTemplateAfterActivate(array $templateInfo): void
{
@@ -1023,7 +1047,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 템플릿 비활성화 후 로그 기록
*
- * @param string $identifier 템플릿 식별자
+ * @param string $identifier 템플릿 식별자
*/
public function handleTemplateAfterDeactivate(string $identifier): void
{
@@ -1036,9 +1060,9 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 템플릿 제거 후 로그 기록
*
- * @param string $identifier 템플릿 식별자
- * @param array $templateInfo 템플릿 정보
- * @param bool $deleteData 데이터 삭제 여부
+ * @param string $identifier 템플릿 식별자
+ * @param array $templateInfo 템플릿 정보
+ * @param bool $deleteData 데이터 삭제 여부
*/
public function handleTemplateAfterUninstall(string $identifier, array $templateInfo, bool $deleteData): void
{
@@ -1052,9 +1076,9 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 템플릿 버전 업데이트 후 로그 기록
*
- * @param string $templateName 템플릿 식별자
- * @param array $result 업데이트 결과
- * @param array $templateInfo 템플릿 정보
+ * @param string $templateName 템플릿 식별자
+ * @param array $result 업데이트 결과
+ * @param array $templateInfo 템플릿 정보
*/
public function handleTemplateAfterVersionUpdate(string $templateName, array $result, array $templateInfo): void
{
@@ -1068,8 +1092,8 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 템플릿 레이아웃 갱신 후 로그 기록
*
- * @param string $identifier 템플릿 식별자
- * @param array $result 갱신 결과
+ * @param string $identifier 템플릿 식별자
+ * @param array $result 갱신 결과
*/
public function handleTemplateAfterRefreshLayouts(string $identifier, array $result): void
{
@@ -1086,10 +1110,10 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 레이아웃 수정 후 로그 기록
*
- * @param Model $layout 수정된 레이아웃
- * @param int $templateId 템플릿 ID
- * @param string $name 레이아웃 이름
- * @param array $data 수정 데이터
+ * @param Model $layout 수정된 레이아웃
+ * @param int $templateId 템플릿 ID
+ * @param string $name 레이아웃 이름
+ * @param array $data 수정 데이터
*/
public function handleLayoutAfterUpdate(Model $layout, int $templateId, string $name, array $data): void
{
@@ -1103,10 +1127,10 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 레이아웃 버전 복원 후 로그 기록
*
- * @param Model $newVersion 복원된 새 버전
- * @param int $templateId 템플릿 ID
- * @param string $name 레이아웃 이름
- * @param int $versionId 복원 대상 버전 ID
+ * @param Model $newVersion 복원된 새 버전
+ * @param int $templateId 템플릿 ID
+ * @param string $name 레이아웃 이름
+ * @param int $versionId 복원 대상 버전 ID
*/
public function handleLayoutAfterVersionRestore(Model $newVersion, int $templateId, string $name, int $versionId): void
{
@@ -1124,9 +1148,9 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 모듈 설정 저장 후 로그 기록
*
- * @param string $identifier 모듈 식별자
- * @param array $settings 저장된 설정
- * @param bool $result 저장 결과
+ * @param string $identifier 모듈 식별자
+ * @param array $settings 저장된 설정
+ * @param bool $result 저장 결과
*/
public function handleModuleSettingsAfterSave(string $identifier, array $settings, bool $result): void
{
@@ -1140,7 +1164,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 모듈 설정 초기화 후 로그 기록
*
- * @param string $identifier 모듈 식별자
+ * @param string $identifier 모듈 식별자
*/
public function handleModuleSettingsAfterReset(string $identifier): void
{
@@ -1157,9 +1181,9 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 플러그인 설정 저장 후 로그 기록
*
- * @param string $identifier 플러그인 식별자
- * @param array $settings 저장된 설정
- * @param bool $result 저장 결과
+ * @param string $identifier 플러그인 식별자
+ * @param array $settings 저장된 설정
+ * @param bool $result 저장 결과
*/
public function handlePluginSettingsAfterSave(string $identifier, array $settings, bool $result): void
{
@@ -1173,7 +1197,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 플러그인 설정 초기화 후 로그 기록
*
- * @param string $identifier 플러그인 식별자
+ * @param string $identifier 플러그인 식별자
*/
public function handlePluginSettingsAfterReset(string $identifier): void
{
@@ -1190,10 +1214,10 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 본인인증 challenge 요청 후 로그 기록.
*
- * @param \App\Extension\IdentityVerification\DTO\VerificationChallenge $challenge
- * @param string $purpose
- * @param \App\Models\User|array $target
- * @param array $context
+ * @param VerificationChallenge $challenge 발급된 본인인증 challenge
+ * @param string $purpose 인증 목적 (IdentityVerificationPurpose 값)
+ * @param User|array $target 인증 대상 (회원 모델 또는 이메일/전화 배열)
+ * @param array $context 부가 컨텍스트 (IP 등)
*/
public function handleIdentityRequested($challenge, string $purpose, $target, array $context = []): void
{
@@ -1213,9 +1237,9 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 본인인증 검증 후 로그 기록 (성공·실패 공통 디스패치).
*
- * @param \App\Extension\IdentityVerification\DTO\VerificationResult $result
- * @param \App\Models\IdentityVerificationLog|null $log
- * @param array $context
+ * @param VerificationResult $result 검증 결과 DTO
+ * @param IdentityVerificationLog|null $log 검증 로그 (없을 수 있음)
+ * @param array $context 부가 컨텍스트 (IP 등)
*/
public function handleIdentityVerified($result, $log, array $context = []): void
{
@@ -1238,7 +1262,7 @@ class CoreActivityLogListener implements HookListenerInterface
/**
* 본인인증 challenge 만료 로그 기록.
*
- * @param \App\Models\IdentityVerificationLog $log
+ * @param IdentityVerificationLog $log
*/
public function handleIdentityExpired($log): void
{
@@ -1251,5 +1275,4 @@ class CoreActivityLogListener implements HookListenerInterface
],
]);
}
-
}
diff --git a/app/Listeners/Identity/EnforceIdentityPolicyListener.php b/app/Listeners/Identity/EnforceIdentityPolicyListener.php
index e40317cc..b8adb26f 100644
--- a/app/Listeners/Identity/EnforceIdentityPolicyListener.php
+++ b/app/Listeners/Identity/EnforceIdentityPolicyListener.php
@@ -90,9 +90,13 @@ class EnforceIdentityPolicyListener implements HookListenerInterface
// 2) 코어 hook 은 getSubscribedHooks() 가 소유하므로 동적 등록 대상에서 제외
$coreHooks = array_fill_keys(static::coreHookTargets(), true);
- // 3) 현재 hook scope 정책 target 으로 재구독
+ // 3) 전담 리스너가 소유하는 target 은 일반 enforce 대상에서 제외
+ $delegated = array_fill_keys(static::delegatedHookTargets(), true);
+
+ // 4) 현재 hook scope 정책 target 으로 재구독
foreach (static::loadDynamicHookTargets() as $hookName) {
- if (! is_string($hookName) || $hookName === '' || isset($coreHooks[$hookName])) {
+ if (! is_string($hookName) || $hookName === ''
+ || isset($coreHooks[$hookName]) || isset($delegated[$hookName])) {
continue;
}
if (isset(self::$dynamicCallbacks[$hookName])) {
@@ -145,6 +149,27 @@ class EnforceIdentityPolicyListener implements HookListenerInterface
];
}
+ /**
+ * 전담 리스너가 강제를 소유하는 hook target 목록.
+ *
+ * 이 리스너는 "행위 직전(before_*)" 훅을 막아 세우는 가드다. 행위가 이미 끝난 뒤 발화하는
+ * 훅에서 예외를 던지면 되돌릴 것이 없는 상태에서 응답만 깨진다.
+ *
+ * `core.auth.after_register` 가 그 경우다. 이 훅은 `InitiateIdentityChallengeAfterRegister`
+ * 가 소유하며, `core.auth.signup_after_create` 정책이 켜져 있으면 계정을 '인증 대기' 로 두고
+ * 본인확인 challenge 를 발행한다(가입 자체는 성립). 여기서 다시 enforce 하면 가입이 428 로
+ * 막혀 '가입 전 본인확인'(`core.auth.signup_before_submit`) 정책과 동작이 같아지고,
+ * '가입 후' 정책은 켜는 순간 아무도 가입할 수 없게 된다.
+ *
+ * @return list 전담 소유 hook target 목록
+ */
+ protected static function delegatedHookTargets(): array
+ {
+ return [
+ 'core.auth.after_register',
+ ];
+ }
+
/**
* identity_policies 테이블에서 scope='hook' 정책의 target 목록을 추출합니다.
*
@@ -175,6 +200,12 @@ class EnforceIdentityPolicyListener implements HookListenerInterface
return;
}
+ // 전담 리스너가 소유하는 훅은 구독 단계에서 제외되지만, 다른 경로로 호출되더라도
+ // 이중 강제가 생기지 않도록 여기서도 막는다 (delegatedHookTargets 주석 참조).
+ if (in_array($hookName, static::delegatedHookTargets(), true)) {
+ return;
+ }
+
$policies = $this->policyRepository->resolveByScopeTarget('hook', $hookName);
if ($policies->isEmpty()) {
return;
diff --git a/app/Listeners/SeoNotificationDataListener.php b/app/Listeners/SeoNotificationDataListener.php
new file mode 100644
index 00000000..ea39ad4b
--- /dev/null
+++ b/app/Listeners/SeoNotificationDataListener.php
@@ -0,0 +1,133 @@
+ [
+ 'method' => 'extractData',
+ 'priority' => 20,
+ 'type' => 'filter',
+ ],
+ ];
+ }
+
+ /**
+ * 훅 이벤트를 처리합니다(HookListenerInterface 필수 메서드).
+ *
+ * @param mixed ...$args 훅에서 전달된 인수들
+ */
+ public function handle(...$args): void {}
+
+ /**
+ * 알림 유형에 따라 데이터와 컨텍스트를 추출합니다.
+ *
+ * @param array $default 기본 extract_data 구조
+ * @param string $type 알림 정의 유형
+ * @param array $args 훅에서 전달된 원본 인수 [$result, $triggeredBy]
+ * @return array{notifiable: null, notifiables: null, data: array, context: array}
+ */
+ public function extractData(array $default, string $type, array $args): array
+ {
+ return match ($type) {
+ 'sitemap_regenerated' => $this->extractRegenerated($args),
+ 'sitemap_regenerate_failed' => $this->extractRegenerateFailed($args),
+ default => $default,
+ };
+ }
+
+ /**
+ * 사이트맵 재생성 완료 알림 데이터를 추출합니다.
+ *
+ * @param array $args 훅 인수 [$result, $triggeredBy]
+ * @return array
+ */
+ private function extractRegenerated(array $args): array
+ {
+ $triggeredBy = $args[1] ?? null;
+ if (! is_int($triggeredBy)) {
+ return $this->skip();
+ }
+
+ $result = is_array($args[0] ?? null) ? $args[0] : [];
+ $data = $result['data'] ?? [];
+ $baseUrl = config('app.url');
+
+ return [
+ 'notifiable' => null,
+ 'notifiables' => null,
+ 'data' => [
+ 'app_name' => config('app.name'),
+ 'url_count' => (string) ($data['url_count'] ?? 0),
+ 'child_count' => (string) ($data['child_count'] ?? 1),
+ 'action_url' => "{$baseUrl}/admin/settings?tab=seo",
+ 'site_url' => $baseUrl,
+ ],
+ 'context' => [
+ 'trigger_user_id' => $triggeredBy,
+ ],
+ ];
+ }
+
+ /**
+ * 사이트맵 재생성 실패 알림 데이터를 추출합니다.
+ *
+ * @param array $args 훅 인수 [$result, $triggeredBy]
+ * @return array
+ */
+ private function extractRegenerateFailed(array $args): array
+ {
+ $triggeredBy = $args[1] ?? null;
+ if (! is_int($triggeredBy)) {
+ return $this->skip();
+ }
+
+ $result = is_array($args[0] ?? null) ? $args[0] : [];
+ $baseUrl = config('app.url');
+
+ return [
+ 'notifiable' => null,
+ 'notifiables' => null,
+ 'data' => [
+ 'app_name' => config('app.name'),
+ 'error' => (string) ($result['message'] ?? ''),
+ 'action_url' => "{$baseUrl}/admin/settings?tab=seo",
+ 'site_url' => $baseUrl,
+ ],
+ 'context' => [
+ 'trigger_user_id' => $triggeredBy,
+ ],
+ ];
+ }
+
+ /**
+ * 발송을 건너뛰도록 지시하는 결과를 반환합니다(비수동 재생성 = 유발 관리자 없음).
+ *
+ * @return array
+ */
+ private function skip(): array
+ {
+ return ['notifiable' => null, 'notifiables' => null, 'data' => [], 'context' => ['skip' => true]];
+ }
+}
diff --git a/app/Listeners/UserLogin/HandleFailedLoginListener.php b/app/Listeners/UserLogin/HandleFailedLoginListener.php
index d761a733..02a98d2d 100644
--- a/app/Listeners/UserLogin/HandleFailedLoginListener.php
+++ b/app/Listeners/UserLogin/HandleFailedLoginListener.php
@@ -47,7 +47,7 @@ class HandleFailedLoginListener implements HookListenerInterface
* 로그인 실패 시 카운트 증가 및 임계 도달 시 잠금 처리.
*
* @param string $email 실패한 로그인 이메일
- * @param array $context IP/UA/시각 등 부가 정보
+ * @param array $context IP/UA/시각 등 부가 정보
*/
public function handleFailed(string $email, array $context = []): void
{
@@ -79,12 +79,14 @@ class HandleFailedLoginListener implements HookListenerInterface
$user
);
+ // 잠금 시간 0(= 무한대) 은 영구 잠금이라 해제 시각이 null 이다.
$lockedUntil = $this->userRepository->lockAccount($user, $lockoutMinutes);
HookManager::doAction('core.auth.account_locked', $user, array_merge($context, [
'attempts' => $newCount,
'locked_until' => $lockedUntil,
'lockout_minutes' => $lockoutMinutes,
+ 'permanent' => $lockedUntil === null,
]));
}
}
diff --git a/app/Models/IdentityMessageDefinition.php b/app/Models/IdentityMessageDefinition.php
index d3a25213..84ea6ef5 100644
--- a/app/Models/IdentityMessageDefinition.php
+++ b/app/Models/IdentityMessageDefinition.php
@@ -9,6 +9,7 @@ use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\Relations\HasOne;
/**
* 본인인증 메시지 정의 모델.
@@ -125,11 +126,31 @@ class IdentityMessageDefinition extends Model
/**
* 메시지 템플릿 관계.
*
+ * 등록 순서(기본키)로 정렬을 고정한다. 목록은 대표 1건만(`firstTemplate` = MIN(id)) 싣고
+ * 단건은 전체를 싣는데, 화면 계약상 양쪽 모두 `templates[0]` 을 대표로 읽는다. 정렬이 없으면
+ * 단건의 첫 항목이 DB 반환 순서(`(definition_id, channel)` 유니크 인덱스 순)를 타서, 목록에서
+ * 본 제목과 다른 채널의 템플릿이 열린다.
+ *
* @return HasMany
*/
public function templates(): HasMany
{
- return $this->hasMany(IdentityMessageTemplate::class, 'definition_id');
+ return $this->hasMany(IdentityMessageTemplate::class, 'definition_id')->orderBy('id');
+ }
+
+ /**
+ * 대표 메시지 템플릿 관계 (가장 먼저 등록된 1건 = `templates` 정렬의 첫 항목).
+ *
+ * 정의 목록 화면은 대표 템플릿 1건의 제목/본문만 그린다. `templates` 를 통째로 eager load
+ * 하면 한 페이지를 여는 것만으로 그 페이지 전 정의의 모든 채널 템플릿 본문이 응답에 실린다.
+ * eager load 의 `limit(1)` 은 부모별이 아니라 배치 쿼리 전체에 걸리므로 쓸 수 없고,
+ * 관계 자체를 "가장 오래된 1건" 으로 좁혀야 정의별 1건이 보장된다.
+ *
+ * @return HasOne 대표 메시지 템플릿과의 관계
+ */
+ public function firstTemplate(): HasOne
+ {
+ return $this->hasOne(IdentityMessageTemplate::class, 'definition_id')->oldestOfMany();
}
/**
diff --git a/app/Models/SitemapUrl.php b/app/Models/SitemapUrl.php
new file mode 100644
index 00000000..72318add
--- /dev/null
+++ b/app/Models/SitemapUrl.php
@@ -0,0 +1,61 @@
+ 대량 할당 가능 컬럼
+ */
+ protected $fillable = [
+ 'resource_type',
+ 'resource_id',
+ 'loc',
+ 'loc_hash',
+ 'lastmod',
+ 'changefreq',
+ 'priority',
+ 'contributor',
+ 'is_visible',
+ ];
+
+ /**
+ * 속성 캐스팅을 반환합니다.
+ *
+ * @return array 캐스팅 맵
+ */
+ protected function casts(): array
+ {
+ return [
+ 'lastmod' => 'datetime',
+ 'priority' => 'float',
+ 'is_visible' => 'boolean',
+ ];
+ }
+}
diff --git a/app/Models/User.php b/app/Models/User.php
index 0e5832ee..6e365a0e 100644
--- a/app/Models/User.php
+++ b/app/Models/User.php
@@ -3,24 +3,25 @@
namespace App\Models;
// use Illuminate\Contracts\Auth\MustVerifyEmail;
+use App\Contracts\UniqueIdServiceInterface;
use App\Enums\MenuPermissionType;
use App\Enums\PermissionType;
use App\Enums\ScopeType;
use App\Enums\UserStatus;
+use Database\Factories\UserFactory;
+use Illuminate\Contracts\Translation\HasLocalePreference;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Database\Eloquent\Relations\MorphOne;
-use App\Contracts\UniqueIdServiceInterface;
-use Illuminate\Contracts\Translation\HasLocalePreference;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Sanctum\HasApiTokens;
class User extends Authenticatable implements HasLocalePreference
{
- /** @use HasFactory<\Database\Factories\UserFactory> */
+ /** @use HasFactory */
use HasApiTokens, HasFactory, Notifiable;
/** @var array 활동 로그 추적 필드 */
@@ -31,7 +32,7 @@ class User extends Authenticatable implements HasLocalePreference
'language' => ['label_key' => 'activity_log.fields.language', 'type' => 'text'],
'timezone' => ['label_key' => 'activity_log.fields.timezone', 'type' => 'text'],
'country' => ['label_key' => 'activity_log.fields.country', 'type' => 'text'],
- 'status' => ['label_key' => 'activity_log.fields.status', 'type' => 'enum', 'enum' => \App\Enums\UserStatus::class],
+ 'status' => ['label_key' => 'activity_log.fields.status', 'type' => 'enum', 'enum' => UserStatus::class],
'is_super' => ['label_key' => 'activity_log.fields.is_super', 'type' => 'boolean'],
'homepage' => ['label_key' => 'activity_log.fields.homepage', 'type' => 'text'],
'mobile' => ['label_key' => 'activity_log.fields.mobile', 'type' => 'text'],
@@ -50,6 +51,22 @@ class User extends Authenticatable implements HasLocalePreference
*/
protected array $effectiveScopeCache = [];
+ /**
+ * 보유 권한 부여 내역 캐시 (인스턴스 레벨)
+ *
+ * 한 요청에서 권한 판정은 수십~수백 번 일어난다 — 레이아웃 노드마다, 목록 행마다,
+ * 리소스 필드마다 부른다. 판정마다 DB 에 물으면 노드/행 수에 비례해 쿼리가 늘어난다.
+ * 첫 판정에서 `roles.permissions` 를 한 번 적재해 두고 이후로는 배열만 본다.
+ *
+ * 캐시 수명은 **모델 인스턴스**, 즉 요청 스코프다. 크로스 요청 캐시를 두지 않으므로
+ * 권한을 바꾸면 다음 요청부터 즉시 반영된다.
+ *
+ * 구조: 권한 식별자 ⇒ [{type, scope_type}, ...] (같은 권한을 여러 역할이 주면 여러 건)
+ *
+ * @var array>|null
+ */
+ protected ?array $permissionGrantsCache = null;
+
/**
* 테이블명
*
@@ -108,6 +125,7 @@ class User extends Authenticatable implements HasLocalePreference
'mobile_verified_at',
'failed_login_attempts',
'locked_until',
+ 'locked_permanently',
'last_failed_login_at',
];
@@ -140,6 +158,7 @@ class User extends Authenticatable implements HasLocalePreference
'is_super' => 'boolean',
'failed_login_attempts' => 'integer',
'locked_until' => 'datetime',
+ 'locked_permanently' => 'boolean',
'last_failed_login_at' => 'datetime',
];
}
@@ -196,7 +215,7 @@ class User extends Authenticatable implements HasLocalePreference
/**
* 사용자가 생성한 모듈들과의 관계를 정의합니다.
*
- * @return \Illuminate\Database\Eloquent\Relations\HasMany
+ * @return HasMany
*/
public function modules()
{
@@ -206,7 +225,7 @@ class User extends Authenticatable implements HasLocalePreference
/**
* 사용자가 생성한 플러그인들과의 관계를 정의합니다.
*
- * @return \Illuminate\Database\Eloquent\Relations\HasMany
+ * @return HasMany
*/
public function plugins()
{
@@ -241,14 +260,79 @@ class User extends Authenticatable implements HasLocalePreference
*/
public function hasPermission(string $permission, ?PermissionType $type = null): bool
{
- return $this->roles()
- ->whereHas('permissions', function ($query) use ($permission, $type) {
- $query->where('identifier', $permission);
- if ($type !== null) {
- $query->where('type', $type);
- }
- })
- ->exists();
+ $grants = $this->permissionGrants()[$permission] ?? null;
+
+ if ($grants === null) {
+ return false;
+ }
+
+ if ($type === null) {
+ return true;
+ }
+
+ foreach ($grants as $grant) {
+ if ($grant['type'] === $type->value) {
+ return true;
+ }
+ }
+
+ return false;
+ }
+
+ /**
+ * 보유 권한 부여 내역을 반환합니다 (인스턴스 캐시).
+ *
+ * 역할 → 권한을 한 번만 적재하고, 이후 판정은 전부 이 배열에서 이루어집니다.
+ *
+ * @return array> 권한 식별자 ⇒ 부여 내역
+ */
+ protected function permissionGrants(): array
+ {
+ if ($this->permissionGrantsCache !== null) {
+ return $this->permissionGrantsCache;
+ }
+
+ $grants = [];
+
+ foreach ($this->roles()->with('permissions')->get() as $role) {
+ foreach ($role->permissions as $permission) {
+ $grants[$permission->identifier][] = [
+ 'type' => $this->enumValue($permission->type),
+ 'scope_type' => $this->enumValue($permission->pivot->scope_type ?? null),
+ ];
+ }
+ }
+
+ return $this->permissionGrantsCache = $grants;
+ }
+
+ /**
+ * Enum 또는 원시 값을 문자열로 정규화합니다.
+ *
+ * 캐스팅 설정 유무에 따라 Enum 인스턴스와 문자열이 섞여 들어오므로 한 형태로 맞춥니다.
+ *
+ * @param mixed $value Enum 인스턴스 · 문자열 · null
+ * @return string|null 정규화된 문자열 (부재 시 null)
+ */
+ private function enumValue(mixed $value): ?string
+ {
+ if ($value instanceof \BackedEnum) {
+ return (string) $value->value;
+ }
+
+ return $value === null ? null : (string) $value;
+ }
+
+ /**
+ * 권한 판정 캐시를 비웁니다.
+ *
+ * 같은 인스턴스에서 역할을 바꾼 직후 다시 판정해야 하는 경우에 호출합니다.
+ * (역할 동기화 서비스가 호출하며, 일반 조회 경로에서는 필요하지 않습니다)
+ */
+ public function flushPermissionCaches(): void
+ {
+ $this->permissionGrantsCache = null;
+ $this->effectiveScopeCache = [];
}
/**
@@ -260,27 +344,17 @@ class User extends Authenticatable implements HasLocalePreference
*/
public function hasPermissions(array $permissions, bool $requireAll = true, ?PermissionType $type = null): bool
{
- $userPermissions = $this->roles()
- ->whereHas('permissions', function ($query) use ($permissions, $type) {
- $query->whereIn('identifier', $permissions);
- if ($type !== null) {
- $query->where('type', $type);
- }
- })
- ->with(['permissions' => function ($query) use ($permissions, $type) {
- $query->whereIn('identifier', $permissions);
- if ($type !== null) {
- $query->where('type', $type);
- }
- }])
- ->get()
- ->pluck('permissions')
- ->flatten()
- ->pluck('identifier')
- ->unique()
- ->count();
+ // 같은 권한 집합을 hasPermission 과 공유한다 — 권한 개수만큼 쿼리가 늘지 않는다.
+ // 비교 기준(고유 매칭 수 vs 인자 개수)은 종전과 동일하게 유지한다.
+ $matched = 0;
- return $requireAll ? $userPermissions === count($permissions) : $userPermissions > 0;
+ foreach (array_unique($permissions) as $permission) {
+ if ($this->hasPermission($permission, $type)) {
+ $matched++;
+ }
+ }
+
+ return $requireAll ? $matched === count($permissions) : $matched > 0;
}
/**
@@ -300,33 +374,21 @@ class User extends Authenticatable implements HasLocalePreference
return $this->effectiveScopeCache[$identifier];
}
- $scopeTypes = $this->roles()
- ->whereHas('permissions', function ($query) use ($identifier) {
- $query->where('identifier', $identifier);
- })
- ->with(['permissions' => function ($query) use ($identifier) {
- $query->where('identifier', $identifier);
- }])
- ->get()
- ->pluck('permissions')
- ->flatten()
- ->pluck('pivot.scope_type');
+ // 같은 권한 집합에서 scope_type 만 뽑는다 — 권한마다 쿼리를 다시 내지 않는다.
+ $values = array_column($this->permissionGrants()[$identifier] ?? [], 'scope_type');
// 권한 미보유 시 null 반환 (기본값: 전체 접근)
- if ($scopeTypes->isEmpty()) {
+ if ($values === []) {
return $this->effectiveScopeCache[$identifier] = null;
}
// union 정책: 하나라도 null → 전체 접근
- if ($scopeTypes->contains(null)) {
+ if (in_array(null, $values, true)) {
return $this->effectiveScopeCache[$identifier] = null;
}
- // ScopeType Enum 값을 문자열로 변환하여 비교
- $values = $scopeTypes->map(fn ($scope) => $scope instanceof ScopeType ? $scope->value : $scope);
-
// 하나라도 'role' → role 적용
- if ($values->contains('role')) {
+ if (in_array(ScopeType::Role->value, $values, true)) {
return $this->effectiveScopeCache[$identifier] = 'role';
}
@@ -366,11 +428,16 @@ class User extends Authenticatable implements HasLocalePreference
*/
public function isAdmin(): bool
{
- return $this->roles()
- ->whereHas('permissions', function ($query) {
- $query->where('type', PermissionType::Admin);
- })
- ->exists();
+ // 같은 권한 집합을 재사용한다 — 관리자 판정은 미들웨어·리소스·레이아웃에서 반복 호출된다.
+ foreach ($this->permissionGrants() as $grants) {
+ foreach ($grants as $grant) {
+ if ($grant['type'] === PermissionType::Admin->value) {
+ return true;
+ }
+ }
+ }
+
+ return false;
}
/**
@@ -388,8 +455,8 @@ class User extends Authenticatable implements HasLocalePreference
/**
* 슈퍼 관리자만 조회합니다.
*
- * @param \Illuminate\Database\Eloquent\Builder $query
- * @return \Illuminate\Database\Eloquent\Builder
+ * @param Builder $query
+ * @return Builder
*/
public function scopeSuperAdmins($query)
{
@@ -445,7 +512,7 @@ class User extends Authenticatable implements HasLocalePreference
/**
* 사용자가 생성한 메뉴들과의 관계를 정의합니다.
*
- * @return \Illuminate\Database\Eloquent\Relations\HasMany
+ * @return HasMany
*/
public function menus()
{
diff --git a/app/Notifications/GenericNotification.php b/app/Notifications/GenericNotification.php
index b16d5c33..9e6ad309 100644
--- a/app/Notifications/GenericNotification.php
+++ b/app/Notifications/GenericNotification.php
@@ -67,6 +67,16 @@ class GenericNotification extends BaseNotification
// 대상 채널이 지정된 경우 (template별 발송) — 게스트 게이트 + 확장 토글 + readiness 확인
if ($this->channel !== null) {
try {
+ $channelService = app(NotificationChannelService::class);
+
+ // 사용 가능한 채널 목록에 없는 채널은 발송 후보에서 제외한다 (로그도 남기지 않음).
+ // 채널을 제공하던 확장이 비활성/삭제되면 그 채널이 getAvailableChannels() 에서 빠지지만,
+ // 저장된 채널 설정·템플릿은 남아 있어 죽은 채널로 발송·"건너뜀" 로깅이 발생한다. 살아 있지
+ // 않은 채널은 "존재하지 않는 것"으로 취급해 조용히 제외한다(skipped 기록 대상 아님).
+ if (! $channelService->isChannelAvailable($this->channel)) {
+ return [];
+ }
+
// 게스트 게이트: 비회원 수신자인데 채널이 게스트 발송 미허용이면 제외
if ($this->isChannelBlockedForGuest($notifiable, $this->channel)) {
$this->logSkippedChannels([
@@ -77,7 +87,6 @@ class GenericNotification extends BaseNotification
}
// 0단계: 확장 단위 채널 전역 활성 여부 확인
- $channelService = app(NotificationChannelService::class);
if (! $channelService->isChannelEnabledForExtension(
$this->extensionType,
$this->extensionIdentifier,
@@ -126,6 +135,12 @@ class GenericNotification extends BaseNotification
$skippedChannels = [];
foreach ($channels as $channel) {
+ // 사용 가능한 채널 목록에 없는 채널(비활성/삭제된 확장이 제공하던 채널)은 로그 없이
+ // 조용히 제외한다 — 죽은 채널을 "건너뜀"으로 기록하지 않는다(채널 지정 경로와 동일 정책).
+ if (! $channelService->isChannelAvailable($channel)) {
+ continue;
+ }
+
// 게스트 게이트: 비회원 수신자인데 채널이 게스트 발송 미허용이면 제외
if ($this->isChannelBlockedForGuest($notifiable, $channel)) {
$skippedChannels[] = [
diff --git a/app/Providers/AppServiceProvider.php b/app/Providers/AppServiceProvider.php
index 625fb2c0..3a22a476 100644
--- a/app/Providers/AppServiceProvider.php
+++ b/app/Providers/AppServiceProvider.php
@@ -2,19 +2,31 @@
namespace App\Providers;
+use App\Contracts\Extension\HookManagerInterface;
+use App\Contracts\Extension\ModuleManagerInterface;
+use App\Contracts\Extension\PluginManagerInterface;
+use App\Contracts\Notifications\ChannelReadinessCheckerInterface;
use App\Extension\HookManager;
+use App\Extension\ModuleManager;
+use App\Extension\PluginManager;
use App\Http\View\Composers\TemplateComposer;
use App\Http\View\Composers\UserTemplateComposer;
use App\Listeners\ExtensionCompatibilityAlertListener;
+use App\Notifications\NotificationChannelManager;
+use App\Services\ChannelReadinessService;
+use App\Services\GeoIpService;
+use App\Support\Routing\DualExtensionRoute;
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Database\Events\QueryExecuted;
use Illuminate\Http\Request;
+use Illuminate\Notifications\ChannelManager;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\RateLimiter;
use Illuminate\Support\Facades\Schema;
use Illuminate\Support\Facades\View;
use Illuminate\Support\ServiceProvider;
+use Laravel\Boost\BoostServiceProvider;
class AppServiceProvider extends ServiceProvider
{
@@ -23,48 +35,55 @@ class AppServiceProvider extends ServiceProvider
*/
public function register(): void
{
+ // 자산 URL 이중 모드 Route 매크로 (dualSuffix / dualAsset).
+ // boot() 가 아니라 register() 에서 등록하는 이유: 라우트 파일은 프레임워크의
+ // 라우팅 부트스트랩(boot 단계)에서 로드되므로, 프로바이더 간 boot 순서에
+ // 의존하면 매크로 미정의 시점에 라우트가 로드될 수 있다. 모든 프로바이더의
+ // register() 는 어떤 boot() 보다 먼저 실행되므로 여기가 유일하게 안전한 지점이다.
+ DualExtensionRoute::register();
+
// NOTE: Faker 부재 시 FakerShim 대체는 app/Support/SampleData/bootstrap.php 에서 처리
// (composer autoload.files 진입점 — vendor/autoload.php 로드 직후 실행되어
// Laravel 의 fake() 헬퍼 정의 시점에 \Faker\Factory 가 이미 alias 되어 있음)
// 알림 발송 공통 디스패처 — 채널 독립 발송 + 발송 전후 G7 훅 실행
$this->app->singleton(
- \Illuminate\Notifications\ChannelManager::class,
- fn ($app) => new \App\Notifications\NotificationChannelManager($app)
+ ChannelManager::class,
+ fn ($app) => new NotificationChannelManager($app)
);
// 채널 Readiness 검증 — 미설정 채널 발송 사전 차단
$this->app->singleton(
- \App\Contracts\Notifications\ChannelReadinessCheckerInterface::class,
- \App\Services\ChannelReadinessService::class
+ ChannelReadinessCheckerInterface::class,
+ ChannelReadinessService::class
);
// TODO: TemplateManagerInterface 바인딩을 추가해야 함
// PluginManagerInterface 바인딩
$this->app->bind(
- \App\Contracts\Extension\PluginManagerInterface::class,
- \App\Extension\PluginManager::class
+ PluginManagerInterface::class,
+ PluginManager::class
);
// ModuleManagerInterface 바인딩
$this->app->bind(
- \App\Contracts\Extension\ModuleManagerInterface::class,
- \App\Extension\ModuleManager::class
+ ModuleManagerInterface::class,
+ ModuleManager::class
);
// HookManagerInterface 바인딩
$this->app->bind(
- \App\Contracts\Extension\HookManagerInterface::class,
- \App\Extension\HookManager::class
+ HookManagerInterface::class,
+ HookManager::class
);
// GeoIpService 싱글톤 등록
- $this->app->singleton(\App\Services\GeoIpService::class);
+ $this->app->singleton(GeoIpService::class);
// Laravel Boost (개발 전용 - dont-discover 대상, 클래스 존재 시에만 등록)
- if (class_exists(\Laravel\Boost\BoostServiceProvider::class)) {
- $this->app->register(\Laravel\Boost\BoostServiceProvider::class);
+ if (class_exists(BoostServiceProvider::class)) {
+ $this->app->register(BoostServiceProvider::class);
}
}
diff --git a/app/Providers/AuthServiceProvider.php b/app/Providers/AuthServiceProvider.php
index 29867b2b..452bd1b5 100644
--- a/app/Providers/AuthServiceProvider.php
+++ b/app/Providers/AuthServiceProvider.php
@@ -4,6 +4,7 @@ namespace App\Providers;
use App\Models\Role;
use App\Models\User;
+use App\Support\GuestRoleResolver;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Gate;
@@ -11,11 +12,6 @@ use Illuminate\Support\Facades\Log;
class AuthServiceProvider extends ServiceProvider
{
- /**
- * guest role 캐시
- */
- protected static ?Role $guestRoleCache = null;
-
/**
* Register any authentication / authorization services.
*/
@@ -236,9 +232,9 @@ class AuthServiceProvider extends ServiceProvider
return null; // guest role 없으면 다음 Gate 정의로 위임
}
- return $guestRole->permissions()
- ->where('identifier', $ability)
- ->exists() ? true : null;
+ // 적재해 둔 권한 컬렉션에서 판정한다. 빌더를 다시 열면 캐시가 무의미해져
+ // Gate 호출마다 쿼리가 나간다.
+ return GuestRoleResolver::hasPermission($ability) ? true : null;
}
/**
@@ -246,13 +242,7 @@ class AuthServiceProvider extends ServiceProvider
*/
protected static function getGuestRole(): ?Role
{
- if (self::$guestRoleCache === null) {
- self::$guestRoleCache = Role::where('identifier', 'guest')
- ->with('permissions')
- ->first();
- }
-
- return self::$guestRoleCache;
+ return GuestRoleResolver::resolve();
}
/**
@@ -260,7 +250,7 @@ class AuthServiceProvider extends ServiceProvider
*/
public static function clearGuestRoleCache(): void
{
- self::$guestRoleCache = null;
+ GuestRoleResolver::flush();
}
/**
@@ -275,16 +265,14 @@ class AuthServiceProvider extends ServiceProvider
$hasPermission = false;
if ($guestRole) {
- $hasPermission = $guestRole->permissions()
- ->where('identifier', $ability)
- ->exists();
+ $hasPermission = GuestRoleResolver::hasPermission($ability);
}
return [
'result' => self::checkGuestPermission($ability),
'guestRole' => $guestRole,
'hasPermission' => $hasPermission,
- 'cachedRoleId' => self::$guestRoleCache?->id,
+ 'cachedRoleId' => $guestRole?->id,
];
}
}
diff --git a/app/Providers/CoreServiceProvider.php b/app/Providers/CoreServiceProvider.php
index 00cbac47..a7064352 100644
--- a/app/Providers/CoreServiceProvider.php
+++ b/app/Providers/CoreServiceProvider.php
@@ -2,6 +2,11 @@
namespace App\Providers;
+use App\Benchmark\Axes\BatchAxisRunner;
+use App\Benchmark\Axes\ListAxisRunner;
+use App\Benchmark\Axes\ScreenAxisRunner;
+use App\Benchmark\Axes\WriteAxisRunner;
+use App\Console\Commands\BenchCommand;
use App\Contracts\Extension\CacheInterface;
use App\Contracts\Extension\ExtensionMiddlewareRegistryInterface;
use App\Contracts\Extension\HookListenerInterface;
@@ -32,6 +37,7 @@ use App\Contracts\Repositories\PluginRepositoryInterface;
use App\Contracts\Repositories\RoleRepositoryInterface;
use App\Contracts\Repositories\ScheduleHistoryRepositoryInterface;
use App\Contracts\Repositories\ScheduleRepositoryInterface;
+use App\Contracts\Repositories\SeoCacheStatRepositoryInterface;
use App\Contracts\Repositories\SystemConfigRepositoryInterface;
use App\Contracts\Repositories\TemplateCustomTranslationRepositoryInterface;
use App\Contracts\Repositories\TemplateLayoutAttachmentRepositoryInterface;
@@ -79,6 +85,7 @@ use App\Repositories\PluginRepository;
use App\Repositories\RoleRepository;
use App\Repositories\ScheduleHistoryRepository;
use App\Repositories\ScheduleRepository;
+use App\Repositories\SeoCacheStatRepository;
use App\Repositories\SystemConfigRepository;
use App\Repositories\TemplateCustomTranslationRepository;
use App\Repositories\TemplateLayoutAttachmentRepository;
@@ -90,6 +97,7 @@ use App\Services\DriverRegistryService;
use App\Services\LayoutExtensionService;
use App\Services\TemplateLayoutAttachmentService;
use App\Services\UniqueIdService;
+use App\Support\PrivilegedDatabaseAccounts;
use Illuminate\Support\Facades\Config;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\File;
@@ -116,9 +124,30 @@ class CoreServiceProvider extends ServiceProvider
$this->registerRepositoryBindings();
$this->registerExtensionManagers();
+ $this->registerBenchmarkAxes();
// ActivityLogManager 제거됨 — Monolog 채널(config/logging.php 'activity')로 대체
}
+ /**
+ * 성능 계측 축 실행기를 등록합니다.
+ *
+ * 축이 늘어날 때 `g7:bench` 커맨드를 고치지 않고 여기에 실행기만 추가하면 되도록
+ * 태그로 묶어 주입합니다. 실행기는 CLI 계측 시점에만 해석되므로 웹 요청 비용은 없습니다.
+ */
+ private function registerBenchmarkAxes(): void
+ {
+ $this->app->tag([
+ ListAxisRunner::class,
+ ScreenAxisRunner::class,
+ WriteAxisRunner::class,
+ BatchAxisRunner::class,
+ ], 'benchmark.axes');
+
+ $this->app->when(BenchCommand::class)
+ ->needs('$runners')
+ ->giveTagged('benchmark.axes');
+ }
+
/**
* Extension(모듈/플러그인) PSR-4 오토로드를 등록합니다.
*
@@ -216,6 +245,9 @@ class CoreServiceProvider extends ServiceProvider
$this->app->bind(NotificationRepositoryInterface::class, NotificationRepository::class);
$this->app->bind(NotificationTemplateRepositoryInterface::class, NotificationTemplateRepository::class);
+ // SEO Repository 바인딩
+ $this->app->bind(SeoCacheStatRepositoryInterface::class, SeoCacheStatRepository::class);
+
// IdentityVerification Repository 바인딩
$this->app->bind(IdentityVerificationLogRepositoryInterface::class, IdentityVerificationLogRepository::class);
$this->app->bind(IdentityPolicyRepositoryInterface::class, IdentityPolicyRepository::class);
@@ -333,9 +365,9 @@ class CoreServiceProvider extends ServiceProvider
return;
}
- // DB 연결 유효성 검증 (root 사용자 접속 방지)
+ // DB 연결 유효성 검증 (최고권한 계정 접속 방지)
if (! $this->isDatabaseConnectionValid()) {
- Log::error('Database connection invalid: using root user or missing credentials. Skipping extension loading.');
+ Log::error('Database connection invalid: using a privileged database account or missing credentials. Skipping extension loading.');
return;
}
@@ -439,30 +471,20 @@ class CoreServiceProvider extends ServiceProvider
/**
* 데이터베이스 연결이 유효한지 검증합니다.
*
- * root 사용자로 접속하거나 비밀번호가 없는 경우를 감지하여
+ * DB 최고권한 계정으로 접속하거나 사용자명이 비어 있는 경우를 감지하여
* 잘못된 설정으로 인한 접속 오류를 방지합니다.
+ * 계정 판정은 `PrivilegedDatabaseAccounts` 가 SSoT 입니다.
*
* @return bool 연결이 유효하면 true
*/
protected function isDatabaseConnectionValid(): bool
{
try {
- $config = DB::connection()->getConfig();
+ // read/write 분리 설정의 우선순위 규칙까지 PrivilegedDatabaseAccounts 가 소유한다.
+ // 호출처마다 규칙이 달라지면 같은 설정에 서로 다른 판정이 나온다.
+ $username = PrivilegedDatabaseAccounts::resolveUsername(DB::connection()->getConfig());
- // read/write 분리 설정인 경우 read 설정 확인
- $username = $config['username'] ?? null;
-
- // read 설정이 배열로 있는 경우
- if (isset($config['read']['username'])) {
- $username = $config['read']['username'];
- }
-
- // root 사용자 또는 빈 username인 경우 무효
- if (empty($username) || $username === 'root') {
- return false;
- }
-
- return true;
+ return PrivilegedDatabaseAccounts::isUsable($username);
} catch (\Throwable $e) {
Log::error('Database configuration check failed: '.$e->getMessage());
@@ -997,7 +1019,7 @@ class CoreServiceProvider extends ServiceProvider
$listener = app($listenerClass);
$listener->registerDynamicHooks();
- Log::info('동적 훅 리스너 등록 완료', ['listener' => $listenerClass]);
+ // 등록 성공은 로그로 남기지 않는다 — 요청마다 부팅되는 경로다. 실패만 아래에 남긴다.
} catch (\Throwable $e) {
Log::warning('동적 훅 리스너 등록 실패', [
'listener' => $listenerClass,
diff --git a/app/Providers/LanguagePackServiceProvider.php b/app/Providers/LanguagePackServiceProvider.php
index 3454ef02..985d3add 100644
--- a/app/Providers/LanguagePackServiceProvider.php
+++ b/app/Providers/LanguagePackServiceProvider.php
@@ -304,10 +304,7 @@ class LanguagePackServiceProvider extends ServiceProvider
$syncFor = function (string $scope, string $identifier, ?array $info, string $relativeBase) use ($registrar) {
$vendor = $this->resolveVendor($identifier, $info);
$version = (string) ($info['version'] ?? '1.0.0');
- $langDir = $relativeBase.'/'.$identifier.'/lang';
- if (! File::isDirectory(base_path($langDir))) {
- $langDir = $relativeBase.'/'.$identifier.'/resources/lang';
- }
+ $langDir = $this->resolveExtensionLangDir($scope, $identifier, $relativeBase);
$registrar->syncFromExtension($scope, $identifier, $vendor, $version, $langDir);
};
@@ -359,6 +356,38 @@ class LanguagePackServiceProvider extends ServiceProvider
});
}
+ /**
+ * 확장의 백엔드 다국어 디렉토리를 반환합니다.
+ *
+ * **런타임이 실제로 로드하는 경로와 같아야 한다** (`TranslationServiceProvider`).
+ * 모듈은 `src/lang`, 플러그인은 `lang` 이며, 코어의 확장 설치 검증
+ * (`ValidatesTranslationPath`)도 같은 규칙을 강제한다. 여기서 다른 경로를 잡으면
+ * 언어팩에 등록된 키와 화면에 나오는 문구의 출처가 어긋난다.
+ *
+ * 존재하지 않으면 관례 경로들을 순서대로 확인해 실제 있는 디렉토리를 돌려준다
+ * (제3자 확장이 다른 배치를 쓰는 경우 대비).
+ *
+ * @param string $scope 확장 스코프 (module|plugin|template)
+ * @param string $identifier 확장 식별자
+ * @param string $relativeBase base_path 기준 상위 디렉토리 (modules|plugins|templates)
+ * @return string base_path 기준 상대 lang 디렉토리
+ */
+ private function resolveExtensionLangDir(string $scope, string $identifier, string $relativeBase): string
+ {
+ $primary = $scope === 'module' ? 'src/lang' : 'lang';
+ $candidates = array_unique([$primary, 'lang', 'src/lang', 'resources/lang']);
+
+ foreach ($candidates as $candidate) {
+ $dir = $relativeBase.'/'.$identifier.'/'.$candidate;
+
+ if (File::isDirectory(base_path($dir))) {
+ return $dir;
+ }
+ }
+
+ return $relativeBase.'/'.$identifier.'/'.$primary;
+ }
+
/**
* 확장 manifest 또는 identifier 로부터 vendor 를 추출합니다.
*
diff --git a/app/Providers/ModuleRouteServiceProvider.php b/app/Providers/ModuleRouteServiceProvider.php
index 767ebf09..d134a558 100644
--- a/app/Providers/ModuleRouteServiceProvider.php
+++ b/app/Providers/ModuleRouteServiceProvider.php
@@ -2,10 +2,9 @@
namespace App\Providers;
-use App\Enums\ExtensionStatus;
use App\Extension\ExtensionManager;
use App\Extension\Testing\ExtensionTestAllowlist;
-use App\Models\Module;
+use App\Extension\Traits\CachesModuleStatus;
use App\Support\InstallerContext;
use Illuminate\Foundation\Support\Providers\RouteServiceProvider as ServiceProvider;
use Illuminate\Support\Facades\File;
@@ -14,6 +13,8 @@ use Illuminate\Support\Facades\Schema;
class ModuleRouteServiceProvider extends ServiceProvider
{
+ use CachesModuleStatus;
+
/**
* The path to the "home" route for your application.
*
@@ -74,10 +75,10 @@ class ModuleRouteServiceProvider extends ServiceProvider
}
}
- // 활성화된 모듈 identifier 목록 가져오기
- $activeModuleIdentifiers = Module::where('status', ExtensionStatus::Active->value)
- ->pluck('identifier')
- ->toArray();
+ // 활성화된 모듈 identifier 목록 가져오기.
+ // 같은 목록을 ModuleManager·ModuleServiceProvider 가 이미 캐시(TTL 기본 하루)해 두므로
+ // 여기서 다시 조회하지 않고 그 캐시를 공유한다. 상태 변경 시 무효화도 같이 따라온다.
+ $activeModuleIdentifiers = self::getActiveModuleIdentifiers();
$modules = File::directories($modulesPath);
$allowlistActive = ExtensionTestAllowlist::isActive();
diff --git a/app/Providers/SettingsServiceProvider.php b/app/Providers/SettingsServiceProvider.php
index 4a9ac0b4..678f4846 100644
--- a/app/Providers/SettingsServiceProvider.php
+++ b/app/Providers/SettingsServiceProvider.php
@@ -3,6 +3,7 @@
namespace App\Providers;
use App\Repositories\JsonConfigRepository;
+use App\Support\AllowedExtensions;
use Illuminate\Support\Facades\Config;
use Illuminate\Support\ServiceProvider;
@@ -29,6 +30,7 @@ class SettingsServiceProvider extends ServiceProvider
'geoip',
'seo',
'identity',
+ 'pagination',
];
/**
@@ -652,12 +654,27 @@ class SettingsServiceProvider extends ServiceProvider
Config::set('filesystems.default', $uploadSettings['disk']);
}
- if (! empty($uploadSettings['max_size'])) {
- Config::set('g7.upload.max_size', (int) $uploadSettings['max_size']);
+ // 관리자 설정은 MB, config/attachment.* 는 KB — 변환은 이 지점 단 한 곳에서만 수행한다.
+ // (기존에는 존재하지 않는 키 `max_size` 를 읽어 설정이 어디에도 반영되지 않았다)
+ if (! empty($uploadSettings['max_file_size'])) {
+ Config::set('attachment.max_file_size', (int) $uploadSettings['max_file_size'] * 1024);
}
- if (! empty($uploadSettings['allowed_extensions'])) {
- Config::set('g7.upload.allowed_extensions', $uploadSettings['allowed_extensions']);
+ // 화면은 콤마 문자열을 보내고 API 직접 호출은 배열을 보낸다. 배열만 받아들이면
+ // 문자열로 저장된 설정이 조용히 버려져 관리자가 확장자를 바꿔도 반영되지 않는다.
+ if (isset($uploadSettings['allowed_extensions'])) {
+ Config::set(
+ 'attachment.allowed_extensions',
+ AllowedExtensions::normalize($uploadSettings['allowed_extensions'])
+ );
+ }
+
+ // 이미지 축소 한계값·품질 — 픽셀/퍼센트라 단위 변환이 없다.
+ // 미설정(빈 값)은 "축소하지 않음" 이므로 그대로 넘겨 ImageResizer 가 판정하게 둔다.
+ foreach (['image_max_width', 'image_max_height', 'image_quality'] as $key) {
+ if (isset($uploadSettings[$key]) && $uploadSettings[$key] !== '') {
+ Config::set("attachment.{$key}", (int) $uploadSettings[$key]);
+ }
}
}
}
diff --git a/app/Repositories/ActivityLogRepository.php b/app/Repositories/ActivityLogRepository.php
index 513573b7..15418f77 100644
--- a/app/Repositories/ActivityLogRepository.php
+++ b/app/Repositories/ActivityLogRepository.php
@@ -5,9 +5,16 @@ namespace App\Repositories;
use App\Contracts\Repositories\ActivityLogRepositoryInterface;
use App\Helpers\PermissionHelper;
use App\Helpers\TimezoneHelper;
+use App\Http\Resources\BaseApiCollection;
use App\Models\ActivityLog;
use App\Repositories\Concerns\HasMultipleSearchFilters;
+use App\Repositories\Concerns\PaginatesWithDeferredJoin;
+use App\Repositories\Concerns\ResolvesSortSpec;
+use App\Support\Query\KeysetPaginator;
+use App\Support\Query\PaginationLimits;
+use Illuminate\Contracts\Pagination\CursorPaginator;
use Illuminate\Contracts\Pagination\LengthAwarePaginator;
+use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\Model;
@@ -17,6 +24,25 @@ use Illuminate\Database\Eloquent\Model;
class ActivityLogRepository implements ActivityLogRepositoryInterface
{
use HasMultipleSearchFilters;
+ use PaginatesWithDeferredJoin;
+ use ResolvesSortSpec;
+
+ /**
+ * 활동 로그 목록 정렬 허용 컬럼
+ *
+ * 요청 값을 그대로 orderBy 에 넘기면 없는 컬럼으로 SQL 오류가 나거나 인덱스 없는 컬럼
+ * 정렬을 강제할 수 있다.
+ *
+ * @var array
+ */
+ private const SORTABLE_COLUMNS = [
+ 'id',
+ 'created_at',
+ 'action',
+ 'log_type',
+ 'user_id',
+ ];
+
/**
* 특정 모델의 활동 로그를 페이지네이션하여 조회합니다.
*
@@ -26,8 +52,8 @@ class ActivityLogRepository implements ActivityLogRepositoryInterface
*/
public function getPaginatedForModel(Model $model, array $filters = []): LengthAwarePaginator
{
- $sortOrder = $filters['sort_order'] ?? 'desc';
- $query = ActivityLog::forModel($model)->orderBy('created_at', $sortOrder);
+ $sortOrder = $this->normalizeSortDirection($filters['sort_order'] ?? null);
+ $query = ActivityLog::forModel($model);
if (isset($filters['action'])) {
$query->action($filters['action']);
@@ -37,18 +63,31 @@ class ActivityLogRepository implements ActivityLogRepositoryInterface
$query->byUser($filters['user_id']);
}
- return $query->paginate($filters['per_page'] ?? 15);
+ // 컬럼을 좁히지 않는 이유는 getPaginated() 와 같다 — 리소스가 변경 내역을 그대로 노출한다
+ return $this->paginateWithDeferredJoin(
+ query: $query,
+ columns: ['*'],
+ sort: [['column' => 'created_at', 'direction' => $sortOrder]],
+ perPage: (int) ($filters['per_page'] ?? 15),
+ // 로그 테이블은 계속 쌓이기만 한다. 총 건수는 상한까지만 세고 "다음" 이동은
+ // per_page + 1 실측으로 끝까지 열어 둔다 (계산 불가는 마지막 페이지 번호 하나뿐).
+ resultCap: PaginationLimits::resultCap('admin.activity_logs'),
+ );
}
/**
* 활동 로그 목록을 페이지네이션하여 조회합니다.
*
+ * 요청에 `cursor` 가 있으면 키셋(커서) 방식으로, 없으면 페이지 번호 방식으로 응답합니다.
+ * 두 방식의 응답 봉투 차이는 {@see BaseApiCollection} 이 흡수합니다.
+ *
* @param array $filters 필터 조건
- * @return LengthAwarePaginator 페이지네이션된 로그 목록
+ * @return LengthAwarePaginator|CursorPaginator 페이지네이션된 로그 목록
*/
- public function getPaginated(array $filters = []): LengthAwarePaginator
+ public function getPaginated(array $filters = []): LengthAwarePaginator|CursorPaginator
{
- $query = ActivityLog::query()->with('user:id,uuid,name,email');
+ // 관계는 지연 조인의 outer 에서만 로드한다 (inner 는 키 컬럼만 조회한다)
+ $query = ActivityLog::query();
// 스코프 기반 권한 필터링 (self: 본인 로그만, role: 소유역할 로그, null: 전체)
PermissionHelper::applyPermissionScope($query, 'core.activities.read');
@@ -92,11 +131,41 @@ class ActivityLogRepository implements ActivityLogRepositoryInterface
$query->where('created_at', '<=', TimezoneHelper::fromSiteDateTime($filters['date_to']));
}
- $sortBy = $filters['sort_by'] ?? 'created_at';
- $sortOrder = $filters['sort_order'] ?? 'desc';
- $query->orderBy($sortBy, $sortOrder);
+ $sort = $this->resolveSortSpec($filters, self::SORTABLE_COLUMNS, 'created_at');
+ $perPage = (int) ($filters['per_page'] ?? 15);
- return $query->paginate($filters['per_page'] ?? 15);
+ // 커서를 받은 요청은 키셋으로 응답한다. 로그는 계속 쌓이기만 해서 깊은 페이지를
+ // OFFSET 으로 훑으면 건너뛸 행을 실제로 읽어야 하지만, 커서는 직전 페이지의 정렬
+ // 키를 WHERE 경계로 삼아 깊이와 무관하게 일정하다.
+ // 커서 모드에서는 OFFSET 자체가 없으므로 지연 조인이 해결하려던 문제도 함께 사라진다.
+ $sortKeys = array_map(
+ static fn (array $spec): array => [$spec['column'], $spec['direction']],
+ $sort
+ );
+
+ if (! empty($filters['cursor']) && KeysetPaginator::supports($sortKeys, self::SORTABLE_COLUMNS)) {
+ return KeysetPaginator::paginate(
+ query: $query->with('user:id,uuid,name,email'),
+ perPage: $perPage,
+ sortKeys: $sortKeys,
+ uniqueKey: 'id',
+ cursor: (string) $filters['cursor'],
+ );
+ }
+
+ // 목록 컬럼을 좁히지 않는 이유: 활동 로그 리소스는 변경 내역(mediumText `changes`)과
+ // 부가 정보(`properties`)까지 그대로 노출하므로 컬럼을 빼면 응답 계약이 바뀐다.
+ // 지연 조인만으로도 이 넓은 컬럼들을 읽는 행 수가 이번 페이지 분량으로 고정된다.
+ return $this->paginateWithDeferredJoin(
+ query: $query,
+ columns: ['*'],
+ sort: $sort,
+ perPage: $perPage,
+ relations: ['user:id,uuid,name,email'],
+ // 로그 테이블은 계속 쌓이기만 한다. 총 건수는 상한까지만 세고 "다음" 이동은
+ // per_page + 1 실측으로 끝까지 열어 둔다 (계산 불가는 마지막 페이지 번호 하나뿐).
+ resultCap: PaginationLimits::resultCap('admin.activity_logs'),
+ );
}
/**
@@ -105,10 +174,9 @@ class ActivityLogRepository implements ActivityLogRepositoryInterface
* action/description 필드는 영어 키를 저장하므로,
* 검색어가 번역된 라벨과 일치하는 원본 키도 함께 검색합니다.
*
- * @param \Illuminate\Database\Eloquent\Builder $query 쿼리 빌더
- * @param string $search 검색어
- * @param string $searchType 검색 유형 (all, action, description, ip_address)
- * @return void
+ * @param Builder $query 쿼리 빌더
+ * @param string $search 검색어
+ * @param string $searchType 검색 유형 (all, action, description, ip_address)
*/
private function applyBilingualSearch($query, string $search, string $searchType): void
{
@@ -146,7 +214,7 @@ class ActivityLogRepository implements ActivityLogRepositoryInterface
/**
* 번역된 액션 라벨로 원본 action 값을 역추적합니다.
*
- * @param string $searchLower 소문자 검색어
+ * @param string $searchLower 소문자 검색어
* @return array 일치하는 action 값 목록
*/
private function findActionsByTranslatedLabel(string $searchLower): array
@@ -179,7 +247,7 @@ class ActivityLogRepository implements ActivityLogRepositoryInterface
/**
* 번역된 설명 텍스트로 원본 description_key를 역추적합니다.
*
- * @param string $searchLower 소문자 검색어
+ * @param string $searchLower 소문자 검색어
* @return array 일치하는 description_key 목록
*/
private function findDescriptionKeysByTranslatedText(string $searchLower): array
@@ -200,7 +268,7 @@ class ActivityLogRepository implements ActivityLogRepositoryInterface
/**
* 활동 로그를 삭제합니다.
*
- * @param int $id 삭제할 활동 로그 ID
+ * @param int $id 삭제할 활동 로그 ID
* @return bool 삭제 성공 여부
*/
public function delete(int $id): bool
@@ -211,7 +279,7 @@ class ActivityLogRepository implements ActivityLogRepositoryInterface
/**
* 여러 활동 로그를 일괄 삭제합니다.
*
- * @param array $ids 삭제할 활동 로그 ID 목록
+ * @param array $ids 삭제할 활동 로그 ID 목록
* @return int 삭제된 건수
*/
public function deleteMany(array $ids): int
diff --git a/app/Repositories/AttachmentRepository.php b/app/Repositories/AttachmentRepository.php
index 79533f0b..bc9b2669 100644
--- a/app/Repositories/AttachmentRepository.php
+++ b/app/Repositories/AttachmentRepository.php
@@ -32,7 +32,8 @@ class AttachmentRepository implements AttachmentRepositoryInterface
public function findByIds(array $ids): Collection
{
if (empty($ids)) {
- return collect();
+ // `collect()` 는 Support 라 선언과 어긋난다 — 빈 결과도 모델 컬렉션이어야 한다.
+ return new Collection;
}
return Attachment::whereIn('id', $ids)
diff --git a/app/Repositories/Concerns/FiltersByDateRange.php b/app/Repositories/Concerns/FiltersByDateRange.php
new file mode 100644
index 00000000..c5e48108
--- /dev/null
+++ b/app/Repositories/Concerns/FiltersByDateRange.php
@@ -0,0 +1,72 @@
+= 하루 시작` / `<= 하루 끝` 범위 조건으로 바꾸면 인덱스가 그대로 쓰인다.
+ *
+ * 경계 처리를 각 저장소가 따로 적으면 한쪽이 종료일 하루를 통째로 빠뜨리기 쉽다
+ * (`<= '2026-08-02'` 는 그날 00:00:00 까지만 포함한다). 경계는 이 Trait 한 곳에서만 정한다.
+ */
+trait FiltersByDateRange
+{
+ /**
+ * 기간(시작일~종료일) 필터를 범위 조건으로 적용합니다.
+ *
+ * 종료일은 그날 23:59:59.999999 까지 포함하므로 `whereDate(..., '<=', ...)` 와
+ * 같은 결과를 냅니다.
+ *
+ * @param Builder|\Illuminate\Database\Query\Builder $query 대상 쿼리
+ * @param string $column 날짜 컬럼 (테이블 한정자 포함 가능)
+ * @param string|null $startDate 시작일 (빈 값이면 미적용)
+ * @param string|null $endDate 종료일 (빈 값이면 미적용)
+ */
+ protected function applyDateRangeFilter($query, string $column, ?string $startDate, ?string $endDate): void
+ {
+ if (! empty($startDate)) {
+ $query->where($column, '>=', CarbonImmutable::parse($startDate)->startOfDay());
+ }
+
+ if (! empty($endDate)) {
+ $query->where($column, '<=', CarbonImmutable::parse($endDate)->endOfDay());
+ }
+ }
+
+ /**
+ * 특정 하루에 해당하는 행만 남기는 필터를 범위 조건으로 적용합니다.
+ *
+ * @param Builder|\Illuminate\Database\Query\Builder $query 대상 쿼리
+ * @param string $column 날짜 컬럼 (테이블 한정자 포함 가능)
+ * @param \DateTimeInterface|string $day 대상 날짜
+ */
+ protected function applyDayFilter($query, string $column, \DateTimeInterface|string $day): void
+ {
+ $target = CarbonImmutable::parse($day instanceof \DateTimeInterface ? $day->format('Y-m-d H:i:s') : $day);
+
+ $query->whereBetween($column, [$target->startOfDay(), $target->endOfDay()]);
+ }
+
+ /**
+ * 특정 연·월에 해당하는 행만 남기는 필터를 범위 조건으로 적용합니다.
+ *
+ * `whereYear` + `whereMonth` 조합은 컬럼에 함수를 두 번 씌워 인덱스를 완전히 막습니다.
+ *
+ * @param Builder|\Illuminate\Database\Query\Builder $query 대상 쿼리
+ * @param string $column 날짜 컬럼 (테이블 한정자 포함 가능)
+ * @param int $year 연도
+ * @param int $month 월 (1~12)
+ */
+ protected function applyMonthFilter($query, string $column, int $year, int $month): void
+ {
+ $start = CarbonImmutable::create($year, $month, 1)->startOfDay();
+
+ $query->whereBetween($column, [$start, $start->endOfMonth()]);
+ }
+}
diff --git a/app/Repositories/Concerns/PaginatesWithDeferredJoin.php b/app/Repositories/Concerns/PaginatesWithDeferredJoin.php
new file mode 100644
index 00000000..45f1b696
--- /dev/null
+++ b/app/Repositories/Concerns/PaginatesWithDeferredJoin.php
@@ -0,0 +1,325 @@
+with()` 만 하고 인자를 생략하면 관계가 로드되지 않는다.
+ * 이 실패는 예외도 쿼리 오류도 내지 않고 응답에서 관계 필드만 사라진다
+ * - 정렬은 닫힌 집합이어야 한다 (ResolvesSortSpec 참조). 인덱스 없는 컬럼 정렬은 inner 도
+ * 전체 스캔하므로 개선 폭이 보장되지 않는다
+ * - 키 컬럼은 정렬 마지막에 자동으로 덧붙는다 (동률 시 페이지 경계가 흔들리는 것을 방지)
+ *
+ * 목록 컬럼에 `SUBSTRING(content, 1, N)` 을 두는 것은 프루닝으로 인정하지 않는다. 오버플로
+ * 페이지 읽기가 그대로 발생하므로, 잘라내기는 outer(`$columns`)에서만 수행한다.
+ *
+ * @see ResolvesSortSpec 정렬 스펙 해석
+ */
+trait PaginatesWithDeferredJoin
+{
+ /**
+ * 지연 조인으로 목록을 페이지네이션합니다.
+ *
+ * @param Builder $query 필터/where 만 적용된 쿼리 (orderBy/with/select 미적용)
+ * @param array $columns outer select 목록 (DB::raw 허용)
+ * @param array $sort 정렬 스펙
+ * @param int $perPage 페이지당 건수
+ * @param int|null $page 현재 페이지 (null = 요청에서 해석)
+ * @param array $relations outer 전용 eager load 관계
+ * @param array $withCount outer 전용 관계 카운트. `withCount()` 로
+ * 그대로 forward 되므로 Laravel 의 두 형태를
+ * 모두 받는다 — 목록 형태(`['options']`) 와
+ * 제약 클로저를 붙인 연관 형태
+ * (`['options as active_count' => fn ($q) => ...]`).
+ * 별칭 없이 같은 관계를 두 번 세면 기본 별칭이
+ * 충돌해 뒤엣것이 앞엣것을 덮으므로 `as` 로 구분한다
+ * @param string $keyName 키 컬럼명 (기본 id)
+ * @param int|null $total 전체 건수 (null = COUNT 수행, 값 지정 시 캐시 total 사용)
+ * @param bool $simple true = COUNT 없이 다음 페이지 유무만 판정
+ * @param bool $preserveIdOrder true = inner 가 정한 ID 순서를 outer 에서 그대로 복원
+ * @param string $pageName 페이지 쿼리 파라미터명
+ * @param Closure|null $outerUsing outer 에만 적용할 조인/집계 (inner 에서는 실행되지 않는다)
+ * @param int|null $resultCap 총 건수 집계 상한 (null = 항상 정확한 COUNT)
+ * @return PaginatorContract 페이지네이터 ($simple=true 면 Paginator, $resultCap 지정 시 BoundedPage, 아니면 LengthAwarePaginator)
+ */
+ protected function paginateWithDeferredJoin(
+ Builder|Relation $query,
+ array $columns,
+ array $sort,
+ int $perPage,
+ ?int $page = null,
+ array $relations = [],
+ array $withCount = [],
+ string $keyName = 'id',
+ ?int $total = null,
+ bool $simple = false,
+ bool $preserveIdOrder = false,
+ string $pageName = 'page',
+ ?Closure $outerUsing = null,
+ ?int $resultCap = null,
+ ): PaginatorContract {
+ // 관계(`$model->items()`)도 받는다 — 표준 `paginate()` 가 되는 자리는 이 계약으로
+ // 바꿔도 되어야 한다. 관계의 소속 조건은 그 밑 빌더에 이미 들어가 있어 보존된다.
+ // (쿼리 빌더는 받지 않는다. 이 계약은 모델의 키 컬럼·eager load 를 다루므로
+ // Eloquent 가 전제다 — 넓힐 수 있는 범위와 없는 범위를 구분한다.)
+ $query = $query instanceof Relation ? $query->getQuery() : $query;
+
+ $page = $page ?: Paginator::resolveCurrentPage($pageName);
+ $page = max(1, $page);
+
+ $sort = $this->normalizeSortSpecForKey($sort, $keyName);
+
+ // inner — 키 컬럼만 조회한다. with() 를 비우는 이유 두 가지:
+ // (a) 성능 — 관계 쿼리가 inner/outer 두 번 실행된다
+ // (b) 정합성 — inner 는 키 컬럼만 select 하므로 관계 FK 가 없어 eager load 가 깨진다
+ // whereHas 는 결과 집합을 결정하는 조건이라 setEagerLoads 로 지워지지 않는다 (의도된 구분).
+ $inner = (clone $query)->setEagerLoads([]);
+
+ // 상한이 지정되면 총 건수를 상한까지만 센다. 다음 페이지 판정은 총 건수와 무관하게
+ // per_page + 1 실측으로 하므로, 마지막 페이지 번호 하나만 계산 불가가 된다.
+ $bounded = ! $simple && $resultCap !== null && $resultCap > 0;
+ $relation = null;
+
+ if ($bounded && $total === null) {
+ // Eloquent 빌더를 그대로 넘긴다 — countWithCap 이 내부에서 toBase() 로
+ // 글로벌 스코프까지 적용한 기반 쿼리를 만든다.
+ [$total, $relation] = BoundedPaginator::countWithCap(clone $inner, $resultCap);
+ } elseif (! $simple && $total === null) {
+ // Laravel 의 paginate() 와 같은 집계 경로를 쓴다. count() 는 groupBy/having 이 있는
+ // 쿼리에서 `select count(*) ... group by ...` 를 그대로 실행해 **첫 그룹의 행 수**를
+ // 총 건수로 돌려준다. getCountForPagination() 은 그룹 쿼리를 서브쿼리로 감싸므로
+ // 그룹 수가 정확히 나온다. toBase() 는 글로벌 스코프를 적용한 뒤 기반 쿼리를 주므로
+ // 소프트 삭제/필터 조건이 집계에서 누락되지 않는다.
+ $total = (clone $inner)->toBase()->getCountForPagination();
+ }
+
+ $this->applySortSpec($inner, $sort);
+
+ // simple/bounded 모드는 다음 페이지 유무 판정을 위해 한 건을 더 읽는다.
+ // forPage() 를 쓰면 offset 이 (page-1) * (perPage+1) 로 계산돼 페이지가 넘어갈수록
+ // 건너뛰는 행이 어긋나므로, offset 은 perPage 기준으로 직접 지정한다.
+ $probesNextPage = $simple || $bounded;
+ $fetchCount = $probesNextPage ? $perPage + 1 : $perPage;
+
+ $ids = $inner
+ ->select($inner->getModel()->qualifyColumn($keyName))
+ ->offset(($page - 1) * $perPage)
+ ->limit($fetchCount)
+ ->pluck($keyName);
+
+ $hasMorePages = $probesNextPage && $ids->count() > $perPage;
+
+ if ($bounded && $hasMorePages) {
+ $ids = $ids->slice(0, $perPage)->values();
+ }
+
+ $items = $ids->isEmpty()
+ ? new Collection
+ : $this->fetchDeferredJoinRows($query, $columns, $sort, $ids->all(), $relations, $withCount, $keyName, $preserveIdOrder, $outerUsing);
+
+ $options = [
+ 'path' => Paginator::resolveCurrentPath(),
+ 'pageName' => $pageName,
+ ];
+
+ if ($simple) {
+ return new Paginator($items, $perPage, $page, $options);
+ }
+
+ if ($bounded) {
+ // 동시 삽입으로 집계 시점과 조회 시점의 모수가 달라질 수 있다
+ $seenSoFar = ($page - 1) * $perPage + $items->count();
+
+ return new BoundedPage(
+ items: $items,
+ total: max((int) $total, $seenSoFar),
+ perPage: $perPage,
+ currentPage: $page,
+ totalRelation: $relation ?? TotalRelation::Exact,
+ resultCap: $resultCap,
+ hasMorePages: $hasMorePages,
+ options: $options,
+ );
+ }
+
+ return new LengthAwarePaginator($items, $total ?? $items->count(), $perPage, $page, $options);
+ }
+
+ /**
+ * outer 쿼리를 실행해 실제 행을 조회합니다.
+ *
+ * @param Builder $query 필터가 적용된 원본 쿼리 (soft delete 스코프 보존을 위해 재사용)
+ * @param array $columns select 목록
+ * @param array $sort 정렬 스펙
+ * @param array $ids 이번 페이지의 키 값 목록
+ * @param array $relations eager load 관계
+ * @param array $withCount 관계 카운트 (목록/연관 두 형태 모두 허용)
+ * @param string $keyName 키 컬럼명
+ * @param bool $preserveIdOrder ID 순서 그대로 복원 여부
+ * @param Closure|null $outerUsing outer 전용 조인/집계
+ * @return Collection 조회된 행 컬렉션
+ */
+ private function fetchDeferredJoinRows(
+ Builder $query,
+ array $columns,
+ array $sort,
+ array $ids,
+ array $relations,
+ array $withCount,
+ string $keyName,
+ bool $preserveIdOrder,
+ ?Closure $outerUsing = null,
+ ): Collection {
+ $outer = (clone $query)->setEagerLoads([]);
+ $qualifiedKey = $outer->getModel()->qualifyColumn($keyName);
+
+ $outer->whereIn($qualifiedKey, $ids);
+
+ // 결과 집합을 좁히지 않는 조인/집계(최근 댓글 서브쿼리, 상관 COUNT 등)는 여기서만
+ // 붙인다. inner 에 두면 건너뛸 행 전체에 대해 실행되므로 OFFSET 이 깊어질수록 그
+ // 비용이 그대로 누적된다. whereIn 뒤에 적용하므로 이번 페이지 건수에만 실행된다.
+ if ($outerUsing !== null) {
+ $outerUsing($outer);
+ }
+
+ if (! empty($relations)) {
+ $outer->with($relations);
+ }
+
+ if (! empty($withCount)) {
+ $outer->withCount($withCount);
+ }
+
+ if ($preserveIdOrder) {
+ $this->applyIdOrder($outer, $qualifiedKey, $ids);
+ } else {
+ // 정렬 스펙에 키 컬럼이 포함돼 전순서가 보장되므로, 같은 스펙을 다시 적용하면
+ // inner 가 정한 순서와 결과가 동일하다 (MySQL 전용 FIELD() 가 필요 없다).
+ $this->applySortSpec($outer, $sort);
+ }
+
+ return $outer->get($columns);
+ }
+
+ /**
+ * 정렬 스펙을 쿼리에 적용합니다.
+ *
+ * 컬럼이 상관 서브쿼리(Builder)면 `orderBy()` 가 서브 select 로 전개한다. 서브쿼리는
+ * 원 행의 키에 상관되므로 inner/outer 어느 쪽에 적용해도 같은 순서를 만든다 —
+ * outer 에서는 이번 페이지 건수만큼만 실행된다.
+ *
+ * @param Builder $query 대상 쿼리
+ * @param array $sort 정렬 스펙
+ */
+ private function applySortSpec(Builder $query, array $sort): void
+ {
+ foreach ($sort as $spec) {
+ $query->orderBy($spec['column'], $spec['direction']);
+ }
+ }
+
+ /**
+ * 정렬 스펙 끝에 키 컬럼을 덧붙여 전순서를 만듭니다.
+ *
+ * 정렬 컬럼에 중복이 많으면(상태/조회수/평점 등) 동률 행의 순서가 실행마다 달라져 페이지
+ * 경계에서 행이 중복되거나 누락된다. inner 와 outer 가 같은 순서를 갖도록 하는 전제이기도 하다.
+ *
+ * 정렬 컬럼은 문자열 외에 **상관 서브쿼리(Builder)** 나 Expression 도 올 수 있다
+ * (관계 테이블 컬럼 기준 정렬 — `SortsByRelatedColumn`). 이 경우 키 컬럼일 수 없으므로
+ * 전순서 보장을 위해 키 컬럼이 항상 덧붙는다.
+ *
+ * @param array $sort 정렬 스펙
+ * @param string $keyName 키 컬럼명
+ * @return array 키 컬럼이 보장된 정렬 스펙
+ */
+ private function normalizeSortSpecForKey(array $sort, string $keyName): array
+ {
+ $normalized = [];
+
+ foreach ($sort as $spec) {
+ $column = $spec['column'] ?? null;
+
+ if (is_string($column) ? $column === '' : ! ($column instanceof Builder || $column instanceof QueryBuilder || $column instanceof Expression)) {
+ continue;
+ }
+
+ $normalized[] = [
+ 'column' => $column,
+ 'direction' => strtolower($spec['direction'] ?? 'desc') === 'asc' ? 'asc' : 'desc',
+ ];
+ }
+
+ foreach ($normalized as $spec) {
+ // 이미 키 컬럼으로 정렬한다면 그것으로 전순서가 성립한다
+ if (! is_string($spec['column'])) {
+ continue;
+ }
+
+ if ($spec['column'] === $keyName || str_ends_with($spec['column'], '.'.$keyName)) {
+ return $normalized;
+ }
+ }
+
+ $lastDirection = $normalized === [] ? 'desc' : end($normalized)['direction'];
+
+ $normalized[] = ['column' => $keyName, 'direction' => $lastDirection];
+
+ return $normalized;
+ }
+
+ /**
+ * inner 가 정한 ID 순서를 outer 에서 그대로 복원합니다.
+ *
+ * outer 에 존재하지 않는 표현식(집계/조인 서브쿼리 등)으로 정렬한 경우에만 사용한다.
+ * MySQL 전용 `FIELD()` 대신 표준 SQL `CASE WHEN` 을 쓴다 (DB 비의존 규정).
+ *
+ * @param Builder $query 대상 쿼리
+ * @param string $qualifiedKey 테이블명이 붙은 키 컬럼
+ * @param array $ids 복원할 순서의 키 값 목록
+ */
+ private function applyIdOrder(Builder $query, string $qualifiedKey, array $ids): void
+ {
+ $wrapped = $query->getQuery()->getGrammar()->wrap($qualifiedKey);
+
+ $cases = [];
+ $bindings = [];
+
+ foreach (array_values($ids) as $index => $id) {
+ $cases[] = "WHEN {$wrapped} = ? THEN {$index}";
+ $bindings[] = $id;
+ }
+
+ $query->orderByRaw('CASE '.implode(' ', $cases).' ELSE '.count($ids).' END', $bindings);
+ }
+}
diff --git a/app/Repositories/Concerns/ResolvesSortSpec.php b/app/Repositories/Concerns/ResolvesSortSpec.php
new file mode 100644
index 00000000..91639093
--- /dev/null
+++ b/app/Repositories/Concerns/ResolvesSortSpec.php
@@ -0,0 +1,105 @@
+ $allowedColumns 허용 정렬 컬럼 화이트리스트
+ * @param string $defaultColumn 화이트리스트에 없거나 미전송일 때 사용할 컬럼
+ * @param string $defaultDirection 기본 정렬 방향 (asc|desc)
+ * @param array $columnAliases 요청 값 → 실제 컬럼 매핑 (예: ['author' => 'author_name'])
+ * @param string $columnKey 정렬 컬럼이 담긴 필터 키
+ * @param string $directionKey 정렬 방향이 담긴 필터 키
+ * @return array 정렬 스펙 배열
+ */
+ protected function resolveSortSpec(
+ array $filters,
+ array $allowedColumns,
+ string $defaultColumn,
+ string $defaultDirection = 'desc',
+ array $columnAliases = [],
+ string $columnKey = 'sort_by',
+ string $directionKey = 'sort_order',
+ ): array {
+ $column = $this->normalizeSortValue($filters[$columnKey] ?? null);
+ $direction = $this->normalizeSortValue($filters[$directionKey] ?? null);
+
+ if ($column !== null && isset($columnAliases[$column])) {
+ $column = $columnAliases[$column];
+ }
+
+ if ($column === null || ! in_array($column, $allowedColumns, true)) {
+ $column = $defaultColumn;
+ }
+
+ return [[
+ 'column' => $column,
+ 'direction' => $this->normalizeSortDirection($direction, $defaultDirection),
+ ]];
+ }
+
+ /**
+ * 정렬 방향 문자열을 asc/desc 로 정규화합니다.
+ *
+ * @param string|null $direction 요청 값
+ * @param string $default 허용 값이 아닐 때 사용할 기본 방향
+ * @return string asc 또는 desc
+ */
+ protected function normalizeSortDirection(?string $direction, string $default = 'desc'): string
+ {
+ $normalized = strtolower((string) $direction);
+
+ if (in_array($normalized, ['asc', 'desc'], true)) {
+ return $normalized;
+ }
+
+ $fallback = strtolower($default);
+
+ return in_array($fallback, ['asc', 'desc'], true) ? $fallback : 'desc';
+ }
+
+ /**
+ * 정렬 관련 요청 값을 문자열로 정규화합니다. (Enum/빈 문자열 흡수)
+ *
+ * @param mixed $value 요청 값 (문자열 또는 BackedEnum)
+ * @return string|null 정규화된 문자열 (값이 없으면 null)
+ */
+ private function normalizeSortValue(mixed $value): ?string
+ {
+ if ($value instanceof BackedEnum) {
+ $value = $value->value;
+ }
+
+ if (! is_string($value) && ! is_int($value)) {
+ return null;
+ }
+
+ $value = trim((string) $value);
+
+ return $value === '' ? null : $value;
+ }
+}
diff --git a/app/Repositories/Concerns/SortsByRelatedColumn.php b/app/Repositories/Concerns/SortsByRelatedColumn.php
new file mode 100644
index 00000000..93552f3e
--- /dev/null
+++ b/app/Repositories/Concerns/SortsByRelatedColumn.php
@@ -0,0 +1,111 @@
+ $allowedColumns 원 테이블 허용 정렬 컬럼
+ * @param array, foreign_key: string, column: string}> $relatedMap 정렬 키 → 관계 스펙
+ * @param Model $parent 정렬 대상 원 모델 (상관 조건의 좌변)
+ * @param string $defaultColumn 기본 정렬 컬럼
+ * @param string $defaultDirection 기본 정렬 방향
+ * @param string $columnKey 정렬 컬럼이 담긴 필터 키
+ * @param string $directionKey 정렬 방향이 담긴 필터 키
+ * @return array 정렬 스펙 배열
+ */
+ protected function resolveSortSpecWithRelated(
+ array $filters,
+ array $allowedColumns,
+ array $relatedMap,
+ Model $parent,
+ string $defaultColumn,
+ string $defaultDirection = 'desc',
+ string $columnKey = 'sort_by',
+ string $directionKey = 'sort_order',
+ ): array {
+ $requested = $filters[$columnKey] ?? null;
+ $requested = is_string($requested) ? trim($requested) : '';
+
+ if ($requested === '' || ! isset($relatedMap[$requested])) {
+ return $this->resolveSortSpec(
+ $filters,
+ $allowedColumns,
+ $defaultColumn,
+ $defaultDirection,
+ columnKey: $columnKey,
+ directionKey: $directionKey,
+ );
+ }
+
+ $direction = $this->normalizeSortDirection($filters[$directionKey] ?? null, $defaultDirection);
+
+ return [[
+ 'column' => $this->relatedSortSubquery($relatedMap[$requested], $parent, $direction),
+ 'direction' => $direction,
+ ]];
+ }
+
+ /**
+ * 관계 테이블에서 정렬 기준값 한 건을 뽑는 상관 서브쿼리를 만듭니다.
+ *
+ * 정렬 방향과 같은 방향으로 관계 행을 정렬해 첫 건만 취한다 —
+ * `desc` 면 가장 늦은 값, `asc` 면 가장 이른 값이 기준이 된다.
+ *
+ * @param array{model: class-string, foreign_key: string, column: string} $spec 관계 스펙
+ * @param Model $parent 원 모델
+ * @param string $direction 정렬 방향 (asc|desc)
+ * @return Builder 상관 서브쿼리
+ */
+ protected function relatedSortSubquery(array $spec, Model $parent, string $direction): Builder
+ {
+ /** @var Model $related */
+ $related = new $spec['model'];
+
+ return $related->newQuery()
+ ->select($related->qualifyColumn($spec['column']))
+ ->whereColumn($related->qualifyColumn($spec['foreign_key']), $parent->qualifyColumn($parent->getKeyName()))
+ ->orderBy($related->qualifyColumn($spec['column']), $direction)
+ ->limit(1);
+ }
+}
diff --git a/app/Repositories/IdentityMessageDefinitionRepository.php b/app/Repositories/IdentityMessageDefinitionRepository.php
index da177b78..d3f02c6e 100644
--- a/app/Repositories/IdentityMessageDefinitionRepository.php
+++ b/app/Repositories/IdentityMessageDefinitionRepository.php
@@ -4,11 +4,25 @@ namespace App\Repositories;
use App\Contracts\Repositories\IdentityMessageDefinitionRepositoryInterface;
use App\Models\IdentityMessageDefinition;
+use App\Repositories\Concerns\ResolvesSortSpec;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Pagination\LengthAwarePaginator;
class IdentityMessageDefinitionRepository implements IdentityMessageDefinitionRepositoryInterface
{
+ use ResolvesSortSpec;
+
+ /** 허용 정렬 컬럼 (AdminIdentityMessageDefinitionIndexRequest 와 동일 집합) */
+ private const SORTABLE_COLUMNS = [
+ 'id',
+ 'provider_id',
+ 'scope_type',
+ 'scope_value',
+ 'is_active',
+ 'created_at',
+ 'updated_at',
+ ];
+
/**
* ID로 메시지 정의 조회.
*
@@ -137,7 +151,11 @@ class IdentityMessageDefinitionRepository implements IdentityMessageDefinitionRe
*/
public function getPaginated(array $filters = [], int $perPage = 20): LengthAwarePaginator
{
- $query = IdentityMessageDefinition::with('templates');
+ // 목록은 대표 템플릿 1건만 싣는다 — 화면이 그리는 것은 `templates[0]` 의 제목/본문뿐이다.
+ // `templates` 를 통째로 로드하면 한 페이지를 여는 것만으로 그 페이지 전 정의의 모든 채널
+ // 템플릿 본문이 응답에 실린다. 전체 템플릿은 단건 조회(show)가 공급한다.
+ $query = IdentityMessageDefinition::with('firstTemplate')
+ ->withCount('templates as templates_count');
if (! empty($filters['provider_id'])) {
$query->where('provider_id', $filters['provider_id']);
@@ -180,10 +198,11 @@ class IdentityMessageDefinitionRepository implements IdentityMessageDefinitionRe
});
}
- $sortBy = $filters['sort_by'] ?? 'id';
- $sortOrder = $filters['sort_order'] ?? 'asc';
- $query->orderBy($sortBy, $sortOrder);
+ foreach ($this->resolveSortSpec($filters, self::SORTABLE_COLUMNS, 'id', 'asc') as $sort) {
+ $query->orderBy($sort['column'], $sort['direction']);
+ }
+ // audit:allow repository-paginate-column-pruning reason: 본인인증 메시지 정의 테이블 — 정의 수가 고정이고 넓은 컬럼이 없다
return $query->paginate($perPage);
}
}
diff --git a/app/Repositories/IdentityPolicyRepository.php b/app/Repositories/IdentityPolicyRepository.php
index a6b7611b..54889b7f 100644
--- a/app/Repositories/IdentityPolicyRepository.php
+++ b/app/Repositories/IdentityPolicyRepository.php
@@ -252,6 +252,7 @@ class IdentityPolicyRepository implements IdentityPolicyRepositoryInterface
});
}
+ // audit:allow repository-paginate-column-pruning reason: 본인인증 정책 정의 테이블 — 정책 수가 고정이고 넓은 컬럼이 없다
return $query->orderByDesc('created_at')->orderByDesc('id')->paginate($perPage);
}
@@ -262,6 +263,7 @@ class IdentityPolicyRepository implements IdentityPolicyRepositoryInterface
*/
public function allEnabled(): Collection
{
+ // audit:allow query-unbounded-get reason: 본인인증 정책은 운영자가 등록한 수만큼만 존재한다 (사용량과 무관)
return IdentityPolicy::query()->where('enabled', true)->get();
}
@@ -346,6 +348,7 @@ class IdentityPolicyRepository implements IdentityPolicyRepositoryInterface
return [];
}
+ // audit:allow query-unbounded-get reason: 본인인증 정책은 운영자가 등록한 수만큼만 존재한다 (사용량과 무관)
return IdentityPolicy::query()
->where('scope', 'hook')
->distinct()
diff --git a/app/Repositories/IdentityVerificationLogRepository.php b/app/Repositories/IdentityVerificationLogRepository.php
index 325222c4..d62ec2f3 100644
--- a/app/Repositories/IdentityVerificationLogRepository.php
+++ b/app/Repositories/IdentityVerificationLogRepository.php
@@ -4,7 +4,12 @@ namespace App\Repositories;
use App\Contracts\Repositories\IdentityVerificationLogRepositoryInterface;
use App\Enums\IdentityVerificationStatus;
+use App\Helpers\TimezoneHelper;
+use App\Models\IdentityPolicy;
use App\Models\IdentityVerificationLog;
+use App\Repositories\Concerns\PaginatesWithDeferredJoin;
+use App\Support\Query\PaginationLimits;
+use Illuminate\Contracts\Pagination\LengthAwarePaginator;
use Illuminate\Support\Carbon;
/**
@@ -14,6 +19,8 @@ use Illuminate\Support\Carbon;
*/
class IdentityVerificationLogRepository implements IdentityVerificationLogRepositoryInterface
{
+ use PaginatesWithDeferredJoin;
+
/**
* 검증 로그를 생성합니다.
*
@@ -130,7 +137,7 @@ class IdentityVerificationLogRepository implements IdentityVerificationLogReposi
*
* @param array $filters 검색 필터
* @param int $perPage 페이지당 항목 수
- * @return \Illuminate\Contracts\Pagination\LengthAwarePaginator 페이지네이터
+ * @return LengthAwarePaginator 페이지네이터
*/
public function search(array $filters, int $perPage = 20)
{
@@ -158,7 +165,7 @@ class IdentityVerificationLogRepository implements IdentityVerificationLogReposi
if (! empty($filters['source_type'])) {
$query->whereIn('origin_policy_key', function ($q) use ($filters) {
$q->select('key')
- ->from('identity_policies')
+ ->from((new IdentityPolicy)->getTable())
->where('source_type', $filters['source_type']);
if (! empty($filters['source_identifier'])) {
$q->where('source_identifier', $filters['source_identifier']);
@@ -190,21 +197,33 @@ class IdentityVerificationLogRepository implements IdentityVerificationLogReposi
}
}
+ // 기간 필터는 사이트 타임존 기준으로 해석한다 — created_at 은 UTC 로 저장되고
+ // 화면은 사이트 타임존으로 보여주므로, 입력 문자열을 그대로 비교하면 하루가 어긋난다.
+ // 종료값은 시각 없이 날짜만 오는 경우(``) 그날 끝까지 포함한다.
if (! empty($filters['date_from'])) {
- $query->where('created_at', '>=', $filters['date_from']);
+ $query->where('created_at', '>=', TimezoneHelper::fromSiteDateTime($filters['date_from']));
}
if (! empty($filters['date_to'])) {
- $query->where('created_at', '<=', $filters['date_to']);
+ $query->where('created_at', '<=', TimezoneHelper::fromSiteRangeEnd($filters['date_to']));
}
$sortBy = in_array($filters['sort_by'] ?? null, ['created_at', 'attempts'], true)
? $filters['sort_by']
: 'created_at';
$sortOrder = ($filters['sort_order'] ?? 'desc') === 'asc' ? 'asc' : 'desc';
- $query->orderBy($sortBy, $sortOrder);
- return $query->paginate($perPage);
+ // 본인인증 로그는 계속 쌓이는 이력이라 뒤쪽 페이지에서 OFFSET 비용이 커진다.
+ // 응답이 요청/응답 payload 를 그대로 노출하므로 컬럼은 좁히지 않고 지연 조인만 적용한다.
+ return $this->paginateWithDeferredJoin(
+ query: $query,
+ columns: ['*'],
+ sort: [['column' => $sortBy, 'direction' => $sortOrder]],
+ perPage: $perPage,
+ // 로그 테이블은 계속 쌓이기만 한다. 총 건수는 상한까지만 세고 "다음" 이동은
+ // per_page + 1 실측으로 끝까지 열어 둔다 (계산 불가는 마지막 페이지 번호 하나뿐).
+ resultCap: PaginationLimits::resultCap('admin.identity_logs'),
+ );
}
/**
diff --git a/app/Repositories/JsonConfigRepository.php b/app/Repositories/JsonConfigRepository.php
index ed63319d..3087f26e 100644
--- a/app/Repositories/JsonConfigRepository.php
+++ b/app/Repositories/JsonConfigRepository.php
@@ -43,6 +43,17 @@ class JsonConfigRepository implements ConfigRepositoryInterface
*/
private ?array $cache = null;
+ /**
+ * 카테고리별 메모리 캐시
+ *
+ * 부팅 한 번에 같은 카테고리를 여러 곳에서 읽는다 — SettingsServiceProvider 의
+ * apply*Config 9종과 loadCoreSettingsToConfig 가 각각 조회하므로, 캐시가 없으면
+ * 요청마다 카테고리 수만큼 곱한 횟수로 파일 존재 확인·읽기·JSON 파싱이 반복된다.
+ *
+ * @var array>
+ */
+ private array $categoryCache = [];
+
/**
* 모든 카테고리의 설정을 조회합니다.
*
@@ -67,9 +78,27 @@ class JsonConfigRepository implements ConfigRepositoryInterface
/**
* 특정 카테고리의 설정을 조회합니다.
*
- * @return array
+ * @param string $category 카테고리명
+ * @return array 기본값과 병합된 설정
*/
public function getCategory(string $category): array
+ {
+ if (array_key_exists($category, $this->categoryCache)) {
+ return $this->categoryCache[$category];
+ }
+
+ return $this->categoryCache[$category] = $this->readCategory($category);
+ }
+
+ /**
+ * 카테고리 설정을 파일에서 읽어 기본값과 병합합니다.
+ *
+ * 캐시를 거치지 않는 실제 읽기 경로입니다.
+ *
+ * @param string $category 카테고리명
+ * @return array
+ */
+ private function readCategory(string $category): array
{
if (! $this->categoryExists($category)) {
return $this->getDefaultsForCategory($category);
@@ -77,11 +106,17 @@ class JsonConfigRepository implements ConfigRepositoryInterface
$path = $this->getCategoryPath($category);
+ // audit:allow no-storage-disk-direct reason: 이 저장소는 SettingsServiceProvider::register() 에서
+ // `new` 로 직접 생성된다 — 컨테이너 바인딩 이전이라 StorageInterface 를 해석할 수 없다.
+ // 설정 JSON 은 부팅 자체가 의존하는 자료라 드라이버 추상화보다 부팅 순서가 우선한다.
if (! Storage::disk(self::STORAGE_DISK)->exists($path)) {
return $this->getDefaultsForCategory($category);
}
try {
+ // audit:allow no-storage-disk-direct reason: 이 저장소는 SettingsServiceProvider::register() 에서
+ // `new` 로 직접 생성된다 — 컨테이너 바인딩 이전이라 StorageInterface 를 해석할 수 없다.
+ // 설정 JSON 은 부팅 자체가 의존하는 자료라 드라이버 추상화보다 부팅 순서가 우선한다.
$content = Storage::disk(self::STORAGE_DISK)->get($path);
$data = json_decode($content, true);
@@ -113,6 +148,8 @@ class JsonConfigRepository implements ConfigRepositoryInterface
* 도트 노테이션으로 특정 설정값을 조회합니다.
*
* @param string $key 예: 'mail.host', 'general.site_name'
+ * @param mixed $default 값이 없을 때 돌려줄 기본값
+ * @return mixed 설정값 (없으면 $default)
*/
public function get(string $key, mixed $default = null): mixed
{
@@ -131,6 +168,10 @@ class JsonConfigRepository implements ConfigRepositoryInterface
/**
* 도트 노테이션으로 특정 설정값을 저장합니다.
+ *
+ * @param string $key 설정 키 (카테고리.항목)
+ * @param mixed $value 저장할 값
+ * @return bool 저장 성공 여부
*/
public function set(string $key, mixed $value): bool
{
@@ -150,7 +191,8 @@ class JsonConfigRepository implements ConfigRepositoryInterface
/**
* 여러 설정을 일괄 저장합니다.
*
- * @param array $settings
+ * @param array $settings 도트 노테이션 키 ⇒ 값
+ * @return bool 저장 성공 여부
*/
public function setMany(array $settings): bool
{
@@ -171,7 +213,9 @@ class JsonConfigRepository implements ConfigRepositoryInterface
/**
* 특정 카테고리의 설정을 저장합니다.
*
- * @param array $settings
+ * @param string $category 카테고리명
+ * @param array $settings 저장할 설정
+ * @return bool 저장 성공 여부
*/
public function saveCategory(string $category, array $settings): bool
{
@@ -195,6 +239,9 @@ class JsonConfigRepository implements ConfigRepositoryInterface
try {
// 파일 잠금으로 동시 쓰기 방지
+ // audit:allow no-storage-disk-direct reason: 이 저장소는 SettingsServiceProvider::register() 에서
+ // `new` 로 직접 생성된다 — 컨테이너 바인딩 이전이라 StorageInterface 를 해석할 수 없다.
+ // 설정 JSON 은 부팅 자체가 의존하는 자료라 드라이버 추상화보다 부팅 순서가 우선한다.
$fullPath = Storage::disk(self::STORAGE_DISK)->path($path);
$handle = fopen($fullPath, 'c');
@@ -211,8 +258,10 @@ class JsonConfigRepository implements ConfigRepositoryInterface
fclose($handle);
- // 캐시 무효화
+ // 캐시 무효화 — 저장한 카테고리와 전체 맵 양쪽을 비운다.
+ // 한쪽만 비우면 저장 직후 조회가 이전 값을 돌려준다.
$this->cache = null;
+ unset($this->categoryCache[$category]);
return true;
} catch (\Exception $e) {
@@ -226,6 +275,9 @@ class JsonConfigRepository implements ConfigRepositoryInterface
/**
* 설정 키 존재 여부를 확인합니다.
+ *
+ * @param string $key 설정 키 (카테고리.항목)
+ * @return bool 존재 여부
*/
public function has(string $key): bool
{
@@ -234,6 +286,9 @@ class JsonConfigRepository implements ConfigRepositoryInterface
/**
* 특정 설정을 삭제합니다.
+ *
+ * @param string $key 설정 키 (카테고리.항목)
+ * @return bool 삭제 성공 여부
*/
public function delete(string $key): bool
{
@@ -269,6 +324,9 @@ class JsonConfigRepository implements ConfigRepositoryInterface
/**
* 카테고리 존재 여부를 확인합니다.
+ *
+ * @param string $category 카테고리명
+ * @return bool 존재 여부
*/
public function categoryExists(string $category): bool
{
@@ -278,7 +336,8 @@ class JsonConfigRepository implements ConfigRepositoryInterface
/**
* 설정 파일을 초기화합니다.
*
- * @param array> $settings
+ * @param array> $settings 기본값 위에 덮어쓸 설정
+ * @return bool 초기화 성공 여부
*/
public function initialize(array $settings = []): bool
{
@@ -310,6 +369,9 @@ class JsonConfigRepository implements ConfigRepositoryInterface
$backupPath = self::BACKUP_DIR.'/'.$backupName;
$zip = new \ZipArchive;
+ // audit:allow no-storage-disk-direct reason: 이 저장소는 SettingsServiceProvider::register() 에서
+ // `new` 로 직접 생성된다 — 컨테이너 바인딩 이전이라 StorageInterface 를 해석할 수 없다.
+ // 설정 JSON 은 부팅 자체가 의존하는 자료라 드라이버 추상화보다 부팅 순서가 우선한다.
$fullBackupPath = Storage::disk(self::STORAGE_DISK)->path($backupPath);
if ($zip->open($fullBackupPath, \ZipArchive::CREATE | \ZipArchive::OVERWRITE) !== true) {
@@ -318,6 +380,9 @@ class JsonConfigRepository implements ConfigRepositoryInterface
foreach ($this->getCategories() as $category) {
$categoryPath = $this->getCategoryPath($category);
+ // audit:allow no-storage-disk-direct reason: 이 저장소는 SettingsServiceProvider::register() 에서
+ // `new` 로 직접 생성된다 — 컨테이너 바인딩 이전이라 StorageInterface 를 해석할 수 없다.
+ // 설정 JSON 은 부팅 자체가 의존하는 자료라 드라이버 추상화보다 부팅 순서가 우선한다.
$fullCategoryPath = Storage::disk(self::STORAGE_DISK)->path($categoryPath);
if (file_exists($fullCategoryPath)) {
@@ -332,9 +397,15 @@ class JsonConfigRepository implements ConfigRepositoryInterface
/**
* 백업에서 설정을 복원합니다.
+ *
+ * @param string $backupPath 백업 파일 경로 (disk 기준)
+ * @return bool 복원 성공 여부
*/
public function restore(string $backupPath): bool
{
+ // audit:allow no-storage-disk-direct reason: 이 저장소는 SettingsServiceProvider::register() 에서
+ // `new` 로 직접 생성된다 — 컨테이너 바인딩 이전이라 StorageInterface 를 해석할 수 없다.
+ // 설정 JSON 은 부팅 자체가 의존하는 자료라 드라이버 추상화보다 부팅 순서가 우선한다.
$fullBackupPath = Storage::disk(self::STORAGE_DISK)->path($backupPath);
if (! file_exists($fullBackupPath)) {
@@ -356,12 +427,16 @@ class JsonConfigRepository implements ConfigRepositoryInterface
if ($this->categoryExists($category)) {
$content = $zip->getFromIndex($i);
$categoryPath = $this->getCategoryPath($category);
+ // audit:allow no-storage-disk-direct reason: 이 저장소는 SettingsServiceProvider::register() 에서
+ // `new` 로 직접 생성된다 — 컨테이너 바인딩 이전이라 StorageInterface 를 해석할 수 없다.
+ // 설정 JSON 은 부팅 자체가 의존하는 자료라 드라이버 추상화보다 부팅 순서가 우선한다.
Storage::disk(self::STORAGE_DISK)->put($categoryPath, $content);
}
}
$zip->close();
$this->cache = null;
+ $this->categoryCache = [];
return true;
}
@@ -457,6 +532,9 @@ class JsonConfigRepository implements ConfigRepositoryInterface
*/
private function ensureDirectoryExists(): void
{
+ // audit:allow no-storage-disk-direct reason: 이 저장소는 SettingsServiceProvider::register() 에서
+ // `new` 로 직접 생성된다 — 컨테이너 바인딩 이전이라 StorageInterface 를 해석할 수 없다.
+ // 설정 JSON 은 부팅 자체가 의존하는 자료라 드라이버 추상화보다 부팅 순서가 우선한다.
$disk = Storage::disk(self::STORAGE_DISK);
if (! $disk->exists('.')) {
@@ -469,6 +547,9 @@ class JsonConfigRepository implements ConfigRepositoryInterface
*/
private function ensureBackupDirectoryExists(): void
{
+ // audit:allow no-storage-disk-direct reason: 이 저장소는 SettingsServiceProvider::register() 에서
+ // `new` 로 직접 생성된다 — 컨테이너 바인딩 이전이라 StorageInterface 를 해석할 수 없다.
+ // 설정 JSON 은 부팅 자체가 의존하는 자료라 드라이버 추상화보다 부팅 순서가 우선한다.
$disk = Storage::disk(self::STORAGE_DISK);
if (! $disk->exists(self::BACKUP_DIR)) {
diff --git a/app/Repositories/LanguagePackRepository.php b/app/Repositories/LanguagePackRepository.php
index 1ee83b3d..426408b1 100644
--- a/app/Repositories/LanguagePackRepository.php
+++ b/app/Repositories/LanguagePackRepository.php
@@ -4,10 +4,13 @@ namespace App\Repositories;
use App\Contracts\Repositories\LanguagePackRepositoryInterface;
use App\Enums\LanguagePackScope;
+use App\Enums\LanguagePackSourceType;
use App\Enums\LanguagePackStatus;
+use App\Enums\TextDirection;
use App\Models\LanguagePack;
use App\Repositories\Concerns\HasMultipleSearchFilters;
use Illuminate\Contracts\Pagination\LengthAwarePaginator;
+use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Support\Facades\DB;
@@ -47,6 +50,7 @@ class LanguagePackRepository implements LanguagePackRepositoryInterface
*/
public function getActivePacks(): Collection
{
+ // audit:allow query-unbounded-get reason: 언어팩은 설치된 팩 × 로케일 수만큼만 존재한다 (사용량과 무관)
return LanguagePack::query()
->where('status', LanguagePackStatus::Active->value)
->get();
@@ -93,6 +97,7 @@ class LanguagePackRepository implements LanguagePackRepositoryInterface
?string $targetIdentifier,
string $locale
): Collection {
+ // audit:allow query-unbounded-get reason: 언어팩은 설치된 팩 × 로케일 수만큼만 존재한다 (사용량과 무관)
return LanguagePack::query()
->where('scope', $scope)
->where('target_identifier', $targetIdentifier)
@@ -109,6 +114,7 @@ class LanguagePackRepository implements LanguagePackRepositoryInterface
*/
public function getActiveCoreLocales(): array
{
+ // audit:allow query-unbounded-get reason: 언어팩은 설치된 팩 × 로케일 수만큼만 존재한다 (사용량과 무관)
return LanguagePack::query()
->where('scope', LanguagePackScope::Core->value)
->where('status', LanguagePackStatus::Active->value)
@@ -127,6 +133,7 @@ class LanguagePackRepository implements LanguagePackRepositoryInterface
*/
public function paginate(array $filters = [], int $perPage = 20): LengthAwarePaginator
{
+ // audit:allow repository-paginate-column-pruning reason: 언어팩 정의 테이블 — 설치된 팩 수만큼만 존재하고 넓은 컬럼이 없다
return $this->buildFilteredQuery($filters)->paginate($perPage);
}
@@ -148,9 +155,9 @@ class LanguagePackRepository implements LanguagePackRepositoryInterface
* (실제 미설치 번들은 Service 계층에서 합쳐집니다).
*
* @param array $filters 필터 조건
- * @return \Illuminate\Database\Eloquent\Builder 정렬까지 적용된 쿼리 빌더
+ * @return Builder 정렬까지 적용된 쿼리 빌더
*/
- private function buildFilteredQuery(array $filters): \Illuminate\Database\Eloquent\Builder
+ private function buildFilteredQuery(array $filters): Builder
{
$query = LanguagePack::query();
@@ -165,7 +172,8 @@ class LanguagePackRepository implements LanguagePackRepositoryInterface
}
if (! empty($filters['status'])) {
if ($filters['status'] === LanguagePackStatus::Uninstalled->value) {
- $query->whereRaw('1 = 0');
+ // 결과 없음 — 빈 whereIn 은 `0 = 1` 로 컴파일된다(raw 불필요)
+ $query->whereIn($query->getModel()->getKeyName(), []);
} else {
$query->where('status', $filters['status']);
}
@@ -190,7 +198,9 @@ class LanguagePackRepository implements LanguagePackRepositoryInterface
return $query
->orderBy('scope')
->orderBy('target_identifier')
- ->orderBy('locale');
+ ->orderBy('locale')
+ // 전순서 보장 — 위 세 컬럼 조합이 유니크하더라도 정렬 계약을 키로 닫아 둔다
+ ->orderBy('id');
}
/**
@@ -239,6 +249,7 @@ class LanguagePackRepository implements LanguagePackRepositoryInterface
*/
public function getPacksForTarget(string $scope, string $targetIdentifier): Collection
{
+ // audit:allow query-unbounded-get reason: 언어팩은 설치된 팩 × 로케일 수만큼만 존재한다 (사용량과 무관)
return LanguagePack::query()
->where('scope', $scope)
->where('target_identifier', $targetIdentifier)
@@ -253,6 +264,7 @@ class LanguagePackRepository implements LanguagePackRepositoryInterface
*/
public function getPacksForLocale(string $locale): Collection
{
+ // audit:allow query-unbounded-get reason: 언어팩은 설치된 팩 × 로케일 수만큼만 존재한다 (사용량과 무관)
return LanguagePack::query()->where('locale', $locale)->get();
}
@@ -282,10 +294,10 @@ class LanguagePackRepository implements LanguagePackRepositoryInterface
$pack->version = (string) ($manifest['version'] ?? '0.0.0');
$pack->license = $manifest['license'] ?? null;
$pack->description = is_array($manifest['description'] ?? null) ? $manifest['description'] : null;
- $pack->status = \App\Enums\LanguagePackStatus::Uninstalled->value;
+ $pack->status = LanguagePackStatus::Uninstalled->value;
$pack->is_protected = false; // lang-packs/_bundled/ 패키지는 사용자가 install/uninstall 자유 (요구사항 #3)
$pack->manifest = $manifest;
- $pack->source_type = \App\Enums\LanguagePackSourceType::Bundled->value;
+ $pack->source_type = LanguagePackSourceType::Bundled->value;
$pack->source_url = $bundledIdentifier;
$pack->setAttribute('bundled_identifier', $bundledIdentifier);
@@ -335,11 +347,11 @@ class LanguagePackRepository implements LanguagePackRepositoryInterface
$pack->locale = $locale;
$pack->locale_name = strtoupper($locale);
$pack->locale_native_name = $nativeName;
- $pack->text_direction = \App\Enums\TextDirection::Ltr->value;
+ $pack->text_direction = TextDirection::Ltr->value;
$pack->version = $version;
- $pack->status = \App\Enums\LanguagePackStatus::Active->value;
+ $pack->status = LanguagePackStatus::Active->value;
$pack->is_protected = true;
- $pack->source_type = \App\Enums\LanguagePackSourceType::BuiltIn->value;
+ $pack->source_type = LanguagePackSourceType::BuiltIn->value;
$pack->source_url = $langPathRelative;
$pack->manifest = [
'identifier' => $identifier,
diff --git a/app/Repositories/LayoutExtensionVersionRepository.php b/app/Repositories/LayoutExtensionVersionRepository.php
index 3c9b9dab..04f82095 100644
--- a/app/Repositories/LayoutExtensionVersionRepository.php
+++ b/app/Repositories/LayoutExtensionVersionRepository.php
@@ -48,20 +48,49 @@ class LayoutExtensionVersionRepository implements LayoutExtensionVersionReposito
}
/**
- * 특정 확장의 모든 버전 조회 (최신순)
+ * 특정 확장의 최근 버전 목록 조회 (최신순)
*
* @param int $extensionId 레이아웃 확장 ID
+ * @param int $limit 조회할 최대 버전 수 (버전 행은 정리되지 않고 쌓이므로 상한 필수)
* @return Collection 버전 컬렉션
*/
- public function getVersions(int $extensionId): Collection
+ public function getVersions(int $extensionId, int $limit = 100): Collection
{
// creator eager load — 버전 목록에 저장자 이름(created_by_name) 노출용 (N+1 회피,
// 레이아웃 본체 getVersionsByLayoutId 와 동일 정책).
+ //
+ // 버전 행은 저장할 때마다 쌓이고 정리되지 않으므로 조회 건수에 상한을 둔다. 목록이 쓰지
+ // 않는 `content`(버전마다 확장 본문 사본)도 조회하지 않는다 — 본문은 버전 비교 diff
+ // 전용이며 단건 조회가 공급한다. (레이아웃 본체와 동일 정책)
return $this->model
->with('creator:id,name')
->where('extension_id', $extensionId)
->orderBy('version', 'desc')
- ->get();
+ ->limit($limit)
+ ->get(['id', 'extension_id', 'version', 'changes_summary', 'created_by', 'created_at']);
+ }
+
+ /**
+ * 확장의 특정 버전 번호 조회 (본문 포함)
+ *
+ * 목록(getVersions)에서 뺀 `content` 의 대체 경로다. 목록 조회를 재사용하면 두 가지가
+ * 동시에 깨진다 — ① 목록이 조회하지 않는 `content` 가 빈 값이 되어 버전 비교 diff 가
+ * "전 항목 삭제"로 표시되고 ② 목록 상한(기본 100건) 밖의 오래된 버전이 404 가 된다.
+ * (레이아웃 본체 LayoutRepository::findVersionByNumber 와 동일 정책)
+ *
+ * @param int $extensionId 레이아웃 확장 ID
+ * @param int $version 버전 번호
+ * @return TemplateLayoutExtensionVersion|null 찾은 버전 모델 또는 null
+ */
+ public function findVersionByNumber(int $extensionId, int $version): ?TemplateLayoutExtensionVersion
+ {
+ // creator eager load — 단건 버전 조회도 저장자 이름을 목록과 일관 노출.
+ return $this->model
+ ->newQuery()
+ ->with('creator:id,name')
+ ->where('extension_id', $extensionId)
+ ->where('version', $version)
+ ->first();
}
/**
diff --git a/app/Repositories/LayoutRepository.php b/app/Repositories/LayoutRepository.php
index 46eba571..388a6e17 100644
--- a/app/Repositories/LayoutRepository.php
+++ b/app/Repositories/LayoutRepository.php
@@ -7,22 +7,88 @@ use App\Enums\LayoutSourceType;
use App\Models\TemplateLayout;
use App\Models\TemplateLayoutVersion;
use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Support\Collection as SupportCollection;
class LayoutRepository implements LayoutRepositoryInterface
{
+ /** @var int 목록 조회 시 본문을 흘려 읽는 청크 크기 */
+ private const LIST_CHUNK_SIZE = 25;
+
/**
* 특정 템플릿의 모든 레이아웃 조회
*
+ * 편집 본문(`content`)은 읽지 않는다. 이 메서드의 남은 소비처는 캐시 무효화
+ * (`InvalidatesLayoutCache` 트레이트)뿐이고 그 경로는 캐시 키를 만드는 식별 컬럼만 쓰는데,
+ * 템플릿 하나에 수십~수백 레이아웃이 있으면 본문 JSON 전량이 메모리에 올라온다.
+ *
+ * 목록 응답은 이 메서드가 아니라 {@see getListByTemplateId()} 가 공급하고(본문에서 파생되는
+ * 설명·크기만 남기고 본문은 즉시 버린다), 본문 자체가 필요한 경로는 단건 조회
+ * (`findByName`)가 공급한다.
+ *
* @param int $templateId 템플릿 ID
* @return Collection 레이아웃 컬렉션
*/
public function getByTemplateId(int $templateId): Collection
{
return TemplateLayout::where('template_id', $templateId)
+ ->select([
+ 'id', 'template_id', 'name', 'original_content_hash', 'original_content_size',
+ 'extends', 'source_type', 'source_identifier', 'created_by', 'updated_by',
+ 'lock_version', 'created_at', 'updated_at',
+ ])
->orderBy('name')
->get();
}
+ /**
+ * 목록 표시용 경량 레이아웃 행을 조회합니다.
+ *
+ * 목록 화면은 이름·설명·크기·수정일만 쓰고 본문은 상세 엔드포인트가 따로 제공한다.
+ * 그런데 `getByTemplateId()` 로 전체 컬럼을 읽으면 `content`(레이아웃 본문)까지 전부
+ * 메모리에 올라간다 — sirsoft-admin_basic 기준 102행 합계 17MB 이상이다.
+ *
+ * 여기서는 chunk 로 흘려 읽으며 본문에서 파생되는 값(설명·크기)만 뽑고 본문 자체는
+ * 즉시 버린다. 결과적으로 반환 컬렉션에 본문이 남지 않고, PHP 피크 메모리도 청크
+ * 단위로 묶인다.
+ *
+ * @param int $templateId 대상 템플릿 ID
+ * @return Collection 목록 행 배열 (id, template_id, name, description, size, lock_version, created_at, updated_at)
+ */
+ public function getListByTemplateId(int $templateId): SupportCollection
+ {
+ $rows = collect();
+
+ // 순회 커서는 기본키다 — `chunkById` 는 `where id > lastId` 로 다음 페이지를 잡으므로
+ // 여기에 `orderBy('name')` 을 함께 걸면 정렬 순서와 커서 기준이 어긋나 행이 조용히
+ // 누락된다(실측: 102행 중 58행만 반환). 표시 정렬은 순회를 마친 뒤에 적용한다.
+ TemplateLayout::query()
+ ->where('template_id', $templateId)
+ ->select(['id', 'template_id', 'name', 'content', 'lock_version', 'created_at', 'updated_at'])
+ ->chunkById(self::LIST_CHUNK_SIZE, function (Collection $chunk) use ($rows) {
+ foreach ($chunk as $layout) {
+ $content = $layout->content;
+ $contentJson = is_array($content)
+ ? json_encode($content, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE)
+ : '{}';
+
+ $rows->push([
+ 'id' => $layout->id,
+ 'template_id' => $layout->template_id,
+ 'name' => $layout->name,
+ // 본문에서 파생 — 이 값만 남기고 본문은 버린다
+ 'description' => $content['meta']['description'] ?? null,
+ 'size' => strlen($contentJson),
+ 'lock_version' => $layout->lock_version,
+ 'created_at' => $layout->created_at,
+ 'updated_at' => $layout->updated_at,
+ ]);
+ }
+ });
+
+ // 표시 정렬은 순회와 분리 — 커서 기준(id)과 섞으면 행이 누락된다
+ return $rows->sortBy('name', SORT_STRING)->values();
+ }
+
/**
* 특정 레이아웃 조회 (템플릿 ID와 이름으로)
*
@@ -37,6 +103,28 @@ class LayoutRepository implements LayoutRepositoryInterface
->first();
}
+ /**
+ * 특정 레이아웃을 영구 삭제 (템플릿 ID와 이름으로)
+ *
+ * @param int $templateId 템플릿 ID
+ * @param string $name 레이아웃 이름
+ * @return bool 삭제 여부 (대상 부재 시 false)
+ */
+ public function deleteByName(int $templateId, string $name): bool
+ {
+ $layout = TemplateLayout::where('template_id', $templateId)
+ ->where('name', $name)
+ ->first();
+
+ if (! $layout) {
+ return false;
+ }
+
+ $layout->forceDelete();
+
+ return true;
+ }
+
/**
* ID로 레이아웃 조회
*
@@ -261,15 +349,24 @@ class LayoutRepository implements LayoutRepositoryInterface
* 특정 레이아웃의 모든 버전 조회
*
* @param int $layoutId 레이아웃 ID
+ * @param int $limit 조회할 최대 버전 수 (버전 행은 정리되지 않고 쌓이므로 상한 필수)
* @return Collection 버전 컬렉션
*/
- public function getVersionsByLayoutId(int $layoutId): Collection
+ public function getVersionsByLayoutId(int $layoutId, int $limit = 100): Collection
{
// creator eager load — 버전 목록에 저장자 이름(created_by_name) 노출용 (N+1 회피).
+ //
+ // 목록이 쓰는 컬럼만 조회한다. `content` 는 버전마다 레이아웃 본문 사본이라, 상한이 있어도
+ // 100건이면 본문 100벌을 읽는다. 본문은 버전 비교 diff 전용이며 단건 조회가 공급한다.
+ // 정렬 기준은 `version` — 레이아웃 안에서 유일하다(uk_layout_version). 종전의
+ // `latest()`(created_at)는 같은 초에 저장된 버전들의 순서를 정하지 못해, 상한이 걸린
+ // 지금은 "어느 100건이 오는가" 까지 실행마다 달라질 수 있다.
return TemplateLayoutVersion::with('creator:id,name')
->where('layout_id', $layoutId)
- ->latest()
- ->get();
+ ->orderBy('version', 'desc')
+ ->limit($limit)
+ // 이 테이블에는 updated_at 이 없다 (버전 행은 불변 스냅샷이라 created_at 만 둔다)
+ ->get(['id', 'layout_id', 'version', 'changes_summary', 'created_by', 'created_at']);
}
/**
@@ -323,9 +420,9 @@ class LayoutRepository implements LayoutRepositoryInterface
* 특정 템플릿의 모든 레이아웃 이름 조회
*
* @param int $templateId 템플릿 ID
- * @return \Illuminate\Support\Collection 레이아웃 이름 컬렉션
+ * @return SupportCollection 레이아웃 이름 컬렉션
*/
- public function getLayoutNamesByTemplateId(int $templateId): \Illuminate\Support\Collection
+ public function getLayoutNamesByTemplateId(int $templateId): SupportCollection
{
return TemplateLayout::where('template_id', $templateId)
->pluck('name')
diff --git a/app/Repositories/MenuRepository.php b/app/Repositories/MenuRepository.php
index 126ae382..b9d5b17b 100644
--- a/app/Repositories/MenuRepository.php
+++ b/app/Repositories/MenuRepository.php
@@ -3,15 +3,31 @@
namespace App\Repositories;
use App\Contracts\Repositories\MenuRepositoryInterface;
-use App\Helpers\PermissionHelper;
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
+ */
+ private const TRANSLATABLE_COLUMNS = ['name'];
+
/**
* 모든 메뉴를 조회합니다.
*
@@ -37,6 +53,14 @@ class MenuRepository implements MenuRepositoryInterface
->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) {
@@ -67,13 +91,18 @@ class MenuRepository implements MenuRepositoryInterface
}
return $query->with(['creator', 'roles', 'children' => function ($query) use ($extensionFilter, $user) {
- $query->where($extensionFilter);
- if ($user) {
- $query->accessibleBy($user);
- }
- $query->with('roles')
- ->orderBy('order');
- }])
+ $query->where($extensionFilter);
+ if ($user) {
+ $query->accessibleBy($user);
+ }
+ // 하위 메뉴의 역할은 목록에서 로드하지 않는다 — 화면이 쓰는 것은 하위 메뉴의
+ // 개수와 표시 정보뿐이고, 역할 배지는 선택한(상위) 메뉴에만 나온다. 로드하면
+ // 상위 메뉴마다 하위 전체의 역할 피벗까지 함께 실려 응답이 배가 된다.
+ // Resource 는 로드되지 않은 하위 메뉴의 `roles` 키를 **생략**한다(빈 배열이 아니다)
+ // — 빈 배열은 "역할 제한 없음" 이라는 사실 아닌 단언이 되어, 화면이 그 값을 그대로
+ // 저장 요청에 실으면 역할 제한이 통째로 해제된다.
+ $query->orderBy('order');
+ }])
->orderBy('order')
->get();
}
@@ -260,7 +289,7 @@ class MenuRepository implements MenuRepositoryInterface
$q->where('extension_type', ExtensionOwnerType::Module)
->whereExists(function ($subQuery) {
$subQuery->select(DB::raw(1))
- ->from('modules')
+ ->from((new Module)->getTable())
->whereColumn('modules.identifier', 'menus.extension_identifier')
->where('modules.status', 'active');
});
@@ -270,7 +299,7 @@ class MenuRepository implements MenuRepositoryInterface
$q->where('extension_type', ExtensionOwnerType::Plugin)
->whereExists(function ($subQuery) {
$subQuery->select(DB::raw(1))
- ->from('plugins')
+ ->from((new Plugin)->getTable())
->whereColumn('plugins.identifier', 'menus.extension_identifier')
->where('plugins.status', 'active');
});
@@ -359,6 +388,15 @@ class MenuRepository implements MenuRepositoryInterface
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) {
@@ -408,20 +446,20 @@ class MenuRepository implements MenuRepositoryInterface
$query->where(function ($q) use ($searchableFields, $value, $operator) {
foreach ($searchableFields as $searchField) {
$q->orWhere(function ($subQ) use ($searchField, $value, $operator) {
- $this->applyFilterOperator($subQ, $searchField, $value, $operator);
+ $this->applySearchableField($subQ, $searchField, $value, $operator);
});
}
});
} elseif (in_array($field, $searchableFields)) {
- $this->applyFilterOperator($query, $field, $value, $operator);
+ $this->applySearchableField($query, $field, $value, $operator);
}
}
}
- // 정렬
- $sortBy = $filters['sort_by'] ?? 'order';
- $sortOrder = $filters['sort_order'] ?? 'asc';
- $query->orderBy($sortBy, $sortOrder);
+ // 정렬 (허용 컬럼 화이트리스트로 해석)
+ 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) {
@@ -437,18 +475,86 @@ class MenuRepository implements MenuRepositoryInterface
$childQuery->where('is_active', $filters['is_active']);
}
- $childQuery->with('roles')->orderBy('order');
+ // 하위 메뉴의 역할은 목록에서 로드하지 않는다 — 화면이 쓰는 것은 하위 메뉴의
+ // 개수와 표시 정보뿐이고, 역할 배지는 선택한(상위) 메뉴에만 나온다. 로드하면
+ // 상위 메뉴마다 하위 전체의 역할 피벗까지 함께 실려 응답이 배가 된다.
+ // 접근 제어(accessibleBy)는 whereHas 로 결과 집합을 좁히므로 그대로 유지된다.
+ // Resource 는 로드되지 않은 하위 메뉴의 `roles` 키를 생략한다 — 위 메서드와 동일.
+ $childQuery->orderBy('order');
}])->get();
}
/**
* 필터 연산자를 쿼리에 적용합니다.
*
- * @param \Illuminate\Database\Eloquent\Builder $query 쿼리 빌더
+ * @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 로케일 코드 목록
+ */
+ 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) {
diff --git a/app/Repositories/NotificationDefinitionRepository.php b/app/Repositories/NotificationDefinitionRepository.php
index a652e898..482fac38 100644
--- a/app/Repositories/NotificationDefinitionRepository.php
+++ b/app/Repositories/NotificationDefinitionRepository.php
@@ -4,15 +4,28 @@ namespace App\Repositories;
use App\Contracts\Repositories\NotificationDefinitionRepositoryInterface;
use App\Models\NotificationDefinition;
+use App\Repositories\Concerns\ResolvesSortSpec;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Pagination\LengthAwarePaginator;
class NotificationDefinitionRepository implements NotificationDefinitionRepositoryInterface
{
+ use ResolvesSortSpec;
+
+ /** 허용 정렬 컬럼 (NotificationDefinitionIndexRequest 와 동일 집합) */
+ private const SORTABLE_COLUMNS = [
+ 'id',
+ 'type',
+ 'extension_type',
+ 'is_active',
+ 'created_at',
+ 'updated_at',
+ ];
+
/**
* ID로 알림 정의 조회.
*
- * @param int $id
+ * @param int $id
* @return NotificationDefinition|null
*/
public function findById(int $id): ?NotificationDefinition
@@ -23,7 +36,7 @@ class NotificationDefinitionRepository implements NotificationDefinitionReposito
/**
* 타입으로 알림 정의 조회.
*
- * @param string $type
+ * @param string $type
* @return NotificationDefinition|null
*/
public function findByType(string $type): ?NotificationDefinition
@@ -34,7 +47,7 @@ class NotificationDefinitionRepository implements NotificationDefinitionReposito
/**
* 활성 상태인 특정 타입 알림 정의 조회.
*
- * @param string $type
+ * @param string $type
* @return NotificationDefinition|null
*/
public function getActiveByType(string $type): ?NotificationDefinition
@@ -58,7 +71,7 @@ class NotificationDefinitionRepository implements NotificationDefinitionReposito
* 알림 목록 응답에서 N+1 회피 목적으로 한 번 호출하여 [type => label] 맵을 생성합니다.
* 라벨 fallback 우선순위: 사용자 로케일 → ko → en → type 식별자
*
- * @param string|null $locale 사용자 로케일 (null이면 app()->getLocale())
+ * @param string|null $locale 사용자 로케일 (null이면 app()->getLocale())
* @return array
*/
public function getLabelMap(?string $locale = null): array
@@ -86,8 +99,8 @@ class NotificationDefinitionRepository implements NotificationDefinitionReposito
/**
* 특정 확장의 알림 정의 목록 조회.
*
- * @param string $extensionType
- * @param string $extensionIdentifier
+ * @param string $extensionType
+ * @param string $extensionIdentifier
* @return Collection
*/
public function getByExtension(string $extensionType, string $extensionIdentifier): Collection
@@ -98,8 +111,8 @@ class NotificationDefinitionRepository implements NotificationDefinitionReposito
/**
* 알림 정의 수정.
*
- * @param NotificationDefinition $definition
- * @param array $data
+ * @param NotificationDefinition $definition
+ * @param array $data
* @return NotificationDefinition
*/
public function update(NotificationDefinition $definition, array $data): NotificationDefinition
@@ -112,13 +125,34 @@ class NotificationDefinitionRepository implements NotificationDefinitionReposito
/**
* 페이지네이션 목록 조회.
*
- * @param array $filters
- * @param int $perPage
+ * @param array $filters
+ * @param int $perPage
* @return LengthAwarePaginator
*/
public function getPaginated(array $filters = [], int $perPage = 20): LengthAwarePaginator
{
- $query = NotificationDefinition::with('templates');
+ // 목록은 템플릿 본문을 싣지 않는다.
+ //
+ // 좁히지 않으면 한 페이지를 여는 것만으로 그 페이지 전 정의의 **모든 채널** 제목·본문이
+ // 응답에 실린다(정의 하나당 채널 × 로케일). 화면은 한 번에 한 채널만 그리므로 그 채널을
+ // `template_channel` 로 지정해 요청한다 — 지정하지 않은 호출자는 템플릿을 받지 않고,
+ // 필요하면 단건 조회(`GET .../notification-definitions/{id}`)가 전 채널을 제공한다.
+ $templateChannel = $filters['template_channel'] ?? null;
+
+ $query = NotificationDefinition::query()
+ // "되돌리기" 버튼 노출 조건은 채널을 가리지 않고 "커스터마이즈된 템플릿이 하나라도
+ // 있는가" 다. 템플릿을 한 채널로 좁히면 배열만으로는 알 수 없으므로 집계로 낸다.
+ ->withCount([
+ 'templates as customized_templates_count' => function ($q) {
+ $q->where('is_default', false);
+ },
+ ]);
+
+ if (! empty($templateChannel)) {
+ $query->with([
+ 'templates' => fn ($q) => $q->where('channel', $templateChannel),
+ ]);
+ }
if (! empty($filters['extension_type'])) {
$query->where('extension_type', $filters['extension_type']);
@@ -148,10 +182,11 @@ class NotificationDefinitionRepository implements NotificationDefinitionReposito
});
}
- $sortBy = $filters['sort_by'] ?? 'id';
- $sortOrder = $filters['sort_order'] ?? 'asc';
- $query->orderBy($sortBy, $sortOrder);
+ foreach ($this->resolveSortSpec($filters, self::SORTABLE_COLUMNS, 'id', 'asc') as $sort) {
+ $query->orderBy($sort['column'], $sort['direction']);
+ }
+ // audit:allow repository-paginate-column-pruning reason: 알림 정의 테이블 — 정의 수가 고정이고 넓은 컬럼이 없다
return $query->paginate($perPage);
}
}
diff --git a/app/Repositories/NotificationLogRepository.php b/app/Repositories/NotificationLogRepository.php
index f92cf1a4..52415dc6 100644
--- a/app/Repositories/NotificationLogRepository.php
+++ b/app/Repositories/NotificationLogRepository.php
@@ -6,12 +6,39 @@ use App\Contracts\Repositories\NotificationLogRepositoryInterface;
use App\Enums\NotificationLogStatus;
use App\Models\NotificationLog;
use App\Models\User;
+use App\Repositories\Concerns\PaginatesWithDeferredJoin;
+use App\Repositories\Concerns\ResolvesSortSpec;
+use App\Support\Query\KeysetPaginator;
+use App\Support\Query\PaginationLimits;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Pagination\CursorPaginator;
use Illuminate\Pagination\LengthAwarePaginator;
class NotificationLogRepository implements NotificationLogRepositoryInterface
{
+ use PaginatesWithDeferredJoin;
+ use ResolvesSortSpec;
+
+ /**
+ * 발송 이력 목록 정렬 허용 컬럼
+ *
+ * 요청 값을 그대로 orderBy 에 넘기면 없는 컬럼으로 SQL 오류가 나거나 인덱스 없는 컬럼
+ * 정렬을 강제할 수 있다.
+ *
+ * @var array
+ */
+ private const SORTABLE_COLUMNS = [
+ 'id',
+ 'sent_at',
+ 'created_at',
+ 'status',
+ 'channel',
+ 'notification_type',
+ 'recipient_name',
+ 'subject',
+ ];
+
/**
* 최근 발송된 알림 로그를 발송 시각 최신순으로 조회합니다 (대시보드 최근 알림).
*
@@ -77,11 +104,12 @@ class NotificationLogRepository implements NotificationLogRepositoryInterface
* @param array $filters 필터 조건
* @param int $perPage 페이지당 건수
* @param User|null $scopeUser 스코프 적용 대상 사용자 (null이면 스코프 미적용)
- * @return LengthAwarePaginator 페이지네이션 결과
+ * @return LengthAwarePaginator|CursorPaginator 페이지네이션 결과 (커서 요청 시 키셋)
*/
- public function getPaginated(array $filters = [], int $perPage = 20, ?User $scopeUser = null): LengthAwarePaginator
+ public function getPaginated(array $filters = [], int $perPage = 20, ?User $scopeUser = null): LengthAwarePaginator|CursorPaginator
{
- $query = NotificationLog::with(['senderUser', 'recipientUser']);
+ // 관계는 지연 조인의 outer 에서만 로드한다 (inner 는 키 컬럼만 조회한다)
+ $query = NotificationLog::query();
// notification-logs scope: 전달된 사용자의 권한 스코프 적용
if ($scopeUser) {
@@ -125,11 +153,39 @@ class NotificationLogRepository implements NotificationLogRepositoryInterface
});
}
- $sortBy = $filters['sort_by'] ?? 'sent_at';
- $sortOrder = $filters['sort_order'] ?? 'desc';
- $query->orderBy($sortBy, $sortOrder);
+ $sort = $this->resolveSortSpec($filters, self::SORTABLE_COLUMNS, 'sent_at');
- return $query->paginate($perPage);
+ // 커서를 받은 요청은 키셋으로 응답한다. 로그는 계속 쌓이기만 해서 깊은 페이지를
+ // OFFSET 으로 훑으면 건너뛸 행을 실제로 읽어야 하지만, 커서는 직전 페이지의 정렬
+ // 키를 WHERE 경계로 삼아 깊이와 무관하게 일정하다.
+ $sortKeys = array_map(
+ static fn (array $spec): array => [$spec['column'], $spec['direction']],
+ $sort
+ );
+
+ if (! empty($filters['cursor']) && KeysetPaginator::supports($sortKeys, self::SORTABLE_COLUMNS)) {
+ return KeysetPaginator::paginate(
+ query: $query->with(['senderUser', 'recipientUser']),
+ perPage: $perPage,
+ sortKeys: $sortKeys,
+ uniqueKey: 'id',
+ cursor: (string) $filters['cursor'],
+ );
+ }
+
+ // 목록 컬럼을 좁히지 않는 이유: 이 목록의 리소스는 렌더링된 본문(longText `body`)까지
+ // 그대로 노출하므로 컬럼을 빼면 응답 계약이 바뀐다. 지연 조인만으로도 본문을 읽는
+ // 행 수가 OFFSET 과 무관하게 이번 페이지 분량으로 고정된다.
+ return $this->paginateWithDeferredJoin(
+ query: $query,
+ columns: ['*'],
+ sort: $sort,
+ perPage: $perPage,
+ relations: ['senderUser', 'recipientUser'],
+ // 로그 테이블은 계속 쌓이기만 한다. 총 건수는 상한까지만 세고 "다음" 이동은
+ // per_page + 1 실측으로 끝까지 열어 둔다 (계산 불가는 마지막 페이지 번호 하나뿐).
+ resultCap: PaginationLimits::resultCap('admin.notification_logs'),
+ );
}
/**
diff --git a/app/Repositories/NotificationRepository.php b/app/Repositories/NotificationRepository.php
index bc23df76..07a4cb10 100644
--- a/app/Repositories/NotificationRepository.php
+++ b/app/Repositories/NotificationRepository.php
@@ -4,6 +4,8 @@ namespace App\Repositories;
use App\Contracts\Repositories\NotificationRepositoryInterface;
use App\Models\User;
+use App\Support\Query\BoundedPaginator;
+use App\Support\Query\PaginationLimits;
use Illuminate\Notifications\DatabaseNotification;
use Illuminate\Pagination\LengthAwarePaginator;
@@ -11,6 +13,11 @@ class NotificationRepository implements NotificationRepositoryInterface
{
/**
* 사용자의 알림 목록을 페이지네이션으로 조회합니다.
+ *
+ * @param User $user 대상 사용자
+ * @param array $filters 필터 조건 (read: unread|read)
+ * @param int $perPage 페이지당 항목 수
+ * @return LengthAwarePaginator 페이지네이션된 알림 목록
*/
public function getByUser(User $user, array $filters = [], int $perPage = 20): LengthAwarePaginator
{
@@ -22,11 +29,26 @@ class NotificationRepository implements NotificationRepositoryInterface
$query->whereNotNull('read_at');
}
- return $query->orderBy('created_at', 'desc')->paginate($perPage);
+ // audit:allow repository-paginate-column-pruning reason: 사용자 1명에 종속된 알림함 —
+ // $user->notifications() 로 이미 좁혀지고, 목록이 표시하는 본문 자체가 data(JSON) 라
+ // 걷어낼 넓은 컬럼이 없다
+ // 정렬 마지막의 기본키는 전순서 보장용이다 — created_at 동률에서 페이지 경계가
+ // 흔들려 인접 페이지가 같은 알림을 중복 노출하고 다른 알림을 누락하는 것을 막는다.
+ //
+ // 알림함은 한 사용자에 묶이지만 시간이 지날수록 계속 쌓인다(설정성 테이블이 아니다).
+ // 총 건수는 상한까지만 세고, 뒤쪽 페이지 이동은 실측으로 끝까지 열어 둔다.
+ return BoundedPaginator::paginate(
+ $query->orderBy('created_at', 'desc')->orderBy('id', 'desc'),
+ perPage: $perPage,
+ resultCap: PaginationLimits::resultCap('user.notifications'),
+ );
}
/**
* 사용자의 미읽음 알림 수를 반환합니다.
+ *
+ * @param User $user 대상 사용자
+ * @return int 미읽음 알림 수
*/
public function getUnreadCount(User $user): int
{
@@ -35,6 +57,10 @@ class NotificationRepository implements NotificationRepositoryInterface
/**
* 특정 알림을 읽음 처리합니다.
+ *
+ * @param User $user 대상 사용자
+ * @param string $notificationId 알림 ID
+ * @return DatabaseNotification|null 읽음 처리된 알림 (없으면 null)
*/
public function markAsRead(User $user, string $notificationId): ?DatabaseNotification
{
@@ -51,6 +77,10 @@ class NotificationRepository implements NotificationRepositoryInterface
/**
* 지정된 알림들을 일괄 읽음 처리합니다.
+ *
+ * @param User $user 대상 사용자
+ * @param array $ids 알림 ID 배열
+ * @return int 읽음 처리된 알림 수
*/
public function markBatchAsRead(User $user, array $ids): int
{
@@ -61,6 +91,9 @@ class NotificationRepository implements NotificationRepositoryInterface
/**
* 사용자의 모든 미읽음 알림을 읽음 처리합니다.
+ *
+ * @param User $user 대상 사용자
+ * @return int 읽음 처리된 알림 수
*/
public function markAllAsRead(User $user): int
{
@@ -73,6 +106,10 @@ class NotificationRepository implements NotificationRepositoryInterface
/**
* 알림을 삭제합니다.
+ *
+ * @param User $user 대상 사용자
+ * @param string $notificationId 알림 ID
+ * @return bool 삭제 성공 여부 (알림이 없으면 false)
*/
public function delete(User $user, string $notificationId): bool
{
@@ -88,7 +125,7 @@ class NotificationRepository implements NotificationRepositoryInterface
/**
* 사용자의 모든 알림을 삭제합니다.
*
- * @param User $user
+ * @param User $user
* @return int 삭제된 알림 수
*/
public function deleteAll(User $user): int
@@ -99,6 +136,8 @@ class NotificationRepository implements NotificationRepositoryInterface
/**
* 오래된 알림을 정리합니다.
*
+ * @param int $readRetentionDays 읽은 알림 보관 일수 (0 이하면 정리하지 않음)
+ * @param int $unreadRetentionDays 미읽음 알림 보관 일수 (0 이하면 정리하지 않음)
* @return array{deleted_read: int, deleted_unread: int}
*/
public function cleanup(int $readRetentionDays, int $unreadRetentionDays): array
diff --git a/app/Repositories/RoleRepository.php b/app/Repositories/RoleRepository.php
index 0b960311..05275a46 100644
--- a/app/Repositories/RoleRepository.php
+++ b/app/Repositories/RoleRepository.php
@@ -17,6 +17,7 @@ class RoleRepository implements RoleRepositoryInterface
*/
public function getAll(): Collection
{
+ // audit:allow query-unbounded-get reason: 역할은 운영자가 정의한 수만큼만 존재한다 (회원 수와 무관)
return Role::with(['permissions'])
->orderBy('id')
->get();
@@ -29,6 +30,7 @@ class RoleRepository implements RoleRepositoryInterface
*/
public function getActiveRoles(): Collection
{
+ // audit:allow query-unbounded-get reason: 역할은 운영자가 정의한 수만큼만 존재한다 (회원 수와 무관)
return Role::where('is_active', true)
->orderBy('id')
->get();
@@ -142,6 +144,7 @@ class RoleRepository implements RoleRepositoryInterface
*/
public function getByExtension(ExtensionOwnerType $extensionType, string $extensionIdentifier): Collection
{
+ // audit:allow query-unbounded-get reason: 역할은 운영자가 정의한 수만큼만 존재한다 (회원 수와 무관)
return Role::where('extension_type', $extensionType)
->where('extension_identifier', $extensionIdentifier)
->get();
@@ -195,9 +198,19 @@ class RoleRepository implements RoleRepositoryInterface
*/
public function getPaginated(array $filters = [], int $perPage = 20): LengthAwarePaginator
{
+ // 권한 관계는 목록에서 로드하지 않는다. 목록 화면이 쓰는 것은 이름·설명·사용자 수·활성
+ // 여부뿐인데, 로드하면 Resource 가 같은 권한 집합을 `permissions`(계층 트리)·
+ // `permission_ids`·`permission_values` 세 형태로 중복 직렬화하고, 계층 트리를 만드느라
+ // 행마다 상위/카테고리 권한을 다시 조회한다(행 수만큼 추가 쿼리).
+ //
+ // Resource 의 `relationLoaded('permissions')` 가드는 그대로 두면 여기서 로드하지 않는 것만으로
+ // 세 필드가 함께 빠진다 — 권한 편집은 단건 조회(`GET /admin/roles/{id}`)가 공급한다.
+ //
+ // 권한 **개수**는 집계로 남긴다. 목록에서 뺀 값의 대체 경로 — 권한 트리를 전송하지 않고도
+ // "이 역할에 권한이 몇 개 걸려 있는가" 를 화면이 보여줄 수 있다. 값 검사가 아니라 별칭
+ // 존재 여부로 판정하므로(RoleResource) 0건인 역할도 0 으로 정확히 표시된다.
$query = Role::query()
- ->withCount('users')
- ->with('permissions');
+ ->withCount(['users', 'permissions']);
// 검색 필터
if (! empty($filters['search'])) {
@@ -215,9 +228,14 @@ class RoleRepository implements RoleRepositoryInterface
}
// 정렬 (코어/확장 소유 역할 먼저, 그 다음 사용자 생성 역할)
+ // 정렬 마지막의 기본키는 전순서 보장용이다. 시더가 일괄 생성한 역할은 created_at 이
+ // 한 타임스탬프에 몰려 있어(실측: 한 값에 최대 10행) 키가 없으면 동률 구간의 순서가
+ // 페이지마다 달라지고, 인접 페이지가 같은 역할을 중복 노출하면서 다른 역할을 누락한다.
$query->orderByRaw('CASE WHEN extension_type IS NOT NULL THEN 0 ELSE 1 END')
- ->orderBy('created_at', 'desc');
+ ->orderBy('created_at', 'desc')
+ ->orderBy('id', 'desc');
+ // audit:allow repository-paginate-column-pruning reason: 역할 정의 테이블 — 행 수가 운영상 고정(수십 건)이고 넓은 컬럼이 없다
return $query->paginate($perPage);
}
diff --git a/app/Repositories/ScheduleHistoryRepository.php b/app/Repositories/ScheduleHistoryRepository.php
index 2f93cdc0..10cc4909 100644
--- a/app/Repositories/ScheduleHistoryRepository.php
+++ b/app/Repositories/ScheduleHistoryRepository.php
@@ -4,15 +4,22 @@ namespace App\Repositories;
use App\Contracts\Repositories\ScheduleHistoryRepositoryInterface;
use App\Models\ScheduleHistory;
+use App\Repositories\Concerns\PaginatesWithDeferredJoin;
+use App\Repositories\Concerns\ResolvesSortSpec;
+use App\Support\Query\PaginationLimits;
+use Carbon\Carbon;
use Illuminate\Contracts\Pagination\LengthAwarePaginator;
use Illuminate\Database\Eloquent\Collection;
class ScheduleHistoryRepository implements ScheduleHistoryRepositoryInterface
{
+ use PaginatesWithDeferredJoin;
+ use ResolvesSortSpec;
+
/**
* ID로 실행 이력을 찾습니다.
*
- * @param int $id 이력 ID
+ * @param int $id 이력 ID
* @return ScheduleHistory|null 찾은 이력 모델 또는 null
*/
public function findById(int $id): ?ScheduleHistory
@@ -23,7 +30,7 @@ class ScheduleHistoryRepository implements ScheduleHistoryRepositoryInterface
/**
* 새로운 실행 이력을 생성합니다.
*
- * @param array $data 이력 생성 데이터
+ * @param array $data 이력 생성 데이터
* @return ScheduleHistory 생성된 이력 모델
*/
public function create(array $data): ScheduleHistory
@@ -34,8 +41,8 @@ class ScheduleHistoryRepository implements ScheduleHistoryRepositoryInterface
/**
* 기존 실행 이력을 업데이트합니다.
*
- * @param ScheduleHistory $history 업데이트할 이력 모델
- * @param array $data 업데이트할 데이터
+ * @param ScheduleHistory $history 업데이트할 이력 모델
+ * @param array $data 업데이트할 데이터
* @return bool 업데이트 성공 여부
*/
public function update(ScheduleHistory $history, array $data): bool
@@ -46,7 +53,7 @@ class ScheduleHistoryRepository implements ScheduleHistoryRepositoryInterface
/**
* 실행 이력을 삭제합니다.
*
- * @param ScheduleHistory $history 삭제할 이력 모델
+ * @param ScheduleHistory $history 삭제할 이력 모델
* @return bool 삭제 성공 여부
*/
public function delete(ScheduleHistory $history): bool
@@ -57,50 +64,70 @@ class ScheduleHistoryRepository implements ScheduleHistoryRepositoryInterface
/**
* 특정 스케줄의 실행 이력을 페이지네이션하여 조회합니다.
*
- * @param int $scheduleId 스케줄 ID
- * @param array $filters 필터 조건 배열
+ * @param int $scheduleId 스케줄 ID
+ * @param array $filters 필터 조건 배열
* @return LengthAwarePaginator 페이지네이션된 이력 목록
*/
public function getPaginatedByScheduleId(int $scheduleId, array $filters = []): LengthAwarePaginator
{
- $query = ScheduleHistory::with('triggeredBy')
+ // 관계는 쿼리에 미리 붙이지 않는다 — 지연 조인 트레이트가 inner/outer 양쪽에서
+ // setEagerLoads([]) 로 지우므로, 여기서 with() 하면 outer 에서도 사라져
+ // ScheduleHistoryResource 의 whenLoaded('triggeredBy') 가 항상 비게 된다.
+ // 로드는 relations: 인자로 넘긴다.
+ $query = ScheduleHistory::query()
->where('schedule_id', $scheduleId);
// 상태 필터
- if (!empty($filters['status'])) {
+ if (! empty($filters['status'])) {
$query->where('status', $filters['status']);
}
// 트리거 유형 필터
- if (!empty($filters['trigger_type'])) {
+ if (! empty($filters['trigger_type'])) {
$query->where('trigger_type', $filters['trigger_type']);
}
- // 날짜 필터
- if (!empty($filters['started_from'])) {
- $query->whereDate('started_at', '>=', $filters['started_from']);
+ // 기간 필터 — whereDate 는 컬럼에 DATE() 를 씌워 인덱스를 못 쓰게 만든다.
+ // 같은 결과를 내는 범위 조건으로 바꿔 started_at 인덱스를 살린다
+ // (종료일은 그날 23:59:59.999999 까지 포함해야 whereDate 와 동일한 경계를 갖는다).
+ if (! empty($filters['started_from'])) {
+ $query->where('started_at', '>=', Carbon::parse($filters['started_from'])->startOfDay());
}
- if (!empty($filters['started_to'])) {
- $query->whereDate('started_at', '<=', $filters['started_to']);
+ if (! empty($filters['started_to'])) {
+ $query->where('started_at', '<=', Carbon::parse($filters['started_to'])->endOfDay());
}
- // 정렬 적용
- $sortBy = $filters['sort_by'] ?? 'started_at';
- $sortOrder = $filters['sort_order'] ?? 'desc';
- $query->orderBy($sortBy, $sortOrder);
+ // 정렬 — 요청 값은 허용 목록으로만 해석한다.
+ // 허용 집합은 ScheduleHistoryListRequest 의 `in:` 규칙과 동일해야 한다. 저장소 목록이
+ // 그보다 좁으면 게이트를 통과한 정렬이 조용히 기본값으로 되돌아간다 (종료시각/소요시간).
+ $sort = $this->resolveSortSpec(
+ $filters,
+ ['started_at', 'ended_at', 'duration', 'status'],
+ 'started_at'
+ );
- // 페이지네이션 적용
- $perPage = $filters['per_page'] ?? 15;
+ $perPage = (int) ($filters['per_page'] ?? 15);
- return $query->paginate($perPage);
+ // 실행 이력은 계속 쌓이며 출력/에러 메시지를 그대로 노출하므로, 컬럼은 좁히지 않고
+ // 지연 조인으로 넓은 컬럼을 읽는 행 수만 이번 페이지 분량으로 고정한다.
+ return $this->paginateWithDeferredJoin(
+ query: $query,
+ columns: ['*'],
+ sort: $sort,
+ perPage: $perPage,
+ relations: ['triggeredBy'],
+ // 로그 테이블은 계속 쌓이기만 한다. 총 건수는 상한까지만 세고 "다음" 이동은
+ // per_page + 1 실측으로 끝까지 열어 둔다 (계산 불가는 마지막 페이지 번호 하나뿐).
+ resultCap: PaginationLimits::resultCap('admin.schedule_histories'),
+ );
}
/**
* 특정 스케줄의 최근 실행 이력을 조회합니다.
*
- * @param int $scheduleId 스케줄 ID
- * @param int $limit 조회 개수
+ * @param int $scheduleId 스케줄 ID
+ * @param int $limit 조회 개수
* @return Collection 최근 이력 컬렉션
*/
public function getRecentByScheduleId(int $scheduleId, int $limit = 10): Collection
@@ -115,7 +142,7 @@ class ScheduleHistoryRepository implements ScheduleHistoryRepositoryInterface
/**
* 여러 이력을 일괄 삭제합니다.
*
- * @param array $ids 이력 ID 배열
+ * @param array $ids 이력 ID 배열
* @return int 삭제된 레코드 수
*/
public function bulkDelete(array $ids): int
@@ -126,7 +153,7 @@ class ScheduleHistoryRepository implements ScheduleHistoryRepositoryInterface
/**
* 특정 스케줄의 모든 이력을 삭제합니다.
*
- * @param int $scheduleId 스케줄 ID
+ * @param int $scheduleId 스케줄 ID
* @return int 삭제된 레코드 수
*/
public function deleteByScheduleId(int $scheduleId): int
@@ -137,7 +164,7 @@ class ScheduleHistoryRepository implements ScheduleHistoryRepositoryInterface
/**
* 특정 기간 이전의 이력을 삭제합니다.
*
- * @param int $days 보관 기간 (일)
+ * @param int $days 보관 기간 (일)
* @return int 삭제된 레코드 수
*/
public function deleteOlderThan(int $days): int
diff --git a/app/Repositories/ScheduleRepository.php b/app/Repositories/ScheduleRepository.php
index dfe718b3..88d0e41c 100644
--- a/app/Repositories/ScheduleRepository.php
+++ b/app/Repositories/ScheduleRepository.php
@@ -3,29 +3,45 @@
namespace App\Repositories;
use App\Contracts\Repositories\ScheduleRepositoryInterface;
-use App\Helpers\PermissionHelper;
use App\Enums\ScheduleFrequency;
use App\Enums\ScheduleResultStatus;
use App\Enums\ScheduleType;
+use App\Helpers\PermissionHelper;
use App\Models\Schedule;
+use App\Repositories\Concerns\FiltersByDateRange;
use App\Repositories\Concerns\HasMultipleSearchFilters;
+use App\Repositories\Concerns\ResolvesSortSpec;
use Illuminate\Contracts\Pagination\LengthAwarePaginator;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
class ScheduleRepository implements ScheduleRepositoryInterface
{
+ use FiltersByDateRange;
use HasMultipleSearchFilters;
+ use ResolvesSortSpec;
/**
* 검색 가능한 필드 목록
*/
private const SEARCHABLE_FIELDS = ['name', 'description', 'command'];
+ /**
+ * 허용 정렬 컬럼 (ScheduleListRequest 와 동일 집합)
+ */
+ private const SORTABLE_COLUMNS = [
+ 'created_at',
+ 'name',
+ 'next_run_at',
+ 'last_run_at',
+ 'is_active',
+ 'last_result',
+ ];
+
/**
* ID로 스케줄을 찾습니다.
*
- * @param int $id 스케줄 ID
+ * @param int $id 스케줄 ID
* @return Schedule|null 찾은 스케줄 모델 또는 null
*/
public function findById(int $id): ?Schedule
@@ -36,7 +52,7 @@ class ScheduleRepository implements ScheduleRepositoryInterface
/**
* 새로운 스케줄을 생성합니다.
*
- * @param array $data 스케줄 생성 데이터
+ * @param array $data 스케줄 생성 데이터
* @return Schedule 생성된 스케줄 모델
*/
public function create(array $data): Schedule
@@ -47,8 +63,8 @@ class ScheduleRepository implements ScheduleRepositoryInterface
/**
* 기존 스케줄을 업데이트합니다.
*
- * @param Schedule $schedule 업데이트할 스케줄 모델
- * @param array $data 업데이트할 데이터
+ * @param Schedule $schedule 업데이트할 스케줄 모델
+ * @param array $data 업데이트할 데이터
* @return bool 업데이트 성공 여부
*/
public function update(Schedule $schedule, array $data): bool
@@ -59,7 +75,7 @@ class ScheduleRepository implements ScheduleRepositoryInterface
/**
* 스케줄을 삭제합니다.
*
- * @param Schedule $schedule 삭제할 스케줄 모델
+ * @param Schedule $schedule 삭제할 스케줄 모델
* @return bool 삭제 성공 여부
*/
public function delete(Schedule $schedule): bool
@@ -80,7 +96,7 @@ class ScheduleRepository implements ScheduleRepositoryInterface
/**
* 필터링 및 페이지네이션이 적용된 스케줄 목록을 조회합니다.
*
- * @param array $filters 필터 조건 배열
+ * @param array $filters 필터 조건 배열
* @return LengthAwarePaginator 페이지네이션된 스케줄 목록
*/
public function getPaginatedSchedules(array $filters = []): LengthAwarePaginator
@@ -93,33 +109,34 @@ class ScheduleRepository implements ScheduleRepositoryInterface
// 필터 조건 적용
$this->applyFilters($query, $filters);
- // 정렬 적용
- $sortBy = $filters['sort_by'] ?? 'created_at';
- $sortOrder = $filters['sort_order'] ?? 'desc';
- $query->orderBy($sortBy, $sortOrder);
+ // 정렬 적용 (허용 컬럼 화이트리스트로 해석)
+ foreach ($this->resolveSortSpec($filters, self::SORTABLE_COLUMNS, 'created_at') as $sort) {
+ $query->orderBy($sort['column'], $sort['direction']);
+ }
// 페이지네이션 적용
$perPage = $filters['per_page'] ?? 15;
+ // audit:allow repository-paginate-column-pruning reason: 스케줄 정의 테이블 — 등록된 스케줄 수만큼만 존재하고 넓은 컬럼이 없다
return $query->paginate($perPage);
}
/**
* 쿼리에 필터 조건을 적용합니다.
*
- * @param Builder $query Eloquent 쿼리 빌더
- * @param array $filters 적용할 필터 조건 배열
+ * @param Builder $query Eloquent 쿼리 빌더
+ * @param array $filters 적용할 필터 조건 배열
* @return void
*/
private function applyFilters(Builder $query, array $filters): void
{
// 다중 검색 조건 적용
- if (!empty($filters['filters']) && is_array($filters['filters'])) {
+ if (! empty($filters['filters']) && is_array($filters['filters'])) {
$this->applyMultipleSearchFilters($query, $filters['filters'], self::SEARCHABLE_FIELDS);
}
// 타입 필터
- if (!empty($filters['type'])) {
+ if (! empty($filters['type'])) {
$type = ScheduleType::tryFrom($filters['type']);
if ($type) {
$query->where('type', $type);
@@ -127,7 +144,7 @@ class ScheduleRepository implements ScheduleRepositoryInterface
}
// 주기 필터
- if (!empty($filters['frequency'])) {
+ if (! empty($filters['frequency'])) {
$frequency = ScheduleFrequency::tryFrom($filters['frequency']);
if ($frequency) {
$query->where('frequency', $frequency);
@@ -135,7 +152,7 @@ class ScheduleRepository implements ScheduleRepositoryInterface
}
// 상태 필터
- if (!empty($filters['status'])) {
+ if (! empty($filters['status'])) {
if ($filters['status'] === 'active') {
$query->where('is_active', true);
} elseif ($filters['status'] === 'inactive') {
@@ -144,7 +161,7 @@ class ScheduleRepository implements ScheduleRepositoryInterface
}
// 마지막 실행 결과 필터
- if (!empty($filters['last_result'])) {
+ if (! empty($filters['last_result'])) {
$result = ScheduleResultStatus::tryFrom($filters['last_result']);
if ($result) {
$query->where('last_result', $result);
@@ -162,10 +179,10 @@ class ScheduleRepository implements ScheduleRepositoryInterface
}
// 확장 타입 필터
- if (!empty($filters['extension_type'])) {
+ if (! empty($filters['extension_type'])) {
$query->where('extension_type', $filters['extension_type']);
- if (!empty($filters['extension_identifier'])) {
+ if (! empty($filters['extension_identifier'])) {
$query->where('extension_identifier', $filters['extension_identifier']);
}
}
@@ -177,19 +194,19 @@ class ScheduleRepository implements ScheduleRepositoryInterface
/**
* 날짜 필터를 적용합니다.
*
- * @param Builder $query Eloquent 쿼리 빌더
- * @param array $filters 필터 조건 배열
+ * @param Builder $query Eloquent 쿼리 빌더
+ * @param array $filters 필터 조건 배열
* @return void
*/
private function applyDateFilters(Builder $query, array $filters): void
{
- if (!empty($filters['created_from'])) {
- $query->whereDate('created_at', '>=', $filters['created_from']);
- }
-
- if (!empty($filters['created_to'])) {
- $query->whereDate('created_at', '<=', $filters['created_to']);
- }
+ // whereDate 는 컬럼에 DATE() 를 씌워 인덱스를 무력화한다 — 범위 조건으로 준다.
+ $this->applyDateRangeFilter(
+ $query,
+ 'created_at',
+ $filters['created_from'] ?? null,
+ $filters['created_to'] ?? null
+ );
}
/**
@@ -233,8 +250,8 @@ class ScheduleRepository implements ScheduleRepositoryInterface
/**
* 여러 스케줄의 상태를 일괄 업데이트합니다.
*
- * @param array $ids 스케줄 ID 배열
- * @param bool $isActive 활성화 여부
+ * @param array $ids 스케줄 ID 배열
+ * @param bool $isActive 활성화 여부
* @return int 업데이트된 레코드 수
*/
public function bulkUpdateStatus(array $ids, bool $isActive): int
@@ -245,7 +262,7 @@ class ScheduleRepository implements ScheduleRepositoryInterface
/**
* 여러 스케줄을 일괄 삭제합니다.
*
- * @param array $ids 스케줄 ID 배열
+ * @param array $ids 스케줄 ID 배열
* @return int 삭제된 레코드 수
*/
public function bulkDelete(array $ids): int
@@ -256,13 +273,13 @@ class ScheduleRepository implements ScheduleRepositoryInterface
/**
* 스케줄을 복제합니다.
*
- * @param Schedule $schedule 복제할 스케줄
+ * @param Schedule $schedule 복제할 스케줄
* @return Schedule 복제된 스케줄
*/
public function duplicate(Schedule $schedule): Schedule
{
$newSchedule = $schedule->replicate();
- $newSchedule->name = $schedule->name . ' (' . __('schedule.copy') . ')';
+ $newSchedule->name = $schedule->name.' ('.__('schedule.copy').')';
$newSchedule->is_active = false;
$newSchedule->last_result = ScheduleResultStatus::Never;
$newSchedule->last_run_at = null;
diff --git a/app/Repositories/SeoCacheStatRepository.php b/app/Repositories/SeoCacheStatRepository.php
new file mode 100644
index 00000000..a6bb968e
--- /dev/null
+++ b/app/Repositories/SeoCacheStatRepository.php
@@ -0,0 +1,135 @@
+
+ */
+ private const GROUPABLE_COLUMNS = ['layout_name', 'module_identifier'];
+
+ /**
+ * 캐시 통계 레코드를 기록합니다.
+ *
+ * @param array $attributes 기록할 속성
+ */
+ public function record(array $attributes): void
+ {
+ SeoCacheStat::create($attributes);
+ }
+
+ /**
+ * 전체 캐시 통계를 집계합니다.
+ *
+ * @param Carbon|null $since 집계 시작 시점 (null 이면 전체 기간)
+ * @return array{total: int, hits: int, misses: int, avg_response_time_ms: float|null} 집계 결과
+ */
+ public function aggregate(?Carbon $since = null): array
+ {
+ $row = $this->baseQuery($since)
+ ->select($this->aggregateSelects())
+ ->first();
+
+ return [
+ 'total' => (int) ($row->total ?? 0),
+ 'hits' => (int) ($row->hits ?? 0),
+ 'misses' => (int) ($row->misses ?? 0),
+ 'avg_response_time_ms' => $row?->avg_response_time_ms !== null
+ ? (float) $row->avg_response_time_ms
+ : null,
+ ];
+ }
+
+ /**
+ * 지정한 컬럼으로 그룹화하여 캐시 통계를 집계합니다.
+ *
+ * @param string $groupBy 그룹 기준 컬럼 (layout_name | module_identifier)
+ * @param Carbon|null $since 집계 시작 시점 (null 이면 전체 기간)
+ * @return array 그룹별 집계 결과
+ *
+ * @throws \InvalidArgumentException 허용되지 않은 그룹 컬럼인 경우
+ */
+ public function aggregateGrouped(string $groupBy, ?Carbon $since = null): array
+ {
+ if (! in_array($groupBy, self::GROUPABLE_COLUMNS, true)) {
+ throw new \InvalidArgumentException(
+ __('exceptions.seo.sitemap_stat_group_column_unsupported', ['column' => $groupBy])
+ );
+ }
+
+ return $this->baseQuery($since)
+ ->select(array_merge([$groupBy], $this->aggregateSelects()))
+ ->groupBy($groupBy)
+ ->get()
+ ->map(fn ($row): array => [
+ 'group' => $row->{$groupBy},
+ 'total' => (int) $row->total,
+ 'hits' => (int) $row->hits,
+ 'misses' => (int) $row->misses,
+ 'avg_response_time_ms' => $row->avg_response_time_ms !== null
+ ? (float) $row->avg_response_time_ms
+ : null,
+ ])
+ ->all();
+ }
+
+ /**
+ * 기준 시점보다 오래된 통계 레코드를 삭제합니다.
+ *
+ * @param Carbon $cutoff 기준 시점
+ * @return int 삭제된 레코드 수
+ */
+ public function deleteOlderThan(Carbon $cutoff): int
+ {
+ return SeoCacheStat::where('created_at', '<', $cutoff)->delete();
+ }
+
+ /**
+ * 기간 필터가 적용된 기본 쿼리를 반환합니다.
+ *
+ * @param Carbon|null $since 집계 시작 시점
+ * @return Builder 쿼리 빌더
+ */
+ private function baseQuery(?Carbon $since): Builder
+ {
+ $query = SeoCacheStat::query();
+
+ if ($since) {
+ $query->since($since);
+ }
+
+ return $query;
+ }
+
+ /**
+ * 집계 select 절을 반환합니다.
+ *
+ * hit/miss 는 단일 순회로 집계하기 위해 조건부 합계를 사용합니다.
+ *
+ * @return array select 표현식 배열
+ */
+ private function aggregateSelects(): array
+ {
+ return [
+ DB::raw('COUNT(*) as total'),
+ DB::raw("SUM(CASE WHEN type = 'hit' THEN 1 ELSE 0 END) as hits"),
+ DB::raw("SUM(CASE WHEN type = 'miss' THEN 1 ELSE 0 END) as misses"),
+ DB::raw("AVG(CASE WHEN type = 'miss' AND response_time_ms IS NOT NULL THEN response_time_ms ELSE NULL END) as avg_response_time_ms"),
+ ];
+ }
+}
diff --git a/app/Repositories/SitemapUrlRepository.php b/app/Repositories/SitemapUrlRepository.php
new file mode 100644
index 00000000..e2e1025d
--- /dev/null
+++ b/app/Repositories/SitemapUrlRepository.php
@@ -0,0 +1,179 @@
+where('resource_type', $type)
+ ->where('resource_id', $id)
+ ->delete();
+
+ $now = now();
+ $rows = [];
+ foreach ($entries as $entry) {
+ $rows[] = $this->toRow(
+ $type,
+ $id,
+ (string) ($entry['contributor'] ?? ''),
+ $entry,
+ $now,
+ );
+ }
+
+ if ($rows !== []) {
+ SitemapUrl::insert($rows);
+ }
+ });
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public function removeForResource(string $type, string $id): void
+ {
+ SitemapUrl::query()
+ ->where('resource_type', $type)
+ ->where('resource_id', $id)
+ ->delete();
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public function streamVisible(?string $contributor = null): iterable
+ {
+ $query = SitemapUrl::query()->where('is_visible', true);
+
+ if ($contributor !== null) {
+ $query->where('contributor', $contributor);
+ }
+
+ // lazyById 는 id 키셋 페이징이라 결과셋 전체를 메모리/드라이버 버퍼에 적재하지 않습니다.
+ return $query->lazyById(self::STREAM_CHUNK);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public function countVisible(): int
+ {
+ return SitemapUrl::query()->where('is_visible', true)->count();
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public function replaceAllForContributor(string $contributor, iterable $entries): int
+ {
+ // 기여자 스코프 전량 제거 후 청크 삽입. 대용량(수백만) 삽입을 단일 트랜잭션으로
+ // 감싸면 락/메모리 부담이 크므로, 삭제 후 청크별 삽입으로 유계 메모리를 유지합니다.
+ SitemapUrl::query()->where('contributor', $contributor)->delete();
+
+ $now = now();
+ $batch = [];
+ $inserted = 0;
+ foreach ($entries as $entry) {
+ $batch[] = $this->toRow(
+ (string) ($entry['resource_type'] ?? 'unknown'),
+ isset($entry['resource_id']) && $entry['resource_id'] !== null
+ ? (string) $entry['resource_id']
+ : null,
+ $contributor,
+ $entry,
+ $now,
+ );
+
+ if (count($batch) >= self::INSERT_CHUNK) {
+ SitemapUrl::insert($batch);
+ $inserted += count($batch);
+ $batch = [];
+ }
+ }
+
+ if ($batch !== []) {
+ SitemapUrl::insert($batch);
+ $inserted += count($batch);
+ }
+
+ return $inserted;
+ }
+
+ /**
+ * URL 항목을 sitemap_urls 삽입용 행으로 변환합니다.
+ *
+ * @param string $type 리소스 유형
+ * @param string|null $id 리소스 PK (문자열, 없으면 null)
+ * @param string $contributor 기여자 식별자
+ * @param array $entry URL 항목 (loc/lastmod/changefreq/priority)
+ * @param Carbon $now 타임스탬프 기준값
+ * @return array 삽입용 행
+ */
+ private function toRow(string $type, ?string $id, string $contributor, array $entry, Carbon $now): array
+ {
+ $loc = (string) ($entry['loc'] ?? '');
+
+ return [
+ 'resource_type' => $type,
+ 'resource_id' => $id,
+ 'loc' => $loc,
+ 'loc_hash' => hash('sha256', $loc),
+ 'lastmod' => $this->normalizeLastmod($entry['lastmod'] ?? null),
+ 'changefreq' => $entry['changefreq'] ?? null,
+ 'priority' => $entry['priority'] ?? null,
+ 'contributor' => $contributor,
+ 'is_visible' => true,
+ 'created_at' => $now,
+ 'updated_at' => $now,
+ ];
+ }
+
+ /**
+ * lastmod 값을 DB 저장용 타임스탬프 문자열로 정규화합니다.
+ *
+ * insert() 는 모델 캐스팅을 우회하므로 W3C 문자열/Carbon 을 직접 파싱합니다.
+ *
+ * @param mixed $lastmod 원본 lastmod (문자열/Carbon/null)
+ * @return string|null 정규화된 'Y-m-d H:i:s' 또는 null
+ */
+ private function normalizeLastmod(mixed $lastmod): ?string
+ {
+ if ($lastmod === null || $lastmod === '') {
+ return null;
+ }
+
+ try {
+ return Carbon::parse($lastmod)->format('Y-m-d H:i:s');
+ } catch (\Throwable) {
+ return null;
+ }
+ }
+}
diff --git a/app/Repositories/UserRepository.php b/app/Repositories/UserRepository.php
index cf24e644..f76f248c 100644
--- a/app/Repositories/UserRepository.php
+++ b/app/Repositories/UserRepository.php
@@ -5,21 +5,34 @@ namespace App\Repositories;
use App\Contracts\Repositories\UserRepositoryInterface;
use App\Helpers\PermissionHelper;
use App\Models\User;
+use App\Repositories\Concerns\FiltersByDateRange;
use App\Repositories\Concerns\HasMultipleSearchFilters;
+use App\Repositories\Concerns\PaginatesWithDeferredJoin;
+use App\Repositories\Concerns\ResolvesSortSpec;
+use App\Support\Query\PaginationLimits;
use Illuminate\Contracts\Pagination\LengthAwarePaginator;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Support\Carbon;
+use Laravel\Sanctum\PersonalAccessToken;
class UserRepository implements UserRepositoryInterface
{
+ use FiltersByDateRange;
use HasMultipleSearchFilters;
+ use PaginatesWithDeferredJoin;
+ use ResolvesSortSpec;
/**
* 검색 가능한 필드 목록
*/
private const SEARCHABLE_FIELDS = ['name', 'email'];
+ /**
+ * 허용 정렬 컬럼 (UserListRequest 와 동일 집합)
+ */
+ private const SORTABLE_COLUMNS = ['created_at', 'name', 'email', 'last_login_at'];
+
/**
* 이메일로 사용자를 찾습니다.
*
@@ -99,21 +112,25 @@ class UserRepository implements UserRepositoryInterface
// 권한 스코프 필터링
PermissionHelper::applyPermissionScope($query, 'core.users.read');
- // roles 관계 eager loading
- $query->with('roles');
-
// 검색 조건 적용
$this->applyFilters($query, $filters);
- // 정렬 적용
- $sortBy = $filters['sort_by'] ?? 'created_at';
- $sortOrder = $filters['sort_order'] ?? 'desc';
- $query->orderBy($sortBy, $sortOrder);
+ // 정렬 적용 (허용 컬럼 화이트리스트로 해석)
+ $sort = $this->resolveSortSpec($filters, self::SORTABLE_COLUMNS, 'created_at');
// 페이지네이션 적용
$perPage = $filters['per_page'] ?? 15;
- return $query->paginate($perPage);
+ // 지연 조인: inner 는 id 만 훑고 roles eager loading 은 해당 페이지에만 적용된다
+ return $this->paginateWithDeferredJoin(
+ query: $query,
+ columns: ['*'],
+ sort: $sort,
+ perPage: $perPage,
+ relations: ['roles'],
+ // 회원 수가 커져도 목록 첫 화면 비용이 총 건수 COUNT 에 끌려가지 않도록 상한을 건다.
+ resultCap: PaginationLimits::resultCap('admin.users'),
+ );
}
/**
@@ -141,13 +158,13 @@ class UserRepository implements UserRepositoryInterface
*/
private function applyDateFilters(Builder $query, array $filters): void
{
- if (! empty($filters['start_date'])) {
- $query->whereDate('created_at', '>=', $filters['start_date']);
- }
-
- if (! empty($filters['end_date'])) {
- $query->whereDate('created_at', '<=', $filters['end_date']);
- }
+ // whereDate 는 컬럼에 DATE() 를 씌워 인덱스를 무력화한다 — 범위 조건으로 준다.
+ $this->applyDateRangeFilter(
+ $query,
+ 'created_at',
+ $filters['start_date'] ?? null,
+ $filters['end_date'] ?? null
+ );
// 기본 날짜 필터 (전체가 아닌 경우)
if (empty($filters['start_date']) && empty($filters['end_date']) &&
@@ -294,16 +311,22 @@ class UserRepository implements UserRepositoryInterface
/**
* 사용자의 계정을 지정된 분만큼 잠급니다.
*
+ * `$minutes <= 0` 은 보안 환경설정의 "0 = 무한대" 규약에 따라 영구 잠금으로 처리합니다.
+ * 영구 잠금은 해제 시각이 없으므로 `locked_until` 을 NULL 로 두고
+ * `locked_permanently` 플래그로 상태를 표현합니다 (NULL 은 이미 "잠금 없음" 을 의미).
+ *
* @param User $user 잠글 사용자
- * @param int $minutes 잠금 유지 시간(분)
- * @return Carbon 잠금 해제 시각
+ * @param int $minutes 잠금 유지 시간(분). 0 이하는 무기한
+ * @return Carbon|null 잠금 해제 시각 (영구 잠금은 null)
*/
- public function lockAccount(User $user, int $minutes): Carbon
+ public function lockAccount(User $user, int $minutes): ?Carbon
{
- $lockedUntil = now()->addMinutes(max(1, $minutes));
+ $permanent = $minutes <= 0;
+ $lockedUntil = $permanent ? null : now()->addMinutes($minutes);
$user->forceFill([
'locked_until' => $lockedUntil,
+ 'locked_permanently' => $permanent,
'failed_login_attempts' => 0,
])->save();
@@ -321,15 +344,18 @@ class UserRepository implements UserRepositoryInterface
{
$needsReset = ($user->failed_login_attempts ?? 0) > 0
|| $user->locked_until !== null
+ || (bool) $user->locked_permanently
|| $user->last_failed_login_at !== null;
if (! $needsReset) {
return;
}
+ // locked_permanently 를 빠뜨리면 성공 로그인·관리자 해제 후에도 영구 잠금이 잔존한다.
$user->forceFill([
'failed_login_attempts' => 0,
'locked_until' => null,
+ 'locked_permanently' => false,
'last_failed_login_at' => null,
])->save();
}
@@ -342,10 +368,92 @@ class UserRepository implements UserRepositoryInterface
*/
public function isLocked(User $user): bool
{
+ // 영구 잠금 판정이 먼저 — 해제 시각이 없으므로 NULL 체크에 먼저 걸리면 안 된다.
+ if ((bool) $user->locked_permanently) {
+ return true;
+ }
+
if ($user->locked_until === null) {
return false;
}
return $user->locked_until->isFuture();
}
+
+ /**
+ * UUID 로 사용자를 찾습니다.
+ *
+ * @param string $uuid 사용자 UUID
+ * @return User|null 찾은 사용자 모델 또는 null
+ */
+ public function findByUuid(string $uuid): ?User
+ {
+ return User::where('uuid', $uuid)->first();
+ }
+
+ /**
+ * UUID 목록에 해당하는 사용자의 정수 ID 배열을 반환합니다.
+ *
+ * @param array $uuids 사용자 UUID 배열
+ * @return array 사용자 ID 배열
+ */
+ public function getIdsByUuids(array $uuids): array
+ {
+ if (empty($uuids)) {
+ return [];
+ }
+
+ return User::whereIn('uuid', $uuids)->pluck('id')->all();
+ }
+
+ /**
+ * 사용자 ID 목록에 해당하는 이름을 ID 로 색인해 반환합니다.
+ *
+ * 목록 화면이 작성자 이름을 행마다 조회하면 N+1 이 되므로, 표시에 필요한
+ * 이름만 한 번에 모아 옵니다.
+ *
+ * @param array $ids 사용자 ID 배열
+ * @return array 사용자 ID => 이름
+ */
+ public function getNamesByIds(array $ids): array
+ {
+ if (empty($ids)) {
+ return [];
+ }
+
+ return User::whereIn('id', $ids)->pluck('name', 'id')->all();
+ }
+
+ /**
+ * 사용자 ID 목록의 지정 컬럼을 일괄 갱신합니다.
+ *
+ * @param array $ids 사용자 ID 배열
+ * @param array $data 갱신할 컬럼 값
+ * @return int 갱신된 행 수
+ */
+ public function updateManyByIds(array $ids, array $data): int
+ {
+ if (empty($ids)) {
+ return 0;
+ }
+
+ return User::whereIn('id', $ids)->update($data);
+ }
+
+ /**
+ * 사용자 ID 목록의 인증 토큰을 모두 삭제합니다.
+ *
+ * @param array $ids 사용자 ID 배열
+ * @return int 삭제된 토큰 수
+ */
+ public function deleteTokensByUserIds(array $ids): int
+ {
+ if (empty($ids)) {
+ return 0;
+ }
+
+ return PersonalAccessToken::where('tokenable_type', User::class)
+ ->whereIn('tokenable_id', $ids)
+ ->delete();
+ }
}
diff --git a/app/Rules/AllowedArtisanCommand.php b/app/Rules/AllowedArtisanCommand.php
index d3dae0ef..300241d5 100644
--- a/app/Rules/AllowedArtisanCommand.php
+++ b/app/Rules/AllowedArtisanCommand.php
@@ -7,14 +7,25 @@ use Closure;
use Illuminate\Contracts\Validation\ValidationRule;
/**
- * Artisan 타입 스케줄의 command 가 차단목록에 걸리지 않는지 검증하는 Custom Rule.
+ * Artisan 타입 스케줄의 command 가 실행 허용 목록 안인지 검증하는 Custom Rule.
*
- * `tinker` 처럼 임의 PHP 코드를 실행하거나 `db:wipe` 처럼 파괴적인 명령을 스케줄로 등록하는 것을
- * 저장 시점에 차단한다. 차단목록은 `config/schedule_security.php` 가 소유하며 관리자 환경설정에
- * 노출되지 않는다.
+ * 허용목록에 없는 명령, 선언되지 않은 옵션, 위치 인자, 그리고 Symfony 가 다르게 해석할 수 있는
+ * 형태(따옴표·백슬래시·단축 옵션)를 저장 시점에 차단한다. 정책은 `config/schedule_security.php`
+ * 가 소유하며 관리자 환경설정에 노출되지 않는다.
+ *
+ * 어느 항목이 왜 막혔는지 드러나도록 거부 사유별로 메시지를 분기한다.
*/
class AllowedArtisanCommand implements ValidationRule
{
+ /** 거부 사유 코드 → 다국어 키 */
+ private const REASON_MESSAGES = [
+ ScheduleCommandValidator::ARTISAN_REASON_DENIED => 'validation.schedule_command.artisan_denied',
+ ScheduleCommandValidator::ARTISAN_REASON_NOT_ALLOWED => 'validation.schedule_command.artisan_not_allowlisted',
+ ScheduleCommandValidator::ARTISAN_REASON_MALFORMED => 'validation.schedule_command.artisan_malformed',
+ ScheduleCommandValidator::ARTISAN_REASON_OPTION => 'validation.schedule_command.artisan_option_denied',
+ ScheduleCommandValidator::ARTISAN_REASON_ARGUMENT => 'validation.schedule_command.artisan_argument_denied',
+ ];
+
/**
* 값이 실행 허용된 artisan 명령인지 검증합니다.
*
@@ -29,13 +40,19 @@ class AllowedArtisanCommand implements ValidationRule
}
if (! is_string($value)) {
- $fail(__('validation.schedule_command.artisan_denied'));
+ $fail(__('validation.schedule_command.artisan_malformed'));
return;
}
- if (! ScheduleCommandValidator::isArtisanCommandAllowed($value)) {
- $fail(__('validation.schedule_command.artisan_denied'));
+ $verdict = ScheduleCommandValidator::inspectArtisanCommand($value);
+
+ if ($verdict['allowed']) {
+ return;
}
+
+ $key = self::REASON_MESSAGES[$verdict['reason']] ?? 'validation.schedule_command.artisan_not_allowlisted';
+
+ $fail(__($key));
}
}
diff --git a/app/Rules/AllowedModuleFileType.php b/app/Rules/AllowedModuleFileType.php
index f69fd3bd..a212873c 100644
--- a/app/Rules/AllowedModuleFileType.php
+++ b/app/Rules/AllowedModuleFileType.php
@@ -39,11 +39,12 @@ class AllowedModuleFileType implements ValidationRule
}
$extension = strtolower(pathinfo($value, PATHINFO_EXTENSION));
+ $allowed = self::getAllowedExtensions();
- if (! in_array($extension, self::ALLOWED_EXTENSIONS, true)) {
+ if (! in_array($extension, $allowed, true)) {
$fail(__('validation.module_path.file_type_not_allowed', [
'extension' => $extension,
- 'allowed' => implode(', ', self::ALLOWED_EXTENSIONS),
+ 'allowed' => implode(', ', $allowed),
]));
return;
@@ -53,10 +54,20 @@ class AllowedModuleFileType implements ValidationRule
/**
* 허용된 확장자 목록 반환
*
- * @return array
+ * 로컬 개발 환경에서만 소스맵(`map`)을 덧붙인다. dev 빌드 산출물은
+ * `//# sourceMappingURL` 이 개별 에셋 서빙 URL 을 가리키므로 서빙되어야
+ * 브라우저 콘솔에 404 가 남지 않는다. 반면 소스맵에는 원본 코드 전문
+ * (`sourcesContent`)이 담겨 있고 이 화이트리스트가 에셋 서빙의 유일한
+ * 방어선이므로, 운영 환경에서는 어떤 경우에도 서빙하지 않는다.
+ *
+ * @return array 허용된 확장자 목록
*/
public static function getAllowedExtensions(): array
{
+ if (app()->environment('local')) {
+ return [...self::ALLOWED_EXTENSIONS, 'map'];
+ }
+
return self::ALLOWED_EXTENSIONS;
}
}
diff --git a/app/Rules/AllowedPluginFileType.php b/app/Rules/AllowedPluginFileType.php
index 0ced5c11..b4ccab54 100644
--- a/app/Rules/AllowedPluginFileType.php
+++ b/app/Rules/AllowedPluginFileType.php
@@ -39,11 +39,12 @@ class AllowedPluginFileType implements ValidationRule
}
$extension = strtolower(pathinfo($value, PATHINFO_EXTENSION));
+ $allowed = self::getAllowedExtensions();
- if (! in_array($extension, self::ALLOWED_EXTENSIONS, true)) {
+ if (! in_array($extension, $allowed, true)) {
$fail(__('validation.plugin_path.file_type_not_allowed', [
'extension' => $extension,
- 'allowed' => implode(', ', self::ALLOWED_EXTENSIONS),
+ 'allowed' => implode(', ', $allowed),
]));
return;
@@ -53,10 +54,20 @@ class AllowedPluginFileType implements ValidationRule
/**
* 허용된 확장자 목록 반환
*
- * @return array
+ * 로컬 개발 환경에서만 소스맵(`map`)을 덧붙인다. dev 빌드 산출물은
+ * `//# sourceMappingURL` 이 개별 에셋 서빙 URL 을 가리키므로 서빙되어야
+ * 브라우저 콘솔에 404 가 남지 않는다. 반면 소스맵에는 원본 코드 전문
+ * (`sourcesContent`)이 담겨 있고 이 화이트리스트가 에셋 서빙의 유일한
+ * 방어선이므로, 운영 환경에서는 어떤 경우에도 서빙하지 않는다.
+ *
+ * @return array 허용된 확장자 목록
*/
public static function getAllowedExtensions(): array
{
+ if (app()->environment('local')) {
+ return [...self::ALLOWED_EXTENSIONS, 'map'];
+ }
+
return self::ALLOWED_EXTENSIONS;
}
}
diff --git a/app/Rules/AllowedTemplateFileType.php b/app/Rules/AllowedTemplateFileType.php
index 391876b6..1614e5bc 100644
--- a/app/Rules/AllowedTemplateFileType.php
+++ b/app/Rules/AllowedTemplateFileType.php
@@ -32,18 +32,21 @@ class AllowedTemplateFileType implements ValidationRule
*/
public function validate(string $attribute, mixed $value, Closure $fail): void
{
- if (!is_string($value)) {
+ if (! is_string($value)) {
$fail(__('validation.template_path.must_be_string'));
+
return;
}
$extension = strtolower(pathinfo($value, PATHINFO_EXTENSION));
+ $allowed = self::getAllowedExtensions();
- if (!in_array($extension, self::ALLOWED_EXTENSIONS, true)) {
+ if (! in_array($extension, $allowed, true)) {
$fail(__('validation.template_path.file_type_not_allowed', [
'extension' => $extension,
- 'allowed' => implode(', ', self::ALLOWED_EXTENSIONS),
+ 'allowed' => implode(', ', $allowed),
]));
+
return;
}
}
@@ -51,10 +54,20 @@ class AllowedTemplateFileType implements ValidationRule
/**
* 허용된 확장자 목록 반환
*
- * @return array
+ * 로컬 개발 환경에서만 소스맵(`map`)을 덧붙인다. dev 빌드 산출물은
+ * `//# sourceMappingURL` 이 개별 에셋 서빙 URL 을 가리키므로 서빙되어야
+ * 브라우저 콘솔에 404 가 남지 않는다. 반면 소스맵에는 원본 코드 전문
+ * (`sourcesContent`)이 담겨 있고 이 화이트리스트가 에셋 서빙의 유일한
+ * 방어선이므로, 운영 환경에서는 어떤 경우에도 서빙하지 않는다.
+ *
+ * @return array 허용된 확장자 목록
*/
public static function getAllowedExtensions(): array
{
+ if (app()->environment('local')) {
+ return [...self::ALLOWED_EXTENSIONS, 'map'];
+ }
+
return self::ALLOWED_EXTENSIONS;
}
}
diff --git a/app/Rules/AvailableNotificationChannel.php b/app/Rules/AvailableNotificationChannel.php
new file mode 100644
index 00000000..20c4bc7b
--- /dev/null
+++ b/app/Rules/AvailableNotificationChannel.php
@@ -0,0 +1,55 @@
+ $persistedChannels 대상 레코드에 이미 저장된 채널 목록
+ */
+ public function __construct(
+ private array $persistedChannels = []
+ ) {}
+
+ /**
+ * 검증 규칙 실행
+ *
+ * @param string $attribute 필드명
+ * @param mixed $value 검증 값
+ * @param Closure $fail 실패 콜백
+ */
+ public function validate(string $attribute, mixed $value, Closure $fail): void
+ {
+ if (! is_string($value) || $value === '') {
+ $fail(__('validation.notification_channel.invalid', ['value' => (string) $value]));
+
+ return;
+ }
+
+ if (in_array($value, $this->persistedChannels, true)) {
+ return;
+ }
+
+ if (! app(NotificationChannelService::class)->isChannelAvailable($value)) {
+ $fail(__('validation.notification_channel.unavailable', ['value' => $value]));
+ }
+ }
+}
diff --git a/app/Rules/LanguagePack/RequiresActivationPermission.php b/app/Rules/LanguagePack/RequiresActivationPermission.php
new file mode 100644
index 00000000..ae9a96df
--- /dev/null
+++ b/app/Rules/LanguagePack/RequiresActivationPermission.php
@@ -0,0 +1,49 @@
+hasPermission(self::PERMISSION, PermissionType::Admin)) {
+ $fail(__('language_packs.errors.auto_activate_requires_manage'));
+ }
+ }
+}
diff --git a/app/Rules/LocaleRequiredTranslatable.php b/app/Rules/LocaleRequiredTranslatable.php
index 34249b12..384e6a30 100644
--- a/app/Rules/LocaleRequiredTranslatable.php
+++ b/app/Rules/LocaleRequiredTranslatable.php
@@ -16,23 +16,24 @@ class LocaleRequiredTranslatable implements ValidationRule
/**
* LocaleRequiredTranslatable 생성자
*
- * @param int $maxLength 각 번역의 최대 길이
- * @param int $minLength 각 번역의 최소 길이 (기본: 0)
- * @param string|null $requiredLocale 필수 로케일 (null이면 현재 로케일 사용)
+ * @param int $maxLength 각 번역의 최대 길이
+ * @param int $minLength 각 번역의 최소 길이 (기본: 0)
+ * @param string|null $requiredLocale 필수 로케일 (null이면 현재 로케일 사용)
+ * @param bool $strictLocales 지원 목록 밖 로케일 키를 실패로 처리할지 여부
*/
public function __construct(
private int $maxLength = 255,
private int $minLength = 0,
- private ?string $requiredLocale = null
+ private ?string $requiredLocale = null,
+ private bool $strictLocales = false
) {}
/**
* 검증 규칙 실행
*
- * @param string $attribute 필드명
- * @param mixed $value 검증 값
- * @param Closure $fail 실패 콜백
- * @return void
+ * @param string $attribute 필드명
+ * @param mixed $value 검증 값
+ * @param Closure $fail 실패 콜백
*/
public function validate(string $attribute, mixed $value, Closure $fail): void
{
@@ -67,11 +68,20 @@ class LocaleRequiredTranslatable implements ValidationRule
// 각 언어별 검증
foreach ($value as $lang => $text) {
- // 지원하지 않는 언어 코드
+ // 지원 목록 밖 로케일 키
+ //
+ // app.translatable_locales 는 활성 언어팩 기준으로 부팅마다 덮어써지는 가변 런타임
+ // 값이다. 언어팩을 비활성화하면 기존 레코드에 남아 있던 그 로케일 키 때문에 수정
+ // 자체가 차단되므로, 기본값은 "길이 검증 대상에서 제외하고 통과"로 둔다.
+ // 데이터를 지우지 않으므로 언어팩을 다시 켜면 번역이 그대로 복구된다.
if (! in_array($lang, $allowedLanguages)) {
- $fail(__('validation.translatable.unsupported_language', ['lang' => $lang]));
+ if ($this->strictLocales) {
+ $fail(__('validation.translatable.unsupported_language', ['lang' => $lang]));
- return;
+ return;
+ }
+
+ continue;
}
// null이거나 빈 문자열이 아닌 경우에만 검증
diff --git a/app/Rules/NotSelfParent.php b/app/Rules/NotSelfParent.php
index daf3ec65..54866803 100644
--- a/app/Rules/NotSelfParent.php
+++ b/app/Rules/NotSelfParent.php
@@ -8,7 +8,11 @@ use Illuminate\Contracts\Validation\ValidationRule;
/**
* 자기 자신을 부모로 설정할 수 없도록 검증하는 Custom Rule
*
- * 메뉴, 카테고리 등 계층 구조에서 순환 참조를 방지합니다.
+ * 메뉴, 카테고리 등 계층 구조에서 자기참조를 방지합니다.
+ *
+ * @deprecated 자기 자신만 검사하므로 자손을 부모로 지정하는 순환은 막지 못합니다.
+ * 신규 코드는 자손 전체를 검사하는 NotCircularParent 를 사용하세요.
+ * 확장이 훅으로 이 규칙을 소비할 수 있어 클래스는 제거하지 않습니다.
*/
class NotSelfParent implements ValidationRule
{
diff --git a/app/Rules/PasswordPolicy.php b/app/Rules/PasswordPolicy.php
new file mode 100644
index 00000000..a6a9e55f
--- /dev/null
+++ b/app/Rules/PasswordPolicy.php
@@ -0,0 +1,46 @@
+ 0 ? $minLength : self::DEFAULT_MIN_LENGTH;
+
+ $rule = Password::min($minLength);
+
+ if ((bool) g7_core_settings('security.require_password_special_char', false)) {
+ $rule = $rule->symbols();
+ }
+
+ return $rule;
+ }
+}
diff --git a/app/Rules/TranslatableField.php b/app/Rules/TranslatableField.php
index 1f11f97e..c615e2a1 100644
--- a/app/Rules/TranslatableField.php
+++ b/app/Rules/TranslatableField.php
@@ -15,12 +15,14 @@ class TranslatableField implements ValidationRule
/**
* TranslatableField 생성자
*
- * @param int $maxLength 각 번역의 최대 길이
- * @param bool $required 최소 하나의 번역 필수 여부
+ * @param int $maxLength 각 번역의 최대 길이
+ * @param bool $required 최소 하나의 번역 필수 여부
+ * @param bool $strictLocales 지원 목록 밖 로케일 키를 실패로 처리할지 여부
*/
public function __construct(
private int $maxLength = 255,
- private bool $required = false
+ private bool $required = false,
+ private bool $strictLocales = false
) {}
/**
@@ -40,11 +42,20 @@ class TranslatableField implements ValidationRule
// 각 언어별 검증
foreach ($value as $lang => $text) {
- // 지원하지 않는 언어 코드
+ // 지원 목록 밖 로케일 키
+ //
+ // app.translatable_locales 는 활성 언어팩 기준으로 부팅마다 덮어써지는 가변 런타임
+ // 값이다. 언어팩을 비활성화하면 기존 레코드에 남아 있던 그 로케일 키 때문에 수정
+ // 자체가 차단되므로, 기본값은 "길이 검증 대상에서 제외하고 통과"로 둔다.
+ // 데이터를 지우지 않으므로 언어팩을 다시 켜면 번역이 그대로 복구된다.
if (! in_array($lang, $allowedLanguages)) {
- $fail(__('validation.translatable.unsupported_language', ['lang' => $lang]));
+ if ($this->strictLocales) {
+ $fail(__('validation.translatable.unsupported_language', ['lang' => $lang]));
- return;
+ return;
+ }
+
+ continue;
}
// null이거나 빈 문자열이 아닌 경우에만 검증
@@ -56,8 +67,8 @@ class TranslatableField implements ValidationRule
return;
}
- // 최대 길이 초과
- if (strlen($text) > $this->maxLength) {
+ // 최대 길이 초과 (바이트가 아닌 문자 단위로 계산)
+ if (mb_strlen($text) > $this->maxLength) {
$fail(__('validation.translatable.max_length', [
'lang' => $lang,
'max' => $this->maxLength,
diff --git a/app/Search/Contracts/KeywordPredicateProvider.php b/app/Search/Contracts/KeywordPredicateProvider.php
new file mode 100644
index 00000000..0cf66aa4
--- /dev/null
+++ b/app/Search/Contracts/KeywordPredicateProvider.php
@@ -0,0 +1,78 @@
+lookupIds($keyword, limit: $context->keyCap);
+ * $method = $boolean === 'or' ? 'orWhereIn' : 'whereIn';
+ * $query->$method($query->getModel()->getQualifiedKeyName(), $ids);
+ * }
+ * }
+ * ```
+ */
+interface KeywordPredicateProvider
+{
+ /**
+ * 쿼리에 키워드 술어를 붙입니다.
+ *
+ * 컬럼 목록은 **하나의 조건으로 함께 평가**해 달라는 요청입니다. 엔진이 그 조합을
+ * 다룰 수 없으면(예: MySQL 이 그 컬럼 조합의 복합 FULLTEXT 인덱스를 요구하는 경우)
+ * 호출자가 {@see KeywordSearch::applyAny()} 로 컬럼별 OR 을 요청합니다.
+ *
+ * 매칭이 하나도 없을 수 있는 검색어(예: 연산자만 입력)에는 **항상 거짓인 조건**을
+ * 붙여야 합니다. 아무 조건도 붙이지 않으면 필터 없는 전체 목록이 검색 결과로 나갑니다.
+ *
+ * **페이지네이션은 호출자(DB)가 담당합니다.** 엔진에게 페이지 번호를 넘기지 않는 이유는,
+ * 엔진이 자기 순서로 한 페이지 분량만 돌려주면 그 뒤에 적용되는 DB 필터(분류·전시상태·
+ * 조인)에 일부가 탈락해 페이지가 비고, DB 정렬과 엔진의 관련도 순서가 달라 페이지 경계도
+ * 어긋나기 때문입니다. 엔진이 책임지는 것은 **"얼마까지 돌려줄 것인가"** 하나입니다.
+ *
+ * 키 집합을 만들어 조건으로 붙이는 구현은 `$context->keyCap` 을 반드시 지켜야 합니다.
+ * 지키지 않으면 매칭이 큰 검색어에서 그 집합 자체가 메모리 폭발이 됩니다. 상한에 걸려
+ * 잘린 경우 그 이상은 도달 불가이며, 총 건수는 "이상" 으로 보고됩니다
+ * ({@see PaginationLimits} 와 같은 의미).
+ *
+ * @param Builder $query 조건을 붙일 Eloquent 쿼리 빌더
+ * @param array $columns 검색 대상 컬럼명
+ * @param string $keyword 검색어 원문 (정제는 엔진이 수행)
+ * @param string $boolean 기존 조건과의 결합 방식 ('and' 또는 'or')
+ * @param KeywordSearchContext $context 술어 생성 조건 (키 집합 상한 등)
+ */
+ public function applyKeywordPredicate(
+ Builder $query,
+ array $columns,
+ string $keyword,
+ string $boolean,
+ KeywordSearchContext $context
+ ): void;
+}
diff --git a/app/Search/Contracts/SearchIndexMaintainer.php b/app/Search/Contracts/SearchIndexMaintainer.php
new file mode 100644
index 00000000..60f98e84
--- /dev/null
+++ b/app/Search/Contracts/SearchIndexMaintainer.php
@@ -0,0 +1,78 @@
+ 구현 클래스` 로 합니다.
+ *
+ * ```php
+ * HookManager::addFilter('core.search.index_maintainers', function (array $maintainers) {
+ * $maintainers['meilisearch'] = MeilisearchIndexMaintainer::class;
+ *
+ * return $maintainers;
+ * });
+ * ```
+ *
+ * 구현하지 않은 엔진은 점검 대상에서 제외될 뿐 검색 자체는 정상 동작합니다.
+ */
+interface SearchIndexMaintainer
+{
+ /**
+ * 이 유지보수기가 담당하는 Scout 드라이버명을 반환합니다.
+ *
+ * `config('scout.driver')` 값과 대조해 활성 엔진의 유지보수기를 고릅니다.
+ *
+ * @return string 드라이버명 (예: mysql-fulltext)
+ */
+ public function driver(): string;
+
+ /**
+ * 현재 환경에서 점검을 수행할 수 있는지 반환합니다.
+ *
+ * 예) FULLTEXT 미지원 DBMS, 외부 검색 서버 미연결 등에서 false.
+ *
+ * @return bool 점검 가능 여부
+ */
+ public function isAvailable(): bool;
+
+ /**
+ * 점검 불가 사유를 반환합니다.
+ *
+ * `isAvailable()` 이 false 일 때 운영자에게 보여 줄 문장입니다.
+ * 사유를 남기지 않으면 "점검 대상 0" 과 "점검할 수 없었음" 이 구분되지 않습니다.
+ *
+ * @return string|null 사유 (사용 가능하면 null)
+ */
+ public function unavailableReason(): ?string;
+
+ /**
+ * 관리 중인 인덱스의 건강도를 판정합니다.
+ *
+ * @param array $filters 엔진별 필터 (예: ['table' => 'pages'])
+ * @return array 인덱스별 판정 결과
+ */
+ public function inspect(array $filters = []): array;
+
+ /**
+ * 재생성이 필요하다고 판정된 인덱스를 재생성합니다.
+ *
+ * 재생성은 비용이 크고 서비스에 영향을 줄 수 있으므로, 호출자는 반드시
+ * 운영자의 명시적 선택을 받은 뒤에만 호출합니다.
+ *
+ * @param SearchIndexHealth $health 재생성 대상 판정 결과
+ * @return void
+ *
+ * @throws \Throwable 재생성 실패 시
+ */
+ public function rebuild(SearchIndexHealth $health): void;
+}
diff --git a/app/Search/DTO/FulltextIndexDefinition.php b/app/Search/DTO/FulltextIndexDefinition.php
new file mode 100644
index 00000000..dd1f50d3
--- /dev/null
+++ b/app/Search/DTO/FulltextIndexDefinition.php
@@ -0,0 +1,65 @@
+ $columns 색인 컬럼 목록
+ * @param string|null $parser 파서명 (예: ngram). 지정되지 않은 인덱스는 null
+ */
+ public function __construct(
+ public string $table,
+ public string $name,
+ public array $columns,
+ public ?string $parser = null,
+ ) {}
+
+ /**
+ * 백틱을 두른 테이블명을 반환합니다.
+ *
+ * @return string 예: `g7_pages`
+ */
+ public function quotedTable(): string
+ {
+ return '`'.$this->table.'`';
+ }
+
+ /**
+ * 백틱을 두른 컬럼 목록을 반환합니다.
+ *
+ * @return string 예: `title`, `content`
+ */
+ public function quotedColumns(): string
+ {
+ return '`'.implode('`, `', $this->columns).'`';
+ }
+
+ /**
+ * `ALTER TABLE ... ADD FULLTEXT` 에 붙일 파서 절을 반환합니다.
+ *
+ * @return string 파서가 없으면 빈 문자열
+ */
+ public function parserClause(): string
+ {
+ return $this->parser === null ? '' : ' WITH PARSER '.$this->parser;
+ }
+
+ /**
+ * 사람이 읽는 식별자를 반환합니다.
+ *
+ * @return string 예: g7_pages.ft_pages_title
+ */
+ public function label(): string
+ {
+ return $this->table.'.'.$this->name;
+ }
+}
diff --git a/app/Search/DTO/KeywordSearchContext.php b/app/Search/DTO/KeywordSearchContext.php
new file mode 100644
index 00000000..f0278fb1
--- /dev/null
+++ b/app/Search/DTO/KeywordSearchContext.php
@@ -0,0 +1,36 @@
+keyCap !== null && $this->keyCap > 0;
+ }
+}
diff --git a/app/Search/DTO/SearchIndexHealth.php b/app/Search/DTO/SearchIndexHealth.php
new file mode 100644
index 00000000..cfbc203d
--- /dev/null
+++ b/app/Search/DTO/SearchIndexHealth.php
@@ -0,0 +1,67 @@
+ $details 엔진별 부가 정보 (표시 전용)
+ * @param array $context 재생성에 필요한 엔진 내부 정보
+ */
+ public function __construct(
+ public string $driver,
+ public string $identifier,
+ public SearchIndexStatus $status,
+ public string $measurement = '',
+ public array $details = [],
+ public array $context = [],
+ ) {}
+
+ /**
+ * 재생성 대상인지 여부.
+ *
+ * @return bool
+ */
+ public function needsRebuild(): bool
+ {
+ return $this->status === SearchIndexStatus::Stale;
+ }
+
+ /**
+ * 기계 판독용 배열로 반환합니다.
+ *
+ * `context` 는 엔진 내부 정보라 응답에 싣지 않습니다.
+ *
+ * @return array
+ */
+ public function toArray(): array
+ {
+ return [
+ 'driver' => $this->driver,
+ 'identifier' => $this->identifier,
+ 'status' => $this->status->value,
+ 'status_label' => $this->status->label(),
+ 'measurement' => $this->measurement,
+ 'details' => $this->details,
+ ];
+ }
+}
diff --git a/app/Search/DTO/SearchIndexRepairReport.php b/app/Search/DTO/SearchIndexRepairReport.php
new file mode 100644
index 00000000..c3020976
--- /dev/null
+++ b/app/Search/DTO/SearchIndexRepairReport.php
@@ -0,0 +1,119 @@
+ $repaired 재생성 성공 인덱스 식별자
+ * @param array $failed 재생성 실패 [식별자 => 사유]
+ * @param array $remaining 재생성 후에도 색인 누락으로 남은 식별자
+ * @param bool $available 이 엔진에서 점검을 수행할 수 있었는지
+ * @param string|null $reason 수행 불가 사유 (available=false 일 때)
+ */
+ public function __construct(
+ public string $driver,
+ public int $inspected = 0,
+ public array $repaired = [],
+ public array $failed = [],
+ public array $remaining = [],
+ public bool $available = true,
+ public ?string $reason = null,
+ ) {}
+
+ /**
+ * 점검을 수행할 수 없었던 경우의 보고를 만듭니다.
+ *
+ * @param string $driver 드라이버명
+ * @param string|null $reason 사유
+ * @return self
+ */
+ public static function unavailable(string $driver, ?string $reason): self
+ {
+ return new self(driver: $driver, available: false, reason: $reason);
+ }
+
+ /**
+ * 재생성 대상이 없었을 때의 보고를 만듭니다.
+ *
+ * @param string $driver 드라이버명
+ * @param int $inspected 점검한 인덱스 수
+ * @return self
+ */
+ public static function nothingToDo(string $driver, int $inspected): self
+ {
+ return new self(driver: $driver, inspected: $inspected);
+ }
+
+ /**
+ * 재생성을 실제로 수행했는지 여부.
+ *
+ * @return bool
+ */
+ public function didRebuild(): bool
+ {
+ return $this->repaired !== [] || $this->failed !== [];
+ }
+
+ /**
+ * 전부 복구되었는지 여부 (실패·잔존 모두 없음).
+ *
+ * @return bool
+ */
+ public function isClean(): bool
+ {
+ return $this->failed === [] && $this->remaining === [];
+ }
+
+ /**
+ * 한 줄 요약을 반환합니다.
+ *
+ * @return string
+ */
+ public function summary(): string
+ {
+ if (! $this->available) {
+ return $this->reason ?? __('search.index.unavailable', ['driver' => $this->driver]);
+ }
+
+ if (! $this->didRebuild()) {
+ return __('search.index.report.nothing_to_do', ['count' => $this->inspected]);
+ }
+
+ return __('search.index.report.rebuilt', [
+ 'inspected' => $this->inspected,
+ 'repaired' => count($this->repaired),
+ 'failed' => count($this->failed),
+ 'remaining' => count($this->remaining),
+ ]);
+ }
+
+ /**
+ * 기계 판독용 배열로 반환합니다.
+ *
+ * @return array
+ */
+ public function toArray(): array
+ {
+ return [
+ 'driver' => $this->driver,
+ 'available' => $this->available,
+ 'reason' => $this->reason,
+ 'inspected' => $this->inspected,
+ 'repaired' => $this->repaired,
+ 'failed' => $this->failed,
+ 'remaining' => $this->remaining,
+ 'summary' => $this->summary(),
+ ];
+ }
+}
diff --git a/app/Search/Engines/DatabaseFulltextEngine.php b/app/Search/Engines/DatabaseFulltextEngine.php
index f77f8cdf..77f7da54 100644
--- a/app/Search/Engines/DatabaseFulltextEngine.php
+++ b/app/Search/Engines/DatabaseFulltextEngine.php
@@ -2,7 +2,13 @@
namespace App\Search\Engines;
+use App\Enums\TotalRelation;
use App\Search\Contracts\FulltextSearchable;
+use App\Search\Contracts\KeywordPredicateProvider;
+use App\Search\DTO\KeywordSearchContext;
+use App\Search\KeywordSearch;
+use App\Support\Query\BoundedPaginator;
+use App\Support\Query\PaginationLimits;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Facades\DB;
@@ -18,7 +24,7 @@ use Laravel\Scout\Engines\Engine;
*
* MySQL 자체가 인덱스 소스이므로 update/delete/flush는 no-op입니다.
*/
-class DatabaseFulltextEngine extends Engine
+class DatabaseFulltextEngine extends Engine implements KeywordPredicateProvider
{
/**
* MariaDB 감지 결과 캐시 (프로세스 수명 동안 유지)
@@ -53,20 +59,52 @@ class DatabaseFulltextEngine extends Engine
* FULLTEXT 검색을 수행합니다.
*
* @param Builder $builder Scout 빌더
- * @return array{query: \Illuminate\Database\Eloquent\Builder, total: int}
+ * @return array{query: \Illuminate\Database\Eloquent\Builder|null, total: int|null, total_relation: TotalRelation|null, result_cap: int|null}
*/
public function search(Builder $builder): array
{
return $this->performSearch($builder);
}
+ /**
+ * 검색 결과의 키 목록만 조회합니다.
+ *
+ * 총 건수를 쓰지 않는 경로이므로 COUNT 를 아예 실행하지 않고, SELECT 도 키 컬럼과
+ * 정렬용 스코어로만 좁힙니다. 좁히지 않으면 매칭된 전 행의 모든 컬럼(본문 포함)을
+ * 읽고 나서 ID 만 뽑아내게 됩니다.
+ *
+ * @param Builder $builder Scout 빌더
+ * @return \Illuminate\Support\Collection 키 컬렉션
+ */
+ public function keys(Builder $builder): \Illuminate\Support\Collection
+ {
+ return $this->mapIds($this->performSearch($builder, withTotal: false, keysOnly: true));
+ }
+
+ /**
+ * 검색 결과를 모델 컬렉션으로 조회합니다.
+ *
+ * 총 건수를 쓰지 않는 경로이므로 COUNT 를 실행하지 않습니다.
+ *
+ * @param Builder $builder Scout 빌더
+ * @return Collection 모델 컬렉션
+ */
+ public function get(Builder $builder): Collection
+ {
+ return $this->map(
+ $builder,
+ $builder->applyAfterRawSearchCallback($this->performSearch($builder, withTotal: false)),
+ $builder->model
+ );
+ }
+
/**
* 페이지네이션 적용 FULLTEXT 검색을 수행합니다.
*
* @param Builder $builder Scout 빌더
* @param int $perPage 페이지당 결과 수
* @param int $page 페이지 번호
- * @return array{query: \Illuminate\Database\Eloquent\Builder, total: int}
+ * @return array{query: \Illuminate\Database\Eloquent\Builder|null, total: int|null, total_relation: TotalRelation|null, result_cap: int|null}
*/
public function paginate(Builder $builder, $perPage, $page): array
{
@@ -76,6 +114,13 @@ class DatabaseFulltextEngine extends Engine
/**
* 검색 결과에서 모델 ID를 추출합니다.
*
+ * 넘겨받은 쿼리의 SELECT 는 건드리지 않는다 — ORDER BY 가 `_ft_score`(그리고 소비자
+ * `->query()` 콜백이 얹은 별칭)를 참조하므로 SELECT 를 갈아끼우면 정렬 대상이 사라져
+ * `Unknown column ... in 'order clause'` 로 죽는다. 키만 읽어야 하는 경로는
+ * `applySelect(keysOnly: true)` 가 조립 시점에 이미 좁혀 두었고, `pluck()` 은 기존
+ * SELECT 를 보존하므로(`onceWithColumns` 는 columns 가 있으면 덮어쓰지 않는다)
+ * 여기서 다시 좁힐 이유가 없다. `clone()` 은 호출자 쿼리 불변을 위해 유지한다.
+ *
* @param array $results 검색 결과
*/
public function mapIds($results): \Illuminate\Support\Collection
@@ -85,7 +130,7 @@ class DatabaseFulltextEngine extends Engine
return collect();
}
- return $query->pluck($query->getModel()->getKeyName());
+ return $query->clone()->pluck($query->getModel()->getKeyName());
}
/**
@@ -129,7 +174,31 @@ class DatabaseFulltextEngine extends Engine
*/
public function getTotalCount($results): int
{
- return $results['total'] ?? 0;
+ return (int) ($results['total'] ?? 0);
+ }
+
+ /**
+ * 검색 결과의 총 건수 정확도를 반환합니다.
+ *
+ * 상한을 넘겨 정확히 세지 않은 경우 `AtLeast` 입니다.
+ *
+ * @param array $results 검색 결과
+ * @return TotalRelation 총 건수 정확도
+ */
+ public function getTotalRelation($results): TotalRelation
+ {
+ return $results['total_relation'] ?? TotalRelation::Exact;
+ }
+
+ /**
+ * 총 건수 집계에 적용된 상한을 반환합니다.
+ *
+ * @param array $results 검색 결과
+ * @return int|null 상한 (무제한이면 null)
+ */
+ public function getResultCap($results): ?int
+ {
+ return $results['result_cap'] ?? null;
}
/**
@@ -239,6 +308,14 @@ class DatabaseFulltextEngine extends Engine
* MySQL 파싱 오류(ER_PARSE_ERROR)를 유발하므로, 사용자 입력을 일반 검색어로만
* 취급하도록 연산자를 제거하고 남은 토큰을 따옴표 구문으로 묶습니다.
*
+ * 토큰은 공백으로 잇습니다 — BOOLEAN MODE 에서 공백 결합은 OR 입니다. 각 토큰에 `+` 를
+ * 붙이면 AND 가 되어 매칭 집합이 줄고 대용량에서 검색 시간이 짧아질 여지가 있지만,
+ * **의도적으로 OR 을 유지합니다**. 입력한 단어 중 하나만 든 문서가 결과에서 통째로
+ * 사라지는 손실이 성능 이득보다 크기 때문입니다. 한글은 ngram 파서가 2글자 단위로
+ * 토큰을 쪼개므로 AND 전환의 결과 축소 폭이 특히 큽니다. 성능 축이 문제가 되면 결합
+ * 방식이 아니라 전용 검색 엔진(core.search.engine_drivers)으로 해결합니다.
+ * 배경·실측: docs/backend/search-system.md, docs/backend/pagination.md
+ *
* @param string $keyword 원본 검색어
* @return string 안전하게 정제된 BOOLEAN MODE 검색식 (정제 결과가 없으면 빈 문자열)
*/
@@ -267,32 +344,114 @@ class DatabaseFulltextEngine extends Engine
*
* DBMS별로 MATCH...AGAINST 또는 LIKE fallback을 자동 적용합니다.
*
+ * 검색어는 반드시 이 헬퍼를 거쳐야 합니다. BOOLEAN MODE 는 `+ - * " ( )` 등을
+ * 연산자로 해석하므로, 원문 키워드를 그대로 바인딩하면 사용자가 `+` 하나만 입력해도
+ * 파싱 오류로 500 이 됩니다. 정제는 sanitizeBooleanModeKeyword 한 곳에서만 합니다.
+ *
+ * **컬럼을 배열로 넘기면 하나의 `MATCH(a, b)` 가 됩니다.** MySQL 은 이 형태에 정확히
+ * 그 컬럼 조합의 **복합 FULLTEXT 인덱스**를 요구하며, 없으면
+ * `Can't find FULLTEXT index matching the column list` 오류가 납니다.
+ * 컬럼별 단일 인덱스만 있는 테이블은 {@see self::whereFulltextAny()} 를 쓰세요.
+ *
* @param \Illuminate\Database\Eloquent\Builder $query Eloquent 쿼리 빌더
- * @param string $column 검색 대상 컬럼명
- * @param string $keyword 검색어
+ * @param string|array $columns 검색 대상 컬럼명 (배열이면 복합 인덱스 필요)
+ * @param string $keyword 검색어 (원문 — 정제는 이 메서드가 수행)
* @param string $boolean 조건 결합 방식 ('and' 또는 'or')
*/
public static function whereFulltext(
\Illuminate\Database\Eloquent\Builder $query,
- string $column,
+ string|array $columns,
string $keyword,
string $boolean = 'and'
): void {
- if (static::supportsFulltext()) {
- $ftKeyword = static::sanitizeBooleanModeKeyword($keyword);
- if ($ftKeyword === '') {
- // 정제 결과 없음 → 항상 false 조건으로 빈 결과 (void 반환 계약 유지)
- $falseMethod = $boolean === 'or' ? 'orWhereRaw' : 'whereRaw';
- $query->$falseMethod('1 = 0');
+ // 활성 엔진 해석을 거친다 — 다른 엔진이 켜져 있으면 그 엔진이 조건을 만든다.
+ // 이 정적 헬퍼를 직접 부르던 코드도 이 경유로 엔진 교체 혜택을 받는다.
+ KeywordSearch::apply($query, $columns, $keyword, $boolean);
+ }
- return;
- }
- $method = $boolean === 'or' ? 'orWhereRaw' : 'whereRaw';
- $query->$method("MATCH(`{$column}`) AGAINST(? IN BOOLEAN MODE)", [$ftKeyword]);
- } else {
- $method = $boolean === 'or' ? 'orWhere' : 'where';
- $query->$method($column, 'LIKE', "%{$keyword}%");
+ /**
+ * {@inheritDoc}
+ *
+ * 이 엔진의 술어는 `MATCH ... AGAINST IN BOOLEAN MODE` 입니다. DBMS 가 FULLTEXT 를
+ * 지원하지 않으면 같은 자리에서 부분일치로 내려갑니다.
+ *
+ * `$context->keyCap` 은 쓰지 않습니다 — 이 엔진의 술어는 SQL 조건 그 자체라 중간
+ * 키 집합을 만들지 않으므로 상한을 적용할 대상이 없습니다. 상한은 키 집합을 만들어
+ * 조건으로 붙이는 엔진(외부 검색 서버 등)을 위한 것입니다.
+ */
+ public function applyKeywordPredicate(
+ \Illuminate\Database\Eloquent\Builder $query,
+ array $columns,
+ string $keyword,
+ string $boolean,
+ KeywordSearchContext $context
+ ): void {
+ static::applyFulltextPredicate($query, $columns, $keyword, $boolean);
+ }
+
+ /**
+ * FULLTEXT 조건을 실제로 조립합니다.
+ *
+ * @param \Illuminate\Database\Eloquent\Builder $query Eloquent 쿼리 빌더
+ * @param array $columns 검색 대상 컬럼명
+ * @param string $keyword 검색어 원문
+ * @param string $boolean 조건 결합 방식 ('and' 또는 'or')
+ */
+ protected static function applyFulltextPredicate(
+ \Illuminate\Database\Eloquent\Builder $query,
+ array $columns,
+ string $keyword,
+ string $boolean = 'and'
+ ): void {
+ $columns = array_values($columns);
+
+ if (! static::supportsFulltext()) {
+ // 전문검색을 제공하지 않는 DBMS 로 설치된 사이트에서는 부분일치가 정상 경로다.
+ // 연산자 선택과 와일드카드 escape 는 코어 해석기가 단독으로 수행한다 —
+ // 여기서 다시 조립하면 DBMS 가 늘 때마다 고쳐야 할 곳이 둘이 된다.
+ KeywordSearch::applyLikeMatch($query, $columns, $keyword, $boolean);
+
+ return;
}
+
+ $ftKeyword = static::sanitizeBooleanModeKeyword($keyword);
+
+ if ($ftKeyword === '') {
+ // 정제 결과 없음(연산자만 입력) → 빈 결과. 빌더가 바인딩까지 처리하도록
+ // 빈 whereIn 을 쓴다 (raw '1 = 0' 은 쓰지 않는다).
+ $method = $boolean === 'or' ? 'orWhereIn' : 'whereIn';
+ $query->$method($query->getModel()->getQualifiedKeyName(), []);
+
+ return;
+ }
+
+ $match = 'MATCH(`'.implode('`, `', $columns).'`)';
+ $method = $boolean === 'or' ? 'orWhereRaw' : 'whereRaw';
+ $query->$method($match.' AGAINST(? IN BOOLEAN MODE)', [$ftKeyword]);
+ }
+
+ /**
+ * 여러 컬럼 중 하나라도 매칭하면 되는 FULLTEXT 조건을 추가합니다.
+ *
+ * 컬럼마다 별도의 `MATCH(col)` 를 만들어 OR 로 묶습니다. 컬럼별 단일 FULLTEXT 인덱스만
+ * 있는 테이블(대부분의 경우)에서 쓰는 형태이며, 복합 인덱스가 없어도 동작합니다.
+ *
+ * 복합 인덱스가 있어 `MATCH(a, b)` 한 번으로 끝내야 하는 테이블은
+ * {@see self::whereFulltext()} 에 배열을 넘기세요.
+ *
+ * @param \Illuminate\Database\Eloquent\Builder $query Eloquent 쿼리 빌더
+ * @param array $columns 검색 대상 컬럼명 목록
+ * @param string $keyword 검색어 (원문 — 정제는 내부에서 수행)
+ * @param string $boolean 바깥 쿼리와의 결합 방식 ('and' 또는 'or')
+ */
+ public static function whereFulltextAny(
+ \Illuminate\Database\Eloquent\Builder $query,
+ array $columns,
+ string $keyword,
+ string $boolean = 'and'
+ ): void {
+ // 활성 엔진 해석을 거친다 ({@see self::whereFulltext()} 와 동일한 이유).
+ KeywordSearch::applyAny($query, $columns, $keyword, $boolean);
}
/**
@@ -329,39 +488,37 @@ class DatabaseFulltextEngine extends Engine
* @param Builder $builder Scout 빌더
* @param int|null $perPage 페이지당 결과 수
* @param int|null $page 페이지 번호
- * @return array{query: \Illuminate\Database\Eloquent\Builder, total: int}
+ * @param bool $withTotal 총 건수를 계산할지 여부 (쓰지 않는 경로에서는 false)
+ * @param bool $keysOnly 키 컬럼과 정렬용 스코어만 조회할지 여부
+ * @return array{query: \Illuminate\Database\Eloquent\Builder|null, total: int|null, total_relation: TotalRelation|null, result_cap: int|null}
*/
- protected function performSearch(Builder $builder, ?int $perPage = null, ?int $page = null): array
- {
+ protected function performSearch(
+ Builder $builder,
+ ?int $perPage = null,
+ ?int $page = null,
+ bool $withTotal = true,
+ bool $keysOnly = false
+ ): array {
$model = $builder->model;
$keyword = $builder->query;
// 빈 검색어인 경우 빈 결과 반환
if (empty(trim($keyword))) {
- return [
- 'query' => null,
- 'total' => 0,
- ];
+ return self::emptyResult();
}
$query = $model->newQuery();
// FulltextSearchable 인터페이스 구현 확인
if (! ($model instanceof FulltextSearchable)) {
- return [
- 'query' => null,
- 'total' => 0,
- ];
+ return self::emptyResult();
}
$columns = $model->searchableColumns();
$weights = $model->searchableWeights();
if (empty($columns)) {
- return [
- 'query' => null,
- 'total' => 0,
- ];
+ return self::emptyResult();
}
$useFulltext = static::supportsFulltext();
@@ -375,10 +532,7 @@ class DatabaseFulltextEngine extends Engine
$ftKeyword = static::sanitizeBooleanModeKeyword($keyword);
if ($ftKeyword === '') {
// 연산자만 입력 → 500 대신 빈 결과 (빈 검색어와 동일 반환 형태)
- return [
- 'query' => null,
- 'total' => 0,
- ];
+ return self::emptyResult();
}
// MATCH...AGAINST WHERE 조건 생성 (MySQL, MariaDB)
@@ -399,7 +553,7 @@ class DatabaseFulltextEngine extends Engine
$scoreBindings[] = $ftKeyword;
}
$scoreRaw = '('.implode(' + ', $scoreExpressions).') as _ft_score';
- $query->selectRaw($qualifiedTable.'.*, '.$scoreRaw, $scoreBindings);
+ $this->applySelect($query, $model, $qualifiedTable, $scoreRaw, $scoreBindings, $keysOnly);
} else {
// LIKE fallback (PostgreSQL, SQLite 등)
$query->where(function ($q) use ($columns, $keyword) {
@@ -409,7 +563,7 @@ class DatabaseFulltextEngine extends Engine
});
// 스코어 고정 0 (관련성 순위 불가)
- $query->selectRaw($qualifiedTable.'.*, 0 as _ft_score');
+ $this->applySelect($query, $model, $qualifiedTable, '0 as _ft_score', [], $keysOnly);
}
// Scout Builder 콜백 적용 (추가 where 조건 등)
@@ -459,8 +613,16 @@ class DatabaseFulltextEngine extends Engine
$query->orderByDesc('_ft_score');
}
- // 전체 건수 계산 (페이지네이션 전)
- $total = $query->toBase()->getCountForPagination();
+ // 전체 건수 계산 (페이지네이션 전).
+ // 총 건수를 쓰지 않는 경로에서는 아예 세지 않는다 — 대용량 매칭에서 COUNT 한 번이
+ // 조회 본체보다 비쌀 수 있다.
+ $resultCap = PaginationLimits::resultCap('search');
+ $total = null;
+ $relation = null;
+
+ if ($withTotal) {
+ [$total, $relation] = BoundedPaginator::countWithCap($query, $resultCap);
+ }
// 페이지네이션 적용
if ($perPage !== null) {
@@ -468,11 +630,66 @@ class DatabaseFulltextEngine extends Engine
$query->limit($perPage)->offset($offset);
} elseif ($builder->limit !== null) {
$query->limit($builder->limit);
+ } elseif ($resultCap !== null) {
+ // perPage 도 limit 도 없으면 LIMIT 이 아예 붙지 않아 매칭 전량을 PHP 로 끌어온다.
+ // 상한을 걸어 한 요청이 읽는 행 수에 천장을 둔다.
+ $query->limit($resultCap);
}
return [
'query' => $query,
'total' => $total,
+ 'total_relation' => $relation,
+ 'result_cap' => $resultCap,
+ ];
+ }
+
+ /**
+ * 조회 컬럼을 적용합니다.
+ *
+ * 키만 필요한 경로에서는 키 컬럼과 정렬용 스코어로 좁힙니다. 스코어는 `ORDER BY` 가
+ * 참조하므로 좁힐 때도 함께 남겨야 합니다.
+ *
+ * 검색 쿼리의 SELECT 를 재작성하는 유일한 지점입니다. `mapIds()`/`map()`/`lazyMap()` 은
+ * 넘겨받은 쿼리의 SELECT·ORDER BY 를 바꾸지 않습니다 — 소비자가 `->query()` 로 얹은
+ * 별칭에도 정렬이 걸릴 수 있어, 재작성은 알려진 별칭 하나만 보존해도 안전하지 않습니다.
+ *
+ * @param \Illuminate\Database\Eloquent\Builder $query 대상 쿼리
+ * @param Model $model 기준 모델
+ * @param string $qualifiedTable 프리픽스 포함 테이블명
+ * @param string $scoreRaw 스코어 SELECT 표현식 (`... as _ft_score`)
+ * @param array $scoreBindings 스코어 표현식 바인딩
+ * @param bool $keysOnly 키 컬럼만 조회할지 여부
+ */
+ protected function applySelect(
+ $query,
+ Model $model,
+ string $qualifiedTable,
+ string $scoreRaw,
+ array $scoreBindings,
+ bool $keysOnly
+ ): void {
+ if ($keysOnly) {
+ $query->select($model->getQualifiedKeyName())->selectRaw($scoreRaw, $scoreBindings);
+
+ return;
+ }
+
+ $query->selectRaw($qualifiedTable.'.*, '.$scoreRaw, $scoreBindings);
+ }
+
+ /**
+ * 검색이 성립하지 않을 때의 빈 결과 형태를 반환합니다.
+ *
+ * @return array{query: null, total: int, total_relation: TotalRelation, result_cap: null}
+ */
+ protected static function emptyResult(): array
+ {
+ return [
+ 'query' => null,
+ 'total' => 0,
+ 'total_relation' => TotalRelation::Exact,
+ 'result_cap' => null,
];
}
}
diff --git a/app/Search/Engines/Maintenance/FulltextIndexMaintainer.php b/app/Search/Engines/Maintenance/FulltextIndexMaintainer.php
new file mode 100644
index 00000000..9624ade9
--- /dev/null
+++ b/app/Search/Engines/Maintenance/FulltextIndexMaintainer.php
@@ -0,0 +1,127 @@
+isAvailable()
+ ? null
+ : __('search.index.fulltext.unsupported_driver');
+ }
+
+ /**
+ * {@inheritDoc}
+ *
+ * 지원 필터: `table`(테이블명, 프리픽스 생략 가능) · `index`(인덱스명) · `samples`(표본 행 수)
+ */
+ public function inspect(array $filters = []): array
+ {
+ $sampleSize = (int) ($filters['samples'] ?? FulltextIndexInspector::DEFAULT_SAMPLE_SIZE);
+
+ $results = $this->inspector->inspectAll(
+ table: isset($filters['table']) ? (string) $filters['table'] : null,
+ index: isset($filters['index']) ? (string) $filters['index'] : null,
+ sampleSize: max(1, $sampleSize),
+ );
+
+ return array_map(fn (array $result) => $this->toHealth($result), $results);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public function rebuild(SearchIndexHealth $health): void
+ {
+ $context = $health->context;
+
+ $this->inspector->rebuild(new FulltextIndexDefinition(
+ table: (string) ($context['table'] ?? ''),
+ name: (string) ($context['name'] ?? ''),
+ columns: (array) ($context['columns'] ?? []),
+ parser: isset($context['parser']) ? (string) $context['parser'] : null,
+ ));
+ }
+
+ /**
+ * 점검기 결과를 엔진 중립 판정 DTO 로 옮깁니다.
+ *
+ * @param array{definition: FulltextIndexDefinition, status: SearchIndexStatus, probed: int, found: int, reason: ?string} $result 점검기 결과
+ * @return SearchIndexHealth
+ */
+ private function toHealth(array $result): SearchIndexHealth
+ {
+ $definition = $result['definition'];
+ $status = $result['status'];
+
+ $measurement = $status === SearchIndexStatus::Skipped
+ ? (string) $result['reason']
+ : __('search.index.fulltext.self_match', ['found' => $result['found'], 'probed' => $result['probed']]);
+
+ return new SearchIndexHealth(
+ driver: self::DRIVER,
+ identifier: $definition->label(),
+ status: $status,
+ measurement: $measurement,
+ details: [
+ 'table' => $definition->table,
+ 'index' => $definition->name,
+ 'columns' => $definition->columns,
+ 'parser' => $definition->parser,
+ 'probed' => $result['probed'],
+ 'found' => $result['found'],
+ ],
+ context: [
+ 'table' => $definition->table,
+ 'name' => $definition->name,
+ 'columns' => $definition->columns,
+ 'parser' => $definition->parser,
+ ],
+ );
+ }
+}
diff --git a/app/Search/FulltextIndexInspector.php b/app/Search/FulltextIndexInspector.php
new file mode 100644
index 00000000..b62a48ad
--- /dev/null
+++ b/app/Search/FulltextIndexInspector.php
@@ -0,0 +1,367 @@
+
+ */
+ public function discover(?string $table = null, ?string $index = null): array
+ {
+ if (! DatabaseFulltextEngine::supportsFulltext()) {
+ return [];
+ }
+
+ $rows = DB::select(
+ 'SELECT TABLE_NAME AS table_name, INDEX_NAME AS index_name,
+ GROUP_CONCAT(COLUMN_NAME ORDER BY SEQ_IN_INDEX) AS columns
+ FROM INFORMATION_SCHEMA.STATISTICS
+ WHERE TABLE_SCHEMA = DATABASE() AND INDEX_TYPE = ?
+ GROUP BY TABLE_NAME, INDEX_NAME
+ ORDER BY TABLE_NAME, INDEX_NAME',
+ ['FULLTEXT']
+ );
+
+ $prefix = DB::getTablePrefix();
+ $wanted = $table === null ? null : [$table, $prefix.$table];
+
+ $definitions = [];
+ foreach ($rows as $row) {
+ if ($wanted !== null && ! in_array($row->table_name, $wanted, true)) {
+ continue;
+ }
+ if ($index !== null && $row->index_name !== $index) {
+ continue;
+ }
+
+ $definitions[] = new FulltextIndexDefinition(
+ table: $row->table_name,
+ name: $row->index_name,
+ columns: explode(',', (string) $row->columns),
+ parser: $this->resolveParser($row->table_name, $row->index_name),
+ );
+ }
+
+ return $definitions;
+ }
+
+ /**
+ * 인덱스 하나의 건강도를 판정합니다.
+ *
+ * 엔진 중립 DTO 로의 변환은 호출자(`FulltextIndexMaintainer`)가 합니다 — 이 클래스는
+ * FULLTEXT 고유의 판정만 담당하고 표현 형식을 알지 않습니다.
+ *
+ * @param FulltextIndexDefinition $definition 인덱스 정의
+ * @param int $sampleSize 표본 행 수
+ * @return array{definition: FulltextIndexDefinition, status: SearchIndexStatus, probed: int, found: int, reason: string|null}
+ */
+ public function inspect(FulltextIndexDefinition $definition, int $sampleSize = self::DEFAULT_SAMPLE_SIZE): array
+ {
+ $key = $this->resolvePrimaryKey($definition->table);
+
+ if ($key === null) {
+ return $this->skipped($definition, __('search.index.fulltext.skip.no_single_pk'));
+ }
+
+ $samples = $this->sampleRows($definition, $key, $sampleSize);
+
+ if ($samples === []) {
+ return $this->skipped($definition, __('search.index.fulltext.skip.no_rows'));
+ }
+
+ $probed = 0;
+ $found = 0;
+
+ foreach ($samples as $sample) {
+ $tokens = $this->buildTokens((string) $sample->body);
+
+ if ($tokens === []) {
+ continue;
+ }
+
+ $probed++;
+
+ if ($this->rowFindsItself($definition, $key, $sample->pk, $tokens)) {
+ $found++;
+ }
+ }
+
+ if ($probed === 0) {
+ return $this->skipped($definition, __('search.index.fulltext.skip.no_tokens'));
+ }
+
+ return [
+ 'definition' => $definition,
+ 'status' => match (true) {
+ $found === 0 => SearchIndexStatus::Stale,
+ $found < $probed => SearchIndexStatus::Degraded,
+ default => SearchIndexStatus::Healthy,
+ },
+ 'probed' => $probed,
+ 'found' => $found,
+ 'reason' => null,
+ ];
+ }
+
+ /**
+ * 전체(또는 필터된) 인덱스의 건강도를 판정합니다.
+ *
+ * @param string|null $table 테이블명 필터
+ * @param string|null $index 인덱스명 필터
+ * @param int $sampleSize 표본 행 수
+ * @return array
+ */
+ public function inspectAll(?string $table = null, ?string $index = null, int $sampleSize = self::DEFAULT_SAMPLE_SIZE): array
+ {
+ return array_map(
+ fn (FulltextIndexDefinition $definition) => $this->inspect($definition, $sampleSize),
+ $this->discover($table, $index)
+ );
+ }
+
+ /**
+ * 판정 불가 결과를 만듭니다.
+ *
+ * @param FulltextIndexDefinition $definition 인덱스 정의
+ * @param string $reason 사유
+ * @return array{definition: FulltextIndexDefinition, status: SearchIndexStatus, probed: int, found: int, reason: string}
+ */
+ private function skipped(FulltextIndexDefinition $definition, string $reason): array
+ {
+ return [
+ 'definition' => $definition,
+ 'status' => SearchIndexStatus::Skipped,
+ 'probed' => 0,
+ 'found' => 0,
+ 'reason' => $reason,
+ ];
+ }
+
+ /**
+ * 인덱스를 같은 정의로 재생성합니다.
+ *
+ * 컬럼 구성과 파서를 그대로 유지하므로 검색 동작이 달라지지 않습니다.
+ * 재생성 중에는 대상 테이블이 잠기므로 대용량 테이블에서는 시간이 걸립니다.
+ *
+ * @param FulltextIndexDefinition $definition 인덱스 정의
+ * @return void
+ *
+ * @throws Throwable 재생성 실패 시 (드롭까지만 되고 끝나지 않도록 예외를 그대로 전파)
+ */
+ public function rebuild(FulltextIndexDefinition $definition): void
+ {
+ $table = $definition->quotedTable();
+ $name = $definition->name;
+
+ DB::statement("ALTER TABLE {$table} DROP INDEX `{$name}`");
+
+ try {
+ DB::statement(
+ "ALTER TABLE {$table} ADD FULLTEXT INDEX `{$name}` ({$definition->quotedColumns()})"
+ .$definition->parserClause()
+ );
+ } catch (Throwable $e) {
+ // 드롭만 되고 끝나면 검색이 아예 죽는다 — 원 정의로 되돌린 뒤 예외를 전파한다
+ $this->restoreQuietly($definition);
+
+ throw $e;
+ }
+ }
+
+ /**
+ * 인덱스의 파서를 조회합니다.
+ *
+ * `INFORMATION_SCHEMA` 는 파서를 노출하지 않으므로 `SHOW CREATE TABLE` 정의에서 읽습니다.
+ *
+ * @param string $table 테이블명 (프리픽스 포함)
+ * @param string $index 인덱스명
+ * @return string|null 파서명 (없으면 null)
+ */
+ private function resolveParser(string $table, string $index): ?string
+ {
+ try {
+ $create = DB::selectOne('SHOW CREATE TABLE `'.$table.'`');
+ } catch (Throwable) {
+ return null;
+ }
+
+ $sql = (array) $create;
+ $ddl = (string) (($sql['Create Table'] ?? $sql['Create View'] ?? ''));
+
+ $pattern = '/FULLTEXT\s+KEY\s+`'.preg_quote($index, '/').'`[^\n]*?WITH\s+PARSER\s+`?(\w+)`?/i';
+
+ return preg_match($pattern, $ddl, $m) === 1 ? $m[1] : null;
+ }
+
+ /**
+ * 테이블의 단일 컬럼 기본키를 조회합니다.
+ *
+ * @param string $table 테이블명 (프리픽스 포함)
+ * @return string|null 기본키 컬럼명 (복합키·부재 시 null)
+ */
+ private function resolvePrimaryKey(string $table): ?string
+ {
+ $rows = DB::select(
+ 'SELECT COLUMN_NAME AS column_name FROM INFORMATION_SCHEMA.STATISTICS
+ WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND INDEX_NAME = ?
+ ORDER BY SEQ_IN_INDEX',
+ [$table, 'PRIMARY']
+ );
+
+ return count($rows) === 1 ? (string) $rows[0]->column_name : null;
+ }
+
+ /**
+ * 색인 컬럼에 내용이 있는 표본 행을 뽑습니다.
+ *
+ * @param FulltextIndexDefinition $definition 인덱스 정의
+ * @param string $key 기본키 컬럼명
+ * @param int $sampleSize 표본 행 수
+ * @return array `pk`, `body` 를 가진 행 배열
+ */
+ private function sampleRows(FulltextIndexDefinition $definition, string $key, int $sampleSize): array
+ {
+ $body = "CONCAT_WS(' ', {$definition->quotedColumns()})";
+
+ return DB::select(
+ "SELECT `{$key}` AS pk, {$body} AS body
+ FROM {$definition->quotedTable()}
+ WHERE {$body} <> '' AND {$body} IS NOT NULL
+ ORDER BY `{$key}` DESC
+ LIMIT ".max(1, $sampleSize)
+ );
+ }
+
+ /**
+ * 행 내용에서 검색 토큰 후보를 만듭니다.
+ *
+ * 비-라틴(한글·한자 등) 조각을 먼저 담습니다 — 기본 불용어 목록이 영어라
+ * 라틴 토큰보다 토크나이저 영향을 덜 받습니다.
+ *
+ * @param string $text 행 내용
+ * @return array 토큰 후보 목록
+ */
+ private function buildTokens(string $text): array
+ {
+ // 부울 모드 연산자(+ - > < ( ) ~ * " @)와 구분자를 제거한다
+ $normalized = preg_replace('/[^\p{L}\p{N}]+/u', ' ', $text) ?? '';
+ $pieces = array_values(array_filter(
+ explode(' ', $normalized),
+ fn (string $piece) => mb_strlen($piece) >= 2
+ ));
+
+ if ($pieces === []) {
+ return [];
+ }
+
+ // 길이 내림차순 — 짧은 조각일수록 불용어·잡음일 확률이 높다
+ usort($pieces, fn (string $a, string $b) => mb_strlen($b) <=> mb_strlen($a));
+
+ $nonLatin = [];
+ $latin = [];
+
+ foreach ($pieces as $piece) {
+ $token = mb_substr($piece, 0, self::MAX_TOKEN_LENGTH);
+
+ if (preg_match('/^[\x00-\x7F]+$/', $token) === 1) {
+ $latin[] = $token;
+ } else {
+ $nonLatin[] = $token;
+ }
+ }
+
+ return array_slice(array_values(array_unique([...$nonLatin, ...$latin])), 0, self::MAX_TOKENS_PER_ROW);
+ }
+
+ /**
+ * 한 행이 자기 토큰 중 하나로 자신을 찾을 수 있는지 확인합니다.
+ *
+ * @param FulltextIndexDefinition $definition 인덱스 정의
+ * @param string $key 기본키 컬럼명
+ * @param mixed $pk 행의 기본키 값
+ * @param array $tokens 토큰 후보
+ * @return bool 하나라도 찾으면 true
+ */
+ private function rowFindsItself(FulltextIndexDefinition $definition, string $key, mixed $pk, array $tokens): bool
+ {
+ foreach ($tokens as $token) {
+ $hit = DB::selectOne(
+ "SELECT COUNT(*) AS hits FROM {$definition->quotedTable()}
+ WHERE `{$key}` = ? AND MATCH({$definition->quotedColumns()}) AGAINST(? IN BOOLEAN MODE)",
+ [$pk, '"'.$token.'"']
+ );
+
+ if ((int) ($hit->hits ?? 0) > 0) {
+ return true;
+ }
+ }
+
+ return false;
+ }
+
+ /**
+ * 재생성 실패 시 원 정의로 되돌립니다 (실패해도 원 예외를 가리지 않도록 조용히 처리).
+ *
+ * @param FulltextIndexDefinition $definition 인덱스 정의
+ * @return void
+ */
+ private function restoreQuietly(FulltextIndexDefinition $definition): void
+ {
+ try {
+ DB::statement(
+ "ALTER TABLE {$definition->quotedTable()} ADD FULLTEXT INDEX `{$definition->name}` "
+ ."({$definition->quotedColumns()})".$definition->parserClause()
+ );
+ } catch (Throwable) {
+ // 되돌리기까지 실패하면 원 예외가 더 중요한 정보다
+ }
+ }
+}
diff --git a/app/Search/KeywordSearch.php b/app/Search/KeywordSearch.php
new file mode 100644
index 00000000..9d958ab9
--- /dev/null
+++ b/app/Search/KeywordSearch.php
@@ -0,0 +1,280 @@
+
+ */
+ private static array $warnedDrivers = [];
+
+ /**
+ * 쿼리에 키워드 술어를 붙입니다.
+ *
+ * 컬럼을 배열로 넘기면 **하나의 조건으로 함께 평가**해 달라는 뜻입니다. 엔진이 그 조합을
+ * 다룰 수 없는 경우(MySQL FULLTEXT 는 그 컬럼 조합의 복합 인덱스를 요구한다)에는
+ * {@see self::applyAny()} 로 컬럼별 OR 을 요청하세요.
+ *
+ * @param Builder $query 조건을 붙일 Eloquent 쿼리 빌더
+ * @param string|array $columns 검색 대상 컬럼명
+ * @param string $keyword 검색어 원문
+ * @param string $boolean 기존 조건과의 결합 방식 ('and' 또는 'or')
+ * @param string|null $limitContext 상한 해석에 쓸 목록 컨텍스트 이름 (예: 'search')
+ */
+ public static function apply(
+ Builder $query,
+ string|array $columns,
+ string $keyword,
+ string $boolean = 'and',
+ ?string $limitContext = null
+ ): void {
+ $columns = array_values((array) $columns);
+
+ if ($columns === []) {
+ return;
+ }
+
+ $provider = self::provider();
+
+ if ($provider !== null) {
+ $provider->applyKeywordPredicate(
+ $query,
+ $columns,
+ $keyword,
+ $boolean,
+ self::context($limitContext)
+ );
+
+ return;
+ }
+
+ self::applyLikeMatch($query, $columns, $keyword, $boolean);
+ }
+
+ /**
+ * 엔진에게 넘길 술어 생성 조건을 만듭니다.
+ *
+ * 키 집합 상한은 목록 총 건수 상한과 같은 값을 쓴다 — 두 상한이 갈라지면 "엔진이
+ * 돌려준 건수" 와 "화면이 보고하는 총 건수" 가 서로 다른 근거를 갖게 된다.
+ *
+ * @param string|null $limitContext 상한 해석에 쓸 목록 컨텍스트 이름
+ * @return KeywordSearchContext 술어 생성 조건
+ */
+ private static function context(?string $limitContext): KeywordSearchContext
+ {
+ return new KeywordSearchContext(
+ keyCap: PaginationLimits::resultCap($limitContext),
+ );
+ }
+
+ /**
+ * 컬럼별로 따로 평가해 OR 로 묶은 키워드 술어를 붙입니다.
+ *
+ * 컬럼마다 개별 인덱스만 있는 테이블에서 씁니다. 바깥은 하나의 그룹으로 감싸므로
+ * 호출자의 기존 조건과 섞이지 않습니다.
+ *
+ * @param Builder $query 조건을 붙일 Eloquent 쿼리 빌더
+ * @param array $columns 검색 대상 컬럼명
+ * @param string $keyword 검색어 원문
+ * @param string $boolean 기존 조건과의 결합 방식 ('and' 또는 'or')
+ * @param string|null $limitContext 상한 해석에 쓸 목록 컨텍스트 이름 (예: 'search')
+ */
+ public static function applyAny(
+ Builder $query,
+ array $columns,
+ string $keyword,
+ string $boolean = 'and',
+ ?string $limitContext = null
+ ): void {
+ $columns = array_values($columns);
+
+ if ($columns === []) {
+ return;
+ }
+
+ $method = $boolean === 'or' ? 'orWhere' : 'where';
+
+ $query->$method(function ($group) use ($columns, $keyword, $limitContext) {
+ foreach ($columns as $index => $column) {
+ self::apply($group, $column, $keyword, $index === 0 ? 'and' : 'or', $limitContext);
+ }
+ });
+ }
+
+ /**
+ * 활성 엔진이 키워드 술어를 제공하는지 확인하고 그 엔진을 반환합니다.
+ *
+ * 제공하지 않으면 null 을 돌려주고, 그 사실을 드라이버당 한 번 기록합니다.
+ * 기록하지 않으면 "검색이 느리고 관련도가 이상하다" 는 증상만 남고 원인을 찾을 단서가
+ * 없어진다 — 폴백은 정상 동작처럼 보이기 때문이다.
+ *
+ * @return KeywordPredicateProvider|null 술어를 제공하는 엔진 (없으면 null)
+ */
+ private static function provider(): ?KeywordPredicateProvider
+ {
+ try {
+ $engine = app(EngineManager::class)->engine();
+ } catch (Throwable) {
+ // 부팅 초기 등 엔진 해석이 불가한 상황 — 경고 없이 폴백한다.
+ return null;
+ }
+
+ if ($engine instanceof KeywordPredicateProvider) {
+ return $engine;
+ }
+
+ self::warnFallbackOnce();
+
+ return null;
+ }
+
+ /**
+ * 폴백 사용 사실을 드라이버당 한 번 기록합니다.
+ */
+ private static function warnFallbackOnce(): void
+ {
+ $driver = (string) config('scout.driver', 'mysql-fulltext');
+
+ if (isset(self::$warnedDrivers[$driver])) {
+ return;
+ }
+
+ self::$warnedDrivers[$driver] = true;
+
+ Log::warning('활성 검색 엔진이 키워드 술어를 제공하지 않아 LIKE 로 검색합니다. 관련도 정렬이 적용되지 않고 전체 스캔이 발생합니다.', [
+ 'driver' => $driver,
+ 'contract' => KeywordPredicateProvider::class,
+ ]);
+ }
+
+ /**
+ * 부분일치(LIKE) 조건을 붙입니다.
+ *
+ * 이 경로는 "엔진이 없을 때의 임시방편" 이 아니다. 전문검색을 제공하지 않는 DBMS 로
+ * 설치된 사이트에서는 **이것이 정상 검색 경로**이므로 이식성을 갖춰야 한다.
+ *
+ * - 대소문자: PostgreSQL 의 `LIKE` 는 대소문자를 구분한다. MySQL 은 기본 collation 이
+ * 구분하지 않으므로, 드라이버별로 연산자를 갈라 **같은 검색어가 DBMS 에 따라 다른
+ * 결과를 내지 않도록** 한다.
+ * - 와일드카드: 검색어의 `%` `_` `\` 를 escape 해 이용자가 입력한 글자 그대로 찾는다.
+ * escape 하지 않으면 `50%` 검색이 `50` 으로 시작하는 모든 행을 반환한다.
+ *
+ * @param Builder $query 조건을 붙일 Eloquent 쿼리 빌더
+ * @param array $columns 검색 대상 컬럼명
+ * @param string $keyword 검색어 원문
+ * @param string $boolean 기존 조건과의 결합 방식
+ */
+ public static function applyLikeMatch(
+ Builder $query,
+ array $columns,
+ string $keyword,
+ string $boolean = 'and'
+ ): void {
+ $columns = array_values($columns);
+
+ if ($columns === []) {
+ return;
+ }
+
+ $pattern = '%'.self::escapeLikeWildcards($keyword).'%';
+ $operator = self::caseInsensitiveLikeOperator();
+ $method = $boolean === 'or' ? 'orWhere' : 'where';
+
+ $query->$method(function ($nested) use ($columns, $pattern, $operator) {
+ foreach ($columns as $index => $column) {
+ $nested->{$index === 0 ? 'where' : 'orWhere'}($column, $operator, $pattern);
+ }
+ });
+ }
+
+ /**
+ * 대소문자를 구분하지 않는 부분일치 연산자를 드라이버별로 반환합니다.
+ *
+ * 드라이버명을 코드에 적지 않는다 — 앞으로 어떤 DBMS 가 공식 지원될지 정해져 있지
+ * 않으므로, 코드에 박으면 DBMS 가 늘 때마다 코어를 고쳐야 한다. 표는 선언형 config
+ * (`core.search.like_operators`)에 있고, 확장은 필터 훅으로 조정한다.
+ *
+ * @return string 사용할 비교 연산자
+ */
+ private static function caseInsensitiveLikeOperator(): string
+ {
+ $default = (string) config('core.search.like_operator_default', 'like');
+
+ $operators = config('core.search.like_operators', []);
+ $operators = HookManager::applyFilters(self::LIKE_OPERATORS_FILTER, $operators);
+
+ if (! is_array($operators)) {
+ return $default;
+ }
+
+ try {
+ $driver = DB::getDriverName();
+ } catch (Throwable) {
+ return $default;
+ }
+
+ $operator = $operators[$driver] ?? $default;
+
+ return is_string($operator) && $operator !== '' ? $operator : $default;
+ }
+
+ /**
+ * `LIKE` 패턴에서 특수 의미를 갖는 문자를 escape 합니다.
+ *
+ * @param string $keyword 검색어 원문
+ * @return string escape 된 검색어
+ */
+ public static function escapeLikeWildcards(string $keyword): string
+ {
+ return str_replace(['\\', '%', '_'], ['\\\\', '\\%', '\\_'], $keyword);
+ }
+
+ /**
+ * 폴백 경고 기록을 초기화합니다 (테스트 전용).
+ */
+ public static function forgetFallbackWarnings(): void
+ {
+ self::$warnedDrivers = [];
+ }
+}
diff --git a/app/Search/SearchCategoryPayload.php b/app/Search/SearchCategoryPayload.php
new file mode 100644
index 00000000..2a72fc16
--- /dev/null
+++ b/app/Search/SearchCategoryPayload.php
@@ -0,0 +1,100 @@
+ $items 화면에 실을 항목 (가공 완료 상태)
+ * @param array $extra 도메인 고유 필드 (available_boards 등)
+ * @return array 카테고리 페이로드
+ */
+ public static function fromBounded(BoundedPage $page, array $items, array $extra = []): array
+ {
+ return array_merge([
+ 'total' => $page->total(),
+ 'total_relation' => $page->totalRelation()->value,
+ 'total_is_exact' => $page->totalRelation()->isExact(),
+ 'result_cap' => $page->resultCap(),
+ 'last_page' => $page->lastPage(),
+ 'has_more_pages' => $page->hasMorePages(),
+ // offset 응답에는 커서가 없다. 키 자체는 남겨 화면이 분기 없이 읽게 한다.
+ 'next_cursor' => null,
+ 'prev_cursor' => null,
+ 'items' => $items,
+ ], $extra);
+ }
+
+ /**
+ * 커서(키셋) 방식 결과로 페이로드를 만듭니다.
+ *
+ * 커서 응답에는 총 건수가 없으므로 건수는 별도 집계로 받습니다. 마지막 페이지 번호는
+ * 커서 방식에 존재하지 않는 개념이라 언제나 null 이며, 화면은 그때 마지막 페이지
+ * 점프만 감추고 "다음" 이동은 그대로 유지합니다.
+ *
+ * @param CursorPaginator $page 커서 페이지 결과
+ * @param BoundedCount|null $count 총 건수 집계 (배지를 그리지 않으면 null)
+ * @param array $items 화면에 실을 항목 (가공 완료 상태)
+ * @param array $extra 도메인 고유 필드
+ * @return array 카테고리 페이로드
+ */
+ public static function fromCursor(
+ CursorPaginator $page,
+ ?BoundedCount $count,
+ array $items,
+ array $extra = []
+ ): array {
+ $relation = $count?->totalRelation() ?? TotalRelation::AtLeast;
+
+ return array_merge([
+ 'total' => $count?->total() ?? count($items),
+ 'total_relation' => $relation->value,
+ 'total_is_exact' => $count !== null && $relation->isExact(),
+ 'result_cap' => $count?->resultCap(),
+ // 커서 방식에는 마지막 페이지 번호가 없다 (총 건수를 알아도 계산하지 않는다).
+ 'last_page' => null,
+ 'has_more_pages' => $page->hasMorePages(),
+ 'next_cursor' => KeysetPaginator::nextCursor($page),
+ 'prev_cursor' => KeysetPaginator::previousCursor($page),
+ 'items' => $items,
+ ], $extra);
+ }
+
+ /**
+ * 목록 없이 건수만 필요한 자리(비활성 탭 배지)의 페이로드를 만듭니다.
+ *
+ * @param BoundedCount $count 총 건수 집계
+ * @param array
+ 
@@ -316,7 +316,7 @@ HookManager::doAction('sirsoft-ecommerce.order.after_confirm', $order);
| 가상 보호 행 | 코어/번들 확장에 내장된 한국어/영어는 별도 설치 없이 항상 활성/보호 상태로 노출 (수정/제거 차단) |
| 보안 | 언어 번역 외의 PHP 실행 코드 포함 시 설치 차단 |
-공식 일본어(ja) 번들 14종(코어 + 주요 모듈/플러그인/템플릿) 이 즉시 사용 가능하며, 인스톨러 4단계에서 모듈/플러그인/템플릿 선택과 종속된 언어팩 카드가 자동 연동되어 함께 설치할 수 있습니다.
+공식 일본어(ja) 번들 16종(코어 + 주요 모듈/플러그인/템플릿) 이 즉시 사용 가능하며, 인스톨러 4단계에서 모듈/플러그인/템플릿 선택과 종속된 언어팩 카드가 자동 연동되어 함께 설치할 수 있습니다.
> 상세: [docs/extension/language-packs.md](docs/extension/language-packs.md)
@@ -390,7 +390,9 @@ cp .env.example .env
| **sirsoft-pay_kginicis** | KG이니시스 결제 연동 |
| **sirsoft-pay_nicepayments** | 나이스페이먼츠 결제 연동 (통합결제창) |
| **sirsoft-pay_nhnkcp** | NHN KCP 결제 연동 (Standard Pay) |
+| **sirsoft-tosspayments** | 토스페이먼츠 결제 연동 |
| **sirsoft-verification_kginicis** | KG이니시스 본인인증 |
+| **sirsoft-verification_nhnkcp** | NHN KCP 휴대폰 본인확인 |
| **sirsoft-daum_postcode** | 다음 우편번호 검색 |
| **sirsoft-marketing** | 마케팅 도구 |
| **sirsoft-ckeditor5** | CKEditor 5 에디터 |
@@ -420,7 +422,9 @@ cp .env.example .env
| **g7-plugin-sirsoft-pay_kginicis-ja** | KG이니시스 결제 플러그인 일본어 |
| **g7-plugin-sirsoft-pay_nicepayments-ja** | 나이스페이먼츠 결제 플러그인 일본어 |
| **g7-plugin-sirsoft-pay_nhnkcp-ja** | NHN KCP 결제 플러그인 일본어 |
+| **g7-plugin-sirsoft-tosspayments-ja** | 토스페이먼츠 플러그인 일본어 |
| **g7-plugin-sirsoft-verification_kginicis-ja** | KG이니시스 본인인증 플러그인 일본어 |
+| **g7-plugin-sirsoft-verification_nhnkcp-ja** | NHN KCP 휴대폰 본인확인 플러그인 일본어 |
| **g7-template-sirsoft-admin_basic-ja** | 관리자 기본 템플릿 일본어 |
| **g7-template-sirsoft-basic-ja** | 사용자 기본 템플릿 일본어 |
diff --git a/app/ActivityLog/Traits/ResolvesActivityLogType.php b/app/ActivityLog/Traits/ResolvesActivityLogType.php
index d0268296..e977b0e0 100644
--- a/app/ActivityLog/Traits/ResolvesActivityLogType.php
+++ b/app/ActivityLog/Traits/ResolvesActivityLogType.php
@@ -44,8 +44,8 @@ trait ResolvesActivityLogType
* properties.extension_origin 에 자동 주입합니다 (loggable 미지정 케이스의
* action 라벨 namespace fallback 용).
*
- * @param string $action 액션명 (예: 'user.create')
- * @param array $context Monolog context 배열
+ * @param string $action 액션명 (예: 'user.create')
+ * @param array $context Monolog context 배열
*/
protected function logActivity(string $action, array $context): void
{
@@ -58,9 +58,13 @@ trait ResolvesActivityLogType
$context['properties'] = $properties;
}
+ // 활동 로그는 부수 기록이다 — 실패해도 그것을 유발한 요청(결제 콜백 등)까지
+ // 죽여서는 안 된다. 채널 해석 실패는 Exception 이 아니라 Error 로 오므로
+ // (\Log::channel() 이 null 을 반환하면 "->info() on null" = \Error)
+ // Throwable 로 받아야 가드가 실제로 동작한다.
try {
Log::channel('activity')->info($action, $context);
- } catch (\Exception $e) {
+ } catch (\Throwable $e) {
Log::error('Failed to record activity log', [
'action' => $action,
'error' => $e->getMessage(),
diff --git a/app/Benchmark/Axes/BatchAxisRunner.php b/app/Benchmark/Axes/BatchAxisRunner.php
new file mode 100644
index 00000000..7d50b0fe
--- /dev/null
+++ b/app/Benchmark/Axes/BatchAxisRunner.php
@@ -0,0 +1,141 @@
+ null;
+
+ if ($profile->mutates() && ! $options->allowWrite) {
+ return BenchmarkResult::skipped($profile, '데이터를 변경하는 배치입니다. --allow-write 를 붙여 실행하세요.');
+ }
+
+ $command = (string) $profile->option('command');
+ $arguments = (array) $profile->option('arguments', []);
+
+ if (! array_key_exists($command, Artisan::all())) {
+ return BenchmarkResult::skipped($profile, "등록되지 않은 커맨드: {$command} (해당 확장이 설치되어 있는지 확인)");
+ }
+
+ $notify("배치 실행: {$command}");
+
+ // 피크 메모리는 프로세스 단위 누적값이라 감소하지 않는다. 실행 전 값을 함께
+ // 기록해야 "이 배치가 피크를 밀어올렸는지"를 판정할 수 있다.
+ $peakBefore = memory_get_peak_usage(true);
+ $usageBefore = memory_get_usage(true);
+ $buffer = new BufferedOutput;
+
+ $start = microtime(true);
+
+ try {
+ $collected = $this->collector->collect(
+ static fn () => Artisan::call($command, $arguments, $buffer)
+ );
+ $exitCode = (int) $collected['value'];
+ $queries = $collected['queries'];
+ } catch (\Throwable $e) {
+ return BenchmarkResult::skipped($profile, '계측 실패: '.$e->getMessage());
+ }
+
+ $elapsedMs = (microtime(true) - $start) * 1000;
+ $peakAfter = memory_get_peak_usage(true);
+ $usageAfter = memory_get_usage(true);
+ $summary = $this->collector->summarize($queries);
+
+ $notes = [
+ sprintf('실행 전 피크 %s → 실행 후 피크 %s', $this->formatBytes($peakBefore), $this->formatBytes($peakAfter)),
+ ];
+
+ if ($peakAfter <= $peakBefore) {
+ $notes[] = '이 배치가 프로세스 피크를 밀어올리지 않았습니다 (실행 전 피크가 이미 더 높음).';
+ }
+
+ if ($exitCode !== 0) {
+ $notes[] = "커맨드가 실패 종료했습니다 (exit={$exitCode}) — 시간·메모리는 실패 지점까지의 값입니다.";
+ }
+
+ $output = trim($buffer->fetch());
+
+ if ($output !== '') {
+ $notes[] = '커맨드 출력: '.$output;
+ }
+
+ return new BenchmarkResult(
+ profile: $profile,
+ headers: ['커맨드', '종료코드', '소요(ms)', '피크 메모리', '메모리 증가', '쿼리(건)'],
+ rows: [[
+ $command,
+ (string) $exitCode,
+ number_format($elapsedMs, 1),
+ $this->formatBytes($peakAfter),
+ $this->formatBytes(max(0, $usageAfter - $usageBefore)),
+ number_format($summary['count']),
+ ]],
+ metrics: [
+ 'command' => $command,
+ 'arguments' => $arguments,
+ 'exit_code' => $exitCode,
+ 'elapsed_ms' => round($elapsedMs, 2),
+ 'peak_memory_before_bytes' => $peakBefore,
+ 'peak_memory_after_bytes' => $peakAfter,
+ 'memory_delta_bytes' => $usageAfter - $usageBefore,
+ 'query_count' => $summary['count'],
+ 'db_ms' => $summary['db_ms'],
+ ],
+ notes: $notes,
+ );
+ }
+
+ /**
+ * 바이트를 사람이 읽는 단위로 바꿉니다.
+ *
+ * @param int $bytes 바이트
+ * @return string 포맷된 문자열
+ */
+ private function formatBytes(int $bytes): string
+ {
+ if ($bytes >= 1024 ** 3) {
+ return number_format($bytes / 1024 ** 3, 2).' GB';
+ }
+
+ if ($bytes >= 1024 ** 2) {
+ return number_format($bytes / 1024 ** 2, 1).' MB';
+ }
+
+ return number_format($bytes / 1024, 1).' KB';
+ }
+}
diff --git a/app/Benchmark/Axes/ListAxisRunner.php b/app/Benchmark/Axes/ListAxisRunner.php
new file mode 100644
index 00000000..ed701f49
--- /dev/null
+++ b/app/Benchmark/Axes/ListAxisRunner.php
@@ -0,0 +1,350 @@
+
+ */
+ private const FILTER_OPERATORS = ['=', '!=', '<>', '<', '<=', '>', '>=', 'like', 'in', 'not in'];
+
+ public function __construct(private readonly SyntheticSeeder $seeder) {}
+
+ /**
+ * {@inheritDoc}
+ */
+ public function axis(): BenchmarkAxis
+ {
+ return BenchmarkAxis::ListQuery;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public function run(BenchmarkProfile $profile, BenchmarkRunOptions $options, ?\Closure $onProgress = null): BenchmarkResult
+ {
+ $notify = $onProgress ?? static fn (string $message) => null;
+ $table = (string) $profile->option('table');
+
+ if (! Schema::hasTable($table)) {
+ return BenchmarkResult::skipped($profile, "테이블이 없습니다: {$table} (해당 확장이 설치되어 있는지 확인)");
+ }
+
+ if (($options->fresh || $options->seed > 0) && app()->environment('production')) {
+ return BenchmarkResult::skipped($profile, '운영 환경에서는 시딩/비움을 사용할 수 없습니다.');
+ }
+
+ $filterError = $this->validateFilters((array) $profile->option('filters', []));
+
+ if ($filterError !== null) {
+ return BenchmarkResult::skipped($profile, $filterError);
+ }
+
+ if ($options->fresh) {
+ $this->seeder->truncate($table);
+ $notify("비움: {$table}");
+ }
+
+ $columns = $this->existingColumns($table, (array) $profile->option('columns', ['*']));
+ $order = $this->existingOrder($table, (array) $profile->option('order', [['id', 'desc']]));
+
+ if ($options->seed > 0) {
+ $notify("시딩: {$table} ".number_format($options->seed).' 건');
+ $this->seeder->seed(
+ $table,
+ $options->seed,
+ (array) $profile->option('seed_overrides', []),
+ fn (int $inserted, int $total) => $notify(sprintf(' 시딩 %s / %s', number_format($inserted), number_format($total))),
+ // 정렬 기준 컬럼은 nullable 이어도 채운다 — 비워두면 합성 행이 전부 동률이 되어
+ // 계측이 정렬 인덱스가 아니라 tie-break 경로를 잰다.
+ array_column($order, 0),
+ );
+ }
+
+ $rows = [];
+ $notes = [];
+
+ foreach ($options->offsets as $offset) {
+ $allMs = $this->measure($profile, ['*'], $order, $offset, $options->runs);
+ $listMs = $this->measure($profile, $columns, $order, $offset, $options->runs);
+ $idOnlyMs = $this->measure($profile, ['id'], $order, $offset, $options->runs);
+
+ $rows[] = [
+ 'offset' => $offset,
+ 'all_ms' => $allMs,
+ 'list_ms' => $listMs,
+ 'id_only_ms' => $idOnlyMs,
+ 'ratio' => $idOnlyMs > 0 ? round($allMs / $idOnlyMs, 1) : null,
+ ];
+
+ if ($options->explain) {
+ $notes[] = "EXPLAIN @ OFFSET {$offset} — 목록 컬럼";
+
+ foreach ($this->explain($profile, $columns, $order, $offset) as $line) {
+ $notes[] = ' '.$line;
+ }
+
+ // 지연 조인의 inner 가 실제로 어떤 계획을 타는지가 인덱스 설계의 근거다
+ $notes[] = "EXPLAIN @ OFFSET {$offset} — ID 만 (지연 조인 inner)";
+
+ foreach ($this->explain($profile, ['id'], $order, $offset) as $line) {
+ $notes[] = ' '.$line;
+ }
+ }
+ }
+
+ return new BenchmarkResult(
+ profile: $profile,
+ headers: ['OFFSET', '전체 컬럼(ms)', '목록 컬럼(ms)', 'ID만(ms)', '전체÷ID'],
+ rows: array_map(fn (array $row) => [
+ number_format($row['offset']),
+ number_format($row['all_ms'], 1),
+ number_format($row['list_ms'], 1),
+ number_format($row['id_only_ms'], 1),
+ $row['ratio'] !== null ? $row['ratio'].'×' : '-',
+ ], $rows),
+ metrics: [
+ 'table' => $table,
+ 'columns' => $columns,
+ 'runs' => $options->runs,
+ 'offsets' => $rows,
+ ],
+ notes: $notes,
+ );
+ }
+
+ /**
+ * 스키마에 실제로 존재하는 컬럼만 남깁니다.
+ *
+ * `['*']` 는 "목록이 전 컬럼을 그대로 노출한다" 는 선언입니다. 응답 계약상 넓은 컬럼을
+ * 뺄 수 없는 목록(활동 로그의 changes, 알림 발송 이력의 body 등)이 여기 해당하며, 이
+ * 경우 계측의 비교 축은 select * vs select id 가 됩니다. 확장 버전에 따라 컬럼 구성이
+ * 달라도 계측이 죽지 않도록 스키마에 없는 컬럼은 걸러냅니다.
+ *
+ * @param string $table 테이블명
+ * @param array