Merge branch 'develop'

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 로 잡는다

.env.example

@@ -3,7 +3,7 @@ APP_ENV=production
 APP_KEY=
 APP_DEBUG=false
 APP_URL=http://localhost
-APP_VERSION=7.0.0-beta.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}"
 
@@ -103,3 +112,8 @@ VITE_APP_NAME="${APP_NAME}"
 G7_UPDATE_GITHUB_URL=https://github.com/gnuboard/g7
 G7_UPDATE_GITHUB_TOKEN=
 G7_UPDATE_PENDING_PATH=
+
+# spawn 자식 프로세스 실패 시 동작 모드 (기본: abort)
+#   - abort    : 즉시 abort + 운영자에게 수동 명령 안내 (안전 우선, stale 메모리 fatal 차단)
+#   - fallback : in-process fallback 진행 (proc_open 미지원 공유 호스팅 호환, stale 메모리 위험 잔존)
+# G7_UPDATE_SPAWN_FAILURE_MODE=abort

.env.testing.example

@@ -3,7 +3,7 @@ APP_ENV=testing
 APP_KEY=
 APP_DEBUG=false
 APP_URL=http://localhost
-APP_VERSION=7.0.0-alpha.18
+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}"
 

.github/ISSUE_TEMPLATE/bug_report.md

@@ -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/ 관련 로그
+- 화면 스크린샷
+-->
+
+## 추가 정보
+
+<!-- 원인 추정, 임시 우회 방법 등 참고될 내용이 있으면 적어 주세요. -->

.github/ISSUE_TEMPLATE/config.yml

@@ -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 로 신고해 주세요.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,26 @@
+---
+name: ✨ 기능 제안
+about: 새로운 기능이나 개선 아이디어를 제안합니다.
+title: "[Feature] "
+labels: enhancement
+assignees: ''
+---
+
+## 해결하려는 문제
+
+<!-- 어떤 불편이나 한계 때문에 이 기능이 필요한지 적어 주세요. -->
+
+## 제안하는 기능
+
+<!-- 원하는 동작을 구체적으로 적어 주세요. -->
+
+## 적용 범위 (해당 시)
+
+- [ ] 코어
+- [ ] 모듈 <!-- 어떤 모듈인지: -->
+- [ ] 플러그인 <!-- 어떤 플러그인인지: -->
+- [ ] 템플릿 <!-- 어떤 템플릿인지: -->
+
+## 대안·참고 사항
+
+<!-- 고려한 다른 방법, 타 CMS 사례, 참고 링크 등이 있으면 적어 주세요. -->

.github/ISSUE_TEMPLATE/upgrade_issue.md

@@ -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/ 의 관련 로그
+- 브라우저 콘솔 에러
+-->

.gitignore

@@ -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/*
@@ -75,9 +80,26 @@ templates/_bundled/*/node_modules/
 !plugins/_pending/
 !templates/_pending/
 
+# ===== 언어팩 시스템 =====
+
+# 활성 언어팩 디렉토리 (설치된 복사본 — Git 제외)
+lang-packs/*/
+!lang-packs/_bundled/
+
+# _pending 디렉토리 (외부 다운로드 임시 영역)
+lang-packs/_bundled/_pending/
+!lang-packs/_pending/
+
 # DevTools debug dump
 storage/debug-dump/
 
+# MaxMind GeoLite2 DB (재배포 금지 — 각 환경에서 직접 다운로드)
+storage/app/geoip/
+
+# 인스톨러 런타임 산출물 — 각 환경에서 자동 생성/소비
+storage/installer-state.json
+storage/installer/
+
 # 개발 전용 파일
 .api-test/
 .serena/
@@ -87,6 +109,7 @@ boost.json
 cypress/
 cypress.config.js
 .env.testing
+.claude/settings.local.json
 
 # ===== 보안: 민감 파일 방어 패턴 =====
 *.pem
@@ -103,3 +126,22 @@ id_ed25519
 *.sql
 *.sqlite
 *.db
+
+# NHN KCP 결제플러그인 PG 공개키는 예외 처리
+!plugins/_bundled/*/bin/pub.key
+
+.claude/tmp/
+
+# ===== Playwright E2E =====
+tests/Playwright/.auth/
+playwright-report/
+test-results/
+# Playwright MCP 세션 아티팩트(스냅샷/콘솔 로그) — 커밋 대상 아님
+.playwright-mcp/
+
+# ===== 소스맵 =====
+# 소스맵은 원본 코드 전문(sourcesContent)을 담고 있어 배포 대상이 아니다.
+# 로컬 개발 빌드에서는 생성되지만(디버깅용) 저장소에는 유입되지 않는다.
+# 배포용 빌드는 `--production` 이 G7_BUILD_SOURCEMAP=0 을 주입해 생성 자체를 막는다.
+# 경로 한정 시 새 확장이 추가될 때 조용히 누락되므로 전역 규칙으로 둔다.
+*.map

AGENTS.md

@@ -6,31 +6,46 @@
 
 <!-- AUTO-GENERATED-START: docs-quick-reference -->
 
