Merge branch 'develop'

fix(docs): 신규 번들 확장이 README 인벤토리에서 누락되던 문제 수정 및 재발 방지
7.0.9 에 추가한 비즈뿌리오 플러그인과 그 일본어 언어팩이 README.md·README.ko.md 인벤토리 표 양쪽에서 빠진 채 릴리즈 직전까지 남아 있었다. manifest·CHANGELOG·버전 동기는 기존 하네스가 잡지만 README 인벤토리 표를 보는 검사는 없었다. 누락되어도 오류가 나지 않고 릴리즈 절차도 그대로 통과하므로, 공개 저장소 첫 화면에서 그 확장만 없는 상태로 배포된다. - 두 README 의 플러그인·언어팩 표에 누락 행 추가 - check-readme-bundled-inventory.cjs 신설 — 네 종류(_bundled 모듈/플러그인/ 템플릿/언어팩)를 두 README 와 대조. 학습용 샘플은 현행대로 제외 - Stop 훅에 등록해 세션 종료 전 자동 검출 - 검출력 확인: 수정 전 README 로 4건(플러그인 2 + 언어팩 2)을 red 로 잡는다
2026-08-24 17:55:37 +09:00 · 2026-08-24 17:49:33 +09:00 · 2026-08-24 17:27:59 +09:00 · 2026-08-24 17:07:41 +09:00 · 2026-08-24 17:03:42 +09:00 · 2026-08-24 16:18:52 +09:00
4156 changed files with 692156 additions and 33263 deletions
@@ -3,7 +3,7 @@ APP_ENV=production
 APP_KEY=
 APP_DEBUG=false
 APP_URL=http://localhost
-APP_VERSION=7.0.1
+APP_VERSION=7.0.9

 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

@@ -36,7 +38,9 @@ DB_WRITE_PASSWORD=
 # Database Table Prefix (optional)
 DB_PREFIX=g7_

-# Read Database Connection (Optional - falls back to WRITE if not set)
+# Read Database Connection (Optional)
+# 비워두면 각 항목이 대응하는 DB_WRITE_* 값으로 대체됩니다 (config/database.php).
+# Read 전용 DB(리플리카)를 쓸 때만 값을 채우세요.
 DB_READ_HOST=
 DB_READ_PORT=
 DB_READ_DATABASE=
@@ -96,6 +100,11 @@ AWS_SECRET_ACCESS_KEY=
 AWS_DEFAULT_REGION=us-east-1
 AWS_BUCKET=
 AWS_USE_PATH_STYLE_ENDPOINT=false
+# 아래 3키는 사용할 때만 주석을 해제하세요 — 값 없는 `KEY=` 는 "미설정" 이 아니라
+# 빈 문자열로 적용됩니다 (S3 공개 URL / S3 호환 엔드포인트 / 첨부 디스크 강제 지정)
+# AWS_URL=
+# AWS_ENDPOINT=
+# ATTACHMENT_DISK=

 VITE_APP_NAME="${APP_NAME}"

@@ -3,7 +3,7 @@ APP_ENV=testing
 APP_KEY=
 APP_DEBUG=false
 APP_URL=http://localhost
-APP_VERSION=7.0.1
+APP_VERSION=7.0.9

 APP_LOCALE=ko
 APP_FALLBACK_LOCALE=ko
@@ -34,7 +34,7 @@ DB_WRITE_PASSWORD=
 DB_PREFIX=g7_

 # Read Database Connection (테스트에서는 WRITE와 동일하게 설정)
-# database.php의 read 기본값이 WRITE와 다르므로, 명시 설정 필수
+# 비워두면 config/database.php 가 WRITE 값으로 대체하나, 테스트 DB 명시를 위해 값을 채워 둔다.
 DB_READ_HOST=127.0.0.1
 DB_READ_PORT=3306
 DB_READ_DATABASE=g7_testing
@@ -77,6 +77,11 @@ AWS_SECRET_ACCESS_KEY=
 AWS_DEFAULT_REGION=us-east-1
 AWS_BUCKET=
 AWS_USE_PATH_STYLE_ENDPOINT=false
+# 아래 3키는 사용할 때만 주석을 해제하세요 — 값 없는 `KEY=` 는 "미설정" 이 아니라
+# 빈 문자열로 적용됩니다 (S3 공개 URL / S3 호환 엔드포인트 / 첨부 디스크 강제 지정)
+# AWS_URL=
+# AWS_ENDPOINT=
+# ATTACHMENT_DISK=

 VITE_APP_NAME="${APP_NAME}"

@@ -0,0 +1,71 @@
+---
+name: 🐛 버그 제보
+about: 그누보드7(G7) 사용 중 발견한 버그를 제보합니다.
+title: "[Bug] "
+labels: bug
+assignees: ''
+---
+
+## 증상 요약
+
+<!-- 어떤 문제가 발생했는지 한두 문장으로 적어 주세요. -->
+
+## 재현 절차
+
+1.
+2.
+3.
+
+## 기대한 동작
+
+<!-- 원래 어떻게 동작해야 하는지 적어 주세요. -->
+
+## 실제 동작
+
+<!-- 실제로 어떻게 동작했는지 적어 주세요. 오류 메시지가 있다면 그대로 붙여 주세요. -->
+
+## 환경 정보 (필수)
+
+> 아래 정보가 없으면 원인 파악이 어렵습니다. 가능한 한 모두 채워 주세요.
+
+- **코어 버전**: <!-- 예: 7.0.2 / config/app.php 의 APP_VERSION 또는 관리자 > 정보 화면 -->
+- **업그레이드 이슈인 경우 — 업그레이드 전 버전 → 후 버전**: <!-- 예: 7.0.0-beta.7 → 7.0.2 -->
+- **PHP 버전**: <!-- 예: 8.2.x / php -v -->
+- **웹서버·실행 방식**: <!-- 예: Apache + mod_php / Nginx + PHP-FPM / 공유호스팅 -->
+- **DB**: <!-- 예: MySQL 8.0 / MariaDB 10.x -->
+- **OS**: <!-- 예: Ubuntu 24.04 / Windows 11 -->
+
+## 활성 확장 목록 (해당 시)
+
+<!--
+확장(모듈/플러그인/템플릿) 관련 문제이거나 업그레이드 문제라면 아래 명령 결과를 붙여 주세요.
+  php artisan module:list
+  php artisan plugin:list
+  php artisan template:list
+-->
+
+```text
+(여기에 붙여넣기)
+```
+
+## 커스텀 자산 여부 (해당 시)
+
+> 업그레이드·파일 삭제·권한 문제라면 반드시 확인해 주세요.
+
+- [ ] `modules/_bundled/`·`plugins/_bundled/`·`templates/_bundled/` 아래에 직접 추가한 커스텀 확장이 있습니다.
+- [ ] `public/.htaccess` 에 직접 추가한 규칙이 있습니다.
+- [ ] 그 외 코어 배포본에 없는 커스텀 파일을 직접 추가/수정했습니다.
+
+<!-- 위 항목에 해당하면 어떤 경로에 무엇을 추가했는지 적어 주세요. -->
+
+## 스크린샷·로그
+
+<!--
+- 브라우저 콘솔 에러 (F12 > Console)
+- storage/logs/ 관련 로그
+- 화면 스크린샷
+-->
+
+## 추가 정보
+
+<!-- 원인 추정, 임시 우회 방법 등 참고될 내용이 있으면 적어 주세요. -->
@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 질문·사용법 문의 (sir.kr Q&A)
+    url: https://sir.kr/questions/create?tag=%EA%B7%B8%EB%88%84%EB%B3%B4%EB%93%9C7
+    about: 버그가 아닌 사용법 질문·사용법 문의는 sir.kr Q&A 를 이용해 주세요.
+  - name: 보안 취약점 신고
+    url: https://github.com/gnuboard/g7/security/advisories/new
+    about: 보안 취약점은 공개 이슈가 아닌 비공개 Security Advisory 로 신고해 주세요.
@@ -0,0 +1,26 @@
+---
+name: ✨ 기능 제안
+about: 새로운 기능이나 개선 아이디어를 제안합니다.
+title: "[Feature] "
+labels: enhancement
+assignees: ''
+---
+
+## 해결하려는 문제
+
+<!-- 어떤 불편이나 한계 때문에 이 기능이 필요한지 적어 주세요. -->
+
+## 제안하는 기능
+
+<!-- 원하는 동작을 구체적으로 적어 주세요. -->
+
+## 적용 범위 (해당 시)
+
+- [ ] 코어
+- [ ] 모듈 <!-- 어떤 모듈인지: -->
+- [ ] 플러그인 <!-- 어떤 플러그인인지: -->
+- [ ] 템플릿 <!-- 어떤 템플릿인지: -->
+
+## 대안·참고 사항
+
+<!-- 고려한 다른 방법, 타 CMS 사례, 참고 링크 등이 있으면 적어 주세요. -->
@@ -0,0 +1,51 @@
+---
+name: ⬆️ 업그레이드 문제
+about: core:update / 확장 업데이트 과정에서 발생한 문제를 제보합니다.
+title: "[Upgrade] "
+labels: "bug, upgrade"
+assignees: ''
+---
+
+## 업그레이드 경로 (필수)
+
+- **업그레이드 전 버전**: <!-- 예: 7.0.0-beta.7 -->
+- **업그레이드 후(목표) 버전**: <!-- 예: 7.0.2 -->
+- **실행한 명령**: <!-- 예: php artisan core:update --source=/tmp/g7-7.0.2 -->
+- **실행 계정/권한**: <!-- 예: www-data / sudo(root) / 일반 사용자 -->
+
+> 참고: `core:update` 는 **현재 설치된(업그레이드 전) 버전의 코드**로 실행됩니다.
+> 따라서 최신 버전에서 수정된 버그라도, 그 수정 이전 버전에서 올라오는 경우에는 재발할 수 있습니다.
+> 업그레이드 전 반드시 전체 백업을 권장합니다.
+
+## 증상
+
+<!-- 업데이트 중/후 어떤 문제가 발생했는지 적어 주세요. 오류 메시지는 그대로 붙여 주세요. -->
+
+## 확장·커스텀 자산 상태 (필수)
+
+- [ ] `_bundled/` 아래에 직접 추가한 커스텀 확장이 있습니다. <!-- 경로: -->
+- [ ] `public/.htaccess`·`public/storage` 등 커스텀 파일/링크가 있습니다.
+- [ ] 업데이트 후 위 자산이 삭제/변경되었습니다.
+
+<!-- 업데이트 전후 확장 목록을 붙여 주시면 도움이 됩니다:
+  php artisan module:list / plugin:list / template:list
+-->
+
+```text
+(확장 목록 붙여넣기)
+```
+
+## 환경 정보
+
+- **PHP 버전**:
+- **웹서버·실행 방식**: <!-- Apache+mod_php / Nginx+PHP-FPM / 공유호스팅 등 -->
+- **DB**:
+- **OS**:
+
+## 로그·스크린샷
+
+<!--
+- 콘솔 전체 출력 (업데이트 실행 로그)
+- storage/logs/ 의 관련 로그
+- 브라우저 콘솔 에러
+-->
@@ -48,6 +48,11 @@ node_modules/

 # Settings JSON files (환경별 설정)
 /storage/app/settings/
+# 성능 계측 리포트 (g7:bench --report) — 측정값이 실행 머신 사양에 종속되므로 저장소에 축적하지 않는다
+/storage/app/benchmarks/
+
+# 확장 프론트엔드 병합 번들 캐시 (version-in-path, 런타임 생성)
+/storage/app/ext-bundles/

 # Bootstrap cache (auto-generated)
 /bootstrap/cache/*
@@ -133,3 +138,10 @@ playwright-report/
 test-results/
 # Playwright MCP 세션 아티팩트(스냅샷/콘솔 로그) — 커밋 대상 아님
 .playwright-mcp/
+
+# ===== 소스맵 =====
+# 소스맵은 원본 코드 전문(sourcesContent)을 담고 있어 배포 대상이 아니다.
+# 로컬 개발 빌드에서는 생성되지만(디버깅용) 저장소에는 유입되지 않는다.
+# 배포용 빌드는 `--production` 이 G7_BUILD_SOURCEMAP=0 을 주입해 생성 자체를 막는다.
+# 경로 한정 시 새 확장이 추가될 때 조용히 누락되므로 전역 규칙으로 둔다.
+*.map
@@ -6,15 +6,17 @@

 <!-- AUTO-GENERATED-START: docs-quick-reference -->

-### 백엔드 [backend/](docs/backend/) (31개)
+### 백엔드 [backend/](docs/backend/) (34개)

 | 문서 | 설명 | TL;DR 핵심 |
 |------|------|-----------|
 | [activity-log-hooks.md](docs/backend/activity-log-hooks.md) | 활동 로그 훅 레퍼런스 (Activity Log Hooks Reference) | 코어 66훅 + 이커머스 92훅 + 게시판 32훅 + 페이지 8훅 = 총 198훅 |
 | [activity-log.md](docs/backend/activity-log.md) | 활동 로그 시스템 (Activity Log System) | Monolog 기반: Service 훅 → Listener → Log::channel('activity... |
 | [admin-settings-access.md](docs/backend/admin-settings-access.md) | Admin 환경설정 값 접근 (`g7_core_settings` vs `config()`) | 동기화 SSoT: storage/app/settings/*.json → SettingsServicePr... |
+| [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... |
@@ -31,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 + ... |
@@ -113,10 +116,10 @@
 | [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/admin/[vendor-module]/... |
+| [module-routing.md](docs/extension/module-routing.md) | 모듈 라우트 규칙 | URL prefix 자동: /api/modules/[vendor-module]/... |
 | [module-settings.md](docs/extension/module-settings.md) | 모듈 환경설정 시스템 개발 가이드 | - |
 | [permissions.md](docs/extension/permissions.md) | 권한 시스템 | 구조: User → Role → Permission (기능 레벨) |
 | [plugin-development.md](docs/extension/plugin-development.md) | 플러그인 개발 가이드 | 디렉토리: plugins/vendor-plugin (예: sirsoft-payment) |
@@ -143,6 +146,37 @@
 | [e2e-testing.md](docs/testing/e2e-testing.md) | 그누보드7 Playwright E2E 테스트 가이드 | - |


+### API 레퍼런스 진입점
+
+> 엔드포인트별 요청 파라미터·응답 필드·요청/응답 예시. 공통 규약(Bearer 토큰 인증, 응답 봉투, 페이지네이션, 401/403/422/428)은 진입점 문서 상단에 정리되어 있다.
+
+| 대상 | 진입점 | 문서/엔드포인트 |
+|------|--------|----------------|
+| 코어 | [docs/backend/api/README.md](docs/backend/api/README.md) | 36 / 319 |
+
+
+### 확장 API 레퍼런스 (14개 확장, 자동 스캔)
+
+> 각 확장이 소유하는 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 / 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 / 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) | 3 / 5 |
+| `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-message_bizppurio` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-message_bizppurio/docs/api/README.md) | 6 / 21 |
+| `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 |
+
+
 <!-- AUTO-GENERATED-END: docs-quick-reference -->

 ---
@@ -161,7 +195,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}`)
@@ -192,6 +226,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` 사용 |
@@ -221,10 +257,26 @@

 | 금지 | 올바른 사용 |
 |------|------------|
-| `Icon className="w-4 h-4"` | `Icon size="sm"` 또는 `className="text-sm"` |
+| `Icon className="w-4 h-4"` | `className="text-base"` (아래 등가표) 또는 `size` prop |
 | `Select valueKey/labelKey` | computed로 `{ value, label }` 변환 |
 | Form 내 `Button` type 없음 | `type="button"` 명시 (submit 방지) |
 | `options={{options}}` | `options={{options ?? []}}` (fallback) |
+| boolean 필드를 `RadioGroup`/`Select` 의 `name` 자동바인딩만으로 폼에 묶기 | `autoBinding: false` + `value: "{{String(_local.form?.필드 ?? 기본값)}}"` + `change` 액션 `"{{$event.target.value === 'true'}}"` 캐스팅. 자동바인딩 value 경로는 `e.target.value` 문자열을 그대로 저장해 서버 `boolean` 규칙에서 422 가 된다 (표시만 보면 정상이라 저장 시점에야 드러남) |
+| `options` 지정 커스텀 `Select`(composite) 에 `defaultValue` | `value: "{{상태 ?? 기본값}}"` + `change` 액션 + 열기 지점 상태 시드 — 커스텀 Select 는 value-제어 전용이라 `defaultValue` 는 렌더되지 않고(빈 표시) 숨은 input 도 없어 값이 조용히 미전송된다 (options 없는 네이티브 렌더 경로만 defaultValue 유효) |
+| 폼 밖 제출 버튼 `props.form: "X"` 만 선언 | 참조 대상 `Form` 에 `props.id: "X"` 동반 필수 — id 가 없으면 버튼이 어떤 폼에도 연결되지 않아 클릭이 무반응이 된다 (오류 없음) |
+
+Icon 은 `<i>` 글리프라 박스 크기가 곧 `font-size` 다. `w-N h-N` 은 박스만 정하고 글리프는 부모 `font-size` 를 상속하므로 어긋난다. 기존 `w-N h-N` 을 옮길 때는 아래 등가표를 쓴다 (Chrome 실측).
+
+| `w-N h-N` | px | 등가 `className` |
+|---|---|---|
+| `w-3 h-3` | 12 | `text-xs` |
+| `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` 의 치환용으로는 쓰지 않는다.

 ### 상태 관리

@@ -259,6 +311,290 @@
 | `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)
+
+### 일괄 처리 목록의 선택 범위
+
+체크박스 선택은 화면 밖(전역/로컬 상태)에 저장된다. 그래서 검색·필터·페이지 이동으로 행이 목록에서 빠져도 그 행의 선택은 남는다. 그 상태에서 일괄 처리를 누르면 사용자가 보고 있지도, 체크하지도 않은 행이 대상이 된다. 확인 모달은 건수만 말하므로 실행 전에 알아챌 방법이 없고, 처리는 정상 성공하므로 실행 후에도 오류가 남지 않는다.
+
+| ❌ 금지 | ✅ 올바른 사용 |
+|--------|---------------|
+| 선택을 화면 밖 상태에 저장하는 DataGrid 에 `selectionScope` 미선언 | `"selectionScope": "page"`(일괄 처리 목록) 또는 `"free"`(선택 자체가 저장 대상인 폼)를 **명시** |
+| 일괄 처리 버튼이 달린 목록에 `"free"` | `"page"` — 대상은 언제나 "화면에 보이고 체크된 행" |
+| 여러 페이지에 걸쳐 고르는 폼 선택기에 `"page"` | `"free"` — 페이지를 넘기면 앞 페이지 선택이 사라져 기능이 깨진다 |
+| `selectable` 이 꺼진 화면이라 안전하다고 간주 | 체크박스가 없으면 남은 선택이 **더** 안 보인다 — 범위 판정은 `selectable` 과 무관 |
+| `"selectionScope": "{{조건}}"` 표현식 분기 | 리터럴 고정 — 분기마다 보존 여부가 갈리면 한쪽이 조용히 대상 밖 행을 싣는다 |
+| 화면마다 검색·필터·페이지 액션에 선택 초기화 액션을 복제 | 컴포넌트가 단일 지점에서 정리 — 액션 복제는 한 곳만 빠져도 같은 결함이 남는다 |
+
+정적 검사가 `onSelectionChange` 가 배선된 DataGrid 를 전수 검사해 미선언을 차단한다. 상세: [component-props.md DataGrid](docs/frontend/component-props.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)
+
+#### 보안 게이트 대칭성 (KVE-2026-1914/1915/1919)
+
+접근 게이트와 권한 등급 상한은 한 경로에만 있으면 다른 경로가 조용한 우회로가 된다. 게이트는 생산 지점(부모 비밀 판정 · 소유권 판정 · 등급 판정) 한 곳을 SSoT 로 두고, 같은 데이터를 내보내는 소비 경로 전부가 그 게이트를 경유해야 한다.
+
+| 금지 | 올바른 사용 |
+|------|------------|
+| 비밀/비공개 부모(게시글)의 비밀 게이트를 하위 리소스(댓글·첨부·문의) 독립 엔드포인트에서 재적용하지 않음 | 부모 비밀 판정을 하위 전 경로(훅·서비스·첨부 서빙·댓글 목록)에 재적용 — PostResource 한 곳만으로는 부족하다 (KVE-2026-1914) |
+| hash 기반 file-serving(preview/download)이 소유권·비밀·발행 상태 검사 없이 서빙 | preview 와 download 가 동일 게이트 공유 — 미발행·비소유·비밀 첨부는 404 (KVE-2026-1914 A-3/S-1/S-2) |
+| User/Role 의 쓰기·상태변경·권한부여 경로가 삭제 경로보다 약한 등급 가드 | 전 경로에 동일 등급-상한(rank ceiling)을 대칭 적용 — 정적 라우트(bulk)는 스코프 미들웨어가 우회되므로 서비스 계층에서 강제한다 (KVE-2026-1919) |
+| 저장측 레이아웃 표현식 검증(SafeLayoutExpressions)을 문자열 endpoint 필드에만 부착 | 표현식이 실릴 수 있는 배열 트리 전체(`content`)에 부착 — 문자열 한정 부착은 `is_array` 가드로 무력화되어 no-op 이 된다 (KVE-2026-1915) |
+| 배열 트리 순회용 규칙(`NoExternalUrls`)이 문자열 필드에도 부착돼 `is_array` 로 조용히 통과 | 규칙이 문자열 스칼라도 처리하거나, 그 자리에서 떼어낸다 — 부착만 해두고 통과시키는 상태가 최악이다 |
+| 같은 저장 대상의 FormRequest 마다 부착 규칙이 다름 (편집기 경로만 누락) | Store·Update·Content·ExtensionContent 4경로 동일 강도 — 편집기 저장 경로가 가장 약하면 그 경로가 우회로다 |
+| same-origin 을 `//` 접두·scheme·`/` 시작 **문자열 검사**로만 판정 | 브라우저 URL 파서와 동일 정규화(tab·LF·CR 제거 → 백슬래시를 슬래시로 → 선행 슬래시 런 접기) 후 판정 — `/\/evil.com/x.js` 는 문자열상 path 지만 브라우저는 외부 origin 으로 해석한다. 런타임·저장측·정적검사 3층이 같은 정규화를 공유한다 (KVE-2026-1915 B-2) |
+| same-origin 판정만 정규화하고 **신뢰 호스트 추출(`hostOf`)은 원문**으로 판정 | 두 판정이 같은 `if` 안에서 이어지므로 정규화도 공유 — 어긋나면 `https://evil.com\@cdn.신뢰.com/x.js` 가 저장측에서만 신뢰 호스트로 보여 통과한다 |
+| 정적 일괄 라우트(`bulk-*`)에 등급 상한만 적용하고 **스코프 축은 비움** | 라우트 모델이 없으면 미들웨어 스코프 검사가 스킵되므로 서비스가 상세 경로와 **같은 스코프 판정**(`PermissionHelper::filterByScope`)을 재적용 — 등급 축만 막으면 스코프 축이 우회로다 (KVE-2026-1919) |
+| 권한 상한(ceiling) 검사를 DB 쓰기 **뒤**에 배치 | 가드 → 쓰기 순서 — 쓰기 뒤에 검사하면 거부된 요청이 고아 행·반영된 속성 변경을 남긴다. 회귀 테스트는 403 뿐 아니라 **상태 불변**까지 단언한다 |
+| 같은 리소스를 쓰는 public 서비스 메서드 중 일부만 보호 가드 보유 | 형제 public 메서드 전부 동일 가드 — 서비스는 확장에 열려 있으므로 "현재 호출부가 없다" 는 방어가 아니다 |
+| 라우트 파라미터가 Model 로 resolve 되지 않는 쓰기 경로를 미들웨어 스코프 검사에 맡김 | 서비스 계층에서 재적용 — 스킵 조건은 정적 경로(`bulk-*`·`reorder`)뿐 아니라 **파라미터명 불일치**(`{id}` + `int` 타입힌트)도 있고, 후자는 상세 경로까지 무가드다 |
+| 순서 변경·일괄 작업의 스코프 거부를 "대상 일부 제외" 로 처리 | 순서·트리처럼 집합 전체가 하나의 값인 작업은 **전량 거부** — 일부만 반영하면 나머지와 어긋난 상태가 저장된다 |
+| 가시성 판정을 호출부가 넘기는 옵트인 플래그(`$filters['is_public'] ?? false`)에 의존 | 열람자 신원 기반 fail-closed — 옵트인은 호출부가 빠뜨리면 조용히 열린다(읽기만 하고 쓰는 곳이 없는 사문 플래그가 실재했다) |
+| 부모 상태로 판정하는 게이트를 `$x->parent && …` 로 작성 | 부모를 못 읽으면 차단 — 부모가 soft-delete 되면 조건이 성립하지 않아 통과한다 |
+| 리소스 `abilityMap can_*` 을 연관/타 리소스 권한으로 게이팅 | 그 엔드포인트의 라우트 권한(SSoT)과 **같은 리소스 prefix** — 상승 방지는 게이트 이중화가 아니라 rank ceiling 이 담당한다 |
+
+이 결함군은 예외도 오류도 남기지 않는다 — 약한 경로가 정상 응답을 내보내는 것이 유일한 증상이다. secret 게이트 재적용·hash 서빙 게이트·rank 대칭·URL 판정 3층 동형·정적 bulk 스코프 재적용·가드 선행·형제 메서드 가드 패리티·abilityMap prefix 정합은 의미 판정 영역이라 정적 검사가 일부만 덮으므로, 부모 변경·하위 서빙·등급 경로·URL 검증 지점을 건드릴 때 코드 리뷰에서 대칭성을 확인한다.
+
+> 상세: [validation.md](docs/backend/validation.md), [service-repository.md](docs/backend/service-repository.md), [frontend/security.md](docs/frontend/security.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`). 운영자가 이후 기본 통화를 바꿔도 과거 주문의 표기는 불변이어야 한다.
+
+동결 대상은 환율만이 아니다 — **소수 자릿수·절사 규칙·환산 분모(base_unit)까지 스냅샷이 SSoT** 다. 이 값들을 현재 설정에서 조회하면, 운영자가 그 통화를 삭제하는 순간 설정에서 사라져 폴백(자릿수 2)이 적용된다. 소수 0자리 통화의 과거 주문 표기가 `¥14,835` → `¥14,835.00` 으로 바뀌고, 3자리 이상으로 설정했던 통화는 표시 금액이 절사된다. 금액 계산은 스냅샷을 쓰는데 표기만 현재 설정을 따라가면 같은 화면 안에서 근거가 갈린다.
+
+| ❌ 금지 | ✅ 올바른 사용 |
+| --- | --- |
+| 주문·환불 표시에서 `getDecimalPlaces($code)` 를 스냅샷 없이 호출 | `getDecimalPlaces($code, $currencySnapshot)` — 스냅샷이 있으면 그것이 우선 |
+| 리소스가 주문 스냅샷을 자식에게 전파하지 않음 | `withOrderCurrency()` 를 전파하는 지점마다 `withCurrencySnapshot()` 도 함께 전파 |
+| 상품·카탈로그 표시까지 스냅샷으로 고정 | 현재 판매가는 **현재 설정**이 정답 — 스냅샷 없이 호출한다 |
+| 자릿수를 박제하지 않은 구형 스냅샷에서 예외/0 자리 강제 | 박제값이 없으면 현재 설정 폴백을 그대로 탄다 (하위호환) |
+
+> 상세: [api-resources.md](docs/backend/api-resources.md), [service-repository.md](docs/backend/service-repository.md)
+
+### 확장 결제수단은 자기 능력을 선언한다
+
+코어 `PaymentMethodEnum` 은 확장 결제수단 ID(`kginicis_naverpay`, `toss_tosspay` 등)를 모른다. 그래서 능력(PG 필요 여부 / PG 고정 / 환불수단)은 **등록하는 확장이 카탈로그에 선언**하고, 관리자 화면과 서버는 그 선언만 읽는다. 미선언 시 안전 기본값(`needs_pg=true`, `pg_locked=false`, `pg_provider=null`)으로 떨어지는데, 그 조합은 "PG 가 필요한데 어느 PG 인지 모른다" 를 뜻해 화면과 실제 결제 경로가 어긋난다.
+
+| 금지 | 올바른 사용 |
+|--------|---------------|
+| entry `defaults` 에 `pg_provider` 만 두고 능력 키 생략 | `needs_pg` 명시 선언 (PG 결제창을 거치는가) |
+| 자기 PG 전용 수단인데 `pg_provider: null` | `pg_provider: '{자기 provider id}'` + `pg_locked: true` (PG 제공자 등록 리스너의 id 와 동일해야 배지가 이름을 찾는다) |
+| 표시를 고치려고 코어 레이아웃 표현식을 정규식 치환 | 카탈로그 선언만 바꾼다 — 레이아웃이 `pg_locked`/`needs_pg` 로 직접 3분기한다 |
+| 선언을 바꾸고 기설치본은 그대로 | 저장된 `order_settings.json` 을 정정하는 업그레이드 스텝 동반 (자기 접두사만, 멱등) |
+
+레이아웃 치환 방식은 코어가 그 리터럴을 버리는 순간 조용히 사문화된다 — 합성 입력으로만 검증한 테스트는 계속 통과하므로 사문화가 드러나지 않는다. 정적 검사가 능력 선언 누락을 차단한다.
+
+### 예외를 응답으로 바꾸는 자리
+
+`catch (\Exception)` / `catch (\Throwable)` 는 **도메인 예외가 아닌 것**을 잡는 자리다. 여기서 4xx 를 돌려주면 인프라 장애·코드 결함이 "입력 오류" 로 위장되어 사용자는 고칠 수 없는 안내를 보고 운영자는 장애를 늦게 안다. 그리고 이미 번역된 `$e->getMessage()` 를 응답의 메시지 **키** 자리에 넘기면 키 해석에 실패해 원문(SQL 상태코드·경로 포함 가능)이 그대로 화면에 나간다. 둘 다 예외도 로그도 남기지 않는다.
+
+| 금지 | 올바른 사용 |
+|--------|---------------|
+| generic catch 가 4xx 반환 | 5xx — 의도적 4xx 는 사유와 함께 판정 테스트의 상수에 선언 |
+| generic catch 에서 상태코드 인자 생략 (`moduleError($mod,'key')`) | 상태코드 명시 — 생략 시 `ResponseHelper` 기본값 **400** 이 조용히 적용된다 |
+| 도메인 예외를 typed 로 승격한 뒤에도 `catch (\RuntimeException)` 유지 | 승격한 예외로 좁힌다 — 도메인 예외의 **부모**를 잡으면 남는 것은 인프라 예외뿐인데 그것까지 4xx 가 된다 |
+| `error($e->getMessage(), 422)` | `error($e->getMessageKey(), 422, null, $e->getMessageParams())` |
+| 도메인 예외가 번역문만 들고 다님 | 생성자에 키+치환 파라미터 보관 → `getMessageKey()` / `getMessageParams()` |
+| 서비스를 typed 예외로 승격하고 컨트롤러는 generic 만 유지 | 그 서비스 메서드를 호출하는 **컨트롤러 메서드 전수**에 typed catch 추가 (없으면 도메인 사유가 500 이 된다) |
+| typed 예외 도입하면서 그 분기의 상태코드도 변경 | typed 는 **기존 상태코드 유지** — 예외 도입이 사용자 계약을 함께 바꾸면 회귀다 |
+| 공개(비인증) 엔드포인트 응답에 예외 원문 포함 | 원문은 `Log::error` 로만 — 관리자 전용 면의 `errors` 페이로드는 진단 정보로 허용된다 |
+| 원문을 직접 문자열로 조립해 노출 폭을 호출부가 정함 | 노출 폭은 `ResponseHelper` 가 정한다 — Throwable 을 넘기면 `app.debug` 에서만 펼쳐진다 |
+| 치환 자리(`:error`)를 가진 키를 파라미터 없이 호출 | 넷째 인자 `messageParams` 로 채운다 — 비워 두면 번역기가 자리표시자를 **그대로 둔 문장**을 돌려줘 운영자 화면에 `:error` 가 노출된다 (실패했을 때만 드러나 정상 흐름 테스트로는 안 잡힌다) |
+| 사유를 모른다고 치환 자리를 비워 두기 | 알 수 없으면 일반 문구(`errors.unknown_error`)로 채운다 |
+| 원문을 싣지 않기로 한 문구에 `:error` 자리를 남겨 두기 | 그 키에서 **치환 자리 자체를 없앤다** — 자리를 남기면 나중에 예외 원문으로 채우는 회귀를 부른다 |
+| 하위 계층이 `false`/`null` 만 돌려주고 실패 사유를 버림 | 사유를 반환 경로에 실어 올린다 (배열 키 `reason` 또는 **뒤에 붙인 선택적 out 파라미터**) — 기존 호출부를 깨지 않는다 |
+| 확장 수명주기 훅이 사유 없이 `false` 반환 | `AbstractModule`/`AbstractPlugin` 의 `failWith(__('...'))` — 코어가 그 사유를 원인 자리에 싣는다 |
+
+`message`(첫 인자)와 `errors`(셋째 인자)는 다른 통로다. **키 자리에 원문을 넘기는 것은 언제나 금지**지만, `errors` 페이로드의 원문은 금지 대상이 아니다 — `ResponseHelper::error` 가 문자열 `errors` 를 `500+` 비디버그에서만 차단하고 배열은 통과시키는 것은 `tests/Unit/Helpers/ResponseHelperTest.php` 가 고정한 의도다. 관리자에게 결제대행사·외부 시스템이 돌려준 사유를 감추면 조치 근거가 사라지고, 다국어 키는 유한해서 예상 못 한 실패를 담지 못한다. 판단 축은 "원문이냐 키냐" 가 아니라 **누구에게 / 무엇의 원문인가 / 어느 통로인가** 셋이다.
+
+상세: [exceptions.md "예외 → 응답 매핑"](docs/backend/exceptions.md). `tests/Feature/Http/GenericCatchStatusCodeContractTest.php` 가 코어와 모든 번들 확장의 컨트롤러를 전수 스캔해 두 규칙을 고정한다. 판정기를 한 확장 안에 두면 그 확장 밖의 동형 결함이 검출되지 않는다. 치환 자리 축은 `tests/Feature/Http/ErrorMessageParamSubstitutionTest.php` 가 고정한다 — 호출부를 열거하지 않고 `->error(...)` 전수를 괄호 균형으로 잘라, 키를 실제로 번역해 `:error` 를 요구하는지 판정한다. 같은 판정기가 `new *OperationException(...)` 생성자 축도 덮는다(파라미터 배열이 넷째가 아니라 둘째 인자다). 이 축이 없으면 키를 들고 다니는 예외로 던지는 경로가 통째로 사각이 된다.
+
 ### Listener 데이터 접근

 | 금지 | 올바른 사용 |
@@ -269,6 +605,8 @@
 | Listener 생성자에 구체 Repository 직접 주입 | Repository Interface 주입 |
 | Listener 에서 `request()` / `$_POST` 직접 접근 | Service 가 검증 후 도메인 객체로 전달 받기 |
 | Filter 훅에 `'type' => 'filter'` 누락 | type 명시 필수 (반환값 무시 회귀 차단) |
+| 실패 시 호출자 트랜잭션을 되돌려야 하는 Action 훅에 `'sync' => true` 누락 | 금전 이동(쿠폰 차감·복원, 적립금 차감·복원)은 `sync` 필수. 기본값은 큐 래핑 + `afterCommit` 이라 **커밋 뒤에** 실행되어, 예외를 던져도 롤백되지 않고 오류 응답만 나간 채 데이터가 남는다 (큐 드라이버가 `sync` 여도 동일) |
+| 훅 회귀 테스트에서 리스너를 손으로 `addAction` 등록 | `HookListenerRegistrar::register()` 로 **실제 등록 경로**를 태운다 — 손으로 등록하면 큐 래핑을 건너뛰어 커밋 이후 실행 문제를 통과시킨다 |
 | Listener 가 `HookListenerInterface` 미구현 (auto-discovery 대상) | implements + `getSubscribedHooks()` 정적 메서드 |

 > 상세: [hooks.md "Listener 데이터 접근 규정"](docs/extension/hooks.md), [service-repository.md](docs/backend/service-repository.md)
@@ -666,9 +1004,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/) 각 문서 참조

 ### 컨트롤러 계층
@@ -712,6 +1056,11 @@ 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 "라우트 캐시")
+필수: 확장 라우트는 활성 상태인 확장의 것만 등록한다 — 모듈·플러그인 두 라우트 프로바이더가 같은 기준을 쓴다. 게이트가 한쪽에만 있으면 그 비대칭은 오류가 아니라 "조용히 열린 경로" 로만 나타난다: 비활성화해도 화면·메뉴·에셋만 사라지고 API 는 계속 호출 가능하며, 컨트롤러가 정상 처리하므로 오류도 로그도 남지 않는다
+필수: 그 rebuild() 는 확장 상태 캐시 무효화(invalidate*StatusCache()) 뒤에 온다 — route:cache 는 새 앱을 부팅해 라우트를 수집하는데 그 부팅의 확장 라우트 프로바이더는 DB 가 아니라 캐시된 활성 확장 목록(TTL 기본 1일)을 읽으므로, 먼저 구우면 방금 바뀐 상태가 빠진 채 박제되고 자가 회복되지 않는다 (활성화 → 그 확장 API 전량 404 / 비활성화 → 끈 확장 API 가 계속 호출 가능 / 업데이트 → 404 + 훅 리스너 누락). 무효화는 굽기 직전이 아니라 DB 상태 쓰기 직후에 둔다 — 같은 목록을 읽는 굽기가 라우트 캐시 말고도 있다 (오토로드 갱신 안의 훅 매핑 캐시). update 경로만 예외: Updating 전이 직후에는 비우지 않고 (비우면 그 창의 오토로드 갱신이 그 확장을 비활성으로 판정해 훅 리스너를 떨군다) 상태 복원 직후에 비운 뒤 ExtensionManager::regenerateHookCache() 로 훅 캐시를 다시 굽는다. 훅 캐시 폴백은 파일 부재·손상에만 작동해 내용이 stale 한 경우는 조용히 통과한다
 필수: 코어 레이아웃에 모듈 UI 주입은 layout_extensions만 사용
 필수: 모든 확장 작업은 Artisan 커맨드로 수행
 ```
@@ -768,14 +1117,33 @@ 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}/`)을 갱신하지 않으면 새로 추가한 번역 키가 런타임에 존재하지 않아 해당 로케일이 조용히 기준 로케일로 폴백한다.
+
+### 배포 산출물의 브라우저 하한
+
+선언 하한은 **Chrome 111 / Safari 16.4 / Firefox 128** 이다 ([requirements.md §7](docs/requirements.md)). 빌드 타깃(`target: 'es2020'`)은 이 하한을 강제하지 못한다 — **ES 연도와 브라우저 지원 연도가 다르기 때문**이다. ES2018 인 정규식 lookbehind 를 WebKit 은 Safari 16.4 에서야 구현했고, 타깃 검사는 그대로 통과시킨다.
+
+정규식 **리터럴** 문법은 그중에서도 다운레벨이 원리상 불가능하다. 번들러는 lookbehind 를 `new RegExp(...)` 로 옮길 뿐이라 파싱 오류가 **런타임 오류로 이동**할 뿐 사라지지 않는다. 따라서 타깃 하향은 해법이 아니다.
+
+| ❌ 금지 | ✅ 올바른 사용 |
+|--------|---------------|
+| 배포 JS 산출물에 선언 하한 **초과** 문법·API (`Object.groupBy`·`Promise.withResolvers`·`Array.fromAsync`·`RegExp.escape`·정규식 `v` 플래그) | 하한 이하 문법으로 작성 |
+| **부팅 임계 번들**(`public/build/core/template-engine.min.js`, `templates/_bundled/*/dist/js/components.iife.js`)에 정규식 리터럴 전용 문법(lookbehind `(?<!` `(?<=`, `v` 플래그) — 하한과 같은 버전이어도 | 그 두 파일만은 하한 미만 브라우저에서도 **파싱**돼야 한다 |
+| 빌드 타깃을 낮춰 해결 시도 | 소스에서 그 문법을 쓰지 않는다 |
+| 바이트 길이 비교식 번들러 검출기로 판정 | 문법·API 표 기반 검사 (프린터 표기 차이가 오탐을 낸다) |
+
+부팅 임계 번들 둘은 `async`/`defer` 없는 동기 classic 스크립트다. 파싱에 실패하면 **폴백 안내 화면조차 렌더되지 않아** 사용자에게는 백지 또는 거짓 진단만 남는다. 하한 미만 브라우저에 "지원 범위 밖" 안내를 띄우려면 이 두 파일은 파싱에 성공해야 하므로, 하한과 **정확히 같은** 버전을 요구하는 문법(lookbehind = Safari 16.4)도 금지한다 — 하한 초과만 보는 검사로는 영원히 잡히지 않는 지점이다. 정적 검사가 이 규칙을 강제한다.
+
 ### 코어 3-번들 구조 + 공유 런타임 (engine-v1.51.0+)

 `core:build` 는 코어 프론트엔드를 3개 IIFE 번들로 빌드한다:
@@ -788,6 +1156,18 @@ php artisan plugin:update sirsoft-payment --force

 lazy 번들(편집기/devtools)이 코어 런타임(DynamicRenderer·엔진 싱글톤·React Context·DevTools 코어)을 재사용할 때는 재번들하지 않고 `window.G7Core.__runtime` 을 빌려 쓴다 — React/컨텍스트/싱글톤 인스턴스 동일성이 강제되기 때문(사본이 둘이면 "Invalid hook call"·컨텍스트 미매칭). 메인 번들이 `G7CoreGlobals` 에서 공유 대상을 `G7Core.__runtime` 에 노출하고, lazy 번들 vite config 는 React 4종(`react`/`react-dom`/`react-dom/client`/`react/jsx-runtime`)을 external→window 로, 코어 런타임 모듈을 `resolveId` 플러그인으로 `__runtime-shims/` 로 치환한다.

+### 확장 번들 병합 (서버측 concat)
+
+활성 모듈/플러그인의 프론트엔드 IIFE JS·CSS 는 타입별로 서버에서 하나의 번들로 병합해 서빙한다(`/api/{modules,plugins}/bundle.{js,css}?v={version}`). `ExtensionBundleService` 가 정렬·필터·concat·캐시를 전담하고, 프론트는 `window.G7Config.bundleUrls` 를 읽어 모듈 번들 → 플러그인 번들 순으로 로드한다. 병합 규율:
+
+- priority 순서는 선언형 — 실행 순서는 오직 manifest `loading.priority` 오름차순(`uasort`). 특정 확장 이름을 지목하는 분기를 두지 않는다.
+- IIFE 사이는 `\n;\n`(JS)/`\n`(CSS) 로 잇는다. 미사용 시 ASI 경계가 깨져 번들 전체 파싱 에러가 난다.
+- 소스맵은 prod strip, dev 는 개별 에셋 서빙 절대 URL 로 rewrite. 개별 에셋 서빙 라우트(`*.map` 포함)는 존치한다.
+- 번들 URL 은 반드시 same-origin(`/api/...`). 외부 origin/CDN·protocol-relative 는 gdpr preblocker 에 자기 차단된다.
+- 확장 에셋 절대경로는 `getBuiltAssetAbsolutePaths()`(=`getModulePath()`/`getPluginPath()`) 만 쓴다. `base_path("modules"|"plugins")` 직접 조립은 `_bundled` 경로 오해석 → 빈 번들.
+- concat 루프는 확장별 try/catch — 실패 확장만 skip 하고 나머지 병합을 지속한다.
+- 번들 파일명에 확장 캐시 버전을 포함(`{type}.{version}.{js,css}`). 조합 변경 시 version bump → 새 파일명 → 자동 재생성. 구파일 GC 는 `ext-bundles:cleanup` + `{module,plugin,template}:cache-clear` 가 담당한다. prod 은 version-in-path 디스크 캐시, 비프로덕션은 매 요청 concat.
+
 ### 빌드 명령어 (Artisan)

 ```bash
@@ -816,6 +1196,8 @@ php artisan plugin:build sirsoft-payment --active       # 활성 디렉토리에
 ```

 > **빌드 원칙**: 기본값은 `_bundled` 디렉토리. 빌드 결과물은 빌드 경로 내에만 남음.
+
+`_bundled` 의 `dist/`(코어는 `public/build/core/`)는 Git 추적되는 배포 산출물이다 (`*.map` 만 ignore). src 변경 시 커밋 dist 를 `--production` 으로 동반 재빌드한다 — 신규 소스 리터럴이 dist 에 없으면 stale 빌드이며, 정적 검사가 이를 검출한다. 커밋 dist 에 `//# sourceMappingURL=` 참조를 남기지 않는다 — `.map` 은 배포본에 존재하지 않아 브라우저 개발자 도구에서 404 를 유발한다. 코어 3번들 재빌드는 `core:build --production` (`--full` 은 앱 번들 전용 — `public/build` 를 비워 코어 3번들을 지운다).
 > 활성 디렉토리 반영은 `update` 커맨드로만 수행. `--watch` 모드는 실시간 개발용으로 활성 디렉토리를 자동 사용.

 ---
@@ -902,7 +1284,7 @@ php artisan migrate:rollback

 | 수정 대상 파일 패턴 | 작업 전 필수 참조 |
 | ------------------- | ------------------ |
-| `app/Http/Controllers/**` | [controllers.md](docs/backend/controllers.md) |
+| `app/Http/Controllers/**` | [controllers.md](docs/backend/controllers.md), [api-documentation.md](docs/backend/api-documentation.md) |
 | `app/Services/**` | [service-repository.md](docs/backend/service-repository.md) |
 | `app/Http/Requests/**` | [validation.md](docs/backend/validation.md) |
 | `app/Repositories/**` | [service-repository.md](docs/backend/service-repository.md) |
@@ -920,6 +1302,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) |

 ---

@@ -952,3 +1335,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`
@@ -4,6 +4,403 @@
 형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)를 따르며,
 [Semantic Versioning](https://semver.org/lang/ko/)을 준수합니다.

+## [7.0.9] - 2026-08-24
+
+### Added
+
+- 게시글·상품 설명·페이지처럼 에디터로 작성한 본문에서 첫 번째 내부 이미지를 찾아 목록 썸네일이나 공유 미리보기 이미지로 활용할 수 있는 공용 기능이 추가되었습니다. 게시판·쇼핑몰·페이지 확장이 이 기능을 사용합니다. (#22 @abc101 님께서 제보해주셨습니다.)
+- 사이트 기본 공유 이미지(og:image)를 환경설정 > SEO 에서 지정할 수 있습니다. 화면별 공유 이미지가 없을 때 이 이미지가 사용되어, 사이트 주소를 공유했을 때 미리보기 카드에 이미지가 비어 보이는 일이 없어집니다.
+
+### Fixed
+
+- 알림 템플릿·본인인증 메시지에서 [기본값 복원]을 실행하면 언어팩이 제공한 번역(일본어 등)이 함께 지워지던 문제를 수정했습니다. 이제 복원 기본값에도 활성 언어팩의 번역이 포함되어, 복원 후에도 해당 언어 화면에 번역이 유지됩니다. 또한 이번 버전으로 업그레이드하면 이전 버전에서 이미 지워졌던 언어팩 번역이 활성 언어팩 기준으로 자동 복구됩니다.
+- 설치·복구 과정의 데이터 동기화에서 코어 알림 정의와 본인인증 메시지에 언어팩 번역이 주입되지 않을 수 있던 문제를 수정했습니다.
+- 언어팩 업데이트가 실패했을 때 사용 중이던 언어팩이 비활성 상태로 남아, 해당 언어의 화면·메일 문구가 안내 없이 기본 언어로 표시되던 문제를 수정했습니다. 이제 실패 시 이전 상태로 복원됩니다.
+- 언어팩을 다시 활성화하거나 업데이트할 때 관리자가 직접 수정해 둔 알림·본인인증 템플릿의 해당 언어 문구가 언어팩 기본값으로 덮어써지던 문제를 수정했습니다. 이제 관리자가 수정한 언어만 보존되고, 수정하지 않은 언어는 언어팩 갱신을 그대로 따라갑니다.
+- 언어팩 활성화 직후 같은 화면 흐름에서 일부 기본 데이터에 새 언어 번역이 반영되지 않던 문제를 수정했습니다.
+
+## [7.0.8] - 2026-08-22
+
+### Added
+
+- 사이트가 외부로 보내는 요청을 지정한 프록시 서버를 거쳐 나가도록 설정할 수 있습니다. 결제사처럼 접속 IP 를 제한하는 외부 서비스를 연동할 때, 개발·스테이징 환경에서도 허용된 IP 로 요청을 보낼 수 있습니다. 환경설정 > 고급에서 디버그 모드를 켜면 프록시 주소 입력칸이 나타나며, 프록시를 거치지 않을 주소를 예외 목록으로 따로 지정할 수 있습니다. 디버그 모드를 끄면 저장된 주소가 남아 있어도 프록시는 적용되지 않습니다.
+- 프록시 주소 옆의 「연결 테스트」로 저장하기 전에 연결 여부를 확인할 수 있습니다. 성공하면 그 프록시를 거쳤을 때 외부 서비스에 보이는 IP 주소를 함께 알려주므로, 결제사에 어떤 IP 를 등록해야 하는지 미리 확인할 수 있습니다.
+- 확장 개발자용: 사이트 표준 HTTP 호출은 프록시 설정이 자동으로 적용됩니다. 외부 연동 규약상 별도 방식으로 통신해야 하는 확장은 코어가 제공하는 프록시 설정을 받아 같은 경로로 내보낼 수 있습니다.
+
+### Changed
+
+- 비활성화한 플러그인의 기능이 더 이상 동작하지 않습니다. 이전에는 플러그인을 꺼도 화면·메뉴·스크립트만 사라지고 그 플러그인의 기능 주소는 계속 응답해, 꺼진 결제수단으로 결제가 시도되는 등 "껐는데 아직 살아 있는" 상태가 남았습니다. 이제 모듈과 동일하게 활성화된 플러그인의 기능만 동작합니다. **결제·본인인증처럼 외부 서비스가 직접 호출하는 주소도 함께 닫히므로, 진행 중인 거래가 있을 때의 비활성화·업데이트는 처리가 끝난 뒤에 하시기 바랍니다.**
+- 확장 개발자용: 모듈·플러그인의 설치·활성화·비활성화·제거 처리에서 실패 사유를 코어에 전달할 수 있습니다. `failWith()` 로 사유를 남기고 실패를 반환하면 관리자 화면의 실패 안내에 그 사유가 함께 표시됩니다. 사유를 남기지 않아도 종전처럼 동작합니다.
+- 지원 브라우저 문서에 최소 버전(Chrome 111 / Safari 16.4 / Firefox 128)을 명시했습니다. 이보다 오래된 브라우저에서는 스타일이 일부 깨질 수 있으나 화면 표시와 기본 이용은 가능하도록 유지한다는 방침도 함께 밝혔습니다. (#121 @bigmsg 님께서 건의해주셨습니다.)
+
+### Fixed
+
+- 구형 iOS·macOS Safari(16.4 미만)에서 사이트가 전혀 표시되지 않던 문제를 수정했습니다. 화면 구성에 쓰이는 스크립트에 해당 브라우저가 해석하지 못하는 문법이 들어 있어, 스크립트 전체가 실행되지 못하고 사이트가 통째로 멈춰 있었습니다. (#121 @bigmsg 님께서 제보해주셨습니다.)
+- 화면을 불러오지 못했을 때 원인과 무관하게 "네트워크 연결이 불안정할 수 있습니다"로 안내되던 문제를 수정했습니다. 브라우저가 지원 범위보다 오래되어 화면을 실행하지 못한 경우에는 그에 맞는 안내를 표시하며, 새로고침해도 해결되지 않는 상황이므로 새로고침 버튼도 표시하지 않습니다.
+- 관리자 화면의 실패 안내에 원인이 들어갈 자리가 채워지지 않아 `:error` 라는 내부 표시가 그대로 보이던 문제를 수정했습니다. 모듈·플러그인·템플릿·언어팩 관리와 플러그인 설정 저장의 실패 안내 전반에서 발생했습니다. 이제 실패 원인을 알 수 있으면 그 원인이, 알 수 없으면 일반 안내 문구가 표시됩니다. 언어팩 관리처럼 원인을 표시하지 않기로 한 안내는 문구 자체를 정리했습니다.
+- 모듈·플러그인을 활성화한 직후 그 확장의 화면과 기능이 "주소를 찾을 수 없음" 오류만 내던 문제를 수정했습니다. 활성화 시점에 사이트 내부 주소록이 활성화 이전 상태를 기준으로 다시 만들어져, 방금 켠 확장의 주소가 빠진 채로 굳어졌습니다. 시간이 지나도 스스로 복구되지 않았습니다. 같은 원인으로 비활성화한 확장의 기능이 계속 호출 가능하던 문제, 확장을 업데이트한 직후 그 확장의 기능과 다른 기능과의 연동 동작이 함께 누락되던 문제도 바로잡았습니다.
+
+## [7.0.7] - 2026-08-19
+
+### Security
+
+- 부관리자(위임 관리자)가 슈퍼 관리자 계정을 함부로 손대지 못하도록 막았습니다. 슈퍼 관리자 보호는 삭제·탈퇴 경로에만 있었고 비밀번호 변경·상태 변경(차단/탈퇴)·계정 잠금 해제·일괄 상태 변경 경로에는 없어, 회원 관리 권한만 위임받은 계정이 슈퍼 관리자 계정을 무력화할 수 있었습니다. 이제 이 경로 전부에 같은 기준을 적용해, 슈퍼 관리자 계정은 슈퍼 관리자만 수정할 수 있습니다. 슈퍼 관리자 본인의 작업은 종전처럼 정상 동작합니다. (KISA 측에서 제보해주셨습니다 — KVE-2026-1919)
+- 부관리자가 역할 권한을 통해 자신보다 높은 권한을 획득하지 못하도록 막았습니다. 이전에는 역할에 권한을 부여할 때 부여하는 사람이 그 권한을 가졌는지 확인하지 않아, 권한 관리 권한만 위임받은 계정이 자신에게 없는 권한이나 더 넓은 범위의 권한을 역할에 실어 우회 상승할 수 있었습니다. 이제 자신이 보유한 권한을 자신의 범위 이내로만 부여할 수 있으며, `admin` 같은 시스템·확장 소유 역할의 권한·활성 상태 변경도 슈퍼 관리자로 제한됩니다. (KISA 측에서 제보해주셨습니다 — KVE-2026-1919)
+- 위 상한을 사용자에게 역할을 붙이는 경로에도 동일하게 적용했습니다. 이전에는 사용자 생성·수정 화면에서 역할을 배정할 때 그 역할이 담은 권한을 배정자가 모두 가졌는지 확인하지 않아, `admin` 같은 고권한 역할을 통째로 붙여 우회 상승할 수 있었습니다. 이제 배정자가 자신의 권한 범위 안에서 전부 부여할 수 있는 역할만 붙일 수 있습니다. 같은 기준이 역할을 **떼는** 방향에도 적용되어, 자신이 부여할 수 없는 상위 역할을 다른 관리자에게서 박탈하는 것도 차단됩니다. 사용자가 이미 가진 역할을 유지하는 수정은 그대로 허용되고, 슈퍼 관리자의 역할 배정은 종전처럼 정상 동작합니다. (KVE-2026-1919)
+- 레이아웃 편집기에 저장하는 표현식이 서버나 다른 사용자 브라우저에서 임의 코드로 실행될 수 없도록 표현식 평가 방식을 근본적으로 바꿨습니다. 이전에는 표현식을 실제 코드로 만들어 실행했기 때문에 특정한 우회 기법으로 편집 권한을 넘어선 동작이 가능했습니다. 이제 정해진 문법·함수만 해석하는 안전한 방식으로 평가하며, 위험한 표현식과 외부 주소의 스크립트 로드는 저장 단계에서도 거부합니다. 기존 레이아웃의 정상 표현식(조건·계산·목록 가공·경로 조립 등)은 그대로 동작하고, 위지윅 에디터·주소 검색처럼 정해진 외부 스크립트를 쓰는 확장은 각자 신뢰 출처를 선언해 정책 강화 이후에도 정상 동작합니다. 신뢰 출처는 모듈·플러그인·템플릿이 모두 자기 설정 파일에 선언할 수 있으며, 활성 상태인 확장의 선언만 반영됩니다. (KISA 측에서 제보해주셨습니다 — KVE-2026-1915)
+- 레이아웃에 적는 주소가 "내 사이트 경로"인지 판정하는 방식을 브라우저의 실제 해석과 일치시켰습니다. 이전에는 주소 앞부분의 글자만 보고 판정했기 때문에, 슬래시 사이에 역슬래시나 보이지 않는 공백 문자를 끼워 넣은 주소가 내 사이트 경로처럼 통과한 뒤 브라우저에서는 외부 사이트 주소로 해석되어, 선언하지 않은 외부 스크립트가 실제로 불려 올 수 있었습니다. 이제 브라우저와 같은 기준으로 정규화한 뒤 판정하며, 저장 단계·화면 로드·정비 검사 세 곳이 같은 기준을 씁니다. 경로 중간에 역슬래시가 들어간 정상 주소는 종전처럼 그대로 동작합니다.
+- 레이아웃 편집기로 저장할 때 외부 주소 차단이 적용되지 않던 문제를 수정했습니다. 레이아웃을 새로 만들거나 정보를 수정하는 경로에는 이 검사가 걸려 있었지만, 편집기가 실제로 사용하는 콘텐츠 저장 경로에는 빠져 있어 같은 내용도 어느 화면에서 저장하느냐에 따라 통과 여부가 달랐습니다. 함께, 주소 입력 칸 하나만 검사하도록 걸어 둔 설정이 실제로는 아무것도 검사하지 않고 지나가던 것도 바로잡았습니다. 이제 네 저장 경로가 모두 같은 강도로 검사합니다.
+- 회원 일괄 상태 변경에서 담당 범위 제한이 적용되지 않던 문제를 수정했습니다. 회원 수정 권한은 "본인 계정만" 또는 "같은 역할 범위만" 으로 범위를 좁혀 위임할 수 있는데, 이 제한은 회원을 하나씩 여는 화면에서만 적용되고 목록에서 여러 명을 한 번에 처리하는 일괄 변경에는 적용되지 않았습니다. 그래서 범위를 좁혀 위임받은 관리자가 일괄 변경으로는 담당 밖 회원까지 차단·탈퇴 처리하고 그 회원들의 로그인 세션까지 끊을 수 있었습니다. 기본 제공 역할인 "매니저" 가 이 구성에 해당합니다. 이제 일괄 변경도 회원 상세와 같은 기준으로 대상마다 범위를 확인하며, 범위 밖 회원은 처리 대상에서 제외되고 처리 건수로 확인할 수 있습니다. 범위 제한 없이 위임받은 관리자의 일괄 작업은 종전처럼 정상 동작합니다. (KVE-2026-1919)
+- 레이아웃에 적는 스크립트 주소가 확장이 선언한 신뢰 출처인지 판정할 때, 주소를 브라우저와 같은 기준으로 정규화하지 않던 문제를 수정했습니다. 신뢰 출처 이름을 주소 뒷부분에 끼워 넣고 그 앞에 역슬래시를 둔 주소가 저장 단계에서만 신뢰 출처로 보여 통과했습니다(화면 로드 단계는 차단하고 있었으므로 실제로 불려 오지는 않았습니다). 반대로 브라우저가 신뢰 출처로 읽는 형태를 저장 단계만 거부하는 경우도 있었습니다. 이제 주소가 "내 사이트 경로인가" 와 "신뢰 출처인가" 를 같은 기준으로 판정합니다.
+- 역할 생성·수정이 권한 상한에 걸려 거부될 때 변경 일부가 남던 문제를 수정했습니다. 권한 확인이 저장 뒤에 있었기 때문에, 거부된 요청인데도 권한이 하나도 없는 빈 역할이 만들어지거나 역할 이름 변경만 반영된 상태가 남았습니다. 이제 저장 전에 확인해 거부 시 아무것도 변경되지 않습니다.
+- 첨부파일 순서 변경과 메뉴 순서 변경에도 담당 범위 제한을 적용했습니다. 두 기능은 대상을 목록으로 한 번에 받는 방식이라 범위 확인이 걸리지 않았고, 그래서 "본인 것만" 으로 범위를 좁혀 위임받은 관리자가 다른 사람이 올린 첨부파일이나 만든 메뉴의 순서를 바꿀 수 있었습니다. 기본 제공 역할인 "매니저" 가 첨부파일에서 이 구성에 해당합니다. 순서는 목록 전체에 대한 하나의 값이라 일부만 반영하면 나머지와 어긋나므로, 범위 밖 대상이 하나라도 섞이면 요청 전체를 거부하고 아무것도 변경하지 않습니다. (KVE-2026-1919)
+- 레이아웃 표현식에서 객체의 숨은 내부 구조에 접근하는 우회 경로를 막았습니다. 표현식 평가기는 위험한 이름으로의 직접 접근을 막고 있었지만, 모든 객체가 공통으로 가진 오래된 방식의 접근 함수는 그 검사를 거치지 않아 같은 곳에 닿을 수 있었습니다. 이 경로로 사이트 전체의 공통 동작을 바꾸거나 망가뜨릴 수 있었습니다(임의 코드 실행으로는 이어지지 않습니다). 이제 화면 로드·저장·정비 검사 세 곳이 모두 이 이름들을 거부하며, 기존 레이아웃이 쓰는 정상 표현식은 그대로 동작합니다. (KVE-2026-1915)
+- 회원 탈퇴·회원 정보 관리 작업이 실패할 때, 응답 메시지에 데이터베이스 오류 원문 같은 내부 시스템 정보가 그대로 노출될 수 있던 문제를 수정했습니다. 이제 이런 경우 사용자에게는 일반 안내 문구만 표시하고, 원본 오류는 서버 로그에만 기록합니다. (sir.kr 커뮤니티의 Xbuilder 님께서 제보해주셨습니다.)
+- 만료된 인증 토큰이 사용자 언어(로케일) 판별에서 여전히 유효한 것으로 취급되던 문제를 수정했습니다. 이제 만료된 토큰은 비로그인과 동일하게 처리합니다. (sir.kr 커뮤니티의 Xbuilder 님께서 제보해주셨습니다.)
+- 통합 검색이 로그인한 회원을 비회원으로 취급하던 문제를 수정했습니다. 검색 API 가 로그인 상태를 해석하지 않아, 회원 전용 게시판의 읽기 권한이 있어도 검색 결과와 게시판 필터 목록이 비회원 기준으로만 제한되었습니다. 이제 로그인한 회원은 자신이 열람할 수 있는 게시판 범위 그대로 검색됩니다. 비회원 검색은 종전과 동일합니다.
+- 셸 예약 작업의 허용 실행 파일 목록에 `bash`·`python` 같은 인터프리터를 등록했을 때, 인터프리터에 인라인 명령(`bash -c ...` 형태)을 실어 임의 명령이 실행되던 문제를 막았습니다. 이제 인터프리터 뒤에는 절대경로 스크립트 파일만 지정할 수 있으며, 인라인 코드 실행·상대경로·경로 조작이 담긴 명령은 저장·실행 양쪽에서 거부됩니다. 스크립트 파일을 주기 실행하는 정상 사용(예: `python /경로/작업.py`)은 그대로 동작합니다. 이 기능은 현재 메뉴에 노출되지 않아 실제 사용 경로가 없습니다. (KISA 측에서 제보해주셨습니다 — KVE-2026-1653)
+- 검색어·게시글 제목처럼 방문자가 입력한 값이 검색엔진용 구조화 데이터(JSON-LD)에 실릴 때, 스크립트 태그를 닫는 문자열을 끼워 넣으면 그 뒤의 내용이 방문자 브라우저에서 스크립트로 실행될 수 있던 문제를 수정했습니다. 검색엔진 봇에게 제공되는 화면이지만 특정 주소 파라미터로 일반 방문자에게도 같은 화면을 강제할 수 있어 실제 공격 경로가 됩니다. 이제 태그 문자를 이스케이프해 실행을 차단하며, 검색엔진이 읽는 구조화 데이터의 의미는 그대로 유지됩니다.
+
+### Added
+
+- 레이아웃 편집기 첨부 파일 업로드에 업로드 전/후 액션 훅과 파일 가공 필터 훅 제공 — 확장에서 다른 업로드 경로와 동일하게 개입할 수 있습니다.
+- S3 호환 스토리지(Cloudflare R2, MinIO, 네이버 클라우드 등) 연결 지원 — 드라이버 설정에 엔드포인트 URL 과 Path-style 주소 옵션이 추가되어, AWS 가 아닌 S3 호환 스토리지도 관리자 화면 설정만으로 연결할 수 있습니다. S3 리전도 목록 선택 대신 자유 입력으로 바뀌어 새로 생기는 리전이나 R2 의 `auto` 값을 그대로 쓸 수 있습니다.
+- 서버에서 동작할 수 없는 드라이버(필요한 라이브러리·PHP 확장이 없는 경우)를 저장하려 하면 사유와 함께 거부합니다 — 잘못된 드라이버 저장으로 사이트가 멈추는 사고를 저장 시점에 차단합니다.
+- 완전 공개 자산(상품·카테고리·리뷰·에디터 이미지)을 S3+CDN 등 원격 디스크의 직접 URL 로 서빙할 수 있습니다. 환경설정 > 드라이버의 "공개 자산 스토리지"에서 디스크를 고르면 새로 올리는 이미지가 그 디스크에 저장되고 화면에는 CDN 주소가 실립니다 — 서버를 거치지 않아 트래픽 부담이 줄어듭니다. 사용 안 함(기본)이면 종전 방식 그대로이며, 디스크를 바꿔도 기존 이미지는 원래 위치에서 계속 정상 표시됩니다. 확장(쇼핑몰·에디터)별로 다른 디스크를 쓰도록 개별 설정할 수도 있습니다. (#100 @lyg-kaban 님께서 건의해주셨습니다.)
+- 확장 개발자용: 스토리지 URL 계약이 public 외에도 URL 이 설정된 디스크(S3+CDN 등)에서 직접 주소를 반환하며, 생성 결과를 공급·수정·차단할 수 있는 `core.storage.filter_url` 필터 훅이 추가되었습니다. 공개 자산 디스크 선택지는 `core.settings.available_public_asset_drivers` 훅으로 플러그인이 확장할 수 있고, 확장이 이미지 같은 카테고리 단위로 다른 스토리지 디스크를 쓰도록 분리할 수 있습니다. 공개 자산 디스크 오버라이드 설정을 선언한 플러그인은 설정 조회·저장 응답에 디스크 선택지 목록이 함께 실리고 저장 시 선택지 검증도 함께 걸리므로, 설정 화면이 별도 권한의 코어 환경설정 API 를 조회하거나 플러그인이 검증을 따로 구현할 필요가 없습니다.
+- 보존 기간이 지난 데이터의 자동 정리에 확장이 개입할 수 있는 훅을 제공합니다 — 활동 로그·알림 발송 이력·예약 작업 이력의 정리 전후에 발생하므로, 확장이 정리 대상을 외부에 따로 보관하는 등의 처리를 붙일 수 있습니다.
+- 폼을 저장하지 않고 나가서 소유자 없이 남은 첨부파일을 자동으로 정리할 수 있습니다. 환경설정 > 업로드에서 자동 정리를 켜면(기본 꺼짐) 설정한 보존기간(기본 30일)이 지난 고아 첨부의 파일과 기록을 매일 삭제합니다. 사이트 로고처럼 현재 사용 중인 첨부와 확장이 관리하는 첨부는 대상에서 제외됩니다.
+- 관리자가 회원 정보 수정 화면에서 상태를 '탈퇴'로 바꿔 저장하면 확인 창을 거치도록 했습니다. 이 처리는 회원의 이메일·이름·닉네임을 익명화하고 되돌릴 수 없으므로, 무엇이 처리되는지 먼저 알려 드립니다. 함께, 관리자가 상태만 바꿔 탈퇴시킨 경우에도 회원이 직접 탈퇴한 것과 동일한 처리(익명화·연계 데이터 정리)가 이뤄지도록 통일했습니다.
+
+### Changed
+
+- 공개 자산을 외부 주소(CDN)로 서빙할 때, 그 주소로 나가는 요청에는 로그인 토큰을 함께 보내지 않습니다 — 공개 자산은 인증이 필요 없고, 토큰이 외부 서비스로 전달되지 않아야 하기 때문입니다. 사이트 자신의 주소로 가는 요청은 종전과 동일합니다.
+- 확장 개발자용: 확장 캐시 계약 인터페이스에 카테고리별 스토리지 접근이 추가되었습니다. 코어가 제공하는 확장 베이스 클래스·서비스 프로바이더를 상속하는 확장은 수정 없이 호환되지만, 이 계약을 직접 구현하는 확장은 새 메서드를 구현해야 합니다 (번들 확장은 모두 반영 완료 — 최소 요구 코어 버전 7.0.7).
+- 예약 작업의 실행 시각이 환경설정의 시간대를 기준으로 해석되도록 바꿨습니다. 종전에는 세계표준시 기준이어서 '새벽 4시'로 등록해도 국내 기준 낮에 실행됐습니다. 이번 변경으로 새로 추가된 자동 정리 작업은 물론, 기존 사이트맵 자동 생성·GeoIP 갱신·확장이 제공하는 예약 작업, 관리자가 직접 등록한 예약 작업까지 모두 같은 기준을 따릅니다. **시각을 지정해 둔 예약은 실제 실행 시각이 이동하므로 확인이 필요합니다.**
+- 시스템 요구사항 문서를 실제 검증 기준에 맞게 정비했습니다. 지원 브라우저 항목에 검증 방식을 명시하고(자동 테스트는 Chromium 기준이며, Firefox·Safari 는 프론트엔드 의존성의 호환 범위를 기준으로 지원합니다), PHP 확장을 필수와 기능별 선택으로 구분했으며, 설치 프로그램이 자동으로 검사하는 항목과 운영자가 직접 확인해야 하는 항목을 구분하는 절을 새로 두었습니다. "요구사항" 이라고 적힌 항목이 모두 설치 단계에서 검사되는 것은 아니라는 점이 이제 문서에 드러납니다. (#95 @glitter-gim 님께서 제보해주셨습니다.)
+- 문서 사이에 어긋나 있던 수치와 표기를 정정했습니다 — 디스크 용량 기준(설치 검사 기준 500MB), PHP 확장 개수, 지원 운영체제에 Windows 개발 환경 추가, 데이터베이스 표기에 MariaDB 병기, 한국어 README 의 시스템 요구사항 항목 보완, 그리고 데이터베이스 접두어 길이 제한·collation 변경 가능 여부처럼 실제로는 동작하지만 문서에 없던 조건의 추가.
+- 확장 개발자용: 배포본에 함께 들어가는 브라우저 테스트 안내 문서가 실제 디렉토리 구성 및 실행 스크립트와 어긋나 있던 부분을 정정했습니다.
+
+### Fixed
+
+- 데이터베이스 테이블 접두어를 기본값(`g7_`)이 아닌 값으로 설치한 사이트에서, 7.0.6 업그레이드의 활동 로그 색인 교체가 옛 색인을 지우지 못하고 남겨 두던 문제를 수정했습니다. 남은 옛 색인은 조회 이득 없이 기록 쓰기 비용만 늘리므로, 이번 업그레이드에서 자동으로 정리됩니다.
+- FULLTEXT 인덱스가 없는 테이블을 검색하면 오류 대신 부분일치 검색으로 자동 전환되고, 그 사실이 기록으로 남습니다. 이전에는 오류가 화면에 드러나지 않아 "검색 결과 0건" 으로만 보였습니다. (#103 @Tuwasduliebst 님께서 제보해주셨습니다.)
+- 통합검색에서 일부 항목의 검색이 실패하면 "검색 결과 없음" 이 아니라 오류 안내로 구분해 표시되도록, 항목별 실패 여부를 응답에 실어 내립니다. 실패 원인은 서버 기록에 상세히 남습니다. (#103 @Tuwasduliebst 님께서 제보해주셨습니다.)
+- 언어팩 업데이트 확인이 특정 조건(요청에 페이지 이동 파라미터가 실려 있는 경우)에서 아무 팩도 확인하지 않고 끝나던 문제를 수정했습니다. (#102 @Tuwasduliebst 님께서 제보해주셨습니다.)
+- 검색엔진 플러그인을 선택해 저장한 뒤 그 플러그인을 삭제하면 사이트 검색이 오류로 멈추던 문제를 수정했습니다. 이제 다른 드라이버 설정과 동일하게 기본 검색엔진으로 자동 복귀합니다.
+- 설정을 항목 단위로 저장할 때 전체 저장과 다른 처리를 거치던 문제를 수정했습니다. 자산 주소 방식을 바꾸면 SEO 미리 생성 캐시가, 드라이버를 바꾸면 백그라운드 작업이 각각 갱신되지 않았습니다. SEO 설정도 항목 단위 저장에서 캐시가 정리되지 않아 검색엔진에 예전 정보가 남았습니다. (#114 @Tuwasduliebst 님께서 제보해주셨습니다.)
+- 모듈 환경설정(쇼핑몰·게시판)을 저장해도 SEO 미리 생성 캐시가 갱신되지 않던 문제를 수정했습니다. 함께, 모듈 설정 변경이 활동 로그에 기록됩니다.
+- 설정을 항목 단위로 저장할 때 한 번 입력한 값을 빈 칸으로 되돌릴 수 없던 문제를 수정했습니다. 켜기/끄기 설정과 숫자 설정이 문자열로 저장되던 문제도 함께 고쳤으며, 해당 설정이 받을 수 없는 값은 저장 단계에서 안내와 함께 거부됩니다.
+- 삭제된 본인인증 플러그인의 식별자가 정책 조회 응답과 공개 페이지에 그대로 노출되던 문제를 수정했습니다. 조회 응답은 실제 사용 가능한 인증 수단으로 해석해 내려주고, 공개 페이지에는 이 값을 싣지 않습니다.
+- 관리자 화면 이동 시 템플릿 목록을 불필요하게 반복 검색하던 문제를 수정했습니다.
+- 언어팩 관리(설치·활성화·삭제·업데이트·캐시 갱신)가 실패했을 때 응답에 내부 오류 원문이 그대로 실리던 문제를 수정했습니다. 설치 전 파일 검증 실패도 마찬가지로 안내 문구만 표시되며, 상세 내용은 디버그 모드에서만 확인할 수 있습니다.
+- 관리자가 설정을 저장해도 백그라운드 작업(큐 워커 등)에는 이전 설정이 계속 적용되던 문제를 수정했습니다. 저장 즉시 실행 중인 프로세스에도 새 값이 반영됩니다. 설정 백업 복원과 플러그인 설정 초기화도 같은 문제가 있어 함께 수정했습니다. (#109 @Tuwasduliebst 님께서 제보해주셨습니다.)
+- 만료된 로그인 토큰 등 수명이 지난 데이터가 정리되지 않고 계속 쌓이던 문제를 수정했습니다. 만료 토큰·비밀번호 재설정 기록·오래된 알림·실패한 작업 기록·SEO 통계·예약 작업 이력·본인인증 이력·활동 로그·알림 발송 이력·확장 화면 구성에 쓰인 병합 파일의 구버전이 매일 자동 정리됩니다. 기존에 쌓여 있던 보존 기간 초과 데이터는 첫 정리 때 한 번에 정리되며, 양이 많아도 나눠서 지우므로 정리 중에 사이트가 멈추지 않습니다. (#110 @Tuwasduliebst, #120 @glitter-gim 님께서 제보해주셨습니다.)
+- 회원 탈퇴가 마지막 단계에서 실패하면 약관 동의 이력·프로필 이미지·로그인 세션만 사라지고 계정은 남는 문제를 수정했습니다. 이제 탈퇴는 전부 성공하거나 전부 취소되며, 같은 이메일로 재가입한 회원이 같은 날 다시 탈퇴해도 실패하지 않습니다. 관리자·운영자 계정의 탈퇴 시도는 서버 오류가 아니라 안내 문구로 거절됩니다. (#112 @Tuwasduliebst 님께서 제보해주셨습니다.)
+- 사이트 로고를 교체해도 이전 로고가 설정에 다시 실려, 교체할 때마다 파일과 기록이 함께 쌓이던 문제를 수정했습니다. 화면에서 뺀 로고는 저장이 완료된 뒤 실제로 삭제되며, 저장에 실패하면 파일도 그대로 남습니다.
+- 관리자 API 의 데이터베이스 백업 요청이 항상 서버 오류로 끝나고, 그 응답에 내부 구현 정보가 그대로 실려 나가던 문제를 수정했습니다. 이 기능은 아직 제공하지 않으므로 "제공하지 않는 기능" 임을 알리는 응답으로 답합니다. 설정 파일 백업은 종전대로 사용할 수 있습니다.
+- 플러그인이 선언한 관리자 메뉴가 설치·업데이트 시 자동으로 만들어지도록 수정했습니다. 종전에는 플러그인이 활성화 처리에서 직접 만든 경우에만 메뉴가 생겨서, 이미 사용 중인 사이트가 플러그인을 업데이트해 새 화면을 받아도 메뉴가 나타나지 않고 주소를 직접 입력해야만 닿을 수 있었습니다. 이제 모듈과 동일하게 처리됩니다.
+- 회원가입 등 일반 화면의 비밀번호 오류 문구가 'SMTP 비밀번호'로 표시되던 문제를 수정했습니다. 같은 이유로 어긋나 있던 '기본 언어'·'기본 통화'·'사용자 ID 목록'·'알림 채널' 등의 문구도 화면에 맞게 정리했습니다. (#113 @Tuwasduliebst 님께서 제보해주셨습니다.)
+- 회원 삭제·회원 정보 수정·회원가입·역할 삭제·비밀번호 재설정·첨부 파일 삭제·메뉴 삭제·예약 작업 삭제가 중간에 실패하면 일부만 처리된 상태로 남던 문제를 수정했습니다. 회원 정보 수정은 프로필 변경·로그인 세션 정리·역할 변경이 함께 처리되므로, 역할 변경에서 실패하면 이름만 바뀌고 로그인이 끊긴 상태로 남았습니다. 이제 각 작업은 전부 성공하거나 전부 취소되며, 파일 삭제는 데이터 정리가 확정된 뒤에 수행됩니다.
+- 페이지 모듈의 첨부 파일 설정(개수·용량·형식)이 저장해도 반영되지 않던 문제를 수정했습니다.
+- 회원 목록에서 여러 명을 골라 일괄 탈퇴할 때, 탈퇴할 수 없는 계정(관리자 등)이 섞여 있으면 그 건이 조용히 건너뛰어지던 문제를 수정했습니다. 이제 처리된 인원·처리하지 못한 인원과 그 사유가 응답에 함께 담깁니다. (#112 @Tuwasduliebst 님께서 제보해주셨습니다.)
+- 회원 일괄 상태 변경의 결과 안내 문구에 처리 인원수가 채워지지 않고 자리표시 원문이 그대로 표시되던 문제를 수정했습니다.
+- 파일 스토리지에서 S3 를 선택해 저장해도 실제 파일 저장이 동작하지 않던 문제를 수정했습니다. S3 구동에 필요한 스토리지 어댑터가 빠져 있었고, 연결 테스트는 통과해도 실제 저장 경로는 동작하지 않았습니다. 이제 어댑터가 기본 포함되고, 연결 테스트도 실제 연결 경로와 같은 설정(엔드포인트·Path-style 포함)을 사용합니다. (#99 @lyg-kaban 님께서 제보해주셨습니다.)
+- 파일 스토리지를 S3 로 저장해도 첨부 파일 업로드는 계속 서버 로컬 디스크에 저장되던 문제를 수정했습니다. 이제 S3 저장 시 새 첨부 파일이 S3 로 저장되며, 기존 파일은 종전 위치에서 계속 서빙됩니다. 서버 환경변수(`ATTACHMENT_DISK`)로 저장 위치를 명시한 경우에는 그 값이 우선합니다. (#99 @lyg-kaban 님께서 제보해주셨습니다.)
+- phpredis PHP 확장이 없는 서버에서 캐시·세션·큐 드라이버로 Redis 를 선택하면 사이트 전체가 열리지 않던 문제를 예방했습니다 — Redis 클라이언트 라이브러리(predis)가 기본 포함되어 확장 없이도 동작합니다.
+- 웹소켓 연결 테스트가 브라우저 접속 주소만 검사해, 테스트는 성공해도 서버 발송(알림 등)은 실패할 수 있던 문제를 수정했습니다 — 이제 서버 발송용 주소도 함께 검사하고, 실패 시 어느 쪽 주소가 문제인지 구분해 알려줍니다.
+- 드라이버 설정의 S3 URL 이 너무 길 때 표시되는 영어 안내 문구가 실제 허용 길이(500자)와 다르게 255자로 안내되던 문제를 수정했습니다.
+- 확인 질문이 있는 Artisan 명령(확장 설치·삭제·업데이트, 코어 업데이트, 검색 인덱스 재생성 등)을 터미널이 아닌 곳에서 실행하면 아무 반응 없이 멈춰 있던 문제를 수정했습니다. 예약 작업·배포 스크립트·CI 처럼 사람이 답할 수 없는 환경에서는 질문이 화면에 나오지도 않은 채 응답을 기다렸기 때문에, 명령이 실패한 것도 아니고 진행 중인 것도 아닌 상태로 남아 "명령이 몹시 느리다" 로만 보였습니다. 이제 그런 환경에서는 질문을 건너뛰고 기본 동작을 따릅니다 — 삭제·업데이트처럼 되돌리기 어려운 명령의 기본 동작은 "중단" 이므로, 확인 없이 수행되는 일은 없습니다. 그대로 진행하려면 종전처럼 `--no-interaction` 이나 `--force` 를 붙이면 됩니다.
+- Windows 에서 확장(모듈·플러그인·템플릿) 업데이트가 "디렉토리 이동 실패" 로 중단되던 문제를 해소했습니다. Windows 는 편집기·개발 도구·파일 감시 프로그램이 폴더를 보고 있기만 해도 폴더 이름 바꾸기를 차단하므로, 폴더를 통째로 이동하는 방식으로는 실패를 피할 수 없었습니다. 이제 이동이 차단되면 파일 단위 교체로 자동 전환해 어떤 프로그램도 종료하지 않고 업데이트를 완료합니다. 잠근 프로그램을 찾아 강제 종료하던 이전 동작은 제거했습니다 — 사용 중인 편집기나 개발 도구가 예고 없이 종료되는 부작용이 있었고, 폴더를 감시만 하는 프로그램은 찾아내지도 못했습니다. 백업 복원에도 같은 방식이 적용되며, 실패한 업데이트가 남긴 임시 폴더는 다음 업데이트 때 자동으로 정리됩니다.
+- 빌드 산출물이 존재하지 않는 소스맵 파일을 참조해 브라우저 개발자 도구 사용 시 불필요한 404 요청이 발생하던 문제를 수정했습니다.
+- 템플릿을 업데이트하거나 템플릿 캐시를 삭제해도 공개 템플릿 설정(config.json)이 최대 1시간 동안 이전 내용으로 응답되던 문제를 수정했습니다. 비활성화·삭제한 템플릿의 설정이 같은 시간 동안 계속 조회되던 문제와, `template:cache-clear` 명령이 실제로는 대부분의 캐시를 지우지 못하면서 삭제 완료로 보고하던 문제도 함께 고쳤습니다. 모듈·플러그인의 캐시 삭제 명령도 실재하는 캐시를 지우도록 정비했습니다. (#119 @glitter-gim 님께서 제보해주셨습니다.)
+- 템플릿 업데이트로 컴포넌트 정의(components.json)가 바뀌어도 레이아웃 저장 검증이 최대 1시간 동안 이전 정의를 기준으로 동작하던 문제와, 템플릿 상태 변경 후에도 레이아웃 편집기의 병합 캐시 일부가 남아 편집기가 이전 내용을 받을 수 있던 문제를 수정했습니다.
+- 캐시 버전 조회 주소(`?v=`)를 생략하고 공개 라우트·다국어·레이아웃 API 를 직접 호출하는 경우(외부 연동·봇 등), 그 응답이 어떤 갱신 경로로도 무효화되지 않는 별도 캐시에 남던 문제를 수정했습니다. 브라우저를 통한 일반 사용에는 영향이 없습니다.
+- 확장·코어 업데이트가 중단되며 남은 임시 폴더와 오래된 백업본, 언어팩 설치 임시 파일이 정리되지 않고 계속 쌓이던 문제를 수정했습니다. 사흘이 지난 임시 산출물과 30일이 지난 백업본(최신 1개는 보존)이 매일 자동 정리됩니다.
+- 개발 도구의 브라우저 콘솔 로그 파일이 하나의 파일에 무한히 쌓이던 문제를 수정했습니다. 이제 날짜별 파일로 나뉘어 7일간 보관됩니다.
+- 예약 작업 저장 화면에서 설치된 확장이 제공하는 Artisan 명령이 "예약 실행이 허용된 명령이 아닙니다" 로 거부되던 문제를 수정했습니다. 터미널에서의 검증은 통과하는 명령이 관리자 화면 저장에서만 거부되었습니다. 이 기능은 현재 메뉴에 노출되지 않아 실제 사용 경로가 없습니다.
+- 검색엔진 노출용 페이지 제목에서 타이틀 접미사가 제목과 붙어 표시되던 문제를 수정했습니다. 관리자 화면 안내대로 접미사를 공백으로 시작하게 입력해도 저장 시 선행 공백이 제거되어 "제목| 사이트명" 처럼 접착되었고, 페이지 제목이 없는 화면에서는 "| 사이트명" 처럼 구분자가 매달려 표시되었습니다. 이제 제목이 있으면 공백을 복원해 잇고, 제목이 없으면 구분자를 떼고 사이트명만 표시합니다.
+
+## [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
+
+- 확장 기능이 화면을 그릴 때, 방문자의 접속 기기 종류처럼 요청마다 달라지는 정보를 화면 구성 데이터에 함께 실어 보낼 수 있는 통로를 마련했습니다. 쇼핑몰의 애플페이가 iOS 기기에서만 표시되도록 하는 데 이 통로가 쓰입니다.
+- 확장 기능이 특정 요청 경로에만 자기 처리 로직을 끼워 넣을 수 있는 표준 연결 방식을 마련했습니다. 각 확장은 자기가 개입할 대상 경로를 명시해 선언하고, 코어가 요청이 들어올 때 대상에 해당하는 확장 로직만 골라 실행합니다. 이를 통해 쿠키 동의 처리나 결제 입금통보의 발신 서버 확인 같은 기능이 필요한 경로에서만 정확히 동작하도록 정리했습니다.
+
+### Fixed
+
+- 검색엔진 노출용으로 만들어 내보내는 페이지에 실제로 존재하지 않는 스타일 파일 주소(`/build/assets/app.css`)가 포함되어, 브라우저 콘솔에 404 오류가 남던 문제를 수정했습니다. 이 주소는 화면 표시에 쓰이지 않는 파일을 가리키던 불필요한 참조였으며, 검색엔진 노출용 페이지의 스타일은 템플릿이 제공하는 파일이 그대로 담당하므로 화면에는 영향이 없었습니다. 이제 이 참조를 제거해 오류가 발생하지 않습니다. (#64 @bigmsg 님께서 제보해주셨습니다.)
+- 코어 업데이트를 `--prune` 옵션으로 실행하면 업로드 파일 연결(`public/storage`)이 삭제되어, 그동안 올린 이미지·첨부 파일이 모두 404로 열리지 않던 문제를 수정했습니다. 이제 `--prune` 업데이트가 이 연결을 지우지 않고 보존하며, 혹시 끊어져 있더라도 업데이트가 끝나는 시점에 자동으로 다시 이어 붙여 파일이 정상적으로 표시됩니다. 관리자 권한으로 업데이트를 실행할 때 이 연결을 다시 이어 붙이면서 소유자가 관리자 계정으로 바뀌던 문제도 함께 바로잡아, 원래 계정 소유가 그대로 유지됩니다. (#43 @bigmsg 님께서 제보해주셨습니다.)
+
+## [7.0.4] - 2026-07-14
+
+### Security
+
+- 서버가 외부 주소를 대신 호출하는 기능들에서, 사내 서버나 클라우드 관리 주소처럼 외부에 공개되지 않은 내부 주소를 호출 대상으로 지정할 수 없도록 차단했습니다. 언어팩을 주소로 내려받을 때, 예약 작업으로 주소를 호출할 때, 쇼핑몰 배송비를 외부 계산 서버로 문의할 때가 해당합니다. 사내 서버를 주기적으로 호출하는 등 내부 주소가 꼭 필요한 운영 환경을 위해, 환경설정 > 보안에 "내부 네트워크 주소 호출 허용" 항목을 새로 추가했습니다. 이 항목은 기본적으로 꺼져 있습니다.
+- 주소를 검사할 때 앞부분만 맞으면 통과시키던 방식을 실제 주소가 정확히 일치하는지 확인하도록 바로잡았습니다. 이전에는 신뢰하는 주소를 앞에 붙인 가짜 주소가 검사를 통과할 수 있었습니다. 본인인증 연동과 언어팩 업데이트 확인에 적용됩니다. (KISA 측에서 제보해주셨습니다 — KVE-2026-1546)
+- 배포본에 원본 소스코드가 그대로 담긴 파일(소스맵)이 함께 포함되어, 누구나 주소만 알면 내려받아 볼 수 있던 문제를 차단했습니다. 이제 배포용으로 빌드하면 이 파일이 아예 만들어지지 않으며, 기존에 포함되어 있던 파일도 모두 제거했습니다. 아울러 이 파일이 서버에 남아 있더라도 웹으로는 내려받을 수 없도록 막았습니다. 내 컴퓨터에서 개발용으로 빌드할 때는 디버깅에 필요하므로 이전과 동일하게 생성됩니다. (#72 @glitter-gim 님께서 건의해주셨습니다.)
+- 아직 공개하지 않은 예약 작업 기능에서, 서버 명령을 실행하는 두 유형(쉘 명령·Artisan 명령)에 대해 향후 정식 공개에 대비한 실행 제한 장치를 미리 마련했습니다. 쉘 명령 예약은 기본적으로 완전히 차단되며 서버 관리자가 실행 파일을 명시적으로 등록해야만 사용할 수 있고(관리자 화면에서는 넓힐 수 없습니다), Artisan 명령 예약도 데이터를 지우거나 임의 코드를 실행할 수 있는 위험한 명령은 거부됩니다. 이 기능은 현재 메뉴에 노출되지 않아 실제 사용 경로가 없습니다. (KISA 측에서 제보해주셨습니다 — KVE-2026-1567)
+
+### Fixed
+
+- 설치 과정에서 임시로 만들어지는 파일에 관리자 비밀번호가 그대로 남을 수 있던 문제를 수정했습니다. 설치가 정상적으로 끝나면 이 파일은 지워지지만, 설치를 중간에 그만두거나 마지막 정리가 이뤄지지 않은 경우에는 남아 있을 수 있었습니다. 이제 비밀번호는 이 파일에 아예 기록되지 않으며, 설치에 꼭 필요한 동안에만 접근이 제한된 별도 파일에 보관했다가 관리자 계정이 만들어지는 즉시 지워집니다. 이미 설치를 마친 사이트도 업데이트하면 남아 있던 파일이 자동으로 정리됩니다. (sir.kr 커뮤니티의 코ppp 님께서 제보해주셨습니다.)
+- 화면 편집기를 작은 화면에서 열면 상단 도구 모음의 버튼 글자가 세로로 쪼개지는 등 화면이 찌그러지던 문제를 수정했습니다. 화면 편집기는 왼쪽 화면 목록과 미리보기 화면을 나란히 놓고 쓰는 도구라 넓은 화면이 필요합니다. 이제 창이 좁아도 편집기를 억지로 우겨넣지 않고 원래 크기를 유지하며, 모자란 만큼은 가로 스크롤로 넘겨 보면 됩니다.
+- 모바일에서 새로고침을 연속으로 눌렀을 때 간헐적으로 "초기화 실패" 또는 "페이지 로딩 실패" 화면이 뜨던 문제를 수정했습니다. 화면을 그리는 데 필요한 요청 하나가 회선 사정으로 잠깐 끊기면 그것만으로 페이지 전체가 뜨지 않았습니다. 이제 이런 일시적인 끊김은 자동으로 다시 시도해 복구하므로, 대부분의 경우 사용자는 아무것도 느끼지 못한 채 화면이 정상적으로 열립니다.
+- 화면 구성에 필요한 스크립트를 끝내 불러오지 못한 경우, 아무 안내 없이 빈 화면만 남거나 영문 오류 문구가 그대로 노출되던 문제를 수정했습니다. 이제 무슨 일이 있었는지 알려주는 안내와 새로고침 버튼이 표시됩니다. 관리자 화면에도 동일하게 적용됩니다.
+- 쇼핑몰 등 확장 기능을 불러오지 못한 상태에서 화면이 5초가량 빈 채로 멈춰 있다가 뜨던 문제를 수정했습니다. 이제 지체 없이 화면이 열리고, 불러오지 못한 확장 기능만 조용히 빠집니다.
+- 외부 라이브러리를 쓰는 확장의 버전을 올린 뒤 그 확장을 업데이트하면 "번들 파일의 무결성 검증에 실패했습니다"라는 오류로 업데이트가 막히던 문제를 수정했습니다. 오류를 풀려면 업데이트가 필요한데 그 업데이트 자체가 막혀 빠져나올 수 없는 상태였습니다. 아울러 확장 버전만 올린 경우에도 번들 재빌드가 필요함을 `--check` 점검이 올바르게 알려주도록 바로잡았습니다. (이미 배포된 확장을 내려받아 쓰는 환경에는 영향이 없으며, 확장을 직접 개발·수정하는 경우에 해당합니다.)
+- Windows 개발 환경에서 코어 의존성 번들을 다시 만들 때, 마지막 정리 단계에서 진행이 멈춘 채 끝나지 않던 문제를 수정했습니다. 이제 번들 빌드가 정상적으로 완료됩니다. 아울러 빌드가 중간에 실패하더라도 기존 번들 파일이 손상되지 않도록 새 결과가 완성된 뒤에만 교체하도록 개선했습니다. (확장을 직접 개발·수정하는 환경에 해당하며, 배포본을 내려받아 쓰는 환경에는 영향이 없습니다.)
+- 확장에 외부 라이브러리를 새로 추가한 뒤 번들을 만들면, 새로 추가한 라이브러리가 번들에 담기지 않은 채로 만들어지던 문제를 수정했습니다. 검증은 통과하지만 실제 파일이 빠져 있어 설치 후 실행 중에 오류가 나던 상태였습니다. 이제 새로 추가한 라이브러리가 번들에 정상적으로 포함됩니다. (확장을 직접 개발·수정하는 환경에 해당합니다.)
+
+## [7.0.3] - 2026-07-10
+
+### Fixed
+
+- 화면 구성 파일이 목록을 만들어 내는 과정에서 다국어 이름을 골라 쓸 때, 사이트를 어떤 언어로 보고 있든 항상 한국어 이름이 선택되던 문제를 수정했습니다. 이제 보고 있는 언어의 이름이 표시됩니다. 헤더의 배송국가 선택처럼 화면이 처음 열릴 때 목록을 만들어 두는 곳이 여기에 해당합니다.
+- 메뉴를 눌러 화면을 이동했을 때, 필요한 정보를 여러 갈래로 나눠 받아오는 화면에서 먼저 도착한 정보가 뒤늦게 도착한 정보에 덮여 사라지는 경우가 있었습니다. 그 탓에 목록이 있어야 할 자리가 간헐적으로 비어 보이고 새로고침하면 정상으로 돌아오곤 했습니다. 이제 어느 정보가 먼저 도착하든 모두 반영됩니다. 이커머스 환경설정의 배송설정 탭에서 배송가능 국가 목록이 비어 보이던 것이 여기에 해당합니다.
+- 이미 설치를 마친 환경의 설정 파일(`.env`)을 새 서버로 복사해, 데이터베이스가 아직 비어 있는 상태에서 설치를 이어가려 할 때 `php artisan migrate`로 테이블을 만들기도 전에 부팅 단계에서 오류가 나며 중단되던 문제를 수정했습니다. 이제 데이터베이스 작업 명령이 실행되는 동안에는 테이블 존재 여부를 실제로 확인하므로, 기존 서버의 설정을 재사용하는 신규 배포에서도 설치가 정상적으로 진행됩니다. (#41 @GyusoonKim 님께서 제보해주셨습니다.)
+- 활동 로그 기록에 실패했을 때 그 기록을 유발한 요청까지 함께 실패하던 문제를 수정했습니다. 결제 입금통보 같은 외부 콜백이 활동 로그 문제로 오류를 반환하는 일이 없어집니다.
+
+## [7.0.2] - 2026-07-08
+
+### Added
+
+- 설치된 모듈·플러그인이 늘어날수록 화면마다 개별로 내려받던 확장 스크립트·스타일 요청을 종류별로 하나로 묶어 내려받도록 개선해, 확장이 많은 사이트의 초기 로딩 요청 수를 크게 줄였습니다. 확장을 설치·활성화·비활성화하면 묶음이 자동으로 다시 만들어져 항상 현재 활성 상태와 일치합니다.
+
+### Changed
+
+- 코어 업데이트가 파일을 반영하는 기본 방식을 "새 버전이 실제로 추가·변경한 파일만 반영"으로 바꿔, 업데이트로 인한 사고 가능성을 크게 줄였습니다. 이제 코어가 건드리지 않은 파일은 그대로 두므로, `public/.htaccess` 에 직접 넣은 설정이나 사용자가 추가해 둔 파일이 업데이트 과정에서 사라지지 않습니다. 새 버전에 함께 담긴 기본 제공 확장(모듈·플러그인·템플릿·언어팩)의 갱신 파일은 이 과정에서도 정상적으로 최신 내용으로 반영되며, 사용자가 확장 폴더에 직접 추가해 둔 항목은 그대로 보존됩니다. 기존처럼 새 버전에서 제거된 파일 정리까지 포함한 전체 덮어쓰기를 원하면 `--prune` 옵션으로 업데이트하세요. (#64 @bigmsg 님께서 제보해주셨습니다.)
+- 화면·데이터를 내려받을 때의 전송 용량을 줄여 초기 로딩과 페이지 이동 속도를 개선했습니다.
+  - 모듈·플러그인의 묶음 스크립트·스타일이 지금까지 압축 없이 전송되던 것을 압축 전송하도록 바꿔, 확장이 많은 사이트에서 첫 화면에 받는 용량을 크게 줄였습니다.
+  - 한글 등 다국어 텍스트가 응답에 불필요하게 부풀려 담기던 것을 원래 형태 그대로 담도록 바꿔, 특히 다국어 번역 데이터의 전송 용량을 줄였습니다.
+  - 화면을 그리는 데 쓰이지 않는 개발용 설명 주석을 화면 정보 응답에서 빼도록 해 응답 용량을 추가로 줄였습니다.
+
+### Fixed
+
+- 코어 업데이트 시 레이아웃 편집기·개발자 진단도구 번들의 빌드 설정 파일이 갱신 대상에서 누락되던 문제를 수정했습니다. 이제 코어를 업데이트하면 이 파일들도 최신 내용으로 반영됩니다.
+- 설치 마법사에서 Vendor 설치 방식을 "Composer 실행"으로 선택해 설치할 때, 일부 Windows 환경에서 Composer 설치 로그의 문자 인코딩이 어긋나면 진행 상태 응답이 비어 진행 상황이 표시되지 않고 오류가 반복될 수 있던 문제를 보완했습니다. 어떤 문자가 섞이더라도 진행 로그가 항상 정상적으로 전달되도록 처리했습니다. (#62 @kitrio 님께서 제보해주셨습니다.)
+- 설치 마법사의 "설치 환경 확인" 단계에서, storage 폴더 하위에 파일이 많이 쌓인 환경일수록 요구사항 검사가 오래 걸리던 문제를 개선했습니다. 폴더 쓰기 권한 검사가 불필요하게 깊은 하위까지 훑던 것을 필요한 범위로 제한해 이 단계가 즉시 완료되도록 했습니다.
+- 설치 시 "읽기 전용 데이터베이스(Read DB)를 사용하지 않음"으로 선택했는데도, 읽기 전용 DB 접속 정보를 확인하려다 설치 마지막 단계에서 실패하던 문제를 수정했습니다. 이제 읽기 전용 DB를 사용하지 않으면 쓰기 DB 정보만으로 설치가 정상 완료됩니다. 아울러 설치 이후에도 읽기 전용 DB 접속 정보를 비워 두면 조회 연결이 자동으로 쓰기 DB로 대체되도록 하여, 별도의 읽기 전용 DB 없이도 안정적으로 동작합니다. (#63 @kitrio 님께서 제보해주셨습니다.)
+
 ## [7.0.1] - 2026-07-03

 ### Changed
@@ -1314,7 +1711,6 @@ abort 발생 시 운영자에게 수동 재개 명령 (`php artisan core:execute
 - 휴대폰 인증, 아이핀 인증 등 본인인증 기능 제공
 - 사용자 관리 화면 레이아웃 확장 (본인인증 상세/폼)
 - 역할 기반 접근 제어 (본인인증 관리자)
- 다국어 지원 (ko, en)

 #### 템플릿: sirsoft-admin_basic (관리자)

@@ -1350,7 +1746,6 @@ abort 발생 시 운영자에게 수동 재개 명령 (`php artisan core:execute
 - CMS 페이지 표시 화면
 - 에러 페이지 (403, 404, 500, 503)
 - 점검 모드(maintenance) 전용 페이지
- 반응형 레이아웃 (데스크톱/태블릿/모바일)

 #### 다국어 시스템 (i18n)

@@ -8,7 +8,7 @@

 | 항목 | 요구사항 |
 |------|---------|
-| **PHP** | 8.2 이상 (필수 확장 30개 포함) |
+| **PHP** | 8.2 이상 (필수 확장 16개 포함 — 기능별 선택 확장은 별도) |
 | **데이터베이스** | MySQL 8.0+ 또는 MariaDB 10.3+ (utf8mb4) |
 | **Composer** | 2.x |
 | **Redis** | 6.0+ (프로덕션 권장, 선택) |
@@ -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.1 g7
+# (필요 시) mv g7-7.0.9 g7

 # ZIP 파일 정리 (선택)
 rm g7-release.zip
@@ -0,0 +1,577 @@
+<p align="center"><a href="README.md">English</a> | 한국어</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/그누보드7-Gnuboard7-000000?style=for-the-badge&labelColor=0066FF&logoColor=white" height="200" alt="그누보드7 (Gnuboard7)">
+</p>
+
+<p align="center">
+  <strong>모던 아키텍처로 다시 태어난 대한민국 대표 오픈소스 CMS</strong><br>
+  A modern, extensible CMS platform built with Laravel + React
+</p>
+
+<p align="center">
+  <a href="#"><img src="https://img.shields.io/badge/version-7.0.9-blue" alt="Version"></a>
+  <a href="#"><img src="https://img.shields.io/badge/PHP-8.2%2B-777BB4?logo=php&logoColor=white" alt="PHP"></a>
+  <a href="#"><img src="https://img.shields.io/badge/Laravel-12.x-FF2D20?logo=laravel&logoColor=white" alt="Laravel"></a>
+  <a href="#"><img src="https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=black" alt="React"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+  <a href="#"><img src="https://img.shields.io/badge/status-Stable-brightgreen" alt="Status"></a>
+</p>
+
+<p align="center">
+  <a href="https://g7.gnuboard.com"><strong>데모 사이트</strong></a> ·
+  <a href="https://g7.gnuboard.com/admin"><strong>관리자 데모</strong></a>
+</p>
+
+---
+
+[소개](#그누보드7-소개) · [주요 기능](#주요-기능) · [기술 스택](#기술-스택) · [아키텍처](#아키텍처) · [빠른 시작](#빠른-시작) · [기본 제공 확장](#기본-제공-확장) · [비즈니스 모델](#비즈니스-모델) · [기존 사용자](#기존-그누보드-사용자) · [문서](#문서) · [기여하기](#기여하기) · [만든 사람들](#만든-사람들) · [커뮤니티](#커뮤니티) · [변경 기록](#변경-기록) · [라이선스](#라이선스)
+
+---
+
+## 그누보드7 소개
+
+**그누보드7 (Gnuboard7)** 은 23년간 대한민국에서 가장 널리 사용된 오픈소스 CMS인 그누보드를, 현대적 기술 스택으로 **완전히 새로 설계**한 차세대 웹 플랫폼입니다.
+
+Laravel과 React를 기반으로, 보안부터 아키텍처까지 처음부터 다시 만들었습니다.
+
+- **JSON 레이아웃 엔진**: React를 몰라도 JSON만으로 React 기반 UI를 선언적으로 정의. 모듈/플러그인이 프론트엔드 빌드 없이 JSON만으로 UI를 동적으로 주입/확장. 고도화된 UI가 필요한 경우 커스텀 React 컴포넌트를 개발하여 등록 가능
+- **하나의 플랫폼, 다양한 비즈니스**: 커뮤니티, 쇼핑몰, 구독, 예약 — 비즈니스 모델에 맞게 확장
+- **정교한 권한 관리**: 역할(Role) + 권한(Permission) + 스코프(Scope) 3단계 접근 제어로, 서비스 규모가 커져도 통제력 유지
+- **글로벌 레디**: 다국어(i18n) 네이티브 지원, 로케일 기반 UI, 다중 통화 대응
+- **확장 시스템**: 모듈 + 플러그인 + 템플릿 3중 구조로 코어 수정 없이 기능 확장
+
+---
+
+## 주요 기능
+
+현대적인 웹 플랫폼에 필요한 핵심 기능을 갖추었습니다.
+
+| 영역 | 설명 |
+|------|------|
+| **모듈 아키텍처** | 모듈 + 플러그인 + 템플릿 3중 확장 구조. 코어 수정 없이 독립적 모듈(게시판, 커머스 등) 개발이 가능합니다. Hook 기반 기능 주입으로 Service-Repository 패턴의 명확한 계층 분리를 유지합니다 |
+| **언어팩 시스템** | 새 언어를 코어 수정 없이 ZIP 또는 GitHub URL 로 설치할 수 있습니다. 일본어 등 공식 번들 언어팩을 즉시 사용할 수 있고, 운영자가 직접 수정한 라벨은 언어팩이 덮어쓰지 않도록 sub-key 단위로 보존합니다. 모듈/플러그인/템플릿 단위로 별도 적용 가능 |
+| **현지화** | 백엔드부터 프론트엔드까지 일관된 다국어 개발 환경을 제공합니다. 활성 언어팩이 알림 채널 라벨, Provider/Registry 페이로드, 환경설정 카탈로그(결제수단·통화·배송 가능 국가)까지 자동 보강되며, 모듈/플러그인이 자기 도메인 라벨을 자기 영역에서 자기설명하도록 활동 로그·메시지 영역도 분리되어 있습니다 |
+| **해외 결제** | 로컬 비즈니스를 넘어 글로벌 커머스로 도약하기 위한 기반을 제공합니다. 결제 연동은 동일한 Extension Point 패턴으로 붙일 수 있으며, 해외 결제 수단은 별도 플러그인으로 제공됩니다 |
+| **권한 제어** | 역할별 메뉴와 기능, 데이터 범위까지 제어할 수 있습니다. 역할(Role) + 권한(Permission) + 스코프(Scope) 3단계 접근 제어로 조직 구조에 맞는 유연한 접근 관리를 제공합니다 |
+| **본인인증 (IDV)** | 회원가입·비밀번호 재설정·민감 작업 등 모든 본인인증 시점을 라우트/훅 단위 선언형 정책으로 통합 관리합니다. 코어가 메일 프로바이더를 기본 내장하고, 외부 KCP·이니시스·SMS·PortOne·Stripe Identity 등은 동일한 Provider 계약으로 붙일 수 있는 확장점을 제공합니다. 서버가 HTTP 428 응답을 반환하면 프론트엔드 인터셉터가 자동으로 인증 모달을 띄우고 인증 성공 시 원 요청을 재실행합니다 |
+| **보안** | 입력값 자동 검증과 토큰 기반 인증을 제공합니다. 설계부터 보안을 고려한 다층 방어 구조(CSRF/XSS/SQL Injection), 로그인 시도 제한·계정 잠금(HTTP 423) 실제 구현, 설치 완료 후 인스톨러 엔드포인트 자동 차단(HTTP 410) 까지 다층 방어를 구성합니다 |
+| **유연한 화면 구성** | 화면 구조를 정의하면 즉시 반영할 수 있습니다. 프론트엔드 인프라 없이 JSON 선언만으로 웹앱 수준의 동적 화면 구현이 가능합니다 |
+| **레이아웃 편집기** | 위지윅 기반 레이아웃 편집 기능으로 화면 블록을 직접 배치하고 수정 결과를 바로 확인할 수 있습니다 |
+| **검증된 기반** | Laravel + React 기반을 제공합니다. 글로벌 기업이 채택한 기술 스택으로 높은 확장성과 유연한 UI 구현이 가능합니다 |
+| **공통 캐시 시스템** | `CacheInterface` 와 코어/모듈/플러그인 3종 드라이버로 키 접두사(`g7:core:`, `g7:module.{id}:`, `g7:plugin.{id}:`) 를 자동 격리합니다. 태그 기반 자동 무효화와 `g7_core_settings('cache.*_ttl')` 중앙 관리로 하드코딩 없이 운영할 수 있습니다 |
+| **알림 시스템** | 알림 정의(Definition) × 템플릿(Template) × 수신자(Recipients) 3계층 구조로 메일/DB/실시간 브로드캐스트(Reverb) 다채널 독립 발송을 지원합니다. 작성자·역할·특정 사용자·권한 보유자 단위 타겟팅과 훅 기반 발송으로 모듈이 자체 알림을 자유롭게 등록할 수 있습니다 |
+| **SEO** | `jaybizzle/crawler-detect` 기반으로 약 1,000종 봇(검색엔진·SNS unfurl·AI 검색)을 자동 감지하여 봇 요청에는 정적 HTML 을, 일반 사용자에게는 SPA 를 응답합니다. OG/Twitter 카드 메타와 모듈이 선언한 도메인 스키마(Article/Product/Offer/AggregateRating), Sitemap 자동·수동 생성, Generator 메타 태그까지 표준 SEO 표면을 코어에서 제공합니다 |
+| **활동 로그** | 관리자·사용자 활동 이력을 자동으로 기록하고 조회할 수 있습니다. Monolog 기반 구조로 확장이 용이하며, 액션 라벨이 모듈/플러그인 자체 다국어 파일에서 우선 해석되어 도메인별 자기설명이 가능합니다 |
+| **검색** | Laravel Scout 기반 전문 검색을 지원합니다. 상품, 게시글 등 주요 콘텐츠를 대상으로 검색 기능을 제공합니다 |
+
+---
+
+## 기술 스택
+
+| 구분 | 기술 |
+|------|------|
+| **백엔드** | PHP 8.2+, Laravel 12.x, MySQL 8.0+ / MariaDB 10.3+, Redis 6.0+ |
+| **프론트엔드** | React 19, Vite, Tailwind CSS 4 (다크 모드 지원) |
+| **인증** | Laravel Sanctum (Bearer 토큰) |
+| **테스트** | PHPUnit 11.x, Vitest |
+| **코드 품질** | Laravel Pint (PSR-12) |
+
+---
+
+## 아키텍처
+
+```
+Gnuboard7
+├── Core (Laravel 12)
+│   ├── Controller → FormRequest → Service → Repository → Model
+│   ├── Hook System (Action / Filter)
+│   ├── Permission (Role → Permission → Scope)
+│   ├── Identity Verification (Policy × Purpose × Provider × Message)
+│   ├── Language Pack (가상 보호 행 + ZIP/GitHub 설치 + sub-key 보존)
+│   ├── Notification (Definition × Template × Recipients)
+│   └── SEO (Bot Detection → Static HTML → Cache → Sitemap)
+│
+├── Extensions
+│   ├── Modules    — 게시판, 쇼핑몰, 페이지 ...
+│   ├── Plugins    — 결제, 인증, 마케팅 ...
+│   ├── Templates  — 관리자 UI, 사용자 UI
+│   └── LanguagePacks — 일본어 등 공식/외부 언어팩
+│
+└── Template Engine
+    ├── JSON Layout → React Components
+    └── Dynamic Rendering + Data Binding
+```
+
+### 템플릿 엔진 동작 흐름
+
+그누보드7의 템플릿 엔진은 **JSON으로 UI 구조를 선언**하면, 엔진이 이를 해석하여 React 컴포넌트로 렌더링합니다.
+
+#### 제공 기능
+
+- JSON 선언만으로 React 기반 UI 구성 — React 전문 지식 없이도 화면 개발 가능
+- 모듈/플러그인이 프론트엔드 빌드 없이 JSON만으로 UI를 동적으로 주입/확장
+- 고도화된 UI가 필요한 경우 커스텀 React 컴포넌트를 개발하여 등록 가능
+- UI가 코드가 아닌 데이터(JSON)로 정의되는 구조를 활용한 **위지윅 레이아웃 편집기** — 비개발자도 화면 블록을 직접 배치·편집하고 결과를 바로 확인할 수 있습니다
+
+```mermaid
+flowchart TB
+    subgraph Backend ["🔧 Backend — Laravel"]
+        A["📄 JSON 레이아웃 파일"] --> B["⚙️ LayoutService"]
+        B --> |"상속 해석<br/>extends / partial"| B
+        M["📦 모듈 레이아웃"] -.-> |"layout_extensions<br/>extension_point 주입"| B
+        P["🔌 플러그인 레이아웃"] -.-> |"layout_extensions<br/>extension_point 주입"| B
+        B --> C["🔒 권한 필터링<br/>사용자별 컴포넌트 제거"]
+        C --> D["📨 병합된 JSON 응답<br/>캐싱 · 1시간 TTL"]
+    end
+
+    subgraph Frontend ["⚛️ Frontend — React"]
+        D --> E["📥 LayoutLoader<br/>레이아웃 JSON 수신"]
+        E --> F["💾 상태 초기화<br/>_global · _local · _computed"]
+        E --> G["🌐 데이터 소스 로딩<br/>API 병렬 호출"]
+        F & G --> H["🎨 DynamicRenderer"]
+
+        H --> I{"❓ 조건 평가<br/>if 표현식"}
+        I --> |"✅ true"| J["🗂️ ComponentRegistry<br/>name → React 컴포넌트"]
+        I --> |"❌ false"| K["⏭️ 렌더링 스킵"]
+
+        J --> L["🔗 데이터 바인딩<br/>표현식 → 실제 값"]
+        L --> N["🖱️ 이벤트 바인딩<br/>onClick → ActionDispatcher"]
+        N --> O["✨ React 렌더링"]
+    end
+
+    subgraph Actions ["👆 사용자 인터랙션"]
+        O --> |"클릭 · 입력"| Q["🎯 ActionDispatcher"]
+        Q --> R["🧭 navigate — 페이지 이동"]
+        Q --> S["📡 apiCall — API 호출"]
+        Q --> T["🔄 setState — 상태 변경"]
+        Q --> U["📋 openModal — 모달 열기"]
+        S --> |"onSuccess · onError"| Q
+        T --> |"상태 변경 → 리렌더링"| H
+    end
+
+    style Backend fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
+    style Frontend fill:#d1fae5,stroke:#059669,stroke-width:2px,color:#064e3b
+    style Actions fill:#fce7f3,stroke:#db2777,stroke-width:2px,color:#831843
+
+    style A fill:#2563eb,stroke:#1d4ed8,color:#fff
+    style B fill:#2563eb,stroke:#1d4ed8,color:#fff
+    style M fill:#7c3aed,stroke:#6d28d9,color:#fff
+    style P fill:#7c3aed,stroke:#6d28d9,color:#fff
+    style C fill:#dc2626,stroke:#b91c1c,color:#fff
+    style D fill:#059669,stroke:#047857,color:#fff
+
+    style E fill:#059669,stroke:#047857,color:#fff
+    style F fill:#0891b2,stroke:#0e7490,color:#fff
+    style G fill:#0891b2,stroke:#0e7490,color:#fff
+    style H fill:#d97706,stroke:#b45309,color:#fff
+    style I fill:#d97706,stroke:#b45309,color:#fff
+    style J fill:#2563eb,stroke:#1d4ed8,color:#fff
+    style K fill:#6b7280,stroke:#4b5563,color:#fff
+    style L fill:#7c3aed,stroke:#6d28d9,color:#fff
+    style N fill:#7c3aed,stroke:#6d28d9,color:#fff
+    style O fill:#059669,stroke:#047857,color:#fff
+
+    style Q fill:#e11d48,stroke:#be123c,color:#fff
+    style R fill:#be185d,stroke:#9d174d,color:#fff
+    style S fill:#be185d,stroke:#9d174d,color:#fff
+    style T fill:#be185d,stroke:#9d174d,color:#fff
+    style U fill:#be185d,stroke:#9d174d,color:#fff
+
+    linkStyle default stroke:#374151,stroke-width:2px
+```
+
+**JSON 레이아웃 예시** — 아래 JSON이 실제 React UI로 렌더링됩니다:
+
+```json
+{
+  "data_sources": [
+    { "id": "products", "endpoint": "/api/products", "method": "GET" }
+  ],
+  "layout": {
+    "type": "basic", "name": "Div",
+    "children": [
+      { "type": "basic", "name": "H1", "text": "$t:product_list" },
+      {
+        "type": "basic", "name": "Div",
+        "iteration": { "source": "{{products?.data?.data}}", "item_var": "$item" },
+        "children": [
+          { "type": "basic", "name": "Span", "text": "{{$item.name}}" }
+        ]
+      },
+      {
+        "type": "basic", "name": "Button", "text": "$t:add",
+        "if": "{{products?.data?.abilities?.can_create}}",
+        "actions": [{
+          "event": "onClick",
+          "handler": "navigate",
+          "params": { "path": "/products/create" }
+        }]
+      }
+    ]
+  }
+}
+```
+
+모듈/플러그인을 활성화하면 해당 UI와 컴포넌트가 자동으로 주입됩니다.
+개발자는 JSON만으로 UI를 추가하거나 변경할 수 있어 별도의 프론트엔드 빌드가 필요 없으며, 권한(abilities)에 따라 UI 요소가 자동으로 표시/숨김 처리됩니다.
+
+### 핵심 시스템
+
+플랫폼을 떠받치는 네 가지 시스템이 유기적으로 동작합니다.
+
+#### 1. 확장 시스템 — 3원칙
+
+1. **코어 수정 최소화** — 모든 비즈니스 로직은 모듈/플러그인으로 구현
+2. **동적 로딩** — `composer.json` 하드코딩 없이 디렉토리 스캔으로 자동 발견
+3. **Hook 기반 확장** — 서비스 계층에서 Action/Filter 훅으로 기능 주입
+
+#### 2. 훅 시스템 (Action / Filter)
+
+Laravel 이벤트와 별개로 동작하는 가벼운 훅 시스템입니다. Action 은 부수 작업(로깅, 알림), Filter 는 값 변형 (기본값 주입, 권한 확장)에 사용됩니다.
+
+```php
+// Service 계층에서 훅 발행
+HookManager::doAction('core.user.after_create', $user, $data);
+$data = HookManager::applyFilters('core.user.filter_create_data', $data);
+
+// 모듈 Listener 가 훅 구독 (자동 발견)
+public static function getSubscribedHooks(): array
+{
+    return [
+        'core.user.after_create' => ['method' => 'onUserCreated', 'priority' => 20],
+    ];
+}
+```
+
+모듈/플러그인은 `Listeners/` 디렉토리에 클래스만 두면 `HookListenerRegistrar` 가 자동으로 구독합니다. 큐 직렬화를 통한 비동기 실행도 지원하며, 워커에서도 `Auth::user()`, `request()->ip()`, `App::getLocale()` 같은 컨텍스트가 자동 복원됩니다.
+
+#### 3. 공통 캐시 시스템
+
+`CacheInterface` 를 기반으로 **코어 · 모듈 · 플러그인** 이 키 충돌 없이 각자의 캐시를 관리합니다.
+
+| 드라이버 | 접두사 | 용도 |
+| --- | --- | --- |
+| `CoreCacheDriver` | `g7:core:{key}` | 코어 서비스 (레이아웃, SEO, 알림, 설정 등) |
+| `ModuleCacheDriver` | `g7:module.{identifier}:{key}` | 모듈별 격리 캐시 (게시판 상품 리스트, 쿨다운 등) |
+| `PluginCacheDriver` | `g7:plugin.{identifier}:{key}` | 플러그인별 격리 캐시 |
+
+```php
+// 모듈 서비스는 BaseModuleServiceProvider::$cacheServices 배열에 등록하면
+// 생성자 타입힌트만으로 자동 주입됨 (Storage 패턴과 동일)
+public function __construct(
+    private BoardRepositoryInterface $repository,
+    private CacheInterface $cache, // ← g7:module.sirsoft-board: 접두사 자동 적용
+) {}
+```
+
+- **TTL 중앙 관리** — 모든 캐시 TTL 은 `g7_core_settings('cache.*_ttl')` 를 추종합니다. 하드코딩 금지
+- **자동 무효화** — `CacheInvalidatable` 트레이트를 모델에 적용하면 `saved` / `deleted` 시점에 태그 기반으로 관련 캐시 자동 삭제
+- **라이프사이클 연동** — 모듈 비활성화/삭제 시 `ModuleManager` 가 해당 모듈의 격리 캐시를 일괄 flush
+- **프론트엔드 캐시 버스팅** — `ext.cache_version` 증가가 응답의 `config.json` 을 통해 전파되어 `?v=` 쿼리 파라미터 기반으로 브라우저 캐시까지 무효화
+
+#### 4. 알림 시스템
+
+**Definition × Template × Recipients** 3계층 모델로 멀티 채널 알림을 관리합니다.
+
+```text
+┌─────────────────────┐      ┌───────────────────────┐      ┌─────────────────────┐
+│ NotificationDefini- │ 1..N │ NotificationTemplate  │      │ Recipients (JSON)   │
+│ tion                ├──────┤ (채널별 독립)         ├──────┤ - trigger_user      │
+│ type=order.created  │      │ channel=mail|db|...   │      │ - related_user      │
+│ variables=[...]     │      │ subject, body,        │      │ - role              │
+│                     │      │ click_url             │      │ - specific_users    │
+└─────────────────────┘      └───────────────────────┘      └─────────────────────┘
+```
+
+- **Definition** — 알림 종류(`type`), 지원 채널, 변수 메타데이터 정의
+- **Template** — 채널(`mail` / `database` / `broadcast`)마다 독립된 제목·본문·클릭 URL. 관리자가 다국어로 커스터마이징 가능
+- **Recipients** — 템플릿별로 수신자 규칙을 JSON 으로 정의. 템플릿 단위 독립이므로 "메일은 주문자에게, DB 알림은 역할 보유자에게" 같은 분기 구성 가능
+
+```php
+// 모듈 Service 에서 훅 발행만 하면 발송 파이프라인이 자동 실행
+HookManager::doAction('sirsoft-ecommerce.order.after_confirm', $order);
+
+// ↓ NotificationHookListener → NotificationDispatcher:
+// 1. order.confirmed 정의 조회
+// 2. 활성 템플릿 순회 (mail/database)
+// 3. 템플릿의 recipients JSON 해석 → 수신자 Collection
+// 4. 각 수신자에게 channel 별 발송 (GenericNotification)
+// 5. notification_logs 에 발송 이력 기록
+```
+
+- 코어 기본 알림 3종: `welcome`, `reset_password`, `password_changed`
+- 이커머스 모듈 알림 7종: `order_confirmed`, `order_shipped`, `order_completed`, `order_cancelled`, `new_order_admin`, `inquiry_received`, `inquiry_replied`
+- 실시간 브로드캐스트는 Laravel Reverb (WebSocket) 기반. Reverb 미구성 환경에서는 graceful skip 으로 오류 없이 동작
+- `GenericNotification` 단일 클래스가 모든 알림을 처리 — 신규 알림 타입 추가 시 개별 Notification 클래스 작성 불필요
+
+#### 5. 언어팩 시스템
+
+새 언어를 코어 수정 없이 추가할 수 있는 운영 도구로, 모듈/플러그인/템플릿 관리와 동일한 라이프사이클(설치 → 활성화 → 업데이트 → 제거 + 자동 백업/롤백) 을 제공합니다.
+
+| 영역 | 동작 |
+| --- | --- |
+| 설치 경로 | ZIP 업로드 / GitHub URL / `lang-packs/_bundled` 번들 디렉토리 (코어 업데이트 시 일괄 동기화) |
+| 적용 범위 | 코어, 모듈, 플러그인, 템플릿 별도 적용 — 모듈 언어팩은 해당 코어 언어팩이 활성일 때만 활성화 |
+| 사용자 수정 보존 | 다국어 JSON 컬럼은 sub-key 단위 (`name.ko` / `name.ja`) 로 user override 기록 — 한 언어 라벨만 수정해도 그 언어만 보존, 신규 언어는 자동 동기화 |
+| 활성화 시점 | 활성/비활성 시 영향받는 모듈/플러그인의 entity 시더가 자동 재실행 → 메뉴·권한·역할·매니페스트·알림 라벨 즉시 DB 반영 |
+| 가상 보호 행 | 코어/번들 확장에 내장된 한국어/영어는 별도 설치 없이 항상 활성/보호 상태로 노출 (수정/제거 차단) |
+| 보안 | 언어 번역 외의 PHP 실행 코드 포함 시 설치 차단 |
+
+공식 일본어(ja) 번들 16종(코어 + 주요 모듈/플러그인/템플릿) 이 즉시 사용 가능하며, 인스톨러 4단계에서 모듈/플러그인/템플릿 선택과 종속된 언어팩 카드가 자동 연동되어 함께 설치할 수 있습니다.
+
+> 상세: [docs/extension/language-packs.md](docs/extension/language-packs.md)
+
+#### 6. 본인인증 (Identity Verification)
+
+회원가입·비밀번호 재설정·민감 작업·결제 직전 등 모든 본인인증 시점을 라우트/훅 단위 선언형 정책으로 통합 관리합니다.
+
+```text
+┌────────────────────┐    ┌─────────────────────┐    ┌──────────────────────┐
+│ Policy             │    │ Purpose             │    │ Provider             │
+│ (강제 시점·실패 모드│    │ (인증 목적·허용 채널│    │ (메일·KCP·이니시스   │
+│  ·단계·conditions) │ ◀▶ │  ·source 추적)      │ ◀▶ │  ·SMS·외부 IDV ...)  │
+└────────────────────┘    └─────────────────────┘    └──────────────────────┘
+            │                                                  │
+            └──────────▶ Message Template (정책×목적 매핑) ◀───┘
+                                    │
+                              GenericNotification
+```
+
+- **정책 SSoT** — 정책 enable 토글이 라우트 코드 수정 없이 즉시 적용. 모든 API 라우트가 정책 DB 와 자동 매칭
+- **428 인터셉터** — 서버가 HTTP 428 응답을 반환하면 프론트엔드가 자동으로 인증 모달을 띄우고 인증 성공 시 원 요청을 자동 재실행
+- **선언형 등록** — 모듈/플러그인은 `module.php::getIdentityPolicies()` / `getIdentityPurposes()` / `getIdentityMessages()` 만 선언하면 활성화/업데이트 시 자동 등록되며 운영자 편집값 보존
+- **메시지 템플릿** — 프로바이더와 (목적/정책)별로 다국어 제목/본문을 개별 정의. 정책 → 목적 → 프로바이더 기본값 순서로 fallback
+- **외부 Provider 슬롯** — 플러그인이 KCP·PortOne·토스인증·Stripe Identity 등을 G7 표준 Extension Point 패턴으로 자기 SDK UI 를 주입 가능
+- **이력 관리** — 관리자 화면에서 인증 수단 탭, 통합 검색, 상태/목적/채널/IP 멀티 필터, 보관주기(180일) 일괄 파기 제공
+
+> 상세: [docs/backend/identity-policies.md](docs/backend/identity-policies.md), [docs/backend/identity-providers.md](docs/backend/identity-providers.md), [docs/backend/identity-messages.md](docs/backend/identity-messages.md)
+
+---
+
+## 빠른 시작
+
+### 시스템 요구사항
+
+- PHP 8.2+ (필수 확장 16개 포함 — `ctype`, `curl`, `dom`, `fileinfo`, `json`, `mbstring`, `openssl`, `pdo_mysql`, `tokenizer`, `xml`, `zip` 등. `gd`/`imagick`, `intl`, `redis`, `bcmath` 등은 해당 기능을 쓸 때만 필요하며 전체 목록은 [docs/requirements.md](docs/requirements.md) 참조)
+- MySQL 8.0+ 또는 MariaDB 10.3+ (utf8mb4)
+- Composer 2.x
+- Node.js 20+ (프론트엔드 에셋을 직접 빌드할 때만 필요)
+- 웹 서버(Apache 또는 Nginx) — 문서 루트를 `public/` 으로 지정
+- Redis 6.0+ (선택 — 프로덕션의 캐시·큐에 권장)
+
+### 설치
+
+```bash
+# 1. 프로젝트 클론
+git clone https://github.com/gnuboard/g7.git
+cd g7
+
+# 2. 환경 설정 파일 복사
+cp .env.example .env
+
+# 3. 브라우저에서 /install 접속 → 설치 마법사 진행
+```
+
+> 상세 설치 가이드는 [INSTALL.md](INSTALL.md)를 참조하세요.
+
+---
+
+## 기본 제공 확장
+
+### 모듈
+
+| 모듈 | 설명 |
+|------|------|
+| **sirsoft-board** | 게시판 — 다중 게시판, 댓글, 파일 첨부 |
+| **sirsoft-ecommerce** | 쇼핑몰 — 상품, 주문, 결제, 배송, 쿠폰, 상품 문의 |
+| **sirsoft-page** | 페이지 — 정적 콘텐츠 관리 |
+
+### 플러그인
+
+| 플러그인 | 설명 |
+|---------|------|
+| **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 에디터 |
+| **sirsoft-gdpr** | 개인정보 보호(GDPR) |
+| **sirsoft-message_bizppurio** | 비즈뿌리오 메시지 발송 (문자·카카오 알림톡) |
+
+### 템플릿
+
+| 템플릿 | 설명 |
+|--------|------|
+| **sirsoft-admin_basic** | 관리자 기본 템플릿 |
+| **sirsoft-basic** | 사용자 기본 템플릿 |
+
+### 번들 언어팩
+
+설치 시 함께 동반 설치할 수 있는 공식 언어팩입니다. 코어 + 주요 모듈/플러그인/템플릿이 일관된 번역으로 즉시 사용 가능합니다.
+
+| 식별자 | 설명 |
+| ------ | ---- |
+| **g7-core-ja** | 코어 일본어 |
+| **g7-module-sirsoft-board-ja** | 게시판 모듈 일본어 |
+| **g7-module-sirsoft-ecommerce-ja** | 이커머스 모듈 일본어 |
+| **g7-module-sirsoft-page-ja** | 페이지 모듈 일본어 |
+| **g7-plugin-sirsoft-ckeditor5-ja** | CKEditor5 플러그인 일본어 |
+| **g7-plugin-sirsoft-daum_postcode-ja** | 다음 우편번호 플러그인 일본어 |
+| **g7-plugin-sirsoft-gdpr-ja** | 개인정보 보호(GDPR) 플러그인 일본어 |
+| **g7-plugin-sirsoft-marketing-ja** | 마케팅 플러그인 일본어 |
+| **g7-plugin-sirsoft-message_bizppurio-ja** | 비즈뿌리오 메시지 발송 플러그인 일본어 |
+| **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** | 사용자 기본 템플릿 일본어 |
+
+> 한국어/영어는 코어/번들 확장에 내장되어 있으며 설치 없이 항상 활성 상태로 동작합니다. 새 언어는 ZIP 또는 GitHub URL 로 자유롭게 추가할 수 있습니다.
+
+### 학습용 샘플 확장
+
+확장 시스템 학습을 위한 최소 구현 샘플입니다. 관리자 UI 에서 "숨김 포함" 토글로 노출되며 CLI 에서는 항상 보입니다.
+
+| 식별자 | 종류 | 설명 |
+| ------ | ---- | ---- |
+| **gnuboard7-hello_module** | 모듈 | Memo CRUD + 훅 발행 시연 |
+| **gnuboard7-hello_plugin** | 플러그인 | Action/Filter 훅 구독 시연 |
+| **gnuboard7-hello_admin_template** | Admin 템플릿 | Basic 컴포넌트 최소 셋 |
+| **gnuboard7-hello_user_template** | User 템플릿 | 홈 + Memo 리스트 연동 |
+
+---
+
+## 비즈니스 모델
+
+그누보드7 하나로 다양한 비즈니스를 운영할 수 있습니다.
+
+| 모델 | 설명 | 상태 |
+|------|------|------|
+| **커뮤니티** | 게시판, 댓글, 회원 관리 | 정식 |
+| **커머스** | 상품 등록, 주문, 결제, 배송 관리 | 정식 |
+
+---
+
+## 기존 그누보드 사용자
+
+기존 그누보드5에서 그누보드7으로 전환할 수 있도록, 회원·게시글·상품 등 주요 데이터의 **마이그레이션 툴을 제공할 예정**입니다.
+
+---
+
+## 문서
+
+| 문서 | 링크 |
+|------|------|
+| 설치 가이드 | [INSTALL.md](INSTALL.md) |
+| 전체 문서 | [docs/README.md](docs/README.md) |
+| 시스템 요구사항 | [docs/requirements.md](docs/requirements.md) |
+| 백엔드 개발 | [docs/backend/README.md](docs/backend/README.md) |
+| 프론트엔드 개발 | [docs/frontend/README.md](docs/frontend/README.md) |
+| 데이터베이스 | [docs/database-guide.md](docs/database-guide.md) |
+| 확장 시스템 | [docs/extension/README.md](docs/extension/README.md) |
+| 모듈 개발 | [docs/extension/module-basics.md](docs/extension/module-basics.md) |
+| 플러그인 개발 | [docs/extension/plugin-development.md](docs/extension/plugin-development.md) |
+| 템플릿 개발 | [docs/extension/template-basics.md](docs/extension/template-basics.md) |
+| 테스트 | [docs/testing-guide.md](docs/testing-guide.md) |
+| API 레퍼런스 | [docs/backend/api/README.md](docs/backend/api/README.md) |
+| API 문서 작성 규정 | [docs/backend/api-documentation.md](docs/backend/api-documentation.md) |
+
+---
+
+## 기여하기
+
+그누보드7은 오픈소스 프로젝트입니다. 모든 형태의 기여를 환영합니다.
+
+- 버그 리포트 및 기능 제안: [GitHub Issues](https://github.com/gnuboard/g7/issues)
+- 코드 스타일: Laravel Pint (PSR-12)
+- 테스트: PHPUnit (백엔드) + Vitest (프론트엔드)
+- AI 협업: AI 에이전트용 개발 규칙 명세(AGENTS.md)와 MCP 디버깅 도구를 내장하고 있어, AI 도구와 자연스럽게 협업할 수 있습니다
+
+---
+
+## 만든 사람들
+
+**[SIRSOFT](https://sir.kr)** 에서 개발하고 있습니다.
+
+### Core Team
+
+<p>
+  <a href="https://github.com/HeuJung"><img src="https://github.com/HeuJung.png" width="60" alt="HeuJung"></a>&nbsp;&nbsp;
+  <a href="https://github.com/chym1217"><img src="https://github.com/chym1217.png" width="60" alt="chym1217"></a>&nbsp;&nbsp;
+  <a href="https://github.com/thisgun"><img src="https://github.com/thisgun.png" width="60" alt="thisgun"></a>
+</p>
+
+### 커뮤니티 기여자
+
+제보와 건의로 그누보드7을 함께 만들어 주신 분들입니다. 아래 목록은 변경 기록(CHANGELOG)에 남은 제보자 표기에서 모았습니다.
+
+<!-- community-contributors:start -->
+<p>
+  <a href="https://github.com/jiwonpapa" title="jiwonpapa"><img src="https://github.com/jiwonpapa.png" width="48" alt="jiwonpapa"></a>
+  <a href="https://github.com/Tuwasduliebst" title="Tuwasduliebst"><img src="https://github.com/Tuwasduliebst.png" width="48" alt="Tuwasduliebst"></a>
+  <a href="https://github.com/glitter-gim" title="glitter-gim"><img src="https://github.com/glitter-gim.png" width="48" alt="glitter-gim"></a>
+  <a href="https://github.com/jordy-bitree" title="jordy-bitree"><img src="https://github.com/jordy-bitree.png" width="48" alt="jordy-bitree"></a>
+  <a href="https://github.com/laelbe" title="laelbe"><img src="https://github.com/laelbe.png" width="48" alt="laelbe"></a>
+  <a href="https://github.com/lyg-kaban" title="lyg-kaban"><img src="https://github.com/lyg-kaban.png" width="48" alt="lyg-kaban"></a>
+  <a href="https://github.com/bigmsg" title="bigmsg"><img src="https://github.com/bigmsg.png" width="48" alt="bigmsg"></a>
+  <a href="https://github.com/abc101" title="abc101"><img src="https://github.com/abc101.png" width="48" alt="abc101"></a>
+  <a href="https://github.com/hwaryeon1234" title="hwaryeon1234"><img src="https://github.com/hwaryeon1234.png" width="48" alt="hwaryeon1234"></a>
+  <a href="https://github.com/koojunho" title="koojunho"><img src="https://github.com/koojunho.png" width="48" alt="koojunho"></a>
+  <a href="https://github.com/yks118" title="yks118"><img src="https://github.com/yks118.png" width="48" alt="yks118"></a>
+  <a href="https://github.com/kitrio" title="kitrio"><img src="https://github.com/kitrio.png" width="48" alt="kitrio"></a>
+  <a href="https://github.com/movielee2020" title="movielee2020"><img src="https://github.com/movielee2020.png" width="48" alt="movielee2020"></a>
+  <a href="https://github.com/ChoDongHyeon" title="ChoDongHyeon"><img src="https://github.com/ChoDongHyeon.png" width="48" alt="ChoDongHyeon"></a>
+  <a href="https://github.com/comtylove-netizen" title="comtylove-netizen"><img src="https://github.com/comtylove-netizen.png" width="48" alt="comtylove-netizen"></a>
+  <a href="https://github.com/devrhee16" title="devrhee16"><img src="https://github.com/devrhee16.png" width="48" alt="devrhee16"></a>
+  <a href="https://github.com/GyusoonKim" title="GyusoonKim"><img src="https://github.com/GyusoonKim.png" width="48" alt="GyusoonKim"></a>
+  <a href="https://github.com/Lastorder-DC" title="Lastorder-DC"><img src="https://github.com/Lastorder-DC.png" width="48" alt="Lastorder-DC"></a>
+  <a href="https://github.com/miles44229" title="miles44229"><img src="https://github.com/miles44229.png" width="48" alt="miles44229"></a>
+  <a href="https://github.com/minyho" title="minyho"><img src="https://github.com/minyho.png" width="48" alt="minyho"></a>
+</p>
+<!-- community-contributors:end -->
+
+코드 기여자 목록은 [GitHub Contributors](https://github.com/gnuboard/g7/graphs/contributors)에서 확인할 수 있습니다.
+
+---
+
+## 커뮤니티
+
+| 채널 | 링크 |
+|------|------|
+| GitHub | [github.com/gnuboard/g7](https://github.com/gnuboard/g7) |
+| SIR 커뮤니티 | [sir.kr](https://sir.kr) |
+| 문의 | minsup@sir.kr |
+
+---
+
+## 변경 기록
+
+최근 변경된 사항에 대한 자세한 내용은 [CHANGELOG](CHANGELOG.md)를 참고해 주세요.
+
+---
+
+## 보안 취약점
+
+보안 취약점을 발견하셨다면 [SIR 문의게시판](https://sir.kr/boards/co_qa)에 비밀글로 제보해 주세요.
+
+---
+
+## 라이선스
+
+그누보드7은 [MIT 라이선스](LICENSE)에 따라 배포되는 오픈소스 소프트웨어입니다.
+
+Copyright (c) 2026 SIRSOFT
+
+---
+
+<p align="center">
+  Made by <a href="https://sir.kr">SIRSOFT</a>
+</p>
@@ -1,14 +1,16 @@
+<p align="center">English | <a href="README.ko.md">한국어</a></p>
+
 <p align="center">
-  <img src="https://img.shields.io/badge/그누보드7-Gnuboard7-000000?style=for-the-badge&labelColor=0066FF&logoColor=white" height="200" alt="그누보드7 (Gnuboard7)">
+  <img src="https://img.shields.io/badge/Gnuboard7-그누보드7-000000?style=for-the-badge&labelColor=0066FF&logoColor=white" height="200" alt="Gnuboard7 (그누보드7)">
 </p>

 <p align="center">
-  <strong>모던 아키텍처로 다시 태어난 대한민국 대표 오픈소스 CMS</strong><br>
-  A modern, extensible CMS platform built with Laravel + React
+  <strong>A modern, extensible CMS platform built with Laravel + React</strong><br>
+  The next generation of Gnuboard — Korea's most widely used open-source CMS
 </p>

 <p align="center">
-  <a href="#"><img src="https://img.shields.io/badge/version-7.0.1-blue" alt="Version"></a>
+  <a href="#"><img src="https://img.shields.io/badge/version-7.0.9-blue" alt="Version"></a>
  <a href="#"><img src="https://img.shields.io/badge/PHP-8.2%2B-777BB4?logo=php&logoColor=white" alt="PHP"></a>
  <a href="#"><img src="https://img.shields.io/badge/Laravel-12.x-FF2D20?logo=laravel&logoColor=white" alt="Laravel"></a>
  <a href="#"><img src="https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=black" alt="React"></a>
@@ -16,63 +18,72 @@
  <a href="#"><img src="https://img.shields.io/badge/status-Stable-brightgreen" alt="Status"></a>
 </p>

---
+<p align="center">
+  <a href="https://g7.gnuboard.com"><strong>Live Demo</strong></a> ·
+  <a href="https://g7.gnuboard.com/admin"><strong>Admin Demo</strong></a>
+</p>

-[소개](#그누보드7-소개) · [주요 기능](#주요-기능) · [기술 스택](#기술-스택) · [아키텍처](#아키텍처) · [빠른 시작](#빠른-시작) · [기본 제공 확장](#기본-제공-확장) · [비즈니스 모델](#비즈니스-모델) · [기존 사용자](#기존-그누보드-사용자) · [문서](#문서) · [기여하기](#기여하기) · [만든 사람들](#만든-사람들) · [커뮤니티](#커뮤니티) · [변경 기록](#변경-기록) · [라이선스](#라이선스)
+<p align="center">
+  <sub>The demo UI language follows your browser (Korean/English); you can switch it in the UI.</sub>
+</p>

 ---

-## 그누보드7 소개
-
-**그누보드7 (Gnuboard7)** 은 23년간 대한민국에서 가장 널리 사용된 오픈소스 CMS인 그누보드를, 현대적 기술 스택으로 **완전히 새로 설계**한 차세대 웹 플랫폼입니다.
-
-Laravel과 React를 기반으로, 보안부터 아키텍처까지 처음부터 다시 만들었습니다.
-
- **JSON 레이아웃 엔진**: React를 몰라도 JSON만으로 React 기반 UI를 선언적으로 정의. 모듈/플러그인이 프론트엔드 빌드 없이 JSON만으로 UI를 동적으로 주입/확장. 고도화된 UI가 필요한 경우 커스텀 React 컴포넌트를 개발하여 등록 가능
- **하나의 플랫폼, 다양한 비즈니스**: 커뮤니티, 쇼핑몰, 구독, 예약 — 비즈니스 모델에 맞게 확장
- **정교한 권한 관리**: 역할(Role) + 권한(Permission) + 스코프(Scope) 3단계 접근 제어로, 서비스 규모가 커져도 통제력 유지
- **글로벌 레디**: 다국어(i18n) 네이티브 지원, 로케일 기반 UI, 다중 통화 대응
- **확장 시스템**: 모듈 + 플러그인 + 템플릿 3중 구조로 코어 수정 없이 기능 확장
+[About](#about-gnuboard7) · [Key Features](#key-features) · [Tech Stack](#tech-stack) · [Architecture](#architecture) · [Quick Start](#quick-start) · [Bundled Extensions](#bundled-extensions) · [Business Models](#business-models) · [Migrating from Gnuboard 5](#migrating-from-gnuboard-5) · [Documentation](#documentation) · [Contributing](#contributing) · [Team](#team) · [Community](#community) · [Changelog](#changelog) · [License](#license)

 ---

-## 주요 기능
+## About Gnuboard7

-현대적인 웹 플랫폼에 필요한 핵심 기능을 갖추었습니다.
+**Gnuboard7** is a complete, ground-up redesign of Gnuboard — Korea's most widely used open-source CMS for 23 years — rebuilt on a modern stack.

-| 영역 | 설명 |
-|------|------|
-| **모듈 아키텍처** | 모듈 + 플러그인 + 템플릿 3중 확장 구조. 코어 수정 없이 독립적 모듈(게시판, 커머스 등) 개발이 가능합니다. Hook 기반 기능 주입으로 Service-Repository 패턴의 명확한 계층 분리를 유지합니다 |
-| **언어팩 시스템** | 새 언어를 코어 수정 없이 ZIP 또는 GitHub URL 로 설치할 수 있습니다. 일본어 등 공식 번들 언어팩을 즉시 사용할 수 있고, 운영자가 직접 수정한 라벨은 언어팩이 덮어쓰지 않도록 sub-key 단위로 보존합니다. 모듈/플러그인/템플릿 단위로 별도 적용 가능 |
-| **현지화** | 백엔드부터 프론트엔드까지 일관된 다국어 개발 환경을 제공합니다. 활성 언어팩이 알림 채널 라벨, Provider/Registry 페이로드, 환경설정 카탈로그(결제수단·통화·배송 가능 국가)까지 자동 보강되며, 모듈/플러그인이 자기 도메인 라벨을 자기 영역에서 자기설명하도록 활동 로그·메시지 영역도 분리되어 있습니다 |
-| **해외 결제** | 로컬 비즈니스를 넘어 글로벌 커머스로 도약하기 위한 기반을 제공합니다. 결제 연동은 동일한 Extension Point 패턴으로 붙일 수 있으며, 해외 결제 수단은 별도 플러그인으로 제공됩니다 |
-| **권한 제어** | 역할별 메뉴와 기능, 데이터 범위까지 제어할 수 있습니다. 역할(Role) + 권한(Permission) + 스코프(Scope) 3단계 접근 제어로 조직 구조에 맞는 유연한 접근 관리를 제공합니다 |
-| **본인인증 (IDV)** | 회원가입·비밀번호 재설정·민감 작업 등 모든 본인인증 시점을 라우트/훅 단위 선언형 정책으로 통합 관리합니다. 코어가 메일 프로바이더를 기본 내장하고, 외부 KCP·이니시스·SMS·PortOne·Stripe Identity 등은 동일한 Provider 계약으로 붙일 수 있는 확장점을 제공합니다. 서버가 HTTP 428 응답을 반환하면 프론트엔드 인터셉터가 자동으로 인증 모달을 띄우고 인증 성공 시 원 요청을 재실행합니다 |
-| **보안** | 입력값 자동 검증과 토큰 기반 인증을 제공합니다. 설계부터 보안을 고려한 다층 방어 구조(CSRF/XSS/SQL Injection), 로그인 시도 제한·계정 잠금(HTTP 423) 실제 구현, 설치 완료 후 인스톨러 엔드포인트 자동 차단(HTTP 410) 까지 다층 방어를 구성합니다 |
-| **유연한 화면 구성** | 화면 구조를 정의하면 즉시 반영할 수 있습니다. 프론트엔드 인프라 없이 JSON 선언만으로 웹앱 수준의 동적 화면 구현이 가능합니다 |
-| **레이아웃 편집기** | 위지윅 기반 레이아웃 편집 기능으로 화면 블록을 직접 배치하고 수정 결과를 바로 확인할 수 있습니다 |
-| **검증된 기반** | Laravel + React 기반을 제공합니다. 글로벌 기업이 채택한 기술 스택으로 높은 확장성과 유연한 UI 구현이 가능합니다 |
-| **공통 캐시 시스템** | `CacheInterface` 와 코어/모듈/플러그인 3종 드라이버로 키 접두사(`g7:core:`, `g7:module.{id}:`, `g7:plugin.{id}:`) 를 자동 격리합니다. 태그 기반 자동 무효화와 `g7_core_settings('cache.*_ttl')` 중앙 관리로 하드코딩 없이 운영할 수 있습니다 |
-| **알림 시스템** | 알림 정의(Definition) × 템플릿(Template) × 수신자(Recipients) 3계층 구조로 메일/DB/실시간 브로드캐스트(Reverb) 다채널 독립 발송을 지원합니다. 작성자·역할·특정 사용자·권한 보유자 단위 타겟팅과 훅 기반 발송으로 모듈이 자체 알림을 자유롭게 등록할 수 있습니다 |
-| **SEO** | `jaybizzle/crawler-detect` 기반으로 약 1,000종 봇(검색엔진·SNS unfurl·AI 검색)을 자동 감지하여 봇 요청에는 정적 HTML 을, 일반 사용자에게는 SPA 를 응답합니다. OG/Twitter 카드 메타와 모듈이 선언한 도메인 스키마(Article/Product/Offer/AggregateRating), Sitemap 자동·수동 생성, Generator 메타 태그까지 표준 SEO 표면을 코어에서 제공합니다 |
-| **활동 로그** | 관리자·사용자 활동 이력을 자동으로 기록하고 조회할 수 있습니다. Monolog 기반 구조로 확장이 용이하며, 액션 라벨이 모듈/플러그인 자체 다국어 파일에서 우선 해석되어 도메인별 자기설명이 가능합니다 |
-| **검색** | Laravel Scout 기반 전문 검색을 지원합니다. 상품, 게시글 등 주요 콘텐츠를 대상으로 검색 기능을 제공합니다 |
+Everything from security to architecture was rewritten from scratch on Laravel and React.
+
+- **JSON layout engine**: define React-based UI declaratively with JSON alone, no React knowledge required. Modules and plugins inject or extend UI dynamically through JSON without a frontend build. When you need something more advanced, you can develop and register custom React components
+- **One platform, many business models**: community, storefront, subscription, booking — extend it to fit your business
+- **Fine-grained access control**: Role + Permission + Scope, a three-tier model that keeps control as your service grows
+- **Global-ready**: native i18n support, locale-driven UI, multi-currency handling
+- **Extension system**: modules + plugins + templates, a three-layer structure that adds functionality without touching the core

 ---

-## 기술 스택
+## Key Features

-| 구분 | 기술 |
-|------|------|
-| **백엔드** | PHP 8.2+, Laravel 12.x, MySQL 8.0+, Redis 6.0+ |
-| **프론트엔드** | React 19, Vite, Tailwind CSS 4 (다크 모드 지원) |
-| **인증** | Laravel Sanctum (Bearer 토큰) |
-| **테스트** | PHPUnit 11.x, Vitest |
-| **코드 품질** | Laravel Pint (PSR-12) |
+Everything a modern web platform needs, built in.
+
+| Area | Description |
+|------|-------------|
+| **Modular architecture** | Modules + plugins + templates, a three-layer extension structure. Independent modules (boards, commerce, and more) can be developed without modifying the core. Hook-based injection preserves the clear layering of the Service-Repository pattern |
+| **Language pack system** | Install a new language from a ZIP file or GitHub URL without touching the core. Official bundled language packs (Japanese and others) are ready to use immediately, and labels an operator has edited are preserved per sub-key so a language pack never overwrites them. Packs apply independently to modules, plugins, and templates |
+| **Localization** | A consistent multilingual development experience from backend to frontend. Active language packs automatically enrich notification channel labels, provider/registry payloads, and settings catalogs (payment methods, currencies, shippable countries). Activity log and message surfaces are separated so modules and plugins describe their own domain labels in their own territory |
+| **Payment gateways** | A foundation for growing beyond a local business into global commerce. Payment integrations attach through the same extension-point pattern, and international gateways ship as separate plugins |
+| **Access control** | Control menus, features, and even data scope per role. Role + Permission + Scope three-tier access control provides flexible management that mirrors your organization |
+| **Identity verification (IDV)** | Every verification point — signup, password reset, sensitive operations — is managed centrally through declarative route/hook-level policies. The core ships a mail provider built in, and external providers (Korean identity-verification services such as KG Inicis and NHN KCP, as well as SMS, PortOne, and Stripe Identity-style services) attach through the same provider contract. When the server returns HTTP 428, the frontend interceptor opens a verification modal automatically and replays the original request on success |
+| **Security** | Automatic input validation and token-based authentication. Layered defense designed in from the start (CSRF/XSS/SQL injection), a real implementation of login throttling and account lockout (HTTP 423), and automatic blocking of installer endpoints once setup completes (HTTP 410) |
+| **Flexible screen composition** | Define a screen structure and see it applied immediately. Web-app-grade dynamic screens are achievable with JSON declarations alone, no frontend infrastructure required |
+| **Layout editor** | A WYSIWYG layout editor lets you place screen blocks directly and see the result right away |
+| **Proven foundation** | Built on Laravel + React — a stack adopted by companies worldwide, offering high extensibility and flexible UI implementation |
+| **Shared cache system** | `CacheInterface` plus three drivers (core/module/plugin) isolate key prefixes automatically (`g7:core:`, `g7:module.{id}:`, `g7:plugin.{id}:`). Tag-based automatic invalidation and central TTL management via `g7_core_settings('cache.*_ttl')` keep operations free of hardcoded values |
+| **Notification system** | A three-tier model — Definition × Template × Recipients — supports independent multi-channel delivery over mail, database, and real-time broadcast (Reverb). Targeting by author, role, specific users, or permission holders, plus hook-based dispatch, lets modules register their own notifications freely |
+| **SEO** | Powered by `jaybizzle/crawler-detect`, roughly 1,000 bot types (search engines, social unfurlers, AI search) are detected automatically: bots receive static HTML while regular users get the SPA. OG/Twitter card metadata, domain schemas declared by modules (Article/Product/Offer/AggregateRating), automatic and manual sitemap generation, and generator meta tags are all provided by the core |
+| **Activity log** | Administrator and user activity is recorded and searchable automatically. The Monolog-based structure is easy to extend, and action labels resolve from a module's or plugin's own translation files first, so each domain describes itself |
+| **Search** | Full-text search powered by Laravel Scout, covering key content such as products and posts |

 ---

-## 아키텍처
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| **Backend** | PHP 8.2+, Laravel 12.x, MySQL 8.0+ / MariaDB 10.3+, Redis 6.0+ |
+| **Frontend** | React 19, Vite, Tailwind CSS 4 (dark mode supported) |
+| **Authentication** | Laravel Sanctum (Bearer tokens) |
+| **Testing** | PHPUnit 11.x, Vitest |
+| **Code quality** | Laravel Pint (PSR-12) |
+
+---
+
+## Architecture

 ```
 Gnuboard7
@@ -81,66 +92,66 @@ Gnuboard7
 │   ├── Hook System (Action / Filter)
 │   ├── Permission (Role → Permission → Scope)
 │   ├── Identity Verification (Policy × Purpose × Provider × Message)
-│   ├── Language Pack (가상 보호 행 + ZIP/GitHub 설치 + sub-key 보존)
+│   ├── Language Pack (virtual protected rows + ZIP/GitHub install + sub-key preservation)
 │   ├── Notification (Definition × Template × Recipients)
 │   └── SEO (Bot Detection → Static HTML → Cache → Sitemap)
 │
 ├── Extensions
-│   ├── Modules    — 게시판, 쇼핑몰, 페이지 ...
-│   ├── Plugins    — 결제, 인증, 마케팅 ...
-│   ├── Templates  — 관리자 UI, 사용자 UI
-│   └── LanguagePacks — 일본어 등 공식/외부 언어팩
+│   ├── Modules    — board, commerce, page ...
+│   ├── Plugins    — payment, verification, marketing ...
+│   ├── Templates  — admin UI, user UI
+│   └── LanguagePacks — official and third-party packs (Japanese and more)
 │
 └── Template Engine
    ├── JSON Layout → React Components
    └── Dynamic Rendering + Data Binding
 ```

-### 템플릿 엔진 동작 흐름
+### How the template engine works

-그누보드7의 템플릿 엔진은 **JSON으로 UI 구조를 선언**하면, 엔진이 이를 해석하여 React 컴포넌트로 렌더링합니다.
+In Gnuboard7 you **declare the UI structure in JSON**, and the engine interprets it and renders React components.

-#### 제공 기능
+#### What it gives you

- JSON 선언만으로 React 기반 UI 구성 — React 전문 지식 없이도 화면 개발 가능
- 모듈/플러그인이 프론트엔드 빌드 없이 JSON만으로 UI를 동적으로 주입/확장
- 고도화된 UI가 필요한 경우 커스텀 React 컴포넌트를 개발하여 등록 가능
- UI가 코드가 아닌 데이터(JSON)로 정의되는 구조를 활용한 **위지윅 레이아웃 편집기** — 비개발자도 화면 블록을 직접 배치·편집하고 결과를 바로 확인할 수 있습니다
+- Build React-based UI from JSON declarations alone — screen development without React expertise
+- Modules and plugins inject or extend UI dynamically through JSON, with no frontend build
+- Develop and register custom React components when a screen needs something more advanced
+- Because the UI is defined as data (JSON) rather than code, a **WYSIWYG layout editor** lets non-developers place and edit screen blocks and see the result immediately

 ```mermaid
 flowchart TB
    subgraph Backend ["🔧 Backend — Laravel"]
-        A["📄 JSON 레이아웃 파일"] --> B["⚙️ LayoutService"]
-        B --> |"상속 해석<br/>extends / partial"| B
-        M["📦 모듈 레이아웃"] -.-> |"layout_extensions<br/>extension_point 주입"| B
-        P["🔌 플러그인 레이아웃"] -.-> |"layout_extensions<br/>extension_point 주입"| B
-        B --> C["🔒 권한 필터링<br/>사용자별 컴포넌트 제거"]
-        C --> D["📨 병합된 JSON 응답<br/>캐싱 · 1시간 TTL"]
+        A["📄 JSON layout file"] --> B["⚙️ LayoutService"]
+        B --> |"inheritance<br/>extends / partial"| B
+        M["📦 Module layout"] -.-> |"layout_extensions<br/>extension_point injection"| B
+        P["🔌 Plugin layout"] -.-> |"layout_extensions<br/>extension_point injection"| B
+        B --> C["🔒 Permission filtering<br/>drop components per user"]
+        C --> D["📨 Merged JSON response<br/>cached · 1 hour TTL"]
    end

    subgraph Frontend ["⚛️ Frontend — React"]
-        D --> E["📥 LayoutLoader<br/>레이아웃 JSON 수신"]
-        E --> F["💾 상태 초기화<br/>_global · _local · _computed"]
-        E --> G["🌐 데이터 소스 로딩<br/>API 병렬 호출"]
+        D --> E["📥 LayoutLoader<br/>receive layout JSON"]
+        E --> F["💾 State init<br/>_global · _local · _computed"]
+        E --> G["🌐 Data source loading<br/>parallel API calls"]
        F & G --> H["🎨 DynamicRenderer"]

-        H --> I{"❓ 조건 평가<br/>if 표현식"}
-        I --> |"✅ true"| J["🗂️ ComponentRegistry<br/>name → React 컴포넌트"]
-        I --> |"❌ false"| K["⏭️ 렌더링 스킵"]
+        H --> I{"❓ Condition eval<br/>if expression"}
+        I --> |"✅ true"| J["🗂️ ComponentRegistry<br/>name → React component"]
+        I --> |"❌ false"| K["⏭️ Skip rendering"]

-        J --> L["🔗 데이터 바인딩<br/>표현식 → 실제 값"]
-        L --> N["🖱️ 이벤트 바인딩<br/>onClick → ActionDispatcher"]
-        N --> O["✨ React 렌더링"]
+        J --> L["🔗 Data binding<br/>expression → value"]
+        L --> N["🖱️ Event binding<br/>onClick → ActionDispatcher"]
+        N --> O["✨ React render"]
    end

-    subgraph Actions ["👆 사용자 인터랙션"]
-        O --> |"클릭 · 입력"| Q["🎯 ActionDispatcher"]
-        Q --> R["🧭 navigate — 페이지 이동"]
-        Q --> S["📡 apiCall — API 호출"]
-        Q --> T["🔄 setState — 상태 변경"]
-        Q --> U["📋 openModal — 모달 열기"]
+    subgraph Actions ["👆 User interaction"]
+        O --> |"click · input"| Q["🎯 ActionDispatcher"]
+        Q --> R["🧭 navigate — page transition"]
+        Q --> S["📡 apiCall — API request"]
+        Q --> T["🔄 setState — state change"]
+        Q --> U["📋 openModal — open a modal"]
        S --> |"onSuccess · onError"| Q
-        T --> |"상태 변경 → 리렌더링"| H
+        T --> |"state change → re-render"| H
    end

    style Backend fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
@@ -174,7 +185,7 @@ flowchart TB
    linkStyle default stroke:#374151,stroke-width:2px
 ```

-**JSON 레이아웃 예시** — 아래 JSON이 실제 React UI로 렌더링됩니다:
+**JSON layout example** — the JSON below renders as a real React UI:

 ```json
 {
@@ -206,29 +217,29 @@ flowchart TB
 }
 ```

-모듈/플러그인을 활성화하면 해당 UI와 컴포넌트가 자동으로 주입됩니다.
-개발자는 JSON만으로 UI를 추가하거나 변경할 수 있어 별도의 프론트엔드 빌드가 필요 없으며, 권한(abilities)에 따라 UI 요소가 자동으로 표시/숨김 처리됩니다.
+Activating a module or plugin injects its UI and components automatically.
+Developers add or change UI with JSON alone — no separate frontend build — and UI elements are shown or hidden automatically according to permissions (abilities).

-### 핵심 시스템
+### Core systems

-플랫폼을 떠받치는 네 가지 시스템이 유기적으로 동작합니다.
+Four systems work together to hold the platform up.

-#### 1. 확장 시스템 — 3원칙
+#### 1. Extension system — three principles

-1. **코어 수정 최소화** — 모든 비즈니스 로직은 모듈/플러그인으로 구현
-2. **동적 로딩** — `composer.json` 하드코딩 없이 디렉토리 스캔으로 자동 발견
-3. **Hook 기반 확장** — 서비스 계층에서 Action/Filter 훅으로 기능 주입
+1. **Minimal core modification** — all business logic lives in modules and plugins
+2. **Dynamic loading** — discovered automatically by directory scan, with no `composer.json` hardcoding
+3. **Hook-based extension** — functionality is injected at the service layer through action and filter hooks

-#### 2. 훅 시스템 (Action / Filter)
+#### 2. Hook system (Action / Filter)

-Laravel 이벤트와 별개로 동작하는 가벼운 훅 시스템입니다. Action 은 부수 작업(로깅, 알림), Filter 는 값 변형 (기본값 주입, 권한 확장)에 사용됩니다.
+A lightweight hook system that operates separately from Laravel events. Actions handle side effects (logging, notifications); filters transform values (injecting defaults, extending permissions).

 ```php
-// Service 계층에서 훅 발행
+// Publish hooks from the service layer
 HookManager::doAction('core.user.after_create', $user, $data);
 $data = HookManager::applyFilters('core.user.filter_create_data', $data);

-// 모듈 Listener 가 훅 구독 (자동 발견)
+// A module listener subscribes to the hook (auto-discovered)
 public static function getSubscribedHooks(): array
 {
    return [
@@ -237,249 +248,272 @@ public static function getSubscribedHooks(): array
 }
 ```

-모듈/플러그인은 `Listeners/` 디렉토리에 클래스만 두면 `HookListenerRegistrar` 가 자동으로 구독합니다. 큐 직렬화를 통한 비동기 실행도 지원하며, 워커에서도 `Auth::user()`, `request()->ip()`, `App::getLocale()` 같은 컨텍스트가 자동 복원됩니다.
+Modules and plugins only need to place a class in their `Listeners/` directory and `HookListenerRegistrar` subscribes it automatically. Asynchronous execution through queue serialization is supported as well, and context such as `Auth::user()`, `request()->ip()`, and `App::getLocale()` is restored automatically inside the worker.

-#### 3. 공통 캐시 시스템
+#### 3. Shared cache system

-`CacheInterface` 를 기반으로 **코어 · 모듈 · 플러그인** 이 키 충돌 없이 각자의 캐시를 관리합니다.
+Built on `CacheInterface`, the **core, modules, and plugins** each manage their own cache without key collisions.

-| 드라이버 | 접두사 | 용도 |
+| Driver | Prefix | Purpose |
 | --- | --- | --- |
-| `CoreCacheDriver` | `g7:core:{key}` | 코어 서비스 (레이아웃, SEO, 알림, 설정 등) |
-| `ModuleCacheDriver` | `g7:module.{identifier}:{key}` | 모듈별 격리 캐시 (게시판 상품 리스트, 쿨다운 등) |
-| `PluginCacheDriver` | `g7:plugin.{identifier}:{key}` | 플러그인별 격리 캐시 |
+| `CoreCacheDriver` | `g7:core:{key}` | Core services (layouts, SEO, notifications, settings) |
+| `ModuleCacheDriver` | `g7:module.{identifier}:{key}` | Per-module isolated cache (board and product lists, cooldowns) |
+| `PluginCacheDriver` | `g7:plugin.{identifier}:{key}` | Per-plugin isolated cache |

 ```php
-// 모듈 서비스는 BaseModuleServiceProvider::$cacheServices 배열에 등록하면
-// 생성자 타입힌트만으로 자동 주입됨 (Storage 패턴과 동일)
+// Register a module service in the BaseModuleServiceProvider::$cacheServices array
+// and it is injected from the constructor type hint alone (same as the storage pattern)
 public function __construct(
    private BoardRepositoryInterface $repository,
-    private CacheInterface $cache, // ← g7:module.sirsoft-board: 접두사 자동 적용
+    private CacheInterface $cache, // ← g7:module.sirsoft-board: prefix applied automatically
 ) {}
 ```

- **TTL 중앙 관리** — 모든 캐시 TTL 은 `g7_core_settings('cache.*_ttl')` 를 추종합니다. 하드코딩 금지
- **자동 무효화** — `CacheInvalidatable` 트레이트를 모델에 적용하면 `saved` / `deleted` 시점에 태그 기반으로 관련 캐시 자동 삭제
- **라이프사이클 연동** — 모듈 비활성화/삭제 시 `ModuleManager` 가 해당 모듈의 격리 캐시를 일괄 flush
- **프론트엔드 캐시 버스팅** — `ext.cache_version` 증가가 응답의 `config.json` 을 통해 전파되어 `?v=` 쿼리 파라미터 기반으로 브라우저 캐시까지 무효화
+- **Central TTL management** — every cache TTL follows `g7_core_settings('cache.*_ttl')`. No hardcoding
+- **Automatic invalidation** — apply the `CacheInvalidatable` trait to a model and related caches are dropped by tag on `saved` / `deleted`
+- **Lifecycle integration** — when a module is deactivated or removed, `ModuleManager` flushes that module's isolated cache in bulk
+- **Frontend cache busting** — incrementing `ext.cache_version` propagates through the response `config.json` and invalidates browser caches via a `?v=` query parameter

-#### 4. 알림 시스템
+#### 4. Notification system

-**Definition × Template × Recipients** 3계층 모델로 멀티 채널 알림을 관리합니다.
+Multi-channel notifications are managed through a three-tier model: **Definition × Template × Recipients**.

 ```text
 ┌─────────────────────┐      ┌───────────────────────┐      ┌─────────────────────┐
 │ NotificationDefini- │ 1..N │ NotificationTemplate  │      │ Recipients (JSON)   │
-│ tion                ├──────┤ (채널별 독립)         ├──────┤ - trigger_user      │
-│ type=order.created  │      │ channel=mail|db|...   │      │ - related_user      │
-│ variables=[...]     │      │ subject, body,        │      │ - role              │
-│                     │      │ click_url             │      │ - specific_users    │
+│ tion                ├──────┤ (independent per      ├──────┤ - trigger_user      │
+│ type=order.created  │      │  channel)             │      │ - related_user      │
+│ variables=[...]     │      │ channel=mail|db|...   │      │ - role              │
+│                     │      │ subject, body,        │      │ - specific_users    │
+│                     │      │ click_url             │      │                     │
 └─────────────────────┘      └───────────────────────┘      └─────────────────────┘
 ```

- **Definition** — 알림 종류(`type`), 지원 채널, 변수 메타데이터 정의
- **Template** — 채널(`mail` / `database` / `broadcast`)마다 독립된 제목·본문·클릭 URL. 관리자가 다국어로 커스터마이징 가능
- **Recipients** — 템플릿별로 수신자 규칙을 JSON 으로 정의. 템플릿 단위 독립이므로 "메일은 주문자에게, DB 알림은 역할 보유자에게" 같은 분기 구성 가능
+- **Definition** — declares the notification type, supported channels, and variable metadata
+- **Template** — an independent subject, body, and click URL per channel (`mail` / `database` / `broadcast`). Administrators can customize them in multiple languages
+- **Recipients** — recipient rules declared as JSON per template. Because they are per-template, you can branch freely: "mail to the buyer, database notification to role holders"

 ```php
-// 모듈 Service 에서 훅 발행만 하면 발송 파이프라인이 자동 실행
+// A module service only publishes a hook; the delivery pipeline runs automatically
 HookManager::doAction('sirsoft-ecommerce.order.after_confirm', $order);

 // ↓ NotificationHookListener → NotificationDispatcher:
-// 1. order.confirmed 정의 조회
-// 2. 활성 템플릿 순회 (mail/database)
-// 3. 템플릿의 recipients JSON 해석 → 수신자 Collection
-// 4. 각 수신자에게 channel 별 발송 (GenericNotification)
-// 5. notification_logs 에 발송 이력 기록
+// 1. Look up the order.confirmed definition
+// 2. Iterate active templates (mail/database)
+// 3. Resolve each template's recipients JSON → recipient collection
+// 4. Deliver per channel to each recipient (GenericNotification)
+// 5. Record the delivery in notification_logs
 ```

- 코어 기본 알림 3종: `welcome`, `reset_password`, `password_changed`
- 이커머스 모듈 알림 7종: `order_confirmed`, `order_shipped`, `order_completed`, `order_cancelled`, `new_order_admin`, `inquiry_received`, `inquiry_replied`
- 실시간 브로드캐스트는 Laravel Reverb (WebSocket) 기반. Reverb 미구성 환경에서는 graceful skip 으로 오류 없이 동작
- `GenericNotification` 단일 클래스가 모든 알림을 처리 — 신규 알림 타입 추가 시 개별 Notification 클래스 작성 불필요
+- Three core notifications: `welcome`, `reset_password`, `password_changed`
+- Seven e-commerce module notifications: `order_confirmed`, `order_shipped`, `order_completed`, `order_cancelled`, `new_order_admin`, `inquiry_received`, `inquiry_replied`
+- Real-time broadcasting runs on Laravel Reverb (WebSocket). Where Reverb is not configured, it skips gracefully without errors
+- A single `GenericNotification` class handles every notification — adding a new notification type requires no new notification class

-#### 5. 언어팩 시스템
+#### 5. Language pack system

-새 언어를 코어 수정 없이 추가할 수 있는 운영 도구로, 모듈/플러그인/템플릿 관리와 동일한 라이프사이클(설치 → 활성화 → 업데이트 → 제거 + 자동 백업/롤백) 을 제공합니다.
+An operations tool for adding a new language without touching the core, with the same lifecycle as module, plugin, and template management (install → activate → update → remove, with automatic backup and rollback).

-| 영역 | 동작 |
+| Area | Behavior |
 | --- | --- |
-| 설치 경로 | ZIP 업로드 / GitHub URL / `lang-packs/_bundled` 번들 디렉토리 (코어 업데이트 시 일괄 동기화) |
-| 적용 범위 | 코어, 모듈, 플러그인, 템플릿 별도 적용 — 모듈 언어팩은 해당 코어 언어팩이 활성일 때만 활성화 |
-| 사용자 수정 보존 | 다국어 JSON 컬럼은 sub-key 단위 (`name.ko` / `name.ja`) 로 user override 기록 — 한 언어 라벨만 수정해도 그 언어만 보존, 신규 언어는 자동 동기화 |
-| 활성화 시점 | 활성/비활성 시 영향받는 모듈/플러그인의 entity 시더가 자동 재실행 → 메뉴·권한·역할·매니페스트·알림 라벨 즉시 DB 반영 |
-| 가상 보호 행 | 코어/번들 확장에 내장된 한국어/영어는 별도 설치 없이 항상 활성/보호 상태로 노출 (수정/제거 차단) |
-| 보안 | 언어 번역 외의 PHP 실행 코드 포함 시 설치 차단 |
+| Install paths | ZIP upload / GitHub URL / the `lang-packs/_bundled` bundled directory (synchronized in bulk on core updates) |
+| Scope | Applied separately to the core, modules, plugins, and templates — a module pack activates only while the matching core pack is active |
+| Preserving operator edits | Multilingual JSON columns record user overrides per sub-key (`name.ko` / `name.ja`), so editing one language's label preserves only that language while new languages sync automatically |
+| Activation effects | On activation or deactivation, the entity seeders of affected modules and plugins re-run, so menus, permissions, roles, manifests, and notification labels reach the database immediately |
+| Virtual protected rows | Korean and English are built into the core and bundled extensions and are always exposed as active and protected (editing and removal are blocked) |
+| Security | Installation is blocked if a pack contains executable PHP beyond language translations |

-공식 일본어(ja) 번들 12종(코어 + 주요 모듈/플러그인/템플릿) 이 즉시 사용 가능하며, 인스톨러 4단계에서 모듈/플러그인/템플릿 선택과 종속된 언어팩 카드가 자동 연동되어 함께 설치할 수 있습니다.
+Sixteen official Japanese (ja) bundled packs — the core plus the main modules, plugins, and templates — are ready to use, and step 4 of the installer links language pack cards to your module, plugin, and template selection so they can be installed together.

-> 상세: [docs/extension/language-packs.md](docs/extension/language-packs.md)
+> Details: [docs/extension/language-packs.md](docs/extension/language-packs.md) (Korean)

-#### 6. 본인인증 (Identity Verification)
+#### 6. Identity verification

-회원가입·비밀번호 재설정·민감 작업·결제 직전 등 모든 본인인증 시점을 라우트/훅 단위 선언형 정책으로 통합 관리합니다.
+Every verification point — signup, password reset, sensitive operations, the moment before payment — is managed centrally through declarative route/hook-level policies.

 ```text
 ┌────────────────────┐    ┌─────────────────────┐    ┌──────────────────────┐
 │ Policy             │    │ Purpose             │    │ Provider             │
-│ (강제 시점·실패 모드│    │ (인증 목적·허용 채널│    │ (메일·KCP·이니시스   │
-│  ·단계·conditions) │ ◀▶ │  ·source 추적)      │ ◀▶ │  ·SMS·외부 IDV ...)  │
+│ (enforcement point │    │ (verification goal, │    │ (mail, KCP, Inicis,  │
+│  failure mode,     │ ◀▶ │  allowed channels,  │ ◀▶ │  SMS, external IDV)  │
+│  step, conditions) │    │  source tracking)   │    │                      │
 └────────────────────┘    └─────────────────────┘    └──────────────────────┘
            │                                                  │
-            └──────────▶ Message Template (정책×목적 매핑) ◀───┘
+            └──────────▶ Message Template (policy × purpose) ◀──┘
                                    │
                              GenericNotification
 ```

- **정책 SSoT** — 정책 enable 토글이 라우트 코드 수정 없이 즉시 적용. 모든 API 라우트가 정책 DB 와 자동 매칭
- **428 인터셉터** — 서버가 HTTP 428 응답을 반환하면 프론트엔드가 자동으로 인증 모달을 띄우고 인증 성공 시 원 요청을 자동 재실행
- **선언형 등록** — 모듈/플러그인은 `module.php::getIdentityPolicies()` / `getIdentityPurposes()` / `getIdentityMessages()` 만 선언하면 활성화/업데이트 시 자동 등록되며 운영자 편집값 보존
- **메시지 템플릿** — 프로바이더와 (목적/정책)별로 다국어 제목/본문을 개별 정의. 정책 → 목적 → 프로바이더 기본값 순서로 fallback
- **외부 Provider 슬롯** — 플러그인이 KCP·PortOne·토스인증·Stripe Identity 등을 G7 표준 Extension Point 패턴으로 자기 SDK UI 를 주입 가능
- **이력 관리** — 관리자 화면에서 인증 수단 탭, 통합 검색, 상태/목적/채널/IP 멀티 필터, 보관주기(180일) 일괄 파기 제공
+- **Policy as the single source of truth** — toggling a policy takes effect immediately without editing route code. Every API route matches against the policy database automatically
+- **428 interceptor** — when the server returns HTTP 428, the frontend opens a verification modal automatically and replays the original request once verification succeeds
+- **Declarative registration** — modules and plugins declare `module.php::getIdentityPolicies()` / `getIdentityPurposes()` / `getIdentityMessages()`, and those are registered automatically on activation or update while preserving operator edits
+- **Message templates** — define multilingual subjects and bodies per provider and per purpose/policy, falling back in the order policy → purpose → provider default
+- **External provider slots** — plugins can inject their own SDK UI for services such as KCP, PortOne, Toss verification, or Stripe Identity through the standard G7 extension-point pattern
+- **History management** — the admin screen offers tabs per verification method, unified search, multi-filters for status/purpose/channel/IP, and bulk destruction by retention period (180 days)

-> 상세: [docs/backend/identity-policies.md](docs/backend/identity-policies.md), [docs/backend/identity-providers.md](docs/backend/identity-providers.md), [docs/backend/identity-messages.md](docs/backend/identity-messages.md)
+> Details: [docs/backend/identity-policies.md](docs/backend/identity-policies.md), [docs/backend/identity-providers.md](docs/backend/identity-providers.md), [docs/backend/identity-messages.md](docs/backend/identity-messages.md) (Korean)

 ---

-## 빠른 시작
+## Quick Start

-### 시스템 요구사항
+### System requirements

- PHP 8.2+ (필수 확장 30개 포함)
- MySQL 8.0+ 또는 MariaDB 10.3+ (utf8mb4)
- Node.js 20+ (빌드 시에만 필요)
+- PHP 8.2+ with the required extensions (16 in total), including `ctype`, `curl`, `dom`, `fileinfo`, `json`, `mbstring`, `openssl`, `pdo_mysql`, `tokenizer`, `xml`, and `zip`. Additional extensions (`gd`/`imagick`, `intl`, `redis`, `bcmath`, and others) are optional and only needed for the features that use them — see [docs/requirements.md](docs/requirements.md)
+- MySQL 8.0+ or MariaDB 10.3+ (utf8mb4)
 - Composer 2.x
+- Node.js 20+ (only needed when building frontend assets)
+- A web server (Apache or Nginx) with the document root pointed at `public/`
+- Redis 6.0+ (optional — recommended for cache and queue in production)

-### 설치
+### Installation

 ```bash
-# 1. 프로젝트 클론
+# 1. Clone the project
 git clone https://github.com/gnuboard/g7.git
 cd g7

-# 2. 환경 설정 파일 복사
+# 2. Install PHP dependencies
+composer install
+
+# 3. Copy the environment file
 cp .env.example .env

-# 3. 브라우저에서 /install 접속 → 설치 마법사 진행
+# 4. Point your web server's document root at the public/ directory,
+#    then open /install in a browser and follow the setup wizard
 ```

-> 상세 설치 가이드는 [INSTALL.md](INSTALL.md)를 참조하세요.
+The setup wizard creates the application key, configures the database connection, runs the migrations, and lets you choose which modules, plugins, templates, and language packs to install. Once setup completes, the installer endpoints are blocked automatically (HTTP 410).
+
+> Detailed installation guide (Korean): [INSTALL.md](INSTALL.md)

 ---

-## 기본 제공 확장
+## Bundled Extensions

-### 모듈
+### Modules

-| 모듈 | 설명 |
-|------|------|
-| **sirsoft-board** | 게시판 — 다중 게시판, 댓글, 파일 첨부 |
-| **sirsoft-ecommerce** | 쇼핑몰 — 상품, 주문, 결제, 배송, 쿠폰, 상품 문의 |
-| **sirsoft-page** | 페이지 — 정적 콘텐츠 관리 |
+| Module | Description |
+|--------|-------------|
+| **sirsoft-board** | Boards — multiple boards, comments, file attachments |
+| **sirsoft-ecommerce** | Storefront — products, orders, payments, shipping, coupons, product inquiries |
+| **sirsoft-page** | Pages — static content management |

-### 플러그인
+### Plugins

-| 플러그인 | 설명 |
-|---------|------|
-| **sirsoft-pay_kginicis** | KG이니시스 결제 연동 |
-| **sirsoft-verification_kginicis** | KG이니시스 본인인증 |
-| **sirsoft-daum_postcode** | 다음 우편번호 검색 |
-| **sirsoft-marketing** | 마케팅 도구 |
-| **sirsoft-ckeditor5** | CKEditor 5 에디터 |
-| **sirsoft-gdpr** | 개인정보 보호(GDPR) |
+| Plugin | Description |
+|--------|-------------|
+| **sirsoft-pay_kginicis** | KG Inicis payment integration (Korean payment gateway) |
+| **sirsoft-pay_nicepayments** | NICE Payments integration (Korean payment gateway, unified checkout) |
+| **sirsoft-pay_nhnkcp** | NHN KCP payment integration (Korean payment gateway, Standard Pay) |
+| **sirsoft-tosspayments** | Toss Payments integration (Korean payment gateway) |
+| **sirsoft-verification_kginicis** | KG Inicis identity verification (Korean identity verification) |
+| **sirsoft-verification_nhnkcp** | NHN KCP mobile identity verification (Korean identity verification) |
+| **sirsoft-daum_postcode** | Daum postcode lookup (Korean address search) |
+| **sirsoft-marketing** | Marketing tools |
+| **sirsoft-ckeditor5** | CKEditor 5 editor |
+| **sirsoft-gdpr** | Privacy and GDPR support |
+| **sirsoft-message_bizppurio** | Bizppurio messaging (SMS/LMS and KakaoTalk alimtalk delivery) |

-### 템플릿
+### Templates

-| 템플릿 | 설명 |
-|--------|------|
-| **sirsoft-admin_basic** | 관리자 기본 템플릿 |
-| **sirsoft-basic** | 사용자 기본 템플릿 |
+| Template | Description |
+|----------|-------------|
+| **sirsoft-admin_basic** | Default admin template |
+| **sirsoft-basic** | Default user template |

-### 번들 언어팩
+### Bundled language packs

-설치 시 함께 동반 설치할 수 있는 공식 언어팩입니다. 코어 + 주요 모듈/플러그인/템플릿이 일관된 번역으로 즉시 사용 가능합니다.
+Official language packs you can install alongside the initial setup, so the core and the main modules, plugins, and templates share one consistent translation from the start.

-| 식별자 | 설명 |
-| ------ | ---- |
-| **g7-core-ja** | 코어 일본어 |
-| **g7-module-sirsoft-board-ja** | 게시판 모듈 일본어 |
-| **g7-module-sirsoft-ecommerce-ja** | 이커머스 모듈 일본어 |
-| **g7-module-sirsoft-page-ja** | 페이지 모듈 일본어 |
-| **g7-plugin-sirsoft-ckeditor5-ja** | CKEditor5 플러그인 일본어 |
-| **g7-plugin-sirsoft-daum_postcode-ja** | 다음 우편번호 플러그인 일본어 |
-| **g7-plugin-sirsoft-gdpr-ja** | 개인정보 보호(GDPR) 플러그인 일본어 |
-| **g7-plugin-sirsoft-marketing-ja** | 마케팅 플러그인 일본어 |
-| **g7-plugin-sirsoft-pay_kginicis-ja** | KG이니시스 결제 플러그인 일본어 |
-| **g7-plugin-sirsoft-verification_kginicis-ja** | KG이니시스 본인인증 플러그인 일본어 |
-| **g7-template-sirsoft-admin_basic-ja** | 관리자 기본 템플릿 일본어 |
-| **g7-template-sirsoft-basic-ja** | 사용자 기본 템플릿 일본어 |
+| Identifier | Description |
+| ---------- | ----------- |
+| **g7-core-ja** | Core, Japanese |
+| **g7-module-sirsoft-board-ja** | Board module, Japanese |
+| **g7-module-sirsoft-ecommerce-ja** | E-commerce module, Japanese |
+| **g7-module-sirsoft-page-ja** | Page module, Japanese |
+| **g7-plugin-sirsoft-ckeditor5-ja** | CKEditor 5 plugin, Japanese |
+| **g7-plugin-sirsoft-daum_postcode-ja** | Daum postcode plugin, Japanese |
+| **g7-plugin-sirsoft-gdpr-ja** | Privacy/GDPR plugin, Japanese |
+| **g7-plugin-sirsoft-marketing-ja** | Marketing plugin, Japanese |
+| **g7-plugin-sirsoft-message_bizppurio-ja** | Bizppurio messaging plugin, Japanese |
+| **g7-plugin-sirsoft-pay_kginicis-ja** | KG Inicis payment plugin, Japanese |
+| **g7-plugin-sirsoft-pay_nicepayments-ja** | NICE Payments plugin, Japanese |
+| **g7-plugin-sirsoft-pay_nhnkcp-ja** | NHN KCP payment plugin, Japanese |
+| **g7-plugin-sirsoft-tosspayments-ja** | Toss Payments plugin, Japanese |
+| **g7-plugin-sirsoft-verification_kginicis-ja** | KG Inicis identity verification plugin, Japanese |
+| **g7-plugin-sirsoft-verification_nhnkcp-ja** | NHN KCP mobile identity verification plugin, Japanese |
+| **g7-template-sirsoft-admin_basic-ja** | Default admin template, Japanese |
+| **g7-template-sirsoft-basic-ja** | Default user template, Japanese |

-> 한국어/영어는 코어/번들 확장에 내장되어 있으며 설치 없이 항상 활성 상태로 동작합니다. 새 언어는 ZIP 또는 GitHub URL 로 자유롭게 추가할 수 있습니다.
+> Korean and English are built into the core and bundled extensions and are always active without installation. Any other language can be added freely from a ZIP file or a GitHub URL.

-### 학습용 샘플 확장
+### Sample extensions for learning

-확장 시스템 학습을 위한 최소 구현 샘플입니다. 관리자 UI 에서 "숨김 포함" 토글로 노출되며 CLI 에서는 항상 보입니다.
+Minimal implementations for learning the extension system. They appear in the admin UI when the "include hidden" toggle is on, and are always visible from the CLI.

-| 식별자 | 종류 | 설명 |
-| ------ | ---- | ---- |
-| **gnuboard7-hello_module** | 모듈 | Memo CRUD + 훅 발행 시연 |
-| **gnuboard7-hello_plugin** | 플러그인 | Action/Filter 훅 구독 시연 |
-| **gnuboard7-hello_admin_template** | Admin 템플릿 | Basic 컴포넌트 최소 셋 |
-| **gnuboard7-hello_user_template** | User 템플릿 | 홈 + Memo 리스트 연동 |
+| Identifier | Type | Description |
+| ---------- | ---- | ----------- |
+| **gnuboard7-hello_module** | Module | Memo CRUD plus a hook publishing demo |
+| **gnuboard7-hello_plugin** | Plugin | Action/filter hook subscription demo |
+| **gnuboard7-hello_admin_template** | Admin template | A minimal set of basic components |
+| **gnuboard7-hello_user_template** | User template | Home page plus a memo list integration |

 ---

-## 비즈니스 모델
+## Business Models

-그누보드7 하나로 다양한 비즈니스를 운영할 수 있습니다.
+One Gnuboard7 installation can run a range of businesses.

-| 모델 | 설명 | 상태 |
-|------|------|------|
-| **커뮤니티** | 게시판, 댓글, 회원 관리 | 정식 |
-| **커머스** | 상품 등록, 주문, 결제, 배송 관리 | 정식 |
+| Model | Description | Status |
+|-------|-------------|--------|
+| **Community** | Boards, comments, member management | Stable |
+| **Commerce** | Product registration, orders, payments, shipping management | Stable |

 ---

-## 기존 그누보드 사용자
+## Migrating from Gnuboard 5

-기존 그누보드5에서 그누보드7으로 전환할 수 있도록, 회원·게시글·상품 등 주요 데이터의 **마이그레이션 툴을 제공할 예정**입니다.
+A migration tool from Gnuboard 5 is planned.

 ---

-## 문서
+## Documentation

-| 문서 | 링크 |
-|------|------|
-| 설치 가이드 | [INSTALL.md](INSTALL.md) |
-| 전체 문서 | [docs/README.md](docs/README.md) |
-| 시스템 요구사항 | [docs/requirements.md](docs/requirements.md) |
-| 백엔드 개발 | [docs/backend/README.md](docs/backend/README.md) |
-| 프론트엔드 개발 | [docs/frontend/README.md](docs/frontend/README.md) |
-| 데이터베이스 | [docs/database-guide.md](docs/database-guide.md) |
-| 확장 시스템 | [docs/extension/README.md](docs/extension/README.md) |
-| 모듈 개발 | [docs/extension/module-basics.md](docs/extension/module-basics.md) |
-| 플러그인 개발 | [docs/extension/plugin-development.md](docs/extension/plugin-development.md) |
-| 템플릿 개발 | [docs/extension/template-basics.md](docs/extension/template-basics.md) |
-| 테스트 | [docs/testing-guide.md](docs/testing-guide.md) |
-| API 레퍼런스 | 준비 중 |
+> Documentation is currently available in Korean only. English documentation is planned.
+
+| Document | Link |
+|----------|------|
+| Installation guide | [INSTALL.md](INSTALL.md) |
+| Full documentation | [docs/README.md](docs/README.md) |
+| System requirements | [docs/requirements.md](docs/requirements.md) |
+| Backend development | [docs/backend/README.md](docs/backend/README.md) |
+| Frontend development | [docs/frontend/README.md](docs/frontend/README.md) |
+| Database | [docs/database-guide.md](docs/database-guide.md) |
+| Extension system | [docs/extension/README.md](docs/extension/README.md) |
+| Module development | [docs/extension/module-basics.md](docs/extension/module-basics.md) |
+| Plugin development | [docs/extension/plugin-development.md](docs/extension/plugin-development.md) |
+| Template development | [docs/extension/template-basics.md](docs/extension/template-basics.md) |
+| Testing | [docs/testing-guide.md](docs/testing-guide.md) |
+| API reference | [docs/backend/api/README.md](docs/backend/api/README.md) |
+| API documentation policy | [docs/backend/api-documentation.md](docs/backend/api-documentation.md) |

 ---

-## 기여하기
+## Contributing

-그누보드7은 오픈소스 프로젝트입니다. 모든 형태의 기여를 환영합니다.
+Gnuboard7 is an open-source project, and contributions of every kind are welcome.

- 버그 리포트 및 기능 제안: [GitHub Issues](https://github.com/gnuboard/g7/issues)
- 코드 스타일: Laravel Pint (PSR-12)
- 테스트: PHPUnit (백엔드) + Vitest (프론트엔드)
- AI 협업: AI 에이전트용 개발 규칙 명세(AGENTS.md)와 MCP 디버깅 도구를 내장하고 있어, AI 도구와 자연스럽게 협업할 수 있습니다
+- Bug reports and feature proposals: [GitHub Issues](https://github.com/gnuboard/g7/issues)
+- Code style: Laravel Pint (PSR-12)
+- Testing: PHPUnit (backend) + Vitest (frontend)
+- AI collaboration: the repository ships a development rule specification for AI agents (AGENTS.md) along with MCP debugging tools, so AI tooling fits naturally into the workflow

 ---

-## 만든 사람들
+## Team

-**[SIRSOFT](https://sir.kr)** 에서 개발하고 있습니다.
+Developed by **[SIRSOFT](https://sir.kr)**.

 ### Core Team

@@ -489,37 +523,64 @@ cp .env.example .env
  <a href="https://github.com/thisgun"><img src="https://github.com/thisgun.png" width="60" alt="thisgun"></a>
 </p>

-### Contributors
+### Community Contributors

-커뮤니티 기여자 목록은 [GitHub Contributors](https://github.com/gnuboard/g7/graphs/contributors)에서 확인할 수 있습니다.
+Thanks to everyone who reported an issue or suggested a feature that shipped — the list below is compiled from the attributions in our changelogs.
+
+<!-- community-contributors:start -->
+<p>
+  <a href="https://github.com/jiwonpapa" title="jiwonpapa"><img src="https://github.com/jiwonpapa.png" width="48" alt="jiwonpapa"></a>
+  <a href="https://github.com/Tuwasduliebst" title="Tuwasduliebst"><img src="https://github.com/Tuwasduliebst.png" width="48" alt="Tuwasduliebst"></a>
+  <a href="https://github.com/glitter-gim" title="glitter-gim"><img src="https://github.com/glitter-gim.png" width="48" alt="glitter-gim"></a>
+  <a href="https://github.com/jordy-bitree" title="jordy-bitree"><img src="https://github.com/jordy-bitree.png" width="48" alt="jordy-bitree"></a>
+  <a href="https://github.com/laelbe" title="laelbe"><img src="https://github.com/laelbe.png" width="48" alt="laelbe"></a>
+  <a href="https://github.com/lyg-kaban" title="lyg-kaban"><img src="https://github.com/lyg-kaban.png" width="48" alt="lyg-kaban"></a>
+  <a href="https://github.com/bigmsg" title="bigmsg"><img src="https://github.com/bigmsg.png" width="48" alt="bigmsg"></a>
+  <a href="https://github.com/abc101" title="abc101"><img src="https://github.com/abc101.png" width="48" alt="abc101"></a>
+  <a href="https://github.com/hwaryeon1234" title="hwaryeon1234"><img src="https://github.com/hwaryeon1234.png" width="48" alt="hwaryeon1234"></a>
+  <a href="https://github.com/koojunho" title="koojunho"><img src="https://github.com/koojunho.png" width="48" alt="koojunho"></a>
+  <a href="https://github.com/yks118" title="yks118"><img src="https://github.com/yks118.png" width="48" alt="yks118"></a>
+  <a href="https://github.com/kitrio" title="kitrio"><img src="https://github.com/kitrio.png" width="48" alt="kitrio"></a>
+  <a href="https://github.com/movielee2020" title="movielee2020"><img src="https://github.com/movielee2020.png" width="48" alt="movielee2020"></a>
+  <a href="https://github.com/ChoDongHyeon" title="ChoDongHyeon"><img src="https://github.com/ChoDongHyeon.png" width="48" alt="ChoDongHyeon"></a>
+  <a href="https://github.com/comtylove-netizen" title="comtylove-netizen"><img src="https://github.com/comtylove-netizen.png" width="48" alt="comtylove-netizen"></a>
+  <a href="https://github.com/devrhee16" title="devrhee16"><img src="https://github.com/devrhee16.png" width="48" alt="devrhee16"></a>
+  <a href="https://github.com/GyusoonKim" title="GyusoonKim"><img src="https://github.com/GyusoonKim.png" width="48" alt="GyusoonKim"></a>
+  <a href="https://github.com/Lastorder-DC" title="Lastorder-DC"><img src="https://github.com/Lastorder-DC.png" width="48" alt="Lastorder-DC"></a>
+  <a href="https://github.com/miles44229" title="miles44229"><img src="https://github.com/miles44229.png" width="48" alt="miles44229"></a>
+  <a href="https://github.com/minyho" title="minyho"><img src="https://github.com/minyho.png" width="48" alt="minyho"></a>
+</p>
+<!-- community-contributors:end -->
+
+The list of code contributors is available on [GitHub Contributors](https://github.com/gnuboard/g7/graphs/contributors).

 ---

-## 커뮤니티
+## Community

-| 채널 | 링크 |
-|------|------|
+| Channel | Link |
+|---------|------|
 | GitHub | [github.com/gnuboard/g7](https://github.com/gnuboard/g7) |
-| SIR 커뮤니티 | [sir.kr](https://sir.kr) |
-| 문의 | minsup@sir.kr |
+| SIR community (Korean) | [sir.kr](https://sir.kr) |
+| Contact | minsup@sir.kr |

 ---

-## 변경 기록
+## Changelog

-최근 변경된 사항에 대한 자세한 내용은 [CHANGELOG](CHANGELOG.md)를 참고해 주세요.
+For details on recent changes, see the [CHANGELOG](CHANGELOG.md) (Korean).

 ---

-## 보안 취약점
+## Security Vulnerabilities

-보안 취약점을 발견하셨다면 [SIR 문의게시판](https://sir.kr/boards/co_qa)에 비밀글로 제보해 주세요.
+If you discover a security vulnerability, please report it as a private post on the [SIR inquiry board](https://sir.kr/boards/co_qa) (Korean board), or email minsup@sir.kr.

 ---

-## 라이선스
+## License

-그누보드7은 [MIT 라이선스](LICENSE)에 따라 배포되는 오픈소스 소프트웨어입니다.
+Gnuboard7 is open-source software distributed under the [MIT License](LICENSE).

 Copyright (c) 2026 SIRSOFT

@@ -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(),
@@ -0,0 +1,141 @@
+<?php
+
+namespace App\Benchmark\Axes;
+
+use App\Benchmark\Contracts\BenchmarkAxisRunner;
+use App\Benchmark\DTO\BenchmarkProfile;
+use App\Benchmark\DTO\BenchmarkResult;
+use App\Benchmark\DTO\BenchmarkRunOptions;
+use App\Benchmark\QueryCollector;
+use App\Enums\BenchmarkAxis;
+use Illuminate\Support\Facades\Artisan;
+use Symfony\Component\Console\Output\BufferedOutput;
+
+/**
+ * 배치 축 실행기 — 배치 커맨드 소요 시간 + 피크 메모리
+ *
+ * 배치는 한 번에 대량을 처리하므로 "느려짐"이 시간보다 메모리로 먼저 드러납니다(청크
+ * 없이 전건 로딩 → OOM). 그래서 시간과 함께 피크 메모리를 함께 잽니다.
+ *
+ * 다른 축과 달리 트랜잭션으로 감싸지 않습니다 — 배치 커맨드는 내부에서 커밋하거나 DDL 을
+ * 실행할 수 있고, 대량 처리를 긴 트랜잭션에 담으면 락 보유 시간이 계측 자체보다 위험해집니다.
+ * 대신 데이터를 변경하는 배치는 `--allow-write` 없이는 실행하지 않습니다.
+ */
+class BatchAxisRunner implements BenchmarkAxisRunner
+{
+    public function __construct(private readonly QueryCollector $collector) {}
+
+    /**
+     * {@inheritDoc}
+     */
+    public function axis(): BenchmarkAxis
+    {
+        return BenchmarkAxis::Batch;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function run(BenchmarkProfile $profile, BenchmarkRunOptions $options, ?\Closure $onProgress = null): BenchmarkResult
+    {
+        $notify = $onProgress ?? static fn (string $message) => 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';
+    }
+}
@@ -0,0 +1,350 @@
+<?php
+
+namespace App\Benchmark\Axes;
+
+use App\Benchmark\Contracts\BenchmarkAxisRunner;
+use App\Benchmark\DTO\BenchmarkProfile;
+use App\Benchmark\DTO\BenchmarkResult;
+use App\Benchmark\DTO\BenchmarkRunOptions;
+use App\Benchmark\SyntheticSeeder;
+use App\Enums\BenchmarkAxis;
+use Illuminate\Database\Query\Builder;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * 목록 조회 축 실행기 — 깊은 OFFSET 비용을 컬럼 폭 3축으로 계측
+ *
+ * 목록 조회는 OFFSET 이 커질수록 느려지는데, 그 원인이 "건너뛸 행의 넓은 컬럼까지 읽기"
+ * 인지 확인하려면 같은 필터·정렬로 (1) 전체 컬럼 (2) 실제 목록 컬럼 (3) 키 컬럼만 조회한
+ * 비용을 나란히 재야 합니다. 셋째 축이 지연 조인(`PaginatesWithDeferredJoin`)의 inner
+ * 쿼리에 해당하므로, 이 세 값의 배수가 곧 지연 조인 적용의 기대 효과입니다.
+ */
+class ListAxisRunner implements BenchmarkAxisRunner
+{
+    /**
+     * 목록 1페이지 상한 (OFFSET 스캔 비용 대비 무시할 수준이라 고정)
+     */
+    private const PAGE_LIMIT = 20;
+
+    /**
+     * 필터 선언에 쓸 수 있는 연산자 (닫힌 집합)
+     *
+     * @var array<int, string>
+     */
+    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<int, string>  $columns  후보 컬럼
+     * @return array<int, string> 존재하는 컬럼 목록
+     */
+    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<int, array{0: string, 1: string}>  $order  후보 정렬
+     * @return array<int, array{0: string, 1: string}> 적용 가능한 정렬 목록
+     */
+    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<int, string>  $columns  select 컬럼
+     * @param  array<int, array{0: string, 1: string}>  $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<int, string>  $columns  select 컬럼
+     * @param  array<int, array{0: string, 1: string}>  $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<string, mixed>  $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<string, mixed>  $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<int, string>  $columns  select 컬럼
+     * @param  array<int, array{0: string, 1: string}>  $order  정렬
+     * @param  int  $offset  OFFSET
+     * @return array<int, string> 실행 계획 요약 줄 목록
+     */
+    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);
+    }
+}
@@ -0,0 +1,261 @@
+<?php
+
+namespace App\Benchmark\Axes;
+
+use App\Benchmark\BenchmarkIdentity;
+use App\Benchmark\Contracts\BenchmarkAxisRunner;
+use App\Benchmark\DTO\BenchmarkProfile;
+use App\Benchmark\DTO\BenchmarkResult;
+use App\Benchmark\DTO\BenchmarkRunOptions;
+use App\Benchmark\QueryCollector;
+use App\Enums\BenchmarkAxis;
+use Illuminate\Contracts\Http\Kernel as HttpKernel;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
+use Illuminate\Support\Facades\Route;
+
+/**
+ * 화면 응답 축 실행기 — 화면 1장의 응답 시간 + 실행 쿼리 건수 + N+1 후보
+ *
+ * 사용자가 체감하는 단위가 "화면 한 장"이므로 네 축 중 값어치가 가장 큽니다. 목록 SELECT
+ * 는 빠른데 화면이 느린 경우(관계 지연 로딩으로 인한 N+1, 권한 조회 반복 등)를 잡는 것이
+ * 이 축의 목적입니다.
+ *
+ * 실행 방식은 라우트를 **HTTP 커널로 내부 요청** 처리하는 것입니다. `Route::dispatch` 로
+ * 라우트만 때리면 전역 미들웨어(인증·권한·로케일·타임존)를 건너뛰어 화면과 다른 것을 재게
+ * 됩니다. 커널을 쓰면 실제 요청과 같은 경로를 지납니다.
+ *
+ * 계측 계정 생성과 요청 처리 전체를 롤백되는 트랜잭션으로 감싸므로, 계측이 데이터에 흔적을
+ * 남기지 않습니다(`BenchmarkIdentity::withRolledBackTransaction`).
+ */
+class ScreenAxisRunner implements BenchmarkAxisRunner
+{
+    public function __construct(
+        private readonly BenchmarkIdentity $identity,
+        private readonly QueryCollector $collector,
+    ) {}
+
+    /**
+     * {@inheritDoc}
+     */
+    public function axis(): BenchmarkAxis
+    {
+        return BenchmarkAxis::Screen;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function run(BenchmarkProfile $profile, BenchmarkRunOptions $options, ?\Closure $onProgress = null): BenchmarkResult
+    {
+        if ($profile->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<string, mixed>  $query  쿼리스트링
+     * @param  int  $runs  측정 횟수
+     * @param  BenchmarkRunOptions  $options  실행 옵션
+     * @param  \Closure|null  $onProgress  진행 콜백
+     * @return array{status: int, total_ms: float, summary: array<string, mixed>, acting_user: array<string, mixed>} 계측 결과
+     */
+    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<string, mixed>  $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];
+    }
+}
@@ -0,0 +1,227 @@
+<?php
+
+namespace App\Benchmark\Axes;
+
+use App\Benchmark\BenchmarkIdentity;
+use App\Benchmark\Contracts\BenchmarkAxisRunner;
+use App\Benchmark\DTO\BenchmarkProfile;
+use App\Benchmark\DTO\BenchmarkResult;
+use App\Benchmark\DTO\BenchmarkRunOptions;
+use App\Benchmark\QueryCollector;
+use App\Enums\BenchmarkAxis;
+
+/**
+ * 쓰기 축 실행기 — 저장 경로 1회 소요 시간
+ *
+ * 목록 조회와 달리 저장 경로는 커맨드가 스스로 조립할 수 없습니다(주문 생성 하나에 재고·
+ * 쿠폰·마일리지·알림이 얽힘). 그래서 실행 자체는 소유 확장이 선언한 콜백에 맡기고, 이
+ * 실행기는 시간·쿼리 건수 계측과 안전장치만 담당합니다.
+ *
+ * 콜백은 `'Fqcn'`(invokable) 또는 `['Fqcn', 'method']` 형식만 허용합니다 — 코어 선언은
+ * `config/benchmark.php` 에 있고 이 파일은 `config:cache` 대상이라 클로저를 담을 수 없기
+ * 때문입니다. 확장 선언도 같은 스키마를 쓰므로 형식을 통일합니다.
+ *
+ * 선언 필드는 세 개입니다 — `prepare`(계측 제외 선행 준비, 회차마다 실행), `callback`
+ * (계측 대상, prepare 반환값을 인자로 받음), `cleanup`(트랜잭션이 되돌리지 못하는 잔여물 정리).
+ *
+ * 계측으로 생긴 행은 롤백되는 트랜잭션으로 되돌립니다. 트랜잭션이 되돌리지 못하는 것
+ * (파일·캐시·외부 호출)은 프로파일이 선언한 `cleanup` 콜백이 정리합니다.
+ */
+class WriteAxisRunner implements BenchmarkAxisRunner
+{
+    public function __construct(
+        private readonly BenchmarkIdentity $identity,
+        private readonly QueryCollector $collector,
+    ) {}
+
+    /**
+     * {@inheritDoc}
+     */
+    public function axis(): BenchmarkAxis
+    {
+        return BenchmarkAxis::Write;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function run(BenchmarkProfile $profile, BenchmarkRunOptions $options, ?\Closure $onProgress = null): BenchmarkResult
+    {
+        $notify = $onProgress ?? static fn (string $message) => 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<int, float>, queries: array<int, array{sql: string, time: float}>} 계측 결과
+     */
+    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,
+        ];
+    }
+}
@@ -0,0 +1,144 @@
+<?php
+
+namespace App\Benchmark;
+
+use App\Enums\ExtensionOwnerType;
+use App\Models\Permission;
+use App\Models\Role;
+use App\Models\User;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
+
+/**
+ * 화면 계측용 인증 주체 해석기
+ *
+ * 관리자 화면의 응답 시간은 로그인 상태에서만 잴 수 있습니다. 두 방식을 지원합니다.
+ *
+ *   기본  — 프로파일이 선언한 권한만 가진 임시 관리자를 즉석 생성해 Sanctum 토큰 발급
+ *   `--as` — 기존 계정을 지정 (그 계정의 실제 역할/권한으로 재측정)
+ *
+ * 두 경로 모두 계정/역할/토큰 생성이라는 **쓰기**를 동반하므로, 호출자가 열어둔 트랜잭션
+ * 안에서 수행하고 계측 후 롤백해 흔적을 남기지 않습니다(`withRolledBackTransaction`).
+ * 트랜잭션이 열려 있으면 Laravel 이 읽기 쿼리도 write PDO 로 보내므로(`Connection::getReadPdo`
+ * 의 `transactions > 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<int, string>  $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<int, string>  $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();
+    }
+}
@@ -0,0 +1,275 @@
+<?php
+
+namespace App\Benchmark;
+
+use App\Benchmark\DTO\BenchmarkProfile;
+use App\Contracts\Extension\ModuleManagerInterface;
+use App\Contracts\Extension\PluginManagerInterface;
+use App\Enums\BenchmarkAxis;
+
+/**
+ * 계측 프로파일 레지스트리 — 코어 config + 활성 확장 선언 수집
+ *
+ * 계측 대상은 "지금 이 설치본에 실제로 존재하는 것"이어야 하므로, 커맨드에 대상을
+ * 하드코딩하지 않고 소유자가 선언한 것을 런타임에 모읍니다. 코어는
+ * `config/benchmark.php`, 확장은 `getBenchmarkProfiles()` 오버라이드가 선언 지점입니다
+ * (채널·알림 정의 등 기존 확장 선언 훅과 동일한 수집 모델).
+ *
+ * 확장 선언은 격리 호출합니다 — 확장 하나의 잘못된 선언이 전체 목록을 날리면 계측 자체를
+ * 못 하게 되므로, 실패한 선언만 사유와 함께 `warnings()` 로 드러내고 나머지는 살립니다.
+ * 조용히 버리지는 않습니다(버려진 선언이 곧 계측 사각이 됩니다).
+ */
+class BenchmarkProfileRegistry
+{
+    /**
+     * 수집된 프로파일 (정규화 키 → 프로파일)
+     *
+     * @var array<string, BenchmarkProfile>|null
+     */
+    private ?array $profiles = null;
+
+    /**
+     * 수집 중 발생한 선언 오류 메시지
+     *
+     * @var array<int, string>
+     */
+    private array $warnings = [];
+
+    public function __construct(
+        private readonly ModuleManagerInterface $moduleManager,
+        private readonly PluginManagerInterface $pluginManager,
+    ) {}
+
+    /**
+     * 모든 프로파일을 정규화 키 기준으로 반환합니다.
+     *
+     * @return array<string, BenchmarkProfile> 정규화 키 → 프로파일
+     */
+    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<string, BenchmarkProfile> 정규화 키 → 프로파일
+     */
+    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<int, string> 경고 메시지
+     */
+    public function warnings(): array
+    {
+        $this->all();
+
+        return $this->warnings;
+    }
+
+    /**
+     * 코어 프로파일을 수집합니다.
+     *
+     * @return array<int, BenchmarkProfile> 코어 프로파일 목록
+     */
+    private function collectCore(): array
+    {
+        $declared = config('benchmark.profiles', []);
+
+        return $this->normalize(is_array($declared) ? $declared : [], 'core', 'core');
+    }
+
+    /**
+     * 활성 모듈/플러그인 프로파일을 수집합니다.
+     *
+     * @return array<int, BenchmarkProfile> 확장 프로파일 목록
+     */
+    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<string, mixed> 선언 배열 (실패 시 빈 배열)
+     */
+    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<string, mixed>  $declared  선언 배열 (키 → 정의)
+     * @param  string  $sourceKind  출처 종류 (core|module|plugin)
+     * @param  string  $sourceIdentifier  출처 식별자
+     * @return array<int, BenchmarkProfile> 정규화된 프로파일 목록
+     */
+    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;
+    }
+}
@@ -0,0 +1,226 @@
+<?php
+
+namespace App\Benchmark;
+
+use App\Benchmark\DTO\BenchmarkResult;
+use App\Benchmark\DTO\BenchmarkRunOptions;
+use App\Enums\BenchmarkAxis;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * 계측 결과 출력기 — 표준출력 표 / JSON / 마크다운 리포트
+ *
+ * 축을 모르고도 출력할 수 있는 이유는 `BenchmarkResult` 가 표시용 표와 기계 판독용 수치를
+ * 함께 담기 때문입니다. 축이 늘어도 이 클래스는 고치지 않습니다.
+ *
+ * 마크다운 리포트에 환경 정보를 반드시 함께 적습니다 — 계측값은 실행 머신·DB 버전·
+ * OPcache 여부에 종속되므로, 환경이 빠진 수치는 다른 리포트와 비교할 수 없는 숫자입니다.
+ * 문서에 옮길 수치는 이 경로로만 산출해 눈대중 기재를 막는 것이 `--report` 의 목적입니다.
+ */
+class BenchmarkReporter
+{
+    /**
+     * 실행 환경 정보를 수집합니다.
+     *
+     * @return array<string, string> 항목 → 값
+     */
+    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<int, BenchmarkResult>  $results  계측 결과
+     * @param  BenchmarkRunOptions  $options  실행 옵션
+     * @param  array<int, string>  $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<int, BenchmarkResult>  $results  계측 결과
+     * @param  BenchmarkRunOptions  $options  실행 옵션
+     * @param  array<int, string>  $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<int, string> 마크다운 줄 목록
+     */
+    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 '-';
+        }
+    }
+}
@@ -0,0 +1,34 @@
+<?php
+
+namespace App\Benchmark\Contracts;
+
+use App\Benchmark\DTO\BenchmarkProfile;
+use App\Benchmark\DTO\BenchmarkResult;
+use App\Benchmark\DTO\BenchmarkRunOptions;
+use App\Enums\BenchmarkAxis;
+
+/**
+ * 계측 축 실행기 계약
+ *
+ * 축이 늘어날 때 커맨드를 고치지 않고 실행기를 추가하도록 분리합니다. 커맨드는
+ * 프로파일의 `type` 으로 실행기를 고르는 일만 합니다.
+ */
+interface BenchmarkAxisRunner
+{
+    /**
+     * 이 실행기가 담당하는 축을 반환합니다.
+     *
+     * @return BenchmarkAxis 담당 축
+     */
+    public function axis(): BenchmarkAxis;
+
+    /**
+     * 프로파일 1건을 계측합니다.
+     *
+     * @param  BenchmarkProfile  $profile  계측 대상
+     * @param  BenchmarkRunOptions  $options  실행 옵션
+     * @param  \Closure|null  $onProgress  진행 상황 콜백 (string $message, 시딩 등 장시간 작업 알림용)
+     * @return BenchmarkResult 계측 결과
+     */
+    public function run(BenchmarkProfile $profile, BenchmarkRunOptions $options, ?\Closure $onProgress = null): BenchmarkResult;
+}
@@ -0,0 +1,97 @@
+<?php
+
+namespace App\Benchmark\DTO;
+
+use App\Enums\BenchmarkAxis;
+
+/**
+ * 계측 프로파일 — 코어 config / 확장 선언에서 수집된 계측 대상 1건 (Value Object)
+ *
+ * 레지스트리가 선언 배열을 검증해 이 객체로 정규화하고, 축 실행기가 그대로 받아 씁니다.
+ * 축별 옵션 스키마가 서로 다르므로 공통 필드(키·축·출처·라벨)만 프로퍼티로 승격하고
+ * 축 고유 옵션은 `options` 에 남깁니다 — 축이 늘 때 VO 를 고치지 않아도 되게 합니다.
+ */
+final readonly class BenchmarkProfile
+{
+    /**
+     * @param  string  $key  선언된 프로파일 키 (확장 내부에서만 고유)
+     * @param  BenchmarkAxis  $axis  계측 축
+     * @param  string  $sourceKind  출처 종류 (core|module|plugin)
+     * @param  string  $sourceIdentifier  출처 식별자 (코어는 'core')
+     * @param  array<string, mixed>  $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<string, mixed> 직렬화 결과
+     */
+    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,
+        ];
+    }
+}
@@ -0,0 +1,68 @@
+<?php
+
+namespace App\Benchmark\DTO;
+
+/**
+ * 계측 결과 1건 — 축 실행기의 산출물 (Value Object)
+ *
+ * 출력기(`BenchmarkReporter`)가 축을 몰라도 표/JSON/마크다운을 만들 수 있도록,
+ * 표시용 표(`headers`/`rows`)와 기계 판독용 수치(`metrics`)를 함께 담습니다.
+ * 축이 늘어날 때 출력기를 고치지 않아도 되는 지점이 여기입니다.
+ */
+final readonly class BenchmarkResult
+{
+    /**
+     * @param  BenchmarkProfile  $profile  계측 대상 프로파일
+     * @param  array<int, string>  $headers  표 헤더
+     * @param  array<int, array<int, string>>  $rows  표 행 (표시용 문자열)
+     * @param  array<string, mixed>  $metrics  기계 판독용 원시 수치
+     * @param  array<int, string>  $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<string, mixed> 직렬화 결과
+     */
+    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,
+        ];
+    }
+}
@@ -0,0 +1,52 @@
+<?php
+
+namespace App\Benchmark\DTO;
+
+/**
+ * 계측 실행 옵션 — 커맨드 옵션을 축 실행기로 한 번 전달하는 값 묶음 (Value Object)
+ *
+ * 축마다 쓰는 옵션이 다르지만(offsets 는 list 축만, allowWrite 는 write/batch 축만)
+ * 실행기 시그니처를 하나로 두기 위해 한 객체로 모읍니다.
+ */
+final readonly class BenchmarkRunOptions
+{
+    /**
+     * @param  array<int, int>  $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<string, mixed> 직렬화 결과
+     */
+    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,
+        ];
+    }
+}
@@ -0,0 +1,203 @@
+<?php
+
+namespace App\Benchmark;
+
+use App\Benchmark\DTO\BenchmarkProfile;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * 목록 프로파일 선언에서 필요한 색인을 도출하고 스키마와 대조합니다.
+ *
+ * 배경: 지연 조인은 inner 가 키 컬럼만 읽게 만들지만, 그 inner 가 **인덱스 순서 그대로**
+ * 끝나야 깊은 OFFSET 이 싸진다. 정렬을 덮는 인덱스가 없으면 inner 도 filesort 로 전체를
+ * 훑으므로 개선 폭이 사라진다. 그런데 어떤 색인이 필요한지는 지금까지 테이블마다 사람이
+ * 손으로 설계했고, 맞는지 검사하는 장치가 없었다.
+ *
+ * 필요한 정보는 이미 계측 프로파일에 선언돼 있다 — `filters` / `order` / `soft_delete` 를
+ * 이으면 그대로 색인 레시피가 된다:
+ *
+ *   (등치 필터 컬럼들 → soft_delete 면 deleted_at → 정렬 컬럼들 → 기본키)
+ *
+ * 이 클래스는 그 도출을 한 곳에 두어, 새 목록이 프로파일을 선언하는 순간 필요한 색인이
+ * 자동으로 드러나게 한다. 색인 설계를 사람의 기억이 아니라 이미 있는 선언에 붙이는 것이라
+ * 호출자가 추가로 선언할 것은 없다.
+ *
+ * 등치가 아닌 필터(`in` / `not in` / 범위)는 선행 컬럼에 넣지 않는다 — 선행 컬럼이 등치로
+ * 고정되지 않으면 뒤따르는 정렬 컬럼을 인덱스 순서로 쓸 수 없기 때문이다. 이 판정을 틀리면
+ * "색인이 있는데도 filesort" 라는, 눈으로는 구분되지 않는 상태를 정상으로 보고하게 된다.
+ */
+class ListIndexAdvisor
+{
+    /** 선행 컬럼으로 쓸 수 있는 연산자 (등치만) */
+    private const EQUALITY_OPERATORS = ['='];
+
+    /**
+     * 프로파일이 요구하는 색인 선행 컬럼 목록을 도출합니다.
+     *
+     * @param  array<string, mixed>  $options  목록 프로파일 옵션
+     * @return array<int, string> 선행 컬럼 순서 (등치 → 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<string, mixed>  $options  목록 프로파일 옵션
+     * @return array{
+     *     table: string|null,
+     *     required: array<int, string>,
+     *     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<string, mixed>  $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<string, BenchmarkProfile>  $profiles  목록 축 프로파일
+     * @return array<int, array<string, mixed>> 프로파일별 점검 결과
+     */
+    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<int, string>  $columns  인덱스 컬럼 순서
+     * @param  array<int, string>  $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);
+    }
+}
@@ -0,0 +1,102 @@
+<?php
+
+namespace App\Benchmark;
+
+use Illuminate\Database\Events\QueryExecuted;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * 실행 쿼리 수집기 — 화면/쓰기/배치 축의 쿼리 건수·시간·N+1 후보 산출
+ *
+ * 목록 SELECT 는 빨라도 화면이 느린 대표적 원인이 N+1 이므로, 응답 시간만 재고 끝내면
+ * 원인을 못 찾습니다. 이 수집기는 계측 구간에서 실행된 쿼리를 모아 건수·DB 시간과, 같은
+ * SQL 이 반복 실행된 그룹(N+1 후보)을 함께 돌려줍니다.
+ *
+ * `DB::listen` 은 한 번 등록하면 해제할 수 없으므로, 리스너는 인스턴스당 한 번만 등록하고
+ * 수집 여부는 플래그로 켰다 끕니다 — 계측 구간 밖의 쿼리가 섞이지 않게 합니다.
+ */
+class QueryCollector
+{
+    /**
+     * 같은 SQL 이 이 횟수 이상 반복되면 N+1 후보로 본다
+     */
+    private const N_PLUS_ONE_THRESHOLD = 5;
+
+    /**
+     * 수집 구간 여부
+     */
+    private bool $collecting = false;
+
+    /**
+     * 수집된 쿼리 (sql, time)
+     *
+     * @var array<int, array{sql: string, time: float}>
+     */
+    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<int, array{sql: string, time: float}>} 반환값과 수집 결과
+     */
+    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<int, array{sql: string, time: float}>  $queries  수집 결과
+     * @return array{count: int, db_ms: float, n_plus_one: array<int, array{count: int, sql: string}>} 요약
+     */
+    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,
+        ];
+    }
+}
@@ -0,0 +1,234 @@
+<?php
+
+namespace App\Benchmark;
+
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Support\Str;
+
+/**
+ * 계측용 합성 행 시딩기
+ *
+ * 깊은 OFFSET 비용은 행 수와 행 폭이 있어야 재현되므로, 계측 전에 대상 테이블을 원하는
+ * 규모까지 채웁니다. 스키마를 introspect 해 NOT NULL + 기본값 없는 컬럼만 타입에 맞춰
+ * 채우므로 계측 대상이 늘 때마다 시더를 따라 만들지 않아도 됩니다.
+ *
+ * 합성 값은 실제 부모 행을 가리키지 않으므로 외래키 제약을 일시 해제합니다. 본 시딩이
+ * 재현하려는 것은 대상 테이블의 OFFSET 스캔 비용(행 수·행 폭)이고 조인은 계측 대상이
+ * 아니므로, 부모 무결성 없이 목적에 충분합니다 — 폐기 가능한 계측용 DB 에서만 쓰는 것을
+ * 전제로 하며, 운영 환경 거부는 호출자(`ListAxisRunner`)가 담당합니다.
+ */
+class SyntheticSeeder
+{
+    /**
+     * 한 번에 삽입할 행 수
+     */
+    private const CHUNK_SIZE = 500;
+
+    /**
+     * 계측용 합성 행을 시딩합니다.
+     *
+     * @param  string  $table  대상 테이블
+     * @param  int  $count  시딩 건수
+     * @param  array<string, mixed>  $overrides  컬럼별 고정값 (실제 조회 조건과 맞추기 위한 지정)
+     * @param  \Closure|null  $onProgress  진행 콜백 (int $inserted, int $total)
+     * @param  array<int, string>  $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<int, array<string, mixed>> 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<int, string>  $names  반드시 채울 컬럼명 목록
+     * @param  array<int, array<string, mixed>>  $already  이미 채우기로 한 컬럼 목록
+     * @return array<int, array<string, mixed>> 추가로 채울 컬럼 정의 목록
+     */
+    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<int, array<string, mixed>>  $fillable  채워야 하는 컬럼 목록
+     * @param  array<string, mixed>  $overrides  컬럼별 고정값
+     * @param  int  $index  행 인덱스 (고유값 생성용)
+     * @return array<string, mixed> 합성 행
+     */
+    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<int, array<string, mixed>>  $chunk  삽입할 행 묶음
+     */
+    private function insert(string $table, array $chunk): void
+    {
+        Schema::withoutForeignKeyConstraints(function () use ($table, $chunk) {
+            DB::table($table)->insert($chunk);
+        });
+    }
+
+    /**
+     * 컬럼 타입에 맞는 합성 값을 만듭니다.
+     *
+     * @param  array<string, mixed>  $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<string, mixed>  $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);
+    }
+}
@@ -0,0 +1,167 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Support\ApiDoc\ResourceFieldDescriber;
+use Illuminate\Console\Command;
+use Symfony\Component\Finder\Finder;
+
+/**
+ * 기존 API 문서의 응답 필드 설명 TODO 를 리소스 계약 사전 설명으로 소급 채웁니다.
+ *
+ * 파라미터 TODO 는 `api:docgen-backfill-params` 가 채우지만, 응답 필드 TODO 는 전용
+ * 백필 커맨드가 없어 재생성(`api:docgen`)으로만 갱신되었습니다. 실측 서버 없이
+ * 재생성하면 이미 실측된 응답 예시값이 퇴행하므로, 이 커맨드는 재생성 대신 응답 필드
+ * 표의 `<!-- TODO: 설명 -->` 셀만 in-place 치환합니다.
+ *
+ * 채움 규칙 SSoT 는 ApiDocScaffolder::responseFieldTable 과 동일한 ResourceFieldDescriber
+ * 입니다 — 이후 정상 재생성(실측 서버 가동 시)도 같은 설명을 산출하므로 멱등합니다.
+ *
+ * 도메인 특이 필드(ResourceFieldDescriber 가 null 반환)는 TODO 를 그대로 둡니다.
+ * 응답 필드 표만 대상으로 하며, 파라미터 표(`<!-- TODO: 용도 -->`)는 건드리지 않습니다.
+ */
+class ApiDocBackfillFieldsCommand extends Command
+{
+    /**
+     * @var string 커맨드 시그니처
+     */
+    protected $signature = 'api:docgen-backfill-fields
+        {--dry-run : 치환하지 않고 채울 건수만 리포트}';
+
+    /**
+     * @var string 커맨드 설명
+     */
+    protected $description = '기존 API 문서의 응답 필드 설명 TODO 를 리소스 계약 사전 설명으로 소급 채웁니다';
+
+    /**
+     * @var string 응답 필드 표를 식별하는 고유 헤더
+     */
+    private const FIELD_TABLE_HEADER = '| 필드 | 타입 | 실측 예시값 | 용도/설명 |';
+
+    /**
+     * @var string 응답 필드 설명 TODO 마커
+     */
+    private const TODO_MARKER = '<!-- TODO: 설명 -->';
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * @return int 종료 코드
+     */
+    public function handle(): int
+    {
+        $describer = new ResourceFieldDescriber;
+        $dryRun = (bool) $this->option('dry-run');
+
+        $filled = 0;
+        $skipped = 0;
+        $filesChanged = 0;
+
+        foreach ($this->apiDocFiles() as $file) {
+            $content = file_get_contents($file);
+            $result = $this->backfillFile($content, $describer, $filled, $skipped);
+
+            if ($result !== $content) {
+                $filesChanged++;
+                if (! $dryRun) {
+                    file_put_contents($file, $result);
+                }
+            }
+        }
+
+        $prefix = $dryRun ? '[dry-run] ' : '';
+        $this->info("{$prefix}응답 필드 설명 채움: {$filled}건, TODO 유지(도메인 특이): {$skipped}건, 변경 파일: {$filesChanged}개");
+
+        return self::SUCCESS;
+    }
+
+    /**
+     * 대상 API 문서 파일 경로를 수집합니다.
+     *
+     * @return array<int, string> 파일 경로 목록
+     */
+    private function apiDocFiles(): array
+    {
+        $dirs = array_filter([
+            base_path('docs/backend/api'),
+            ...glob(base_path('modules/_bundled/*/docs/api')),
+            ...glob(base_path('plugins/_bundled/*/docs/api')),
+        ], 'is_dir');
+
+        if ($dirs === []) {
+            return [];
+        }
+
+        $files = [];
+        foreach (Finder::create()->files()->in($dirs)->name('*.md') as $f) {
+            $files[] = $f->getRealPath();
+        }
+
+        return $files;
+    }
+
+    /**
+     * 단일 문서의 응답 필드 표 TODO 를 채웁니다.
+     *
+     * 응답 필드 표 헤더 이후 표 행만 대상으로 하며, `<!-- TODO: 설명 -->` 셀을
+     * ResourceFieldDescriber 결과로 치환합니다. 설명이 null(도메인 특이)이면 유지합니다.
+     * 파라미터 표는 헤더가 달라 진입하지 않으므로 건드리지 않습니다.
+     *
+     * @param  string  $content  문서 내용
+     * @param  ResourceFieldDescriber  $describer  설명기
+     * @param  int  $filled  채운 건수 (참조 누적)
+     * @param  int  $skipped  유지 건수 (참조 누적)
+     * @return string 치환된 문서 내용
+     */
+    private function backfillFile(string $content, ResourceFieldDescriber $describer, int &$filled, int &$skipped): string
+    {
+        $lines = explode("\n", $content);
+        $inFieldTable = false;
+
+        foreach ($lines as $i => $line) {
+            // 응답 필드 표 헤더 진입 감지
+            if (str_contains($line, self::FIELD_TABLE_HEADER)) {
+                $inFieldTable = true;
+
+                continue;
+            }
+
+            // 표 구분선(| --- | ...) 은 건너뜀
+            if ($inFieldTable && preg_match('/^\|\s*-+\s*\|/', $line)) {
+                continue;
+            }
+
+            // 표가 아닌 라인(빈 줄 또는 | 로 시작하지 않음) → 표 종료
+            if ($inFieldTable && ! str_starts_with(ltrim($line), '|')) {
+                $inFieldTable = false;
+
+                continue;
+            }
+
+            if (! $inFieldTable || ! str_contains($line, self::TODO_MARKER)) {
+                continue;
+            }
+
+            // 응답 필드 행 파싱: | name | type | `sample` | <!-- TODO: 설명 --> |
+            $cells = array_map('trim', explode('|', trim($line, '| ')));
+            if (count($cells) < 4) {
+                continue;
+            }
+
+            [$name, $type] = [$cells[0], $cells[1]];
+            $desc = $describer->describe($name, $type);
+
+            if ($desc === null) {
+                $skipped++;
+
+                continue;
+            }
+
+            $safe = str_replace(['|', "\n", "\r"], ['\\|', ' ', ''], $desc);
+            $lines[$i] = str_replace(self::TODO_MARKER, $safe, $line);
+            $filled++;
+        }
+
+        return implode("\n", $lines);
+    }
+}
@@ -0,0 +1,162 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Support\ApiDoc\ParameterDescriber;
+use Illuminate\Console\Command;
+use Symfony\Component\Finder\Finder;
+
+/**
+ * 기존 API 문서의 파라미터 용도 TODO 를 공통 파라미터 설명으로 소급 채웁니다.
+ *
+ * 실측 서버 없이 재생성하면 이미 실측된 응답표·사람 서술이 퇴행하므로, 이 커맨드는
+ * 재생성 대신 파라미터 표의 `<!-- TODO: 용도 -->` 셀만 in-place 치환합니다.
+ * 채움 규칙 SSoT 는 ApiDocScaffolder 와 동일한 ParameterDescriber 입니다 —
+ * 이후 정상 재생성(실측 서버 가동 시)도 같은 설명을 산출하므로 멱등합니다.
+ *
+ * 도메인 특이 파라미터(ParameterDescriber 가 null 반환)는 TODO 를 그대로 둡니다.
+ */
+class ApiDocBackfillParamsCommand extends Command
+{
+    /**
+     * @var string 커맨드 시그니처
+     */
+    protected $signature = 'api:docgen-backfill-params
+        {--dry-run : 치환하지 않고 채울 건수만 리포트}';
+
+    /**
+     * @var string 커맨드 설명
+     */
+    protected $description = '기존 API 문서의 파라미터 용도 TODO 를 공통 파라미터 설명으로 소급 채웁니다';
+
+    /**
+     * @var string 파라미터 표를 식별하는 고유 헤더
+     */
+    private const PARAM_TABLE_HEADER = '| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |';
+
+    /**
+     * @var string 파라미터 용도 TODO 마커
+     */
+    private const TODO_MARKER = '<!-- TODO: 용도 -->';
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * @return int 종료 코드
+     */
+    public function handle(): int
+    {
+        $describer = new ParameterDescriber;
+        $dryRun = (bool) $this->option('dry-run');
+
+        $filled = 0;
+        $skipped = 0;
+        $filesChanged = 0;
+
+        foreach ($this->apiDocFiles() as $file) {
+            $content = file_get_contents($file);
+            $result = $this->backfillFile($content, $describer, $filled, $skipped);
+
+            if ($result !== $content) {
+                $filesChanged++;
+                if (! $dryRun) {
+                    file_put_contents($file, $result);
+                }
+            }
+        }
+
+        $prefix = $dryRun ? '[dry-run] ' : '';
+        $this->info("{$prefix}파라미터 용도 채움: {$filled}건, TODO 유지(도메인 특이): {$skipped}건, 변경 파일: {$filesChanged}개");
+
+        return self::SUCCESS;
+    }
+
+    /**
+     * 대상 API 문서 파일 경로를 수집합니다.
+     *
+     * @return array<int, string> 파일 경로 목록
+     */
+    private function apiDocFiles(): array
+    {
+        $dirs = array_filter([
+            base_path('docs/backend/api'),
+            ...glob(base_path('modules/_bundled/*/docs/api')),
+            ...glob(base_path('plugins/_bundled/*/docs/api')),
+        ], 'is_dir');
+
+        if ($dirs === []) {
+            return [];
+        }
+
+        $files = [];
+        foreach (Finder::create()->files()->in($dirs)->name('*.md') as $f) {
+            $files[] = $f->getRealPath();
+        }
+
+        return $files;
+    }
+
+    /**
+     * 단일 문서의 파라미터 표 TODO 를 채웁니다.
+     *
+     * 파라미터 표 헤더 이후 표 행만 대상으로 하며, `<!-- TODO: 용도 -->` 셀을
+     * ParameterDescriber 결과로 치환합니다. 설명이 null(도메인 특이)이면 유지합니다.
+     *
+     * @param  string  $content  문서 내용
+     * @param  ParameterDescriber  $describer  설명기
+     * @param  int  $filled  채운 건수 (참조 누적)
+     * @param  int  $skipped  유지 건수 (참조 누적)
+     * @return string 치환된 문서 내용
+     */
+    private function backfillFile(string $content, ParameterDescriber $describer, int &$filled, int &$skipped): string
+    {
+        $lines = explode("\n", $content);
+        $inParamTable = false;
+
+        foreach ($lines as $i => $line) {
+            // 파라미터 표 헤더 진입 감지
+            if (str_contains($line, self::PARAM_TABLE_HEADER)) {
+                $inParamTable = true;
+
+                continue;
+            }
+
+            // 표 구분선(| --- | ...) 은 건너뜀
+            if ($inParamTable && preg_match('/^\|\s*-+\s*\|/', $line)) {
+                continue;
+            }
+
+            // 표가 아닌 라인(빈 줄 또는 | 로 시작하지 않음) → 표 종료
+            if ($inParamTable && ! str_starts_with(ltrim($line), '|')) {
+                $inParamTable = false;
+
+                continue;
+            }
+
+            if (! $inParamTable || ! str_contains($line, self::TODO_MARKER)) {
+                continue;
+            }
+
+            // 파라미터 행 파싱: | name | location | type | 필수 | 허용값 | <!-- TODO: 용도 --> |
+            $cells = array_map('trim', explode('|', trim($line, '| ')));
+            if (count($cells) < 5) {
+                continue;
+            }
+
+            [$name, $location, $type] = [$cells[0], $cells[1], $cells[2]];
+            $desc = $describer->describe($name, $location, $type);
+
+            if ($desc === null) {
+                $skipped++;
+
+                continue;
+            }
+
+            $safe = str_replace(['|', "\n", "\r"], ['\\|', ' ', ''], $desc);
+            $lines[$i] = str_replace(self::TODO_MARKER, $safe, $line);
+            $filled++;
+        }
+
+        return implode("\n", $lines);
+    }
+}
@@ -0,0 +1,125 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Seo\Contracts\SeoCacheManagerInterface;
+use App\Services\SettingsService;
+use App\Support\AssetUrl;
+use Illuminate\Console\Command;
+
+/**
+ * 자산 URL 모드 조회/전환 Artisan 커맨드 (이슈 #486 §9)
+ *
+ * 정적 최적화 블록(`location ~* \.(js|css|json)$`)이 동적 응답을 가로채는 서버에서는
+ * **관리자 화면 자체가 뜨지 않는다**. "브라우저로 설정을 바꾸세요" 는 순환 참조이므로
+ * CLI 탈출구가 반드시 필요하다.
+ *
+ * ```
+ * php artisan g7:asset-url-mode                # 현재 모드 + 진단 안내
+ * php artisan g7:asset-url-mode extensionless  # 전환
+ * ```
+ */
+class AssetUrlModeCommand extends Command
+{
+    /**
+     * @var string 커맨드 시그니처
+     */
+    protected $signature = 'g7:asset-url-mode
+        {mode? : 전환할 모드 (extension | extensionless). 생략 시 현재 모드만 출력}';
+
+    /**
+     * @var string 커맨드 설명
+     */
+    protected $description = '자산 URL 모드를 조회하거나 전환합니다 (정적 최적화 서버 대응)';
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * @param  SettingsService  $settingsService  환경설정 서비스
+     * @param  SeoCacheManagerInterface  $seoCacheManager  SEO 캐시 매니저
+     * @return int 종료 코드
+     */
+    public function handle(SettingsService $settingsService, SeoCacheManagerInterface $seoCacheManager): int
+    {
+        $current = AssetUrl::mode();
+        $requested = $this->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('');
+    }
+}
@@ -0,0 +1,395 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Benchmark\BenchmarkProfileRegistry;
+use App\Benchmark\BenchmarkReporter;
+use App\Benchmark\Contracts\BenchmarkAxisRunner;
+use App\Benchmark\DTO\BenchmarkProfile;
+use App\Benchmark\DTO\BenchmarkResult;
+use App\Benchmark\DTO\BenchmarkRunOptions;
+use App\Enums\BenchmarkAxis;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * 성능 계측 커맨드 — 목록 조회 / 화면 응답 / 쓰기 작업 / 배치 작업 4축
+ *
+ * 계측 대상은 소유자가 선언합니다 — 코어는 `config/benchmark.php`, 확장은
+ * `getBenchmarkProfiles()` 오버라이드입니다. 커맨드에 대상을 하드코딩하지 않는 이유는,
+ * 확장이 설치·제거되는 설치본마다 실제로 존재하는 대상이 다르기 때문입니다.
+ *
+ * 축별 실행은 `App\Benchmark\Axes\*` 실행기가 담당하고, 이 커맨드는 프로파일 선택·옵션
+ * 해석·출력만 합니다.
+ *
+ * tinker 스크립트 대신 커맨드로 만든 이유: tinker 는 REPL 이라 스크립트 실행 후에도 STDIN 을
+ * 기다려 출력이 유실된다.
+ */
+class BenchCommand extends Command
+{
+    protected $signature = 'g7:bench
+        {--profile=* : 계측할 프로파일 키 (짧은 키 또는 출처/키 형태). 다중 지정 가능}
+        {--axis= : 축 단위 실행 (list|screen|write|batch)}
+        {--all : 등록된 모든 프로파일 실행}
+        {--offsets=0,20000,50000,99980 : 측정할 OFFSET 목록 (쉼표 구분, list 축)}
+        {--runs=3 : 측정 횟수 (첫 회는 버림)}
+        {--per-page=20 : 목록/화면 1페이지 건수}
+        {--seed=0 : 계측 전 합성 행 시딩 건수 (0 = 시딩 안 함, list 축)}
+        {--fresh : 시딩 전에 대상 테이블을 비움 (운영 환경에서는 거부)}
+        {--explain : 각 OFFSET 의 실행 계획도 함께 수집 (list 축)}
+        {--as= : 화면 계측에 사용할 기존 계정 (ID 또는 이메일). 미지정 시 계측용 임시 계정}
+        {--allow-write : 데이터를 변경하는 축(write/batch/비-GET 화면) 실행 허용}
+        {--database= : 계측에 사용할 데이터베이스명 (미지정 시 기본 연결. 개발 DB 오염 방지용)}
+        {--json : 기계 판독용 JSON 출력}
+        {--report= : 마크다운 리포트 저장 경로 (값 없이 --report 만 주면 storage/app/benchmarks/ 아래 자동 생성)}
+        {--list-profiles : 등록된 프로파일 목록 출력}';
+
+    protected $description = '목록 조회·화면 응답·쓰기·배치 4축 성능을 계측합니다 (대상은 코어 config + 확장 선언에서 수집)';
+
+    protected $aliases = ['g7:bench:pagination'];
+
+    /**
+     * 리포트 기본 저장 디렉토리 (저장소 미추적 — 계측값은 실행 머신 사양에 종속되므로 축적하지 않음)
+     */
+    private const REPORT_DIR = 'app/benchmarks';
+
+    /**
+     * @param  BenchmarkProfileRegistry  $registry  프로파일 레지스트리
+     * @param  BenchmarkReporter  $reporter  결과 출력기
+     * @param  iterable<BenchmarkAxisRunner>  $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<int, BenchmarkProfile>, 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<int, int> 오름차순 정렬된 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<int, BenchmarkResult>  $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<int, BenchmarkResult>  $results  계측 결과
+     * @param  BenchmarkRunOptions  $options  실행 옵션
+     * @param  array<int, string>  $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;
+    }
+}
@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\ExtensionBundleService;
+use Illuminate\Console\Command;
+
+/**
+ * 오래된 확장 프론트엔드 병합 번들 파일을 정리하는 커맨드
+ *
+ * 번들 캐시 파일(`storage/app/ext-bundles/{type}.{version}.{js|css}`)은 Laravel
+ * 캐시 스토어 밖 파일시스템이라 version bump 나 cache:clear 가 구버전 파일을
+ * 지우지 않는다(TTL/GC 없음). 이 커맨드가 현재 version 외의 구파일을 삭제한다.
+ * (`CleanupLayoutPreviewsCommand` 파일 산출물 GC 패턴 미러)
+ */
+class CleanupExtensionBundlesCommand extends Command
+{
+    /**
+     * The name and signature of the console command.
+     */
+    protected $signature = 'ext-bundles:cleanup';
+
+    /**
+     * The console command description.
+     */
+    protected $description = '오래된 확장 프론트엔드 병합 번들 파일(구 version)을 삭제합니다';
+
+    /**
+     * Execute the console command.
+     *
+     * @param  ExtensionBundleService  $service  번들 서비스
+     * @return int 명령 실행 결과 코드
+     */
+    public function handle(ExtensionBundleService $service): int
+    {
+        $currentVersion = $service->getCurrentVersion();
+        $deleted = $service->cleanupStaleBundles($currentVersion);
+
+        $this->info("오래된 확장 번들 {$deleted}건이 삭제되었습니다. (현재 version: {$currentVersion})");
+
+        return self::SUCCESS;
+    }
+}
@@ -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);
@@ -94,9 +94,12 @@ class BuildCoreCommand extends Command
            return $this->runWatchBundles($projectPath);
        }

+        // 3개 번들을 npm 스크립트로 순차 호출하므로 빌드 환경변수를 세 곳 모두에 주입한다.
+        $buildEnv = $this->buildEnv($productionMode);
+
        // ── 1) 템플릿 엔진 번들 (편집기 코드 제외) ──────────────────────────────
        $this->info('🔨 코어 빌드 시작 (템플릿 엔진)'.($productionMode ? ' (프로덕션)' : ''));
-        $engineResult = $this->runNpmCommand(['npm', 'run', 'build:core'], $projectPath, true);
+        $engineResult = $this->runNpmCommand(['npm', 'run', 'build:core'], $projectPath, true, $buildEnv);

        if ($engineResult !== Command::SUCCESS) {
            return $engineResult;
@@ -104,7 +107,7 @@ class BuildCoreCommand extends Command

        // ── 2) 레이아웃 편집기 번들 (lazy, /admin/layout-editor/* 진입 시 로드) ──
        $this->info('🔨 코어 빌드 시작 (레이아웃 편집기)'.($productionMode ? ' (프로덕션)' : ''));
-        $editorResult = $this->runNpmCommand(['npm', 'run', 'build:core-editor'], $projectPath, true);
+        $editorResult = $this->runNpmCommand(['npm', 'run', 'build:core-editor'], $projectPath, true, $buildEnv);

        if ($editorResult !== Command::SUCCESS) {
            $this->error('❌ 레이아웃 편집기 번들 빌드 실패');
@@ -114,7 +117,7 @@ class BuildCoreCommand extends Command

        // ── 3) DevTools 번들 (lazy, 디버그 모드에서만 로드) ──
        $this->info('🔨 코어 빌드 시작 (DevTools)'.($productionMode ? ' (프로덕션)' : ''));
-        $devtoolsResult = $this->runNpmCommand(['npm', 'run', 'build:core-devtools'], $projectPath, true);
+        $devtoolsResult = $this->runNpmCommand(['npm', 'run', 'build:core-devtools'], $projectPath, true, $buildEnv);

        if ($devtoolsResult !== Command::SUCCESS) {
            $this->error('❌ DevTools 번들 빌드 실패');
@@ -197,7 +200,13 @@ class BuildCoreCommand extends Command
            $this->info('🔨 코어 빌드 시작 (전체)'.($productionMode ? ' (프로덕션)' : ''));
        }

-        $result = $this->runNpmCommand($buildCommand, $projectPath, ! $watchMode);
+        // 감시 모드에는 소스맵 억제를 주입하지 않는다 — 개발 중 디버깅 필요
+        $result = $this->runNpmCommand(
+            $buildCommand,
+            $projectPath,
+            ! $watchMode,
+            $watchMode ? [] : $this->buildEnv($productionMode)
+        );

        if ($result === Command::SUCCESS && ! $watchMode) {
            $this->info('✅ 코어 빌드 완료 (전체)');
@@ -311,15 +320,30 @@ class BuildCoreCommand extends Command
        }
    }

+    /**
+     * 빌드 프로세스에 주입할 환경변수를 구성합니다.
+     *
+     * 프로덕션 빌드에서는 소스맵을 생성하지 않습니다. 배포 산출물에 원본 코드가
+     * 포함되는 것을 막기 위함이며, 각 vite config 가 이 값을 읽습니다.
+     *
+     * @param  bool  $productionMode  프로덕션 빌드 여부
+     * @return array<string, string> Process 에 주입할 환경변수
+     */
+    private function buildEnv(bool $productionMode): array
+    {
+        return $productionMode ? ['G7_BUILD_SOURCEMAP' => '0'] : [];
+    }
+
    /**
     * npm 명령 실행
     *
     * @param  array  $command  실행할 명령
     * @param  string  $cwd  작업 디렉토리
     * @param  bool  $waitForCompletion  완료 대기 여부
+     * @param  array<string, string>  $env  추가로 주입할 환경변수 (부모 환경에 병합됨)
     * @return int 명령 실행 결과 코드
     */
-    private function runNpmCommand(array $command, string $cwd, bool $waitForCompletion = true): int
+    private function runNpmCommand(array $command, string $cwd, bool $waitForCompletion = true, array $env = []): int
    {
        // Windows 환경에서는 cmd /c 사용
        if (PHP_OS_FAMILY === 'Windows') {
@@ -328,6 +352,11 @@ class BuildCoreCommand extends Command

        $process = new Process($command);
        $process->setWorkingDirectory($cwd);
+
+        // Symfony Process 는 지정한 env 를 부모 환경에 병합하므로(PATH 등 유지) 추가분만 넘긴다.
+        if ($env !== []) {
+            $process->setEnv($env);
+        }
        $process->setTimeout(null); // 타임아웃 없음

        if ($waitForCompletion) {
@@ -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]));
+        }
+    }
 }
@@ -8,6 +8,7 @@ use App\Exceptions\UpgradeHandoffException;
 use App\Extension\CoreVersionChecker;
 use App\Extension\Helpers\CoreBackupHelper;
 use App\Extension\Helpers\FilePermissionHelper;
+use App\Extension\Helpers\StorageLinkHelper;
 use App\Extension\ModuleManager;
 use App\Extension\PluginManager;
 use App\Extension\TemplateManager;
@@ -16,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;

@@ -28,11 +30,13 @@ class CoreUpdateCommand extends Command
    protected $signature = 'core:update
        {--force : 버전 비교 없이 강제 업데이트}
        {--no-backup : 백업 생성 건너뛰기}
+        {--prune : 코어가 제거한 파일 정리 + targets 전체 덮어쓰기(기존 방식). 미지정 시 코어가 실제 변경/추가한 파일만 적용하고 나머지는 보존}
        {--no-maintenance : 유지보수 모드 활성화 건너뛰기}
        {--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 코어를 최신 버전으로 업데이트합니다';

@@ -346,6 +350,12 @@ class CoreUpdateCommand extends Command
            //
            // `--no-backup` 모드면 backupPath 가 null 이므로 manifest 생성을 스킵 — 롤백
            // 자체가 불가능한 모드이므로 기존 동작 유지.
+            // 증분 적용(3-way) 대상 목록. 백업 있음 + --prune 미지정 시에만 산출.
+            // null 로 남으면(백업 부재 또는 --prune) applyUpdate 가 전체 덮어쓰기로 회귀.
+            $applyList = null;
+            $applyStats = null;
+            $prune = (bool) $this->option('prune');
+
            if ($backupPath !== null) {
                $bar->setMessage('신규 파일 manifest 생성 중...');
                $log('신규 파일 manifest 생성 시작');
@@ -371,15 +381,51 @@ class CoreUpdateCommand extends Command
                        'error' => $manifestError->getMessage(),
                    ]);
                }
+
+                // ── 증분 적용 대상 산출 (3-way) ──
+                // --prune 이면 전체 덮어쓰기이므로 산출 자체를 스킵.
+                if (! $prune) {
+                    try {
+                        $applyStats = CoreBackupHelper::computeApplyList(
+                            $backupPath,
+                            $pendingPath,
+                            (array) config('app.update.targets', []),
+                            (array) config('app.update.protected_paths', []),
+                            (array) config('app.update.excludes', []),
+                        );
+                        $applyList = $applyStats['apply'];
+                        $log(sprintf(
+                            '증분 적용 대상 산출 완료 (added=%d, changed=%d, total=%d)',
+                            $applyStats['added_count'],
+                            $applyStats['changed_count'],
+                            count($applyList),
+                        ));
+                    } catch (\Throwable $applyError) {
+                        // 산출 실패 시 안전하게 전체 덮어쓰기로 회귀 (applyList=null 유지)
+                        $applyList = null;
+                        $applyStats = null;
+                        $log("증분 적용 대상 산출 실패 (전체 덮어쓰기로 회귀): {$applyError->getMessage()}");
+                        Log::warning('코어 업데이트: 증분 적용 대상 산출 실패', [
+                            'error' => $applyError->getMessage(),
+                        ]);
+                    }
+                }
            }

            // ── Step 7: 파일 적용 ──
            $bar->setMessage(__('settings.core_update.step_apply'));
            $bar->advance();
-            $log('코어 파일 덮어쓰기 시작');

-            $service->applyUpdate($pendingPath, $onProgress);
-            $log('코어 파일 덮어쓰기 완료');
+            if ($prune) {
+                $log('코어 파일 덮어쓰기 시작 (--prune: 전체 덮어쓰기 + orphan 정리)');
+            } elseif ($applyList !== null) {
+                $log(sprintf('코어 파일 적용 시작 (증분: 코어 변경분 %d건만 적용, 나머지 보존)', count($applyList)));
+            } else {
+                $log('코어 파일 덮어쓰기 시작 (백업 부재 — 전체 덮어쓰기로 회귀)');
+            }
+
+            $service->applyUpdate($pendingPath, $onProgress, prune: $prune, applyList: $applyList);
+            $log('코어 파일 적용 완료');

            // ── Step 8: vendor 디렉토리 복사 (_pending → 운영) ──
            if ($composerSkipped) {
@@ -474,6 +520,12 @@ class CoreUpdateCommand extends Command
            $this->surfacePermissionWarnings($service, $log);
            $log('업데이트 경로 소유권 복원 완료');

+            // 소유권 복원 완료 후 · 유지보수 해제 전에 `public/storage` symlink 를 방어 복구한다.
+            // `--prune` 이 릴리즈 소스에 없는 symlink 를 orphan 으로 삭제했거나(#43) 손상된
+            // 경우에도, 첫 요청부터 `/storage/...` 가 200 을 반환하도록 링크를 재생성한다.
+            StorageLinkHelper::ensurePublicStorageLink();
+            $log('public/storage symlink 확인/복구 완료');
+
            $service->cleanupPending($pendingPath);

            if ($backupPath) {
@@ -492,6 +544,11 @@ class CoreUpdateCommand extends Command
            // 상태를 가드하고 실패를 안전하게 흡수한다.
            ConfigCacheHelper::rebuild();

+            // 라우트 캐시도 같은 이유로 되살린다. 코어 업데이트는 routes/*.php 와 vendor 를
+            // 교체하므로 흐름 중간에 비우는 것이 맞지만, 비운 채로 끝내면 이후 모든 요청이
+            // 라우트를 다시 등록한다. 재생성은 파일이 전부 안착한 이 지점에서만 안전하다.
+            RouteCacheHelper::rebuild();
+
            $log('정리 완료');

            $bar->finish();
@@ -503,6 +560,9 @@ class CoreUpdateCommand extends Command
            $this->info("그누보드7 코어가 {$toVersion} 버전으로 업데이트되었습니다!");
            $this->newLine();

+            // ── 파일 적용 방식 요약 (부수의무: 설명의무) ──
+            $this->summarizeApplyMode($prune, $applyList, $applyStats);
+
            // _bundled 확장 일괄 업데이트 프롬프트 (번들에 신버전이 있을 때만 표시).
            //
            // 주의: Step 11 restoreOwnership 이후에 실행되므로, 프롬프트 내 실제
@@ -577,6 +637,11 @@ class CoreUpdateCommand extends Command
                $this->surfacePermissionWarnings($service, $log);
                $log('핸드오프 cleanup 완료 (버전 toVersion 고정 + 캐시 clear + 소유권 복원)');

+                // 핸드오프 시에도 파일은 이미 toVersion 으로 반영돼 `public/storage` symlink 가
+                // 삭제/손상됐을 수 있으므로 유지보수 해제 전에 동일하게 방어 복구한다(#43).
+                StorageLinkHelper::ensurePublicStorageLink();
+                $log('public/storage symlink 확인/복구 완료 (핸드오프)');
+
                if (! empty($pendingPath)) {
                    $service->cleanupPending($pendingPath);
                }
@@ -1068,6 +1133,41 @@ class CoreUpdateCommand extends Command
        return true;
    }

+    /**
+     * 파일 적용 방식(증분/prune/fallback)과 통계를 사용자에게 요약 출력합니다.
+     *
+     * @param  bool  $prune  --prune 지정 여부
+     * @param  array<int, string>|null  $applyList  증분 적용 대상 목록 (null 이면 전체 덮어쓰기)
+     * @param  array{apply:array<int,string>, added_count:int, changed_count:int, has_symlink:bool}|null  $applyStats  computeApplyList 산출 통계
+     */
+    private function summarizeApplyMode(bool $prune, ?array $applyList, ?array $applyStats): void
+    {
+        if ($prune) {
+            $this->line(__('settings.core_update.apply_mode_prune'));
+            $this->newLine();
+
+            return;
+        }
+
+        if ($applyList === null) {
+            // 백업 부재 또는 산출 실패 → 전체 덮어쓰기로 회귀
+            $this->warn(__('settings.core_update.apply_mode_fallback'));
+            $this->newLine();
+
+            return;
+        }
+
+        // 증분 모드
+        $added = $applyStats['added_count'] ?? 0;
+        $changed = $applyStats['changed_count'] ?? 0;
+        $this->line(__('settings.core_update.apply_mode_incremental', [
+            'added' => $added,
+            'changed' => $changed,
+        ]));
+        $this->line(__('settings.core_update.apply_mode_incremental_prune_hint'));
+        $this->newLine();
+    }
+
    /**
     * 업데이트 로그를 파일로 저장합니다.
     *
@@ -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;
    }
-
 }
@@ -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 모드에서는 부모가 처리하므로 스킵.
@@ -0,0 +1,39 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\IdentityLogService;
+use Illuminate\Console\Command;
+
+/**
+ * 만료 시각이 지난 본인인증 challenge 를 만료 상태로 전환하는 커맨드
+ *
+ * 상태 전환만 수행하며 행을 삭제하지 않습니다 (물리 파기는 identity:prune-logs 담당).
+ */
+class ExpireIdentityChallengesCommand extends Command
+{
+    /**
+     * The name and signature of the console command.
+     */
+    protected $signature = 'identity:expire-challenges';
+
+    /**
+     * The console command description.
+     */
+    protected $description = '만료 시각이 지난 본인인증 challenge 를 만료 처리합니다';
+
+    /**
+     * Execute the console command.
+     *
+     * @param  IdentityLogService  $service  본인인증 이력 서비스
+     * @return int 명령 실행 결과 코드
+     */
+    public function handle(IdentityLogService $service): int
+    {
+        $expired = $service->expirePastDue();
+
+        $this->info("본인인증 challenge {$expired}건이 만료 처리되었습니다.");
+
+        return self::SUCCESS;
+    }
+}
@@ -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 매핑으로 훅 발화 누락/과잉 위험).
@@ -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;
+    }
 }
@@ -0,0 +1,150 @@
+<?php
+
+namespace App\Console\Commands\LanguagePack;
+
+use App\Models\LanguagePack;
+use App\Services\LanguagePack\LanguagePackBaseLocales;
+use App\Services\LanguagePackService;
+use Illuminate\Console\Command;
+use Throwable;
+
+/**
+ * 정책(supported_locales) 기준으로 미설치 번들 언어팩을 멱등 설치(프로비저닝)합니다.
+ *
+ * fresh install / 시더 / 수동 복구가 공유하는 단일 프로비저닝 SSoT 입니다.
+ * base locale(ko/en)은 가상 보호 행으로 항상 서빙되므로 대상에서 제외되고,
+ * 나머지 로케일(예: ja)은 `lang-packs/_bundled/` 에 소스가 있어도 설치본 디렉토리로
+ * 복사·등록되어야 서빙되므로 이 커맨드가 그 프로비저닝을 담당합니다.
+ *
+ * 대상은 두 갈래입니다 — 미설치 번들 팩(신규 프로비저닝)과, 설치 행은 있으나 설치본 파일이
+ * 사라진 드리프트 팩(수동 복구). 후자는 슬롯이 점유돼 있어 `getUninstalledBundledPacks()` 가
+ * 잡지 못하므로 `getDriftedInstalledPacks()` 로 따로 모읍니다. 이 커맨드가 복구 경로를 겸하지 않으면
+ * 드리프트는 화면에서 보이기만 하고 CLI 로는 고칠 수 없습니다.
+ *
+ * 멱등성: 정상 설치된 팩은 두 집합 어디에도 속하지 않으므로 재실행 시 신규 설치 0 건으로 수렴합니다.
+ */
+class ProvisionLanguagePackCommand extends Command
+{
+    /**
+     * @var string
+     */
+    protected $signature = 'language-pack:provision
+        {--locale=* : 대상 로케일(미지정 시 supported_locales 에서 base locale 제외)}
+        {--scope=* : core/module/plugin/template 로 대상 스코프 한정}
+        {--no-activate : 설치 후 자동 활성화하지 않음}';
+
+    /**
+     * @var string
+     */
+    protected $description = '정책(supported_locales) 기준 미설치 번들 언어팩을 멱등 설치합니다.';
+
+    /**
+     * @param  LanguagePackService  $service  언어팩 Service
+     */
+    public function __construct(
+        private readonly LanguagePackService $service,
+    ) {
+        parent::__construct();
+    }
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * @return int 종료 코드
+     */
+    public function handle(): int
+    {
+        $targetLocales = $this->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<int, string> 대상 로케일 목록 (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),
+        )));
+    }
+}
@@ -96,6 +96,8 @@ class MigrateSettingsToJsonCommand extends Command
        'debug_mode' => 'debug',
        'sql_query_log' => 'debug',
        'log_level' => 'debug',
+        'outbound_proxy' => 'debug',
+        'outbound_proxy_bypass' => 'debug',
    ];

    /**
@@ -189,8 +189,13 @@ class BuildModuleCommand extends Command
            $this->info("🔨 빌드 시작: {$identifier}".($productionMode ? ' (프로덕션)' : ''));
        }

-        // 빌드 실행
-        $result = $this->runNpmCommand($buildCommand, $buildPath, ! $watchMode);
+        // 빌드 실행 (감시 모드에는 소스맵 억제를 주입하지 않는다 — 개발 중 디버깅 필요)
+        $result = $this->runNpmCommand(
+            $buildCommand,
+            $buildPath,
+            ! $watchMode,
+            $watchMode ? [] : $this->buildEnv($productionMode)
+        );

        if ($result === Command::SUCCESS && ! $watchMode) {
            $this->info("✅ 빌드 완료: {$identifier}");
@@ -338,15 +343,30 @@ class BuildModuleCommand extends Command
        return $failCount > 0 ? Command::FAILURE : Command::SUCCESS;
    }

+    /**
+     * 빌드 프로세스에 주입할 환경변수를 구성합니다.
+     *
+     * 프로덕션 빌드에서는 소스맵을 생성하지 않습니다. 배포 산출물에 원본 코드가
+     * 포함되는 것을 막기 위함이며, 각 vite config 가 이 값을 읽습니다.
+     *
+     * @param  bool  $productionMode  프로덕션 빌드 여부
+     * @return array<string, string> Process 에 주입할 환경변수
+     */
+    private function buildEnv(bool $productionMode): array
+    {
+        return $productionMode ? ['G7_BUILD_SOURCEMAP' => '0'] : [];
+    }
+
    /**
     * npm 명령 실행
     *
     * @param  array  $command  실행할 명령
     * @param  string  $cwd  작업 디렉토리
     * @param  bool  $waitForCompletion  완료 대기 여부
+     * @param  array<string, string>  $env  추가로 주입할 환경변수 (부모 환경에 병합됨)
     * @return int 명령 실행 결과 코드
     */
-    private function runNpmCommand(array $command, string $cwd, bool $waitForCompletion = true): int
+    private function runNpmCommand(array $command, string $cwd, bool $waitForCompletion = true, array $env = []): int
    {
        // Windows 환경에서는 cmd /c 사용
        if (PHP_OS_FAMILY === 'Windows') {
@@ -355,6 +375,11 @@ class BuildModuleCommand extends Command

        $process = new Process($command);
        $process->setWorkingDirectory($cwd);
+
+        // Symfony Process 는 지정한 env 를 부모 환경에 병합하므로(PATH 등 유지) 추가분만 넘긴다.
+        if ($env !== []) {
+            $process->setEnv($env);
+        }
        $process->setTimeout(null); // 타임아웃 없음

        if ($waitForCompletion) {
@@ -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,
        ]));

@@ -2,14 +2,22 @@

 namespace App\Console\Commands\Module;

-use App\Contracts\Extension\CacheInterface;
-use App\Contracts\Repositories\ModuleRepositoryInterface;
+use App\Contracts\Repositories\LayoutRepositoryInterface;
+use App\Enums\LayoutSourceType;
+use App\Extension\ExtensionMiddlewareRegistry;
 use App\Extension\ModuleManager;
+use App\Extension\Traits\ClearsTemplateCaches;
+use App\Extension\Traits\InvalidatesLayoutCache;
+use App\Services\ExtensionBundleService;
+use App\Services\LayoutResolverService;
 use Illuminate\Console\Command;
 use Illuminate\Support\Facades\Log;

 class ClearModuleCacheCommand extends Command
 {
+    use ClearsTemplateCaches;
+    use InvalidatesLayoutCache;
+
    /**
     * The name and signature of the console command.
     */
@@ -26,14 +34,19 @@ class ClearModuleCacheCommand extends Command
     */
    public function __construct(
        private ModuleManager $moduleManager,
-        private ModuleRepositoryInterface $moduleRepository,
-        private CacheInterface $cache
+        protected LayoutRepositoryInterface $layoutRepository,
+        private ExtensionBundleService $bundleService,
+        private LayoutResolverService $layoutResolver
    ) {
        parent::__construct();
    }

    /**
     * Execute the console command.
+     *
+     * 실재하는 서버 캐시(모듈 레이아웃 서빙/해석 캐시 + 상태 키 + 미들웨어 인덱스
+     * + 버전 포함 키)를 무효화한다.
+     * 종전 forget 대상(module.config.{id} 등)은 writer 가 없는 유령 키였다 (#588).
     */
    public function handle(): int
    {
@@ -59,6 +72,11 @@ class ClearModuleCacheCommand extends Command

                $clearedCount = $this->clearModuleCache($identifier);

+                // 상태 키(ext.modules.*) + 미들웨어 인덱스 + 버전 포함 키 무효화 (버전 bump)
+                ModuleManager::invalidateModuleStatusCache();
+                ExtensionMiddlewareRegistry::flush();
+                $this->incrementExtensionCacheVersion();
+
                $this->info('✅ '.__('modules.commands.cache_clear.success_single', [
                    'module' => $identifier,
                    'count' => $clearedCount,
@@ -67,25 +85,19 @@ class ClearModuleCacheCommand extends Command
                // 모든 모듈 캐시 삭제
                $this->info(__('modules.commands.cache_clear.clearing_all'));

-                // 전체 모듈 캐시 키 삭제
-                $cacheKeys = [
-                    'modules.all',
-                    'modules.active',
-                    'modules.installed',
-                ];
-
-                foreach ($cacheKeys as $key) {
-                    if ($this->cache->forget($key)) {
-                        $clearedCount++;
-                    }
-                }
-
                // 각 모듈별 캐시 삭제
-                $allModules = $this->moduleManager->getAllModules();
-                foreach ($allModules as $moduleName => $module) {
+                foreach ($this->moduleManager->getAllModules() as $module) {
                    $clearedCount += $this->clearModuleCache($module->getIdentifier());
                }

+                // 상태 키 + 미들웨어 인덱스 + 버전 포함 키 무효화는 전체에서 1회면 충분
+                ModuleManager::invalidateModuleStatusCache();
+                ExtensionMiddlewareRegistry::flush();
+                $this->incrementExtensionCacheVersion();
+
+                // 모듈 프론트엔드 병합 번들 파일 삭제 (캐시 키 forget 만으로는 미삭제)
+                $clearedCount += $this->bundleService->clearBundles('module');
+
                $this->info('✅ '.__('modules.commands.cache_clear.success_all', ['count' => $clearedCount]));
            }

@@ -108,26 +120,23 @@ class ClearModuleCacheCommand extends Command

    /**
     * 특정 모듈의 캐시를 삭제합니다.
+     *
+     * 모듈이 소유한 실재 서버 캐시는 레이아웃 캐시(서빙/병합 + 해석)다 — 각각
+     * 트레이트(InvalidatesLayoutCache)와 LayoutResolverService 단일 지점으로
+     * 위임해 키 규약 드리프트를 방지한다. 해석 캐시(layout_resolver.*)는 버전
+     * 접미사 없는 고정 키에 레이아웃 row ID 를 저장하므로 능동 삭제하지 않으면
+     * TTL 동안 이전 해석 결과가 유지된다 (#588 동종 보강).
+     *
+     * @param  string  $identifier  모듈 식별자
+     * @return int 캐시를 무효화한 레이아웃 수
     */
    private function clearModuleCache(string $identifier): int
    {
-        $clearedCount = 0;
+        $this->invalidateExtensionLayoutCache($identifier, 'module');
+        $this->layoutResolver->clearResolutionCacheByModule($identifier);

-        // 모듈별 캐시 키
-        $cacheKeys = [
-            "module.config.{$identifier}",
-            "module.info.{$identifier}",
-            "module.routes.{$identifier}",
-            "module.permissions.{$identifier}",
-            "module.menus.{$identifier}",
-        ];
-
-        foreach ($cacheKeys as $key) {
-            if ($this->cache->forget($key)) {
-                $clearedCount++;
-            }
-        }
-
-        return $clearedCount;
+        return $this->layoutRepository
+            ->getBySourceIdentifier($identifier, LayoutSourceType::Module)
+            ->count();
    }
 }
@@ -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;
            }

@@ -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;
            }

@@ -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<int, string>  $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();
@@ -0,0 +1,377 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Contracts\Repositories\LayoutRepositoryInterface;
+use App\Contracts\Repositories\TemplateRepositoryInterface;
+use App\Extension\Traits\ComputesLayoutContentHash;
+use App\Extension\Traits\InvalidatesLayoutCache;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Config;
+use Illuminate\Support\Facades\File;
+
+/**
+ * Playwright E2E 용 시드 레이아웃 설치/제거 커맨드.
+ *
+ * 레이아웃 편집기 E2E 중 **저장(PUT)까지 수행하는** spec 은 편집 결과가 그대로 영속된다.
+ * 이들이 제품 화면(`home` / `admin_dashboard` 등)을 대상으로 하면 실행할 때마다 빈 표·차트가
+ * 누적돼 개발 사이트가 오염된다(실측: `home` 20,321 → 33,696 bytes, 빈 표 7개). spec 안에
+ * 원복 장치를 넣어도 편집기가 캐시한 문서를 다시 밀어 넣어 오염 시점 크기로 되돌아왔다.
+ *
+ * 그래서 저장 spec 전용 시드 화면(`e2e_sandbox`)을 제품 레이아웃과 분리한다. 이 커맨드가
+ * 그 화면을 **활성 템플릿 디렉토리에만** 설치하므로 `_bundled`(배포 원본)은 손대지 않고,
+ * 활성 디렉토리는 Git 무시 대상이라 릴리스 산출물에도 포함되지 않는다.
+ *
+ * 설치 절차(템플릿별):
+ *   ① `tests/Playwright/fixtures/seed-layouts/{identifier}.e2e_sandbox.json` 을
+ *      `templates/{identifier}/layouts/e2e_sandbox.json` 으로 복사
+ *   ② 활성 `templates/{identifier}/routes.json` 에 라우트 1건 추가(멱등 — 마커로 식별).
+ *      편집기 라우트 트리는 routes.json 에서 만들어지므로 이 항목이 없으면 `?route=` 로
+ *      시드 화면을 열 수 없다
+ *   ③ 시드 레이아웃 DB 행만 upsert. 편집기의 조회/저장 대상은 DB 행이라 이 단계가 없으면 404
+ *
+ * ③ 에서 `template:refresh-layout`(전체 재동기화)을 쓰지 않는 이유: 그 경로는 파일에 없는
+ * DB 레이아웃을 지우고 모든 레이아웃을 파일 기준으로 되돌린다. 편집기 UI 로 저장한 변경은
+ * 파일이 아니라 DB 에만 있으므로, E2E 를 돌릴 때마다 사람이 편집기로 만든 결과가 사라진다.
+ * 시드 설치는 시드 행 하나만 건드린다.
+ *
+ * `--remove` 는 ①②를 되돌리고 시드 DB 행만 삭제한다 (다른 레이아웃 무영향).
+ *
+ * 보안 가드 (2중) — `PlaywrightIssueToken` 과 동일 규약:
+ *   ① CLI 한정 — `php_sapi_name() === 'cli'` 확인. production 웹 요청에서 절대 도달 불가
+ *   ② 명시 옵트인 — `G7_PLAYWRIGHT_BYPASS=1` 환경변수 부여 필수.
+ *      `.env` 영구 수정 없이 인라인 환경변수로만 활성화 가능 → 무심코 production 으로 새지 않음
+ *
+ * 호출 예시 (PowerShell):
+ *   $env:G7_PLAYWRIGHT_BYPASS='1'; php artisan playwright:seed-layout
+ *   $env:G7_PLAYWRIGHT_BYPASS='1'; php artisan playwright:seed-layout --remove
+ */
+class PlaywrightSeedLayout extends Command
+{
+    use ComputesLayoutContentHash, InvalidatesLayoutCache;
+
+    protected $signature = 'playwright:seed-layout
+        {--template=* : 대상 템플릿 identifier (생략 시 기본 대상 전체)}
+        {--remove : 시드 레이아웃/라우트를 제거한다}';
+
+    protected $description = 'Playwright E2E 전용 시드 레이아웃 설치/제거 (CLI + G7_PLAYWRIGHT_BYPASS 가드)';
+
+    /** 시드 레이아웃 이름 — 파일명·DB name·라우트 layout 이 모두 이 값을 공유한다. */
+    private const LAYOUT_NAME = 'e2e_sandbox';
+
+    /**
+     * routes.json 의 시드 라우트 식별 마커.
+     *
+     * 경로 문자열은 템플릿 타입마다 다르므로(사용자 템플릿 vs 관리자 템플릿), 제거 시에는
+     * 경로가 아니라 이 마커로 대상을 찾는다.
+     */
+    private const ROUTE_MARKER = 'playwright-seed-layout';
+
+    /** 원본 routes.json 보관 파일 접미사 — 제거 시 서식까지 바이트 동일 복원용 */
+    private const ROUTES_BACKUP_SUFFIX = '.playwright-backup';
+
+    /**
+     * 기본 대상 템플릿 → 라우트 경로.
+     *
+     * 관리자 템플릿 라우트는 관리자 URL 프리픽스 규약을 따른다.
+     *
+     * @var array<string, string>
+     */
+    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<string, string> 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<string, mixed>|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<string, mixed>  $routes  디코드된 routes.json
+     * @return array<int, mixed> 마커 항목이 제거된 라우트 배열
+     */
+    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
+        );
+    }
+}
@@ -189,8 +189,13 @@ class BuildPluginCommand extends Command
            $this->info("🔨 빌드 시작: {$identifier}".($productionMode ? ' (프로덕션)' : ''));
        }

-        // 빌드 실행
-        $result = $this->runNpmCommand($buildCommand, $buildPath, ! $watchMode);
+        // 빌드 실행 (감시 모드에는 소스맵 억제를 주입하지 않는다 — 개발 중 디버깅 필요)
+        $result = $this->runNpmCommand(
+            $buildCommand,
+            $buildPath,
+            ! $watchMode,
+            $watchMode ? [] : $this->buildEnv($productionMode)
+        );

        if ($result === Command::SUCCESS && ! $watchMode) {
            $this->info("✅ 빌드 완료: {$identifier}");
@@ -338,15 +343,30 @@ class BuildPluginCommand extends Command
        return $failCount > 0 ? Command::FAILURE : Command::SUCCESS;
    }

+    /**
+     * 빌드 프로세스에 주입할 환경변수를 구성합니다.
+     *
+     * 프로덕션 빌드에서는 소스맵을 생성하지 않습니다. 배포 산출물에 원본 코드가
+     * 포함되는 것을 막기 위함이며, 각 vite config 가 이 값을 읽습니다.
+     *
+     * @param  bool  $productionMode  프로덕션 빌드 여부
+     * @return array<string, string> Process 에 주입할 환경변수
+     */
+    private function buildEnv(bool $productionMode): array
+    {
+        return $productionMode ? ['G7_BUILD_SOURCEMAP' => '0'] : [];
+    }
+
    /**
     * npm 명령 실행
     *
     * @param  array  $command  실행할 명령
     * @param  string  $cwd  작업 디렉토리
     * @param  bool  $waitForCompletion  완료 대기 여부
+     * @param  array<string, string>  $env  추가로 주입할 환경변수 (부모 환경에 병합됨)
     * @return int 명령 실행 결과 코드
     */
-    private function runNpmCommand(array $command, string $cwd, bool $waitForCompletion = true): int
+    private function runNpmCommand(array $command, string $cwd, bool $waitForCompletion = true, array $env = []): int
    {
        // Windows 환경에서는 cmd /c 사용
        if (PHP_OS_FAMILY === 'Windows') {
@@ -355,6 +375,11 @@ class BuildPluginCommand extends Command

        $process = new Process($command);
        $process->setWorkingDirectory($cwd);
+
+        // Symfony Process 는 지정한 env 를 부모 환경에 병합하므로(PATH 등 유지) 추가분만 넘긴다.
+        if ($env !== []) {
+            $process->setEnv($env);
+        }
        $process->setTimeout(null); // 타임아웃 없음

        if ($waitForCompletion) {
@@ -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,
        ]));

@@ -2,14 +2,21 @@

 namespace App\Console\Commands\Plugin;

-use App\Contracts\Extension\CacheInterface;
-use App\Contracts\Repositories\PluginRepositoryInterface;
+use App\Contracts\Repositories\LayoutRepositoryInterface;
+use App\Enums\LayoutSourceType;
+use App\Extension\ExtensionMiddlewareRegistry;
 use App\Extension\PluginManager;
+use App\Extension\Traits\ClearsTemplateCaches;
+use App\Extension\Traits\InvalidatesLayoutCache;
+use App\Services\ExtensionBundleService;
 use Illuminate\Console\Command;
 use Illuminate\Support\Facades\Log;

 class ClearPluginCacheCommand extends Command
 {
+    use ClearsTemplateCaches;
+    use InvalidatesLayoutCache;
+
    /**
     * The name and signature of the console command.
     */
@@ -26,14 +33,20 @@ class ClearPluginCacheCommand extends Command
     */
    public function __construct(
        private PluginManager $pluginManager,
-        private PluginRepositoryInterface $pluginRepository,
-        private CacheInterface $cache
+        protected LayoutRepositoryInterface $layoutRepository,
+        private ExtensionBundleService $bundleService
    ) {
        parent::__construct();
    }

    /**
     * Execute the console command.
+     *
+     * 실재하는 서버 캐시(플러그인 레이아웃 캐시 + 상태 키 + 미들웨어 인덱스
+     * + 버전 포함 키)를 무효화한다.
+     * 종전 forget 대상(plugin.config.{id} 등)은 writer 가 없는 유령 키였다 (#588).
+     * 해석 캐시(layout_resolver.*)는 모듈 레이아웃 전용이라 플러그인은 비대상
+     * (LayoutResolverService::resolve 의 fromModules 스코프는 plugin row 를 반환하지 않음).
     */
    public function handle(): int
    {
@@ -59,6 +72,11 @@ class ClearPluginCacheCommand extends Command

                $clearedCount = $this->clearPluginCache($identifier);

+                // 상태 키(ext.plugins.*) + 미들웨어 인덱스 + 버전 포함 키 무효화 (버전 bump)
+                PluginManager::invalidatePluginStatusCache();
+                ExtensionMiddlewareRegistry::flush();
+                $this->incrementExtensionCacheVersion();
+
                $this->info('✅ '.__('plugins.commands.cache_clear.success_single', [
                    'plugin' => $identifier,
                    'count' => $clearedCount,
@@ -67,25 +85,19 @@ class ClearPluginCacheCommand extends Command
                // 모든 플러그인 캐시 삭제
                $this->info(__('plugins.commands.cache_clear.clearing_all'));

-                // 전체 플러그인 캐시 키 삭제
-                $cacheKeys = [
-                    'plugins.all',
-                    'plugins.active',
-                    'plugins.installed',
-                ];
-
-                foreach ($cacheKeys as $key) {
-                    if ($this->cache->forget($key)) {
-                        $clearedCount++;
-                    }
-                }
-
                // 각 플러그인별 캐시 삭제
-                $allPlugins = $this->pluginManager->getAllPlugins();
-                foreach ($allPlugins as $pluginName => $plugin) {
+                foreach ($this->pluginManager->getAllPlugins() as $plugin) {
                    $clearedCount += $this->clearPluginCache($plugin->getIdentifier());
                }

+                // 상태 키 + 미들웨어 인덱스 + 버전 포함 키 무효화는 전체에서 1회면 충분
+                PluginManager::invalidatePluginStatusCache();
+                ExtensionMiddlewareRegistry::flush();
+                $this->incrementExtensionCacheVersion();
+
+                // 플러그인 프론트엔드 병합 번들 파일 삭제 (캐시 키 forget 만으로는 미삭제)
+                $clearedCount += $this->bundleService->clearBundles('plugin');
+
                $this->info('✅ '.__('plugins.commands.cache_clear.success_all', ['count' => $clearedCount]));
            }

@@ -108,25 +120,18 @@ class ClearPluginCacheCommand extends Command

    /**
     * 특정 플러그인의 캐시를 삭제합니다.
+     *
+     * 플러그인이 소유한 실재 서버 캐시는 레이아웃 캐시뿐이다 — 트레이트 단일 지점
+     * (InvalidatesLayoutCache)으로 위임해 키 규약 드리프트를 방지한다.
+     *
+     * @return int 캐시를 무효화한 레이아웃 수
     */
    private function clearPluginCache(string $identifier): int
    {
-        $clearedCount = 0;
+        $this->invalidateExtensionLayoutCache($identifier, 'plugin');

-        // 플러그인별 캐시 키 (메뉴 캐시 없음)
-        $cacheKeys = [
-            "plugin.config.{$identifier}",
-            "plugin.info.{$identifier}",
-            "plugin.routes.{$identifier}",
-            "plugin.permissions.{$identifier}",
-        ];
-
-        foreach ($cacheKeys as $key) {
-            if ($this->cache->forget($key)) {
-                $clearedCount++;
-            }
-        }
-
-        return $clearedCount;
+        return $this->layoutRepository
+            ->getBySourceIdentifier($identifier, LayoutSourceType::Plugin)
+            ->count();
    }
 }
@@ -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;
            }

@@ -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;
            }

@@ -0,0 +1,41 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\ActivityLogService;
+use Illuminate\Console\Command;
+
+/**
+ * 보존 기간이 지난 활동 로그를 정리하는 커맨드
+ */
+class PruneActivityLogsCommand extends Command
+{
+    /**
+     * The name and signature of the console command.
+     */
+    protected $signature = 'activity-log:prune {--days=365 : 보존 기간(일)}';
+
+    /**
+     * The console command description.
+     */
+    protected $description = '보존 기간이 지난 활동 로그를 삭제합니다';
+
+    /**
+     * Execute the console command.
+     *
+     * 파기 자체는 도메인 서비스가 수행합니다 — 커맨드는 옵션만 전달합니다.
+     * 보존 기간 하한과 확장 훅 발행은 그 계층이 소유합니다.
+     *
+     * @param  ActivityLogService  $service  활동 로그 서비스
+     * @return int 명령 실행 결과 코드
+     */
+    public function handle(ActivityLogService $service): int
+    {
+        $days = (int) $this->option('days');
+        $deleted = $service->prune($days);
+
+        $this->info("활동 로그 {$deleted}건이 삭제되었습니다. (보존 {$days}일)");
+
+        return self::SUCCESS;
+    }
+}
@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\IdentityLogService;
+use Illuminate\Console\Command;
+
+/**
+ * 보존 기간이 지난 본인인증 이력을 파기하는 커맨드
+ *
+ * 관리자 화면의 수동 파기 버튼과 동일한 기본 보관주기(180일)를 사용합니다.
+ */
+class PruneIdentityLogsCommand extends Command
+{
+    /**
+     * The name and signature of the console command.
+     */
+    protected $signature = 'identity:prune-logs {--days=180 : 보관 기간(일)}';
+
+    /**
+     * The console command description.
+     */
+    protected $description = '보관 기간이 지난 본인인증 이력을 파기합니다';
+
+    /**
+     * Execute the console command.
+     *
+     * 파기 자체는 도메인 서비스가 수행합니다 — 커맨드는 옵션만 전달하고,
+     * 보존 기간 하한은 그 계층이 소유합니다.
+     *
+     * @param  IdentityLogService  $service  본인인증 이력 서비스
+     * @return int 명령 실행 결과 코드
+     */
+    public function handle(IdentityLogService $service): int
+    {
+        $days = (int) $this->option('days');
+        $purged = $service->purge($days);
+
+        $this->info("본인인증 이력 {$purged}건이 파기되었습니다. (보관 {$days}일)");
+
+        return self::SUCCESS;
+    }
+}
@@ -0,0 +1,41 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\NotificationLogService;
+use Illuminate\Console\Command;
+
+/**
+ * 보존 기간이 지난 알림 발송 이력을 정리하는 커맨드
+ */
+class PruneNotificationLogsCommand extends Command
+{
+    /**
+     * The name and signature of the console command.
+     */
+    protected $signature = 'notification-log:prune {--days=90 : 보존 기간(일)}';
+
+    /**
+     * The console command description.
+     */
+    protected $description = '보존 기간이 지난 알림 발송 이력을 삭제합니다';
+
+    /**
+     * Execute the console command.
+     *
+     * 파기 자체는 도메인 서비스가 수행합니다 — 커맨드는 옵션만 전달합니다.
+     * 보존 기간 하한과 확장 훅 발행은 그 계층이 소유합니다.
+     *
+     * @param  NotificationLogService  $service  알림 발송 이력 서비스
+     * @return int 명령 실행 결과 코드
+     */
+    public function handle(NotificationLogService $service): int
+    {
+        $days = (int) $this->option('days');
+        $deleted = $service->prune($days);
+
+        $this->info("알림 발송 이력 {$deleted}건이 삭제되었습니다. (보존 {$days}일)");
+
+        return self::SUCCESS;
+    }
+}
@@ -0,0 +1,123 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\AttachmentService;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * 소유자 없는 고아 첨부파일 정리 커맨드
+ *
+ * 폼 저장 전에 즉시 업로드되는 첨부는 소유자 없이 먼저 만들어지므로, 폼을 저장하지 않고
+ * 이탈하면 파일과 기록이 그대로 남습니다. 그 잔존물을 회수합니다.
+ *
+ * 사용자 파일을 실제로 파기하므로 기본 꺼짐(운영자 옵트인)입니다. 스케줄 호출
+ * (`--scheduled`)은 설정을 false 폴백으로 확인한 뒤에만 수행합니다.
+ *
+ * @example php artisan attachments:prune-orphans --dry-run
+ * @example php artisan attachments:prune-orphans --days=7 --limit=100
+ */
+class PruneOrphanAttachmentsCommand extends Command
+{
+    /**
+     * 커맨드 이름 및 시그니처
+     *
+     * @var string
+     */
+    protected $signature = 'attachments:prune-orphans
+                            {--dry-run : 실제 삭제 없이 대상 건수만 확인}
+                            {--limit=500 : 한 번에 처리할 최대 건수}
+                            {--days= : 보존기간(일) 재정의 — 미지정 시 환경설정값}
+                            {--scheduled : 스케줄러 호출 표시 — 자동 정리 토글이 꺼져 있으면 조기 종료}';
+
+    /**
+     * 커맨드 설명
+     *
+     * @var string
+     */
+    protected $description = '소유자 없이 방치된 고아 첨부파일을 정리합니다.';
+
+    /**
+     * @param  AttachmentService  $attachmentService  첨부파일 서비스
+     */
+    public function __construct(
+        protected AttachmentService $attachmentService
+    ) {
+        parent::__construct();
+    }
+
+    /**
+     * 커맨드 실행
+     *
+     * @return int 종료 코드
+     */
+    public function handle(): int
+    {
+        if ($this->option('scheduled') && ! $this->isCleanupEnabled()) {
+            $this->info('고아 첨부 자동 정리가 꺼져 있어 실행하지 않았습니다. (upload.orphan_cleanup_enabled = false)');
+
+            return Command::SUCCESS;
+        }
+
+        $days = $this->resolveRetentionDays();
+
+        if ($days < 1) {
+            $this->info('고아 첨부 보존기간이 1일 미만이어서 정리를 수행하지 않았습니다.');
+
+            return Command::SUCCESS;
+        }
+
+        $limit = max(1, (int) $this->option('limit'));
+        $isDryRun = (bool) $this->option('dry-run');
+
+        $result = $this->attachmentService->pruneOrphans($days, $limit, $isDryRun);
+
+        if ($isDryRun) {
+            $this->info("[DRY RUN] 보존기간({$days}일) 경과 고아 첨부: {$result['scanned']}건");
+
+            return Command::SUCCESS;
+        }
+
+        $this->info(sprintf(
+            '보존기간(%d일) 경과 고아 첨부 %d건 중 %d건을 삭제했습니다. (실패 %d건)',
+            $days,
+            $result['scanned'],
+            $result['deleted'],
+            $result['failed'],
+        ));
+
+        Log::info('PruneOrphanAttachmentsCommand: 고아 첨부 정리 완료', [
+            'days' => $days,
+            'limit' => $limit,
+        ] + $result);
+
+        return Command::SUCCESS;
+    }
+
+    /**
+     * 자동 정리 토글을 false 폴백으로 조회합니다.
+     *
+     * @return bool 자동 정리 활성 여부
+     */
+    private function isCleanupEnabled(): bool
+    {
+        return (bool) g7_core_settings('upload.orphan_cleanup_enabled', false);
+    }
+
+    /**
+     * 보존기간을 해석합니다 (옵션 > 환경설정 > 기본 30일).
+     *
+     * @return int 보존기간(일)
+     */
+    private function resolveRetentionDays(): int
+    {
+        $option = $this->option('days');
+
+        if ($option !== null && $option !== '') {
+            return (int) $option;
+        }
+
+        return (int) g7_core_settings('upload.orphan_retention_days', 30);
+    }
+}
@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\ScheduleService;
+use Illuminate\Console\Command;
+
+/**
+ * 보존 기간이 지난 스케줄 실행 이력을 정리하는 커맨드
+ *
+ * 이력 행은 출력(longText)을 포함해 실행마다 누적되므로 정리 주체가 없으면 무한히 성장합니다.
+ */
+class PruneScheduleHistoryCommand extends Command
+{
+    /**
+     * The name and signature of the console command.
+     */
+    protected $signature = 'schedules:prune-history {--days=90 : 보존 기간(일)}';
+
+    /**
+     * The console command description.
+     */
+    protected $description = '보존 기간이 지난 스케줄 실행 이력을 삭제합니다';
+
+    /**
+     * Execute the console command.
+     *
+     * 파기 자체는 도메인 서비스가 수행합니다 — 커맨드는 옵션만 전달합니다.
+     * 보존 기간 하한과 확장 훅 발행은 그 계층이 소유합니다.
+     *
+     * @param  ScheduleService  $service  스케줄 서비스
+     * @return int 명령 실행 결과 코드
+     */
+    public function handle(ScheduleService $service): int
+    {
+        $days = (int) $this->option('days');
+        $deleted = $service->pruneHistory($days);
+
+        $this->info("스케줄 실행 이력 {$deleted}건이 삭제되었습니다. (보존 {$days}일)");
+
+        return self::SUCCESS;
+    }
+}
@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Seo\SeoCacheStatsService;
+use Illuminate\Console\Command;
+
+/**
+ * 보존 기간이 지난 SEO 캐시 통계를 정리하는 커맨드
+ *
+ * 통계 행은 봇 요청마다 누적되므로 정리 주체가 없으면 무한히 성장합니다.
+ */
+class PruneSeoCacheStatsCommand extends Command
+{
+    /**
+     * The name and signature of the console command.
+     */
+    protected $signature = 'seo:prune-stats {--days=30 : 보존 기간(일)}';
+
+    /**
+     * The console command description.
+     */
+    protected $description = '보존 기간이 지난 SEO 캐시 통계 기록을 삭제합니다';
+
+    /**
+     * Execute the console command.
+     *
+     * 파기 자체는 도메인 서비스가 수행합니다 — 커맨드는 옵션만 전달하고,
+     * 보존 기간 하한은 그 계층이 소유합니다.
+     *
+     * @param  SeoCacheStatsService  $service  SEO 캐시 통계 서비스
+     * @return int 명령 실행 결과 코드
+     */
+    public function handle(SeoCacheStatsService $service): int
+    {
+        $days = (int) $this->option('days');
+        $deleted = $service->cleanup($days);
+
+        $this->info("SEO 캐시 통계 {$deleted}건이 삭제되었습니다. (보존 {$days}일)");
+
+        return self::SUCCESS;
+    }
+}
@@ -0,0 +1,81 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\StorageLeftoverPruneService;
+use Illuminate\Console\Command;
+
+/**
+ * 스토리지 잔존물 정리 커맨드
+ *
+ * 확장/코어 업데이트·설치가 중단되며 남긴 임시 산출물(_pending 스테이징 ·
+ * storage/app/temp · vendor 번들 스테이징)과 오래된 백업본, 레거시 브라우저 로그를
+ * 회수한다. 로직은 `StorageLeftoverPruneService` 가 소유한다
+ * (`CleanupExtensionBundlesCommand` 위임 패턴 미러).
+ */
+class PruneStorageLeftoversCommand extends Command
+{
+    /**
+     * The name and signature of the console command.
+     */
+    protected $signature = 'storage:prune-leftovers
+                            {--days=3 : 임시 산출물 보존일 (mtime 기준, 경과분 삭제)}
+                            {--backup-days=30 : 백업 보존일 (identifier 별 최신 1개는 나이와 무관하게 보존)}
+                            {--dry-run : 실제 삭제 없이 대상 목록만 확인}';
+
+    /**
+     * The console command description.
+     */
+    protected $description = '중단된 업데이트·설치가 남긴 임시 산출물과 오래된 백업본을 정리합니다';
+
+    /**
+     * 대상군 키 → 출력 라벨.
+     *
+     * @var array<string, string>
+     */
+    private const GROUP_LABELS = [
+        'staging' => '업데이트 스테이징 잔존',
+        'temp' => '코어 임시 산출물',
+        'vendor_bundle_staging' => 'vendor 번들 스테이징',
+        'extension_backups' => '확장 백업',
+        'core_backups' => '코어 백업',
+        'legacy_browser_log' => '레거시 브라우저 로그',
+    ];
+
+    /**
+     * Execute the console command.
+     *
+     * @param  StorageLeftoverPruneService  $service  잔존물 정리 서비스
+     * @return int 명령 실행 결과 코드
+     */
+    public function handle(StorageLeftoverPruneService $service): int
+    {
+        $days = max(0, (int) $this->option('days'));
+        $backupDays = max(0, (int) $this->option('backup-days'));
+        $dryRun = (bool) $this->option('dry-run');
+
+        $result = $service->prune($days, $backupDays, $dryRun);
+
+        $total = 0;
+
+        foreach (self::GROUP_LABELS as $key => $label) {
+            $paths = $result[$key] ?? [];
+            $count = count($paths);
+            $total += $count;
+
+            $this->line("{$label}: {$count}건");
+
+            if ($dryRun) {
+                foreach ($paths as $path) {
+                    $this->line("  - {$path}");
+                }
+            }
+        }
+
+        $this->info($dryRun
+            ? "삭제 대상 합계 {$total}건 (dry-run — 실제 삭제 없음)"
+            : "합계 {$total}건이 삭제되었습니다. (임시 보존일: {$days}일, 백업 보존일: {$backupDays}일)");
+
+        return self::SUCCESS;
+    }
+}
@@ -0,0 +1,194 @@
+<?php
+
+namespace App\Console\Commands\Search;
+
+use App\Console\Commands\Traits\HasUnifiedConfirm;
+use App\Enums\SearchIndexStatus;
+use App\Search\DTO\SearchIndexHealth;
+use App\Search\SearchIndexMaintenanceManager;
+use Illuminate\Console\Command;
+
+/**
+ * 검색 인덱스 점검·재생성 커맨드
+ *
+ * 인덱스는 있는데 내용이 색인되지 않아 검색이 조용히 0건을 돌려주는 상태를 검출하고,
+ * 운영자가 선택하면 재생성합니다. 이 상태는 예외도 로그도 남기지 않으므로
+ * "원래 검색이 안 되는 줄" 알고 지나가기 쉽습니다.
+ *
+ * 점검 방법은 **활성 Scout 엔진의 유지보수기**가 정합니다. 확장이 자체 검색 엔진을
+ * 등록하면서 유지보수기를 함께 등록하면 이 커맨드가 그대로 그 엔진을 다룹니다
+ * (`core.search.index_maintainers` 필터 훅).
+ *
+ * 사용 예시:
+ *   php artisan search:index                       # 활성 엔진의 인덱스 점검 (읽기 전용)
+ *   php artisan search:index --repair              # 색인 누락 인덱스 재생성
+ *   php artisan search:index --filter=table=pages  # 엔진별 필터 전달
+ *   php artisan search:index --json                # 기계 판독용 출력
+ */
+class SearchIndexCommand extends Command
+{
+    use HasUnifiedConfirm;
+
+    protected $signature = 'search:index
+        {--repair : 색인이 누락된 인덱스를 재생성 (미지정 시 점검만)}
+        {--filter=* : 엔진별 필터 (key=value 형태, 다중 지정 가능. FULLTEXT: table, index, samples)}
+        {--json : 기계 판독용 JSON 출력}';
+
+    protected $description = '활성 검색 엔진의 인덱스가 실제로 내용을 색인하고 있는지 점검하고, 누락 시 재생성합니다';
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * @param  SearchIndexMaintenanceManager  $manager  검색 인덱스 유지보수 진입점
+     * @return int 종료 코드 (색인 누락 잔존 시 1)
+     */
+    public function handle(SearchIndexMaintenanceManager $manager): int
+    {
+        $driver = $manager->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<string, string>
+     */
+    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<int, SearchIndexHealth>  $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<int, SearchIndexHealth>  $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,
+            '<fg='.$health->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('  <comment>'.__('search.index.degraded_hint').'</comment>');
+        }
+    }
+}
@@ -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'));
+    }
 }
@@ -181,8 +181,13 @@ class BuildTemplateCommand extends Command
            $this->info("🔨 빌드 시작: {$identifier}".($productionMode ? ' (프로덕션)' : ''));
        }

-        // 빌드 실행
-        $result = $this->runNpmCommand($buildCommand, $buildPath, ! $watchMode);
+        // 빌드 실행 (감시 모드에는 소스맵 억제를 주입하지 않는다 — 개발 중 디버깅 필요)
+        $result = $this->runNpmCommand(
+            $buildCommand,
+            $buildPath,
+            ! $watchMode,
+            $watchMode ? [] : $this->buildEnv($productionMode)
+        );

        if ($result === Command::SUCCESS && ! $watchMode) {
            $this->info("✅ 빌드 완료: {$identifier}");
@@ -285,15 +290,30 @@ class BuildTemplateCommand extends Command
        return $failCount > 0 ? Command::FAILURE : Command::SUCCESS;
    }

+    /**
+     * 빌드 프로세스에 주입할 환경변수를 구성합니다.
+     *
+     * 프로덕션 빌드에서는 소스맵을 생성하지 않습니다. 배포 산출물에 원본 코드가
+     * 포함되는 것을 막기 위함이며, 각 vite config 가 이 값을 읽습니다.
+     *
+     * @param  bool  $productionMode  프로덕션 빌드 여부
+     * @return array<string, string> Process 에 주입할 환경변수
+     */
+    private function buildEnv(bool $productionMode): array
+    {
+        return $productionMode ? ['G7_BUILD_SOURCEMAP' => '0'] : [];
+    }
+
    /**
     * npm 명령 실행
     *
     * @param  array  $command  실행할 명령
     * @param  string  $cwd  작업 디렉토리
     * @param  bool  $waitForCompletion  완료 대기 여부
+     * @param  array<string, string>  $env  추가로 주입할 환경변수 (부모 환경에 병합됨)
     * @return int 명령 실행 결과 코드
     */
-    private function runNpmCommand(array $command, string $cwd, bool $waitForCompletion = true): int
+    private function runNpmCommand(array $command, string $cwd, bool $waitForCompletion = true, array $env = []): int
    {
        // Windows 환경에서는 cmd /c 사용
        if (PHP_OS_FAMILY === 'Windows') {
@@ -302,6 +322,11 @@ class BuildTemplateCommand extends Command

        $process = new Process($command);
        $process->setWorkingDirectory($cwd);
+
+        // Symfony Process 는 지정한 env 를 부모 환경에 병합하므로(PATH 등 유지) 추가분만 넘긴다.
+        if ($env !== []) {
+            $process->setEnv($env);
+        }
        $process->setTimeout(null); // 타임아웃 없음

        if ($waitForCompletion) {
@@ -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,
        ]));

@@ -2,15 +2,17 @@

 namespace App\Console\Commands\Template;

-use App\Contracts\Extension\CacheInterface;
 use App\Extension\TemplateManager;
+use App\Extension\Traits\ClearsTemplateCaches;
 use App\Models\Template;
-use App\Models\TemplateLayout;
+use App\Services\ExtensionBundleService;
 use Illuminate\Console\Command;
 use Illuminate\Support\Facades\Log;

 class ClearTemplateCacheCommand extends Command
 {
+    use ClearsTemplateCaches;
+
    /**
     * The name and signature of the console command.
     */
@@ -27,7 +29,7 @@ class ClearTemplateCacheCommand extends Command
     */
    public function __construct(
        private TemplateManager $templateManager,
-        private CacheInterface $cache
+        private ExtensionBundleService $bundleService
    ) {
        parent::__construct();
    }
@@ -65,6 +67,10 @@ class ClearTemplateCacheCommand extends Command

    /**
     * 특정 템플릿의 캐시 삭제
+     *
+     * 라이프사이클(update/deactivate/uninstall)과 동일한 무효화 단일 지점
+     * (`TemplateManager::clearTemplateCache()`)을 경유한다 — 커맨드가 키 목록을
+     * 별도로 유지하면 키 규약 변경 시 유령 forget 으로 사문화된다 (#588, 공개 #119).
     */
    private function clearSingleTemplateCache(string $identifier): void
    {
@@ -76,34 +82,12 @@ class ClearTemplateCacheCommand extends Command

        $this->info(__('templates.commands.cache_clear.clearing_single', ['template' => $identifier]));

-        $clearedCount = 0;
+        // 고정 키(config/components_manifest) + 현재 버전 routes/language + 레이아웃 캐시
+        $clearedCount = $this->templateManager->clearTemplateCache($identifier);

-        // 1. 레이아웃 캐시 삭제
-        $templateRecord = Template::where('identifier', $identifier)->first();
-        if ($templateRecord) {
-            $layouts = TemplateLayout::where('template_id', $templateRecord->id)->get();
-            foreach ($layouts as $layout) {
-                $this->cache->forget("layout.{$identifier}.{$layout->name}");
-                $clearedCount++;
-            }
-        }
-
-        // 2. Routes 캐시 삭제
-        $this->cache->forget("template.routes.{$identifier}");
-        $clearedCount++;
-
-        // 3. 다국어 파일 캐시 삭제
-        $supportedLocales = config('app.supported_locales', ['ko', 'en']);
-        foreach ($supportedLocales as $locale) {
-            $this->cache->forget("template.language.{$identifier}.{$locale}");
-            $clearedCount++;
-        }
-
-        // 4. 활성 템플릿 타입 캐시 삭제
-        if ($templateRecord) {
-            $this->cache->forget("templates.active.{$templateRecord->type}");
-            $clearedCount++;
-        }
+        // 상태 키(ext.templates.*) + 버전 포함 키 무효화 (버전 bump)
+        TemplateManager::invalidateTemplateStatusCache();
+        $this->incrementExtensionCacheVersion();

        $this->info('✅ '.__('templates.commands.cache_clear.success_single', [
            'template' => $identifier,
@@ -124,34 +108,18 @@ class ClearTemplateCacheCommand extends Command
        $this->info(__('templates.commands.cache_clear.clearing_all'));

        $clearedCount = 0;
-        $supportedLocales = config('app.supported_locales', ['ko', 'en']);

-        // 모든 설치된 템플릿의 캐시 삭제
-        $templates = Template::all();
-
-        foreach ($templates as $templateRecord) {
-            // 1. 레이아웃 캐시 삭제
-            $layouts = TemplateLayout::where('template_id', $templateRecord->id)->get();
-            foreach ($layouts as $layout) {
-                $this->cache->forget("layout.{$templateRecord->identifier}.{$layout->name}");
-                $clearedCount++;
-            }
-
-            // 2. Routes 캐시 삭제
-            $this->cache->forget("template.routes.{$templateRecord->identifier}");
-            $clearedCount++;
-
-            // 3. 다국어 파일 캐시 삭제
-            foreach ($supportedLocales as $locale) {
-                $this->cache->forget("template.language.{$templateRecord->identifier}.{$locale}");
-                $clearedCount++;
-            }
+        // 모든 설치된 템플릿의 캐시 삭제 (설치 레코드 기준 — 라이프사이클과 동일 지점)
+        foreach (Template::all() as $templateRecord) {
+            $clearedCount += $this->templateManager->clearTemplateCache($templateRecord->identifier);
        }

-        // 4. 활성 템플릿 타입 캐시 삭제
-        $this->cache->forget('templates.active.admin');
-        $this->cache->forget('templates.active.user');
-        $clearedCount += 2;
+        // 상태 키 + 버전 포함 키 무효화는 전체에서 1회면 충분
+        TemplateManager::invalidateTemplateStatusCache();
+        $this->incrementExtensionCacheVersion();
+
+        // 확장 프론트엔드 병합 번들 파일 전체 삭제 (템플릿 캐시 정리는 페이지 전면 갱신)
+        $clearedCount += $this->bundleService->clearBundles();

        $this->info('✅ '.__('templates.commands.cache_clear.success_all', [
            'count' => $clearedCount,
@@ -3,6 +3,7 @@
 namespace App\Console\Commands\Traits;

 use App\Console\Helpers\ConsoleConfirm;
+use Symfony\Component\Console\Input\StreamableInputInterface;

 /**
 * Laravel Command 컨텍스트에서 표준화된 yes/no 프롬프트를 제공하는 트레이트.
@@ -12,6 +13,7 @@ use App\Console\Helpers\ConsoleConfirm;
 * 재질문 루프는 ConsoleConfirm::parse() 와 공유한다.
 *
 * - `--no-interaction` 시: $default 즉시 반환
+ * - 응답을 받을 수 없는 실행(콘솔 없는 STDIN) 시: $default 즉시 반환
 * - empty 입력 시: $default 반환
 * - yes/y → true, no/n → false (대소문자 무시)
 * - 그 외 입력: "yes, y, no, n 중 하나로 입력해 주세요." 출력 후 재질문
@@ -26,7 +28,7 @@ trait HasUnifiedConfirm
     */
    protected function unifiedConfirm(string $question, bool $default = false): bool
    {
-        if (! $this->input->isInteractive()) {
+        if (! $this->input->isInteractive() || ! $this->canPromptForAnswer()) {
            return $default;
        }

@@ -47,4 +49,38 @@ trait HasUnifiedConfirm
            $this->warn('  yes, y, no, n 중 하나로 입력해 주세요.');
        }
    }
+
+    /**
+     * 이 실행이 프롬프트 응답을 실제로 받을 수 있는지 판정합니다.
+     *
+     * Symfony 는 `posix_isatty()` 로 비대화 실행을 감지해 `isInteractive()` 를 false 로
+     * 내리는데, Windows PHP 에는 posix 확장이 없어 그 분기가 실행되지 않는다. 그래서
+     * `--no-interaction` 없이 CI·스케줄러·에이전트처럼 콘솔이 없는 곳에서 부르면
+     * `isInteractive()` 가 true 로 남고 `ask()` 가 오지 않을 응답을 무한히 기다린다.
+     * 프롬프트 출력마저 버퍼에 갇혀 있어 겉으로는 "커맨드가 느리다" 로만 보인다.
+     *
+     * `stream_isatty()` 는 posix 확장 없이도 Windows 를 포함해 동작하므로 이를 쓴다.
+     * 판정 재료가 없으면 true 를 돌려 기존 동작(질문)을 유지한다 — 물어보지 못해 멈추는
+     * 것보다 물어볼 수 있는데 안 묻는 쪽이 더 위험하기 때문이다.
+     *
+     * @return bool 응답을 받을 수 있으면 true
+     */
+    protected function canPromptForAnswer(): bool
+    {
+        // 테스트는 QuestionHelper 를 대체하거나 입력을 주입하므로 STDIN 을 쓰지 않는다
+        if ($this->laravel !== null && $this->laravel->runningUnitTests()) {
+            return true;
+        }
+
+        // 입력 스트림이 주입된 실행(CommandTester::setInputs 등)도 STDIN 과 무관하다
+        if ($this->input instanceof StreamableInputInterface && is_resource($this->input->getStream())) {
+            return true;
+        }
+
+        if (! \defined('STDIN') || ! is_resource(STDIN) || ! \function_exists('stream_isatty')) {
+            return true;
+        }
+
+        return stream_isatty(STDIN);
+    }
 }
@@ -0,0 +1,114 @@
+<?php
+
+namespace App\Console\Commands\Traits;
+
+use App\Search\DTO\SearchIndexHealth;
+use App\Search\DTO\SearchIndexRepairReport;
+use App\Search\SearchIndexMaintenanceManager;
+
+/**
+ * 설치·업데이트 커맨드에 "검색 인덱스 재생성" 선택 옵션을 제공하는 트레이트.
+ *
+ * 재생성 비용은 엔진마다 다르지만(테이블 잠금 / 전체 재색인) 어느 쪽이든 운영 중인
+ * 사이트에 영향을 줍니다. 그래서 **기본값은 재생성하지 않음**이고, 운영자가
+ * `--rebuild-search-index` 로 명시했을 때만 수행합니다.
+ *
+ * 옵션을 주지 않아도 점검 결과는 안내합니다 — 색인이 누락되면 검색이 오류 없이 0건을
+ * 돌려주므로, 알려주지 않으면 운영자가 알 방법이 없습니다.
+ */
+trait RebuildsSearchIndex
+{
+    /**
+     * 커맨드 `$signature` 에 붙일 옵션 정의.
+     *
+     * @return string 옵션 시그니처 조각
+     */
+    public static function rebuildSearchIndexOption(): string
+    {
+        return '{--rebuild-search-index : 완료 후 색인이 누락된 검색 인덱스를 재생성 (인덱스가 잠기거나 재색인됩니다 — 운영 중에는 점검 결과만 확인하고 유지보수 시간에 수행하세요)}';
+    }
+
+    /**
+     * 작업 완료 후 검색 인덱스를 점검하고, 요청이 있었으면 재생성합니다.
+     *
+     * @param  bool|null  $requested  재생성 요청 여부 (null 이면 커맨드 옵션에서 읽음)
+     * @return SearchIndexRepairReport|null 재생성 보고 (재생성을 하지 않았으면 null)
+     */
+    protected function handleSearchIndexRebuild(?bool $requested = null): ?SearchIndexRepairReport
+    {
+        $manager = app(SearchIndexMaintenanceManager::class);
+
+        // 점검을 제공하지 않는 엔진에서는 조용히 넘어간다 (검색 자체는 정상 동작)
+        if (! $manager->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<int, SearchIndexHealth>  $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]));
+        }
+    }
+}
@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Contracts\ApiDoc;
+
+/**
+ * API 문서 실측용 완전 샘플 시더 계약
+ *
+ * 확장(모듈/플러그인)이 자신의 API 도메인 대표 엔티티에 완전한 샘플 레코드를
+ * 멱등하게 생성하고, docgen 이 상세 GET 실측(path 파라미터 치환)에 사용할
+ * 도메인별 대표 route key 맵을 제공하기 위한 인터페이스입니다.
+ *
+ * 확장은 이 인터페이스를 구현한 클래스를 `{Namespace}\Support\ApiDoc\ApiDocSampleService`
+ * 규약 위치에 두며, `api:docgen --scope=module:{id}` 실행 시 커맨드가 자동으로 발견합니다.
+ * 코어의 `App\Support\ApiDoc\ApiDocSampleService` 도 동일 계약을 구현합니다.
+ */
+interface ApiDocSampleSeeder
+{
+    /**
+     * 도메인별 완전 샘플을 멱등 생성하고 대표 route key 맵을 반환합니다.
+     *
+     * 반환 맵의 키는 라우트 도메인 그룹명(`domain_group`, 예: pages)이며,
+     * 값은 그 도메인의 상세 GET path 파라미터를 실측 가능한 실제 레코드로
+     * 치환하기 위한 모델 FQCN·route key 이름·route key 값입니다.
+     *
+     * 선택 필드 `path_params`(param 명 => 실제 값 맵)를 두면, route-model binding
+     * 도 도메인 폴백도 없는 문자열 path 파라미터(예: 게시판 slug 라우팅
+     * `boards/{slug}/posts/{id}`)를 param 명 정확 일치로 치환해 상세 GET 을
+     * 실측할 수 있습니다. 미제공 시 route key 기반 자동 치환만 적용됩니다.
+     *
+     * @return array<string, array{model: class-string, key: string, value: string, path_params?: array<string, string>}> 도메인 => 대표 레코드 정보
+     */
+    public function seed(): array;
+}
@@ -25,6 +25,17 @@ interface CacheableExtensionInterface
     */
    public function getStorage(): StorageInterface;

+    /**
+     * 카테고리별 스토리지 드라이버를 반환합니다.
+     *
+     * getStorageDiskFor($category) 가 결정한 디스크의 인스턴스를 반환하며,
+     * 기본 구현은 getStorage() 와 동일한 디스크를 사용합니다.
+     *
+     * @param  string  $category  카테고리 (settings, attachments, images, cache, temp)
+     * @return StorageInterface 카테고리 디스크의 스토리지 인스턴스
+     */
+    public function getStorageFor(string $category): StorageInterface;
+
    /**
     * 확장 도메인에 격리된 캐시 드라이버를 반환합니다.
     *
@@ -0,0 +1,34 @@
+<?php
+
+namespace App\Contracts\Extension;
+
+/**
+ * 확장 선언 미들웨어의 라우트 매칭 인덱스 계약.
+ *
+ * 활성 확장(모듈/플러그인)이 `getMiddleware()` 로 선언한 미들웨어를 수집해,
+ * 요청 시점에 라우트 이름·URI 를 각 선언의 `targets` 술어와 대조하여 매칭되는
+ * 미들웨어 FQCN 목록을 반환합니다. 코어 self-gate 게이트(`ExtensionMiddlewareGate`)가
+ * 이 계약을 사용해 그룹/timing 별로 매칭 미들웨어를 동적 실행합니다.
+ *
+ * 부팅 시점 라우트 순회로 확장 간 미들웨어를 부착할 수 없는 제약(확장 라우트는
+ * booted 지연 등록 + 순서 미보장)을 요청 시점 매칭으로 원천 회피합니다.
+ * IDV `IdentityPolicyRepository::getRouteScopeIndex()` 미러.
+ *
+ * @since 7.0.5
+ */
+interface ExtensionMiddlewareRegistryInterface
+{
+    /**
+     * 현재 요청에 매칭되는 확장 미들웨어 FQCN 목록을 반환합니다.
+     *
+     * 게이트 래퍼가 자기 그룹·timing 을 전달하면, 그 축의 엔트리 중 라우트명 또는
+     * URI 술어가 매칭되는 것을 확장 로드 순서대로 반환합니다.
+     *
+     * @param  string  $routeName  현재 요청 라우트 이름 (무명 라우트면 빈 문자열)
+     * @param  string  $path  현재 요청 URI path (선행 슬래시 없음, 무명 라우트 타게팅용)
+     * @param  string  $group  요청이 속한 그룹 ('web'|'api')
+     * @param  string  $timing  실행 시점 ('before_core'|'after_core')
+     * @return array<int, class-string> 매칭된 확장 미들웨어 FQCN (선언 순서 = 확장 로드 순서)
+     */
+    public function resolveForRoute(string $routeName, string $path, string $group, string $timing): array;
+}
@@ -2,6 +2,8 @@

 namespace App\Contracts\Extension;

+use Symfony\Component\HttpFoundation\StreamedResponse;
+
 /**
 * 확장(모듈/플러그인) 스토리지 인터페이스
 *
@@ -50,12 +52,14 @@ interface StorageInterface
    /**
     * 파일의 공개 URL을 반환합니다.
     *
-     * public disk인 경우 직접 URL을 반환하고,
-     * private disk인 경우 null을 반환합니다 (별도 API 엔드포인트 사용).
+     * public 디스크이거나 `filesystems.disks.{disk}.url` 이 설정된 디스크(S3+CDN 등)면
+     * 직접 URL 을 반환하고, 그 외에는 null 을 반환합니다 (별도 API 엔드포인트 사용).
+     * 생성 결과는 디스크 종류와 무관하게 `core.storage.filter_url` 필터 훅을 항상 통과하므로,
+     * 확장이 URL 을 공급/수정/차단할 수 있습니다 (null 반환도 훅 발화 대상).
     *
     * @param  string  $category  카테고리
     * @param  string  $path  파일 경로
-     * @return string|null 파일 URL (private disk인 경우 null)
+     * @return string|null 파일 URL (직접 URL 불가 디스크이고 훅 공급도 없으면 null)
     */
    public function url(string $category, string $path): ?string;

@@ -110,9 +114,9 @@ interface StorageInterface
     * @param  string  $path  파일 경로
     * @param  string  $filename  다운로드 시 표시될 파일명
     * @param  array  $headers  추가 HTTP 헤더
-     * @return \Symfony\Component\HttpFoundation\StreamedResponse|null 파일 스트림 (파일이 없으면 null)
+     * @return StreamedResponse|null 파일 스트림 (파일이 없으면 null)
     */
-    public function response(string $category, string $path, string $filename, array $headers = []): ?\Symfony\Component\HttpFoundation\StreamedResponse;
+    public function response(string $category, string $path, string $filename, array $headers = []): ?StreamedResponse;

    /**
     * 사용할 디스크를 변경한 새 인스턴스를 반환합니다.
@@ -132,7 +136,7 @@ interface StorageInterface
     * @param  string  $path  파일 경로
     * @param  string  $filename  다운로드 시 표시될 파일명
     * @param  array  $headers  추가 HTTP 헤더
-     * @return \Symfony\Component\HttpFoundation\StreamedResponse|null 다운로드 응답 (파일이 없으면 null)
+     * @return StreamedResponse|null 다운로드 응답 (파일이 없으면 null)
     */
-    public function download(string $category, string $path, string $filename, array $headers = []): ?\Symfony\Component\HttpFoundation\StreamedResponse;
+    public function download(string $category, string $path, string $filename, array $headers = []): ?StreamedResponse;
 }
@@ -7,10 +7,18 @@ use App\Enums\DeactivationReason;
 interface TemplateManagerInterface
 {
    /**
-     * 모든 템플릿을 로드하고 초기화합니다.
+     * 모든 템플릿을 로드하고 초기화합니다. (항상 재스캔)
     */
    public function loadTemplates(): void;

+    /**
+     * 템플릿이 아직 로드되지 않았을 때만 로드합니다. (멱등)
+     *
+     * "맵이 채워져 있기만 하면 되는" 소비자용 진입점. 재스캔이 필요한 경우
+     * (설치/삭제/업데이트 직후)에만 `loadTemplates()` 를 직접 호출합니다.
+     */
+    public function ensureLoaded(): void;
+
    /**
     * /templates 디렉토리를 스캔하여 사용 가능한 템플릿을 발견합니다.
     *
@@ -0,0 +1,39 @@
+<?php
+
+namespace App\Contracts\Pagination;
+
+use App\Enums\TotalRelation;
+
+/**
+ * 총 건수 정확도를 스스로 밝히는 페이지 결과 계약
+ *
+ * 표준 `LengthAwarePaginator` 는 `total()` 이 항상 정확하다고 가정한다. 대용량 목록에서
+ * 상한을 걸고 센 결과는 그 가정을 만족하지 못하므로, 정확도를 함께 실어 나른다.
+ *
+ * 이 계약을 구현한 페이지는 `BaseApiCollection::paginationMeta()` 가 자동으로 알아보고
+ * `total_relation` / `total_is_exact` / `result_cap` 메타를 응답에 덧붙인다. 컬렉션 쪽
+ * 코드 변경은 필요 없다.
+ */
+interface BoundedTotalAware
+{
+    /**
+     * 총 건수와 실제 매칭 건수의 관계를 반환합니다.
+     *
+     * @return TotalRelation 정확(Exact) 또는 하한(AtLeast)
+     */
+    public function totalRelation(): TotalRelation;
+
+    /**
+     * 총 건수 집계에 적용된 상한을 반환합니다.
+     *
+     * @return int|null 상한 (무제한이면 null)
+     */
+    public function resultCap(): ?int;
+
+    /**
+     * 총 건수가 상한에 걸려 잘렸는지 여부를 반환합니다.
+     *
+     * @return bool 잘렸으면 true (= totalRelation 이 AtLeast)
+     */
+    public function isTruncated(): bool;
+}
@@ -2,6 +2,7 @@

 namespace App\Contracts\Repositories;

+use Illuminate\Contracts\Pagination\CursorPaginator;
 use Illuminate\Contracts\Pagination\LengthAwarePaginator;
 use Illuminate\Database\Eloquent\Collection;
 use Illuminate\Database\Eloquent\Model;
@@ -18,20 +19,22 @@ interface ActivityLogRepositoryInterface
     * @param  array  $filters  필터 조건
     * @return LengthAwarePaginator 페이지네이션된 로그 목록
     */
-
    public function getPaginatedForModel(Model $model, array $filters = []): LengthAwarePaginator;
+
    /**
     * 활동 로그 목록을 페이지네이션하여 조회합니다.
     *
+     * 요청에 `cursor` 가 있으면 키셋(커서) 방식으로 응답합니다.
+     *
     * @param  array  $filters  필터 조건
-     * @return LengthAwarePaginator 페이지네이션된 로그 목록
+     * @return LengthAwarePaginator|CursorPaginator 페이지네이션된 로그 목록
     */
-    public function getPaginated(array $filters = []): LengthAwarePaginator;
+    public function getPaginated(array $filters = []): LengthAwarePaginator|CursorPaginator;

    /**
     * 활동 로그를 삭제합니다.
     *
-     * @param int $id 삭제할 활동 로그 ID
+     * @param  int  $id  삭제할 활동 로그 ID
     * @return bool 삭제 성공 여부
     */
    public function delete(int $id): bool;
@@ -39,7 +42,7 @@ interface ActivityLogRepositoryInterface
    /**
     * 여러 활동 로그를 일괄 삭제합니다.
     *
-     * @param array<int> $ids 삭제할 활동 로그 ID 목록
+     * @param  array<int>  $ids  삭제할 활동 로그 ID 목록
     * @return int 삭제된 건수
     */
    public function deleteMany(array $ids): int;
@@ -62,4 +65,12 @@ interface ActivityLogRepositoryInterface
     * @return int 익명화된 row 수
     */
    public function anonymizeUserId(int $userId): int;
+
+    /**
+     * 보존 기간이 지난 활동 로그를 삭제합니다.
+     *
+     * @param  int  $days  보존 기간 (일)
+     * @return int 삭제된 건수
+     */
+    public function deleteOlderThan(int $days): int;
 }
@@ -4,6 +4,7 @@ namespace App\Contracts\Repositories;

 use App\Models\Attachment;
 use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Support\Carbon;

 /**
 * 첨부파일 Repository 인터페이스
@@ -18,6 +19,17 @@ interface AttachmentRepositoryInterface
     */
    public function findById(int $id): ?Attachment;

+    /**
+     * 소프트삭제된 행까지 포함해 ID로 첨부파일 조회
+     *
+     * 영구 삭제(파일+forceDelete) 경로 전용이다. 소프트삭제된 행은 기본 조회에서 빠지므로,
+     * 이 메서드 없이 영구 삭제를 시도하면 대상을 찾지 못해 매 회차 실패만 누적된다.
+     *
+     * @param  int  $id  첨부파일 ID
+     * @return Attachment|null 첨부파일 또는 null
+     */
+    public function findByIdWithTrashed(int $id): ?Attachment;
+
    /**
     * 여러 ID로 첨부파일 조회 (order 정렬)
     *
@@ -145,4 +157,20 @@ interface AttachmentRepositoryInterface
     * @param  string  $collection  컬렉션명
     */
    public function reorderAfterDelete(string $attachmentableType, int $attachmentableId, string $collection): void;
+
+    /**
+     * 소유자 없이 방치된 고아 첨부 후보를 오래된 순으로 조회합니다.
+     *
+     * 폼 저장 전에 즉시 업로드되는 첨부는 소유자(attachmentable) 없이 먼저 생성되므로,
+     * 폼을 저장하지 않고 이탈하면 그대로 남습니다. 그 회수 대상을 찾습니다.
+     *
+     * 확장이 소유한 첨부(source_identifier 보유)는 그 확장의 라이프사이클 소관이므로 제외하고,
+     * 현역으로 쓰이는 첨부 ID 는 호출자가 넘겨 보호합니다.
+     *
+     * @param  Carbon  $threshold  기준 시각 (이 시각 이전 업로드가 대상)
+     * @param  int  $limit  최대 조회 건수
+     * @param  array<int, int>  $protectedIds  보호할 첨부 ID 목록 (현역 사이트 로고 등)
+     * @return Collection 고아 첨부 후보 (created_at 오름차순, 소프트 삭제분 포함)
+     */
+    public function findOrphanCandidates(Carbon $threshold, int $limit, array $protectedIds = []): Collection;
 }
@@ -72,13 +72,24 @@ interface LanguagePackRepositoryInterface
    public function getActiveCoreLocales(): array;

    /**
-     * 페이지네이션 + 필터링된 언어팩 목록을 조회합니다.
+     * 페이지네이션 + 필터링된 언어팩 목록을 조회합니다 (관리자 목록 전용).
+     *
+     * 전량 순회 용도로는 쓰지 않는다 — page 를 생략하면 HTTP `page` 파라미터가 암묵
+     * 해석되어, 무관한 요청 파라미터가 순회 범위를 바꾼다({@see self::allForUpdateCheck()}).
     *
     * @param  array<string, mixed>  $filters  필터 (scope, target_identifier, locale, status, vendor)
     * @param  int  $perPage  페이지당 건수
+     * @param  int|null  $page  페이지 번호 (null 이면 요청 파라미터에서 해석)
     * @return LengthAwarePaginator 페이지네이션 결과
     */
-    public function paginate(array $filters = [], int $perPage = 20): LengthAwarePaginator;
+    public function paginate(array $filters = [], int $perPage = 20, ?int $page = null): LengthAwarePaginator;
+
+    /**
+     * 업데이트 확인용 전체 언어팩 컬렉션을 조회합니다.
+     *
+     * @return Collection<int, LanguagePack> 설치된 전체 언어팩
+     */
+    public function allForUpdateCheck(): Collection;

    /**
     * 필터링된 언어팩 컬렉션을 페이지네이션 없이 조회합니다.
@@ -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 목록의 현재(최신) 버전 번호 맵 조회
@@ -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<int, array> 목록 행 배열 컬렉션
+     */
+    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;

    /**
     * 특정 버전 조회
@@ -40,6 +40,17 @@ interface MenuRepositoryInterface
     */
    public function findById(int $id): ?Menu;

+    /**
+     * 여러 ID로 메뉴를 한 번에 조회합니다.
+     *
+     * 정적 라우트(`PUT menus/order`)에서 스코프 게이트를 재적용할 때 대상 전체를 한 번에
+     * 확인하기 위한 조회입니다. 관계는 로드하지 않습니다(소유자 판정에 불필요).
+     *
+     * @param  array<int, int>  $ids  메뉴 ID 목록
+     * @return Collection 메뉴 컬렉션
+     */
+    public function findByIds(array $ids): Collection;
+
    /**
     * 슬러그로 메뉴를 찾습니다.
     *
@@ -48,6 +59,14 @@ interface MenuRepositoryInterface
     */
    public function findBySlug(string $slug): ?Menu;

+    /**
+     * URL 로 메뉴를 찾습니다.
+     *
+     * @param  string  $url  메뉴 URL
+     * @return Menu|null 찾은 메뉴 모델 또는 null
+     */
+    public function findByUrl(string $url): ?Menu;
+
    /**
     * 새로운 메뉴를 생성합니다.
     *
@@ -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
@@ -39,10 +40,18 @@ interface NotificationLogRepositoryInterface
     */
    public function bulkDelete(array $ids): int;

+    /**
+     * 보존 기간이 지난 발송 이력을 삭제합니다.
+     *
+     * @param  int  $days  보존 기간 (일)
+     * @return int 삭제된 건수
+     */
+    public function deleteOlderThan(int $days): int;
+
    /**
     * 페이지네이션 목록 조회.
     *
     * @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;
 }
@@ -31,6 +31,14 @@ interface PermissionRepositoryInterface
     */
    public function findByIdentifier(string $identifier): ?Permission;

+    /**
+     * 여러 ID로 권한을 일괄 조회합니다.
+     *
+     * @param  array<int>  $ids  권한 ID 배열
+     * @return Collection 권한 컬렉션 (ID 기준)
+     */
+    public function getByIds(array $ids): Collection;
+
    /**
     * 새로운 권한을 생성합니다.
     *
@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Contracts\Repositories;
+
+use Carbon\Carbon;
+
+/**
+ * SEO 캐시 통계 Repository 인터페이스
+ */
+interface SeoCacheStatRepositoryInterface
+{
+    /**
+     * 캐시 통계 레코드를 기록합니다.
+     *
+     * @param  array<string, mixed>  $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<int, array{group: string|null, total: int, hits: int, misses: int, avg_response_time_ms: float|null}> 그룹별 집계 결과
+     */
+    public function aggregateGrouped(string $groupBy, ?Carbon $since = null): array;
+
+    /**
+     * 기준 시점보다 오래된 통계 레코드를 삭제합니다.
+     *
+     * @param  Carbon  $cutoff  기준 시점
+     * @return int 삭제된 레코드 수
+     */
+    public function deleteOlderThan(Carbon $cutoff): int;
+}
@@ -0,0 +1,62 @@
+<?php
+
+namespace App\Contracts\Repositories;
+
+use App\Models\SitemapUrl;
+
+/**
+ * 사이트맵 URL 저장소 인터페이스
+ *
+ * sitemap_urls 테이블에 대한 리소스 단위 증분 갱신과 스트리밍 조회를 제공합니다.
+ * 리스너는 SitemapIndexer 를 경유해 이 저장소를 사용하며(직접 Model/DB 접근 금지),
+ * 전체 재생성/증분 파일 작성은 이 저장소의 스트림을 소비합니다.
+ */
+interface SitemapUrlRepositoryInterface
+{
+    /**
+     * 한 리소스의 사이트맵 URL 행을 현재 상태로 대체합니다(멱등).
+     *
+     * (resource_type, resource_id) 로 기존 행을 제거한 뒤 전달된 항목을 삽입하므로,
+     * 같은 입력으로 여러 번 호출해도 테이블 내용이 동일합니다(loc 변경/슬러그 변경 흡수).
+     *
+     * @param  string  $type  리소스 유형
+     * @param  string  $id  리소스 PK (문자열)
+     * @param  array<int, array{loc: string, contributor: string, lastmod?: mixed, changefreq?: ?string, priority?: ?float}>  $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<int, SitemapUrl> URL 순회자
+     */
+    public function streamVisible(?string $contributor = null): iterable;
+
+    /**
+     * 공개(is_visible) URL 총 개수를 반환합니다.
+     *
+     * @return int 공개 URL 수
+     */
+    public function countVisible(): int;
+
+    /**
+     * 한 기여자의 모든 사이트맵 URL 행을 전량 대체합니다(전체 재생성).
+     *
+     * 기여자 스코프로 기존 행을 제거한 뒤 스트림을 청크 삽입하여
+     * 대용량에서도 메모리를 유계로 유지합니다.
+     *
+     * @param  string  $contributor  기여자 식별자
+     * @param  iterable<int, array{loc: string, resource_type?: string, resource_id?: mixed, lastmod?: mixed, changefreq?: ?string, priority?: ?float}>  $entries  URL 항목 스트림
+     * @return int 삽입된 행 수 (진행상황 누적 URL 표기용 — count 쿼리 없이 스트림 누적)
+     */
+    public function replaceAllForContributor(string $contributor, iterable $entries): int;
+}
@@ -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<int, int> 사용자 ID 배열
+     */
+    public function getIdsByUuids(array $uuids): array;
+
+    /**
+     * 사용자 ID 목록에 해당하는 이름을 ID 로 색인해 반환합니다.
+     *
+     * 목록 화면이 작성자 이름을 행마다 조회하면 N+1 이 되므로, 표시에 필요한
+     * 이름만 한 번에 모아 오기 위한 배치 조회입니다.
+     *
+     * @param  array  $ids  사용자 ID 배열
+     * @return array<int, string> 사용자 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;
 }
@@ -0,0 +1,93 @@
+<?php
+
+namespace App\Enums;
+
+/**
+ * 성능 계측 축 Enum
+ *
+ * `g7:bench` 커맨드가 재는 네 가지 대상을 구분합니다. 프로파일 선언의 `type` 필드
+ * 값 도메인이며, 축마다 필수 옵션과 실행기(`App\Benchmark\Axes\*`)가 다릅니다.
+ */
+enum BenchmarkAxis: string
+{
+    /**
+     * 목록 SELECT 비용 (전체 컬럼 / 목록 컬럼 / 키 컬럼 3축 비교)
+     */
+    case ListQuery = 'list';
+
+    /**
+     * 화면 1장 응답 시간 + 실행 쿼리 건수 + N+1 후보
+     */
+    case Screen = 'screen';
+
+    /**
+     * 저장 경로 1회 소요 시간 (주문 생성, 게시글 등록 등)
+     */
+    case Write = 'write';
+
+    /**
+     * 배치 커맨드 소요 시간 + 피크 메모리
+     */
+    case Batch = 'batch';
+
+    /**
+     * 사람이 읽을 수 있는 라벨
+     *
+     * @return string 축 라벨
+     */
+    public function label(): string
+    {
+        return match ($this) {
+            self::ListQuery => '목록 조회',
+            self::Screen => '화면 응답',
+            self::Write => '쓰기 작업',
+            self::Batch => '배치 작업',
+        };
+    }
+
+    /**
+     * 프로파일 선언에서 반드시 채워야 하는 옵션 키 목록
+     *
+     * 각 원소는 "대안 그룹"이며, 그룹마다 최소 하나가 선언되어야 합니다
+     * (`screen` 축은 라우트명 또는 URI 중 하나). 레지스트리가 이 목록으로 선언을
+     * 검증하며, 누락된 선언은 사유와 함께 경고로 드러내고 목록에서 제외합니다
+     * (조용히 버리면 계측 사각이 됩니다).
+     *
+     * @return array<int, array<int, string>> 필수 옵션 대안 그룹 목록
+     */
+    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<int, string> 축 값 목록
+     */
+    public static function values(): array
+    {
+        return array_column(self::cases(), 'value');
+    }
+}
@@ -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 값 배열.
     *
@@ -0,0 +1,59 @@
+<?php
+
+namespace App\Enums;
+
+/**
+ * 검색 인덱스 건강도 등급 (엔진 중립)
+ *
+ * 판정 방법은 엔진마다 다릅니다 — 각 `SearchIndexMaintainer` 구현이 자기 방식으로
+ * 판정한 뒤 이 등급 중 하나로 답합니다. 코어는 등급만 보고 재생성 대상을 고릅니다.
+ */
+enum SearchIndexStatus: string
+{
+    /** 정상 — 색인된 내용으로 검색이 성립한다 */
+    case Healthy = 'healthy';
+
+    /** 부분 — 일부만 성립. 엔진 특성일 수 있어 자동 재생성 대상이 아니다 */
+    case Degraded = 'degraded';
+
+    /** 색인 누락 — 검색이 성립하지 않는다. 재생성 대상 */
+    case Stale = 'stale';
+
+    /** 판정 불가 — 표본·연결 부재 등 (사유를 함께 기록) */
+    case Skipped = 'skipped';
+
+    /**
+     * 사용자 친화 라벨을 반환합니다.
+     *
+     * @return string lang 키 해석 결과 (locale 자동 반영)
+     */
+    public function label(): string
+    {
+        return __('search.index.status.'.$this->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<int, string>
+     */
+    public static function allValues(): array
+    {
+        return array_column(self::cases(), 'value');
+    }
+}
@@ -0,0 +1,70 @@
+<?php
+
+namespace App\Enums;
+
+/**
+ * 사이트맵 <changefreq> 값 Enum (sitemaps.org 폐쇄 어휘)
+ *
+ * https://www.sitemaps.org/protocol.html 의 <changefreq> 는 크롤러에게 페이지 갱신
+ * 빈도를 알려주는 힌트로, 허용 값이 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;
+    }
+}
@@ -0,0 +1,48 @@
+<?php
+
+namespace App\Enums;
+
+/**
+ * 사이트맵 재생성 모드 Enum
+ *
+ * SitemapManager::regenerate 와 GenerateSitemapJob, seo:generate-sitemap 커맨드가
+ * 공유하는 재생성 모드 도메인입니다.
+ *
+ * - Full: 저장소 상태와 무관하게 각 기여자를 스트리밍해 sitemap_urls 를 전량 대체한 뒤 파일 재작성.
+ * - Auto: 저장소가 비어 있으면 Full, 아니면 Incremental 로 동작(스케줄러 기본).
+ * - Incremental: 기여자 재쿼리 없이 저장소의 현재 델타만으로 파일 재작성.
+ */
+enum SitemapGenerationMode: string
+{
+    /**
+     * 전체 재생성 (관리자 수동 = 항상 Full)
+     */
+    case Full = 'full';
+
+    /**
+     * 자동 판정 (빈 저장소=Full / 채워짐=Incremental)
+     */
+    case Auto = 'auto';
+
+    /**
+     * 증분 재생성 (저장소 델타만 파일로 반영)
+     */
+    case Incremental = 'incremental';
+
+    /**
+     * 저장소 상태를 반영해 실제 실행 모드(Full 또는 Incremental)로 해석합니다.
+     *
+     * Auto 는 저장소가 비어 있으면 Full, 아니면 Incremental 로 해석됩니다.
+     *
+     * @param  int  $visibleCount  저장소의 공개 URL 수
+     * @return self 실제 실행 모드 (Full | Incremental)
+     */
+    public function resolve(int $visibleCount): self
+    {
+        return match ($this) {
+            self::Full => self::Full,
+            self::Incremental => self::Incremental,
+            self::Auto => $visibleCount === 0 ? self::Full : self::Incremental,
+        };
+    }
+}
@@ -0,0 +1,60 @@
+<?php
+
+namespace App\Enums;
+
+/**
+ * 목록 총 건수(total)와 실제 매칭 건수의 관계
+ *
+ * 대용량 목록에서 `COUNT(*)` 전량 집계는 비용이 커서 상한을 걸고 센다.
+ * 상한 이하면 센 값이 곧 실제 건수이고, 상한을 넘으면 "그 이상"이라는 사실만 알 수 있다.
+ * 화면은 이 값을 보고 "1,234건" 과 "10,000건 이상" 을 구분해 표기한다.
+ */
+enum TotalRelation: string
+{
+    /** 정확 — total 이 실제 매칭 건수와 같다 */
+    case Exact = 'exact';
+
+    /** 하한 — 실제 매칭 건수가 total 이상이다 (상한 초과로 정확히 세지 않음) */
+    case AtLeast = 'at_least';
+
+    /**
+     * 모든 값을 문자열 배열로 반환합니다.
+     *
+     * @return array<int, string>
+     */
+    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);
+    }
+}
@@ -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;
+    }
 }
@@ -0,0 +1,23 @@
+<?php
+
+namespace App\Exceptions;
+
+use Exception;
+
+/**
+ * 보호된 역할(코어/확장 소유) 수정 시도 시 발생하는 예외
+ *
+ * 삭제 경로에만 있던 코어/확장 소유 역할 보호를 수정·상태변경 경로까지 대칭
+ * 적용하기 위한 예외입니다. 비-슈퍼관리자 액터는 `admin` 등 코어/확장 소유
+ * 역할의 권한·활성상태를 변경할 수 없습니다(KVE-2026-1919).
+ */
+class CannotModifyProtectedRoleException extends Exception
+{
+    /**
+     * 보호된 역할 수정 시도 시 예외를 생성합니다.
+     */
+    public function __construct()
+    {
+        parent::__construct(__('exceptions.cannot_modify_protected_role'));
+    }
+}
@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Exceptions;
+
+use Exception;
+
+/**
+ * 비-슈퍼관리자 액터가 슈퍼 관리자 계정/역할을 수정하려 할 때 발생하는 예외
+ *
+ * 삭제 경로에만 있던 슈퍼 관리자 보호 가드를 수정·상태변경·권한부여 경로까지
+ * 대칭 적용하기 위한 등급 상한(rank ceiling) 위반 예외입니다.
+ */
+class CannotModifySuperAdminException extends Exception
+{
+    /**
+     * 슈퍼 관리자 수정 시도 시 예외를 생성합니다.
+     */
+    public function __construct()
+    {
+        parent::__construct(__('exceptions.cannot_modify_super_admin'));
+    }
+}
@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Exceptions;
+
+use Exception;
+
+/**
+ * 권한 상승(escalation) 시도 시 발생하는 예외
+ *
+ * 비-슈퍼관리자 액터가 역할에 자신이 보유하지 않은 권한, 또는 자신의 범위(scope)보다
+ * 넓은 범위의 권한을 부여하려 할 때 발생합니다(KVE-2026-1919 권한 상승 차단).
+ */
+class PermissionEscalationException extends Exception
+{
+    /**
+     * 권한 상승 시도 시 예외를 생성합니다.
+     */
+    public function __construct()
+    {
+        parent::__construct(__('exceptions.cannot_grant_unheld_permission'));
+    }
+}
@@ -0,0 +1,80 @@
+<?php
+
+namespace App\Exceptions;
+
+use Exception;
+
+/**
+ * 스케줄 실행 실패 예외
+ *
+ * 저장된 스케줄을 실행하는 시점에 차단 목록에 걸리거나(artisan/shell 화이트리스트, 내부망 URL),
+ * 실행 자체가 실패했을 때 발생합니다. `ScheduleService` 가 이 예외를 잡아 실행 이력에 기록합니다.
+ */
+class ScheduleExecutionException extends Exception
+{
+    /**
+     * 거부 사유 코드 (`ScheduleCommandValidator::ARTISAN_REASON_*`).
+     *
+     * 관리자에게 보이는 메시지는 사유와 무관하게 동일하지만, 운영 진단 로그에는
+     * 어느 규칙에 걸렸는지가 남아야 한다 — 업그레이드 점검 스텝을 두지 않기로 했으므로
+     * 실행 이력과 로그가 유일한 통로다.
+     */
+    public ?string $reasonCode = null;
+
+    /**
+     * 허용되지 않은 Artisan 명령
+     *
+     * @param  string|null  $reasonCode  거부 사유 코드 (`ScheduleCommandValidator::ARTISAN_REASON_*`)
+     * @return self 생성된 예외
+     */
+    public static function artisanNotAllowed(?string $reasonCode = null): self
+    {
+        $exception = new self(__('schedule.artisan_not_allowed'));
+        $exception->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);
+    }
+}
@@ -40,6 +40,17 @@ abstract class AbstractExtensionServiceProvider extends ServiceProvider
     */
    protected array $storageServices = [];

+    /**
+     * 카테고리별 StorageInterface 가 필요한 서비스 클래스 매핑 (클래스 ⇒ 카테고리).
+     *
+     * 등록된 클래스에는 getStorageFor($category) 인스턴스가 주입되어, 확장이
+     * getStorageDiskFor() 를 오버라이드하면 해당 서비스의 put/getDisk() 가
+     * 서비스 코드 무수정으로 카테고리 디스크를 따릅니다.
+     *
+     * @var array<class-string, string>
+     */
+    protected array $storageCategoryServices = [];
+
    /**
     * CacheInterface 가 필요한 서비스 클래스 목록.
     *
@@ -111,13 +122,17 @@ abstract class AbstractExtensionServiceProvider extends ServiceProvider
     */
    protected function registerStorageBindings(): void
    {
-        if (empty($this->storageServices)) {
-            return;
+        if (! empty($this->storageServices)) {
+            $this->app->when($this->storageServices)
+                ->needs(StorageInterface::class)
+                ->give(fn () => $this->resolveExtension()->getStorage());
        }

-        $this->app->when($this->storageServices)
-            ->needs(StorageInterface::class)
-            ->give(fn () => $this->resolveExtension()->getStorage());
+        foreach ($this->storageCategoryServices as $service => $category) {
+            $this->app->when($service)
+                ->needs(StorageInterface::class)
+                ->give(fn () => $this->resolveExtension()->getStorageFor($category));
+        }
    }

    /**
@@ -9,6 +9,7 @@ use App\Contracts\Extension\StorageInterface;
 use App\Contracts\Extension\UpgradeStepInterface;
 use App\Extension\Cache\ModuleCacheDriver;
 use App\Extension\Storage\ModuleStorageDriver;
+use App\Extension\Traits\ReportsLifecycleFailure;
 use Illuminate\Database\Seeder;
 use ReflectionClass;

@@ -21,6 +22,8 @@ use ReflectionClass;
 */
 abstract class AbstractModule implements CacheableExtensionInterface, ModuleInterface
 {
+    use ReportsLifecycleFailure;
+
    /**
     * 모듈 디렉토리 경로 (캐시)
     */
@@ -551,6 +554,37 @@ abstract class AbstractModule implements CacheableExtensionInterface, ModuleInte
        return [];
    }

+    /**
+     * 이 모듈이 등록할 HTTP 미들웨어 선언을 반환합니다.
+     *
+     * 모듈이 web/api 그룹에 미들웨어를 직접 넣는 대신, 코어의 self-gate 게이트
+     * (`ExtensionMiddlewareGate`)가 요청 시점에 라우트 이름·URI 를 각 선언의 `targets`
+     * 패턴과 대조해 매칭될 때만 해당 미들웨어를 실행합니다. 코어 IDV 정책의 라우트명
+     * 인덱스 조회 모델과 동일합니다. 미들웨어 클래스 자체는 게이트 로직을 갖지 않아도
+     * 됩니다 (순수하게 유지).
+     *
+     * 기본적으로 빈 배열 반환. 미들웨어가 필요한 모듈만 오버라이드합니다.
+     *
+     * @return array<int, array{class: class-string, groups: array<int, string>, timing?: string, targets: array<int, string>}>
+     *                                                                                                                          [
+     *                                                                                                                          [
+     *                                                                                                                          'class'   => VerifyGuestOrderToken::class,  // 미들웨어 FQCN (class_exists 검증)
+     *                                                                                                                          'groups'  => ['api'],       // 등록 그룹 배열: ['web'] | ['api'] | ['web','api']
+     *                                                                                                                          'timing'  => 'after_core',  // 'after_core'(기본, 코어 그룹 미들웨어 뒤) | 'before_core'(코어 전처리보다 먼저)
+     *                                                                                                                          'targets' => ['self'],      // 라우트명/URI 패턴 배열. 'self' = 자기 확장 prefix 자동 치환
+     *                                                                                                                          ],
+     *                                                                                                                          ]
+     *
+     * targets 카탈로그: 'self'(자기 라우트) | 'all_extensions'(모든 확장, 코어 제외) |
+     * 'core'(코어만) | 'everything'·'*'(전부) | 'module:{id}' | 'plugin:{id}' |
+     * 원시 라우트명 glob·brace(`api.modules.x.*`, `{a,b}`) | '/' 로 시작하는 URI 패턴(무명 라우트용).
+     * targets 누락/빈배열 시 등록 거부. 상세: docs/backend/middleware.md "확장 미들웨어 선언".
+     */
+    public function getMiddleware(): array
+    {
+        return [];
+    }
+
    /**
     * Declarative i18n getter family — 모듈이 선언하는 다국어/SSoT 데이터 4종.
     *
@@ -718,6 +752,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<string, array<string, mixed>> 프로파일 키 → 정의
+     *                                             [
+     *                                             '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 [];
+    }
+
    /**
     * 모듈 설치 시 실행할 시더 클래스 목록 반환
     *
@@ -864,6 +930,31 @@ abstract class AbstractModule implements CacheableExtensionInterface, ModuleInte
        return [];
    }

+    /**
+     * 신뢰하는 외부 스크립트 호스트 목록을 반환합니다.
+     *
+     * module.json 의 `trusted_script_hosts` 배열에서 읽습니다. 이 모듈이 레이아웃
+     * `scripts[].src` 로 로드하는 외부 CDN 호스트를 선언합니다. 코어는 이 목록을
+     * 집계(AbstractModule/AbstractPlugin → TrustedScriptHosts)해 런타임 스크립트 로더·
+     * 저장측 검증·정적 검사가 same-origin 이 아닌 스크립트 중 **선언된 호스트만** 허용하도록
+     * 합니다 (KVE-2026-1915 신뢰 출처 허용목록).
+     *
+     * @return array<int, string> 신뢰 호스트명 목록 (예: ['cdn.example.com'])
+     */
+    public function getTrustedScriptHosts(): array
+    {
+        $hosts = $this->loadManifest()['trusted_script_hosts'] ?? [];
+
+        if (! is_array($hosts)) {
+            return [];
+        }
+
+        return array_values(array_filter(
+            array_map(fn ($host) => is_string($host) ? trim($host) : '', $hosts),
+            fn ($host) => $host !== ''
+        ));
+    }
+
    /**
     * 레이아웃 확장 파일 경로 반환
     *
@@ -1022,11 +1113,11 @@ abstract class AbstractModule implements CacheableExtensionInterface, ModuleInte
     *
     * @param  string  $pageType  레이아웃 meta.seo.page_type
     * @return array<string, array{expr: string, label: string|array<string, string>}>
-     *               키별 데이터 경로 메타 — 예:
-     *               [
-     *               'image' => ['expr' => '{{product.data.thumbnail_url}}', 'label' => 'vendor-module::seo.auto_value.product_image'],
-     *               'image_alt' => ['expr' => '{{product.data.name}}', 'label' => 'vendor-module::seo.auto_value.product_name'],
-     *               ]
+     *                                                                                 키별 데이터 경로 메타 — 예:
+     *                                                                                 [
+     *                                                                                 'image' => ['expr' => '{{product.data.thumbnail_url}}', 'label' => 'vendor-module::seo.auto_value.product_image'],
+     *                                                                                 'image_alt' => ['expr' => '{{product.data.name}}', 'label' => 'vendor-module::seo.auto_value.product_name'],
+     *                                                                                 ]
     */
    public function seoOgDefaultMeta(string $pageType): array
    {
@@ -1038,7 +1129,7 @@ abstract class AbstractModule implements CacheableExtensionInterface, ModuleInte
     *
     * @param  string  $pageType  페이지 타입
     * @return array<string, array{expr: string, label: string|array<string, string>}> 키별 데이터 경로 메타
-     *               (label = 번역 키 권장 — seoOgDefaultMeta 참조)
+     *                                                                                 (label = 번역 키 권장 — seoOgDefaultMeta 참조)
     */
    public function seoTwitterDefaultMeta(string $pageType): array
    {
@@ -1054,11 +1145,11 @@ abstract class AbstractModule implements CacheableExtensionInterface, ModuleInte
     *
     * @param  string  $pageType  페이지 타입
     * @return array<string, array{expr: string, label: string|array<string, string>}>
-     *               점 경로 키별 데이터 경로 메타 (label = 번역 키 권장 — seoOgDefaultMeta 참조) — 예:
-     *               [
-     *               'name' => ['expr' => '{{product.data.name}}', 'label' => 'vendor-module::seo.auto_value.product_name'],
-     *               'offers.price' => ['expr' => '{{product.data.selling_price}}', 'label' => 'vendor-module::seo.auto_value.product_price'],
-     *               ]
+     *                                                                                 점 경로 키별 데이터 경로 메타 (label = 번역 키 권장 — seoOgDefaultMeta 참조) — 예:
+     *                                                                                 [
+     *                                                                                 'name' => ['expr' => '{{product.data.name}}', 'label' => 'vendor-module::seo.auto_value.product_name'],
+     *                                                                                 'offers.price' => ['expr' => '{{product.data.selling_price}}', 'label' => 'vendor-module::seo.auto_value.product_price'],
+     *                                                                                 ]
     */
    public function seoStructuredDataMeta(string $pageType): array
    {
@@ -1190,6 +1281,29 @@ abstract class AbstractModule implements CacheableExtensionInterface, ModuleInte
        return $result;
    }

+    /**
+     * 빌드된 에셋의 절대 파일 경로를 반환합니다.
+     *
+     * `getBuiltAssetPaths()` 는 module.json 의 상대 output 경로를 돌려주므로
+     * 파일을 실제로 읽으려면 모듈 루트(`getModulePath()`: 활성 dir 또는 `_bundled`
+     * 실제 위치)를 앞에 붙여야 한다. 서버측 번들 병합(ExtensionBundleService)이
+     * `getAssetFilePath()` 의 `base_path("modules/{id}/...")` 하드코딩을 복제하지
+     * 않고 `_bundled` 확장에서도 정확한 경로를 얻도록 이 게터를 SSoT 로 쓴다.
+     *
+     * @return array 빌드된 에셋 절대 경로 배열 ['js' => '...', 'css' => '...']
+     */
+    public function getBuiltAssetAbsolutePaths(): array
+    {
+        $relative = $this->getBuiltAssetPaths();
+        $result = [];
+
+        foreach ($relative as $kind => $output) {
+            $result[$kind] = $this->getModulePath().'/'.$output;
+        }
+
+        return $result;
+    }
+
    /**
     * 모듈 스토리지 드라이버 인스턴스 반환
     *
@@ -1223,6 +1337,75 @@ abstract class AbstractModule implements CacheableExtensionInterface, ModuleInte
        return 'modules';
    }

+    /**
+     * 카테고리별 스토리지 인스턴스 캐시 (디스크명 키 memoize)
+     *
+     * @var array<string, StorageInterface>
+     */
+    private array $storageByDisk = [];
+
+    /**
+     * 카테고리별 스토리지 디스크 이름 반환
+     *
+     * 기본값은 getStorageDisk() 와 동일 (현행 동작 100% 보존).
+     * 특정 카테고리(예: 'images')만 다른 디스크를 쓰려면 모듈이 오버라이드합니다.
+     *
+     * 주의: 오버라이드 구현은 'settings' 카테고리에서 모듈 설정을 조회하면 안 됩니다 —
+     * 모듈 설정 로드가 getStorage()->get('settings', ...) 를 경유하므로 재귀 고리가 생깁니다.
+     * 모듈 설정 조회는 'images' 등 설정 저장과 무관한 카테고리에서만 수행합니다.
+     *
+     * @param  string  $category  카테고리 (settings, attachments, images, cache, temp)
+     * @return string 디스크 이름
+     */
+    public function getStorageDiskFor(string $category): string
+    {
+        return $this->getStorageDisk();
+    }
+
+    /**
+     * 카테고리별 스토리지 드라이버 인스턴스 반환
+     *
+     * getStorageDiskFor() 가 결정한 디스크의 드라이버를 디스크 단위로 memoize 하여 반환합니다.
+     * 기본 디스크와 동일하면 getStorage() 인스턴스를 그대로 재사용합니다.
+     *
+     * @param  string  $category  카테고리
+     * @return StorageInterface 스토리지 드라이버 인스턴스
+     */
+    public function getStorageFor(string $category): StorageInterface
+    {
+        $disk = $this->getStorageDiskFor($category);
+
+        if (! isset($this->storageByDisk[$disk])) {
+            $base = $this->getStorage();
+            $this->storageByDisk[$disk] = ($disk === $base->getDisk()) ? $base : $base->withDisk($disk);
+        }
+
+        return $this->storageByDisk[$disk];
+    }
+
+    /**
+     * 공개 자산 디스크 설정값을 해석합니다.
+     *
+     * 우선순위: 확장 개별 설정(override) > 코어 전역 설정(core.storage.public_asset_disk).
+     * 미설정('')/'none'/config 에 존재하지 않는 디스크(고아 플러그인 디스크)는 null 로
+     * 해석되어 호출측이 기존 디스크(스트리밍)로 폴백합니다.
+     *
+     * @param  string|null  $override  확장 개별 설정값 (''/null 이면 코어 전역 설정 사용)
+     * @return string|null 사용할 디스크 이름 (스트리밍 유지면 null)
+     */
+    protected function resolvePublicAssetDisk(?string $override = null): ?string
+    {
+        $disk = ($override !== null && $override !== '')
+            ? $override
+            : (string) config('core.storage.public_asset_disk', '');
+
+        if ($disk === '' || $disk === 'none' || config("filesystems.disks.{$disk}") === null) {
+            return null;
+        }
+
+        return $disk;
+    }
+
    /**
     * 모듈 캐시 드라이버 인스턴스 반환
     *
--- a/Show More
+++ b/Show More