feat(core): 정적 최적화 서버 대응 자산 URL 이중 모드

nginx 의 정규식 location 은 프리픽스 location 보다 먼저 매칭되므로,
`location ~* \.(js|css|json)$` 블록이 있는 서버에서는 확장자 붙은 동적
엔드포인트가 `try_files ... /index.php` 폴백이 실행될 기회 없이 404 가 된다.
aaPanel/CyberPanel/Plesk 기본 템플릿에 들어있어 드물지 않으며, 관리자 화면조차
뜨지 않아 "서버 설정을 고치세요" 안내가 순환 참조가 된다.

관례를 깬 쪽이 G7 이므로 해소 책임도 G7 에 두고, 두 형태를 모두 서빙한 뒤
환경에 따라 택일한다. 확장자 형태는 영구 유지한다 — 제거하면 URL 을 하드코딩한
서드파티 확장이 깨진다.

- 라우트: dualSuffix / dualSuffixSegment / dualAsset 매크로로 23개 엔드포인트와
 프로브를 이중 등록. 확장자 형태를 먼저 등록한다 — 확장자 없는 쪽이 더 느슨한
 패턴이라 순서가 뒤집히면 `.json` 요청까지 삼킨다
- URL 생성: 서버 App\Support\AssetUrl, 프론트 core/support/assetUrl.ts 로 집약.
 기본 모드에서 생성 결과는 치환 이전과 문자열까지 동일하다 (쿼리 순서 포함 —
 순서가 바뀌면 의미는 같아도 HTTP 캐시 키가 갈린다)
- 자가 복구: 부트스트랩 자산 로드 실패 시 확장자 없는 형태로 1회 단방향 전환.
 역방향 금지 + 기존 재시도 예산 공유로 무한 왕복을 막는다
- 감지·전환: 인스톨러 프로브(설치 시 확정) / 관리자 환경설정 일반 탭 /
 g7:asset-url-mode. 판정은 상태코드가 아니라 매직 토큰 + Content-Type 으로 한다.
 상태코드만 보면 "404 대신 200 + 에러 HTML" 환경에서 영원히 오판한다
- 봇은 JavaScript 를 실행하지 않아 자가 복구가 닿지 않으므로, 모드 변경 시
 SEO 프리렌더 캐시를 비워 재생성시킨다

가드: audit 룰 2종(dynamic-route-static-extension / asset-url-builder-required),
Playwright 6건(정적 블록 가로채기 시뮬레이션), 루프 방지 불변식 L1~L9 전수 red 증명.

부수 정리: 양 Composer 에 중복돼 있던 확장 에셋 수집 123줄을 트레이트로 통합하고,
자산 확장자 화이트리스트 누락(.map)과 경로 정규화 우회 가능성을 함께 교정.

sir.kr 커뮤니티의 hang 님께서 제보해주셨습니다.

app/Http/View/Composers/TemplateComposer.php

@@ -8,17 +8,18 @@ use App\Extension\PluginManager;
 use App\Extension\TemplateManager;
 use App\Extension\Traits\ClearsTemplateCaches;
 use App\Http\View\Composers\Traits\CollectsActiveExtensionMeta;
+use App\Http\View\Composers\Traits\CollectsExtensionAssets;
 use App\Http\View\Composers\Traits\CollectsTemplateExternals;
 use App\Services\ModuleSettingsService;
 use App\Services\PluginSettingsService;
 use App\Services\SettingsService;
 use App\Services\TemplateService;
