HeuJung
bd215bc586
메일 인증 대신 휴대폰 본인확인을 쓸 수 있게 하는 플러그인을 추가한다. 가입·비밀번호 재설정·성인인증 등 코어 IDV 가 강제하는 모든 지점에서 동작하며, 테스트 모드로 계약 없이 전 흐름을 확인할 수 있다. 구현·검수 과정에서 드러난 저장소 전역 결함을 함께 처리했다. - 외래키 컬럼의 한국어 comment 가 방출되지 않던 문제 (소스 38건 교정 + 기설치본 백필 업그레이드 스텝 7종). ->comment 를 ->constrained 뒤에 체인하면 예외 없이 통과하면서 comment 가 조용히 사라진다 - 로케일 전환 후 확장 액션 핸들러가 소실되던 문제 (플러그인 3종에 재등록 진입점 노출) - 본인인증 상태 폴링 응답이 누적 시도 횟수를 함께 내보내던 문제 - 인증 안내 문구와 실제 진행 방식의 폭 경계 불일치 (768~1023px). 엔진과 같은 값을 같은 방법으로 읽도록 교정 - transition_overlay_target 이 replace 없이 무효이던 관리자 목록 40곳. 로딩 표시가 나오지 않아도 경고가 남지 않아 화면을 봐야만 알 수 있었다 두 인증 플러그인의 코어 최소 요구 버전을 7.0.6 으로 올린다. 운영 모드 자격증명 필수 검사가 7.0.6 의 설정 저장 검증 표면에 의존하며, 그보다 낮은 코어에서는 그 검사가 조용히 통과해 빈 자격증명으로 저장할 수 있었다. 재발 차단으로 정적 검사 룰 4종을 신설하고, 검사 도구가 미커밋 신규 확장을 "검사 파일 0" 으로 통과시키던 사각을 함께 막았다.
601 lines
19 KiB
Markdown
601 lines
19 KiB
Markdown
# 모듈 프론트엔드 에셋 시스템
|
||
|
||
> 이 문서는 G7의 모듈 프론트엔드 에셋 로딩 시스템을 다룹니다.
|
||
|
||
---
|
||
|
||
## TL;DR (5초 요약)
|
||
|
||
```text
|
||
1. module.json에 에셋 매니페스트 정의 (js, css, loading strategy)
|
||
2. Vite IIFE 빌드로 dist/에 번들 생성
|
||
3. TemplateApp 초기화 시 자동 로드 (global 전략)
|
||
4. 핸들러 네이밍: {module-identifier}.{handler-name}
|
||
5. 빌드 명령: php artisan module:build [identifier] (기본: _bundled, --active로 활성)
|
||
```
|
||
|
||
---
|
||
|
||
## 목차
|
||
|
||
- [개요](#개요)
|
||
- [에셋 매니페스트 스키마](#에셋-매니페스트-스키마)
|
||
- [모듈 프론트엔드 구조](#모듈-프론트엔드-구조)
|
||
- [핸들러 등록](#핸들러-등록)
|
||
- [빌드 및 배포](#빌드-및-배포)
|
||
- [에셋 로딩 전략](#에셋-로딩-전략)
|
||
- [외부 라이브러리](#외부-라이브러리)
|
||
- [관련 문서](#관련-문서)
|
||
|
||
---
|
||
|
||
## 개요
|
||
|
||
모듈/플러그인은 자체 프론트엔드 에셋(JS, CSS, 이미지, 폰트 등)을 포함할 수 있습니다.
|
||
이 시스템은 활성화된 모듈의 에셋을 동적으로 로드하여 ActionDispatcher에 핸들러를 등록합니다.
|
||
|
||
### 작동 원리
|
||
|
||
```
|
||
1. admin.blade.php 렌더링
|
||
└─ window.G7Config.moduleAssets 주입
|
||
|
||
2. TemplateApp.init()
|
||
└─ ModuleAssetLoader.loadActiveExtensionAssets()
|
||
├─ CSS 로드 (병렬)
|
||
└─ JS 로드 (병렬 fetch + 순차 실행)
|
||
├─ priority 오름차순 정렬 후 DOM append
|
||
├─ script.async = false → 삽입 순서대로 실행 보장 (HTML 사양)
|
||
└─ 각 모듈의 initModule() 실행
|
||
└─ ActionDispatcher.registerHandler()
|
||
|
||
3. 레이아웃 렌더링
|
||
└─ 모듈 핸들러 사용 가능
|
||
```
|
||
|
||
> **성능 참고**: JS 번들은 `Promise.all` 로 병렬 fetch 되며, `script.async = false` 와
|
||
> priority 정렬된 DOM append 순서로 **실행 순서는 유지**됩니다. N 개의 확장 IIFE 로딩이
|
||
> N × (fetch 시간) 에서 max(fetch 시간) 으로 단축됩니다. 단, 확장 간 런타임 의존성
|
||
> (다른 확장의 window 전역/핸들러 참조) 이 발생하면 priority 필드로 실행 순서를 명시해야 합니다.
|
||
|
||
---
|
||
|
||
## 에셋 매니페스트 스키마
|
||
|
||
### module.json (통합 스키마)
|
||
|
||
모듈 루트에 `module.json` 파일을 생성합니다. 메타데이터와 에셋 설정이 하나의 파일에 통합되어 있습니다.
|
||
|
||
```json
|
||
{
|
||
"identifier": "sirsoft-ecommerce",
|
||
"vendor": "sirsoft",
|
||
"name": {
|
||
"ko": "이커머스",
|
||
"en": "Ecommerce"
|
||
},
|
||
"version": "1.0.0",
|
||
"description": {
|
||
"ko": "상품 및 주문 관리를 위한 이커머스 모듈",
|
||
"en": "E-commerce module for product and order management"
|
||
},
|
||
"g7_version": ">=1.0.0",
|
||
"dependencies": {
|
||
"modules": {},
|
||
"plugins": {}
|
||
},
|
||
"github_url": null,
|
||
"github_changelog_url": null,
|
||
"assets": {
|
||
"js": {
|
||
"entry": "resources/js/index.ts",
|
||
"output": "dist/js/module.iife.js"
|
||
},
|
||
"css": {
|
||
"entry": "resources/css/main.css",
|
||
"output": "dist/css/module.css"
|
||
},
|
||
"handlers": true,
|
||
"static": "resources/assets/"
|
||
},
|
||
"loading": {
|
||
"strategy": "global",
|
||
"priority": 100
|
||
}
|
||
}
|
||
```
|
||
|
||
> **참고**: `identifier`, `vendor`는 디렉토리명에서 자동 추론되므로 생략 가능합니다.
|
||
> `name`, `version`, `description`은 AbstractModule에서 자동 파싱됩니다.
|
||
|
||
### 스키마 설명
|
||
|
||
#### 메타데이터 필드
|
||
|
||
| 필드 | 타입 | 필수 | 설명 |
|
||
|------|------|------|------|
|
||
| `identifier` | `string` | 선택 | 모듈 식별자 (디렉토리명에서 자동 추론) |
|
||
| `vendor` | `string` | 선택 | 벤더명 (identifier에서 자동 추론) |
|
||
| `name` | `string\|object` | 필수 | 모듈명 (다국어: `{"ko": "...", "en": "..."}`) |
|
||
| `version` | `string` | 필수 | 시맨틱 버전 (예: `1.0.0`) |
|
||
| `description` | `string\|object` | 필수 | 모듈 설명 (다국어 지원) |
|
||
| `g7_version` | `string` | 선택 | 그누보드7 코어 버전 제약 (예: `>=1.0.0`) |
|
||
| `dependencies` | `object` | 선택 | 모듈/플러그인 의존성 |
|
||
| `github_url` | `string\|null` | 선택 | GitHub 저장소 URL (업데이트 감지용) |
|
||
| `github_changelog_url` | `string\|null` | 선택 | GitHub 변경 이력 URL |
|
||
|
||
#### 에셋 필드
|
||
|
||
| 필드 | 설명 |
|
||
|------|------|
|
||
| `assets.js.entry` | JS 소스 엔트리 포인트 |
|
||
| `assets.js.output` | 빌드된 JS 출력 경로 |
|
||
| `assets.css.entry` | CSS 소스 엔트리 포인트 |
|
||
| `assets.css.output` | 빌드된 CSS 출력 경로 |
|
||
| `assets.handlers` | 핸들러 포함 여부 |
|
||
| `assets.static` | 정적 에셋 소스 디렉토리 |
|
||
| `loading.strategy` | 로딩 전략 (global, layout, lazy) |
|
||
| `loading.priority` | 로드 우선순위 (낮을수록 먼저) |
|
||
|
||
---
|
||
|
||
## 모듈 프론트엔드 구조
|
||
|
||
### 디렉토리 구조
|
||
|
||
```
|
||
modules/_bundled/sirsoft-ecommerce/
|
||
├── module.json ← 에셋 매니페스트
|
||
├── package.json ← npm 패키지 정의
|
||
├── vite.config.ts ← Vite 빌드 설정
|
||
├── tsconfig.json ← TypeScript 설정
|
||
├── dist/ ← 빌드 출력 (git ignore)
|
||
│ ├── js/module.iife.js
|
||
│ ├── css/module.css
|
||
│ └── assets/
|
||
│ ├── fonts/
|
||
│ └── images/
|
||
├── resources/
|
||
│ ├── js/ ← JS 소스
|
||
│ │ ├── index.ts
|
||
│ │ ├── types.ts
|
||
│ │ └── handlers/
|
||
│ │ ├── index.ts
|
||
│ │ └── updateProductField.ts
|
||
│ ├── css/main.css ← CSS 소스
|
||
│ └── assets/ ← 정적 에셋 소스
|
||
│ ├── fonts/
|
||
│ └── images/
|
||
└── ...
|
||
```
|
||
|
||
### package.json
|
||
|
||
```json
|
||
{
|
||
"name": "sirsoft-ecommerce",
|
||
"version": "1.0.0",
|
||
"private": true,
|
||
"type": "module",
|
||
"scripts": {
|
||
"dev": "vite build --watch",
|
||
"build": "vite build"
|
||
},
|
||
"devDependencies": {
|
||
"typescript": "^5.0.0",
|
||
"vite": "^6.0.0"
|
||
}
|
||
}
|
||
```
|
||
|
||
### vite.config.ts
|
||
|
||
```typescript
|
||
import { defineConfig } from 'vite';
|
||
import path from 'path';
|
||
|
||
export default defineConfig({
|
||
build: {
|
||
lib: {
|
||
entry: path.resolve(__dirname, 'resources/js/index.ts'),
|
||
name: 'SirsoftEcommerce',
|
||
fileName: 'module',
|
||
formats: ['iife'],
|
||
},
|
||
outDir: 'dist',
|
||
rollupOptions: {
|
||
output: {
|
||
entryFileNames: 'js/[name].iife.js',
|
||
assetFileNames: (assetInfo) => {
|
||
if (assetInfo.name?.endsWith('.css')) {
|
||
return 'css/[name][extname]';
|
||
}
|
||
return 'assets/[name][extname]';
|
||
},
|
||
},
|
||
},
|
||
emptyOutDir: true,
|
||
minify: true,
|
||
sourcemap: true,
|
||
},
|
||
resolve: {
|
||
alias: {
|
||
'@': path.resolve(__dirname, 'resources/js'),
|
||
},
|
||
},
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 핸들러 등록
|
||
|
||
### 모듈 엔트리 파일 (index.ts)
|
||
|
||
```typescript
|
||
import '../css/main.css';
|
||
import { handlerMap } from './handlers';
|
||
|
||
const MODULE_IDENTIFIER = 'sirsoft-ecommerce';
|
||
|
||
export function initModule(): void {
|
||
const registerHandlers = () => {
|
||
const actionDispatcher = (window as any).G7Core?.getActionDispatcher?.();
|
||
|
||
if (actionDispatcher) {
|
||
Object.entries(handlerMap).forEach(([name, handler]) => {
|
||
const fullName = `${MODULE_IDENTIFIER}.${name}`;
|
||
actionDispatcher.registerHandler(fullName, handler);
|
||
});
|
||
console.log(`[Module:${MODULE_IDENTIFIER}] Handlers registered`);
|
||
} else {
|
||
// ActionDispatcher 초기화 대기
|
||
setTimeout(registerHandlers, 100);
|
||
}
|
||
};
|
||
|
||
if (document.readyState === 'complete') {
|
||
registerHandlers();
|
||
} else {
|
||
window.addEventListener('load', registerHandlers);
|
||
}
|
||
}
|
||
|
||
// IIFE 빌드 시 즉시 실행
|
||
initModule();
|
||
|
||
// 코어 재초기화 시 재등록 진입점 노출 (아래 "코어 재초기화 시 핸들러 재등록" 참조)
|
||
(window as any).__SirsoftEcommerce = {
|
||
identifier: MODULE_IDENTIFIER,
|
||
initModule,
|
||
};
|
||
```
|
||
|
||
### 코어 재초기화 시 핸들러 재등록
|
||
|
||
로케일 전환처럼 `TemplateApp` 이 다시 초기화되는 시점에 ActionDispatcher 는 **새 인스턴스로 교체**된다.
|
||
이때 앞서 등록해 둔 확장 핸들러는 전부 사라지므로, 코어가 각 확장에 재등록을 요청한다.
|
||
요청 방식은 **window 전역 객체에서 약속된 이름의 함수를 찾아 호출**하는 것 하나뿐이다.
|
||
|
||
| 확장 타입 | 전역 객체 | 재등록 진입점 |
|
||
| --- | --- | --- |
|
||
| 모듈 | `window.__[ModuleName]` | `initModule()` |
|
||
| 플러그인 | `window.__[PluginName]` | `initPlugin()` |
|
||
| 템플릿 | `window.G7TemplateHandlers` | 코어가 직접 재등록 (확장 작업 불필요) |
|
||
|
||
```typescript
|
||
// 플러그인 엔트리 파일 (index.ts)
|
||
function initPlugin(): void {
|
||
registerHandlersWithRetry(); // 핸들러 재등록만 수행
|
||
}
|
||
|
||
initPlugin();
|
||
|
||
(window as any).__SirsoftDaumPostcode = {
|
||
identifier: PLUGIN_IDENTIFIER,
|
||
initPlugin,
|
||
};
|
||
```
|
||
|
||
이름은 고정이다. 전역 객체를 노출하지 않거나 진입점 이름이 다르면(`init`, `bootstrap`, `setup` 등)
|
||
코어는 그 확장을 재등록 대상에서 조용히 건너뛴다. 그 결과는 다음과 같다:
|
||
|
||
- 사용자가 언어를 한 번 바꾼 뒤부터 해당 확장의 모든 액션이 **무반응**이 된다
|
||
- 핸들러가 없으므로 dispatch 는 그대로 무시된다 — 콘솔 에러도, 토스트도, 네트워크 요청도 없다
|
||
- 새로고침하면 정상으로 돌아오므로 재현 조건을 모르면 원인 추적이 어렵다
|
||
|
||
진입점은 **핸들러 재등록만** 수행한다. 최초 진입 1회로 충분한 작업(리다이렉트 복귀 처리,
|
||
MutationObserver·인터셉터 설치, DOM 주입 등)은 넣지 않는다 — 재초기화마다 중복 실행된다.
|
||
|
||
### 핸들러 정의
|
||
|
||
```typescript
|
||
// handlers/updateProductField.ts
|
||
import type { ActionContext } from '@/types';
|
||
|
||
interface UpdateProductFieldParams {
|
||
productId: string | number;
|
||
field: string;
|
||
value: string | number | boolean;
|
||
stateKey?: string;
|
||
}
|
||
|
||
export function updateProductFieldHandler(
|
||
params: UpdateProductFieldParams,
|
||
context: ActionContext
|
||
): void {
|
||
const { productId, field, value, stateKey = 'products' } = params;
|
||
|
||
// setState를 통해 상태 업데이트
|
||
if (context.setState) {
|
||
context.setState({
|
||
[stateKey]: {
|
||
_modified: {
|
||
[productId]: { [field]: value }
|
||
}
|
||
}
|
||
});
|
||
}
|
||
}
|
||
|
||
// handlers/index.ts
|
||
import { updateProductFieldHandler } from './updateProductField';
|
||
import { updateOptionFieldHandler } from './updateOptionField';
|
||
import type { ActionHandler } from '@/types';
|
||
|
||
export const handlerMap: Record<string, ActionHandler> = {
|
||
updateProductField: updateProductFieldHandler,
|
||
updateOptionField: updateOptionFieldHandler,
|
||
};
|
||
```
|
||
|
||
### 레이아웃에서 핸들러 사용
|
||
|
||
```json
|
||
{
|
||
"component": "Input",
|
||
"props": {
|
||
"type": "number",
|
||
"value": "{{row.stock_quantity}}"
|
||
},
|
||
"events": {
|
||
"onBlur": {
|
||
"handler": "sirsoft-ecommerce.updateProductField",
|
||
"params": {
|
||
"productId": "{{row.id}}",
|
||
"field": "stock_quantity",
|
||
"value": "{{$event.target.value}}"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 빌드 및 배포
|
||
|
||
### Artisan 커맨드
|
||
|
||
```bash
|
||
# _bundled에서 빌드 (기본값)
|
||
php artisan module:build sirsoft-ecommerce
|
||
|
||
# 모든 _bundled 모듈 빌드
|
||
php artisan module:build --all
|
||
|
||
# 프로덕션 빌드 (_bundled)
|
||
php artisan module:build sirsoft-ecommerce --production
|
||
|
||
# 파일 감시 모드 (활성 디렉토리에서 자동 실행)
|
||
php artisan module:build sirsoft-ecommerce --watch
|
||
|
||
# 활성 디렉토리에서 빌드
|
||
php artisan module:build sirsoft-ecommerce --active
|
||
|
||
# 빌드 후 활성 디렉토리 반영
|
||
php artisan module:update sirsoft-ecommerce
|
||
```
|
||
|
||
### npm 스크립트
|
||
|
||
```bash
|
||
# 모듈 디렉토리에서 직접 실행
|
||
cd modules/_bundled/sirsoft-ecommerce
|
||
npm install
|
||
npm run build
|
||
|
||
# 개발 모드 (파일 감시)
|
||
npm run dev
|
||
```
|
||
|
||
### 에셋 서빙 API
|
||
|
||
빌드된 에셋은 다음 API를 통해 서빙됩니다:
|
||
|
||
```
|
||
GET /api/modules/assets/{identifier}/{path}
|
||
|
||
예시:
|
||
/api/modules/assets/sirsoft-ecommerce/dist/js/module.iife.js
|
||
/api/modules/assets/sirsoft-ecommerce/dist/css/module.css
|
||
```
|
||
|
||
---
|
||
|
||
## 서버측 번들 병합 (Server-side Bundle)
|
||
|
||
활성 모듈/플러그인이 늘어날수록 개별 IIFE JS/CSS 요청이 선형 증가한다. 이를 줄이기 위해 코어는 타입별(모듈/플러그인)로 활성 `global` 에셋을 서버에서 하나의 번들로 병합해 서빙한다. 각 확장 IIFE 는 자체 클로저에서 자가등록(레지스트리 + 핸들러/리스너)을 수행하므로, priority 순으로 이어붙여 단일 `<script>` 로 실행해도 등록 동작은 동일하다.
|
||
|
||
### 서빙 엔드포인트
|
||
|
||
```
|
||
GET /api/modules/bundle.js?v={version}
|
||
GET /api/modules/bundle.css?v={version}
|
||
GET /api/plugins/bundle.js?v={version}
|
||
GET /api/plugins/bundle.css?v={version}
|
||
```
|
||
|
||
`{version}` = 확장 캐시 버전(`ClearsTemplateCaches::getExtensionCacheVersion()`). 활성 조합이 바뀌면 install/activate/deactivate/update 라이프사이클에서 version 이 bump 되어 새 URL → 새 캐시 파일명으로 자동 무효화된다.
|
||
|
||
### 동작 흐름
|
||
|
||
```
|
||
1. blade → window.G7Config.bundleUrls 주입 (활성 에셋 없는 타입은 null)
|
||
2. TemplateApp.loadExtensionAssets()
|
||
└─ ModuleAssetLoader.loadBundle('module', ...) → loadBundle('plugin', ...)
|
||
├─ 단일 <script async=false> + 단일 <link> append
|
||
└─ 번들 내부 물리 순서(=priority 정렬)로 IIFE 자가등록 실행
|
||
```
|
||
|
||
`bundleUrls` 가 없으면(구버전 blade) `ModuleAssetLoader.loadActiveExtensionAssets` 개별 로딩으로 폴백한다.
|
||
|
||
### 병합 규율
|
||
|
||
| 규율 | 내용 | 정적 검사 |
|
||
|------|------|---------|
|
||
| priority 순서 | manifest `loading.priority` 오름차순만. 확장 이름 하드코딩 금지 | (선언형) |
|
||
| `\n;\n` 구분자 | IIFE 사이는 `\n;\n`(JS)/`\n`(CSS). 미사용 시 ASI 붕괴 → 전체 파싱 에러 | `extension-bundle-concat-separator` |
|
||
| 소스맵 | prod strip, dev 는 개별 에셋 서빙 절대 URL 로 rewrite | - |
|
||
| same-origin | 번들 URL 은 `/api/...` 만 (CDN 금지 — gdpr preblocker 자기차단 방지) | `extension-bundle-url-same-origin` |
|
||
| 절대경로 게터 | `getBuiltAssetAbsolutePaths()` 사용. `base_path("modules"\|"plugins")` 직접 조립 금지 | `extension-bundle-asset-path-getter` |
|
||
| 확장별 try/catch | 파일 읽기 실패 시 해당 확장만 skip, 나머지 병합 지속 | (메모리+회귀테스트) |
|
||
| CSS url() | 상대경로 url() 을 가진 CSS 는 번들 제외(개별 폴백) | - |
|
||
|
||
### 캐시 stale 관리
|
||
|
||
번들 파일(`storage/app/ext-bundles/{type}.{version}.{js,css}`)은 Laravel 캐시 스토어 밖 파일시스템이라 version bump/`cache:clear` 가 구파일을 지우지 않는다. 정리 경로:
|
||
|
||
```bash
|
||
php artisan ext-bundles:cleanup # 현재 version 외 구파일 삭제
|
||
php artisan module:cache-clear # 모듈 번들 파일 정리 포함
|
||
php artisan plugin:cache-clear # 플러그인 번들 파일 정리 포함
|
||
php artisan template:cache-clear # 전체 번들 파일 정리 포함
|
||
```
|
||
|
||
프로덕션은 version-in-path 디스크 캐시, 비프로덕션(dev/watch)은 캐시 없이 매 요청 concat(rebuild 즉시 반영). `_bundled` 수정 후에는 `{type}:update {id} --force` 로 활성 반영 후 version bump 로 번들이 재생성된다.
|
||
|
||
> 개별 에셋 서빙 라우트(`/api/{type}/assets/...`, `*.map` 포함)는 소스맵·static 참조를 위해 존치한다.
|
||
> 다만 `*.map` 의 **실제 서빙은 `local` 환경에서만** 허용된다 — 소스맵에는 원본 코드 전문이
|
||
> 담기므로 운영에서는 확장자 화이트리스트가 차단한다. 상세: [template-security.md](template-security.md) "소스맵 (`map`) — 로컬 개발 환경 전용".
|
||
|
||
### 전송 압축 (gzip)
|
||
|
||
번들 JS/CSS 는 `fileResponse()`(= `response()->file()` → `BinaryFileResponse`)로 서빙되며, `GzipEncodeResponse` 미들웨어가 gzip 압축을 적용한다. `BinaryFileResponse` 는 `getContent()` 가 `false` 를 반환하므로, 미들웨어는 파일 경로(`getFile()->getPathname()`)에서 본문을 읽어 압축한 뒤 헤더(Content-Type/ETag/Cache-Control)를 승계한 일반 `Response` 로 치환한다.
|
||
|
||
- 1KB 미만 번들(예: 빈 CSS)은 `MIN_COMPRESS_SIZE` 가드로 압축 생략.
|
||
- `Accept-Encoding: gzip` 미포함 요청, 이미 `Content-Encoding` 이 있는 응답, 304 응답은 압축 대상에서 제외.
|
||
- 회귀 테스트: `tests/Feature/Middleware/GzipEncodeResponseTest.php` (BinaryFileResponse 압축/헤더 승계/소용량 skip).
|
||
|
||
> `BinaryFileResponse` 를 압축 대상에 포함하지 않으면 번들이 비압축 전송되는 사각지대가 생긴다(모듈/플러그인 번들은 크기가 커 압축 이득이 특히 크다).
|
||
|
||
---
|
||
|
||
## 에셋 로딩 전략
|
||
|
||
### global (기본값)
|
||
|
||
앱 초기화 시 자동으로 로드됩니다.
|
||
|
||
```json
|
||
{
|
||
"loading": {
|
||
"strategy": "global",
|
||
"priority": 100
|
||
}
|
||
}
|
||
```
|
||
|
||
- TemplateApp.init()에서 자동 로드
|
||
- 모든 페이지에서 핸들러 사용 가능
|
||
- 우선순위(priority)가 낮을수록 먼저 로드
|
||
|
||
### layout (향후 지원)
|
||
|
||
특정 레이아웃에서만 로드됩니다.
|
||
|
||
```json
|
||
{
|
||
"loading": {
|
||
"strategy": "layout"
|
||
}
|
||
}
|
||
```
|
||
|
||
- 레이아웃의 scripts 섹션에서 명시적 로드
|
||
- 해당 레이아웃 진입 시 로드
|
||
|
||
### lazy (향후 지원)
|
||
|
||
필요할 때 동적으로 로드됩니다.
|
||
|
||
```json
|
||
{
|
||
"loading": {
|
||
"strategy": "lazy"
|
||
}
|
||
}
|
||
```
|
||
|
||
- 핸들러 호출 시점에 로드
|
||
- 초기 로딩 시간 최적화
|
||
|
||
---
|
||
|
||
## 외부 라이브러리
|
||
|
||
외부 CDN 스크립트를 조건부로 로드할 수 있습니다.
|
||
|
||
### module.json 설정
|
||
|
||
```json
|
||
{
|
||
"assets": {
|
||
"external": [
|
||
{
|
||
"src": "https://cdn.example.com/chart.js",
|
||
"id": "chartjs-cdn",
|
||
"if": "{{_global.settings.useCharts}}"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 레이아웃 scripts 섹션
|
||
|
||
```json
|
||
{
|
||
"scripts": [
|
||
{
|
||
"src": "https://cdn.example.com/lib.js",
|
||
"id": "external-lib",
|
||
"if": "{{_global.modules['sirsoft-ecommerce'].useExternalLib}}",
|
||
"async": true
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## AbstractModule 에셋 메서드
|
||
|
||
AbstractModule은 에셋 관련 헬퍼 메서드를 제공합니다:
|
||
|
||
| 메서드 | 설명 |
|
||
|--------|------|
|
||
| `getAssets()` | module.json의 assets 섹션 반환 |
|
||
| `getAssetLoadingConfig()` | loading 설정 반환 (strategy, priority) |
|
||
| `hasAssets()` | 에셋 정의 존재 여부 |
|
||
| `getBuiltAssetPaths()` | 빌드된 에셋 경로 반환 (js, css) |
|
||
|
||
---
|
||
|
||
## 관련 문서
|
||
|
||
- [module-basics.md](./module-basics.md) - 모듈 개발 기초
|
||
- [hooks.md](./hooks.md) - 훅 시스템 (핸들러와 연계)
|
||
- [module-commands.md](./module-commands.md) - 모듈 Artisan 커맨드
|
||
- [../frontend/components.md](../frontend/components.md) - 컴포넌트 핸들러 호출
|