-### 백엔드 [backend/](docs/backend/) (19개)
+### 백엔드 [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... |
-| [api-resources.md](docs/backend/api-resources.md) | API 리소스 | BaseApiResource 상속 필수 |
+| [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... |
 | [core-config.md](docs/backend/core-config.md) | 코어 설정 (config/core.php) | config/core.php = 코어 권한/역할/메뉴/메일템플릿의 SSoT (Single Source ... |
 | [core-update-system.md](docs/backend/core-update-system.md) | 코어 업데이트 시스템 (Core Update System) | 코어 업그레이드 스텝: upgrades/ 디렉토리 (프로젝트 루트), 네임스페이스 App\Upgrades |
+| [data-sync-helpers.md](docs/backend/data-sync-helpers.md) | 데이터 동기화 Helper (Data Sync Helpers) | 모든 데이터 동기화는 Service/Seeder 가 Helper 를 호출해 수행 (직접 Model 조작... |
+| [dto.md](docs/backend/dto.md) | DTO (Data Transfer Object) 사용 규칙 | DTO 두 패턴 — Value Object(불변 1회 전달) vs Data Carrier(다단계 변형/... |
 | [enum.md](docs/backend/enum.md) | Enum 사용 규칙 | 상태/타입/분류 = Enum 필수 (PHP 8.1+ Backed Enum) |
 | [exceptions.md](docs/backend/exceptions.md) | Custom Exception 다국어 처리 | 예외 메시지 하드코딩 금지 → __() 함수 필수 |
+| [geoip.md](docs/backend/geoip.md) | GeoIP 시스템 (MaxMind GeoLite2) | MaxMind GeoLite2-City DB 기반 IP → 타임존 감지 (SetTimezone 미들웨어... |
+| [identity-messages.md](docs/backend/identity-messages.md) | 본인인증 메시지 템플릿 시스템 (Identity Messages) | 알림 시스템(notification_*)과 완전 분리된 IDV 전용 템플릿 인프라 |
+| [identity-policies.md](docs/backend/identity-policies.md) | 본인인증 정책 시스템 (Identity Policies) | - |
+| [identity-providers.md](docs/backend/identity-providers.md) | IDV Provider 작성 가이드 (Identity Verification Providers) | VerificationProviderInterface 구현 + IdentityProviderManage... |
+| [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) | 모든 알림은 BaseNotification 상속 필수 (via() 보일러플레이트 제거) |
+| [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 + ... |
 | [seo-system.md](docs/backend/seo-system.md) | SEO 페이지 생성기 시스템 (SEO Page Generator) | SeoMiddleware: 봇 요청 감지 → ?locale= 파라미터 해석 → SeoRenderer가 ... |
 | [service-provider.md](docs/backend/service-provider.md) | 서비스 프로바이더 안전성 | DB 접근 전 .env 파일 존재 확인 필수 |
 | [service-repository.md](docs/backend/service-repository.md) | Service-Repository 패턴 | RepositoryInterface 주입 필수 (구체 클래스 직접 주입 금지) |
+| [settings-multilingual-enrichment.md](docs/backend/settings-multilingual-enrichment.md) | Settings 카탈로그 다국어 자동 보강 | settings JSON 의 다국어 카탈로그 라벨(_cached_name 등)은 카탈로그 빌드 시점에 보강 |
+| [translatable-seeders.md](docs/backend/translatable-seeders.md) | 다국어 시더 인터페이스 (Translatable Seeders) | 다국어 JSON 컬럼(name 등)을 시드하는 확장 entity 시더는 TranslatableSeede... |
+| [user-overrides.md](docs/backend/user-overrides.md) | 사용자 수정 보존 (HasUserOverrides Trait) | 모델에 `use HasUserOverrides;` + `protected array $trackable... |
 | [validation.md](docs/backend/validation.md) | 검증 (Validation) | 필수: FormRequest에서 검증 (Service에 검증 로직 배치 금지) |
 
-### 프론트엔드 [frontend/](docs/frontend/) (48개)
+### 프론트엔드 [frontend/](docs/frontend/) (50개)
 
 | 문서 | 설명 | TL;DR 핵심 |
 |------|------|-----------|
@@ -56,6 +71,8 @@
 | [g7core-api-advanced.md](docs/frontend/g7core-api-advanced.md) | G7Core 전역 API 레퍼런스 - 고급 | - |
 | [g7core-api.md](docs/frontend/g7core-api.md) | G7Core 전역 API 레퍼런스 | G7Core.state: get/set/subscribe 전역 상태 관리 |
 | [g7core-helpers.md](docs/frontend/g7core-helpers.md) | G7Core 헬퍼 API | - |
+| [identity-guard-interceptor.md](docs/frontend/identity-guard-interceptor.md) | IdentityGuardInterceptor — 코어 본인인증 인터셉터 레퍼런스 | ActionDispatcher.handleApiCall 응답 후처리에서 isIdentityRequire... |
+| [identity-verification-ui.md](docs/frontend/identity-verification-ui.md) | 본인인증(IDV) 공통 UI 가이드 | 모든 IDV 강제 지점은 동일한 428 응답 형식을 공유 (코어 9 + 게시판 4 + 이커머스 4 + N) |
 | [layout-json-components-loading.md](docs/frontend/layout-json-components-loading.md) | 레이아웃 JSON - 데이터 로딩 및 생명주기 | - |
 | [layout-json-components-rendering.md](docs/frontend/layout-json-components-rendering.md) | 레이아웃 JSON - 조건부/반복 렌더링 | - |
 | [layout-json-components-slots.md](docs/frontend/layout-json-components-slots.md) | 레이아웃 JSON - 슬롯 시스템 | - |
@@ -83,32 +100,40 @@
 | [handlers.md](docs/frontend/templates/sirsoft-basic/handlers.md) | sirsoft-basic 핸들러 | setTheme/initTheme: 다크/라이트 모드 전환 (admin과 동일 키 공유) |
 | [layouts.md](docs/frontend/templates/sirsoft-basic/layouts.md) | sirsoft-basic 레이아웃 | 베이스: _user_base.json (헤더 + 푸터 + 모바일 네비 + 콘텐츠 슬롯) |
 
-### 확장 시스템 [extension/](docs/extension/) (22개)
+### 확장 시스템 [extension/](docs/extension/) (30개)
 
 | 문서 | 설명 | TL;DR 핵심 |
 |------|------|-----------|
+| [cache-driver.md](docs/extension/cache-driver.md) | 캐시 드라이버 시스템 (CacheInterface) | 모든 캐시 저장은 CacheInterface 사용 (Cache:: 직접 호출 금지) |
 | [changelog-rules.md](docs/extension/changelog-rules.md) | Changelog 규칙 (Changelog Rules) | 확장/코어 버전 업 시 CHANGELOG.md에 변경사항 기록 필수 (미기록 시 버전 업 불가) |
+| [editor-spec.md](docs/extension/editor-spec.md) | 편집기 스펙 (editor-spec.json) | editor-spec.json = 편집기 팔레트/스타일 컨트롤/중첩 규칙/샘플 데이터/레시피의 선언 (... |
 | [extension-manager.md](docs/extension/extension-manager.md) | ExtensionManager (확장 관리자) | composer.json 수정 없음 - 런타임 오토로드 방식 사용 |
 | [extension-update-system.md](docs/extension/extension-update-system.md) | 확장 업데이트 시스템 (Extension Update System) | 업데이트 감지 우선순위: GitHub > _bundled (2단계, _pending 미참여) |
 | [hooks.md](docs/extension/hooks.md) | 훅 시스템 (Hook System) | Action 훅: doAction() - 부가 작업 (로그, 알림, 캐시) |
+| [language-packs.md](docs/extension/language-packs.md) | 언어팩 시스템 (Language Packs) | 코어/번들 확장의 lang/{ko,en}/ 는 가상 보호 행으로 자동 노출 (DB 없이 항상 activ... |
 | [layout-extensions.md](docs/extension/layout-extensions.md) | 레이아웃 확장 시스템 (Layout Extensions) | - |
 | [menus.md](docs/extension/menus.md) | 메뉴 시스템 | 구조: User → Role → role_menus 피벗 → Menu |
 | [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) |
+| [sample-extensions.md](docs/extension/sample-extensions.md) | 학습용 샘플 확장 (Sample Extensions) | 샘플 확장 4종: gnuboard7-hello_module / _plugin / _admin_templ... |
 | [storage-driver.md](docs/extension/storage-driver.md) | 스토리지 드라이버 시스템 (StorageInterface) | 모든 파일 저장은 StorageInterface 사용 (Storage::disk() 직접 호출 금지) |
 | [template-basics.md](docs/extension/template-basics.md) | 템플릿 시스템 기초 | 타입: Admin (관리자용), User (일반사용자용) |
 | [template-caching.md](docs/extension/template-caching.md) | 템플릿 캐싱 전략 | - |
 | [template-commands.md](docs/extension/template-commands.md) | 템플릿 Artisan 커맨드 | 목록: php artisan template:list |
+| [template-idv-bootstrap.md](docs/extension/template-idv-bootstrap.md) | 템플릿 IDV launcher 등록 가이드 | 템플릿 부트스트랩(initTemplate)에서 window.G7Core.identity.setLaunc... |
 | [template-routing.md](docs/extension/template-routing.md) | 템플릿 라우트/언어 파일 규칙 | - |
 | [template-security.md](docs/extension/template-security.md) | 템플릿 보안 정책 | - |
 | [template-workflow.md](docs/extension/template-workflow.md) | 템플릿 개발 워크플로우 | 필수 파일: template.json, routes.json, _base.json, errors/{40... |
+| [upgrade-step-guide.md](docs/extension/upgrade-step-guide.md) | 업그레이드 스텝 작성 가이드 (Upgrade Step Guide) | upgrade step 이 실행되는 환경은 경로에 따라 다르다 — 섹션 9 "업그레이드 경로" 먼저 읽기 |
+| [vendor-bundle.md](docs/extension/vendor-bundle.md) | Vendor 번들 시스템 (Vendor Bundle System) | - |
 
 ### 공통 (5개)
 
@@ -118,7 +143,38 @@
 | [database-guide.md](docs/database-guide.md) | 그누보드7 데이터베이스 개발 가이드 | 마이그레이션: 한국어 comment 필수, down() 구현 필수 |
 | [requirements.md](docs/requirements.md) | 그누보드7 시스템 요구사항 (System Requirements) | PHP 8.2+ 필수 |
 | [testing-guide.md](docs/testing-guide.md) | 그누보드7 테스트 가이드 | 테스트 통과 = 작업 완료 (작성만으로 불충분!) |
-| [auto-document.md](.claude/docs/auto-document.md) | 자동 문서화 (auto-document) | - |
+| [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 -->
@@ -133,6 +189,31 @@
 
 ---
 
+## 버전 동기화 의무
+
+코어 또는 번들 확장의 공개 표면을 수정할 때, 그 변경의 영향 범위에 있는 다른 확장의 버전 제약(`g7_version`, `dependencies.{modules|plugins}`)을 함께 갱신한다.
+
+### ① 코어 → 확장 동기화 (`requires.g7_version`)
+
+- 트리거: 코어 공개 확장 표면(`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}`)
+
+- 트리거: 번들 모듈/플러그인의 공개 Service/Contract/Repository/Model/Route, 발행 훅·이벤트, CHANGELOG 수정
+- 조치: 그 확장에 의존하는 다른 번들 확장 전수 스캔 → 최소 버전 제약 상향 여부 판정
+
+### 판정 순서
+
+1. 기존 소비자 API 시그니처/동작을 건드렸는가 → 소비 확장 최소 버전 상향
+2. 새 공개 API 가 도입되었는가 → 후보 확장 전수 스캔 후 검토
+3. 의존 관계 B 의 공개 API 가 변경되었는가 → A 의 `dependencies.B` 상향
+4. 동기화 대상이 없다면 그 근거("순수 내부 리팩토링" 등)를 변경 이력에 기록
+
+> 상세: [changelog-rules.md](docs/extension/changelog-rules.md) "코어 버전 제약 정책"
+
+---
+
 ## CRITICAL RULES - 절대 금지 패턴 (DO NOT)
 
 ### API/핸들러 호출
@@ -145,6 +226,13 @@
 | `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` 사용 |
+| `handler: "showToast"` | `handler: "toast"` |
+| 모달 안에서 부모 `_local.*` 참조 | 데이터소스 응답 필드 또는 `_global` 사용 (모달은 별도 컨텍스트) |
 
 ### 데이터 바인딩
 
@@ -169,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` 의 치환용으로는 쓰지 않는다.
 
 ### 상태 관리
 
@@ -198,6 +302,315 @@
 | 모든 API에 개별 headers 설정 | globalHeaders로 공통 헤더 정의 |
 | pattern 없이 헤더 정의 | pattern 필수 (`*`, `/api/shop/*` 등) |
 
+### 인증/리다이렉트 규칙 (engine-v1.47.0+)
+
+| 금지 | 올바른 사용 |
+|------|------------|
+| 모듈/플러그인에서 `AuthManager.updateConfig()` 호출 | 템플릿 부트스트랩(`initTemplate`)에서만 호출 |
+| `AuthManager.updateConfig({ loginPath: 'https://...' })` (외부 origin) | `loginPath` 는 `/` 로 시작하는 동일 origin path-only |
+| `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 데이터 접근
+
+| 금지 | 올바른 사용 |
+|------|------------|
+| Listener 에서 `Model::query/find/where/create` 직접 호출 | Repository 인터페이스 주입 후 위임 |
+| Listener 에서 `DB::table()->update(...)` | Repository 의 도메인 의도 메서드 (recalculate*/anonymize* 등) |
+| Listener 에서 `$row->save()` / `saveQuietly()` / `delete()` | Repository 의 update/save/delete 호출 |
+| 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)
+
 ---
 
 ## 템플릿 엔진 내부 버전 (engine-v1.x.x)
@@ -287,6 +700,58 @@ Keep a Changelog 표준:
 
 ---
 
+## 공개 CHANGELOG 작성 규칙
+
+코어(`CHANGELOG.md`) 및 확장(`modules/*/CHANGELOG.md`, `plugins/*/CHANGELOG.md`, `templates/*/CHANGELOG.md`)의 릴리즈 CHANGELOG 작성 규칙입니다.
+
+### 톤과 표현
+
+- 사용자/개발자가 읽는 문서이므로 **사용자 관점**으로 작성
+- "~할 수 있도록 개선", "~하도록 변경", "~문제 수정" 톤 사용
+- 각 불릿은 **1~2줄**로 간결하게
+- 내부 구현 상세(클래스명, 파일 경로, 테스트 건수, 훅 체인, DI 패턴)는 포함하지 않음
+- 이슈 번호(`#123`)는 포함하지 않음
+
+### 포함/제외 대상
+
+| 포함 | 제외 |
+|------|------|
+| 사용자에게 보이는 기능 추가/변경 | 내부 파일 경로, 클래스/메서드명 |
+| API 변경 (엔드포인트, 파라미터) | 테스트 건수/파일명 |
+| 기존 기능의 버그 수정 | 리팩토링 세부사항 |
+| 성능 개선 (체감 가능한 것) | 내부 규정/문서 변경 |
+| Breaking Change | 내부 작업 이슈 번호 단독 (예: `refs #347`) |
+| 엔진 버전 참조 (engine-v1.X.Y) | 코드 패턴 설명 |
+| **공개 제보자 attribution** (`(#N @login 님께서 제보해주셨습니다.)`) | — |
+| **KISA 등 공식 보안 채널** (`(KISA 측에서 제보해주셨습니다 — KVE-XXXX-XXXXX)`) | — |
+
+### 공개 제보자 attribution
+
+공개 저장소(GitHub) 이슈로 제보·건의된 항목이 출시 CHANGELOG 에 반영되면, 항목 끝에 공개 이슈 번호와 제보자 GitHub 핸들 멘션을 부착합니다.
+
+- 형식: `- (본문) (#N @login 님께서 제보해주셨습니다.)` 또는 `... 건의해주셨습니다.`
+- 톤: 버그 리포트는 "제보", 제안형 개선 요청은 "건의"
+- 다중 매칭: `(#A @x, #B @y 님께서 제보해주셨습니다.)` / 혼재: `(#A @x 님께서 제보해주시고, #B @y 님께서 건의해주셨습니다.)`
+- KISA 등 공식 보안 채널: GitHub 멘션 없이 텍스트 "KISA 측에서" + 공개 가능한 식별자만
+
+### 신규 기능의 버그 수정 제외 규칙
+
+해당 릴리즈에서 **새로 도입한 기능**의 개발 중 버그 수정은 Fixed에 기록하지 않습니다. 사용자 관점에서 그 기능은 해당 릴리즈에서 처음 제공되므로, "추가했다가 고쳤다"는 내부 개발 이력일 뿐입니다.
+
+**판단 기준**: 해당 버그가 **이전 릴리즈에도 존재했던 기능**에서 발생한 것인지 확인
+
+### 기능 그룹핑
+
+Added/Changed/Fixed 내 항목이 10개를 초과하면 `####` 서브 헤딩으로 기능 단위 분류합니다.
+
+### Keep a Changelog 형식
+
+- `## [버전] - YYYY-MM-DD` 헤더 필수
+- `### Added` / `### Changed` / `### Fixed` / `### Removed` 카테고리 사용
+- 최신 버전이 파일 상단
+
+---
+
 ## 레이아웃 JSON 구현 규칙
 
 ```
@@ -323,12 +788,19 @@ Keep a Changelog 표준:
 
 ```text
 기능 구현 = 테스트 코드 작성 필수
+신규 기능 / 도메인 표면 변경 = 시나리오 매니페스트(tests/scenarios/<feature>.yaml) 작성 의무 — 입력 axis cross product + 후속 효과 체인 전수 커버
 테스트 통과 = 작업 완료 (작성만으로 불충분!)
 기존 테스트 있음 → 변경사항 반영하여 수정 후 실행
 기능 구현 시 관련된 모든 계층(백엔드+프론트엔드+레이아웃 렌더링) 테스트 필수
 주의: 모듈/플러그인 프론트엔드 테스트는 독립 vitest.config.ts 사용 (루트 config 포함 금지)
+필수: 도메인 매트릭스 = 테스트 위치/형식 가이드. 입력 조합 망라 의무는 시나리오 매니페스트가 SSoT
+필수: 버그 수정은 먼저 실패하는 회귀 테스트 → fail 확인 → 수정 → green 4단계
+필수: 테스트 중 발견한 무관 에러도 같은 세션에서 처리 (stale test 또는 로직 수정)
+필수: 릴리스 전 composer test-smoke 통과
 ```
 
+> 상세: [docs/testing-guide.md](docs/testing-guide.md) — 기능 단위 시나리오 매트릭스, 도메인 매트릭스, Pre-release Smoke Suite, 회귀 테스트 4단계, 무관 에러 처리
+
 ### 그누보드7 레이아웃 렌더링 테스트
 
 ```text
@@ -434,6 +906,20 @@ powershell -Command "npm run test:run"
 
 ---
 
+## npm install 규칙
+
+기본 `npm install`은 `package-lock.json`을 자동 수정할 수 있으므로, lock 파일 변경 의도가 없는 의존성 복구나 작업 환경 재구성에는 `npm install --package-lock=false`를 사용합니다.
+
+| 상황 | 권장 명령어 | 비고 |
+| ---- | ----------- | ---- |
+| 누락 의존성 복구 / 작업 환경 재구성 | `npm install --package-lock=false` | lock 파일 변경 없이 설치 |
+| clean install | `npm ci` | `package.json`과 `package-lock.json`이 동기화된 경우 |
+| 의존성 신규 추가/업데이트 | `npm install <pkg>` | lock 변경이 작업 범위에 포함된 경우만 |
+
+lock 파일 변경 의도가 없는 상황에서 `npm install` 단독 실행을 피합니다. `module.json`, `plugin.json`, `template.json`의 `version`을 바꾸면 해당 확장의 `package.json`, `package-lock.json`, `composer.json` 버전도 함께 동기화합니다. 의존성 재설치 없이 lock 파일의 version 필드만 갱신할 때는 `npm install --package-lock-only`를 사용합니다.
+
+---
+
 ## 핵심 원칙
 
 ### 1. 동적 로딩
@@ -518,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/) 각 문서 참조
 
 ### 컨트롤러 계층
@@ -564,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 커맨드로 수행
 ```
@@ -620,14 +1117,57 @@ 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 번들로 빌드한다:
+
+| 번들 | 로드 시점 | vite config |
+|------|----------|-------------|
+| `template-engine.min.js` | 모든 페이지 (동기 `<script>`) | `vite.config.core.js` |
+| `layout-editor.min.js` | `/admin/layout-editor/*` 진입 시 런타임 주입 | `vite.config.editor.js` |
+| `devtools.min.js` | 디버그 모드에서만 런타임 주입 | `vite.config.devtools.js` |
+
+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
@@ -656,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` 모드는 실시간 개발용으로 활성 디렉토리를 자동 사용.
 
 ---
@@ -666,6 +1208,7 @@ php artisan plugin:build sirsoft-payment --active       # 활성 디렉토리에
 # 코어 업데이트
 php artisan core:check-updates                                    # 코어 업데이트 확인
 php artisan core:update [--force] [--no-backup] [--no-maintenance] # 코어 업데이트 실행
+php artisan core:execute-upgrade-steps --from=X.Y.Z --to=A.B.C [--force]  # 업그레이드 스텝 단독 실행 (HANDOFF 안내/수동 복구용 — 사전·사후 단계 자동 수행)
 
 # 모듈
 php artisan module:list
@@ -677,7 +1220,7 @@ php artisan module:composer-install [identifier?] [--all]
 php artisan module:cache-clear [identifier?]
 php artisan module:seed [identifier] [--sample] [--count=key=value]
 php artisan module:check-updates [identifier?]
-php artisan module:update [identifier] [--force]
+php artisan module:update [identifier] [--force] [--source=auto|bundled|github]
 
 # 플러그인
 php artisan plugin:list
@@ -689,7 +1232,7 @@ php artisan plugin:composer-install [identifier?] [--all]
 php artisan plugin:cache-clear [identifier?]
 php artisan plugin:seed [identifier] [--sample] [--count=key=value]
 php artisan plugin:check-updates [identifier?]
-php artisan plugin:update [identifier] [--force]
+php artisan plugin:update [identifier] [--force] [--source=auto|bundled|github]
 
 # 템플릿
 php artisan template:list
@@ -699,7 +1242,7 @@ php artisan template:deactivate [identifier]
 php artisan template:uninstall [identifier]
 php artisan template:cache-clear
 php artisan template:check-updates [identifier?]
-php artisan template:update [identifier] [--layout-strategy=overwrite] [--force]
+php artisan template:update [identifier] [--layout-strategy=overwrite] [--force] [--source=auto|bundled|github]
 
 # Composer 의존성 (모듈/플러그인별 독립 vendor/)
 php artisan extension:composer-install
@@ -741,11 +1284,12 @@ 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) |
 | `app/Http/Resources/**` | [api-resources.md](docs/backend/api-resources.md) |
+| `app/**/DTO/**`, `modules/**/src/DTO/**`, `plugins/**/src/DTO/**` | [dto.md](docs/backend/dto.md) |
 | `database/migrations/**` | [database-guide.md](docs/database-guide.md) |
 | `database/seeders/**` | [database-guide.md](docs/database-guide.md) |
 | `resources/layouts/**/*.json` | [layout-json.md](docs/frontend/layout-json.md) |
@@ -753,9 +1297,12 @@ php artisan migrate:rollback
 | `templates/**/src/components/**/*.tsx` | [components.md](docs/frontend/components.md) |
 | `modules/**/Listeners/**` | [hooks.md](docs/extension/hooks.md) |
 | `plugins/**/Listeners/**` | [hooks.md](docs/extension/hooks.md) |
+| `lang/{ko,en}/**/*.php` | [database-guide.md](docs/database-guide.md) (다국어 섹션) — 코어 백엔드 다국어 |
+| `lang/{ko,en}.json`, `lang/partial/{ko,en}/**` | [data-binding-i18n.md](docs/frontend/data-binding-i18n.md) — 코어 프론트엔드 다국어 (`$t:core.*`) |
 | `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) |
 
 ---
 
@@ -788,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`

INSTALL.md

@@ -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+ (프로덕션 권장, 선택) |
@@ -47,6 +47,14 @@ git clone https://github.com/gnuboard/g7.git
 </VirtualHost>
 ```
 
+**Apache + mod_fcgid 환경 추가 설정** (PHP 8.5 NTS Windows 등 mod_php 미제공 빌드):
+
+`fcgid.conf` 에 다음 1줄을 추가 후 Apache 재시작. 미설정 시 mod_fcgid 의 default 64KB 출력 버퍼가 인스톨러 SSE 스트림과 폴링 응답을 스크립트 종료 시점까지 보관하여 설치 진행 상황이 화면에 실시간 반영되지 않는다.
+
+```apache
+FcgidOutputBufferSize 0
+```
+
 **Nginx 예시**:
 
 ```nginx
@@ -69,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단계: 설치 마법사 실행
 
 브라우저에서 접속합니다.
@@ -184,6 +235,139 @@ php artisan serve
 
 ---
 
+## 방법 4: 공유 호스팅
+
+Composer 실행이 불가능한 공유 호스팅 환경에서의 설치 방법입니다. SSH + PHP CLI 사용이 가능한 요금제를 전제로 하며, [Vendor 번들 시스템](docs/extension/vendor-bundle.md)을 통해 Composer 없이 의존성을 배치합니다.
+
+### Cafe24
+
+#### 검증 환경
+
+본 가이드는 Cafe24 [**뉴아우토반 호스팅 절약형**](https://hosting.cafe24.com/?controller=new_product_page&page=newautobahn) 요금제에서 검증되었습니다. 동일 계열(일반형/비즈니스형 등) 요금제는 더 넉넉한 리소스를 제공하므로 그대로 적용 가능합니다.
+
+| 항목 | 절약형 사양 |
+|------|-------------|
+| 월 요금 | 500원 (1년 약정 시 450원) |
+| 웹 용량 | 700MB (FullSSD) |
+| 트래픽 | 1.6GB/일 |
+| DB | MariaDB 10.x (InnoDB), 서버 공간 내 무제한 |
+| PHP | 8.4 / 8.2 / 7.4 (Rocky OS 기준) |
+| 접속 | FTP / SFTP / SSH 지원 |
+
+> 웹 용량 700MB는 G7 코어 + 기본 확장 설치에 충분하지만, 업로드 파일이 많아질 경우 **일반형(1.4GB) 이상**을 권장합니다.
+
+#### 사전 준비
+
+- SSH 접속이 허용된 Cafe24 호스팅 계정 (절약형 이상)
+- SFTP 클라이언트 (FileZilla, WinSCP, Cyberduck 등)
+- Cafe24 관리자 페이지에서 PHP 버전을 **8.2 또는 8.4**로 설정
+- Cafe24 관리자 페이지에서 생성한 MariaDB DB (utf8mb4)
+
+#### 1단계: GitHub Release에서 배포 패키지 다운로드
+
+[https://github.com/gnuboard/g7/releases](https://github.com/gnuboard/g7/releases) 접속하여 최신 릴리스의 **Assets** 섹션에서 배포 패키지를 다운로드합니다.
+
+#### 2단계: SFTP로 ZIP 파일 업로드
+
+다운로드한 ZIP 파일을 SFTP로 홈 디렉토리 바로 아래에 업로드합니다.
+
+```text
+~/                  ← Cafe24 계정의 홈 디렉토리
+├── www             ← 기존 심볼릭 링크 또는 디렉토리 (4단계에서 갱신)
+└── g7-release.zip  ← 업로드한 ZIP 파일
+```
+
+#### 3단계: SSH 접속 후 압축 해제 및 심볼릭 링크 갱신
+
+SSH 접속 후 홈 디렉토리에서 ZIP 압축 해제와 웹 루트 심볼릭 링크 갱신을 함께 진행합니다.
+
+```bash
+cd ~
+
+# 업로드한 ZIP 압축 해제 (파일명은 실제 다운로드한 이름으로 교체)
+unzip g7-release.zip
+
+# 압축 해제 결과 확인 — 루트 디렉토리가 g7이 아니면 이름 변경
+ls -la
+# (필요 시) mv g7-7.0.9 g7
+
+# ZIP 파일 정리 (선택)
+rm g7-release.zip
+```
+
+압축 해제 후 디렉토리 구조는 다음과 같아야 합니다.
+
+```text
+~/
+├── www             ← 아래에서 갱신할 심볼릭 링크
+└── g7/
+    ├── app/
+    ├── bootstrap/
+    ├── public/
+    ├── storage/
+    ├── vendor-bundle.zip
+    ├── .env.example
+    └── ...
+```
+
+Cafe24의 웹 루트는 홈 디렉토리 아래 `www`(심볼릭 링크 또는 디렉토리)이며, 이를 `g7/public/`으로 연결해야 합니다.
+
+```bash
+# 기존 www 상태 확인
+ls -la www
+
+# 기존 www 삭제 후 재생성
+rm www
+ln -s g7/public www
+
+# 결과 확인 (아래와 같은 형태여야 합니다)
+ls -la www
+# lrwxrwxrwx 1 user user 9 ... www -> g7/public/
+```
+
+기존 `www` 안에 운영 중인 사이트가 있다면, 먼저 SFTP로 백업 다운로드하거나 `mv www www.bak`으로 이름 변경한 뒤 새 심볼릭 링크를 생성하세요.
+
+> 본 가이드의 모든 쉘 명령은 `cd ~` 또는 `cd ~/g7` 컨텍스트 진입 후 `./` 상대경로로 실행하므로, Cafe24 계정의 홈 디렉토리 절대경로를 몰라도 됩니다.
+
+#### 4단계: 웹 인스톨러 실행
+
+브라우저에서 도메인으로 접속합니다.
+
+```text
+http://도메인/install
+```
+
+설치 마법사의 각 단계를 진행합니다.
+
+| Step | 작업 |
+|------|------|
+| 0. 환영 | 언어 선택 및 `storage` 권한 검증 — 권한 부족 시 인스톨러가 상대경로 기반 명령을 자동 안내 |
+| 1. 라이선스 | 동의 |
+| 2. 요구사항 | PHP 8.2+ 및 필수 확장 확인 |
+| 3. 환경 설정 | DB 정보 + 관리자 계정 + **Vendor 설치 방식** 선택 |
+| 4. 확장 선택 | 템플릿/모듈/플러그인 선택 (의존성 자동 해결) |
+| 5. 설치 실행 | "설치 시작" 버튼 클릭 후 진행 상황 모니터링 |
+
+`.env` 파일 생성과 `storage` / `bootstrap/cache` 쓰기 권한 부여는 인스톨러가 환경(소유자 일치 여부 등)에 맞춰 Step 0 및 이후 단계에서 자동 안내하므로, 사전 SSH 작업으로 수행할 필요 없습니다.
+
+**Step 3 — Vendor 설치 방식 선택:**
+
+- **자동 (권장)**: 환경을 자동 감지하여 번들 모드로 폴백합니다.
+- **번들 Vendor 사용**: `vendor-bundle.zip`을 명시적으로 선택합니다 (Cafe24 권장).
+
+#### Cafe24 환경 체크리스트
+
+설치 중 문제가 발생하면 아래 항목을 확인합니다.
+
+- [ ] `php -v` 출력이 8.2 이상인가? (Cafe24 관리자에서 PHP 버전 변경 가능)
+- [ ] `php -m` 출력에 `pdo_mysql`, `mbstring`, `openssl`, `zip`이 포함되어 있는가?
+- [ ] `~/www`가 `g7/public/`를 올바르게 가리키는가? (`ls -la ~/www` 확인)
+- [ ] `vendor-bundle.zip`이 `~/g7/` 디렉토리에 존재하는가?
+- [ ] 웹 인스톨러 Step 3에서 "Vendor 설치 방식"을 **번들 Vendor 사용** 또는 **자동**으로 선택했는가?
+- [ ] DB 접속 정보(호스트/포트/계정)가 Cafe24 관리자 정보와 일치하는가?
+
+---
+
 ## 설치 후 확인
 
 설치가 완료되면 아래 페이지에 접근할 수 있습니다.
@@ -197,6 +381,157 @@ php artisan serve
 
 ---
 
+## 업그레이드
+
+이미 운영 중인 그누보드7을 새 버전으로 업그레이드할 때의 절차입니다. 신버전 ZIP 또는 git pull 로 파일만 덮어쓰면 **데이터베이스 마이그레이션, 데이터 시드, 확장(모듈/플러그인/템플릿) 재동기화가 함께 수행되지 않아** 게시판/회원/상품 데이터 누락이나 부정합 부팅 실패가 발생합니다. 반드시 아래 절차를 따라주세요.
+
+### 개요
+
+그누보드7 업그레이드의 SSoT(Single Source of Truth)는 Artisan 커맨드입니다.
+
+```bash
+sudo php artisan core:update
+```
+
+이 커맨드 1회 실행으로 다음 작업이 자동 수행됩니다.
+
+- 신버전 다운로드 및 압축 해제 (GitHub Release 또는 지정 ZIP)
+- 자동 백업 생성 (실패 시 자동 롤백)
+- 유지보수 모드 자동 진입
+- 데이터베이스 마이그레이션 실행
+- 업그레이드 스텝 실행 (버전별 데이터 보정)
+- 번들 확장 자동 재동기화
+- 캐시 정리 및 유지보수 모드 해제
+
+### 업그레이드 사전 준비
+
+업그레이드 전 다음을 확인하세요.
+
+1. **데이터베이스 백업** (필수)
+
+    ```bash
+    mysqldump -u DB사용자 -p DB이름 > backup-$(date +%Y%m%d).sql
+    ```
+
+2. **활성 디렉토리 백업 권장** — 직접 수정한 코드나 외부 확장(`_bundled` 에 포함되지 않은 GitHub install 확장) 이 있다면 다음 4개 디렉토리를 별도 위치로 백업하세요.
+
+    ```bash
+    tar -czf extensions-backup-$(date +%Y%m%d).tar.gz modules plugins templates lang-packs
+    ```
+
+3. **SSH/CLI 접근 확보** — 코어 업그레이드는 보안상 웹 UI 에서 실행할 수 없으며, 반드시 서버 터미널(SSH) 에서 직접 실행해야 합니다.
+
+### 방법 1: 관리자 UI 에서 업데이트 확인 (권장 동선 시작점)
+
+운영자가 새 버전 출시 여부를 가장 빠르게 알 수 있는 동선입니다.
+
+1. 관리자 페이지 로그인 → **환경설정 > 정보** 탭 이동
+2. "**업데이트 확인**" 버튼 클릭 → 최신 버전과 변경사항 모달 표시
+3. 신버전이 감지되면 "**변경사항 보기**" 로 changelog 확인 → "**업데이트 방법**" 버튼 클릭
+4. 모달이 권장 명령어와 본 가이드 링크를 안내하므로 그 안내에 따라 **서버 터미널에서 직접 실행**
+
+> 모달은 안내 전용입니다. 보안상 UI 에서 코어 업그레이드를 직접 실행하지 않으며, 운영자가 권한 일치를 확인한 후 CLI 에서 실행해야 합니다.
+
+### 방법 2: CLI 자동 업그레이드 (표준 절차)
+
+대다수 환경에서 권장되는 절차입니다.
+
+```bash
+sudo php artisan core:update
+```
+
+#### `sudo` 가 권장되는 이유
+
+업그레이드는 다음 파일들을 수정·생성하므로, 운영 환경에서 일반 사용자 권한으로 모두 접근 가능한 경우가 드뭅니다.
+
+- `.env` — `APP_VERSION` 갱신 (보안상 `0600` 또는 `0640` 권한, 소유자는 보통 웹 서버 사용자 `www-data` · `nginx` · `apache` 등)
+- `bootstrap/cache/` — 설정·라우트·서비스 캐시 갱신
+- `storage/framework/`, `storage/logs/` — 캐시·로그 파일 생성
+- `modules/`, `plugins/`, `templates/`, `lang-packs/` — 확장 재동기화
+
+`sudo` 로 root 권한을 위임받으면 위 파일들의 소유자가 누구든(웹 서버 사용자 또는 별도 배포 사용자) 권한 충돌 없이 한 번에 처리할 수 있습니다. 업그레이드 도중 `.env` 머지 단계는 기존 소유자·그룹을 그대로 보존하므로, root 로 실행해도 파일 권한이 임의로 변경되지 않습니다.
+
+#### `sudo` 없이 실행해도 되는 환경
+
+- 소유자가 명령줄 사용자와 일치하는 **단일 사용자 호스팅** (Cafe24 등 공유 호스팅, 개인 VPS 의 사용자 계정 운영) — 그냥 `php artisan core:update` 실행
+- **Windows (XAMPP/Laragon 등)** — 관리자 권한 PowerShell 에서 `php artisan core:update` 실행
+
+> 자신의 환경이 어느 쪽인지 확인하려면 `ls -l .env` 의 소유자(세 번째 컬럼) 가 명령줄 로그인 사용자와 일치하는지 보세요. 일치하면 `sudo` 없이 실행 가능합니다.
+
+### 방법 3: 수동 ZIP 업그레이드 (PHP zip 확장 미설치 환경)
+
+PHP `zip` 확장 또는 시스템 `unzip` 명령이 없는 서버에서는 GitHub Release ZIP 을 직접 다운로드한 뒤 압축 해제 경로를 지정해 업그레이드합니다.
+
+```bash
+# 1. GitHub 릴리스 페이지에서 ZIP 다운로드 후 서버에 압축 해제
+wget https://github.com/gnuboard/g7/releases/download/<버전>/<파일명>.zip
+unzip <파일명>.zip -d /tmp/g7-new
+
+# 2. 압축 해제된 경로를 지정하여 업데이트 실행
+sudo php artisan core:update --source=/tmp/g7-new
+```
+
+`--source=` 옵션은 다운로드 단계를 건너뛰고 지정 경로의 파일을 신버전으로 간주합니다.
+
+### 사용자군별 단계적 업그레이드
+
+여러 베타 버전을 건너뛰고 한 번에 최신 버전으로 올리는 것은 권장하지 않습니다. 중간 버전의 업그레이드 스텝이 이전 버전 메모리에 없는 신규 코드에 의존하여 부팅 실패 위험이 있습니다.
+
+| 현재 버전 | 권장 경로 |
+|----------|----------|
+| **beta.5 이상** | `sudo php artisan core:update` 1회로 최신 버전까지 자동 처리 |
+| **beta.3 / beta.4** | beta.5 → 최신 순서로 2회 분할 실행. 각 단계 후 `.env` `APP_VERSION` 이 자동 갱신되므로 같은 명령을 반복 실행 |
+| **beta.1 / beta.2** | beta.2 → beta.3 → beta.4 → beta.5 → 최신 순으로 단계별 진행 |
+| **beta.4 도중 fatal 후 중단** | `.env` `APP_VERSION` 을 변경하지 말고 `php artisan core:update --force` 재실행. 새 자식 프로세스가 신버전 메모리로 부팅되어 남은 스텝이 멱등 적용됨 |
+
+특정 베타 버전으로의 단계 업그레이드는 `--source=` 또는 `--zip=` 옵션으로 해당 버전 릴리스 ZIP 을 지정하여 진행합니다.
+
+> 사용자군별 상세 분기는 [CHANGELOG.md](CHANGELOG.md) 의 해당 버전 "Upgrade Notice" 섹션을 참고하세요.
+
+### 권한/캐시 트러블슈팅
+
+업그레이드 도중 또는 직후 사이트가 응답하지 않는 경우, 다음을 확인합니다. 본 절의 `chmod`/`chown`/`chgrp` 명령은 POSIX 권한 모델 (Linux/macOS/BSD) 환경 전용이며, Windows 환경에서는 해당하지 않습니다.
+
+#### `.env` 읽기 실패 (`Permission denied`)
+
+```bash
+ls -l .env
+# -rw------- 1 www-data www-data ... .env   ← 세 번째 컬럼이 소유자
+```
+
+대부분의 경우 `sudo php artisan core:update` 로 재실행하면 root 권한으로 소유자에 관계없이 접근됩니다. 권한 보안을 강화하려면 본 문서 [`.env` 권한 강화 (선택)](#env-권한-강화-선택) 섹션의 `0600` / `0640` 가이드를 참고하세요. 명령줄 사용자와 웹 서버 사용자가 다른 환경에서는 `0640` + 웹 서버 그룹 부여가 안전한 절충안입니다.
+
+#### `bootstrap/cache` 쓰기 실패
+
+```bash
+sudo chown -R www-data:www-data bootstrap/cache storage
+```
+
+소유자를 웹 서버 사용자로 일괄 정렬한 뒤 업그레이드를 재실행합니다.
+
+#### 업그레이드 도중 자동 롤백 후 부팅 실패
+
+beta.6 이상에서는 자동 롤백 후 잔존 파일을 추가 진단하는 `hotfix:rollback-stale-files` 커맨드가 제공됩니다.
+
+```bash
+# 진단 모드 (실제 삭제 없음)
+sudo php artisan hotfix:rollback-stale-files
+
+# 운영자 확인 후 실제 정리
+sudo php artisan hotfix:rollback-stale-files --prune
+```
+
+### 업그레이드 후 확인
+
+업그레이드가 끝나면 다음을 점검합니다.
+
+1. 관리자 페이지 > **환경설정 > 정보** 에서 G7 버전이 갱신되었는지 확인
+2. **확장 > 모듈/플러그인/템플릿** 목록이 모두 정상 표시되는지 확인
+3. 사용자 페이지 진입하여 기존 콘텐츠(게시판/상품/페이지) 가 정상 노출되는지 확인
+4. `storage/logs/laravel.log` 에 신규 에러가 누적되지 않는지 확인
+
+---
+
 ## 프로덕션 환경 추가 설정
 
 프로덕션 환경에서는 아래 항목을 추가로 설정하는 것을 권장합니다.
@@ -205,6 +540,30 @@ php artisan serve
 
 프로덕션 환경에서는 HTTPS를 사용해야 합니다. `.env` 파일에서 `APP_URL`을 `https://`로 설정하세요.
 
+### `.env` 권한 강화 (선택)
+
+`.env` 는 DB 비밀번호와 `APP_KEY` 등 평문 자격증명을 포함합니다. 인스톨러는 설치 직후 `.env` 의 권한을 임의로 변경하지 않으므로, 운영자가 환경에 맞춰 직접 강화 권한을 적용할 수 있습니다.
+
+- 가장 안전한 권한은 `0600` (소유자만 읽기·쓰기) 입니다. 다만 `0600` 적용 전에 **`.env` 의 소유자가 웹 서버 실행 사용자와 동일해야** 합니다. 소유자가 다른데 `0600` 으로 변경하면 웹 서버가 `.env` 를 읽지 못해 사이트가 응답하지 않습니다.
+
+- **단일 사용자 환경** (예: 카페24 등 명령줄 사용자와 웹 서버 사용자가 같은 경우):
+
+    ```bash
+    sudo chown www-data:www-data .env
+    sudo chmod 600 .env
+    ```
+
+- **자체 구축 서버** (명령줄 사용자 `jjh` 등과 웹 서버 사용자 `www-data` 가 다른 경우):
+
+    ```bash
+    sudo chgrp www-data .env
+    sudo chmod 640 .env
+    ```
+
+    웹 서버는 그룹 멤버로 읽기만 허용되고, 명령줄 사용자는 직접 수정할 수 있는 절충안입니다.
+
+인스톨러 Step 5 완료 화면은 현재 `.env` 권한이 `0600` 이 아닐 경우 위 두 명령 예시를 조건부로 표시합니다.
+
 ### 데몬 프로세스
 
 상시 실행이 필요한 프로세스입니다. Supervisor 등을 사용하여 관리합니다.

README.ko.md

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

README.md

@@ -1,74 +1,89 @@
+<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.0--beta.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>
   <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-Open%20Beta-orange" alt="Status"></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>Live Demo</strong></a> ·
+  <a href="https://g7.gnuboard.com/admin"><strong>Admin Demo</strong></a>
+</p>
+
+<p align="center">
+  <sub>The demo UI language follows your browser (Korean/English); you can switch it in the UI.</sub>
 </p>
 
 ---
 
-[소개](#그누보드7-소개) · [주요 기능](#주요-기능) · [기술 스택](#기술-스택) · [아키텍처](#아키텍처) · [빠른 시작](#빠른-시작) · [기본 제공 확장](#기본-제공-확장) · [비즈니스 모델](#비즈니스-모델) · [기존 사용자](#기존-그누보드-사용자) · [문서](#문서) · [기여하기](#기여하기) · [만든 사람들](#만든-사람들) · [커뮤니티](#커뮤니티) · [변경 기록](#변경-기록) · [라이선스](#라이선스)
+[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)
 
 ---
 
-## 그누보드7 소개
+## About Gnuboard7
 
-**그누보드7 (Gnuboard7)** 은 23년간 대한민국에서 가장 널리 사용된 오픈소스 CMS인 그누보드를, 현대적 기술 스택으로 **완전히 새로 설계**한 차세대 웹 플랫폼입니다.
+**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.
 
-Laravel과 React를 기반으로, 보안부터 아키텍처까지 처음부터 다시 만들었습니다.
+Everything from security to architecture was rewritten from scratch on Laravel and React.
 
-- **JSON 레이아웃 엔진**: React를 몰라도 JSON만으로 React 기반 UI를 선언적으로 정의. 모듈/플러그인이 프론트엔드 빌드 없이 JSON만으로 UI를 동적으로 주입/확장. 고도화된 UI가 필요한 경우 커스텀 React 컴포넌트를 개발하여 등록 가능
-- **하나의 플랫폼, 다양한 비즈니스**: 커뮤니티, 쇼핑몰, 구독, 예약 — 비즈니스 모델에 맞게 확장
-- **정교한 권한 관리**: 역할(Role) + 권한(Permission) + 스코프(Scope) 3단계 접근 제어로, 서비스 규모가 커져도 통제력 유지
-- **글로벌 레디**: 다국어(i18n) 네이티브 지원, 로케일 기반 UI, 다중 통화 대응
-- **확장 시스템**: 모듈 + 플러그인 + 템플릿 3중 구조로 코어 수정 없이 기능 확장
+- **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
 
-현대적인 웹 플랫폼에 필요한 핵심 기능을 갖추었습니다.
+Everything a modern web platform needs, built in.
 
-| 영역 | 설명 |
-|------|------|
-| **모듈 아키텍처** | 모듈 + 플러그인 + 템플릿 3중 확장 구조. 코어 수정 없이 독립적 모듈(게시판, 커머스 등) 개발이 가능합니다. Hook 기반 기능 주입으로 Service-Repository 패턴의 명확한 계층 분리를 유지합니다 |
-| **현지화** | 백엔드부터 프론트엔드까지 일관된 다국어 개발 환경을 제공합니다. 로케일 기반 UI, 확장 가능한 언어 팩을 지원합니다 |
-| **해외 결제** | 로컬 비즈니스를 넘어 글로벌 커머스로 도약하기 위한 기반을 제공합니다 `정식버전에서 지원예정` |
-| **권한 제어** | 역할별 메뉴와 기능, 데이터 범위까지 제어할 수 있습니다. 역할(Role) + 권한(Permission) + 스코프(Scope) 3단계 접근 제어로 조직 구조에 맞는 유연한 접근 관리를 제공합니다 |
-| **보안** | 입력값 자동 검증과 토큰 기반 인증을 제공합니다. 설계부터 보안을 고려한 다층 방어 구조(CSRF/XSS/SQL Injection)를 구현합니다 |
-| **유연한 화면 구성** | 화면 구조를 정의하면 즉시 반영할 수 있습니다. 프론트엔드 인프라 없이 JSON 선언만으로 웹앱 수준의 동적 화면 구현이 가능합니다 |
-| **레이아웃 편집기** | 위지윅 기반 레이아웃 편집 기능으로 화면 블록을 직접 배치하고 수정 결과를 바로 확인할 수 있습니다 `정식버전에서 지원예정` |
-| **검증된 기반** | Laravel + React 기반을 제공합니다. 글로벌 기업이 채택한 기술 스택으로 높은 확장성과 유연한 UI 구현이 가능합니다 |
-| **캐싱** | 화면 구조와 API 응답, 권한 정보를 다층으로 캐싱합니다. 불필요한 재처리 없이 빠른 응답 속도를 유지합니다 |
-| **활동 로그** | 관리자·사용자 활동 이력을 자동으로 기록하고 조회할 수 있습니다. Monolog 기반 구조로 확장이 용이합니다 |
-| **검색** | Laravel Scout 기반 전문 검색을 지원합니다. 상품, 게시글 등 주요 콘텐츠를 대상으로 검색 기능을 제공합니다 |
+| 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
 
-| 구분 | 기술 |
-|------|------|
-| **백엔드** | 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) |
+| 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
@@ -76,66 +91,67 @@ Gnuboard7
 │   ├── Controller → FormRequest → Service → Repository → Model
 │   ├── Hook System (Action / Filter)
 │   ├── Permission (Role → Permission → Scope)
+│   ├── Identity Verification (Policy × Purpose × Provider × Message)
+│   ├── 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
+│   ├── 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
@@ -169,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
 {
@@ -201,160 +217,370 @@ 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).
 
-**확장 시스템 3원칙**
+### Core systems
 
-1. **코어 수정 최소화** — 모든 비즈니스 로직은 모듈/플러그인으로 구현
-2. **동적 로딩** — composer.json 하드코딩 없이 디렉토리 스캔으로 자동 발견
-3. **Hook 기반 확장** — 서비스 계층에서 Action/Filter 훅으로 기능 주입
+Four systems work together to hold the platform up.
+
+#### 1. Extension system — three principles
+
+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. Hook system (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
+// Publish hooks from the service layer
+HookManager::doAction('core.user.after_create', $user, $data);
+$data = HookManager::applyFilters('core.user.filter_create_data', $data);
+
+// A module listener subscribes to the hook (auto-discovered)
+public static function getSubscribedHooks(): array
+{
+    return [
+        'core.user.after_create' => ['method' => 'onUserCreated', 'priority' => 20],
+    ];
+}
+```
+
+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. Shared cache system
+
+Built on `CacheInterface`, the **core, modules, and plugins** each manage their own cache without key collisions.
+
+| Driver | Prefix | Purpose |
+| --- | --- | --- |
+| `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
+// 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: prefix applied automatically
+) {}
+```
+
+- **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. Notification system
+
+Multi-channel notifications are managed through a three-tier model: **Definition × Template × Recipients**.
+
+```text
+┌─────────────────────┐      ┌───────────────────────┐      ┌─────────────────────┐
+│ NotificationDefini- │ 1..N │ NotificationTemplate  │      │ Recipients (JSON)   │
+│ tion                ├──────┤ (independent per      ├──────┤ - trigger_user      │
+│ type=order.created  │      │  channel)             │      │ - related_user      │
+│ variables=[...]     │      │ channel=mail|db|...   │      │ - role              │
+│                     │      │ subject, body,        │      │ - specific_users    │
+│                     │      │ click_url             │      │                     │
+└─────────────────────┘      └───────────────────────┘      └─────────────────────┘
+```
+
+- **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
+// A module service only publishes a hook; the delivery pipeline runs automatically
+HookManager::doAction('sirsoft-ecommerce.order.after_confirm', $order);
+
+// ↓ NotificationHookListener → NotificationDispatcher:
+// 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
+```
+
+- 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. 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 |
+| --- | --- |
+| 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 |
+
+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.
+
+> Details: [docs/extension/language-packs.md](docs/extension/language-packs.md) (Korean)
+
+#### 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             │
+│ (enforcement point │    │ (verification goal, │    │ (mail, KCP, Inicis,  │
+│  failure mode,     │ ◀▶ │  allowed channels,  │ ◀▶ │  SMS, external IDV)  │
+│  step, conditions) │    │  source tracking)   │    │                      │
+└────────────────────┘    └─────────────────────┘    └──────────────────────┘
+            │                                                  │
+            └──────────▶ Message Template (policy × purpose) ◀──┘
+                                    │
+                              GenericNotification
+```
+
+- **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)
+
+> 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-tosspayments** | 토스페이먼츠 결제 연동 |
-| **sirsoft-verification** | 본인인증 |
-| **sirsoft-daum_postcode** | 다음 우편번호 검색 |
-| **sirsoft-marketing** | 마케팅 도구 |
+| 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.
+
+| 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 |
+
+> 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
+
+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.
+
+| 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.
 
-| 모델 | 설명 | 상태 |
-|------|------|------|
-| **커뮤니티** | 게시판, 댓글, 회원 관리 | Beta |
-| **커머스** | 상품 등록, 주문, 결제, 배송 관리 | Beta |
+| 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
 
 <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>
+  <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>
 
-### 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
 
-보안 취약점을 발견하셨다면 [GitHub Issues](https://github.com/gnuboard/g7/issues)에 보고해 주세요.
+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
 

app/ActivityLog/Traits/ResolvesActivityLogType.php

@@ -3,6 +3,7 @@
 namespace App\ActivityLog\Traits;
 
 use App\Enums\ActivityLogType;
+use App\Extension\ExtensionManager;
 use Illuminate\Support\Facades\Log;
 
 /**
@@ -39,17 +40,31 @@ trait ResolvesActivityLogType
      * 활동 로그를 기록합니다.
      *
      * context에 log_type이 명시되지 않으면 resolveLogType()으로 자동 결정합니다.
+     * 호출 클래스 FQCN 으로부터 모듈/플러그인 origin 을 추론하여
+     * 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
     {
         $context['log_type'] ??= $this->resolveLogType();
 
+        $origin = ExtensionManager::resolveExtensionByFqcn(static::class);
+        if ($origin !== null) {
+            $properties = $context['properties'] ?? [];
+            $properties['extension_origin'] ??= $origin;
+            $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(),

app/Benchmark/Axes/BatchAxisRunner.php

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

app/Benchmark/Axes/ListAxisRunner.php

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

app/Benchmark/Axes/ScreenAxisRunner.php

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

app/Benchmark/Axes/WriteAxisRunner.php

@@ -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,
+        ];
+    }
+}

app/Benchmark/BenchmarkIdentity.php

@@ -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();
+    }
+}

app/Benchmark/BenchmarkProfileRegistry.php

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

app/Benchmark/BenchmarkReporter.php

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

app/Benchmark/Contracts/BenchmarkAxisRunner.php

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

app/Benchmark/DTO/BenchmarkProfile.php

@@ -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,
+        ];
+    }
+}

app/Benchmark/DTO/BenchmarkResult.php

@@ -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,
+        ];
+    }
+}

app/Benchmark/DTO/BenchmarkRunOptions.php

@@ -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,
+        ];
+    }
+}

app/Benchmark/ListIndexAdvisor.php

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

app/Benchmark/QueryCollector.php

@@ -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,
+        ];
+    }
+}

app/Benchmark/SyntheticSeeder.php

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

app/Casts/AsUnicodeJson.php

@@ -31,7 +31,15 @@ class AsUnicodeJson implements CastsAttributes
             return null;
         }
 
-        return json_decode($value, true);
+        // 이미 배열인 경우 (다시 read 시점에 배열이 들어오는 시나리오 방어)
+        if (is_array($value)) {
+            return $value;
+        }
+
+        $decoded = json_decode((string) $value, true);
+
+        // 스칼라/문자열로 디코드된 경우는 반환 타입(?array) 위반 → null 처리
+        return is_array($decoded) ? $decoded : null;
     }
 
     /**

app/Concerns/Seeder/HasTranslatableSeeder.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace App\Concerns\Seeder;
+
+use App\Extension\HookManager;
+
+/**
+ * TranslatableSeederInterface 구현체용 헬퍼 트레이트.
+ *
+ * 시더의 run() 안에서 $this->resolveTranslatedDefaults() 호출 시
+ * 활성 언어팩의 ja/en 등 locale 키가 자동 머지된 entry 배열을 반환.
+ *
+ * @since 7.0.0-beta.5
+ */
+trait HasTranslatableSeeder
+{
+    /**
+     * 활성 언어팩의 다국어 데이터로 머지된 시드 entry 를 반환합니다.
+     *
+     * @return array<int, array<string, mixed>>
+     */
+    protected function resolveTranslatedDefaults(): array
+    {
+        return HookManager::applyFilters(
+            $this->resolveTranslationFilterName(),
+            $this->getDefaults(),
+        );
+    }
+
+    /**
+     * `seed.{ext}.{entity}.translations` 필터 키를 조립합니다.
+     */
+    protected function resolveTranslationFilterName(): string
+    {
+        $extension = $this->getExtensionIdentifier();
+        $entity = $this->getTranslatableEntity();
+
+        return $extension !== ''
+            ? "seed.{$extension}.{$entity}.translations"
+            : "seed.{$entity}.translations";
+    }
+}

app/Console/Commands/ApiDocBackfillFieldsCommand.php

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

app/Console/Commands/ApiDocBackfillParamsCommand.php

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

app/Console/Commands/AssetUrlModeCommand.php

@@ -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('');
+    }
+}

app/Console/Commands/BenchCommand.php

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

app/Console/Commands/BroadcastDashboardResources.php

@@ -2,7 +2,7 @@
 
 namespace App\Console\Commands;
 
-use App\Events\Dashboard\DashboardUpdated;
+use App\Extension\HookManager;
 use App\Services\DashboardService;
 use Illuminate\Console\Command;
 
@@ -31,11 +31,13 @@ class BroadcastDashboardResources extends Command
      * 커맨드를 실행합니다.
      *
      * @param  DashboardService  $dashboardService  대시보드 서비스
-     * @return int
      */
     public function handle(DashboardService $dashboardService): int
     {
-        broadcast(new DashboardUpdated('resources', $dashboardService->getSystemResources()));
+        HookManager::broadcast('core.admin.dashboard', 'dashboard.resources.updated', [
+            'type' => 'resources',
+            'data' => $dashboardService->getSystemResources(),
+        ]);
 
         $this->info('시스템 리소스 정보가 브로드캐스트되었습니다.');
 

app/Console/Commands/CleanupExtensionBundlesCommand.php

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

app/Console/Commands/ConvertJsonUnicodeEscapes.php

@@ -109,7 +109,7 @@ class ConvertJsonUnicodeEscapes extends Command
     /**
      * 테이블 존재 여부를 확인합니다.
      *
-     * @param string $table 테이블명 (프리픽스 포함)
+     * @param  string  $table  테이블명 (프리픽스 포함)
      * @return bool 존재 여부
      */
     private function tableExists(string $table): bool
@@ -126,10 +126,10 @@ class ConvertJsonUnicodeEscapes extends Command
     /**
      * 특정 테이블의 특정 컬럼을 변환합니다.
      *
-     * @param string $table 테이블명
-     * @param string $column 컬럼명
-     * @param int $chunkSize 청크 크기
-     * @param bool $dryRun 드라이런 모드
+     * @param  string  $table  테이블명
+     * @param  string  $column  컬럼명
+     * @param  int  $chunkSize  청크 크기
+     * @param  bool  $dryRun  드라이런 모드
      * @return array{int, int} [변환 건수, 스킵 건수]
      */
     private function processColumn(string $table, string $column, int $chunkSize, bool $dryRun): array
@@ -152,11 +152,13 @@ class ConvertJsonUnicodeEscapes extends Command
 
         $this->components->twoColumnDetail("{$table}.{$column}", "대상 {$total}건 처리 중...");
 
+        // chunkById(키셋 순회) 필수 — 콜백이 필터 조건 컬럼을 UTF-8 로 다시 써서 처리된
+        // 행이 `LIKE '%\u%'` 결과에서 이탈한다. OFFSET 기반 chunk() 는 그만큼 앞으로 밀려
+        // 아직 변환되지 않은 행을 건너뛴다. (대상 테이블 8종 모두 `id` auto-increment PK)
         DB::table($table)
             ->whereNotNull($column)
             ->where($column, 'LIKE', '%\\\\u%')
-            ->orderBy('id')
-            ->chunk($chunkSize, function ($rows) use ($table, $column, $dryRun, &$converted, &$skipped) {
+            ->chunkById($chunkSize, function ($rows) use ($table, $column, $dryRun, &$converted, &$skipped) {
                 foreach ($rows as $row) {
                     $original = $row->{$column};
                     $decoded = json_decode($original, true);

app/Console/Commands/Core/BuildCoreCommand.php

@@ -2,12 +2,15 @@
 
 namespace App\Console\Commands\Core;
 
+use App\Extension\Traits\ClearsTemplateCaches;
 use Illuminate\Console\Command;
 use Illuminate\Support\Facades\Log;
 use Symfony\Component\Process\Process;
 
 class BuildCoreCommand extends Command
 {
+    use ClearsTemplateCaches;
+
     /**
      * The name and signature of the console command.
      */
@@ -82,26 +85,98 @@ class BuildCoreCommand extends Command
      */
     private function buildEngineOnly(string $projectPath, bool $watchMode, bool $productionMode): int
     {
-        $buildCommand = ['npm', 'run'];
-
+        // 감시 모드: 엔진 번들 + 편집기 번들(layout-editor.min.js)을 각각 vite --watch 로
+        // 병렬 감시한다. (기존 dev 서버는 코어 lib 를 빌드하지 않으므로 사용 불가)
         if ($watchMode) {
-            // build:core는 watch 모드가 없으므로 dev 사용
-            $buildCommand[] = 'dev';
-            $this->info('👀 파일 감시 모드로 코어 빌드 시작 (템플릿 엔진)');
+            $this->info('👀 파일 감시 모드로 코어 빌드 시작 (템플릿 엔진 + 레이아웃 편집기)');
             $this->line('   Ctrl+C로 종료할 수 있습니다.');
-        } else {
-            $buildCommand[] = 'build:core';
-            $this->info('🔨 코어 빌드 시작 (템플릿 엔진)'.($productionMode ? ' (프로덕션)' : ''));
+
+            return $this->runWatchBundles($projectPath);
         }
 
-        $result = $this->runNpmCommand($buildCommand, $projectPath, ! $watchMode);
+        // 3개 번들을 npm 스크립트로 순차 호출하므로 빌드 환경변수를 세 곳 모두에 주입한다.
+        $buildEnv = $this->buildEnv($productionMode);
 
-        if ($result === Command::SUCCESS && ! $watchMode) {
-            $this->info('✅ 코어 빌드 완료 (템플릿 엔진)');
-            $this->showEngineBuildResults($projectPath);
+        // ── 1) 템플릿 엔진 번들 (편집기 코드 제외) ──────────────────────────────
+        $this->info('🔨 코어 빌드 시작 (템플릿 엔진)'.($productionMode ? ' (프로덕션)' : ''));
+        $engineResult = $this->runNpmCommand(['npm', 'run', 'build:core'], $projectPath, true, $buildEnv);
+
+        if ($engineResult !== Command::SUCCESS) {
+            return $engineResult;
         }
 
-        return $result;
+        // ── 2) 레이아웃 편집기 번들 (lazy, /admin/layout-editor/* 진입 시 로드) ──
+        $this->info('🔨 코어 빌드 시작 (레이아웃 편집기)'.($productionMode ? ' (프로덕션)' : ''));
+        $editorResult = $this->runNpmCommand(['npm', 'run', 'build:core-editor'], $projectPath, true, $buildEnv);
+
+        if ($editorResult !== Command::SUCCESS) {
+            $this->error('❌ 레이아웃 편집기 번들 빌드 실패');
+
+            return $editorResult;
+        }
+
+        // ── 3) DevTools 번들 (lazy, 디버그 모드에서만 로드) ──
+        $this->info('🔨 코어 빌드 시작 (DevTools)'.($productionMode ? ' (프로덕션)' : ''));
+        $devtoolsResult = $this->runNpmCommand(['npm', 'run', 'build:core-devtools'], $projectPath, true, $buildEnv);
+
+        if ($devtoolsResult !== Command::SUCCESS) {
+            $this->error('❌ DevTools 번들 빌드 실패');
+
+            return $devtoolsResult;
+        }
+
+        $this->info('✅ 코어 빌드 완료 (템플릿 엔진 + 레이아웃 편집기 + DevTools)');
+        $this->showEngineBuildResults($projectPath);
+        $this->incrementExtensionCacheVersion();
+
+        return Command::SUCCESS;
+    }
+
+    /**
+     * 감시 모드에서 엔진 번들 + 편집기 번들을 병렬로 vite --watch 실행합니다.
+     *
+     * @param  string  $projectPath  프로젝트 경로
+     * @return int 명령 실행 결과 코드
+     */
+    private function runWatchBundles(string $projectPath): int
+    {
+        // 엔진 + 편집기 + DevTools 번들을 각각 vite --watch 로 병렬 감시
+        $bundles = [
+            'engine' => ['npm', 'run', 'build:core-watch'],
+            'editor' => ['npm', 'run', 'build:core-editor-watch'],
+            'devtools' => ['npm', 'run', 'build:core-devtools-watch'],
+        ];
+
+        /** @var array<string, Process> $processes */
+        $processes = [];
+
+        foreach ($bundles as $label => $command) {
+            if (PHP_OS_FAMILY === 'Windows') {
+                $command = array_merge(['cmd', '/c'], $command);
+            }
+
+            $process = new Process($command);
+            $process->setWorkingDirectory($projectPath);
+            $process->setTimeout(null);
+            $process->start(function ($type, $buffer) use ($label) {
+                $this->output->write("[{$label}] ".$buffer);
+            });
+
+            $processes[$label] = $process;
+        }
+
+        // 하나라도 실행 중이면 계속 대기 (Ctrl+C 로 종료)
+        do {
+            $anyRunning = false;
+            foreach ($processes as $process) {
+                if ($process->isRunning()) {
+                    $anyRunning = true;
+                }
+            }
+            usleep(100000); // 100ms
+        } while ($anyRunning);
+
+        return Command::SUCCESS;
     }
 
     /**
@@ -125,11 +200,18 @@ 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('✅ 코어 빌드 완료 (전체)');
             $this->showFullBuildResults($projectPath);
+            $this->incrementExtensionCacheVersion();
         }
 
         return $result;
@@ -150,22 +232,25 @@ class BuildCoreCommand extends Command
 
         $this->line('   빌드 결과:');
 
-        // template-engine.min.js 확인
+        // template-engine.min.js 확인 (일반 페이지 초기 로드 = 이 번들만)
         $engineFile = $corePath.'/template-engine.min.js';
         if (file_exists($engineFile)) {
             $fileSize = number_format(filesize($engineFile) / 1024, 2);
             $this->line("   - template-engine.min.js ({$fileSize} KB)");
         }
 
-        // lang 파일 확인
-        $langPath = $corePath.'/lang';
-        if (is_dir($langPath)) {
-            $langFiles = glob($langPath.'/*.json');
-            foreach ($langFiles as $langFile) {
-                $fileName = 'lang/'.basename($langFile);
-                $fileSize = number_format(filesize($langFile) / 1024, 2);
-                $this->line("   - {$fileName} ({$fileSize} KB)");
-            }
+        // layout-editor.min.js 확인 (편집기 lazy 번들, /admin/layout-editor/* 진입 시 로드)
+        $editorFile = $corePath.'/layout-editor.min.js';
+        if (file_exists($editorFile)) {
+            $fileSize = number_format(filesize($editorFile) / 1024, 2);
+            $this->line("   - layout-editor.min.js ({$fileSize} KB, lazy)");
+        }
+
+        // devtools.min.js 확인 (DevTools lazy 번들, 디버그 모드에서만 로드)
+        $devtoolsFile = $corePath.'/devtools.min.js';
+        if (file_exists($devtoolsFile)) {
+            $fileSize = number_format(filesize($devtoolsFile) / 1024, 2);
+            $this->line("   - devtools.min.js ({$fileSize} KB, lazy/debug)");
         }
     }
 
@@ -235,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') {
@@ -252,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) {

app/Console/Commands/Core/Concerns/BundledExtensionUpdatePrompt.php

@@ -0,0 +1,532 @@
+<?php
+
+namespace App\Console\Commands\Core\Concerns;
+
+use App\Console\Commands\Core\ExecuteBundledUpdatesCommand;
+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;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * 코어 업데이트 완료 후 _bundled 번들에 신버전이 포함된
+ * 모듈/플러그인/템플릿을 일괄 업데이트하는 대화형 프롬프트.
+ *
+ * CoreUpdateCommand 에서 사용되며, 다음 단계로 동작한다.
+ *  1) 각 확장 매니저의 checkAllXxxForUpdates() 로 번들 업데이트 감지
+ *  2) 감지 목록 표시 + 일괄 업데이트 진행 여부 확인
+ *  3) 동의 시 전역 레이아웃 전략(overwrite|keep) 1회 질의
+ *  4) 확장별 예외 변경 질의 (choice 로 다중 선택)
+ *  5) 각 확장 매니저의 updateXxx() 호출
+ *  6) 결과 요약 출력
+ *
+ * --force 옵션이 지정된 경우: 프롬프트 스킵 + 전역 전략 'overwrite' 로 즉시 실행.
+ *
+ * 본 트레이트를 사용하는 Command 는 HasUnifiedConfirm 트레이트도 함께 사용해야 한다
+ * (yes/no 입력 정규화 및 재질문 루프 제공).
+ */
+trait BundledExtensionUpdatePrompt
+{
+    /**
+     * 번들 업데이트 목록 수집.
+     *
+     * @return array{modules: array, plugins: array, templates: array, lang_packs: array}
+     */
+    protected function collectBundledUpdates(
+        ModuleManager $moduleManager,
+        PluginManager $pluginManager,
+        TemplateManager $templateManager,
+    ): array {
+        // CoreUpdateService::collectBundledExtensionUpdates() 를 통해 _bundled manifest 버전을
+        // DB 현재 버전과 직접 비교한다. Manager::checkXxxUpdate() 의 "GitHub 엄격 우선" 정책을
+        // 우회하여 GitHub 미릴리스 상태에서도 _bundled 신버전을 정확히 감지.
+        $extUpdates = app(CoreUpdateService::class)->collectBundledExtensionUpdates();
+
+        // 언어팩도 동일 패턴으로 _bundled vs DB 직접 비교 (LanguagePackService::collectBundledLangPackUpdates).
+        $extUpdates['lang_packs'] = app(LanguagePackService::class)->collectBundledLangPackUpdates();
+
+        return $extUpdates;
+    }
+
+    /**
+     * 일괄 업데이트 UX 를 실행하고 결과를 반환한다.
+     *
+     * @return array{success: int, failed: int, skipped: int, has_updates: bool}
+     */
+    protected function runBundledExtensionUpdatePrompt(
+        ModuleManager $moduleManager,
+        PluginManager $pluginManager,
+        TemplateManager $templateManager,
+        bool $force,
+    ): array {
+        $updates = $this->collectBundledUpdates($moduleManager, $pluginManager, $templateManager);
+        $updates['lang_packs'] = $updates['lang_packs'] ?? [];
+        $total = count($updates['modules']) + count($updates['plugins']) + count($updates['templates']) + count($updates['lang_packs']);
+
+        if ($total === 0) {
+            $this->info('활성 확장이 최신 번들과 일치합니다.');
+
+            return ['success' => 0, 'failed' => 0, 'skipped' => 0, 'has_updates' => false];
+        }
+
+        $this->newLine();
+        $this->info('번들에 새 버전이 포함된 확장이 감지되었습니다:');
+        foreach ($updates['modules'] as $m) {
+            $this->line("  [모듈]    {$m['identifier']}   {$m['current_version']} → {$m['latest_version']}");
+        }
+        foreach ($updates['plugins'] as $p) {
+            $this->line("  [플러그인] {$p['identifier']}   {$p['current_version']} → {$p['latest_version']}");
+        }
+        foreach ($updates['templates'] as $t) {
+            $this->line("  [템플릿]  {$t['identifier']}   {$t['current_version']} → {$t['latest_version']}");
+        }
+        foreach ($updates['lang_packs'] as $lp) {
+            $this->line("  [언어팩]  {$lp['identifier']}   {$lp['current_version']} → {$lp['latest_version']}");
+        }
+        $this->newLine();
+
+        if (! $force && ! $this->unifiedConfirm('일괄 업데이트를 진행하시겠습니까?', true)) {
+            $this->info('일괄 업데이트를 건너뜁니다.');
+
+            return ['success' => 0, 'failed' => 0, 'skipped' => $total, 'has_updates' => true];
+        }
+
+        // 전역 레이아웃 전략
+        $globalStrategy = 'overwrite';
+        if (! $force) {
+            $answer = $this->choice(
+                '전역 레이아웃 전략을 선택하세요',
+                ['overwrite' => '모든 레이아웃을 번들로 덮어쓰기', 'keep' => '사용자가 수정한 레이아웃은 보존'],
+                'overwrite',
+            );
+            $globalStrategy = $answer;
+        }
+
+        // 확장별 전략 오버라이드
+        $strategies = $this->collectPerExtensionStrategies($updates, $globalStrategy, $force);
+
+        // 검색 인덱스 재생성 여부 — 인덱스 잠금·재색인 비용이 있어 운영 중인 사이트에서는
+        // 기본값(아니오)을 유지하고 유지보수 시간에 별도로 수행하는 것이 안전하다.
+        $rebuildSearchIndex = $this->askRebuildSearchIndex($force);
+
+        // 일괄 실행
+        return $this->executeBulkUpdate(
+            $moduleManager,
+            $pluginManager,
+            $templateManager,
+            $updates,
+            $strategies,
+            $rebuildSearchIndex,
+        );
+    }
+
+    /**
+     * 확장별 전략 오버라이드 수집.
+     *
+     * @param  array  $updates  collectBundledUpdates() 반환값
+     * @return array<string, string> key: "{type}:{identifier}", value: strategy
+     */
+    private function collectPerExtensionStrategies(array $updates, string $globalStrategy, bool $force): array
+    {
+        // lang_packs 는 layout 이 없어 overwrite/keep strategy 가 의미 없으므로 의도적으로 제외.
+        // 매니페스트에는 strategy 없이 그대로 전달되어 ExecuteBundledUpdatesCommand 가 일괄 처리.
+        $strategies = [];
+        foreach (['modules', 'plugins', 'templates'] as $type) {
+            foreach ($updates[$type] as $ext) {
+                $strategies["{$type}:{$ext['identifier']}"] = $globalStrategy;
+            }
+        }
+
+        if ($force) {
+            return $strategies;
+        }
+
+        if (! $this->unifiedConfirm('전역 전략과 다르게 적용할 확장이 있습니까?', false)) {
+            return $strategies;
+        }
+
+        $choices = [];
+        foreach ($updates['modules'] as $m) {
+            $choices[] = "[모듈] {$m['identifier']}";
+        }
+        foreach ($updates['plugins'] as $p) {
+            $choices[] = "[플러그인] {$p['identifier']}";
+        }
+        foreach ($updates['templates'] as $t) {
+            $choices[] = "[템플릿] {$t['identifier']}";
+        }
+
+        $overrideStrategy = $globalStrategy === 'overwrite' ? 'keep' : 'overwrite';
+
+        $this->info("예외 확장은 '{$overrideStrategy}' 전략이 적용됩니다.");
+        $selected = $this->ask('예외 확장 선택 (쉼표로 구분, 빈 값이면 건너뛰기)', '');
+
+        if (trim((string) $selected) === '') {
+            return $strategies;
+        }
+
+        $lookup = [];
+        $idx = 0;
+        foreach (['modules', 'plugins', 'templates'] as $type) {
+            foreach ($updates[$type] as $ext) {
+                $lookup[$choices[$idx]] = "{$type}:{$ext['identifier']}";
+                $idx++;
+            }
+        }
+
+        foreach (array_map('trim', explode(',', (string) $selected)) as $choice) {
+            if (isset($lookup[$choice])) {
+                $strategies[$lookup[$choice]] = $overrideStrategy;
+            }
+        }
+
+        return $strategies;
+    }
+
+    /**
+     * 실제 일괄 업데이트 실행.
+     *
+     * 구조 fix (beta.4 도입): 부모(`core:update`) 프로세스의 stale memory 가 신버전 sync
+     * 메서드를 호출하지 못하던 결함의 영구 차단. 사용자 선택을 매니페스트로 직렬화한 후
+     * `core:execute-bundled-updates` 를 별도 PHP 프로세스에서 spawn 하여 실행한다 (자식은
+     * 디스크의 fresh 코어 코드 로드).
+     *
+     * proc_open 미지원 / 실패 환경에서는 in-process fallback 으로 안전하게 전환 (기존 흐름).
+     *
+     * @return array{success: int, failed: int, skipped: int, has_updates: bool}
+     */
+    private function executeBulkUpdate(
+        ModuleManager $moduleManager,
+        PluginManager $pluginManager,
+        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];
+        }
+
+        $this->newLine();
+        $this->info('── 일괄 업데이트 실행 ──');
+
+        $spawnResult = $this->spawnBundledUpdates($manifest);
+        if ($spawnResult !== null) {
+            return [
+                'success' => $spawnResult['success'],
+                'failed' => $spawnResult['failed'],
+                'skipped' => 0,
+                'has_updates' => true,
+            ];
+        }
+
+        // proc_open 미지원 / spawn 실패 — in-process fallback
+        $this->warn('별도 프로세스 spawn 실패 — in-process fallback 으로 전환합니다.');
+
+        return $this->executeBulkUpdateInProcess(
+            $moduleManager,
+            $pluginManager,
+            $templateManager,
+            $updates,
+            $strategies,
+            $rebuildSearchIndex,
+        );
+    }
+
+    /**
+     * 사용자 선택을 spawn 자식에 전달할 매니페스트 형식으로 직렬화.
+     *
+     * @return array{modules: array, plugins: array, templates: array, lang_packs: array}
+     */
+    private function buildBundledUpdateManifest(array $updates, array $strategies): array
+    {
+        $manifest = [
+            'modules' => [],
+            'plugins' => [],
+            'templates' => [],
+            'lang_packs' => [],
+        ];
+
+        foreach ($updates['modules'] ?? [] as $m) {
+            $id = $m['identifier'];
+            $manifest['modules'][] = [
+                'identifier' => $id,
+                'strategy' => $strategies["modules:{$id}"] ?? 'overwrite',
+            ];
+        }
+        foreach ($updates['plugins'] ?? [] as $p) {
+            $id = $p['identifier'];
+            $manifest['plugins'][] = [
+                'identifier' => $id,
+                'strategy' => $strategies["plugins:{$id}"] ?? 'overwrite',
+            ];
+        }
+        foreach ($updates['templates'] ?? [] as $t) {
+            $id = $t['identifier'];
+            $manifest['templates'][] = [
+                'identifier' => $id,
+                'strategy' => $strategies["templates:{$id}"] ?? 'overwrite',
+            ];
+        }
+        foreach ($updates['lang_packs'] ?? [] as $lp) {
+            $manifest['lang_packs'][] = ['identifier' => $lp['identifier']];
+        }
+
+        return $manifest;
+    }
+
+    private function bundledManifestIsEmpty(array $manifest): bool
+    {
+        return empty($manifest['modules'])
+            && empty($manifest['plugins'])
+            && empty($manifest['templates'])
+            && empty($manifest['lang_packs']);
+    }
+
+    /**
+     * `core:execute-bundled-updates` 를 별도 PHP 프로세스에서 실행.
+     *
+     * 자식 stdout 을 부모 콘솔로 실시간 전달 (단 `[BUNDLED-RESULT]` prefix 라인은
+     * 결과 페이로드로 보관 후 부모 콘솔로 노출하지 않음). 종료 후 페이로드 파싱.
+     *
+     * @return array{success: int, failed: int}|null spawn 성공 시 결과, 실패/미지원 시 null
+     */
+    private function spawnBundledUpdates(array $manifest): ?array
+    {
+        if (! function_exists('proc_open')) {
+            return null;
+        }
+
+        $manifestPath = storage_path('app/core_pending'.DIRECTORY_SEPARATOR.'bundled-updates-manifest_'.uniqid().'.json');
+        File::ensureDirectoryExists(dirname($manifestPath));
+        File::put($manifestPath, json_encode($manifest, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT));
+
+        try {
+            $phpBinary = config('process.php_binary', PHP_BINARY);
+            $artisan = base_path('artisan');
+
+            $command = [
+                $phpBinary,
+                $artisan,
+                'core:execute-bundled-updates',
+                '--manifest='.$manifestPath,
+            ];
+            $commandLine = implode(' ', array_map('escapeshellarg', $command)).' 2>&1';
+
+            $descriptors = [
+                0 => ['pipe', 'r'],
+                1 => ['pipe', 'w'],
+                2 => ['pipe', 'w'],
+            ];
+
+            // ENV 합집합 (G7_UPDATE_IN_PROGRESS 등 핵심 플래그 자식에 전달)
+            $env = array_merge(getenv(), $_ENV);
+
+            $process = proc_open($commandLine, $descriptors, $pipes, base_path(), $env);
+            if (! is_resource($process)) {
+                return null;
+            }
+
+            fclose($pipes[0]);
+
+            $resultPayload = null;
+            $resultPrefix = ExecuteBundledUpdatesCommand::RESULT_PREFIX;
+
+            while (! feof($pipes[1])) {
+                $line = fgets($pipes[1]);
+                if ($line === false) {
+                    continue;
+                }
+                $trimmed = rtrim($line);
+
+                if (str_starts_with($trimmed, $resultPrefix)) {
+                    $json = substr($trimmed, strlen($resultPrefix));
+                    $decoded = json_decode($json, true);
+                    if (is_array($decoded)) {
+                        $resultPayload = $decoded;
+                    }
+
+                    continue; // 부모 콘솔에 노출 안 함
+                }
+
+                $this->line($trimmed);
+            }
+
+            fclose($pipes[1]);
+            fclose($pipes[2]);
+            proc_close($process);
+
+            if ($resultPayload === null) {
+                Log::warning('번들 spawn 자식이 결과 페이로드를 출력하지 않음 — 카운트 0 으로 처리');
+
+                return ['success' => 0, 'failed' => 0];
+            }
+
+            return [
+                'success' => (int) ($resultPayload['success'] ?? 0),
+                'failed' => (int) ($resultPayload['failed'] ?? 0),
+            ];
+        } finally {
+            if (File::exists($manifestPath)) {
+                File::delete($manifestPath);
+            }
+        }
+    }
+
+    /**
+     * in-process fallback — proc_open 미지원 환경 전용.
+     *
+     * 기존 (beta.3) 흐름의 직접 호출 패턴 보존. 단 부모 메모리의 stale 코드로 인해
+     * sync 메서드 누락 결함이 재현될 수 있으므로 spawn 가능 환경에서는 사용되지 않는다.
+     *
+     * @return array{success: int, failed: int, skipped: int, has_updates: bool}
+     */
+    private function executeBulkUpdateInProcess(
+        ModuleManager $moduleManager,
+        PluginManager $pluginManager,
+        TemplateManager $templateManager,
+        array $updates,
+        array $strategies,
+        bool $rebuildSearchIndex = false,
+    ): array {
+        $success = 0;
+        $failed = 0;
+
+        foreach ($updates['modules'] as $m) {
+            $id = $m['identifier'];
+            $strategy = $strategies["modules:{$id}"] ?? 'overwrite';
+            $this->line("→ [모듈] {$id} ({$strategy})");
+            try {
+                $moduleManager->updateModule($id, true, null, VendorMode::Auto, $strategy, null, 'bundled');
+                $success++;
+            } catch (\Throwable $e) {
+                $failed++;
+                $this->warn("  실패: {$e->getMessage()}");
+                Log::error('번들 일괄 업데이트 실패', ['type' => 'module', 'id' => $id, 'error' => $e->getMessage()]);
+            }
+        }
+
+        foreach ($updates['plugins'] as $p) {
+            $id = $p['identifier'];
+            $strategy = $strategies["plugins:{$id}"] ?? 'overwrite';
+            $this->line("→ [플러그인] {$id} ({$strategy})");
+            try {
+                $pluginManager->updatePlugin($id, true, null, VendorMode::Auto, $strategy, null, 'bundled');
+                $success++;
+            } catch (\Throwable $e) {
+                $failed++;
+                $this->warn("  실패: {$e->getMessage()}");
+                Log::error('번들 일괄 업데이트 실패', ['type' => 'plugin', 'id' => $id, 'error' => $e->getMessage()]);
+            }
+        }
+
+        foreach ($updates['templates'] as $t) {
+            $id = $t['identifier'];
+            $strategy = $strategies["templates:{$id}"] ?? 'overwrite';
+            $this->line("→ [템플릿] {$id} ({$strategy})");
+            try {
+                $templateManager->updateTemplate($id, true, null, $strategy, 'bundled');
+                $success++;
+            } catch (\Throwable $e) {
+                $failed++;
+                $this->warn("  실패: {$e->getMessage()}");
+                Log::error('번들 일괄 업데이트 실패', ['type' => 'template', 'id' => $id, 'error' => $e->getMessage()]);
+            }
+        }
+
+        $langPackService = app(LanguagePackService::class);
+        foreach ($updates['lang_packs'] ?? [] as $lp) {
+            $id = $lp['identifier'];
+            $this->line("→ [언어팩] {$id}");
+            try {
+                $pack = $langPackService->findByIdentifier($id);
+                if (! $pack) {
+                    throw new \RuntimeException(__('language_packs.errors.identifier_not_found', ['identifier' => $id]));
+                }
+                $langPackService->performUpdate($pack, true);
+                $success++;
+            } catch (\Throwable $e) {
+                $failed++;
+                $this->warn("  실패: {$e->getMessage()}");
+                Log::error('번들 일괄 업데이트 실패', ['type' => 'lang_pack', 'id' => $id, 'error' => $e->getMessage()]);
+            }
+        }
+
+        $this->newLine();
+        $this->info("업데이트 완료: 성공 {$success}, 실패 {$failed}");
+
+        $this->runSearchIndexRebuildIfRequested($rebuildSearchIndex);
+
+        return [
+            'success' => $success,
+            'failed' => $failed,
+            'skipped' => 0,
+            'has_updates' => true,
+        ];
+    }
+
+    /**
+     * 검색 인덱스 재생성 여부를 운영자에게 확인합니다.
+     *
+     * 재생성은 인덱스 잠금 또는 전체 재색인을 유발하므로 기본값은 "아니오" 입니다.
+     * `--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]));
+        }
+    }
+}

app/Console/Commands/Core/CoreVendorBundleCommand.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace App\Console\Commands\Core;
+
+use App\Console\Commands\Vendor\Concerns\RunsVendorBundleAction;
+use App\Extension\Vendor\VendorBundler;
+use Illuminate\Console\Command;
+
+/**
+ * 코어 vendor/ 디렉토리를 vendor-bundle.zip 으로 빌드합니다.
+ *
+ * 기존 *:build 패턴과 일관된 코어 단독 vendor 번들 빌드 명령어.
+ */
+class CoreVendorBundleCommand extends Command
+{
+    use RunsVendorBundleAction;
+
+    protected $signature = 'core:vendor-bundle
+                            {--force : 해시 체크 무시, 강제 재빌드}
+                            {--check : 실제 빌드 없이 stale 여부만 확인}';
+
+    protected $description = '코어 vendor/ 디렉토리를 vendor-bundle.zip 으로 빌드합니다 (공유 호스팅용)';
+
+    public function handle(VendorBundler $bundler): int
+    {
+        $targets = [['type' => 'core', 'identifier' => null]];
+
+        return $this->runBuildAction(
+            $bundler,
+            $targets,
+            (bool) $this->option('force'),
+            (bool) $this->option('check'),
+        );
+    }
+}

app/Console/Commands/Core/CoreVendorVerifyCommand.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Console\Commands\Core;
+
+use App\Console\Commands\Vendor\Concerns\RunsVendorBundleAction;
+use App\Extension\Vendor\VendorIntegrityChecker;
+use Illuminate\Console\Command;
+
+/**
+ * 코어 vendor-bundle.zip 무결성을 검증합니다.
+ */
+class CoreVendorVerifyCommand extends Command
+{
+    use RunsVendorBundleAction;
+
+    protected $signature = 'core:vendor-verify';
+
+    protected $description = '코어 vendor-bundle.zip 의 SHA256 무결성을 검증합니다';
+
+    public function handle(VendorIntegrityChecker $checker): int
+    {
+        $targets = [['type' => 'core', 'identifier' => null]];
+
+        return $this->runVerifyAction($checker, $targets);
+    }
+}

app/Console/Commands/Core/ExecuteBundledUpdatesCommand.php

@@ -0,0 +1,194 @@
+<?php
+
+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;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * 번들 확장(모듈/플러그인/템플릿/언어팩) 일괄 업데이트를 별도 PHP 프로세스에서 실행합니다.
+ *
+ * `core:update` 의 `BundledExtensionUpdatePrompt::executeBulkUpdate` 가 사용자 선택을
+ * 매니페스트로 직렬화한 후 본 커맨드를 `proc_open` 으로 spawn 한다. 자식은 fresh PHP
+ * 프로세스이므로 디스크에 막 적용된 신버전 코어 코드(특히 `ModuleManager` /
+ * `PluginManager` / `TemplateManager` / `LanguagePackService`) 를 메모리에 로드한 상태
+ * 에서 update 메서드를 호출한다.
+ *
+ * 부모 프로세스의 stale memory 가 신규 sync 메서드(`syncDeclarativeArtifacts` 등) 를
+ * 호출하지 못하던 결함의 영구 차단 (beta.4 의 `Upgrade_7_0_0_beta_4` 사후 보정과는 별개의
+ * 구조적 fix — 향후 모든 코어 업그레이드에서 동일 패턴 회귀를 차단).
+ *
+ * 매니페스트 형식:
+ * ```json
+ * {
+ *   "modules":    [{"identifier": "...", "strategy": "overwrite|keep"}, ...],
+ *   "plugins":    [{"identifier": "...", "strategy": "overwrite|keep"}, ...],
+ *   "templates":  [{"identifier": "...", "strategy": "overwrite|keep"}, ...],
+ *   "lang_packs": [{"identifier": "..."}, ...]
+ * }
+ * ```
+ *
+ * 출력:
+ *   - stdout 에 진행 라인을 그대로 출력 (부모 콘솔이 forwarding)
+ *   - 종료 직전 `[BUNDLED-RESULT] {json}` 표식으로 최종 카운트 페이로드를 1회 출력 →
+ *     부모가 stdout 파싱해 결과 복원.
+ */
+class ExecuteBundledUpdatesCommand extends Command
+{
+    public const RESULT_PREFIX = '[BUNDLED-RESULT] ';
+
+    protected $signature = 'core:execute-bundled-updates
+        {--manifest= : 업데이트 매니페스트 JSON 파일 경로 (필수)}
+        {--force : 강제 업데이트 플래그 (확장 매니저 update 호출에 전달)}
+        {--rebuild-search-index : 일괄 업데이트 후 검색 인덱스 재생성 (매니페스트의 선택보다 우선)}';
+
+    protected $description = '번들 확장 일괄 업데이트를 실행합니다 (CoreUpdateCommand 내부용 — fresh PHP 프로세스에서 호출)';
+
+    public function handle(): int
+    {
+        $manifestPath = (string) $this->option('manifest');
+        if ($manifestPath === '' || ! File::isFile($manifestPath)) {
+            $this->error('--manifest 옵션이 필수이며 존재하는 파일이어야 합니다.');
+
+            return self::INVALID;
+        }
+
+        // spawn 자식 진입 시 활성 모듈/플러그인의 PSR-4 매핑을 fresh 등록 — 자세한 배경은
+        // ExecuteUpgradeStepsCommand::handle 의 동일 호출 주석 참조.
+        // (Artisan::call 대신 직접 메서드 호출 — nested Artisan::call 이 outer 명령의
+        // output buffer 를 덮어쓰는 Laravel 동작 회피)
+        try {
+            app(ExtensionManager::class)->updateComposerAutoload();
+        } catch (\Throwable $e) {
+            Log::warning('bundled update spawn 자식: updateComposerAutoload 호출 실패', [
+                'error' => $e->getMessage(),
+            ]);
+        }
+
+        $manifest = json_decode(File::get($manifestPath), true);
+        if (! is_array($manifest)) {
+            $this->error('매니페스트 JSON 파싱 실패: '.$manifestPath);
+
+            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'] ?? [];
+        $langPacks = $manifest['lang_packs'] ?? [];
+
+        $moduleManager = app(ModuleManager::class);
+        $pluginManager = app(PluginManager::class);
+        $templateManager = app(TemplateManager::class);
+        $langPackService = app(LanguagePackService::class);
+
+        $success = 0;
+        $failed = 0;
+
+        $this->info('── 번들 일괄 업데이트 실행 (spawn child) ──');
+
+        foreach ($modules as $entry) {
+            $id = (string) ($entry['identifier'] ?? '');
+            $strategy = (string) ($entry['strategy'] ?? 'overwrite');
+            if ($id === '') {
+                continue;
+            }
+            $this->line("→ [모듈] {$id} ({$strategy})");
+            try {
+                $moduleManager->updateModule($id, true, null, VendorMode::Auto, $strategy, null, 'bundled');
+                $success++;
+            } catch (\Throwable $e) {
+                $failed++;
+                $this->warn("  실패: {$e->getMessage()}");
+                Log::error('번들 일괄 업데이트 실패 (spawn)', ['type' => 'module', 'id' => $id, 'error' => $e->getMessage()]);
+            }
+        }
+
+        foreach ($plugins as $entry) {
+            $id = (string) ($entry['identifier'] ?? '');
+            $strategy = (string) ($entry['strategy'] ?? 'overwrite');
+            if ($id === '') {
+                continue;
+            }
+            $this->line("→ [플러그인] {$id} ({$strategy})");
+            try {
+                $pluginManager->updatePlugin($id, true, null, VendorMode::Auto, $strategy, null, 'bundled');
+                $success++;
+            } catch (\Throwable $e) {
+                $failed++;
+                $this->warn("  실패: {$e->getMessage()}");
+                Log::error('번들 일괄 업데이트 실패 (spawn)', ['type' => 'plugin', 'id' => $id, 'error' => $e->getMessage()]);
+            }
+        }
+
+        foreach ($templates as $entry) {
+            $id = (string) ($entry['identifier'] ?? '');
+            $strategy = (string) ($entry['strategy'] ?? 'overwrite');
+            if ($id === '') {
+                continue;
+            }
+            $this->line("→ [템플릿] {$id} ({$strategy})");
+            try {
+                $templateManager->updateTemplate($id, true, null, $strategy, 'bundled');
+                $success++;
+            } catch (\Throwable $e) {
+                $failed++;
+                $this->warn("  실패: {$e->getMessage()}");
+                Log::error('번들 일괄 업데이트 실패 (spawn)', ['type' => 'template', 'id' => $id, 'error' => $e->getMessage()]);
+            }
+        }
+
+        foreach ($langPacks as $entry) {
+            $id = (string) ($entry['identifier'] ?? '');
+            if ($id === '') {
+                continue;
+            }
+            $this->line("→ [언어팩] {$id}");
+            try {
+                $pack = $langPackService->findByIdentifier($id);
+                if (! $pack) {
+                    throw new \RuntimeException(__('language_packs.errors.identifier_not_found', ['identifier' => $id]));
+                }
+                $langPackService->performUpdate($pack, true);
+                $success++;
+            } catch (\Throwable $e) {
+                $failed++;
+                $this->warn("  실패: {$e->getMessage()}");
+                Log::error('번들 일괄 업데이트 실패 (spawn)', ['type' => 'lang_pack', 'id' => $id, 'error' => $e->getMessage()]);
+            }
+        }
+
+        $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,
+            'failed' => $failed,
+        ], JSON_UNESCAPED_UNICODE));
+
+        return $failed > 0 ? self::FAILURE : self::SUCCESS;
+    }
+}

app/Console/Commands/Core/ExecuteUpgradeStepsCommand.php

@@ -0,0 +1,315 @@
+<?php
+
+namespace App\Console\Commands\Core;
+
+use App\Console\Commands\Core\Concerns\BundledExtensionUpdatePrompt;
+use App\Console\Commands\Traits\HasUnifiedConfirm;
+use App\Exceptions\UpgradeHandoffException;
+use App\Extension\ExtensionManager;
+use App\Extension\Helpers\FilePermissionHelper;
+use App\Extension\ModuleManager;
+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;
+
+/**
+ * 코어 업그레이드 스텝을 별도 프로세스에서 실행합니다.
+ *
+ * CoreUpdateCommand 의 Step 10 에서 proc_open 으로 호출하여 최신 버전 클래스·
+ * config 를 새 PHP 프로세스에서 로드하게 하는 진입점. 새 프로세스에서 실행되므로
+ * upgrade step 이 신규 Service/Repository/Controller 등을 자유롭게 호출할 수 있다.
+ *
+ * 단, 이는 beta.3 이후 업그레이드 경로(경로 B)에만 적용된다. beta.1 → beta.2
+ * 업그레이드는 beta.1 의 CoreUpdateCommand 가 본 커맨드를 알지 못하므로 spawn
+ * 효과를 받지 못한다(경로 A) — 이 경우 upgrade step 파일 내부 로컬 로직으로
+ * 후처리를 수행해야 한다. 상세는 docs/extension/upgrade-step-guide.md 참조.
+ *
+ * 단독 실행 안전성: 운영자가 HANDOFF 안내문 또는 수동 복구 목적으로 직접 호출하면
+ * 기본값으로 부모 CoreUpdateCommand 가 처리하던 사전(Migration + Resync) 및
+ * 사후(.env 버전 + 캐시 정리 + 번들 확장 일괄 업데이트) 단계를 자동 수행한다.
+ * CoreUpdateCommand spawn 호출 시엔 `--skip-*` 옵션 5개로 중복 회피.
+ *
+ * `--steps-only`: 업그레이드 스텝만 실행하고 모든 보조 단계(권한 정상화 ·
+ * 오토로드 재생성 · 마이그레이션 · resync · 버전 갱신 · 캐시 정리 · 번들 업데이트)를
+ * 생략한다. 특정 스텝의 데이터 보정만 단발성으로 재실행할 때 사용한다. 보조 단계가
+ * 이미 완료된 환경에서 무거운 권한 재귀 순회 등을 건너뛴다.
+ */
+class ExecuteUpgradeStepsCommand extends Command
+{
+    use BundledExtensionUpdatePrompt;
+    use ClearsTemplateCaches;
+    use HasUnifiedConfirm;
+
+    protected $signature = 'core:execute-upgrade-steps
+        {--from= : 시작 버전}
+        {--to= : 대상 버전}
+        {--force : 동일 버전 강제 실행 + 번들 확장 일괄 업데이트 prompt 스킵}
+        {--steps-only : 업그레이드 스텝만 실행 — 권한 정상화·오토로드 재생성·마이그레이션·resync·버전 갱신·캐시 정리·번들 업데이트 등 모든 사전/사후 보조 단계 생략}
+        {--skip-migrations : 마이그레이션 실행 생략 (CoreUpdateCommand spawn 시 부모 Step 9 가 이미 실행)}
+        {--skip-resync : 코어 config 재로드 및 권한/메뉴/시더 동기화 생략 (동일 사유)}
+        {--skip-version-env : .env APP_VERSION 갱신 생략 (부모 Step 11 가 처리)}
+        {--skip-cache-clear : 캐시 정리 생략 (부모 Step 11 가 처리)}
+        {--skip-bundled-updates : 번들 확장 일괄 업데이트 생략 (부모가 prompt 로 처리)}';
+
+    protected $description = '코어 업그레이드 스텝을 별도 프로세스에서 실행합니다. 단독 실행 시 사전/사후 단계를 자동 수행하며, --steps-only 로 스텝만 실행할 수 있습니다.';
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * @param  CoreUpdateService  $service  코어 업데이트 서비스
+     * @return int 종료 코드
+     */
+    public function handle(CoreUpdateService $service): int
+    {
+        $from = (string) $this->option('from');
+        $to = (string) $this->option('to');
+        $force = (bool) $this->option('force');
+
+        // --steps-only: 업그레이드 스텝만 실행하고 모든 보조 단계(권한 정상화 · 오토로드
+        // 재생성 · 마이그레이션 · resync · 버전 갱신 · 캐시 정리 · 번들 업데이트)를 생략한다.
+        // 운영자가 특정 스텝의 데이터 보정만 단발성으로 재실행할 때 사용한다.
+        $stepsOnly = (bool) $this->option('steps-only');
+
+        if ($from === '' || $to === '') {
+            $this->error('--from 과 --to 는 필수 옵션입니다.');
+
+            return self::INVALID;
+        }
+
+        // spawn 자식 진입 시 활성 모듈/플러그인의 PSR-4 매핑을 fresh 등록.
+        // 부모 프로세스의 autoload-extensions.php 가 stale 한 경우 upgrade step 안에서
+        // ModuleManager / PluginManager 호출 → declaration 메서드가 Models/Services 등
+        // 다른 클래스 lazy load 시 "Class not found" 발생. 진입 직후 1회 호출로 모든 후속
+        // upgrade step (현재 + 미래) 이 fresh autoload 환경에서 실행됨을 보장.
+        //
+        // 본 커맨드 자체가 spawn 자식 (proc_open 으로 fork 된 별개 PHP 프로세스) 의 진입점이라
+        // 디스크의 fresh ExtensionManager(beta.X+1) 클래스를 메모리에 로드한 상태. 따라서
+        // `app(ExtensionManager::class)->updateComposerAutoload()` 직접 호출은 stale 가능성
+        // 없음. (Artisan::call 대신 직접 호출 — nested Artisan::call 이 outer 명령의
+        // output buffer 를 덮어쓰는 Laravel 동작 회피)
+        if (! $stepsOnly) {
+            try {
+                app(ExtensionManager::class)->updateComposerAutoload();
+            } catch (\Throwable $e) {
+                Log::warning('upgrade step spawn 자식: updateComposerAutoload 호출 실패', [
+                    'error' => $e->getMessage(),
+                ]);
+            }
+        }
+
+        // spawn 자식 진입 시 활성 디렉토리의 쓰기 권한 디렉토리를 멱등적으로 보장.
+        // fresh 디스크 config (`app.update.restore_ownership_group_writable`) 를 읽어 처리하므로
+        // 미래 release 가 새 쓰기 권한 디렉토리를 도입할 때 본 호출은 자동으로 신규 항목을 처리한다.
+        // upgrade step 에 mkdir/chown 코드를 매번 하드코딩할 필요 없음.
+        //
+        // 한계: 부모(이전 버전) 만 알고 있던 신규 디렉토리는 처리 불가 — 그 일회성 케이스는
+        // 해당 release 의 upgrade step 단발 처리. (예: beta.3→beta.4 의 lang-packs/* 보정)
+        if (! $stepsOnly) {
+            try {
+                $writablePaths = (array) config('app.update.restore_ownership_group_writable', []);
+                if (! empty($writablePaths)) {
+                    $service->ensureWritableDirectories(
+                        $writablePaths,
+                        function (string $level, string $msg): void {
+                            // 콘솔 + upgrade 로그 채널 동시 출력 — 운영자가 단일 파일(upgrade.log)에서
+                            // spawn 자식의 권한 정상화 진행을 추적할 수 있도록 양쪽 모두 누적.
+                            $this->{$level === 'warning' ? 'warn' : 'info'}($msg);
+                            Log::channel('upgrade')->$level('[spawn] '.$msg);
+                        },
+                    );
+                }
+            } catch (\Throwable $e) {
+                Log::warning('upgrade step spawn 자식: ensureWritableDirectories 호출 실패', [
+                    'error' => $e->getMessage(),
+                ]);
+            }
+        }
+
+        // 코어 업데이트 spawn 자식 감지.
+        //
+        // CoreUpdateCommand::spawnUpgradeStepsProcess 가 자식에 `G7_UPDATE_IN_PROGRESS=1` env 를
+        // 전달한다 (beta.3 부터 존재). 이 시그널은 자식이 부모의 `core:update` 컨텍스트에서
+        // 실행 중임을 의미한다. 부모는 본인이 사전(Step 9 migration + resync) + 사후
+        // (Step 11 version-env + cache-clear + bundled prompt) 단계를 모두 책임지므로 자식은
+        // 5단계 모두 스킵해야 한다.
+        //
+        // 구버전 부모(예: beta.5)는 신버전 자식이 도입한 `--skip-*` 옵션을 모른다. 옵션 부재
+        // 시 자식이 사후 단계를 실행하면 (특히 bundled prompt) non-interactive 환경에서
+        // `Aborted.` exit=1 회귀 발생 (882deb9b0 사각지대). env 시그널이 옵션 부재를 보완.
+        //
+        // 단독 호출 (운영자 수동) 시엔 env 미설정 → 모든 단계 정상 진행.
+        $isSpawnChild = getenv('G7_UPDATE_IN_PROGRESS') === '1';
+
+        // 사전 단계 (단독 실행 안전성 보장).
+        //
+        // CoreUpdateCommand 가 spawn 호출 시엔 부모 Step 9 (CoreUpdateCommand.php:408-409) 에서
+        // 이미 동일 단계를 실행했으므로 --skip-migrations / --skip-resync 로 중복 회피.
+        // 운영자 단독 호출 시 옵션 미전달 → 기본값으로 두 단계 자동 수행 →
+        // migration / permission / menu / seeder 누락 차단.
+        if (! $this->option('skip-migrations') && ! $isSpawnChild && ! $stepsOnly) {
+            $this->info('마이그레이션 실행');
+            $service->runMigrations();
+        } else {
+            $this->info($stepsOnly ? '[steps-only] 마이그레이션 스킵' : '[spawn] 마이그레이션 스킵 — 부모가 이미 실행');
+        }
+
+        if (! $this->option('skip-resync') && ! $isSpawnChild && ! $stepsOnly) {
+            $this->info('코어 config 재로드 및 권한/메뉴/시더 동기화');
+            $service->reloadCoreConfigAndResync();
+        } else {
+            $this->info($stepsOnly ? '[steps-only] resync 스킵' : '[spawn] resync 스킵 — 부모가 이미 실행');
+        }
+
+        $stepsExecuted = 0;
+        $stepsDiscovered = 0;
+
+        try {
+            $service->runUpgradeSteps(
+                $from,
+                $to,
+                function (string $version) use (&$stepsExecuted): void {
+                    $this->info("upgrade step 실행: {$version}");
+                    $stepsExecuted++;
+                },
+                $force,
+                function (int $discovered) use (&$stepsDiscovered): void {
+                    $stepsDiscovered = $discovered;
+                },
+            );
+        } catch (UpgradeHandoffException $e) {
+            // 업그레이드 스텝이 새 PHP 프로세스 재진입을 요청했다.
+            // 부모 프로세스(spawnUpgradeStepsProcess)가 [HANDOFF] 라인을 stdout 에서
+            // 읽어 페이로드를 복원하고 UpgradeHandoffException 재구성 후 상위로 던지도록,
+            // JSON 페이로드를 표식과 함께 출력한다. 표식 문자열은 구분자 역할이므로 일반
+            // step 출력과 충돌하지 않게 고정된 접두사를 사용한다.
+            //
+            // resumeCommand 는 step 작성자가 null 로 두는 것을 권장(CoreUpdateCommand 가
+            // from/to 버전을 사용해 자동 생성). null 도 JSON 으로 그대로 전달.
+            $payload = json_encode([
+                'afterVersion' => $e->afterVersion,
+                'reason' => $e->reason,
+                'resumeCommand' => $e->resumeCommand,
+            ], JSON_UNESCAPED_UNICODE);
+
+            $this->line('[HANDOFF] '.$payload);
+
+            Log::info('core:execute-upgrade-steps 핸드오프', [
+                'from' => $from,
+                'to' => $to,
+                'after' => $e->afterVersion,
+                'reason' => $e->reason,
+            ]);
+
+            $this->restoreUpgradeLogOwnership();
+
+            return UpgradeHandoffException::EXIT_CODE;
+        } catch (\Throwable $e) {
+            Log::error('core:execute-upgrade-steps 실패', [
+                'from' => $from,
+                'to' => $to,
+                'error' => $e->getMessage(),
+            ]);
+            $this->error($e->getMessage());
+
+            $this->restoreUpgradeLogOwnership();
+
+            return self::FAILURE;
+        }
+
+        // 부모 (CoreUpdateCommand::spawnUpgradeStepsProcess) 가 silent skip 가드용으로 파싱하는
+        // 명시 종료 신호. [HANDOFF] 와 동일 구조의 라인 프로토콜. 정상 종료 (handoff 미발생) 경로
+        // 에서만 발행되며, 부모는 exit=0 인데 본 라인이 부재하면 mode=abort 시 throw,
+        // mode=fallback 시 in-process 진행 (`spawn_failure_mode`).
+        $this->line('[STEPS_EXECUTED] '.json_encode([
+            'count' => $stepsExecuted,
+            'discovered' => $stepsDiscovered,
+            'fromVersion' => $from,
+            'toVersion' => $to,
+        ], JSON_UNESCAPED_UNICODE));
+
+        // 사후 단계 (단독 실행 안전성 보장).
+        //
+        // CoreUpdateCommand spawn 시엔 부모 Step 11 (CoreUpdateCommand.php:457-458) 및
+        // 번들 확장 일괄 업데이트 prompt (라인 497-515) 가 자식 종료 후 실행하므로
+        // --skip-version-env / --skip-cache-clear / --skip-bundled-updates 로 중복 회피.
+        // 단독 실행 시엔 옵션 미전달 → 기본값으로 3단계 자동 수행 → gnuboard/g7#34 의 운영자 수동 절차
+        // (sed APP_VERSION + cache:clear + module/plugin/template:update --force --source=bundled) 통합.
+        if (! $this->option('skip-version-env') && ! $isSpawnChild && ! $stepsOnly) {
+            $this->info(".env APP_VERSION={$to} 갱신");
+            $service->updateVersionInEnv($to);
+        } else {
+            $this->info($stepsOnly ? '[steps-only] .env APP_VERSION 갱신 스킵' : '[spawn] .env APP_VERSION 갱신 스킵 — 부모가 처리');
+        }
+
+        if (! $this->option('skip-cache-clear') && ! $isSpawnChild && ! $stepsOnly) {
+            $this->info('캐시 정리 (config/route/view/services/packages)');
+            $service->clearAllCaches();
+            // clearAllCaches() 는 config:clear 만 하므로, 단독 실행 흐름에서는 config 캐시가
+            // 비활성 상태로 남는다. 모든 upgrade step + 번들 확장 업데이트가 config 소스를
+            // 변경했을 수 있으니, 캐시 정리 세트의 마지막에 config 캐시를 재생성한다.
+            // spawn 자식·steps-only 는 이 블록을 스킵하고 부모(CoreUpdateCommand)가 재생성한다.
+            ConfigCacheHelper::rebuild();
+            // 라우트 캐시도 같은 이유로 되살린다 — 업그레이드 스텝이나 번들 확장 업데이트가
+            // 라우트를 바꿨을 수 있고, 비운 채로 끝내면 이후 모든 요청이 라우트를 재등록한다.
+            RouteCacheHelper::rebuild();
+            // 업그레이드 스텝 단독 실행 시에도 코어 lang/routes/layout 변경이
+            // 프론트엔드 캐시 stale 로 가려지지 않도록 `ext.cache_version` bump.
+            // spawn 자식·steps-only 모드에서는 부모가 처리하므로 스킵.
+            $this->incrementExtensionCacheVersion();
+        } else {
+            $this->info($stepsOnly ? '[steps-only] 캐시 정리 스킵' : '[spawn] 캐시 정리 스킵 — 부모가 처리');
+        }
+
+        if (! $this->option('skip-bundled-updates') && ! $isSpawnChild && ! $stepsOnly) {
+            $this->info('번들 확장 일괄 업데이트 (모듈/플러그인/템플릿/언어팩)');
+            $this->runBundledExtensionUpdatePrompt(
+                app(ModuleManager::class),
+                app(PluginManager::class),
+                app(TemplateManager::class),
+                $force,
+            );
+        } else {
+            $this->info($stepsOnly ? '[steps-only] 번들 확장 일괄 업데이트 스킵' : '[spawn] 번들 확장 일괄 업데이트 스킵 — 부모가 처리');
+        }
+
+        $this->restoreUpgradeLogOwnership();
+
+        return self::SUCCESS;
+    }
+
+    /**
+     * spawn 자식이 root 로 만든 upgrade 로그 파일의 소유권을 부모(storage/logs) 로 정합합니다.
+     *
+     * upgrade step 은 sudo 코어 업데이트에서 별도 PHP 프로세스로 spawn 되며(이 커맨드),
+     * root 로 실행되어 `upgrade-YYYY-MM-DD.log`(Log::channel('upgrade')) 를 root 소유로
+     * 만든다. 부모(CoreUpdateCommand) 프로세스는 업데이트 시작 시점의 *이전 버전* 클래스를
+     * 메모리에 들고 있어, 부모 측 로그 정상화 로직이 추가돼 있어도 그 버전엔 없을 수 있다
+     * (클래스 캐싱). 반면 본 spawn 자식은 항상 *신버전* 코드로 실행되므로, upgrade 로그를
+     * 만든 주체인 자식이 자기 종료 직전에 직접 소유권을 정합하면 부모 버전과 무관하게 동작한다.
+     *
+     * 그 결과 이후 www-data(php-fpm) 의 module:update upgrade step 이 같은 날짜 upgrade
+     * 로그에 append 할 수 있다. 본 메서드는 어떤 로그도 쓰지 않는다(쓰면 다시 root 가 됨).
+     * sudo 아닌 환경에서는 silent no-op(멱등).
+     */
+    private function restoreUpgradeLogOwnership(): void
+    {
+        $logsDir = storage_path('logs');
+        if (! is_dir($logsDir)) {
+            return;
+        }
+
+        // 코어('upgrade-*.log') + 확장('extension-upgrade-*.log') 두 채널의 daily 로그를 모두
+        // 정합한다. glob 'upgrade-*.log' 는 'extension-' 접두사 파일을 매칭하지 못하므로
+        // 두 패턴을 각각 순회한다.
+        foreach (['upgrade-*.log', 'extension-upgrade-*.log'] as $pattern) {
+            foreach (glob($logsDir.DIRECTORY_SEPARATOR.$pattern) ?: [] as $logFile) {
+                FilePermissionHelper::inheritOwnershipFromParent($logFile);
+            }
+        }
+    }
+}

app/Console/Commands/ExpireIdentityChallengesCommand.php

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

app/Console/Commands/Extension/UpdateAutoloadCommand.php

@@ -3,6 +3,9 @@
 namespace App\Console\Commands\Extension;
 
 use App\Extension\ExtensionManager;
+use App\Extension\HookCacheManager;
+use App\Extension\ModuleManager;
+use App\Extension\PluginManager;
 use Illuminate\Console\Command;
 
 class UpdateAutoloadCommand extends Command
@@ -24,8 +27,12 @@ class UpdateAutoloadCommand extends Command
     /**
      * Execute the console command.
      */
-    public function handle(ExtensionManager $extensionManager): int
-    {
+    public function handle(
+        ExtensionManager $extensionManager,
+        HookCacheManager $hookCacheManager,
+        ModuleManager $moduleManager,
+        PluginManager $pluginManager,
+    ): int {
         $this->info('확장 오토로드 파일을 생성합니다...');
 
         try {
@@ -34,6 +41,22 @@ 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 매핑으로 훅 발화 누락/과잉 위험).
+            $moduleManager->loadModules();
+            $pluginManager->loadPlugins();
+            $hookCacheManager->generate($moduleManager, $pluginManager);
+
+            $this->info('정적 훅 매핑 캐시가 재생성되었습니다.');
+            $this->line('  → bootstrap/cache/hooks.php');
+
             return Command::SUCCESS;
         } catch (\Exception $e) {
             $this->error('오토로드 파일 생성 중 오류가 발생했습니다: '.$e->getMessage());

app/Console/Commands/GeoIp/UpdateGeoLiteDatabaseCommand.php

@@ -0,0 +1,102 @@
+<?php
+
+namespace App\Console\Commands\GeoIp;
+
+use App\Services\GeoIpDatabaseService;
+use Illuminate\Console\Command;
+
+/**
+ * MaxMind GeoLite2 DB 다운로드/갱신 커맨드.
+ *
+ * 모든 비즈니스 로직은 GeoIpDatabaseService에 위임합니다.
+ * 이 커맨드는 CLI 인터페이스(옵션 파싱 + 결과 출력)만 담당합니다.
+ */
+class UpdateGeoLiteDatabaseCommand extends Command
+{
+    protected $signature = 'geoip:update
+        {--force : 파일이 이미 존재해도 재다운로드}
+        {--dry-run : 실제 다운로드 없이 키/URL만 검증}';
+
+    protected $description = 'MaxMind GeoLite2-City DB를 다운로드하여 storage/app/geoip/에 배치합니다.';
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * @param  GeoIpDatabaseService  $service  GeoIP DB 관리 서비스
+     * @return int 종료 코드
+     */
+    public function handle(GeoIpDatabaseService $service): int
+    {
+        if ($this->option('dry-run')) {
+            return $this->handleDryRun($service);
+        }
+
+        $result = $service->updateDatabase((bool) $this->option('force'));
+
+        return $this->reportResult($result);
+    }
+
+    /**
+     * dry-run 모드: 라이선스 키 마스킹 후 URL만 출력합니다.
+     *
+     * @param  GeoIpDatabaseService  $service  GeoIP DB 관리 서비스
+     * @return int 종료 코드
+     */
+    private function handleDryRun(GeoIpDatabaseService $service): int
+    {
+        if (! $service->isLicenseKeyConfigured()) {
+            $this->error('MaxMind 라이선스 키가 설정되지 않았습니다.');
+            $this->line('관리자 > 환경설정 > 고급 탭에서 라이선스 키를 입력하세요.');
+
+            return Command::FAILURE;
+        }
+
+        $maskedUrl = $service->buildDownloadUrlForDisplay(true);
+        $this->info('[dry-run] 다운로드 URL 검증 완료');
+        $this->line("  URL: {$maskedUrl}");
+
+        return Command::SUCCESS;
+    }
+
+    /**
+     * Service 결과를 CLI 출력으로 변환하고 exit code를 반환합니다.
+     *
+     * @param  array<string, mixed>  $result  Service::updateDatabase() 반환값
+     * @return int 종료 코드
+     */
+    private function reportResult(array $result): int
+    {
+        $status = (string) ($result['status'] ?? '');
+        $message = (string) ($result['message'] ?? '');
+
+        if ($status === 'missing_license_key') {
+            $this->error($message);
+            $this->line('관리자 > 환경설정 > 고급 탭에서 라이선스 키를 입력하세요.');
+            $this->line('무료 발급: https://www.maxmind.com/en/geolite2/signup');
+
+            return Command::FAILURE;
+        }
+
+        if ($status === 'skipped') {
+            $this->info($message);
+
+            return Command::SUCCESS;
+        }
+
+        if ($status === 'updated') {
+            $data = $result['data'] ?? [];
+            $this->newLine();
+            $this->info('✅ '.$message);
+            $this->line(sprintf('  파일: %s', $data['database_path'] ?? '-'));
+            $this->line(sprintf('  크기: %.2f MB', (int) ($data['file_size_bytes'] ?? 0) / 1048576));
+            $this->line(sprintf('  소요 시간: %s초', $data['elapsed_seconds'] ?? '-'));
+
+            return Command::SUCCESS;
+        }
+
+        // 그 외 모든 실패 상태
+        $this->error($message !== '' ? $message : 'GeoIP DB 업데이트에 실패했습니다.');
+
+        return Command::FAILURE;
+    }
+}

app/Console/Commands/HooksCacheCommand.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Extension\HookCacheManager;
+use App\Extension\ModuleManager;
+use App\Extension\PluginManager;
+use Illuminate\Console\Command;
+
+/**
+ * 정적 훅 매핑 캐시 생성 Artisan 커맨드.
+ *
+ * 코어(app/Listeners) + 활성 모듈/플러그인의 정적 훅 리스너를 사전 계산하여
+ * bootstrap/cache/hooks.php 에 저장한다. route:cache 동형 — 코어 리스너를
+ * 추가/변경하는 코드 배포 시 배포 파이프라인에서 실행한다.
+ * (확장 install/update 시에는 ExtensionManager 가 자동 재생성하므로 수동 실행 불필요.)
+ */
+class HooksCacheCommand extends Command
+{
+    /**
+     * @var string 커맨드 시그니처
+     */
+    protected $signature = 'hooks:cache';
+
+    /**
+     * @var string 커맨드 설명
+     */
+    protected $description = '정적 훅 매핑 캐시 생성 (bootstrap/cache/hooks.php)';
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * @param  HookCacheManager  $hookCacheManager  훅 캐시 매니저
+     * @param  ModuleManager  $moduleManager  모듈 매니저
+     * @param  PluginManager  $pluginManager  플러그인 매니저
+     * @return int 종료 코드
+     */
+    public function handle(
+        HookCacheManager $hookCacheManager,
+        ModuleManager $moduleManager,
+        PluginManager $pluginManager,
+    ): int {
+        $moduleManager->loadModules();
+        $pluginManager->loadPlugins();
+
+        $counts = $hookCacheManager->generate($moduleManager, $pluginManager);
+
+        $this->info(__('hooks.cache_generated', [
+            'core' => $counts['core'],
+            'modules' => $counts['modules'],
+            'plugins' => $counts['plugins'],
+            'path' => $hookCacheManager->getCacheFilePath(),
+        ]));
+
+        return Command::SUCCESS;
+    }
+}

app/Console/Commands/HooksClearCommand.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Extension\HookCacheManager;
+use Illuminate\Console\Command;
+
+/**
+ * 정적 훅 매핑 캐시 삭제 Artisan 커맨드.
+ *
+ * bootstrap/cache/hooks.php 를 삭제한다. 캐시 삭제 후에는 부팅 시 스캔 폴백으로
+ * 동작하므로 항상 안전하다 (route:clear 동형).
+ */
+class HooksClearCommand extends Command
+{
+    /**
+     * @var string 커맨드 시그니처
+     */
+    protected $signature = 'hooks:clear';
+
+    /**
+     * @var string 커맨드 설명
+     */
+    protected $description = '정적 훅 매핑 캐시 삭제 (bootstrap/cache/hooks.php)';
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * @param  HookCacheManager  $hookCacheManager  훅 캐시 매니저
+     * @return int 종료 코드
+     */
+    public function handle(HookCacheManager $hookCacheManager): int
+    {
+        if (! $hookCacheManager->isCached()) {
+            $this->info(__('hooks.cache_absent'));
+
+            return Command::SUCCESS;
+        }
+
+        $hookCacheManager->clear();
+        $this->info(__('hooks.cache_cleared'));
+
+        return Command::SUCCESS;
+    }
+}

app/Console/Commands/Hotfix/RollbackStaleFilesCommand.php

@@ -0,0 +1,246 @@
+<?php
+
+namespace App\Console\Commands\Hotfix;
+
+use App\Console\Commands\Traits\HasUnifiedConfirm;
+use App\Extension\Helpers\CoreBackupHelper;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\File;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * 자동 롤백 후 활성 디렉토리에 잔존할 수 있는 신 버전 신규 파일을 진단/정리하는 단발성
+ * 결함 보정 도구.
+ *
+ * 결함 컨텍스트: 7.0.0-beta.5 이전의 코어 자동 롤백은 backup → 활성 overlay 복사 방식
+ * 으로만 동작하여, 신 버전이 활성 디렉토리에 새로 추가한 파일은 백업에 없으므로 삭제되지
+ * 않고 잔존했다. 결과적으로 `bootstrap/providers.php` 는 백업본(구버전) 으로 되돌아가지만
+ * 디스크에는 신 ServiceProvider 파일이 잔존하여 `BindingResolutionException` 등 부팅
+ * 부정합 발생.
+ *
+ * 도입 버전: 7.0.0-beta.6 신설.
+ *
+ * 동작:
+ *  - `--backup` 미지정 시 `storage/app/core_backups/` 의 가장 최근 백업 자동 선택
+ *  - 백업 디렉토리에 `_new_files_manifest.json` 이 있으면 그 기반으로 잔존 파일 후보 식별 (정확)
+ *  - manifest 부재 시 보수적 진단 모드 (실제 정리는 운영자 수동)
+ *  - 기본은 진단 모드 (실제 삭제 없이 후보 목록만 출력)
+ *  - `--prune` 옵션 시 확인 프롬프트 후 정리. symlink/protected_paths 가드 적용
+ *  - 정리 결과는 `storage/logs/hotfix_rollback_stale_files_<timestamp>.log` 기록
+ *
+ * @permanent — 7.0.0-beta.5 이전 사용자의 잔존 결함 회복을 위해 영구 보존. 향후 운영자가
+ *              과거 롤백 흔적을 점검할 수 있도록 유지하며, deprecation 예정 없음.
+ */
+class RollbackStaleFilesCommand extends Command
+{
+    use HasUnifiedConfirm;
+
+    protected $signature = 'hotfix:rollback-stale-files
+        {--backup= : 특정 백업 디렉토리 경로 지정 (미지정 시 가장 최근 백업 자동 선택)}
+        {--prune : 진단만이 아닌 실제 정리 수행 (확인 프롬프트 동반)}';
+
+    protected $description = '[hotfix/beta.6 신설] 코어 자동 롤백 후 활성 디렉토리에 잔존할 수 있는 신 버전 신규 파일을 진단/정리합니다.';
+
+    public function handle(): int
+    {
+        $backupPath = $this->resolveBackupPath();
+        if ($backupPath === null) {
+            $this->info('사용 가능한 백업이 없습니다 (`storage/app/core_backups/` 비어 있음).');
+
+            return Command::SUCCESS;
+        }
+
+        $this->info("백업 디렉토리: {$backupPath}");
+
+        $manifestPath = $backupPath.DIRECTORY_SEPARATOR.CoreBackupHelper::NEW_FILES_MANIFEST;
+        $manifestAvailable = File::exists($manifestPath);
+
+        if (! $manifestAvailable) {
+            $this->warn('⚠ _new_files_manifest.json 부재 — 보수적 진단 모드로 진행합니다.');
+            $this->line('  manifest 가 없으면 신 파일 vs 사용자 추가 파일을 정확히 구분할 수 없습니다.');
+            $this->line('  beta.5 이전 사용자: beta.6 업그레이드 스텝이 manifest 를 사후 작성하므로');
+            $this->line('  먼저 `php artisan core:execute-upgrade-steps --from=<버전> --to=7.0.0-beta.6 --force`');
+            $this->line('  를 실행한 뒤 본 커맨드를 재실행하는 것을 권장합니다.');
+            $this->newLine();
+        }
+
+        $candidates = $this->collectCandidates($backupPath, $manifestAvailable);
+
+        if ($candidates['files'] === [] && $candidates['dirs'] === []) {
+            $this->info('잔존 후보 없음 — 활성 디렉토리가 정상 상태입니다.');
+
+            return Command::SUCCESS;
+        }
+
+        $this->newLine();
+        $this->info(sprintf(
+            '잔존 후보: 파일 %d개, 디렉토리 %d개',
+            count($candidates['files']),
+            count($candidates['dirs']),
+        ));
+        foreach (array_slice($candidates['files'], 0, 20) as $f) {
+            $this->line("  · 파일: {$f}");
+        }
+        if (count($candidates['files']) > 20) {
+            $this->line(sprintf('  ... (총 %d건, 상위 20건만 표시)', count($candidates['files'])));
+        }
+        foreach (array_slice($candidates['dirs'], 0, 10) as $d) {
+            $this->line("  · 디렉토리: {$d}");
+        }
+        if (count($candidates['dirs']) > 10) {
+            $this->line(sprintf('  ... (총 %d건, 상위 10건만 표시)', count($candidates['dirs'])));
+        }
+
+        if (! $this->option('prune')) {
+            $this->newLine();
+            $this->info('진단 모드: 실제 삭제하지 않았습니다. 정리하려면 `--prune` 옵션을 추가하세요.');
+
+            return Command::SUCCESS;
+        }
+
+        if (! $manifestAvailable) {
+            $this->newLine();
+            $this->error('manifest 부재 상태에서는 자동 prune 을 수행하지 않습니다 (사용자 추가 파일 손실 위험).');
+            $this->line('beta.6 업그레이드 스텝을 먼저 실행하여 manifest 를 사후 작성한 뒤 재시도하세요.');
+
+            return Command::FAILURE;
+        }
+
+        $this->newLine();
+        if (! $this->unifiedConfirm('위 후보를 활성 디렉토리에서 정리하시겠습니까?', false)) {
+            $this->info('취소되었습니다.');
+
+            return Command::SUCCESS;
+        }
+
+        $protectedPaths = (array) config('app.update.protected_paths', []);
+        $result = CoreBackupHelper::pruneNewFiles($backupPath, base_path(), $protectedPaths);
+
+        $this->newLine();
+        $this->info(sprintf(
+            '정리 완료: 파일 %d개, 디렉토리 %d개 제거. 보호 %d건, symlink skip %d건, 실패 %d건.',
+            $result['removed_files'],
+            $result['removed_dirs'],
+            $result['protected_count'],
+            $result['symlink_skipped'],
+            $result['failed_count'],
+        ));
+
+        $logPath = storage_path(sprintf(
+            'logs/hotfix_rollback_stale_files_%s.log',
+            date('Ymd_His'),
+        ));
+        @file_put_contents($logPath, $this->buildLogEntry($backupPath, $result, $candidates));
+        $this->line("로그: {$logPath}");
+
+        Log::info('hotfix:rollback-stale-files 정리 완료', [
+            'backup_path' => $backupPath,
+            'result' => $result,
+        ]);
+
+        return Command::SUCCESS;
+    }
+
+    /**
+     * `--backup` 옵션 또는 가장 최근 백업 디렉토리 경로를 반환.
+     */
+    private function resolveBackupPath(): ?string
+    {
+        $explicit = $this->option('backup');
+        if ($explicit !== null && $explicit !== '') {
+            $real = realpath($explicit);
+            if ($real === false || ! is_dir($real)) {
+                $this->error("지정된 백업 디렉토리가 존재하지 않습니다: {$explicit}");
+
+                return null;
+            }
+
+            return $real;
+        }
+
+        $backups = CoreBackupHelper::listBackups();
+        if ($backups === []) {
+            return null;
+        }
+        // listBackups 는 정렬 보장이 약하므로 mtime 기준으로 다시 정렬
+        usort($backups, fn ($a, $b) => filemtime($b['path']) <=> filemtime($a['path']));
+
+        return $backups[0]['path'] ?? null;
+    }
+
+    /**
+     * 잔존 후보 식별 — manifest 가 있으면 그 기반, 부재 시 빈 배열 반환 (운영자 수동 검토 안내).
+     *
+     * @return array{files:array<int,string>, dirs:array<int,string>}
+     */
+    private function collectCandidates(string $backupPath, bool $manifestAvailable): array
+    {
+        if (! $manifestAvailable) {
+            return ['files' => [], 'dirs' => []];
+        }
+
+        $manifestPath = $backupPath.DIRECTORY_SEPARATOR.CoreBackupHelper::NEW_FILES_MANIFEST;
+        $raw = @file_get_contents($manifestPath);
+        if ($raw === false) {
+            return ['files' => [], 'dirs' => []];
+        }
+
+        $manifest = json_decode($raw, true);
+        if (! is_array($manifest)) {
+            return ['files' => [], 'dirs' => []];
+        }
+
+        $files = [];
+        foreach ((array) ($manifest['new_files'] ?? []) as $rel) {
+            if (! is_string($rel) || $rel === '') {
+                continue;
+            }
+            $absolute = base_path($rel);
+            if (file_exists($absolute) || is_link($absolute)) {
+                $files[] = $rel;
+            }
+        }
+
+        $dirs = [];
+        foreach ((array) ($manifest['new_dirs'] ?? []) as $rel) {
+            if (! is_string($rel) || $rel === '') {
+                continue;
+            }
+            $absolute = base_path($rel);
+            if (is_dir($absolute) && ! is_link($absolute)) {
+                $dirs[] = $rel;
+            }
+        }
+
+        return ['files' => $files, 'dirs' => $dirs];
+    }
+
+    /**
+     * 진단/정리 결과를 로그 텍스트로 빌드.
+     */
+    private function buildLogEntry(string $backupPath, array $result, array $candidates): string
+    {
+        $lines = [
+            '=== hotfix:rollback-stale-files 실행 로그 ===',
+            '날짜: '.date('Y-m-d H:i:s'),
+            "백업 디렉토리: {$backupPath}",
+            '',
+            '결과:',
+            sprintf('  파일 제거: %d', $result['removed_files']),
+            sprintf('  디렉토리 제거: %d', $result['removed_dirs']),
+            sprintf('  보호 경로 skip: %d', $result['protected_count']),
+            sprintf('  symlink skip: %d', $result['symlink_skipped']),
+            sprintf('  실패: %d', $result['failed_count']),
+            '',
+            '후보 목록 (실행 직전 스냅샷):',
+        ];
+        foreach ($candidates['files'] as $f) {
+            $lines[] = "  · 파일: {$f}";
+        }
+        foreach ($candidates['dirs'] as $d) {
+            $lines[] = "  · 디렉토리: {$d}";
+        }
+
+        return implode("\n", $lines)."\n";
+    }
+}

app/Console/Commands/LanguagePack/ActivateLanguagePackCommand.php

@@ -0,0 +1,66 @@
+<?php
+
+namespace App\Console\Commands\LanguagePack;
+
+use App\Services\LanguagePackService;
+use Illuminate\Console\Command;
+use Throwable;
+
+/**
+ * 언어팩을 활성화합니다.
+ *
+ * 모듈/플러그인/템플릿의 activate 커맨드와 동일한 운영 도구.
+ * 동일 슬롯의 다른 활성 팩은 자동으로 inactive 로 전환됩니다.
+ */
+class ActivateLanguagePackCommand extends Command
+{
+    /**
+     * @var string
+     */
+    protected $signature = 'language-pack:activate
+        {identifier : 언어팩 식별자}
+        {--force : 의존성/검증 경고를 무시하고 강제 활성화}';
+
+    /**
+     * @var string
+     */
+    protected $description = '언어팩을 활성화합니다.';
+
+    /**
+     * @param  LanguagePackService  $service  언어팩 Service
+     */
+    public function __construct(
+        private readonly LanguagePackService $service,
+    ) {
+        parent::__construct();
+    }
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * @return int 종료 코드
+     */
+    public function handle(): int
+    {
+        $identifier = (string) $this->argument('identifier');
+        $force = (bool) $this->option('force');
+
+        $pack = $this->service->findByIdentifier($identifier);
+        if (! $pack) {
+            $this->error("언어팩을 찾을 수 없습니다: {$identifier}");
+
+            return self::FAILURE;
+        }
+
+        try {
+            $this->service->activate($pack, $force);
+            $this->info("언어팩 활성화 완료: {$identifier}");
+
+            return self::SUCCESS;
+        } catch (Throwable $e) {
+            $this->error('언어팩 활성화 실패: '.$e->getMessage());
+
+            return self::FAILURE;
+        }
+    }
+}

app/Console/Commands/LanguagePack/CacheClearLanguagePackCommand.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace App\Console\Commands\LanguagePack;
+
+use App\Services\LanguagePackService;
+use Illuminate\Console\Command;
+use Throwable;
+
+/**
+ * 언어팩 관련 캐시(레지스트리/Translator/템플릿/버전 스탬프)를 정리합니다.
+ *
+ * 모듈/플러그인/템플릿의 cache-clear 커맨드와 동일한 운영 도구.
+ * _bundled 의 다국어 파일을 손으로 수정한 뒤 즉시 반영하려는 운영 시나리오에 사용합니다.
+ */
+class CacheClearLanguagePackCommand extends Command
+{
+    /**
+     * @var string
+     */
+    protected $signature = 'language-pack:cache-clear';
+
+    /**
+     * @var string
+     */
+    protected $description = '언어팩 캐시(registry/translator/template/version)를 정리합니다.';
+
+    /**
+     * @param  LanguagePackService  $service  언어팩 Service
+     */
+    public function __construct(
+        private readonly LanguagePackService $service,
+    ) {
+        parent::__construct();
+    }
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * @return int 종료 코드
+     */
+    public function handle(): int
+    {
+        try {
+            $result = $this->service->refreshCache();
+            $this->info('언어팩 캐시 정리 완료:');
+            foreach ($result as $key => $ok) {
+                $this->line('  - '.$key.': '.($ok ? 'ok' : 'failed'));
+            }
+
+            return collect($result)->every(fn ($v) => $v === true) ? self::SUCCESS : self::FAILURE;
+        } catch (Throwable $e) {
+            $this->error('언어팩 캐시 정리 실패: '.$e->getMessage());
+
+            return self::FAILURE;
+        }
+    }
+}

app/Console/Commands/LanguagePack/CheckLanguagePackUpdatesCommand.php

@@ -0,0 +1,86 @@
+<?php
+
+namespace App\Console\Commands\LanguagePack;
+
+use App\Services\LanguagePackService;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Log;
+use Throwable;
+
+/**
+ * GitHub 으로 설치된 언어팩의 최신 릴리스 버전을 확인하여 `latest_version` 컬럼을 갱신합니다.
+ *
+ * 관리 UI 에서 "업데이트 가능" 배지 노출에 사용되며, 스케줄러에서 주기적으로 실행됩니다.
+ */
+class CheckLanguagePackUpdatesCommand extends Command
+{
+    /**
+     * @var string
+     */
+    protected $signature = 'language-pack:check-updates {--identifier= : 특정 언어팩만 확인 (선택)}';
+
+    /**
+     * @var string
+     */
+    protected $description = '설치된 언어팩의 GitHub 업데이트를 확인합니다.';
+
+    /**
+     * @param  LanguagePackService  $service  언어팩 Service (실제 로직 SSoT)
+     */
+    public function __construct(
+        private readonly LanguagePackService $service,
+    ) {
+        parent::__construct();
+    }
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * 실제 갱신 로직은 LanguagePackService::checkUpdates() 에 위임합니다.
+     *
+     * @return int 종료 코드 (0=성공, 1=실패)
+     */
+    public function handle(): int
+    {
+        $identifier = $this->option('identifier');
+
+        try {
+            $result = $this->service->checkUpdates($identifier);
+
+            if ($result['checked'] === 0) {
+                $this->info('확인할 GitHub 기반 언어팩이 없습니다.');
+
+                return Command::SUCCESS;
+            }
+
+            foreach ($result['details'] as $entry) {
+                if ($entry['error']) {
+                    $this->warn(sprintf('  [%s] 조회 실패: %s', $entry['identifier'], $entry['error']));
+
+                    continue;
+                }
+
+                $line = sprintf(
+                    '  [%s] %s → %s%s',
+                    $entry['identifier'],
+                    $entry['current'],
+                    $entry['latest'] ?? '?',
+                    $entry['has_update'] ? '  (업데이트 가능)' : '',
+                );
+                $this->line($line);
+            }
+
+            $this->info(sprintf('확인 완료: %d 건 검사, %d 건 업데이트 가능.', $result['checked'], $result['updates']));
+
+            return Command::SUCCESS;
+        } catch (Throwable $e) {
+            $this->error('업데이트 확인 실패: '.$e->getMessage());
+            Log::error('language-pack:check-updates 실패', [
+                'identifier' => $identifier,
+                'error' => $e->getMessage(),
+            ]);
+
+            return Command::FAILURE;
+        }
+    }
+}

app/Console/Commands/LanguagePack/DeactivateLanguagePackCommand.php

@@ -0,0 +1,64 @@
+<?php
+
+namespace App\Console\Commands\LanguagePack;
+
+use App\Services\LanguagePackService;
+use Illuminate\Console\Command;
+use Throwable;
+
+/**
+ * 언어팩을 비활성화합니다.
+ *
+ * 모듈/플러그인/템플릿의 deactivate 커맨드와 동일한 운영 도구.
+ * 보호된 팩(is_protected=true)은 거부되며, 호스트 cascade 컨텍스트에서만 우회됩니다.
+ */
+class DeactivateLanguagePackCommand extends Command
+{
+    /**
+     * @var string
+     */
+    protected $signature = 'language-pack:deactivate
+        {identifier : 언어팩 식별자}';
+
+    /**
+     * @var string
+     */
+    protected $description = '언어팩을 비활성화합니다.';
+
+    /**
+     * @param  LanguagePackService  $service  언어팩 Service
+     */
+    public function __construct(
+        private readonly LanguagePackService $service,
+    ) {
+        parent::__construct();
+    }
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * @return int 종료 코드
+     */
+    public function handle(): int
+    {
+        $identifier = (string) $this->argument('identifier');
+
+        $pack = $this->service->findByIdentifier($identifier);
+        if (! $pack) {
+            $this->error("언어팩을 찾을 수 없습니다: {$identifier}");
+
+            return self::FAILURE;
+        }
+
+        try {
+            $this->service->deactivate($pack);
+            $this->info("언어팩 비활성화 완료: {$identifier}");
+
+            return self::SUCCESS;
+        } catch (Throwable $e) {
+            $this->error('언어팩 비활성화 실패: '.$e->getMessage());
+
+            return self::FAILURE;
+        }
+    }
+}

app/Console/Commands/LanguagePack/InstallLanguagePackCommand.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace App\Console\Commands\LanguagePack;
+
+use App\Services\LanguagePackService;
+use Illuminate\Console\Command;
+use Throwable;
+
+/**
+ * 번들/GitHub/URL 소스에서 언어팩을 설치합니다.
+ *
+ * 모듈/플러그인/템플릿의 install 커맨드와 동일한 운영 도구.
+ * `--source=bundled` 시 `lang-packs/_bundled/{identifier}` 디렉토리에서 설치하며,
+ * 외부 다운로드 없이 코어 언어팩의 (재)설치/복구가 가능합니다.
+ */
+class InstallLanguagePackCommand extends Command
+{
+    /**
+     * @var string
+     */
+    protected $signature = 'language-pack:install
+        {identifier : 번들 식별자 또는 소스에 따른 식별자/URL}
+        {--source=bundled : 설치 소스 (bundled|github|url)}
+        {--no-activate : 설치 후 자동 활성화하지 않음}';
+
+    /**
+     * @var string
+     */
+    protected $description = '번들/GitHub/URL 소스에서 언어팩을 설치합니다.';
+
+    /**
+     * @param  LanguagePackService  $service  언어팩 Service
+     */
+    public function __construct(
+        private readonly LanguagePackService $service,
+    ) {
+        parent::__construct();
+    }
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * @return int 종료 코드
+     */
+    public function handle(): int
+    {
+        $identifier = (string) $this->argument('identifier');
+        $source = (string) $this->option('source');
+        $autoActivate = ! (bool) $this->option('no-activate');
+
+        try {
+            $pack = match ($source) {
+                'bundled' => $this->service->installFromBundled($identifier, $autoActivate),
+                'github' => $this->service->installFromGithub($identifier, $autoActivate),
+                'url' => $this->service->installFromUrl($identifier, null, $autoActivate),
+                default => throw new \InvalidArgumentException(
+                    __('language_packs.errors.unsupported_source', ['source' => $source])
+                ),
+            };
+
+            $this->info(sprintf(
+                '언어팩 설치 완료: %s v%s (status=%s)',
+                $pack->identifier,
+                $pack->version,
+                $pack->status,
+            ));
+
+            return self::SUCCESS;
+        } catch (Throwable $e) {
+            $this->error('언어팩 설치 실패: '.$e->getMessage());
+
+            return self::FAILURE;
+        }
+    }
+}

app/Console/Commands/LanguagePack/ListLanguagePackCommand.php

@@ -0,0 +1,93 @@
+<?php
+
+namespace App\Console\Commands\LanguagePack;
+
+use App\Models\LanguagePack;
+use App\Services\LanguagePackService;
+use Illuminate\Console\Command;
+
+/**
+ * 언어팩 목록을 출력합니다.
+ *
+ * 모듈/플러그인/템플릿의 list 커맨드와 동일한 운영 도구. Service::list() 를 경유하므로
+ * 설치된 DB 행뿐 아니라 "번들에 있으나 미설치"(uninstalled) 및 "active 로 기록됐으나
+ * 설치본 파일 부재(드리프트)" 상태를 함께 표면화한다(이슈 #496).
+ */
+class ListLanguagePackCommand extends Command
+{
+    /**
+     * @var string
+     */
+    protected $signature = 'language-pack:list {--scope= : 특정 스코프만 (core/module/plugin/template)}';
+
+    /**
+     * @var string
+     */
+    protected $description = '언어팩 목록을 출력합니다 (미설치 번들 및 드리프트 상태 포함).';
+
+    /**
+     * @param  LanguagePackService  $service  언어팩 Service
+     */
+    public function __construct(
+        private readonly LanguagePackService $service,
+    ) {
+        parent::__construct();
+    }
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * @return int 종료 코드
+     */
+    public function handle(): int
+    {
+        $filters = [];
+        if ($scope = $this->option('scope')) {
+            $filters['scope'] = $scope;
+        }
+
+        $paginator = $this->service->list($filters, 100);
+        $packs = $paginator->items();
+
+        if (empty($packs)) {
+            $this->info('언어팩이 없습니다.');
+
+            return self::SUCCESS;
+        }
+
+        $rows = [];
+        foreach ($packs as $pack) {
+            $rows[] = [
+                $pack->identifier,
+                $pack->scope,
+                $pack->target_identifier ?? '-',
+                $pack->locale,
+                $pack->vendor,
+                $pack->version,
+                $this->formatStatus($pack),
+            ];
+        }
+
+        $this->table(
+            ['Identifier', 'Scope', 'Target', 'Locale', 'Vendor', 'Version', 'Status'],
+            $rows
+        );
+
+        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;
+    }
+}

app/Console/Commands/LanguagePack/ProvisionLanguagePackCommand.php

@@ -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),
+        )));
+    }
+}

app/Console/Commands/LanguagePack/UninstallLanguagePackCommand.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace App\Console\Commands\LanguagePack;
+
+use App\Console\Commands\Traits\HasUnifiedConfirm;
+use App\Services\LanguagePackService;
+use Illuminate\Console\Command;
+use Throwable;
+
+/**
+ * 언어팩을 제거합니다.
+ *
+ * 모듈/플러그인/템플릿의 uninstall 커맨드와 동일한 운영 도구.
+ * 보호된 팩(`is_protected=true`)은 차단되며, `--force` 없이는 yes/no 확인을 요구합니다.
+ */
+class UninstallLanguagePackCommand extends Command
+{
+    use HasUnifiedConfirm;
+
+    /**
+     * @var string
+     */
+    protected $signature = 'language-pack:uninstall
+        {identifier : 언어팩 식별자}
+        {--cascade : 코어 팩 제거 시 동일 locale 의 module/plugin/template 팩도 inactive 로 강등}
+        {--force : 확인 없이 즉시 제거}';
+
+    /**
+     * @var string
+     */
+    protected $description = '언어팩을 제거합니다.';
+
+    /**
+     * @param  LanguagePackService  $service  언어팩 Service
+     */
+    public function __construct(
+        private readonly LanguagePackService $service,
+    ) {
+        parent::__construct();
+    }
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * @return int 종료 코드
+     */
+    public function handle(): int
+    {
+        $identifier = (string) $this->argument('identifier');
+        $cascade = (bool) $this->option('cascade');
+        $force = (bool) $this->option('force');
+
+        $pack = $this->service->findByIdentifier($identifier);
+        if (! $pack) {
+            $this->error("언어팩을 찾을 수 없습니다: {$identifier}");
+
+            return self::FAILURE;
+        }
+
+        if (! $force && ! $this->unifiedConfirm("언어팩 '{$identifier}' 을(를) 제거하시겠습니까?", false)) {
+            $this->info('취소되었습니다.');
+
+            return self::SUCCESS;
+        }
+
+        try {
+            $this->service->uninstall($pack, $cascade);
+            $this->info("언어팩 제거 완료: {$identifier}");
+
+            return self::SUCCESS;
+        } catch (Throwable $e) {
+            $this->error('언어팩 제거 실패: '.$e->getMessage());
+
+            return self::FAILURE;
+        }
+    }
+}

app/Console/Commands/LanguagePack/UpdateLanguagePackCommand.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace App\Console\Commands\LanguagePack;
+
+use App\Services\LanguagePackService;
+use Illuminate\Console\Command;
+use Throwable;
+
+/**
+ * 언어팩을 업데이트합니다.
+ *
+ * 모듈/플러그인/템플릿의 update 커맨드와 동일한 운영 도구.
+ * 동시성 가드 + 백업 + 롤백은 Service 의 performUpdate 가 담당합니다.
+ *
+ * 옵션:
+ *  --force                       버전이 동일해도 강제 재적용 (확장 update --force 와 동일 의미)
+ *  --source=auto|bundled|github  업데이트 소스 우선순위. auto(기본): force 시 bundled, 외 GitHub
+ */
+class UpdateLanguagePackCommand extends Command
+{
+    /**
+     * @var string
+     */
+    protected $signature = 'language-pack:update
+        {identifier : 언어팩 식별자}
+        {--force : 버전 변경이 없어도 강제 재적용 (_bundled 우선)}
+        {--source=auto : 업데이트 소스 (auto|bundled|github)}';
+
+    /**
+     * @var string
+     */
+    protected $description = '언어팩을 GitHub 또는 _bundled 신버전으로 업데이트합니다.';
+
+    /**
+     * @param  LanguagePackService  $service  언어팩 Service
+     */
+    public function __construct(
+        private readonly LanguagePackService $service,
+    ) {
+        parent::__construct();
+    }
+
+    /**
+     * 커맨드를 실행합니다.
+     *
+     * @return int 종료 코드
+     */
+    public function handle(): int
+    {
+        $identifier = (string) $this->argument('identifier');
+        $force = (bool) $this->option('force');
+        $source = (string) $this->option('source');
+
+        if (! in_array($source, ['auto', 'bundled', 'github'], true)) {
+            $this->error("알 수 없는 --source 값: {$source} (auto|bundled|github 중 선택)");
+
+            return self::FAILURE;
+        }
+
+        $pack = $this->service->findByIdentifier($identifier);
+        if (! $pack) {
+            $this->error("언어팩을 찾을 수 없습니다: {$identifier}");
+
+            return self::FAILURE;
+        }
+
+        try {
+            $fromVersion = $pack->version;
+            // source=bundled 는 force 와 동등 (bundled 1순위 강제). source=github 는 force 무시.
+            $effectiveForce = $force || $source === 'bundled';
+            $updated = $this->service->performUpdate($pack, $effectiveForce);
+
+            $this->info(sprintf(
+                '언어팩 업데이트 완료: %s (%s → %s)',
+                $updated->identifier,
+                $fromVersion,
+                $updated->version,
+            ));
+
+            return self::SUCCESS;
+        } catch (Throwable $e) {
+            $this->error('언어팩 업데이트 실패: '.$e->getMessage());
+
+            return self::FAILURE;
+        }
+    }
+}

app/Console/Commands/MigrateSettingsToJsonCommand.php

@@ -2,6 +2,7 @@
 
 namespace App\Console\Commands;
 
+use App\Console\Commands\Traits\HasUnifiedConfirm;
 use App\Models\SystemConfig;
 use App\Repositories\JsonConfigRepository;
 use Illuminate\Console\Command;
@@ -12,6 +13,8 @@ use Illuminate\Support\Facades\Schema;
  */
 class MigrateSettingsToJsonCommand extends Command
 {
+    use HasUnifiedConfirm;
+
     /**
      * 커맨드 시그니처
      *
@@ -93,6 +96,8 @@ class MigrateSettingsToJsonCommand extends Command
         'debug_mode' => 'debug',
         'sql_query_log' => 'debug',
         'log_level' => 'debug',
+        'outbound_proxy' => 'debug',
+        'outbound_proxy_bypass' => 'debug',
     ];
 
     /**
@@ -122,8 +127,6 @@ class MigrateSettingsToJsonCommand extends Command
      * 커맨드를 실행합니다.
      *
      * DI 컨테이너 바인딩 시점 문제로 직접 인스턴스화합니다.
-     *
-     * @return int
      */
     public function handle(): int
     {
@@ -133,7 +136,7 @@ class MigrateSettingsToJsonCommand extends Command
         if (! Schema::hasTable('system_configs')) {
             $this->warn('system_configs 테이블이 존재하지 않습니다. 기본값으로 초기화합니다.');
 
-            $configRepository = new JsonConfigRepository();
+            $configRepository = new JsonConfigRepository;
             $configRepository->initialize();
 
             $this->info('기본 설정 파일이 생성되었습니다.');
@@ -142,11 +145,11 @@ class MigrateSettingsToJsonCommand extends Command
         }
 
         // JsonConfigRepository 직접 인스턴스화 (DI 컨테이너 바인딩 전 실행 가능)
-        $configRepository = new JsonConfigRepository();
+        $configRepository = new JsonConfigRepository;
 
         // 기존 JSON 파일 존재 확인
         if (file_exists(storage_path('app/settings/general.json')) && ! $this->option('force')) {
-            if (! $this->confirm('기존 JSON 설정 파일이 존재합니다. 덮어쓰시겠습니까?')) {
+            if (! $this->unifiedConfirm('기존 JSON 설정 파일이 존재합니다. 덮어쓰시겠습니까?', false)) {
                 $this->info('마이그레이션이 취소되었습니다.');
 
                 return Command::SUCCESS;
@@ -196,10 +199,6 @@ class MigrateSettingsToJsonCommand extends Command
 
     /**
      * 문자열 값을 원래 타입으로 파싱합니다.
-     *
-     * @param string $value
-     * @param string $type
-     * @return mixed
      */
     private function parseValue(string $value, string $type): mixed
     {

app/Console/Commands/Module/BuildModuleCommand.php

@@ -4,6 +4,7 @@ namespace App\Console\Commands\Module;
 
 use App\Extension\ModuleManager;
 use App\Extension\Traits\ClearsTemplateCaches;
+use App\Extension\Traits\GeneratesComponentManifest;
 use Illuminate\Console\Command;
 use Illuminate\Support\Facades\Log;
 use Symfony\Component\Process\Process;
@@ -11,6 +12,7 @@ use Symfony\Component\Process\Process;
 class BuildModuleCommand extends Command
 {
     use ClearsTemplateCaches;
+    use GeneratesComponentManifest;
 
     /**
      * The name and signature of the console command.
@@ -187,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}");
@@ -196,6 +203,14 @@ class BuildModuleCommand extends Command
             // 빌드 결과 파일 확인
             $this->displayBuildResults($buildPath, $identifier);
 
+            // 편집기 컴포넌트 매니페스트(components.json) 생성
+            $manifestResult = $this->generateComponentManifest($buildPath, $identifier);
+            if ($manifestResult['written']) {
+                $this->line("   - components.json 생성됨 (컴포넌트 {$manifestResult['count']}개)");
+            } else {
+                $this->warn('   - components.json 생성 실패 (편집 모드 컨트롤 노출 제한)');
+            }
+
             // 캐시 버전 증가 (브라우저 캐시 무효화)
             $this->incrementExtensionCacheVersion();
             $this->line('   - 캐시 버전 갱신됨');
@@ -328,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') {
@@ -345,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) {

app/Console/Commands/Module/CheckModuleUpdatesCommand.php

@@ -116,7 +116,7 @@ class CheckModuleUpdatesCommand extends Command
         $updateCount = 0;
 
         foreach ($result['details'] as $detail) {
-            $isUpdate = $detail['update_available'] ?? false;
+            $isUpdate = (bool) ($detail['update_available'] ?? true);
             if ($isUpdate) {
                 $updateCount++;
             }
@@ -143,7 +143,7 @@ class CheckModuleUpdatesCommand extends Command
         $this->table($headers, $tableData);
         $this->newLine();
         $this->info(__('modules.commands.check_updates.summary', [
-            'total' => count($result['details']),
+            'total' => $result['checked_count'] ?? count($result['details']),
             'updates' => $updateCount,
         ]));
 

app/Console/Commands/Module/ClearModuleCacheCommand.php

@@ -2,14 +2,22 @@
 
 namespace App\Console\Commands\Module;
 
-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\Cache;
 use Illuminate\Support\Facades\Log;
 
 class ClearModuleCacheCommand extends Command
 {
+    use ClearsTemplateCaches;
+    use InvalidatesLayoutCache;
+
     /**
      * The name and signature of the console command.
      */
@@ -26,13 +34,19 @@ class ClearModuleCacheCommand extends Command
      */
     public function __construct(
         private ModuleManager $moduleManager,
-        private ModuleRepositoryInterface $moduleRepository
+        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
     {
@@ -58,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,
@@ -66,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 (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]));
             }
 
@@ -107,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 (Cache::forget($key)) {
-                $clearedCount++;
-            }
-        }
-
-        return $clearedCount;
+        return $this->layoutRepository
+            ->getBySourceIdentifier($identifier, LayoutSourceType::Module)
+            ->count();
     }
 }

app/Console/Commands/Module/InstallModuleCommand.php

@@ -3,9 +3,11 @@
 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;
+use App\Extension\Vendor\VendorMode;
 use App\Models\Menu;
 use App\Models\Permission;
 use App\Rules\ValidExtensionIdentifier;
@@ -16,11 +18,16 @@ use Illuminate\Support\Facades\Validator;
 class InstallModuleCommand extends Command
 {
     use HasProgressBar;
+    use RebuildsSearchIndex;
 
     /**
      * The name and signature of the console command.
      */
-    protected $signature = 'module:install {identifier : 설치할 모듈 식별자}';
+    protected $signature = 'module:install
+        {identifier : 설치할 모듈 식별자}
+        {--vendor-mode=auto : Vendor 설치 모드 (auto|composer|bundled)}
+        {--force : 이미 설치된 경우에도 _bundled/_pending 원본으로 활성 디렉토리를 덮어쓰고 재설치 (불완전 설치 복구)}
+        {--rebuild-search-index : 완료 후 색인이 누락된 검색 인덱스를 재생성 (인덱스가 잠기거나 재색인됩니다 — 운영 중에는 유지보수 시간에 수행하세요)}';
 
     /**
      * The console command description.
@@ -56,22 +63,29 @@ class InstallModuleCommand extends Command
             return Command::FAILURE;
         }
 
+        $force = (bool) $this->option('force');
+
         try {
             // 모듈 디렉토리 스캔 및 로드
             $this->moduleManager->loadModules();
 
-            // 이미 설치된 모듈인지 확인
+            // 이미 설치된 모듈인지 확인 (force 시 스킵하여 재설치/복구 허용)
             $existingModule = $this->moduleRepository->findByIdentifier($identifier);
-            if ($existingModule) {
+            if ($existingModule && ! $force) {
                 $this->warn('⚠️  '.__('modules.commands.install.already_installed', ['module' => $identifier]));
 
                 return Command::FAILURE;
             }
 
+            if ($existingModule && $force) {
+                $this->warn('⚠️  '.__('modules.commands.install.force_reinstall', ['module' => $identifier]));
+            }
+
             // 모듈 설치
+            $vendorMode = VendorMode::fromStringOrAuto((string) $this->option('vendor-mode'));
             $onProgress = $this->createProgressCallback(ModuleManager::INSTALL_STEPS);
             try {
-                $result = $this->moduleManager->installModule($identifier, $onProgress);
+                $result = $this->moduleManager->installModule($identifier, $onProgress, $vendorMode, $force);
                 $this->finishProgress();
             } catch (\Exception $e) {
                 $this->finishProgress();
@@ -103,6 +117,9 @@ class InstallModuleCommand extends Command
 
                 Log::info(__('modules.commands.install.success', ['module' => $identifier]));
 
+                // 검색 인덱스 재생성은 운영자가 선택했을 때만 수행한다 (인덱스 잠금·재색인 비용)
+                $this->handleSearchIndexRebuild();
+
                 return Command::SUCCESS;
             }
 

app/Console/Commands/Module/ListModuleCommand.php

@@ -13,7 +13,8 @@ class ListModuleCommand extends Command
      * The name and signature of the console command.
      */
     protected $signature = 'module:list
-        {--status= : 상태로 필터 (installed, uninstalled, active, inactive)}';
+        {--status= : 상태로 필터 (installed, uninstalled, active, inactive)}
+        {--hidden : 숨김(hidden=true) 모듈도 함께 출력}';
 
     /**
      * The console command description.
@@ -39,6 +40,7 @@ class ListModuleCommand extends Command
         $this->moduleManager->loadModules();
 
         $statusFilter = $this->option('status');
+        $includeHidden = (bool) $this->option('hidden');
 
         // 상태 필터 검증
         if ($statusFilter && ! in_array($statusFilter, ['installed', 'uninstalled', 'active', 'inactive'])) {
@@ -58,6 +60,11 @@ class ListModuleCommand extends Command
 
         // 설치된 모듈 추가
         foreach ($installedModules as $identifier => $module) {
+            // 숨김 필터: --hidden 미지정 시 hidden=true 모듈 제외
+            if (! $includeHidden && ! empty($module['hidden'])) {
+                continue;
+            }
+
             // 상태 필터
             if ($statusFilter) {
                 if ($statusFilter === 'uninstalled') {
@@ -86,6 +93,11 @@ class ListModuleCommand extends Command
         // 미설치 모듈 추가
         if (! $statusFilter || $statusFilter === 'uninstalled') {
             foreach ($uninstalledModules as $identifier => $module) {
+                // 숨김 필터: --hidden 미지정 시 hidden=true 모듈 제외
+                if (! $includeHidden && ! empty($module['hidden'])) {
+                    continue;
+                }
+
                 // 상태 필터 (uninstalled 또는 필터 없음)
                 if ($statusFilter && $statusFilter !== 'uninstalled') {
                     continue;

app/Console/Commands/Module/ModuleVendorBundleCommand.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace App\Console\Commands\Module;
+
+use App\Console\Commands\Vendor\Concerns\RunsVendorBundleAction;
+use App\Extension\Vendor\VendorBundler;
+use Illuminate\Console\Command;
+
+/**
+ * 모듈 vendor/ 디렉토리를 vendor-bundle.zip 으로 빌드합니다.
+ *
+ * 기존 module:build 패턴과 동일하게 positional identifier + --all 옵션 지원.
+ */
+class ModuleVendorBundleCommand extends Command
+{
+    use RunsVendorBundleAction;
+
+    protected $signature = 'module:vendor-bundle
+                            {identifier? : 빌드할 모듈 식별자 (생략 시 --all 필요)}
+                            {--all : 모든 _bundled 모듈 빌드}
+                            {--force : 해시 체크 무시, 강제 재빌드}
+                            {--check : 실제 빌드 없이 stale 여부만 확인}';
+
+    protected $description = '모듈 vendor/ 디렉토리를 vendor-bundle.zip 으로 빌드합니다 (공유 호스팅용)';
+
+    public function handle(VendorBundler $bundler): int
+    {
+        $identifier = $this->argument('identifier');
+        $all = (bool) $this->option('all');
+
+        if (! $identifier && ! $all) {
+            $this->error('식별자 또는 --all 옵션을 지정해야 합니다.');
+            $this->line('사용법:');
+            $this->line('  php artisan module:vendor-bundle sirsoft-ecommerce');
+            $this->line('  php artisan module:vendor-bundle --all');
+
+            return self::FAILURE;
+        }
+
+        $targets = [];
+        if ($all) {
+            foreach ($this->discoverBundledIdentifiers('module') as $id) {
+                $targets[] = ['type' => 'module', 'identifier' => $id];
+            }
+        } else {
+            $targets[] = ['type' => 'module', 'identifier' => $identifier];
+        }
+
+        return $this->runBuildAction(
+            $bundler,
+            $targets,
+            (bool) $this->option('force'),
+            (bool) $this->option('check'),
+        );
+    }
+}

app/Console/Commands/Module/ModuleVendorVerifyCommand.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace App\Console\Commands\Module;
+
+use App\Console\Commands\Vendor\Concerns\RunsVendorBundleAction;
+use App\Extension\Vendor\VendorIntegrityChecker;
+use Illuminate\Console\Command;
+
+/**
+ * 모듈 vendor-bundle.zip 무결성을 검증합니다.
+ */
+class ModuleVendorVerifyCommand extends Command
+{
+    use RunsVendorBundleAction;
+
+    protected $signature = 'module:vendor-verify
+                            {identifier? : 검증할 모듈 식별자 (생략 시 --all 필요)}
+                            {--all : 모든 _bundled 모듈 검증}';
+
+    protected $description = '모듈 vendor-bundle.zip 의 SHA256 무결성을 검증합니다';
+
+    public function handle(VendorIntegrityChecker $checker): int
+    {
+        $identifier = $this->argument('identifier');
+        $all = (bool) $this->option('all');
+
+        if (! $identifier && ! $all) {
+            $this->error('식별자 또는 --all 옵션을 지정해야 합니다.');
+
+            return self::FAILURE;
+        }
+
+        $targets = [];
+        if ($all) {
+            foreach ($this->discoverBundledIdentifiers('module') as $id) {
+                $targets[] = ['type' => 'module', 'identifier' => $id];
+            }
+        } else {
+            $targets[] = ['type' => 'module', 'identifier' => $identifier];
+        }
+
+        return $this->runVerifyAction($checker, $targets);
+    }
+}

app/Console/Commands/Module/UninstallModuleCommand.php

@@ -3,6 +3,7 @@
 namespace App\Console\Commands\Module;
 
 use App\Console\Commands\Traits\HasProgressBar;
+use App\Console\Commands\Traits\HasUnifiedConfirm;
 use App\Contracts\Repositories\ModuleRepositoryInterface;
 use App\Enums\ExtensionOwnerType;
 use App\Extension\ModuleManager;
@@ -14,6 +15,7 @@ use Illuminate\Support\Facades\Log;
 class UninstallModuleCommand extends Command
 {
     use HasProgressBar;
+    use HasUnifiedConfirm;
 
     /**
      * The name and signature of the console command.
@@ -82,7 +84,7 @@ class UninstallModuleCommand extends Command
                 }
                 $this->newLine();
 
-                if (! $this->confirm(__('modules.commands.uninstall.confirm_question'), false)) {
+                if (! $this->unifiedConfirm(__('modules.commands.uninstall.confirm_question'), false)) {
                     $this->info(__('modules.commands.uninstall.aborted'));
 
                     return Command::SUCCESS;

app/Console/Commands/Module/UpdateModuleCommand.php

@@ -3,21 +3,33 @@
 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;
+use App\Extension\Vendor\VendorMode;
+use App\Services\LayoutExtensionService;
 use Illuminate\Console\Command;
 use Illuminate\Support\Facades\Log;
 
 class UpdateModuleCommand extends Command
 {
     use HasProgressBar;
+    use HasUnifiedConfirm;
+    use RebuildsSearchIndex;
 
     /**
      * The name and signature of the console command.
      */
     protected $signature = 'module:update
         {identifier : 업데이트할 모듈 식별자}
-        {--force : 버전 비교 없이 강제 업데이트}';
+        {--force : 버전 비교 없이 강제 업데이트}
+        {--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 기준)}
+        {--rebuild-search-index : 완료 후 색인이 누락된 검색 인덱스를 재생성 (인덱스가 잠기거나 재색인됩니다 — 운영 중에는 유지보수 시간에 수행하세요)}';
 
     /**
      * The console command description.
@@ -29,7 +41,8 @@ class UpdateModuleCommand extends Command
      */
     public function __construct(
         private ModuleManager $moduleManager,
-        private ModuleRepositoryInterface $moduleRepository
+        private ModuleRepositoryInterface $moduleRepository,
+        private LayoutExtensionService $layoutExtensionService
     ) {
         parent::__construct();
     }
@@ -41,6 +54,40 @@ class UpdateModuleCommand extends Command
     {
         $identifier = $this->argument('identifier');
         $force = $this->option('force');
+        $layoutStrategy = (string) $this->option('layout-strategy');
+        $sourceOption = (string) $this->option('source');
+        $zipPath = $this->option('zip');
+
+        if (! in_array($layoutStrategy, ['overwrite', 'keep'], true)) {
+            $this->error('❌ --layout-strategy 는 overwrite 또는 keep 이어야 합니다.');
+
+            return Command::FAILURE;
+        }
+
+        if (! in_array($sourceOption, ['auto', 'bundled', 'github'], true)) {
+            $this->error('❌ --source 는 auto, bundled, github 중 하나여야 합니다.');
+
+            return Command::FAILURE;
+        }
+
+        // --zip 과 --source 동시 지정 금지 (zip 이 우선 대상이므로)
+        if ($zipPath !== null && $sourceOption !== 'auto') {
+            $this->error('❌ --zip 은 --source 와 동시에 지정할 수 없습니다.');
+
+            return Command::FAILURE;
+        }
+
+        if ($zipPath !== null) {
+            $resolvedZip = realpath($zipPath);
+            if (! $resolvedZip || ! is_file($resolvedZip)) {
+                $this->error('❌ 지정된 ZIP 파일이 존재하지 않습니다: '.$zipPath);
+
+                return Command::FAILURE;
+            }
+            $zipPath = $resolvedZip;
+        }
+
+        $sourceOverride = $sourceOption === 'auto' ? null : $sourceOption;
 
         try {
             $this->moduleManager->loadModules();
@@ -54,38 +101,90 @@ class UpdateModuleCommand extends Command
                 return Command::FAILURE;
             }
 
-            // 업데이트 확인
-            $checkResult = $this->moduleManager->checkModuleUpdate($identifier);
+            // 업데이트 확인 (--zip 모드는 GitHub/번들 비교를 우회하므로 스킵)
+            if ($zipPath === null) {
+                $checkResult = $this->moduleManager->checkModuleUpdate($identifier);
 
-            if (! $checkResult['update_available'] && ! $force) {
-                $this->info('✅ '.__('modules.commands.update.no_update', ['module' => $identifier]));
+                if (! $checkResult['update_available'] && ! $force) {
+                    $this->info('✅ '.__('modules.commands.update.no_update', ['module' => $identifier]));
 
-                return Command::SUCCESS;
+                    return Command::SUCCESS;
+                }
+
+                // 업데이트 정보 표시
+                $this->info(__('modules.commands.update.current_version', ['version' => $checkResult['current_version']]));
+
+                if ($force && ! $checkResult['update_available']) {
+                    $this->warn('⚠️  '.__('modules.commands.update.force_mode'));
+                } else {
+                    $this->info(__('modules.commands.update.latest_version', ['version' => $checkResult['latest_version']]));
+                    $this->info(__('modules.commands.update.update_source', ['source' => $checkResult['update_source']]));
+                }
+            } else {
+                $this->info(__('modules.commands.update.current_version', ['version' => $module->version]));
+                $this->info('업데이트 소스: ZIP ('.$zipPath.')');
+                $this->info('업데이트 버전: (module.json 추출 후 판별)');
             }
 
-            // 업데이트 정보 표시
-            $this->info(__('modules.commands.update.current_version', ['version' => $checkResult['current_version']]));
+            $this->info(__('modules.commands.update.layout_strategy', ['strategy' => $layoutStrategy]));
 
-            if ($force && ! $checkResult['update_available']) {
-                $this->warn('⚠️  '.__('modules.commands.update.force_mode'));
-            } else {
-                $this->info(__('modules.commands.update.latest_version', ['version' => $checkResult['latest_version']]));
-                $this->info(__('modules.commands.update.update_source', ['source' => $checkResult['update_source']]));
+            // overwrite 전략일 때 관리자가 편집한 레이아웃 확장 경고
+            if ($layoutStrategy === 'overwrite') {
+                $modifiedExtensions = $this->layoutExtensionService->getModifiedExtensionsBySource(
+                    LayoutSourceType::Module,
+                    $identifier
+                );
+
+                if (! empty($modifiedExtensions)) {
+                    $this->newLine();
+                    $this->warn('⚠️  '.__('modules.commands.update.modified_extensions_warning', [
+                        'count' => count($modifiedExtensions),
+                    ]));
+
+                    foreach ($modifiedExtensions as $extension) {
+                        $this->warn(__('modules.commands.update.modified_extension_item', [
+                            'target' => $extension['target_name'],
+                            'source' => $extension['source_identifier'],
+                        ]));
+                    }
+                }
             }
 
             $this->newLine();
 
             // 확인 프롬프트 (--force 시 건너뜀)
-            if (! $force && ! $this->confirm(__('modules.commands.update.confirm_question'), false)) {
+            if (! $force && ! $this->unifiedConfirm(__('modules.commands.update.confirm_question'), false)) {
                 $this->info(__('modules.commands.update.aborted'));
 
                 return Command::SUCCESS;
             }
 
             // 업데이트 실행
+            $vendorMode = VendorMode::fromStringOrAuto((string) $this->option('vendor-mode'));
             $onProgress = $this->createProgressCallback(ModuleManager::UPDATE_STEPS);
+
+            // upgrade step 콘솔 출력 콜백: progress bar 를 잠시 지우고 별도 줄에 출력
+            $onUpgradeStep = function (string $version) use ($identifier): void {
+                if ($this->progressBar) {
+                    $this->progressBar->clear();
+                }
+                $this->line("  • [{$identifier}] upgrade step 실행: {$version}");
+                if ($this->progressBar) {
+                    $this->progressBar->display();
+                }
+            };
+
             try {
-                $updateResult = $this->moduleManager->updateModule($identifier, $force, $onProgress);
+                $updateResult = $this->moduleManager->updateModule(
+                    $identifier,
+                    $force,
+                    $onProgress,
+                    $vendorMode,
+                    $layoutStrategy,
+                    $onUpgradeStep,
+                    $sourceOverride,
+                    $zipPath,
+                );
                 $this->finishProgress();
             } catch (\Exception $e) {
                 $this->finishProgress();
@@ -104,8 +203,12 @@ class UpdateModuleCommand extends Command
                     'module' => $identifier,
                     'from' => $updateResult['from_version'],
                     'to' => $updateResult['to_version'],
+                    'layout_strategy' => $layoutStrategy,
                 ]);
 
+                // 검색 인덱스 재생성은 운영자가 선택했을 때만 수행한다 (인덱스 잠금·재색인 비용)
+                $this->handleSearchIndexRebuild();
+
                 return Command::SUCCESS;
             }
 

app/Console/Commands/NotificationCleanupCommand.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\NotificationService;
+use Illuminate\Console\Command;
+
+/**
+ * 오래된 사이트내 알림을 정리하는 커맨드
+ */
+class NotificationCleanupCommand extends Command
+{
+    /**
+     * The name and signature of the console command.
+     */
+    protected $signature = 'notification:cleanup';
+
+    /**
+     * The console command description.
+     */
+    protected $description = '보관 기간이 지난 사이트내 알림을 삭제합니다';
+
+    /**
+     * Execute the console command.
+     *
+     * @param NotificationService $service 알림 서비스
+     * @return int 명령 실행 결과 코드
+     */
+    public function handle(NotificationService $service): int
+    {
+        $this->info('알림 정리 시작...');
+
+        $config = config('notification.database_channel', []);
+        $this->info("  읽음 보관: {$config['read_retention_days']}일, 미읽음 보관: {$config['unread_retention_days']}일");
+
+        $result = $service->cleanup();
+
+        $this->info("  읽음 알림 삭제: {$result['deleted_read']}건");
+        $this->info("  미읽음 알림 삭제: {$result['deleted_unread']}건");
+        $this->info('알림 정리 완료');
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/PlaywrightIssueToken.php

@@ -0,0 +1,212 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Enums\ExtensionOwnerType;
+use App\Models\Permission;
+use App\Models\Role;
+use App\Models\User;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Config;
+
+/**
+ * Playwright E2E 용 Sanctum 토큰 발급 커맨드.
+ *
+ * 임의 권한 식별자(코어/모듈/플러그인) 를 받아 권한 보유 관리자 유저를 즉시 생성하고
+ * Sanctum 개인 액세스 토큰을 발급한다. 발급된 토큰은 stdout 마지막 줄에 출력되어
+ * Playwright fixture 가 stdin 캡처로 사용한다.
+ *
+ * 보안 가드 (3중):
+ *   ① CLI 한정 — `php_sapi_name() === 'cli'` 확인. production 웹 요청에서 절대 도달 불가
+ *   ② 명시 옵트인 — `G7_PLAYWRIGHT_BYPASS=1` 환경변수 부여 필수.
+ *      `.env` 영구 수정 없이 인라인 환경변수로만 활성화 가능 → 무심코 production 으로 새지 않음
+ *   ③ APP_DEBUG 강제 — bypass flag 인지 후 `config('app.debug')` 를 true 로 inline override.
+ *      SettingsServiceProvider 의 testing/bypass 분기가 이미 settings JSON 덮어쓰기를 건너뛰므로
+ *      production + debug=false 환경에서도 토큰 발급이 가능하다
+ *
+ * 환경 매트릭스:
+ * - local   + bypass=1 : 로컬 개발자 PC 에서 직접 spec 작성/실행
+ * - testing + bypass=1 : CI / PHPUnit 환경에서 .env.testing 로 동작하는 E2E 통합 (testing 환경은 이미 testing 가드로 통과)
+ * - production + bypass=1 : production DB 가 활성 호스트를 가리키는 환경(예: g7.dev) 에서 E2E
+ *
+ * 호출 예시 (PowerShell):
+ *   $env:G7_PLAYWRIGHT_BYPASS='1'; php artisan playwright:issue-token --permissions=core.templates.layouts.edit
+ *
+ * 로직 출처: tests/Feature/Api/Admin/LayoutAccessCheckEndpointTest::makeAdminUser (44~87행)
+ */
+class PlaywrightIssueToken extends Command
+{
+    protected $signature = 'playwright:issue-token
+        {--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 웹 요청에서 절대 도달 불가
+        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;
+        }
+
+        // ③ APP_DEBUG 강제 — production + debug=false 환경에서도 sanctum 토큰 발급 + 디버그 정보 누락 방지.
+        // 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') ?: [];
+
+        // --no-admin-role: 지정한 권한만 가진 계정을 만든다.
+        // 기본값(플래그 없음)은 종전대로 admin 역할을 함께 부여한다 — 기존 spec 무영향.
+        $user = $this->makeAdminUser($permissions, ! $this->option('no-admin-role'));
+        $token = $user->createToken('playwright-'.uniqid())->plainTextToken;
+
+        $this->line($token);
+
+        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}건");
+        }
+    }
+
+    /**
+     * 권한 식별자 배열로 관리자 유저를 생성하고 권한을 부여한다.
+     *
+     * 절차:
+     * 1. User factory 로 신규 유저 생성
+     * 2. 권한 식별자별로 Permission 행 보장 (firstOrCreate)
+     * 3. uniqid 접미사로 격리된 test role 생성 + 권한 sync
+     * 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, 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' => ['ko' => $identifier, 'en' => $identifier],
+                    'description' => ['ko' => $identifier, 'en' => $identifier],
+                    'extension_type' => ExtensionOwnerType::Core,
+                    'extension_identifier' => 'core',
+                    'type' => 'admin',
+                ]
+            );
+            $permissionIds[] = $permission->id;
+        }
+
+        $testRole = Role::create([
+            'identifier' => 'playwright_test_'.uniqid(),
+            'name' => ['ko' => 'Playwright 테스트 관리자', 'en' => 'Playwright Test Admin'],
+            'description' => ['ko' => 'E2E 자동화 전용', 'en' => 'E2E automation only'],
+            'is_active' => true,
+        ]);
+
+        if (! empty($permissionIds)) {
+            $testRole->permissions()->sync($permissionIds);
+        }
+
+        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();
+    }
+}

app/Console/Commands/PlaywrightSeedLayout.php

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

app/Console/Commands/Plugin/BuildPluginCommand.php

@@ -4,6 +4,7 @@ namespace App\Console\Commands\Plugin;
 
 use App\Extension\PluginManager;
 use App\Extension\Traits\ClearsTemplateCaches;
+use App\Extension\Traits\GeneratesComponentManifest;
 use Illuminate\Console\Command;
 use Illuminate\Support\Facades\Log;
 use Symfony\Component\Process\Process;
@@ -11,6 +12,7 @@ use Symfony\Component\Process\Process;
 class BuildPluginCommand extends Command
 {
     use ClearsTemplateCaches;
+    use GeneratesComponentManifest;
 
     /**
      * The name and signature of the console command.
@@ -187,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}");
@@ -196,6 +203,14 @@ class BuildPluginCommand extends Command
             // 빌드 결과 파일 확인
             $this->displayBuildResults($buildPath, $identifier);
 
+            // 편집기 컴포넌트 매니페스트(components.json) 생성
+            $manifestResult = $this->generateComponentManifest($buildPath, $identifier);
+            if ($manifestResult['written']) {
+                $this->line("   - components.json 생성됨 (컴포넌트 {$manifestResult['count']}개)");
+            } else {
+                $this->warn('   - components.json 생성 실패 (편집 모드 컨트롤 노출 제한)');
+            }
+
             // 캐시 버전 증가 (브라우저 캐시 무효화)
             $this->incrementExtensionCacheVersion();
             $this->line('   - 캐시 버전 갱신됨');
@@ -328,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') {
@@ -345,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) {

app/Console/Commands/Plugin/CheckPluginUpdatesCommand.php

@@ -116,7 +116,7 @@ class CheckPluginUpdatesCommand extends Command
         $updateCount = 0;
 
         foreach ($result['details'] as $detail) {
-            $isUpdate = $detail['update_available'] ?? false;
+            $isUpdate = (bool) ($detail['update_available'] ?? true);
             if ($isUpdate) {
                 $updateCount++;
             }
@@ -143,7 +143,7 @@ class CheckPluginUpdatesCommand extends Command
         $this->table($headers, $tableData);
         $this->newLine();
         $this->info(__('plugins.commands.check_updates.summary', [
-            'total' => count($result['details']),
+            'total' => $result['checked_count'] ?? count($result['details']),
             'updates' => $updateCount,
         ]));
 

app/Console/Commands/Plugin/ClearPluginCacheCommand.php

@@ -2,14 +2,21 @@
 
 namespace App\Console\Commands\Plugin;
 
-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\Cache;
 use Illuminate\Support\Facades\Log;
 
 class ClearPluginCacheCommand extends Command
 {
+    use ClearsTemplateCaches;
+    use InvalidatesLayoutCache;
+
     /**
      * The name and signature of the console command.
      */
@@ -26,13 +33,20 @@ class ClearPluginCacheCommand extends Command
      */
     public function __construct(
         private PluginManager $pluginManager,
-        private PluginRepositoryInterface $pluginRepository
+        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
     {
@@ -58,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,
@@ -66,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 (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]));
             }
 
@@ -107,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 (Cache::forget($key)) {
-                $clearedCount++;
-            }
-        }
-
-        return $clearedCount;
+        return $this->layoutRepository
+            ->getBySourceIdentifier($identifier, LayoutSourceType::Plugin)
+            ->count();
     }
 }

app/Console/Commands/Plugin/InstallPluginCommand.php

@@ -3,9 +3,11 @@
 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;
+use App\Extension\Vendor\VendorMode;
 use App\Models\Permission;
 use App\Rules\ValidExtensionIdentifier;
 use Illuminate\Console\Command;
@@ -15,11 +17,16 @@ use Illuminate\Support\Facades\Validator;
 class InstallPluginCommand extends Command
 {
     use HasProgressBar;
+    use RebuildsSearchIndex;
 
     /**
      * The name and signature of the console command.
      */
-    protected $signature = 'plugin:install {identifier : 설치할 플러그인 식별자}';
+    protected $signature = 'plugin:install
+        {identifier : 설치할 플러그인 식별자}
+        {--vendor-mode=auto : Vendor 설치 모드 (auto|composer|bundled)}
+        {--force : 이미 설치된 경우에도 _bundled/_pending 원본으로 활성 디렉토리를 덮어쓰고 재설치 (불완전 설치 복구)}
+        {--rebuild-search-index : 완료 후 색인이 누락된 검색 인덱스를 재생성 (인덱스가 잠기거나 재색인됩니다 — 운영 중에는 유지보수 시간에 수행하세요)}';
 
     /**
      * The console command description.
@@ -55,22 +62,29 @@ class InstallPluginCommand extends Command
             return Command::FAILURE;
         }
 
+        $force = (bool) $this->option('force');
+
         try {
             // 플러그인 디렉토리 스캔 및 로드
             $this->pluginManager->loadPlugins();
 
-            // 이미 설치된 플러그인인지 확인
+            // 이미 설치된 플러그인인지 확인 (force 시 스킵하여 재설치/복구 허용)
             $existingPlugin = $this->pluginRepository->findByIdentifier($identifier);
-            if ($existingPlugin) {
+            if ($existingPlugin && ! $force) {
                 $this->warn('⚠️  '.__('plugins.commands.install.already_installed', ['plugin' => $identifier]));
 
                 return Command::FAILURE;
             }
 
+            if ($existingPlugin && $force) {
+                $this->warn('⚠️  '.__('plugins.commands.install.force_reinstall', ['plugin' => $identifier]));
+            }
+
             // 플러그인 설치
+            $vendorMode = VendorMode::fromStringOrAuto((string) $this->option('vendor-mode'));
             $onProgress = $this->createProgressCallback(PluginManager::INSTALL_STEPS);
             try {
-                $result = $this->pluginManager->installPlugin($identifier, $onProgress);
+                $result = $this->pluginManager->installPlugin($identifier, $onProgress, $vendorMode, $force);
                 $this->finishProgress();
             } catch (\Exception $e) {
                 $this->finishProgress();
@@ -100,6 +114,9 @@ class InstallPluginCommand extends Command
 
                 Log::info(__('plugins.commands.install.success', ['plugin' => $identifier]));
 
+                // 검색 인덱스 재생성은 운영자가 선택했을 때만 수행한다 (인덱스 잠금·재색인 비용)
+                $this->handleSearchIndexRebuild();
+
                 return Command::SUCCESS;
             }
 

app/Console/Commands/Plugin/ListPluginCommand.php

@@ -13,7 +13,8 @@ class ListPluginCommand extends Command
      * The name and signature of the console command.
      */
     protected $signature = 'plugin:list
-        {--status= : 상태로 필터 (installed, uninstalled, active, inactive)}';
+        {--status= : 상태로 필터 (installed, uninstalled, active, inactive)}
+        {--hidden : 숨김(hidden=true) 플러그인도 함께 출력}';
 
     /**
      * The console command description.
@@ -39,6 +40,7 @@ class ListPluginCommand extends Command
         $this->pluginManager->loadPlugins();
 
         $statusFilter = $this->option('status');
+        $includeHidden = (bool) $this->option('hidden');
 
         // 상태 필터 검증
         if ($statusFilter && ! in_array($statusFilter, ['installed', 'uninstalled', 'active', 'inactive'])) {
@@ -58,6 +60,11 @@ class ListPluginCommand extends Command
 
         // 설치된 플러그인 추가
         foreach ($installedPlugins as $identifier => $plugin) {
+            // 숨김 필터: --hidden 미지정 시 hidden=true 플러그인 제외
+            if (! $includeHidden && ! empty($plugin['hidden'])) {
+                continue;
+            }
+
             // 상태 필터
             if ($statusFilter) {
                 if ($statusFilter === 'uninstalled') {
@@ -86,6 +93,11 @@ class ListPluginCommand extends Command
         // 미설치 플러그인 추가
         if (! $statusFilter || $statusFilter === 'uninstalled') {
             foreach ($uninstalledPlugins as $identifier => $plugin) {
+                // 숨김 필터: --hidden 미지정 시 hidden=true 플러그인 제외
+                if (! $includeHidden && ! empty($plugin['hidden'])) {
+                    continue;
+                }
+
                 // 상태 필터 (uninstalled 또는 필터 없음)
                 if ($statusFilter && $statusFilter !== 'uninstalled') {
                     continue;

app/Console/Commands/Plugin/PluginVendorBundleCommand.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace App\Console\Commands\Plugin;
+
+use App\Console\Commands\Vendor\Concerns\RunsVendorBundleAction;
+use App\Extension\Vendor\VendorBundler;
+use Illuminate\Console\Command;
+
+/**
+ * 플러그인 vendor/ 디렉토리를 vendor-bundle.zip 으로 빌드합니다.
+ *
+ * 기존 plugin:build 패턴과 동일하게 positional identifier + --all 옵션 지원.
+ */
+class PluginVendorBundleCommand extends Command
+{
+    use RunsVendorBundleAction;
+
+    protected $signature = 'plugin:vendor-bundle
+                            {identifier? : 빌드할 플러그인 식별자 (생략 시 --all 필요)}
+                            {--all : 모든 _bundled 플러그인 빌드}
+                            {--force : 해시 체크 무시, 강제 재빌드}
+                            {--check : 실제 빌드 없이 stale 여부만 확인}';
+
+    protected $description = '플러그인 vendor/ 디렉토리를 vendor-bundle.zip 으로 빌드합니다 (공유 호스팅용)';
+
+    public function handle(VendorBundler $bundler): int
+    {
+        $identifier = $this->argument('identifier');
+        $all = (bool) $this->option('all');
+
+        if (! $identifier && ! $all) {
+            $this->error('식별자 또는 --all 옵션을 지정해야 합니다.');
+            $this->line('사용법:');
+            $this->line('  php artisan plugin:vendor-bundle sirsoft-payment');
+            $this->line('  php artisan plugin:vendor-bundle --all');
+
+            return self::FAILURE;
+        }
+
+        $targets = [];
+        if ($all) {
+            foreach ($this->discoverBundledIdentifiers('plugin') as $id) {
+                $targets[] = ['type' => 'plugin', 'identifier' => $id];
+            }
+        } else {
+            $targets[] = ['type' => 'plugin', 'identifier' => $identifier];
+        }
+
+        return $this->runBuildAction(
+            $bundler,
+            $targets,
+            (bool) $this->option('force'),
+            (bool) $this->option('check'),
+        );
+    }
+}

app/Console/Commands/Plugin/PluginVendorVerifyCommand.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace App\Console\Commands\Plugin;
+
+use App\Console\Commands\Vendor\Concerns\RunsVendorBundleAction;
+use App\Extension\Vendor\VendorIntegrityChecker;
+use Illuminate\Console\Command;
+
+/**
+ * 플러그인 vendor-bundle.zip 무결성을 검증합니다.
+ */
+class PluginVendorVerifyCommand extends Command
+{
+    use RunsVendorBundleAction;
+
+    protected $signature = 'plugin:vendor-verify
+                            {identifier? : 검증할 플러그인 식별자 (생략 시 --all 필요)}
+                            {--all : 모든 _bundled 플러그인 검증}';
+
+    protected $description = '플러그인 vendor-bundle.zip 의 SHA256 무결성을 검증합니다';
+
+    public function handle(VendorIntegrityChecker $checker): int
+    {
+        $identifier = $this->argument('identifier');
+        $all = (bool) $this->option('all');
+
+        if (! $identifier && ! $all) {
+            $this->error('식별자 또는 --all 옵션을 지정해야 합니다.');
+
+            return self::FAILURE;
+        }
+
+        $targets = [];
+        if ($all) {
+            foreach ($this->discoverBundledIdentifiers('plugin') as $id) {
+                $targets[] = ['type' => 'plugin', 'identifier' => $id];
+            }
+        } else {
+            $targets[] = ['type' => 'plugin', 'identifier' => $identifier];
+        }
+
+        return $this->runVerifyAction($checker, $targets);
+    }
+}

app/Console/Commands/Plugin/UninstallPluginCommand.php

@@ -3,6 +3,7 @@
 namespace App\Console\Commands\Plugin;
 
 use App\Console\Commands\Traits\HasProgressBar;
+use App\Console\Commands\Traits\HasUnifiedConfirm;
 use App\Contracts\Repositories\PluginRepositoryInterface;
 use App\Enums\ExtensionOwnerType;
 use App\Extension\PluginManager;
@@ -13,6 +14,7 @@ use Illuminate\Support\Facades\Log;
 class UninstallPluginCommand extends Command
 {
     use HasProgressBar;
+    use HasUnifiedConfirm;
 
     /**
      * The name and signature of the console command.
@@ -79,7 +81,7 @@ class UninstallPluginCommand extends Command
                 }
                 $this->newLine();
 
-                if (! $this->confirm(__('plugins.commands.uninstall.confirm_question'), false)) {
+                if (! $this->unifiedConfirm(__('plugins.commands.uninstall.confirm_question'), false)) {
                     $this->info(__('plugins.commands.uninstall.aborted'));
 
                     return Command::SUCCESS;

app/Console/Commands/Plugin/UpdatePluginCommand.php

@@ -3,21 +3,33 @@
 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;
+use App\Extension\Vendor\VendorMode;
+use App\Services\LayoutExtensionService;
 use Illuminate\Console\Command;
 use Illuminate\Support\Facades\Log;
 
 class UpdatePluginCommand extends Command
 {
     use HasProgressBar;
+    use HasUnifiedConfirm;
+    use RebuildsSearchIndex;
 
     /**
      * The name and signature of the console command.
      */
     protected $signature = 'plugin:update
         {identifier : 업데이트할 플러그인 식별자}
-        {--force : 버전 비교 없이 강제 업데이트}';
+        {--force : 버전 비교 없이 강제 업데이트}
+        {--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 기준)}
+        {--rebuild-search-index : 완료 후 색인이 누락된 검색 인덱스를 재생성 (인덱스가 잠기거나 재색인됩니다 — 운영 중에는 유지보수 시간에 수행하세요)}';
 
     /**
      * The console command description.
@@ -29,7 +41,8 @@ class UpdatePluginCommand extends Command
      */
     public function __construct(
         private PluginManager $pluginManager,
-        private PluginRepositoryInterface $pluginRepository
+        private PluginRepositoryInterface $pluginRepository,
+        private LayoutExtensionService $layoutExtensionService
     ) {
         parent::__construct();
     }
@@ -41,6 +54,39 @@ class UpdatePluginCommand extends Command
     {
         $identifier = $this->argument('identifier');
         $force = $this->option('force');
+        $layoutStrategy = (string) $this->option('layout-strategy');
+        $sourceOption = (string) $this->option('source');
+        $zipPath = $this->option('zip');
+
+        if (! in_array($layoutStrategy, ['overwrite', 'keep'], true)) {
+            $this->error('❌ --layout-strategy 는 overwrite 또는 keep 이어야 합니다.');
+
+            return Command::FAILURE;
+        }
+
+        if (! in_array($sourceOption, ['auto', 'bundled', 'github'], true)) {
+            $this->error('❌ --source 는 auto, bundled, github 중 하나여야 합니다.');
+
+            return Command::FAILURE;
+        }
+
+        if ($zipPath !== null && $sourceOption !== 'auto') {
+            $this->error('❌ --zip 은 --source 와 동시에 지정할 수 없습니다.');
+
+            return Command::FAILURE;
+        }
+
+        if ($zipPath !== null) {
+            $resolvedZip = realpath($zipPath);
+            if (! $resolvedZip || ! is_file($resolvedZip)) {
+                $this->error('❌ 지정된 ZIP 파일이 존재하지 않습니다: '.$zipPath);
+
+                return Command::FAILURE;
+            }
+            $zipPath = $resolvedZip;
+        }
+
+        $sourceOverride = $sourceOption === 'auto' ? null : $sourceOption;
 
         try {
             $this->pluginManager->loadPlugins();
@@ -54,38 +100,90 @@ class UpdatePluginCommand extends Command
                 return Command::FAILURE;
             }
 
-            // 업데이트 확인
-            $checkResult = $this->pluginManager->checkPluginUpdate($identifier);
+            // 업데이트 확인 (--zip 모드는 GitHub/번들 비교를 우회하므로 스킵)
+            if ($zipPath === null) {
+                $checkResult = $this->pluginManager->checkPluginUpdate($identifier);
 
-            if (! $checkResult['update_available'] && ! $force) {
-                $this->info('✅ '.__('plugins.commands.update.no_update', ['plugin' => $identifier]));
+                if (! $checkResult['update_available'] && ! $force) {
+                    $this->info('✅ '.__('plugins.commands.update.no_update', ['plugin' => $identifier]));
 
-                return Command::SUCCESS;
+                    return Command::SUCCESS;
+                }
+
+                // 업데이트 정보 표시
+                $this->info(__('plugins.commands.update.current_version', ['version' => $checkResult['current_version']]));
+
+                if ($force && ! $checkResult['update_available']) {
+                    $this->warn('⚠️  '.__('plugins.commands.update.force_mode'));
+                } else {
+                    $this->info(__('plugins.commands.update.latest_version', ['version' => $checkResult['latest_version']]));
+                    $this->info(__('plugins.commands.update.update_source', ['source' => $checkResult['update_source']]));
+                }
+            } else {
+                $this->info(__('plugins.commands.update.current_version', ['version' => $plugin->version]));
+                $this->info('업데이트 소스: ZIP ('.$zipPath.')');
+                $this->info('업데이트 버전: (plugin.json 추출 후 판별)');
             }
 
-            // 업데이트 정보 표시
-            $this->info(__('plugins.commands.update.current_version', ['version' => $checkResult['current_version']]));
+            $this->info(__('plugins.commands.update.layout_strategy', ['strategy' => $layoutStrategy]));
 
-            if ($force && ! $checkResult['update_available']) {
-                $this->warn('⚠️  '.__('plugins.commands.update.force_mode'));
-            } else {
-                $this->info(__('plugins.commands.update.latest_version', ['version' => $checkResult['latest_version']]));
-                $this->info(__('plugins.commands.update.update_source', ['source' => $checkResult['update_source']]));
+            // overwrite 전략일 때 관리자가 편집한 레이아웃 확장 경고
+            if ($layoutStrategy === 'overwrite') {
+                $modifiedExtensions = $this->layoutExtensionService->getModifiedExtensionsBySource(
+                    LayoutSourceType::Plugin,
+                    $identifier
+                );
+
+                if (! empty($modifiedExtensions)) {
+                    $this->newLine();
+                    $this->warn('⚠️  '.__('plugins.commands.update.modified_extensions_warning', [
+                        'count' => count($modifiedExtensions),
+                    ]));
+
+                    foreach ($modifiedExtensions as $extension) {
+                        $this->warn(__('plugins.commands.update.modified_extension_item', [
+                            'target' => $extension['target_name'],
+                            'source' => $extension['source_identifier'],
+                        ]));
+                    }
+                }
             }
 
             $this->newLine();
 
             // 확인 프롬프트 (--force 시 건너뜀)
-            if (! $force && ! $this->confirm(__('plugins.commands.update.confirm_question'), false)) {
+            if (! $force && ! $this->unifiedConfirm(__('plugins.commands.update.confirm_question'), false)) {
                 $this->info(__('plugins.commands.update.aborted'));
 
                 return Command::SUCCESS;
             }
 
             // 업데이트 실행
+            $vendorMode = VendorMode::fromStringOrAuto((string) $this->option('vendor-mode'));
             $onProgress = $this->createProgressCallback(PluginManager::UPDATE_STEPS);
+
+            // upgrade step 콘솔 출력 콜백: progress bar 를 잠시 지우고 별도 줄에 출력
+            $onUpgradeStep = function (string $version) use ($identifier): void {
+                if ($this->progressBar) {
+                    $this->progressBar->clear();
+                }
+                $this->line("  • [{$identifier}] upgrade step 실행: {$version}");
+                if ($this->progressBar) {
+                    $this->progressBar->display();
+                }
+            };
+
             try {
-                $updateResult = $this->pluginManager->updatePlugin($identifier, $force, $onProgress);
+                $updateResult = $this->pluginManager->updatePlugin(
+                    $identifier,
+                    $force,
+                    $onProgress,
+                    $vendorMode,
+                    $layoutStrategy,
+                    $onUpgradeStep,
+                    $sourceOverride,
+                    $zipPath,
+                );
                 $this->finishProgress();
             } catch (\Exception $e) {
                 $this->finishProgress();
@@ -104,8 +202,12 @@ class UpdatePluginCommand extends Command
                     'plugin' => $identifier,
                     'from' => $updateResult['from_version'],
                     'to' => $updateResult['to_version'],
+                    'layout_strategy' => $layoutStrategy,
                 ]);
 
+                // 검색 인덱스 재생성은 운영자가 선택했을 때만 수행한다 (인덱스 잠금·재색인 비용)
+                $this->handleSearchIndexRebuild();
+
                 return Command::SUCCESS;
             }
 

app/Console/Commands/PruneActivityLogsCommand.php

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

app/Console/Commands/PruneIdentityLogsCommand.php

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

app/Console/Commands/PruneNotificationLogsCommand.php

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

app/Console/Commands/PruneOrphanAttachmentsCommand.php

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

app/Console/Commands/PruneScheduleHistoryCommand.php

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

app/Console/Commands/PruneSeoCacheStatsCommand.php

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

app/Console/Commands/PruneStorageLeftoversCommand.php

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

app/Console/Commands/RecalculateLayoutVersionDiffsCommand.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Contracts\Repositories\LayoutVersionRepositoryInterface;
+use Illuminate\Console\Command;
+
+/**
+ * 레이아웃 버전의 변경 요약(changes_summary)을 현재 알고리즘으로 재계산하는 커맨드
+ *
+ * 버전 변경량 측정이 키 경로 단위에서 라인 단위(버전 비교 diff 뷰와 동일 SSoT)로
+ * 바뀌기 전에 저장된 버전들은 옛 기준의 changes_summary 를 담고 있어, 버전 목록의
+ * 변경량이 상세 diff 와 불일치한다. 본 커맨드로 기존 버전을 일괄 재계산해 정합시킨다.
+ */
+class RecalculateLayoutVersionDiffsCommand extends Command
+{
+    /**
+     * The name and signature of the console command.
+     */
+    protected $signature = 'layout-versions:recalculate-diffs';
+
+    /**
+     * The console command description.
+     */
+    protected $description = '레이아웃 버전의 변경 요약을 현재 라인 단위 알고리즘으로 재계산합니다';
+
+    /**
+     * Execute the console command.
+     *
+     * @param  LayoutVersionRepositoryInterface  $repository  버전 저장소
+     * @return int 명령 실행 결과 코드
+     */
+    public function handle(LayoutVersionRepositoryInterface $repository): int
+    {
+        $this->info('레이아웃 버전 변경 요약 재계산을 시작합니다...');
+
+        $updated = $repository->recalculateAllChangeSummaries();
+
+        $this->info("버전 {$updated}건의 변경 요약을 재계산했습니다.");
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/Search/SearchIndexCommand.php

@@ -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>');
+        }
+    }
+}

app/Console/Commands/SeoGenerateSitemapCommand.php

@@ -2,20 +2,26 @@
 
 namespace App\Console\Commands;
 
+use App\Enums\SitemapGenerationMode;
 use App\Jobs\GenerateSitemapJob;
 use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Config;
 
 /**
  * Sitemap XML 생성 Artisan 커맨드
  *
- * 큐를 통한 비동기 실행 또는 --sync 옵션으로 동기 실행을 지원합니다.
+ * 큐 드라이버 설정에 따라 비동기/동기 실행을 자동 선택합니다.
+ * --sync 옵션을 명시하면 큐 드라이버와 무관하게 동기 실행합니다.
  */
 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 커맨드 설명
@@ -29,14 +35,44 @@ class SeoGenerateSitemapCommand extends Command
      */
     public function handle(): int
     {
-        if ($this->option('sync')) {
-            GenerateSitemapJob::dispatchSync();
-            $this->info('Sitemap이 생성되었습니다.');
+        $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 값을 보존하므로 격리가 유지된다.
+        $connection = (string) Config::get('queue.default', 'sync');
+        $isSyncDriver = $connection === 'sync';
+
+        if ($forceSync || $isSyncDriver) {
+            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'));
+    }
 }

app/Console/Commands/Template/BuildTemplateCommand.php

@@ -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) {

app/Console/Commands/Template/CheckTemplateUpdatesCommand.php

@@ -116,7 +116,7 @@ class CheckTemplateUpdatesCommand extends Command
         $updateCount = 0;
 
         foreach ($result['details'] as $detail) {
-            $isUpdate = $detail['update_available'] ?? false;
+            $isUpdate = (bool) ($detail['update_available'] ?? true);
             if ($isUpdate) {
                 $updateCount++;
             }
@@ -143,7 +143,7 @@ class CheckTemplateUpdatesCommand extends Command
         $this->table($headers, $tableData);
         $this->newLine();
         $this->info(__('templates.commands.check_updates.summary', [
-            'total' => count($result['details']),
+            'total' => $result['checked_count'] ?? count($result['details']),
             'updates' => $updateCount,
         ]));
 

app/Console/Commands/Template/ClearTemplateCacheCommand.php

@@ -3,14 +3,16 @@
 namespace App\Console\Commands\Template;
 
 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\Cache;
 use Illuminate\Support\Facades\Log;
 
 class ClearTemplateCacheCommand extends Command
 {
+    use ClearsTemplateCaches;
+
     /**
      * The name and signature of the console command.
      */
@@ -26,7 +28,8 @@ class ClearTemplateCacheCommand extends Command
      * 템플릿 관리자
      */
     public function __construct(
-        private TemplateManager $templateManager
+        private TemplateManager $templateManager,
+        private ExtensionBundleService $bundleService
     ) {
         parent::__construct();
     }
@@ -64,6 +67,10 @@ class ClearTemplateCacheCommand extends Command
 
     /**
      * 특정 템플릿의 캐시 삭제
+     *
+     * 라이프사이클(update/deactivate/uninstall)과 동일한 무효화 단일 지점
+     * (`TemplateManager::clearTemplateCache()`)을 경유한다 — 커맨드가 키 목록을
+     * 별도로 유지하면 키 규약 변경 시 유령 forget 으로 사문화된다 (#588, 공개 #119).
      */
     private function clearSingleTemplateCache(string $identifier): void
     {
@@ -75,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) {
-                Cache::forget("layout.{$identifier}.{$layout->name}");
-                $clearedCount++;
-            }
-        }
-
-        // 2. Routes 캐시 삭제
-        Cache::forget("template.routes.{$identifier}");
-        $clearedCount++;
-
-        // 3. 다국어 파일 캐시 삭제
-        $supportedLocales = config('app.supported_locales', ['ko', 'en']);
-        foreach ($supportedLocales as $locale) {
-            Cache::forget("template.language.{$identifier}.{$locale}");
-            $clearedCount++;
-        }
-
-        // 4. 활성 템플릿 타입 캐시 삭제
-        if ($templateRecord) {
-            Cache::forget("templates.active.{$templateRecord->type}");
-            $clearedCount++;
-        }
+        // 상태 키(ext.templates.*) + 버전 포함 키 무효화 (버전 bump)
+        TemplateManager::invalidateTemplateStatusCache();
+        $this->incrementExtensionCacheVersion();
 
         $this->info('✅ '.__('templates.commands.cache_clear.success_single', [
             'template' => $identifier,
@@ -123,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) {
-                Cache::forget("layout.{$templateRecord->identifier}.{$layout->name}");
-                $clearedCount++;
-            }
-
-            // 2. Routes 캐시 삭제
-            Cache::forget("template.routes.{$templateRecord->identifier}");
-            $clearedCount++;
-
-            // 3. 다국어 파일 캐시 삭제
-            foreach ($supportedLocales as $locale) {
-                Cache::forget("template.language.{$templateRecord->identifier}.{$locale}");
-                $clearedCount++;
-            }
+        // 모든 설치된 템플릿의 캐시 삭제 (설치 레코드 기준 — 라이프사이클과 동일 지점)
+        foreach (Template::all() as $templateRecord) {
+            $clearedCount += $this->templateManager->clearTemplateCache($templateRecord->identifier);
         }
 
-        // 4. 활성 템플릿 타입 캐시 삭제
-        Cache::forget('templates.active.admin');
-        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,

app/Console/Commands/Template/InstallTemplateCommand.php

@@ -17,7 +17,9 @@ class InstallTemplateCommand extends Command
     /**
      * The name and signature of the console command.
      */
-    protected $signature = 'template:install {identifier : 템플릿 식별자 (디렉토리명)}';
+    protected $signature = 'template:install
+        {identifier : 템플릿 식별자 (디렉토리명)}
+        {--force : 이미 설치된 경우에도 _bundled/_pending 원본으로 활성 디렉토리를 덮어쓰고 재설치 (불완전 설치 복구)}';
 
     /**
      * The console command description.
@@ -53,14 +55,22 @@ class InstallTemplateCommand extends Command
             return Command::FAILURE;
         }
 
+        $force = (bool) $this->option('force');
+
         try {
             // 템플릿 디렉토리 스캔 및 로드
             $this->templateManager->loadTemplates();
 
+            // 이미 설치된 템플릿인지 확인 (force 시 경고 후 재설치/복구 허용)
+            $existingTemplate = $this->templateRepository->findByIdentifier($identifier);
+            if ($existingTemplate && $force) {
+                $this->warn('⚠️  '.__('templates.commands.install.force_reinstall', ['template' => $identifier]));
+            }
+
             // 템플릿 설치
             $onProgress = $this->createProgressCallback(TemplateManager::INSTALL_STEPS);
             try {
-                $result = $this->templateManager->installTemplate($identifier, $onProgress);
+                $result = $this->templateManager->installTemplate($identifier, $onProgress, $force);
                 $this->finishProgress();
             } catch (\Exception $e) {
                 $this->finishProgress();

app/Console/Commands/Template/ListTemplateCommand.php

@@ -13,7 +13,8 @@ class ListTemplateCommand extends Command
      */
     protected $signature = 'template:list
         {--type= : 템플릿 타입으로 필터 (admin, user)}
-        {--status= : 상태로 필터 (installed, uninstalled, active, inactive)}';
+        {--status= : 상태로 필터 (installed, uninstalled, active, inactive)}
+        {--hidden : 숨김(hidden=true) 템플릿도 함께 출력}';
 
     /**
      * The console command description.
@@ -40,6 +41,7 @@ class ListTemplateCommand extends Command
 
         $typeFilter = $this->option('type');
         $statusFilter = $this->option('status');
+        $includeHidden = (bool) $this->option('hidden');
 
         // 타입 필터 검증
         if ($typeFilter && ! in_array($typeFilter, ['admin', 'user'])) {
@@ -66,6 +68,11 @@ class ListTemplateCommand extends Command
 
         // 설치된 템플릿 추가
         foreach ($installedTemplates as $identifier => $template) {
+            // 숨김 필터: --hidden 미지정 시 hidden=true 템플릿 제외
+            if (! $includeHidden && ! empty($template['hidden'])) {
+                continue;
+            }
+
             // 타입 필터
             if ($typeFilter && $template['type'] !== $typeFilter) {
                 continue;
@@ -99,6 +106,11 @@ class ListTemplateCommand extends Command
         // 미설치 템플릿 추가
         if (! $statusFilter || $statusFilter === 'uninstalled') {
             foreach ($uninstalledTemplates as $identifier => $template) {
+                // 숨김 필터: --hidden 미지정 시 hidden=true 템플릿 제외
+                if (! $includeHidden && ! empty($template['hidden'])) {
+                    continue;
+                }
+
                 // 타입 필터
                 if ($typeFilter && $template['type'] !== $typeFilter) {
                     continue;

app/Console/Commands/Template/UninstallTemplateCommand.php

@@ -3,6 +3,7 @@
 namespace App\Console\Commands\Template;
 
 use App\Console\Commands\Traits\HasProgressBar;
+use App\Console\Commands\Traits\HasUnifiedConfirm;
 use App\Contracts\Repositories\TemplateRepositoryInterface;
 use App\Extension\TemplateManager;
 use Illuminate\Console\Command;
@@ -11,6 +12,7 @@ use Illuminate\Support\Facades\Log;
 class UninstallTemplateCommand extends Command
 {
     use HasProgressBar;
+    use HasUnifiedConfirm;
 
     /**
      * The name and signature of the console command.
@@ -57,7 +59,7 @@ class UninstallTemplateCommand extends Command
             $this->warn(__('templates.commands.uninstall.confirm_details.layouts', ['count' => $template->layouts()->count()]));
             $this->warn(__('templates.commands.uninstall.confirm_details.versions'));
 
-            if (! $this->confirm(__('templates.commands.uninstall.confirm_question'), false)) {
+            if (! $this->unifiedConfirm(__('templates.commands.uninstall.confirm_question'), false)) {
                 $this->info(__('templates.commands.uninstall.aborted'));
 
                 return Command::SUCCESS;

app/Console/Commands/Template/UpdateTemplateCommand.php

@@ -3,6 +3,7 @@
 namespace App\Console\Commands\Template;
 
 use App\Console\Commands\Traits\HasProgressBar;
+use App\Console\Commands\Traits\HasUnifiedConfirm;
 use App\Contracts\Repositories\TemplateRepositoryInterface;
 use App\Extension\TemplateManager;
 use Illuminate\Console\Command;
@@ -11,6 +12,7 @@ use Illuminate\Support\Facades\Log;
 class UpdateTemplateCommand extends Command
 {
     use HasProgressBar;
+    use HasUnifiedConfirm;
 
     /**
      * The name and signature of the console command.
@@ -18,7 +20,9 @@ class UpdateTemplateCommand extends Command
     protected $signature = 'template:update
         {identifier : 업데이트할 템플릿 식별자}
         {--layout-strategy=overwrite : 레이아웃 전략 (overwrite|keep)}
-        {--force : 버전 비교 없이 강제 업데이트}';
+        {--force : 버전 비교 없이 강제 업데이트}
+        {--source=auto : 업데이트 소스 (auto|bundled|github) — bundled 는 _bundled 만 사용(GitHub 우회)}
+        {--zip= : 외부 ZIP 파일 경로 (지정 시 GitHub/번들 우회 + 버전은 template.json 기준)}';
 
     /**
      * The console command description.
@@ -43,6 +47,8 @@ class UpdateTemplateCommand extends Command
         $identifier = $this->argument('identifier');
         $layoutStrategy = $this->option('layout-strategy');
         $force = $this->option('force');
+        $sourceOption = (string) $this->option('source');
+        $zipPath = $this->option('zip');
 
         // 레이아웃 전략 검증
         if (! in_array($layoutStrategy, ['overwrite', 'keep'])) {
@@ -51,6 +57,30 @@ class UpdateTemplateCommand extends Command
             return Command::FAILURE;
         }
 
+        if (! in_array($sourceOption, ['auto', 'bundled', 'github'], true)) {
+            $this->error('❌ --source 는 auto, bundled, github 중 하나여야 합니다.');
+
+            return Command::FAILURE;
+        }
+
+        if ($zipPath !== null && $sourceOption !== 'auto') {
+            $this->error('❌ --zip 은 --source 와 동시에 지정할 수 없습니다.');
+
+            return Command::FAILURE;
+        }
+
+        if ($zipPath !== null) {
+            $resolvedZip = realpath($zipPath);
+            if (! $resolvedZip || ! is_file($resolvedZip)) {
+                $this->error('❌ 지정된 ZIP 파일이 존재하지 않습니다: '.$zipPath);
+
+                return Command::FAILURE;
+            }
+            $zipPath = $resolvedZip;
+        }
+
+        $sourceOverride = $sourceOption === 'auto' ? null : $sourceOption;
+
         try {
             $this->templateManager->loadTemplates();
 
@@ -63,23 +93,29 @@ class UpdateTemplateCommand extends Command
                 return Command::FAILURE;
             }
 
-            // 업데이트 확인
-            $checkResult = $this->templateManager->checkTemplateUpdate($identifier);
+            // 업데이트 확인 (--zip 모드는 GitHub/번들 비교를 우회하므로 스킵)
+            if ($zipPath === null) {
+                $checkResult = $this->templateManager->checkTemplateUpdate($identifier);
 
-            if (! $checkResult['update_available'] && ! $force) {
-                $this->info('✅ '.__('templates.commands.update.no_update', ['template' => $identifier]));
+                if (! $checkResult['update_available'] && ! $force) {
+                    $this->info('✅ '.__('templates.commands.update.no_update', ['template' => $identifier]));
 
-                return Command::SUCCESS;
-            }
+                    return Command::SUCCESS;
+                }
 
-            // 업데이트 정보 표시
-            $this->info(__('templates.commands.update.current_version', ['version' => $checkResult['current_version']]));
+                // 업데이트 정보 표시
+                $this->info(__('templates.commands.update.current_version', ['version' => $checkResult['current_version']]));
 
-            if ($force && ! $checkResult['update_available']) {
-                $this->warn('⚠️  '.__('templates.commands.update.force_mode'));
+                if ($force && ! $checkResult['update_available']) {
+                    $this->warn('⚠️  '.__('templates.commands.update.force_mode'));
+                } else {
+                    $this->info(__('templates.commands.update.latest_version', ['version' => $checkResult['latest_version']]));
+                    $this->info(__('templates.commands.update.update_source', ['source' => $checkResult['update_source']]));
+                }
             } else {
-                $this->info(__('templates.commands.update.latest_version', ['version' => $checkResult['latest_version']]));
-                $this->info(__('templates.commands.update.update_source', ['source' => $checkResult['update_source']]));
+                $this->info(__('templates.commands.update.current_version', ['version' => $template->version]));
+                $this->info('업데이트 소스: ZIP ('.$zipPath.')');
+                $this->info('업데이트 버전: (template.json 추출 후 판별)');
             }
 
             $this->info(__('templates.commands.update.layout_strategy', ['strategy' => $layoutStrategy]));
@@ -106,7 +142,7 @@ class UpdateTemplateCommand extends Command
             $this->newLine();
 
             // 확인 프롬프트 (--force 시 건너뜀)
-            if (! $force && ! $this->confirm(__('templates.commands.update.confirm_question'), false)) {
+            if (! $force && ! $this->unifiedConfirm(__('templates.commands.update.confirm_question'), false)) {
                 $this->info(__('templates.commands.update.aborted'));
 
                 return Command::SUCCESS;
@@ -115,7 +151,7 @@ class UpdateTemplateCommand extends Command
             // 업데이트 실행
             $onProgress = $this->createProgressCallback(TemplateManager::UPDATE_STEPS);
             try {
-                $updateResult = $this->templateManager->updateTemplate($identifier, $layoutStrategy, $force, $onProgress);
+                $updateResult = $this->templateManager->updateTemplate($identifier, $force, $onProgress, $layoutStrategy, $sourceOverride, $zipPath);
                 $this->finishProgress();
             } catch (\Exception $e) {
                 $this->finishProgress();

app/Console/Commands/Traits/HasUnifiedConfirm.php

@@ -0,0 +1,86 @@
+<?php
+
+namespace App\Console\Commands\Traits;
+
+use App\Console\Helpers\ConsoleConfirm;
+use Symfony\Component\Console\Input\StreamableInputInterface;
+
+/**
+ * Laravel Command 컨텍스트에서 표준화된 yes/no 프롬프트를 제공하는 트레이트.
+ *
+ * Symfony QuestionHelper 를 거쳐 입력을 받기 때문에 Laravel 테스트의
+ * expectsQuestion() / expectsConfirmation() 헬퍼와 호환된다. 입력 정규화 및
+ * 재질문 루프는 ConsoleConfirm::parse() 와 공유한다.
+ *
+ * - `--no-interaction` 시: $default 즉시 반환
+ * - 응답을 받을 수 없는 실행(콘솔 없는 STDIN) 시: $default 즉시 반환
+ * - empty 입력 시: $default 반환
+ * - yes/y → true, no/n → false (대소문자 무시)
+ * - 그 외 입력: "yes, y, no, n 중 하나로 입력해 주세요." 출력 후 재질문
+ */
+trait HasUnifiedConfirm
+{
+    /**
+     * 표준 yes/no 프롬프트.
+     *
+     * @param  string  $question  질문 메시지
+     * @param  bool  $default  기본값 (true=[yes], false=[no])
+     */
+    protected function unifiedConfirm(string $question, bool $default = false): bool
+    {
+        if (! $this->input->isInteractive() || ! $this->canPromptForAnswer()) {
+            return $default;
+        }
+
+        $hint = $default ? '[yes]' : '[no]';
+        $prompt = "{$question} (yes/no) {$hint}";
+
+        while (true) {
+            // Symfony QuestionHelper 의 default 표시(`[default]`)를 회피하기 위해 default 를
+            // null 로 넘긴다. empty 입력 시 Symfony 가 null 반환 → ConsoleConfirm::parse 가
+            // empty 로 처리하여 자체 default 적용.
+            $raw = (string) $this->ask($prompt);
+            $parsed = ConsoleConfirm::parse($raw, $default);
+
+            if ($parsed !== null) {
+                return $parsed;
+            }
+
+            $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);
+    }
+}

app/Console/Commands/Traits/RebuildsSearchIndex.php

@@ -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]));
+        }
+    }
+}