-use Illuminate\Support\Facades\Log;
 use Illuminate\View\View;
 
 class TemplateComposer
 {
     use CollectsActiveExtensionMeta;
+    use CollectsExtensionAssets;
     use CollectsTemplateExternals;
 
     /**
@@ -115,156 +116,4 @@ class TemplateComposer
         $view->with('appConfig', $appConfig);
         $view->with('templateExternals', $templateExternals);
     }
-
-    /**
-     * 확장 프론트엔드 병합 번들 URL을 계산합니다.
-     *
-     * 활성 global 에셋(JS/CSS)이 하나라도 있는 타입만 해당 번들 URL을 채우고,
-     * 없으면 null을 두어 프론트가 로드를 스킵하게 한다. URL은 same-origin
-     * (`/api/...`)이어야 gdpr preblocker 의 same-origin 통과 규칙에 자기 차단되지
-     * 않는다(CDN 호스팅 금지).
-     *
-     * @param  array  $moduleAssets  수집된 모듈 개별 에셋 맵
-     * @param  array  $pluginAssets  수집된 플러그인 개별 에셋 맵
-     * @param  int  $version  확장 캐시 버전
-     * @return array{moduleJs: ?string, moduleCss: ?string, pluginJs: ?string, pluginCss: ?string}
-     */
-    private function buildExtensionBundleUrls(array $moduleAssets, array $pluginAssets, int $version): array
-    {
-        $hasJs = static fn (array $assets): bool => ! empty(array_filter($assets, fn ($a) => ! empty($a['js'])));
-        $hasCss = static fn (array $assets): bool => ! empty(array_filter($assets, fn ($a) => ! empty($a['css'])));
-
-        return [
-            'moduleJs' => $hasJs($moduleAssets) ? "/api/modules/bundle.js?v={$version}" : null,
-            'moduleCss' => $hasCss($moduleAssets) ? "/api/modules/bundle.css?v={$version}" : null,
-            'pluginJs' => $hasJs($pluginAssets) ? "/api/plugins/bundle.js?v={$version}" : null,
-            'pluginCss' => $hasCss($pluginAssets) ? "/api/plugins/bundle.css?v={$version}" : null,
-        ];
-    }
-
-    /**
-     * 활성화된 모듈의 프론트엔드 에셋 정보를 수집합니다.
-     *
-     * @return array<string, array{js?: string, css?: string, priority: int, external?: array}>
-     */
-    private function collectModuleAssets(): array
-    {
-        $assets = [];
-
-        try {
-            // ModuleManager에서 활성화된 모듈 목록 조회
-            $activeModules = $this->moduleManager->getActiveModules();
-
-            // 캐시 버전 조회 (브라우저 캐시 무효화용)
-            $cacheVersion = ClearsTemplateCaches::getExtensionCacheVersion();
-
-            foreach ($activeModules as $identifier => $module) {
-                // 모듈에 에셋이 있는지 확인
-                if (! $module->hasAssets()) {
-                    continue;
-                }
-
-                $builtPaths = $module->getBuiltAssetPaths();
-                $loadingConfig = $module->getAssetLoadingConfig();
-                $assetConfig = $module->getAssets();
-
-                // global 전략인 경우에만 수집 (layout, lazy는 레이아웃에서 처리)
-                if ($loadingConfig['strategy'] !== 'global') {
-                    continue;
-                }
-
-                $moduleAsset = [
-                    'priority' => $loadingConfig['priority'],
-                ];
-
-                // JS 빌드 경로 (캐시 버전 파라미터 추가)
-                if (! empty($builtPaths['js'])) {
-                    $moduleAsset['js'] = "/api/modules/assets/{$identifier}/".$builtPaths['js']."?v={$cacheVersion}";
-                }
-
-                // CSS 빌드 경로 (캐시 버전 파라미터 추가)
-                if (! empty($builtPaths['css'])) {
-                    $moduleAsset['css'] = "/api/modules/assets/{$identifier}/".$builtPaths['css']."?v={$cacheVersion}";
-                }
-
-                // 외부 스크립트 (조건부 로드용)
-                if (! empty($assetConfig['external'])) {
-                    $moduleAsset['external'] = $assetConfig['external'];
-                }
-
-                $assets[$identifier] = $moduleAsset;
-            }
-
-            // 우선순위 기준 정렬 (낮을수록 먼저)
-            uasort($assets, fn ($a, $b) => $a['priority'] <=> $b['priority']);
-        } catch (\Exception $e) {
-            // 에러 발생 시 빈 배열 반환 (에셋 로드 실패해도 앱 진행)
-            Log::warning('Failed to collect module assets: '.$e->getMessage());
-        }
-
-        return $assets;
-    }
-
-    /**
-     * 활성화된 플러그인의 프론트엔드 에셋 정보를 수집합니다.
-     *
-     * @return array<string, array{js?: string, css?: string, priority: int, external?: array}>
-     */
-    private function collectPluginAssets(): array
-    {
-        $assets = [];
-
-        try {
-            // PluginManager에서 활성화된 플러그인 목록 조회
-            $activePlugins = $this->pluginManager->getActivePlugins();
-
-            // 캐시 버전 조회 (브라우저 캐시 무효화용)
-            $cacheVersion = ClearsTemplateCaches::getExtensionCacheVersion();
-
-            foreach ($activePlugins as $identifier => $plugin) {
-                // 플러그인에 에셋이 있는지 확인
-                if (! $plugin->hasAssets()) {
-                    continue;
-                }
-
-                $builtPaths = $plugin->getBuiltAssetPaths();
-                $loadingConfig = $plugin->getAssetLoadingConfig();
-                $assetConfig = $plugin->getAssets();
-
-                // global 전략인 경우에만 수집 (layout, lazy는 레이아웃에서 처리)
-                if ($loadingConfig['strategy'] !== 'global') {
-                    continue;
-                }
-
-                $pluginAsset = [
-                    'priority' => $loadingConfig['priority'],
-                ];
-
-                // JS 빌드 경로 (캐시 버전 파라미터 추가)
-                if (! empty($builtPaths['js'])) {
-                    $pluginAsset['js'] = "/api/plugins/assets/{$identifier}/".$builtPaths['js']."?v={$cacheVersion}";
-                }
-
-                // CSS 빌드 경로 (캐시 버전 파라미터 추가)
-                if (! empty($builtPaths['css'])) {
-                    $pluginAsset['css'] = "/api/plugins/assets/{$identifier}/".$builtPaths['css']."?v={$cacheVersion}";
-                }
-
-                // 외부 스크립트 (조건부 로드용)
-                if (! empty($assetConfig['external'])) {
-                    $pluginAsset['external'] = $assetConfig['external'];
-                }
-
-                $assets[$identifier] = $pluginAsset;
-            }
-
-            // 우선순위 기준 정렬 (낮을수록 먼저)
-            uasort($assets, fn ($a, $b) => $a['priority'] <=> $b['priority']);
-        } catch (\Exception $e) {
-            // 에러 발생 시 빈 배열 반환 (에셋 로드 실패해도 앱 진행)
-            Log::warning('Failed to collect plugin assets: '.$e->getMessage());
-        }
-
-        return $assets;
-    }
 }

app/Http/View/Composers/Traits/CollectsExtensionAssets.php

@@ -0,0 +1,143 @@
+<?php
+
+namespace App\Http\View\Composers\Traits;
+
+use App\Extension\Traits\ClearsTemplateCaches;
+use App\Support\AssetUrl;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * 활성 확장(모듈·플러그인)의 프론트엔드 에셋 수집 및 번들 URL 생성.
+ *
+ * `TemplateComposer`(admin)와 `UserTemplateComposer`(user)가 공유한다. 두 클래스는
+ * 이 세 메서드를 주석까지 통째로 중복 보유하고 있었고(123줄), 그래서 한쪽만 고치면
+ * 다른 쪽이 조용히 어긋나는 구조였다. 트레이트로 승격해 그 가능성을 제거한다.
+ *
+ * URL 생성은 전부 `AssetUrl` 을 경유한다 — 자산 URL 이중 모드(확장자 유지/제거)를
+ * 한 곳에서 결정하기 위함이다.
+ *
+ * 사용하는 클래스는 `$moduleManager` / `$pluginManager` 프로퍼티를 가져야 한다.
+ *
+ * @see AssetUrl
+ */
+trait CollectsExtensionAssets
+{
+    /**
+     * 확장 병합 번들 URL 을 생성합니다.
+     *
+     * 병합 번들은 same-origin(`/api/...`)이어야 한다. 외부 origin/CDN 은 GDPR
+     * 프리블로커에 자기 차단되므로 호스팅하지 않는다.
+     *
+     * @param  array<string, mixed>  $moduleAssets  수집된 모듈 개별 에셋 맵
+     * @param  array<string, mixed>  $pluginAssets  수집된 플러그인 개별 에셋 맵
+     * @param  int  $version  확장 캐시 버전
+     * @return array{moduleJs: ?string, moduleCss: ?string, pluginJs: ?string, pluginCss: ?string} 번들 URL 맵
+     */
+    private function buildExtensionBundleUrls(array $moduleAssets, array $pluginAssets, int $version): array
+    {
+        $hasJs = static fn (array $assets): bool => ! empty(array_filter($assets, fn ($a) => ! empty($a['js'])));
+        $hasCss = static fn (array $assets): bool => ! empty(array_filter($assets, fn ($a) => ! empty($a['css'])));
+
+        return [
+            'moduleJs' => $hasJs($moduleAssets) ? AssetUrl::extensionBundle('modules', 'js', $version) : null,
+            'moduleCss' => $hasCss($moduleAssets) ? AssetUrl::extensionBundle('modules', 'css', $version) : null,
+            'pluginJs' => $hasJs($pluginAssets) ? AssetUrl::extensionBundle('plugins', 'js', $version) : null,
+            'pluginCss' => $hasCss($pluginAssets) ? AssetUrl::extensionBundle('plugins', 'css', $version) : null,
+        ];
+    }
+
+    /**
+     * 활성화된 모듈의 프론트엔드 에셋 정보를 수집합니다.
+     *
+     * @return array<string, array{js?: string, css?: string, priority: int, external?: array}> 식별자별 에셋 맵
+     */
+    private function collectModuleAssets(): array
+    {
+        return $this->collectExtensionAssets(
+            'modules',
+            fn () => $this->moduleManager->getActiveModules(),
+            'Failed to collect module assets: '
+        );
+    }
+
+    /**
+     * 활성화된 플러그인의 프론트엔드 에셋 정보를 수집합니다.
+     *
+     * @return array<string, array{js?: string, css?: string, priority: int, external?: array}> 식별자별 에셋 맵
+     */
+    private function collectPluginAssets(): array
+    {
+        return $this->collectExtensionAssets(
+            'plugins',
+            fn () => $this->pluginManager->getActivePlugins(),
+            'Failed to collect plugin assets: '
+        );
+    }
+
+    /**
+     * 확장 에셋 수집 공통 구현.
+     *
+     * 모듈/플러그인은 수집 대상 조회 방법과 로그 문구만 다르고 나머지 로직이 동일하다.
+     *
+     * @param  string  $type  `modules` 또는 `plugins`
+     * @param  callable  $activeResolver  활성 확장 목록을 반환하는 콜백
+     * @param  string  $logPrefix  실패 시 경고 로그 접두사
+     * @return array<string, array{js?: string, css?: string, priority: int, external?: array}> 식별자별 에셋 맵
+     */
+    private function collectExtensionAssets(string $type, callable $activeResolver, string $logPrefix): array
+    {
+        $assets = [];
+
+        try {
+            $active = $activeResolver();
+
+            // 캐시 버전 조회 (브라우저 캐시 무효화용)
+            $cacheVersion = ClearsTemplateCaches::getExtensionCacheVersion();
+
+            foreach ($active as $identifier => $extension) {
+                // 확장에 에셋이 있는지 확인
+                if (! $extension->hasAssets()) {
+                    continue;
+                }
+
+                $builtPaths = $extension->getBuiltAssetPaths();
+                $loadingConfig = $extension->getAssetLoadingConfig();
+                $assetConfig = $extension->getAssets();
+
+                // global 전략인 경우에만 수집 (layout, lazy는 레이아웃에서 처리)
+                if ($loadingConfig['strategy'] !== 'global') {
+                    continue;
+                }
+
+                $asset = [
+                    'priority' => $loadingConfig['priority'],
+                ];
+
+                // JS 빌드 경로 (캐시 버전 파라미터 추가)
+                if (! empty($builtPaths['js'])) {
+                    $asset['js'] = AssetUrl::extensionAsset($type, $identifier, $builtPaths['js'], $cacheVersion);
+                }
+
+                // CSS 빌드 경로 (캐시 버전 파라미터 추가)
+                if (! empty($builtPaths['css'])) {
+                    $asset['css'] = AssetUrl::extensionAsset($type, $identifier, $builtPaths['css'], $cacheVersion);
+                }
+
+                // 외부 스크립트 (조건부 로드용)
+                if (! empty($assetConfig['external'])) {
+                    $asset['external'] = $assetConfig['external'];
+                }
+
+                $assets[$identifier] = $asset;
+            }
+
+            // 우선순위 기준 정렬 (낮을수록 먼저)
+            uasort($assets, fn ($a, $b) => $a['priority'] <=> $b['priority']);
+        } catch (\Exception $e) {
+            // 에러 발생 시 빈 배열 반환 (에셋 로드 실패해도 앱 진행)
+            Log::warning($logPrefix.$e->getMessage());
+        }
+
+        return $assets;
+    }
+}

app/Http/View/Composers/UserTemplateComposer.php

@@ -8,12 +8,12 @@ use App\Extension\PluginManager;
 use App\Extension\TemplateManager;
 use App\Extension\Traits\ClearsTemplateCaches;
 use App\Http\View\Composers\Traits\CollectsActiveExtensionMeta;
+use App\Http\View\Composers\Traits\CollectsExtensionAssets;
 use App\Http\View\Composers\Traits\CollectsTemplateExternals;
 use App\Services\ModuleSettingsService;
 use App\Services\PluginSettingsService;
 use App\Services\SettingsService;
 use App\Services\TemplateService;
-use Illuminate\Support\Facades\Log;
 use Illuminate\View\View;
 
 /**
@@ -24,6 +24,7 @@ use Illuminate\View\View;
 class UserTemplateComposer
 {
     use CollectsActiveExtensionMeta;
+    use CollectsExtensionAssets;
     use CollectsTemplateExternals;
 
     /**
@@ -121,156 +122,4 @@ class UserTemplateComposer
         $view->with('appConfig', $appConfig);
         $view->with('templateExternals', $templateExternals);
     }
-
-    /**
-     * 확장 프론트엔드 병합 번들 URL을 계산합니다.
-     *
-     * 활성 global 에셋(JS/CSS)이 하나라도 있는 타입만 해당 번들 URL을 채우고,
-     * 없으면 null을 두어 프론트가 로드를 스킵하게 한다. URL은 same-origin
-     * (`/api/...`)이어야 gdpr preblocker 의 same-origin 통과 규칙에 자기 차단되지
-     * 않는다(CDN 호스팅 금지).
-     *
-     * @param  array  $moduleAssets  수집된 모듈 개별 에셋 맵
-     * @param  array  $pluginAssets  수집된 플러그인 개별 에셋 맵
-     * @param  int  $version  확장 캐시 버전
-     * @return array{moduleJs: ?string, moduleCss: ?string, pluginJs: ?string, pluginCss: ?string}
-     */
-    private function buildExtensionBundleUrls(array $moduleAssets, array $pluginAssets, int $version): array
-    {
-        $hasJs = static fn (array $assets): bool => ! empty(array_filter($assets, fn ($a) => ! empty($a['js'])));
-        $hasCss = static fn (array $assets): bool => ! empty(array_filter($assets, fn ($a) => ! empty($a['css'])));
-
-        return [
-            'moduleJs' => $hasJs($moduleAssets) ? "/api/modules/bundle.js?v={$version}" : null,
-            'moduleCss' => $hasCss($moduleAssets) ? "/api/modules/bundle.css?v={$version}" : null,
-            'pluginJs' => $hasJs($pluginAssets) ? "/api/plugins/bundle.js?v={$version}" : null,
-            'pluginCss' => $hasCss($pluginAssets) ? "/api/plugins/bundle.css?v={$version}" : null,
-        ];
-    }
-
-    /**
-     * 활성화된 모듈의 프론트엔드 에셋 정보를 수집합니다.
-     *
-     * @return array<string, array{js?: string, css?: string, priority: int, external?: array}>
-     */
-    private function collectModuleAssets(): array
-    {
-        $assets = [];
-
-        try {
-            // ModuleManager에서 활성화된 모듈 목록 조회
-            $activeModules = $this->moduleManager->getActiveModules();
-
-            // 캐시 버전 조회 (브라우저 캐시 무효화용)
-            $cacheVersion = ClearsTemplateCaches::getExtensionCacheVersion();
-
-            foreach ($activeModules as $identifier => $module) {
-                // 모듈에 에셋이 있는지 확인
-                if (! $module->hasAssets()) {
-                    continue;
-                }
-
-                $builtPaths = $module->getBuiltAssetPaths();
-                $loadingConfig = $module->getAssetLoadingConfig();
-                $assetConfig = $module->getAssets();
-
-                // global 전략인 경우에만 수집 (layout, lazy는 레이아웃에서 처리)
-                if ($loadingConfig['strategy'] !== 'global') {
-                    continue;
-                }
-
-                $moduleAsset = [
-                    'priority' => $loadingConfig['priority'],
-                ];
-
-                // JS 빌드 경로 (캐시 버전 파라미터 추가)
-                if (! empty($builtPaths['js'])) {
-                    $moduleAsset['js'] = "/api/modules/assets/{$identifier}/".$builtPaths['js']."?v={$cacheVersion}";
-                }
-
-                // CSS 빌드 경로 (캐시 버전 파라미터 추가)
-                if (! empty($builtPaths['css'])) {
-                    $moduleAsset['css'] = "/api/modules/assets/{$identifier}/".$builtPaths['css']."?v={$cacheVersion}";
-                }
-
-                // 외부 스크립트 (조건부 로드용)
-                if (! empty($assetConfig['external'])) {
-                    $moduleAsset['external'] = $assetConfig['external'];
-                }
-
-                $assets[$identifier] = $moduleAsset;
-            }
-
-            // 우선순위 기준 정렬 (낮을수록 먼저)
-            uasort($assets, fn ($a, $b) => $a['priority'] <=> $b['priority']);
-        } catch (\Exception $e) {
-            // 에러 발생 시 빈 배열 반환 (에셋 로드 실패해도 앱 진행)
-            Log::warning('Failed to collect module assets: '.$e->getMessage());
-        }
-
-        return $assets;
-    }
-
-    /**
-     * 활성화된 플러그인의 프론트엔드 에셋 정보를 수집합니다.
-     *
-     * @return array<string, array{js?: string, css?: string, priority: int, external?: array}>
-     */
-    private function collectPluginAssets(): array
-    {
-        $assets = [];
-
-        try {
-            // PluginManager에서 활성화된 플러그인 목록 조회
-            $activePlugins = $this->pluginManager->getActivePlugins();
-
-            // 캐시 버전 조회 (브라우저 캐시 무효화용)
-            $cacheVersion = ClearsTemplateCaches::getExtensionCacheVersion();
-
-            foreach ($activePlugins as $identifier => $plugin) {
-                // 플러그인에 에셋이 있는지 확인
-                if (! $plugin->hasAssets()) {
-                    continue;
-                }
-
-                $builtPaths = $plugin->getBuiltAssetPaths();
-                $loadingConfig = $plugin->getAssetLoadingConfig();
-                $assetConfig = $plugin->getAssets();
-
-                // global 전략인 경우에만 수집 (layout, lazy는 레이아웃에서 처리)
-                if ($loadingConfig['strategy'] !== 'global') {
-                    continue;
-                }
-
-                $pluginAsset = [
-                    'priority' => $loadingConfig['priority'],
-                ];
-
-                // JS 빌드 경로 (캐시 버전 파라미터 추가)
-                if (! empty($builtPaths['js'])) {
-                    $pluginAsset['js'] = "/api/plugins/assets/{$identifier}/".$builtPaths['js']."?v={$cacheVersion}";
-                }
-
-                // CSS 빌드 경로 (캐시 버전 파라미터 추가)
-                if (! empty($builtPaths['css'])) {
-                    $pluginAsset['css'] = "/api/plugins/assets/{$identifier}/".$builtPaths['css']."?v={$cacheVersion}";
-                }
-
-                // 외부 스크립트 (조건부 로드용)
-                if (! empty($assetConfig['external'])) {
-                    $pluginAsset['external'] = $assetConfig['external'];
-                }
-
-                $assets[$identifier] = $pluginAsset;
-            }
-
-            // 우선순위 기준 정렬 (낮을수록 먼저)
-            uasort($assets, fn ($a, $b) => $a['priority'] <=> $b['priority']);
-        } catch (\Exception $e) {
-            // 에러 발생 시 빈 배열 반환 (에셋 로드 실패해도 앱 진행)
-            Log::warning('Failed to collect plugin assets: '.$e->getMessage());
-        }
-
-        return $assets;
-    }
 }