v7.0.0-beta.2 release

This commit is contained in:
HeuJung committed 2026-04-20 20:37:49 +09:00
1 parent 6595fd0eb5
commit fa8eba7a0d
1165 files changed
+107118 -762127

No files matched your search

+278
View File
@@ -0,0 +1,278 @@
# 캐시 드라이버 시스템 (CacheInterface)
> **코어/모듈/플러그인에서 캐시를 관리하기 위한 표준화된 인터페이스**
## TL;DR (5초 요약)
```text
1. 모든 캐시 저장은 CacheInterface 사용 (Cache:: 직접 호출 금지)
2. BaseModuleServiceProvider에서 cacheServices 배열에 Service 클래스 등록
3. 접두사로 캐시 키 격리: g7:core:{key}, g7:module.{id}:{key}, g7:plugin.{id}:{key}
4. TTL은 g7_core_settings('cache.*')로 중앙 관리 (하드코딩 금지)
5. Service 생성자에서 CacheInterface 타입힌트하면 자동 주입
```
---
## 목차
- [개요](#개요)
- [아키텍처](#아키텍처)
- [모듈에서 사용하기](#모듈에서-사용하기)
- [코어 서비스에서 사용하기](#코어-서비스에서-사용하기)
- [자동 무효화 (CacheInvalidatable)](#자동-무효화-cacheinvalidatable)
- [TTL 중앙 관리](#ttl-중앙-관리)
- [API 레퍼런스](#api-레퍼런스)
- [StorageDriver와의 대응](#storagedriver와의-대응)
---
## 개요
G7 캐시 드라이버 시스템은 StorageDriver 패턴을 참고하여 설계되었습니다.
코어, 모듈, 플러그인별로 캐시 키를 접두사로 격리하고, DI를 통해 자동 주입됩니다.
### 핵심 원칙
- **접두사 격리**: 각 확장의 캐시 키가 충돌하지 않음
- **DI 자동 주입**: Service 생성자에서 `CacheInterface` 타입힌트만으로 해당 확장의 캐시 드라이버를 받음
- **TTL 중앙 관리**: 모든 TTL은 `g7_core_settings('cache.*')`에서 관리
- **확장 라이프사이클 통합**: 모듈/플러그인 비활성화/삭제 시 캐시 자동 정리
---
## 아키텍처
```
CacheInterface (인터페이스 — app/Contracts/Extension/)
↑ implements
AbstractCacheDriver (공통 구현 — app/Extension/Cache/)
↑ extends
├── CoreCacheDriver 접두사: g7:core:{key}
├── ModuleCacheDriver 접두사: g7:module.{identifier}:{key}
└── PluginCacheDriver 접두사: g7:plugin.{identifier}:{key}
CacheInvalidatable (트레이트 — app/Extension/Traits/)
→ 모델에 적용, saved/deleted 시 관련 태그 캐시 자동 무효화
```
### 키 접두사 체계
| 드라이버 | 접두사 패턴 | 예시 |
|---------|-----------|------|
| CoreCacheDriver | `g7:core:{key}` | `g7:core:system_settings` |
| ModuleCacheDriver | `g7:module.{id}:{key}` | `g7:module.sirsoft-ecommerce:products:list` |
| PluginCacheDriver | `g7:plugin.{id}:{key}` | `g7:plugin.sirsoft-payment:gateways` |
---
## 모듈에서 사용하기
### 1단계: ServiceProvider에 cacheServices 등록
```php
class EcommerceServiceProvider extends BaseModuleServiceProvider
{
protected string $moduleIdentifier = 'sirsoft-ecommerce';
protected array $cacheServices = [
ProductService::class,
CategoryService::class,
];
}
```
### 2단계: Service 생성자에서 CacheInterface 주입
```php
class ProductService
{
public function __construct(
private readonly ProductRepositoryInterface $productRepository,
private readonly CacheInterface $cache,
) {}
public function getProducts(array $filters): array
{
$queryHash = md5(json_encode($filters));
return $this->cache->rememberQuery(
$queryHash,
fn () => $this->productRepository->list($filters),
ttl: 3600,
tags: ['products'],
);
}
public function getProduct(int $id): ?Product
{
return $this->cache->remember(
"product:{$id}",
fn () => $this->productRepository->find($id),
ttl: 3600,
tags: ['products', "product:{$id}"],
);
}
}
```
### 3단계 (선택): 캐시 스토어 오버라이드
모듈 클래스에서 `getCacheStore()`를 오버라이드하면 다른 캐시 드라이버를 사용할 수 있습니다.
```php
class EcommerceModule extends AbstractModule
{
public function getCacheStore(): string
{
return 'redis'; // 기본값(config('cache.default')) 대신 redis 사용
}
}
```
---
## 코어 서비스에서 사용하기
코어 서비스는 `CoreServiceProvider`에서 `CacheInterface`를 바인딩합니다.
```php
// CoreServiceProvider
$this->app->bind(CacheInterface::class, function () {
return new CoreCacheDriver(config('cache.default'));
});
```
코어 서비스에서도 동일하게 생성자 주입으로 사용합니다.
```php
class LayoutService
{
public function __construct(
private readonly CacheInterface $cache,
) {}
public function loadAndMergeLayout(string $name, int $templateId): array
{
$ttl = (int) g7_core_settings('cache.layout_ttl', 3600);
return $this->cache->remember(
"layout.{$templateId}.{$name}",
fn () => $this->mergeLayout($name, $templateId),
$ttl,
['layout'],
);
}
}
```
---
## 자동 무효화 (CacheInvalidatable)
모델에 `CacheInvalidatable` 트레이트를 적용하면 `saved`/`deleted` 이벤트 시 관련 태그 캐시를 자동 삭제합니다.
```php
use App\Extension\Traits\CacheInvalidatable;
class Product extends Model
{
use CacheInvalidatable;
protected function getCacheInvalidationTags(): array
{
return ['products', 'product:' . $this->id];
}
protected function getCacheDriver(): ?CacheInterface
{
return app(ModuleManager::class)
->getModule('sirsoft-ecommerce')?->getCache();
}
}
```
**흐름**: Product 수정 → `CacheInvalidatable`이 `saved` 이벤트 감지 → `flushTags(['products', 'product:123'])` → 해당 태그 캐시 삭제 → 다음 조회 시 `remember()` 콜백 실행으로 재생성
---
## TTL 중앙 관리
모든 캐시 TTL은 `g7_core_settings('cache.*')`로 중앙 관리합니다. 하드코딩 금지.
| 설정 키 | 기본값 | 용도 |
|---------|--------|------|
| `cache.default_ttl` | 86400 | 기본 TTL (24h) |
| `cache.layout_ttl` | 3600 | 레이아웃 캐시 TTL |
| `cache.seo_ttl` | 7200 | SEO 페이지 캐시 TTL |
| `cache.seo_sitemap_ttl` | 86400 | Sitemap 캐시 TTL |
| `cache.notification_ttl` | 3600 | 알림 정의/템플릿 캐시 TTL |
| `cache.extension_status_ttl` | 86400 | 확장 상태 캐시 TTL |
| `cache.geoip_ttl` | 86400 | GeoIP 캐시 TTL |
| `cache.version_check_ttl` | 3600 | 버전 검증 캐시 TTL |
```php
// 사용 예시
$ttl = (int) g7_core_settings('cache.layout_ttl', 3600);
$this->cache->remember($key, $callback, $ttl, $tags);
```
---
## API 레퍼런스
### 기본 CRUD
| 메서드 | 설명 |
|--------|------|
| `get(key, default)` | 캐시 조회 |
| `put(key, value, ttl)` | 캐시 저장 |
| `has(key)` | 존재 확인 |
| `forget(key)` | 삭제 |
### Remember 패턴
| 메서드 | 설명 |
|--------|------|
| `remember(key, callback, ttl, tags)` | 캐시 미스 시 콜백 실행 + 저장 |
| `rememberQuery(queryHash, callback, ttl, tags)` | 쿼리 해시 기반 캐싱 (`query:` 접두사) |
| `refresh(key, callback, ttl, tags)` | forget + remember 원자적 실행 |
### 벌크 연산
| 메서드 | 설명 |
|--------|------|
| `many(keys)` | 여러 키 한 번에 조회 |
| `putMany(values, ttl)` | 여러 키-값 한 번에 저장 |
### 무효화
| 메서드 | 설명 |
|--------|------|
| `flush()` | 이 드라이버 소속 전체 캐시 삭제 |
| `flushTags(tags)` | 특정 태그의 캐시만 삭제 |
### 메타
| 메서드 | 설명 |
|--------|------|
| `supportsTags()` | 태그 지원 여부 |
| `getStore()` | 현재 스토어 이름 |
| `withStore(store)` | 스토어 변경 (불변 복제) |
| `resolveKey(key)` | 전체 키 확인 (디버깅용) |
---
## StorageDriver와의 대응
| StorageDriver | CacheDriver | 비고 |
|--------------|-------------|------|
| `StorageInterface` | `CacheInterface` | 계약 |
| `CoreStorageDriver` | `CoreCacheDriver` | 코어용 |
| `ModuleStorageDriver` | `ModuleCacheDriver` | 모듈용 |
| `PluginStorageDriver` | `PluginCacheDriver` | 플러그인용 |
| `getStorage()` | `getCache()` | 추상 클래스 메서드 |
| `getStorageDisk()` | `getCacheStore()` | 오버라이드 가능 |
| `withDisk()` | `withStore()` | 불변 복제 |
| `$storageServices` | `$cacheServices` | ServiceProvider 배열 |
| `registerStorageBindings()` | `registerCacheBindings()` | DI 자동 바인딩 |
+41
View File
@@ -23,6 +23,7 @@
5. [API 엔드포인트](#5-api-엔드포인트)
6. [관리 화면 표시](#6-관리-화면-표시)
7. [템플릿 예시](#7-템플릿-예시)
8. [코어 버전 제약 정책](#8-코어-버전-제약-정책)
---
@@ -201,6 +202,46 @@ setState(selectedX) → apiCall(changelog)
---
## 8. 코어 버전 제약 정책
확장 manifest(`module.json`, `plugin.json`, `template.json`)의 `g7_version` 과 `dependencies.{modules|plugins}` 버전 제약 작성 규칙.
### 표기 규칙
- 형식: `>=X.Y.Z[-prerelease]` 통일 (공백 없음). 예: `>=7.0.0-beta.2`, `>=1.0.0-beta.2`
- 캐럿(`^`), 틸드(`~`), 엄격 일치(`=`) 사용 금지
- placeholder 금지: 실존하지 않는 버전(`0.1.0`, `0.0.1` 등) 을 적어 사실상 "아무 버전이나 허용" 상태로 두지 않음
### `g7_version` — 코어 최소 요구 버전
- 확장이 실제로 의존하는 코어 API/기능의 **최초 도입 버전**을 최소값으로 기재
- 확장 `version` 이 bump 될 때 `g7_version` 재검토 필수
- 번들 확장은 일반적으로 코어의 현재 릴리스와 같은 단계(beta.X, rc.X, X.Y.Z)를 하한으로 둠
- 예: 알림 시스템 3계층(NotificationDefinition/Template) 을 사용하는 모듈은 최소 `>=7.0.0-beta.2`
### `dependencies.{modules|plugins}` — 확장 간 버전 제약
- A 확장이 B 확장의 공개 Service/Contract/Model/Route/훅을 사용한다면 `dependencies.{type}.B: ">=X.Y.Z"` 기재
- B 에서 공개 표면이 변경되거나 새 API 가 도입되어 A 가 그것을 소비하게 되면 A 의 최소 버전 제약을 **그 API 최초 도입 버전**으로 상향
- 실존하지 않는 placeholder 버전(`>=0.1.0` 등)은 금지 — 버전 게이팅 무효화 유발
### 버전 제약 재검토 트리거
다음 이벤트 발생 시 관련 확장 manifest 를 전수 재검토한다.
| 이벤트 | 재검토 대상 |
|--------|------------|
| 코어 공개 확장 표면 변경 (AbstractModule/AbstractPlugin/HookManager/Contracts 등) | 모든 번들 확장의 `g7_version` |
| 코어 minor/major/beta 번호 변경 | 번들 확장 전체 `g7_version` |
| 번들 모듈/플러그인의 공개 Service/Contract/Model/Route/훅/CHANGELOG 변경 | 해당 확장을 `dependencies` 에 선언한 모든 확장 |
### CHANGELOG 기재
- `g7_version` 상향: `### Changed` 에 `- 코어 최소 요구 버전을 X.Y.Z 로 상향`
- `dependencies.{id}` 상향: `### Changed` 에 `- {id} 의존성 버전 제약을 실제 릴리스 버전에 맞춰 정비` 또는 `- {id} 최소 버전을 X.Y.Z 로 상향` (변경 이유에 따라)
---
## 관련 파일
- `app/Extension/Helpers/ChangelogParser.php` — Changelog 파서
+15
View File
@@ -144,6 +144,21 @@ registerExtensionAutoload($loader)
✅ 장점: 확장 간 의존성 충돌 방지, 삭제 시 깔끔한 정리
```
### Vendor 설치 모드 (VendorMode)
공유 호스팅 등 Composer 실행 불가 환경을 지원하기 위해 **VendorResolver** 경유로 설치 모드를 결정합니다.
```text
VendorMode enum:
- auto: composer 가능 시 composer, 불가 시 bundled (기본값)
- composer: composer install 강제 (불가 시 예외)
- bundled: vendor-bundle.zip 추출 강제
```
설치/업데이트 시 `installModule()` / `installPlugin()` / `updateModule()` / `updatePlugin()` 의 `VendorMode $vendorMode` 파라미터로 전달되며, `VendorResolver::install()` 가 환경 감지 + DB 기록 이전 모드 상속 + 번들 zip 무결성 검증을 거쳐 적절한 전략으로 라우팅합니다. `modules.vendor_mode` / `plugins.vendor_mode` 컬럼에 최종 사용된 모드가 기록되어 업데이트 시 자동 상속됩니다.
> 상세: [vendor-bundle.md](vendor-bundle.md) — 번들 구조, 빌드/검증/설치 흐름, 무결성 검증
### 동작 방식
```text
+222 -21
View File
@@ -66,6 +66,8 @@
```
> **주의**: `_pending` 디렉토리는 업데이트 감지에 **참여하지 않습니다**.
>
> GitHub API 호출은 `GithubHelper` (Laravel Http 파사드 기반)로 일원화되어 있습니다. `file_get_contents` + `stream_context_create` 직접 사용 금지 — `allow_url_fopen=Off` 공유 호스팅 환경 대응.
### 감지 결과
@@ -78,6 +80,59 @@
]
```
### 소스 강제 경로 (sourceOverride)
기본 2단계 우선순위(GitHub > _bundled)를 우회해 특정 소스 단독으로 업데이트를 실행하는 경로입니다.
#### 감지
- 일반: `Manager::checkAll{Type}ForUpdates()` — GitHub > _bundled 순으로 먼저 응답하는 소스 사용
- 번들 강제: `CoreUpdateService::collectBundledExtensionUpdates()` — DB 현재 버전 vs `_bundled/{id}/{manifest}.json` 직접 비교
#### 실행
- 일반: `Manager::update{Type}($id, $force, ...)` — `update_source` 자동 결정
- 번들 강제: `sourceOverride='bundled'` — GitHub 응답과 무관하게 `_bundled` 버전 설치
- GitHub 강제: `sourceOverride='github'` — `_bundled` 폴백 차단, `github_url` 미설정 시 `force_update_no_source` 오류로 명확히 차단
이유: GitHub 릴리즈가 `_bundled` 보다 구(舊) 버전이거나 일시적으로 API 가 실패해도 코어와 함께 배포된 `_bundled` 버전이 코어와의 호환성 보증 기준이 되어야 하기 때문. 반대로 GitHub 에서 핫픽스 태그를 먼저 받아야 하는 운영 상황에서는 `github` 강제가 필요합니다.
`sourceOverride` 파라미터는 `updateModule` / `updatePlugin` / `updateTemplate` 의 마지막 파라미터이며, 지정하지 않으면 기존 GitHub > _bundled 우선순위가 그대로 적용됩니다.
#### CLI 옵션
`module:update` / `plugin:update` / `template:update` 에 `--source=auto|bundled|github` 옵션이 제공됩니다.
| 값 | 동작 |
| --- | --- |
| `auto` (기본) | GitHub > _bundled 2단계 우선순위 |
| `bundled` | `_bundled` manifest 단독 사용 (GitHub 전면 우회) |
| `github` | GitHub 단독 사용 (`_bundled` 폴백 차단) |
사용 예: GitHub 에 임시 장애가 있거나 잘못된 태그가 퍼블리시되어 자동 경로가 실패할 때 `--source=bundled` 로 강제 설치, 반대로 긴급 핫픽스를 GitHub 태그로만 배포한 경우 `--source=github` 로 번들 폴백을 차단합니다.
#### 외부 ZIP 직접 지정 (`--zip`)
`module:update` / `plugin:update` / `template:update` 에 `--zip={path}` 옵션이 제공됩니다. GitHub 우회 + 번들 우회 경로로, 오프라인 환경·사설 레지스트리·긴급 수동 배포 용도입니다.
| 값 | 동작 |
| --- | --- |
| `--zip=/path/to/ext.zip` | 지정 ZIP 을 추출하여 소스로 사용. `manifest.json`(module.json / plugin.json / template.json)의 `identifier` 가 대상 확장과 일치해야 하며, `version` 은 manifest 기준으로 자동 결정 |
동작 요약:
1. `extractFromZip()` 이 ZIP 을 임시 디렉토리에 추출 (GitHub zipball 의 `owner-repo-hash/` 래퍼든 평탄 루트든 자동 감지)
2. `prepareZipSource()` 가 manifest 존재·JSON 해석·identifier 일치·version 존재를 검증
3. manifest 의 `version` 을 `$toVersion` 으로 채택하고 staging → 적용 → 마이그레이션 → upgrade step 순 진행
제약:
- `--zip` 은 `--source` 와 **동시에 지정할 수 없습니다** (커맨드 시작 전 FAILURE 종료)
- ZIP 파일이 존재하지 않거나 파일이 아닌 경로인 경우 FAILURE 종료
- `--zip` 사용 시 `checkModuleUpdate` / `checkPluginUpdate` / `checkTemplateUpdate` 의 `update_available` 판정은 우회합니다 (사용자가 명시적으로 ZIP 을 제공한 것이 업데이트 의도의 확인으로 간주)
프로그래매틱 호출 시 `updateModule` / `updatePlugin` / `updateTemplate` 의 **마지막** 파라미터 `$zipPath` 로 절대 경로를 전달합니다.
### check-updates API 흐름
1. Service 레이어에서 훅 발행: `core.{type}.before_check_updates`
@@ -90,15 +145,17 @@
GitHub 소스 업데이트 시 아카이브 URL 해석 → 다운로드 → 압축 해제 과정을 거칩니다:
**v접두사 자동 감지** (`resolveGithubArchiveUrl`):
**v접두사 자동 감지 및 태그 실재 검증** (`resolveGithubArchiveUrl`):
```text
1. "v{version}" 태그로 HEAD 요청 시도 (예: v1.2.0)
2. 실패 시 "{version}" 태그로 HEAD 요청 시도 (예: 1.2.0)
3. HTTP 200/302 → 유효한 URL 반환
4. 모두 실패 → null 반환 (업데이트 불가)
1. "v{version}" 태그 실재 검증 — GET git/refs/tags/v{version} (200=존재, 404=부재)
2. 실패 시 "{version}" 태그 실재 검증 — GET git/refs/tags/{version}
3. 200 응답한 태그의 zipball URL 반환
4. 모두 404 → null 반환 (업데이트 소스 없음 — "force_update_no_source" 안내)
```
> **주의**: `zipball/{ref}` 엔드포인트는 태그 존재 여부와 무관하게 항상 302로 codeload 에 리다이렉트하기 때문에, 302 수신만으로는 태그 유효성을 판정할 수 없습니다. 반드시 `git/refs/tags/{tag}` 로 실재를 먼저 검증해야 합니다.
**아카이브 추출 전략** (2단계 폴백):
| 순서 | 방식 | 조건 |
@@ -146,6 +203,62 @@ GitHub 소스 업데이트 시 아카이브 URL 해석 → 다운로드 → 압
3. 에러 로깅 (upgrade 채널)
```
### 업데이트 진행 플래그 (`G7_UPDATE_IN_PROGRESS`)
코어 업데이트는 파일 교체 / manifest 교체 / `.env` `APP_VERSION` 갱신이 서로 다른 단계에 수행되어, 중간 시점에 부팅되는 spawn 프로세스에서 코어·확장 버전이 일시적으로 불일치합니다. 이 상태에서 `CoreServiceProvider::validateAndDeactivateIncompatibleExtensions` / `validateAndDeactivateIncompatibleTemplates` 가 실행되면 호환성 판정이 부정확해 활성 확장이 자동 비활성화되고, 이어서 `updateModule` 이 `previousStatus='inactive'` 를 캡처해 영구 비활성 상태로 복원되는 회귀가 발생합니다.
방지 규약:
1. `CoreUpdateCommand::handle()` 진입 즉시 `G7_UPDATE_IN_PROGRESS=1` 을 `$_ENV / $_SERVER / putenv` 3 경로에 기록.
2. 모든 spawn 호출(`proc_open`) 이 **`array_merge(getenv(), $_ENV, ['G7_UPDATE_IN_PROGRESS' => '1', ...])`** 패턴으로 `$env` 를 구성 → 플래그가 자식에 확실히 전파.
3. `CoreServiceProvider::validateAndDeactivate*` 는 진입 직후 `isCoreUpdateInProgress()` 체크 → 플래그 감지 시 즉시 `return`.
4. 업데이트 종료 → 부모 프로세스 종료 → env 소멸 → 다음 요청부터 정상 호환성 체크 복원.
#### proc_open `$env` 구성 주의 (CRITICAL)
`$_ENV` 만으로 spawn 자식에 전달하면 **플래그가 누락될 수 있습니다**.
원인: `$_ENV` 는 PHP `variables_order` ini 설정에 `E` 가 포함되어야 populate 됩니다 (기본 CLI `"EGPCS"`, 일부 호스팅 `"GPCS"` — E 없음). `E` 가 없는 환경에서는:
- `$_ENV['G7_UPDATE_IN_PROGRESS'] = '1'` 할당은 superglobal 에만 적용되고 프로세스 environ 에는 미반영
- `putenv('G7_UPDATE_IN_PROGRESS=1')` 는 프로세스 environ 에 기록되지만 `$_ENV` 와 별개
- `array_merge($_ENV, [...])` 결과는 플래그 누락 — 자식이 플래그 없이 boot → validateAndDeactivate 발동 → 확장 자동 비활성화
**올바른 패턴**:
```php
// getenv() (인자 없이 호출, PHP 7.1+) 은 프로세스 environ 테이블을 직접 반환 →
// putenv 로 설정된 값까지 확실히 포함. $_ENV 가 비어있어도 안전.
$env = array_merge(getenv(), $_ENV, [
'G7_UPDATE_IN_PROGRESS' => '1',
// 필요한 추가 env ...
]);
$process = proc_open($cmd, $descriptors, $pipes, $cwd, $env);
```
`isCoreUpdateInProgress()` 는 env 외에 `$argv[1]` 이 `core:update` / `core:execute-upgrade-steps` 인 경우도 true 판정 — env 전파 실패 극단 상황 방어용. 하지만 `php -r '...'` 로 기동되는 spawn (inline 스크립트) 은 argv 판정이 되지 않으므로 env 전파가 유일한 수단입니다.
### 동적 엔티티 보존 (Permission / Role / Menu)
모듈·플러그인이 런타임에 동적으로 생성한 Permission/Role/Menu 는 정적 정의(`getPermissions()`, `getRoles()`, `getAdminMenus()`)에 포함되지 않으므로, 업데이트 시 `cleanupStaleModuleEntries()` / `cleanupStalePluginEntries()` 가 stale 로 오판하지 않도록 모듈 측에서 아래 hook 을 override 해 현재 식별자 전체를 반환한다.
확장 측 override hook:
- `getDynamicPermissionIdentifiers()` — 런타임 생성 권한 식별자 (Module · Plugin)
- `getDynamicRoleIdentifiers()` — 런타임 생성 역할 식별자 (Module · Plugin)
- `getDynamicMenuSlugs()` — 런타임 생성 메뉴 slug (Module)
cleanup 로직은 정적 + 동적 식별자를 병합한 expected 목록을 기준으로 stale 판정한다. 상세 override 예시는 [module-basics.md "동적 권한/역할/메뉴 보존 규칙"](module-basics.md#동적-권한역할메뉴-보존-규칙) 참조.
### 언인스톨 시 권한/메뉴/역할 보존 정책
`uninstallModule() / uninstallPlugin()` 은 `$deleteData` 파라미터로 데이터 삭제 범위를 분기한다:
- `$deleteData=false` (기본): 권한·메뉴·역할 **보존** (재설치 시 사용자 역할 할당 복원 가능). 테이블/vendor/storage 도 보존.
- `$deleteData=true`: 권한·메뉴·역할 + 테이블 + vendor + storage 전수 삭제.
동적 권한/역할/메뉴가 있는 모듈은 이 정책이 특히 중요하다. 사용자가 의도적으로 "데이터도 함께 삭제" 를 체크하지 않는 한 동적 엔티티는 유지된다.
---
## 4. ExtensionStatusGuard
@@ -339,6 +452,19 @@ class Upgrade_2_0_0 implements UpgradeStepInterface
}
```
### 멱등성 방어 로직 (필수)
업그레이드 스텝은 재실행될 수 있다 (롤백 후 재시도, `--force` 등). 모든 DB 조작은 이미 완료된 상태에서 재실행해도 안전해야 한다.
| 조작 유형 | 방어 패턴 |
|----------|----------|
| 레코드 삽입 | `firstOrCreate` 또는 `updateOrCreate` |
| 대량 데이터 이관 | 이관 완료 마커 확인 후 스킵 |
| 식별자 rename (unique 컬럼) | 신규 존재 여부 확인 후 분기 |
| 코드/상태값 변환 | WHERE 조건이 이미 변환된 건을 자동 제외 |
> 상세: [core-update-system.md](../backend/core-update-system.md) "멱등성 방어 로직" 참조
### 자동 발견 규칙
- 디렉토리: `{extensionPath}/upgrades/`
@@ -468,22 +594,25 @@ class Upgrade_2_0_0 implements UpgradeStepInterface
---
## 10. 템플릿 레이아웃 충돌 전략
## 10. 레이아웃 충돌 전략 (3종 공통)
템플릿 업데이트 시 관리자가 수정한 레이아웃이 있으면 충돌이 발생합니다.
템플릿/모듈/플러그인 업데이트 시 관리자가 UI 에서 수정한 레이아웃이 있으면 충돌이 발생합니다. 3종 모두 동일한 전략과 API 구조를 공유합니다.
### 사전 확인 API
```
GET /api/admin/templates/{templateName}/check-modified-layouts
GET /api/admin/modules/{moduleName}/check-modified-layouts
GET /api/admin/plugins/{pluginName}/check-modified-layouts
```
응답:
```json
{
"has_modified": true,
"has_modified_layouts": true,
"modified_count": 2,
"modified_layouts": [
{ "id": 1, "name": "dashboard", "updated_at": "2026-02-24T10:00:00Z" }
{ "id": 1, "name": "sirsoft-board.admin_post_list", "updated_at": "2026-04-19 10:00:00", "size_diff": 128 }
]
}
```
@@ -492,32 +621,46 @@ GET /api/admin/templates/{templateName}/check-modified-layouts
| 전략 | 동작 |
|------|------|
| `apply_new` (기본값) | 새 버전의 레이아웃으로 덮어쓰기 (관리자 수정 사항 유실) |
| `keep_current` | 기존 레이아웃 유지 (새 버전 레이아웃 미적용) |
| `overwrite` (기본값) | 새 버전의 레이아웃으로 덮어쓰기 (관리자 수정 사항 유실) |
| `keep` | 원본 해시 기준으로 사용자가 수정한 레이아웃만 보존, 미수정 레이아웃은 덮어쓰기 |
업데이트 API에 `layout_strategy` 파라미터로 전달:
```
POST /api/admin/templates/{templateName}/update
Body: { "layout_strategy": "apply_new" }
POST /api/admin/{modules|plugins|templates}/{identifier}/update
Body: { "layout_strategy": "keep" }
```
### 수정 감지 원리
- 확장 설치/업데이트 시 `template_layouts.original_content_hash` / `original_content_size` 컬럼에 파일 원본 SHA-256 해시 저장
- `hasModifiedLayouts()` 는 현재 DB content 의 해시를 다시 계산하여 원본과 비교
- 해시가 다르면 사용자가 관리자 UI 에서 수정했다고 판단 → `keep` 전략에서 보존
- 공용 Trait `App\Extension\Traits\ComputesLayoutContentHash` (normalize → JSON encode → SHA-256)
---
## 11. Artisan 커맨드
| 커맨드 | 설명 |
|--------|------|
| `module:install [identifier] [--vendor-mode=auto] [--force]` | 모듈 설치 (`--force` 시 활성 디렉토리를 원본으로 덮어쓰고 재설치) |
| `module:check-updates [identifier?]` | 모듈 업데이트 확인 (전체 또는 단일) |
| `module:update [identifier] [--force]` | 모듈 업데이트 실행 |
| `module:update [identifier] [--force] [--vendor-mode=auto] [--layout-strategy=overwrite]` | 모듈 업데이트 실행 |
| `plugin:install [identifier] [--vendor-mode=auto] [--force]` | 플러그인 설치 (`--force` 동작은 모듈과 동일) |
| `plugin:check-updates [identifier?]` | 플러그인 업데이트 확인 (전체 또는 단일) |
| `plugin:update [identifier] [--force]` | 플러그인 업데이트 실행 |
| `plugin:update [identifier] [--force] [--vendor-mode=auto] [--layout-strategy=overwrite]` | 플러그인 업데이트 실행 |
| `template:install [identifier] [--force]` | 템플릿 설치 (`--force` 동작은 모듈과 동일) |
| `template:check-updates [identifier?]` | 템플릿 업데이트 확인 (전체 또는 단일) |
| `template:update [identifier] [--layout-strategy=overwrite] [--force]` | 템플릿 업데이트 실행 |
| `template:update [identifier] [--force] [--layout-strategy=overwrite]` | 템플릿 업데이트 실행 |
> 단일 `check-updates`는 `checkXxxUpdate()` 호출 후 커맨드에서 DB 갱신 (`updateByIdentifier()`)
> 템플릿 `update`만 `--layout-strategy` 옵션 지원 (`overwrite` | `keep`)
> `--force`: 버전 비교를 건너뛰고 강제 재설치 (파일 손상, 수동 수정 복원 시 사용)
> `--layout-strategy`: 3종 공통. `overwrite` (기본) 또는 `keep` (사용자 수정 보존). 섹션 10 참조
> `--vendor-mode`: 모듈/플러그인 전용. `auto|composer|bundled` — Vendor 설치 방식 선택 (템플릿 미지원)
> `--force` (update): 버전 비교를 건너뛰고 강제 재설치 (파일 손상, 수동 수정 복원 시 사용)
> `--force` (install): 이미 설치된 확장이라도 `_bundled`/`_pending` 원본으로 활성 디렉토리를 덮어쓰고 재설치 — 불완전 활성 디렉토리(manifest 누락 등) 복구 시 사용
> 코어 업데이트 (`core:update`) 완료 후에는 `_bundled` 에 새 버전이 있는 확장을 감지하여 일괄 업데이트 인터랙티브 프롬프트가 자동으로 표시됨
> 활성 디렉토리 로드 시 manifest(`module.json`·`plugin.json`·`template.json`) 가 없으면 경고 로그 + 복구 힌트(`install {id} --force`) 가 출력됨
---
@@ -528,14 +671,16 @@ Body: { "layout_strategy": "apply_new" }
| 메서드 | 경로 | 권한 | 설명 |
|--------|------|------|------|
| POST | `/api/admin/modules/check-updates` | `core.modules.install` | 모듈 업데이트 일괄 확인 |
| POST | `/api/admin/modules/{moduleName}/update` | `core.modules.install` | 모듈 업데이트 실행 |
| GET | `/api/admin/modules/{moduleName}/check-modified-layouts` | `core.modules.read` | 수정된 레이아웃 확인 |
| POST | `/api/admin/modules/{moduleName}/update` | `core.modules.install` | 모듈 업데이트 실행 (`layout_strategy`, `vendor_mode` body) |
### 플러그인
| 메서드 | 경로 | 권한 | 설명 |
|--------|------|------|------|
| POST | `/api/admin/plugins/check-updates` | `core.plugins.install` | 플러그인 업데이트 일괄 확인 |
| POST | `/api/admin/plugins/{pluginName}/update` | `core.plugins.install` | 플러그인 업데이트 실행 |
| GET | `/api/admin/plugins/{pluginName}/check-modified-layouts` | `core.plugins.read` | 수정된 레이아웃 확인 |
| POST | `/api/admin/plugins/{pluginName}/update` | `core.plugins.install` | 플러그인 업데이트 실행 (`layout_strategy`, `vendor_mode` body) |
### 템플릿
@@ -543,7 +688,7 @@ Body: { "layout_strategy": "apply_new" }
|--------|------|------|------|
| POST | `/api/admin/templates/check-updates` | `core.templates.install` | 템플릿 업데이트 일괄 확인 |
| GET | `/api/admin/templates/{templateName}/check-modified-layouts` | `core.templates.read` | 수정된 레이아웃 확인 |
| POST | `/api/admin/templates/{templateName}/update` | `core.templates.install` | 템플릿 업데이트 실행 |
| POST | `/api/admin/templates/{templateName}/update` | `core.templates.install` | 템플릿 업데이트 실행 (`layout_strategy` body) |
### 훅 (Hook)
@@ -643,6 +788,62 @@ Body: { "layout_strategy": "apply_new" }
| `MenuUserOverridesListener` | `core.menu.after_update_order` | 순서 변경된 메뉴에 "order" |
| `MenuUserOverridesListener` | `core.menu.after_sync_roles` | 변경된 개별 역할 식별자 |
### HasUserOverrides Trait — 표준 추상 (7.0.0-beta.2 신규)
신규 모델에 user_overrides 패턴을 적용할 때는 `app/Models/Concerns/HasUserOverrides.php` trait 을 사용합니다. 위 ExtensionRoleSyncHelper / ExtensionMenuSyncHelper 는 권한 식별자 보호 등 복잡 로직을 그대로 유지합니다 (legacy 호환).
**적용**:
```php
use App\Models\Concerns\HasUserOverrides;
class NotificationTemplate extends Model
{
use HasUserOverrides;
protected array $trackableFields = ['subject', 'body', 'click_url', 'recipients', 'is_active'];
}
```
**동작**:
- 사용자가 trackable 필드를 수정하면 trait 의 `static::updating` 이벤트가 자동 감지 → `user_overrides` 에 자동 기록
- 시더/업그레이드 스텝에서 `Model::syncOrCreateFromUpgrade($finder, $attributes)` 호출 → 기록된 필드는 보존, 나머지는 갱신
- 시더 컨텍스트 플래그: `app('user_overrides.seeding')` 가 true 일 때 자동 기록 비활성
**제공 메서드**:
- `getTrackableFields(): array` — 추적 대상 필드 반환 (`$trackableFields` 속성으로 오버라이드)
- `syncFromUpgrade(array $newAttributes): void` — 사용자 수정 보존 갱신
- `createFromUpgrade(array $attributes): self` — 시더 컨텍스트 신규 생성
- `syncOrCreateFromUpgrade(array $finder, array $attributes): self` — 통합 헬퍼
**신규 모델 적용 4단계**:
1. **컬럼 추가** — 마이그레이션에 `text user_overrides nullable` 추가, comment 에 보존 대상 필드명 예시 기록
2. **모델 적용** — `use HasUserOverrides;` + `protected array $trackableFields = [...];` + `$fillable`/`$casts` 에 `'user_overrides'` (`array`) 추가
3. **시더 호출** — 기존 `Model::updateOrCreate(...)` 를 `Model::syncOrCreateFromUpgrade($finder, $attributes)` 로 변경
4. **회귀 테스트** — `tests/Feature/UserOverrides/{Model}UserOverridesTest.php` 작성
**helper / listener / 훅 신규 작성: 불필요** (trait 가 모두 처리)
**현재 적용 모델 (7.0.0-beta.2)**:
| 모델 | trackable 필드 | 적용 위치 |
| ---- | -------------- | --------- |
| `App\Models\NotificationTemplate` | `subject`, `body`, `click_url`, `recipients`, `is_active` | 코어 |
| `App\Models\NotificationDefinition` | `name`, `is_active` | 코어 |
| `App\Models\Schedule` | `expression`, `command`, `timeout`, `is_active` | 코어 (사전 설계, 시더 미존재) |
| `Modules\Sirsoft\Board\Models\BoardType` | `name` | 게시판 모듈 |
| `Modules\Sirsoft\Ecommerce\Models\ClaimReason` | `name`, `sort_order`, `is_active` | 이커머스 모듈 |
**모듈 차원 적용 가이드**:
- 모듈은 코어 trait 차용: `use App\Models\Concerns\HasUserOverrides;`
- 시더 호출: `Model::syncOrCreateFromUpgrade()` 사용
- listener / 훅 / `Module::registerHooks` 등록: 불필요 — trait 의 Eloquent updating 이벤트가 모듈 모델에도 동등 동작
- trackable 필드는 사용자가 수정 가능한 필드만 (system 식별자 `type`/`code`/`slug` 등 절대 포함 금지)
---
## 14. SettingsMigrator
+165 -4
View File
@@ -135,6 +135,18 @@ core.menu.update_validation_rules
core.layout_extension.before_apply
core.layout_extension.after_apply
# 드라이버 확장 훅 (Filter) — 플러그인이 새 드라이버를 등록
core.settings.available_storage_drivers
core.settings.available_cache_drivers
core.settings.available_session_drivers
core.settings.available_queue_drivers
core.settings.available_log_drivers
core.settings.available_websocket_drivers
core.settings.available_mail_drivers
# 드라이버 확장 훅 (Action) — 플러그인 드라이버 선택 시 Config 적용
core.settings.apply_driver_config
# SEO 렌더링 훅 (Filter)
core.seo.filter_context
core.seo.filter_meta
@@ -181,13 +193,16 @@ class ProductCacheInvalidationListener implements HookListenerInterface
*/
public function handleProductChange(...$args): void
{
// CacheInterface 를 컨테이너에서 lazy resolve (모듈 리스너면 ModuleCacheDriver)
$cache = app(\App\Contracts\Extension\CacheInterface::class);
// 모든 상품 목록 캐시 삭제
Cache::forget('products.all');
Cache::forget('products.active');
$cache->forget('products.all');
$cache->forget('products.active');
// 특정 상품 캐시 삭제
if (isset($args[0]->id)) {
Cache::forget("product.{$args[0]->id}");
$cache->forget("product.{$args[0]->id}");
}
Log::info('상품 캐시가 무효화되었습니다.', [
@@ -199,6 +214,99 @@ class ProductCacheInvalidationListener implements HookListenerInterface
---
## 큐 자동 실행
Action 훅 리스너는 환경설정의 **큐 드라이버** 설정에 따라 자동으로 동기/비동기 실행됩니다. 리스너 개발자가 별도로 설정할 필요 없습니다.
### 큐 드라이버별 동작
| 큐 드라이버 | 리스너 실행 방식 | 큐 워커 필요 |
|------------|-----------------|-------------|
| `sync` | 즉시 실행 (동기) | 불필요 |
| `database` | jobs 테이블 저장 → 워커 처리 | 필요 (`php artisan queue:work`) |
| `redis` | Redis 큐 저장 → 워커 처리 | 필요 (`php artisan queue:work`) |
| 커스텀 (플러그인 추가) | 해당 드라이버 큐 → 워커 처리 | 필요 |
> **Filter 훅**은 반환값 체인이므로 **항상 동기 실행**됩니다 (큐 드라이버 무관).
### 동기 실행 강제 (opt-out)
리스너가 반드시 HTTP 요청 스레드에서 동기 실행되어야 하는 경우, `'sync' => true`를 선언합니다.
```php
public static function getSubscribedHooks(): array
{
return [
'core.user.after_create' => [
'method' => 'handleUserCreated',
'priority' => 10,
'sync' => true, // 큐 드라이버 무관하게 항상 즉시 실행
],
];
}
```
### getSubscribedHooks() 옵션 요약
| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `method` | string | `'handle'` | 실행할 메서드명 |
| `priority` | int | `10` | 실행 우선순위 (낮을수록 먼저) |
| `type` | string | `'action'` | `'action'` 또는 `'filter'` |
| `sync` | bool | `false` | `true`: 큐 드라이버 무관하게 동기 실행 |
### 내부 구현
`HookListenerRegistrar`가 리스너 등록 시 큐/동기 분기를 처리합니다:
- Action + `sync: false` (기본) → `DispatchHookListenerJob`으로 래핑하여 `dispatch()`
- Action + `sync: true` → 기존 방식 동기 실행
- Filter → 항상 동기 실행
`DispatchHookListenerJob`은 리스너 클래스명과 메서드명을 직렬화하고, 큐 워커에서 DI 컨테이너로 리스너를 재생성하여 호출합니다.
### 사용자 컨텍스트 자동 복원
큐 워커는 별도 프로세스이므로 `Auth::user()`, `request()->ip()`, `App::getLocale()` 등이 모두 리셋됩니다. 이를 보완하기 위해 `HookContextCapture`가 디스패치 시점에 다음 항목을 자동 캡처하고, 워커에서 복원합니다:
| 항목 | 캡처 출처 | 복원 효과 |
| ---- | --------- | --------- |
| `user_id` | `Auth::id()` | 워커에서 `Auth::user()` 사용 가능 (활동로그 actor 정상 기록) |
| `ip_address` | `request()->ip()` | 워커에서 `request()->ip()` 사용 가능 |
| `user_agent` | `request()->userAgent()` | 워커에서 `request()->userAgent()` 사용 가능 |
| `locale` | `App::getLocale()` | 워커에서 다국어 메시지가 원래 요청 로케일로 발송됨 |
| `path` | `request()->path()` | `ResolvesActivityLogType`이 워커에서 정상 동작 |
리스너 코드는 변경 불필요 — 평소처럼 `Auth::user()`, `request()->ip()` 호출하면 됩니다.
#### 확장 컨텍스트 추가 (플러그인)
플러그인이 `tenant_id`, `trace_id` 등 추가 컨텍스트를 캡처/복원하려면 코어 수정 없이 훅으로 확장 가능:
```php
// 캡처 시 키 추가
HookManager::addFilter('hook.context.capture', function (array $context) {
$context['tenant_id'] = app('tenant')->id;
return $context;
});
// 복원 시 처리
HookManager::addAction('hook.context.restore', function (array $context) {
if (! empty($context['tenant_id'])) {
app('tenant')->setId($context['tenant_id']);
}
});
```
### 주의사항
- 큐 디스패치 시 인자는 `HookArgumentSerializer`로 직렬화됩니다. Eloquent Model은 PK로 변환 후 워커에서 DB 재조회합니다.
- Closure 등 직렬화 불가능한 인자는 null로 대체되므로, 훅 인자로 Closure를 전달하지 마세요.
- 큐 드라이버가 `database`/`redis`일 때 큐 워커가 미실행이면 작업이 적체됩니다.
- 사용자 컨텍스트는 자동 복원되지만, `request()->session()` 등 세션 의존 정보는 복원되지 않습니다 (큐 컨텍스트는 단발 실행).
---
## 코어 리스너 자동 발견
코어 애플리케이션의 훅 리스너는 `app/Listeners/` 디렉토리에서 **자동 발견**됩니다. `HookListenerInterface`를 구현한 클래스는 별도 등록 없이 자동으로 HookManager에 등록됩니다.
@@ -287,6 +395,59 @@ private function registerCoreHookListeners(): void
| 위치 | `app/Listeners/**/*.php` | `modules/**/Listeners/`, `plugins/**/Listeners/` |
| 등록 주체 | `CoreServiceProvider` | `ModuleServiceProvider`, `PluginServiceProvider` |
### 동적 훅 리스너 (DB 기반)
DB 설정에 따라 훅 구독 대상이 동적으로 변하는 경우, 리스너에 `registerDynamicHooks()` 메서드를 구현합니다.
자동 발견 시스템이 이 메서드를 감지하여 `boot()` 후반부(DB 접근 가능 시점)에서 자동 호출합니다.
```php
class NotificationHookListener implements HookListenerInterface
{
// 정적 훅은 빈 배열 (DB 기반이므로)
public static function getSubscribedHooks(): array
{
return [];
}
public function handle(...$args): void {}
/**
* DB 기반 동적 훅을 등록합니다.
* CoreServiceProvider 자동 발견 시스템이 boot 후반부에서 자동 호출합니다.
*/
public function registerDynamicHooks(): void
{
// notification_definitions 테이블에서 훅 목록 조회
// 각 훅에 대해 HookManager::addAction() 등록
}
}
```
| 조건 | 설명 |
|------|------|
| 메서드명 | `registerDynamicHooks()` (덕 타이핑) |
| 호출 시점 | `CoreServiceProvider::boot()` 후반부 (DB 유효성 검증 후) |
| 별도 인터페이스 | 불필요 — `method_exists()` 체크 |
| 안전성 | 테이블 미존재 시 `Schema::hasTable()` 체크 필수 |
---
### HookManager::broadcast() — WebSocket 브로드캐스트
훅 리스너에서 WebSocket 브로드캐스트를 실행할 때 사용합니다.
```php
use App\Extension\HookManager;
HookManager::broadcast(
'user.notifications.123', // 채널
'notification.received', // 이벤트명
['subject' => '새 알림'] // 데이터
);
```
개별 Event 클래스(`app/Events/`)를 직접 생성하지 않습니다. `HookManager::broadcast()`가 내부적으로 `GenericBroadcastEvent`를 사용합니다.
---
## 우선순위 가이드라인
@@ -870,7 +1031,7 @@ public function download(int $id, ?User $user): ?Attachment
| `[module].product.after_update` | `onProductUpdate` | 해당 URL + 목록 |
| `[module].*.after_delete` | `onProductChange` | 전체 관련 캐시 |
캐시 무효화 시 `Cache::forget('seo:sitemap')`도 함께 호출
캐시 무효화 시 `app(CacheInterface::class)->forget('seo.sitemap')` 도 함께 호출 (드라이버가 `g7:core:` 접두사 자동 적용)
> 구현 상세: [seo-system.md](../backend/seo-system.md)
+14 -1
View File
@@ -288,7 +288,13 @@ v1.17.0 이전: modals 내부의 extension_point는 처리되지 않았음
{
"type": "extension_point",
"name": "user_form_additional_fields",
"default": []
"default": [],
"props": {
"readOnlyFields": ["zipcode", "address"]
},
"callbacks": {
"onAddressSelect": { "handler": "setState", "params": { "target": "local", "form.zipcode": "{{$event.zipcode}}" } }
}
}
]
}
@@ -296,6 +302,13 @@ v1.17.0 이전: modals 내부의 extension_point는 처리되지 않았음
}
```
#### Extension Point 데이터 전달 (engine-v1.28.0+)
| 필드 | 타입 | 설명 |
|------|------|------|
| `props` | object | 주입 컴포넌트에 전달할 데이터. 표현식 평가됨. 플러그인에서 `{{extensionPointProps.xxx}}`로 접근 |
| `callbacks` | object | 주입 컴포넌트에 전달할 액션 객체. 평가 없이 그대로 전달. 플러그인에서 `{{extensionPointCallbacks.xxx}}`로 접근 |
### 모듈에서 Extension Point에 주입
```json
+30
View File
@@ -386,8 +386,38 @@ $role->menus()->wherePivot('permission_type', 'write')->get();
---
## 완전 동기화 (Stale Cleanup)
코어/확장 업그레이드 시 메뉴 동기화는 **완전 동기화** — config/manifest 에서 제거된 메뉴는 DB 에서도 삭제됩니다. 유지되는 메뉴는 사용자 수정(`user_overrides` 컬럼) 에 따라 필드 단위 보존이 적용됩니다.
### 적용 지점
| 경로 | 호출 시점 | cleanup 대상 |
|---|---|---|
| `CoreUpdateService::syncCoreMenus` 말미 | 코어 업데이트 | `core/core` 소유 메뉴 전체 slug |
| `ModuleManager::updateModule` 내 sync 블록 말미 | 모듈 업데이트 | 해당 모듈 소유 메뉴 |
### 핵심 정책
- **row 존재 여부**: config 기준 (user_overrides 무관 삭제)
- **필드 값 (유지 row)**: user_overrides 에 등록된 필드 (`name`, `icon`, `order`, `url`) 보존, 나머지 갱신
- **role-menu 매핑**: 메뉴 삭제 시 `role_menus` 피벗은 FK cascade 로 자동 정리
### 사용자 수정 기록
`Menu` 모델은 `HasUserOverrides` trait + `$trackableFields = ['name', 'icon', 'order', 'url']` 적용. 사용자가 UI/API 로 수정하면 trait 이 자동으로 user_overrides 에 누적 기록합니다 (mass update 포함).
### Helper (권장)
직접 Model 조작 금지. `ExtensionMenuSyncHelper` 를 통해 sync/cleanup 수행. 자세한 사용법은 [data-sync-helpers.md](../backend/data-sync-helpers.md#3-extensionmenusynchelper) 참조.
---
## 관련 문서
- [permissions.md](./permissions.md) - 권한 시스템 (Role, Permission, 리소스 레벨 권한)
- [module-basics.md](./module-basics.md) - 모듈 기본 구조
- [index.md](./index.md) - 확장 시스템 인덱스
- [../backend/core-config.md](../backend/core-config.md#완전-동기화-원칙) - 완전 동기화 원칙
- [../backend/data-sync-helpers.md](../backend/data-sync-helpers.md) - 데이터 동기화 Helper
- [../backend/user-overrides.md](../backend/user-overrides.md) - 사용자 수정 보존
+8 -1
View File
@@ -43,7 +43,9 @@
2. TemplateApp.init()
└─ ModuleAssetLoader.loadActiveExtensionAssets()
├─ CSS 로드 (병렬)
└─ JS 로드 (순차)
└─ JS 로드 (병렬 fetch + 순차 실행)
├─ priority 오름차순 정렬 후 DOM append
├─ script.async = false → 삽입 순서대로 실행 보장 (HTML 사양)
└─ 각 모듈의 initModule() 실행
└─ ActionDispatcher.registerHandler()
@@ -51,6 +53,11 @@
└─ 모듈 핸들러 사용 가능
```
> **성능 참고**: JS 번들은 `Promise.all` 로 병렬 fetch 되며, `script.async = false` 와
> priority 정렬된 DOM append 순서로 **실행 순서는 유지**됩니다. N 개의 확장 IIFE 로딩이
> N × (fetch 시간) 에서 max(fetch 시간) 으로 단축됩니다. 단, 확장 간 런타임 의존성
> (다른 확장의 window 전역/핸들러 참조) 이 발생하면 priority 필드로 실행 순서를 명시해야 합니다.
---
## 에셋 매니페스트 스키마
+104 -2
View File
@@ -107,7 +107,7 @@
| 메서드 | 반환 타입 | 설명 |
|--------|----------|------|
| `getIdentifier()` | `string` | 디렉토리명에서 자동 추론 (예: `sirsoft-ecommerce`) |
| `getVendor()` | `string` | 디렉토리명에서 자동 추론 (예: `sirsoft`) |
| `getVendor()` | `string` | `module.json` 의 `vendor` 필드를 우선 사용. 값이 없으면 디렉토리명의 첫 단어로 폴백 (예: `sirsoft`) |
### 기본값 제공 메서드 (필요시 오버라이드)
@@ -123,6 +123,9 @@
| `getViews()` | `[]` | 뷰 파일 |
| `getPermissions()` | `[]` | 권한 목록 (resource_route_key, owner_key, roles scope_type 지원) |
| `getRoles()` | `[]` | 역할 목록 |
| `getDynamicPermissionIdentifiers()` | `[]` | 런타임 생성 권한 식별자 — stale cleanup 보존 대상 (아래 참조) |
| `getDynamicRoleIdentifiers()` | `[]` | 런타임 생성 역할 식별자 — stale cleanup 보존 대상 |
| `getDynamicMenuSlugs()` | `[]` | 런타임 생성 메뉴 slug — stale cleanup 보존 대상 |
| `getConfig()` | `[]` | 설정 |
| `getAdminMenus()` | `[]` | 관리자 메뉴 |
| `getHookListeners()` | `[]` | 훅 리스너 |
@@ -130,6 +133,33 @@
| `getMetadata()` | `[]` | 메타데이터 |
| `upgrades()` | `[]` | 업그레이드 스텝 (`upgrades/` 디렉토리 자동 발견) |
#### 동적 권한/역할/메뉴 보존 규칙
모듈이 런타임에 `Permission::updateOrCreate` / `Role::firstOrCreate` / `Menu::create` 등으로 동적 엔티티를 만드는 경우(예: sirsoft-board 의 게시판 slug 별 권한·역할·메뉴), 업데이트 시 `cleanupStale*` 로직이 **정적 정의에 없다** 는 이유로 전수 삭제되는 회귀가 발생한다. 이를 방지하려면 아래 3개 메서드를 override 해 **현재 DB 에 존재해야 하는 동적 식별자 전체** 를 반환한다.
```php
public function getDynamicPermissionIdentifiers(): array
{
if (! Schema::hasTable('boards')) { return []; }
$actions = array_keys((array) config('sirsoft-board.board_permission_definitions', []));
$module = $this->getIdentifier();
$ids = [];
foreach (Board::query()->select('slug')->get() as $board) {
$ids[] = "{$module}.{$board->slug}"; // 카테고리
foreach ($actions as $a) {
$ids[] = "{$module}.{$board->slug}.{$a}"; // 액션
}
}
return $ids;
}
```
보존 원칙:
- **업데이트 경로**: `updateModule()` → `cleanupStaleModuleEntries()` 는 정적 + 동적 식별자를 병합한 expected 목록을 기준으로 stale 판정. 동적 식별자가 정확히 반환되면 유실 없음.
- **언인스톨 경로**: `uninstallModule($deleteData=false)` 는 권한·메뉴·역할을 **보존** (재설치 시 사용자 역할 할당 복원). `deleteData=true` 일 때만 전수 삭제.
- **설치 경로**: `installModule(--force)` 는 cleanup 을 실행하지 않아 동적 엔티티 유실 없음.
### 간결한 모듈 구현 예시
> **참고**: `getName()`, `getVersion()`, `getDescription()`은 `module.json`에서 자동 파싱되므로 오버라이드가 불필요합니다.
@@ -504,7 +534,7 @@ modules/_bundled/sirsoft-ecommerce/
| 디렉토리 | 설명 |
|----------|------|
| `module.json` | 메타데이터 SSoT (이름, 버전, 설명, 의존성, 라이선스 등) |
| `module.json` | 메타데이터 SSoT (이름, 버전, 설명, 의존성, 라이선스 등) — 버전 제약 정책은 [changelog-rules.md](changelog-rules.md#8-코어-버전-제약-정책) 참조 |
| `module.php` | ModuleInterface 구현 (진입점) |
| `LICENSE` | 라이선스 전문 (MIT 등) — API 엔드포인트 `GET /api/admin/modules/{identifier}/license`로 제공 |
| `composer.json` | PSR-4 오토로딩 + 외부 패키지 의존성 설정 |
@@ -614,6 +644,78 @@ powershell -Command "npm run test:run"
---
## SEO 변수 선언 (seoVariables)
모듈이 SEO 메타 데이터(제목/설명)에 동적 변수를 제공하려면 `seoVariables()` 메서드를 오버라이드합니다.
### 오버라이드 시점
- 모듈이 SEO 대상 페이지를 제공하는 경우 (상품 상세, 카테고리 목록 등)
- 모듈 설정의 SEO 템플릿(`seo.meta_{page_type}_title`)에서 `{key}` 변수 치환이 필요한 경우
### 구조
```php
public function seoVariables(): array
{
return [
// _common: 모든 page_type에 공통 적용
'_common' => [
'site_name' => ['source' => 'core_setting', 'key' => 'general.site_name'],
'commerce_name' => ['source' => 'setting', 'key' => 'basic_info.shop_name'],
],
// page_type별 변수
'product' => [
'product_name' => ['source' => 'data', 'key' => 'product.data.name'],
'product_description' => ['source' => 'data', 'key' => 'product.data.short_description'],
],
'category' => [
'category_name' => ['source' => 'data', 'key' => 'category.data.name'],
],
'search' => [
'keyword_name' => ['source' => 'query', 'key' => 'q'],
],
];
}
```
### 소스 타입
| source | 설명 | 자동 해석 |
|--------|------|----------|
| `setting` | 해당 모듈의 설정 값 | ✅ |
| `core_setting` | 코어 설정 값 | ✅ |
| `query` | URL 쿼리 파라미터 | ✅ |
| `route` | URL 라우트 파라미터 | ✅ |
| `data` | 데이터소스 응답 데이터 (레이아웃 `vars`에서 매핑 필요) | ❌ |
### 레이아웃에서 사용
레이아웃 JSON의 `meta.seo.extensions`에 모듈을 선언하면 `seoVariables()`가 자동 호출됩니다.
```json
{
"meta": {
"seo": {
"extensions": [{ "type": "module", "id": "sirsoft-ecommerce" }],
"page_type": "product",
"vars": {
"product_name": "{{product.data.name ?? ''}}",
"product_description": "{{product.data.short_description ?? ''}}"
}
}
}
}
```
- `setting`, `core_setting`, `query`, `route` 소스는 SeoRenderer가 자동 해석
- `data` 소스 변수는 `vars`에서 표현식으로 매핑 필요
- 설치 시 `ValidatesSeoVariables` 트레이트가 변수명 고유성 검증
> 상세: [seo-system.md](../backend/seo-system.md) "SEO 변수 시스템" 참조
---
## 관련 문서
- [index.md](./index.md) - 확장 시스템 개요
+6 -1
View File
@@ -220,7 +220,7 @@ php artisan module:check-updates sirsoft-ecommerce
#### 모듈 업데이트
```bash
php artisan module:update [identifier] [--force]
php artisan module:update [identifier] [--force] [--source=auto|bundled|github] [--layout-strategy=overwrite|keep] [--vendor-mode=auto|composer|bundled]
```
**인수**:
@@ -228,6 +228,9 @@ php artisan module:update [identifier] [--force]
**옵션**:
- `--force`: 버전 비교 없이 강제 업데이트 (파일 손상, 수동 수정 복원 시 사용)
- `--source`: 업데이트 소스 강제 (`auto` 기본 = GitHub > `_bundled` 우선순위, `bundled` = `_bundled` 단독, `github` = GitHub 단독)
- `--layout-strategy`: 사용자 수정 레이아웃 처리 (`overwrite` = 전체 덮어쓰기, `keep` = 수정분 보존)
- `--vendor-mode`: vendor 설치 방식 (`auto` 기본, `composer`, `bundled`)
**수행 작업**:
- 업데이트 가용 여부 확인 (없으면 info + SUCCESS, `--force` 시 무시하고 진행)
@@ -239,6 +242,8 @@ php artisan module:update [identifier] [--force]
```bash
php artisan module:update sirsoft-ecommerce
php artisan module:update sirsoft-ecommerce --force # 강제 재설치
php artisan module:update sirsoft-ecommerce --source=bundled # GitHub 장애/잘못된 태그 우회
php artisan module:update sirsoft-ecommerce --source=github --force # 긴급 핫픽스 태그로만 강제 설치
```
#### 모듈 캐시 초기화
+7 -6
View File
@@ -495,12 +495,14 @@ $content = $layoutData;
### 무효화 메서드
```php
use App\Contracts\Extension\CacheInterface;
protected function invalidateLayoutCache(string $moduleIdentifier): void
{
// 1. 태그 기반 캐시 삭제
if (method_exists(Cache::getStore(), 'tags')) {
Cache::tags(['layouts', $moduleIdentifier])->flush();
}
$cache = app(CacheInterface::class); // 드라이버가 `g7:core:` 접두사 자동 적용
// 1. 태그 기반 캐시 삭제 (CacheInterface::flushTags)
$cache->flushTags(['layouts', $moduleIdentifier]);
// 2. 개별 레이아웃 캐시 삭제
$moduleLayouts = TemplateLayout::where('source_type', LayoutSourceType::Module)
@@ -508,8 +510,7 @@ protected function invalidateLayoutCache(string $moduleIdentifier): void
->get();
foreach ($moduleLayouts as $layout) {
$cacheKey = "layout.{$layout->template_id}.{$layout->name}";
Cache::forget($cacheKey);
$cache->forget("template.{$layout->template_id}.layout.{$layout->name}");
}
}
```
+104
View File
@@ -117,6 +117,83 @@ public function isAdmin(): bool
],
```
### 코어 권한에서 타입 지정 (config/core.php)
코어 권한(`config/core.php`의 `categories`)도 모듈/플러그인 매니페스트와 **동일하게 `type` 필드를 지원**합니다. `CoreUpdateService::syncCoreRolesAndPermissions()`가 이 필드를 읽어 admin/user 컨텍스트를 분리합니다.
```php
// config/core.php
'categories' => [
[
'identifier' => 'core.users',
'category' => 'users',
'order' => 1,
'type' => 'admin', // ← 카테고리 타입 명시
'permissions' => [
['identifier' => 'core.users.read', 'type' => 'admin', ...], // ← 권한 타입 명시
['identifier' => 'core.users.create', 'type' => 'admin', ...],
],
],
[
'identifier' => 'core.user-notifications',
'category' => 'user-notifications',
'order' => 7.6,
'type' => 'user', // ← 사용자 컨텍스트 카테고리
'permissions' => [
['identifier' => 'core.user-notifications.read', 'type' => 'user', ...],
],
],
],
```
```text
✅ 필수: 신규 코어 권한 정의 시 카테고리/개별 권한 모두에 `type` 명시 (가독성 + 의도 명확화)
✅ 카테고리 type은 (1) 명시 필드 (2) 하위 권한이 모두 동일 type일 때 추론 (3) admin 기본값 우선순위로 결정됨
✅ 권한 type 미지정 시 카테고리 type을 상속
```
### CRITICAL: 단일 unique 제약 함정
```text
⚠️ CRITICAL: permissions.identifier 컬럼은 단일 unique 제약입니다.
⚠️ 같은 식별자로 (identifier='core.notifications.read', type='admin')과 (identifier='core.notifications.read', type='user') 두 행을 동시에 생성할 수 없습니다.
```
| 잘못된 접근 | 올바른 접근 |
|---|---|
| `core.notifications.*` 하나의 식별자를 admin/user 양쪽에서 사용 | admin은 `core.notifications.*` (`type=admin`), 사용자는 `core.user-notifications.*` (`type=user`)로 **별도 식별자** 분리 |
| 라우트 미들웨어에서 admin 식별자를 user 컨텍스트에 사용 | 사용자 라우트(`/api/user/...`)는 반드시 `type=user` 권한 행이 존재하는 식별자를 사용 |
`PermissionMiddleware`는 `(identifier, type)` 쌍으로 권한 행을 조회하므로, 라우트 미들웨어 `permission:user,xxx`는 DB에 `(identifier='xxx', type='user')` 행이 존재할 때만 통과합니다.
### 라우트 미들웨어 type 일치 규칙
```php
// routes/api.php
// ❌ 잘못된 예: 사용자 라우트에 admin 타입 권한 식별자 사용
Route::get('/api/user/notifications', [UserNotificationController::class, 'index'])
->middleware('permission:user,core.notifications.read'); // 항상 403 — type 불일치
// ✅ 올바른 예: 사용자 라우트에는 user 타입 권한 식별자 사용
Route::get('/api/user/notifications', [UserNotificationController::class, 'index'])
->middleware('permission:user,core.user-notifications.read');
// ✅ 관리자 라우트에는 admin 타입 권한 식별자 사용
Route::get('/api/admin/notifications', [AdminNotificationController::class, 'index'])
->middleware('permission:admin,core.notifications.read');
```
`Broadcast::channel()` 권한 체크에서도 동일하게 `PermissionType` 인자를 명시해야 합니다:
```php
// routes/channels.php
Broadcast::channel('core.user.notifications.{uuid}', function ($user, $uuid) {
return $user->uuid === $uuid
&& $user->hasPermission('core.user-notifications.read', PermissionType::User);
});
```
### Permission 모델 헬퍼
```php
@@ -808,9 +885,36 @@ generateIdentifier(name)
---
## 완전 동기화 (Stale Cleanup)
코어/확장 업그레이드 시 권한·역할 동기화는 단순 upsert 가 아니라 **완전 동기화** 를 수행합니다. config/manifest 에서 제거된 권한·역할은 DB 에서도 삭제됩니다.
### 적용 지점
| 경로 | 호출 시점 | cleanup 대상 |
|---|---|---|
| `CoreUpdateService::syncCoreRolesAndPermissions` 말미 | 코어 업데이트 | `core/core` 소유 권한·역할 |
| `ModuleManager::updateModule` 내 sync 블록 말미 | 모듈 업데이트 | 해당 모듈 소유 권한·역할 |
| `PluginManager::updatePlugin` 내 sync 블록 말미 | 플러그인 업데이트 | 해당 플러그인 소유 권한·역할 |
### 핵심 정책
- **권한 stale 삭제**: 순수 diff — config 에 없으면 즉시 삭제 (user_overrides 개념 없음)
- **역할 stale 삭제**: config 에 없으면 삭제. 단 **`user_roles` 피벗에 사용자가 참조 중인 역할은 삭제 차단 + 경고 로그** (수동 재배정 유도)
- **역할-권한 매핑**: `syncAllRoleAssignments` 가 `core/core` 전체 권한을 diff 기준으로 사용하여 이관된 구 식별자도 detach
### Helper (권장)
직접 Model 조작 금지. `ExtensionRoleSyncHelper` 를 통해 sync/cleanup 수행. 자세한 사용법은 [data-sync-helpers.md](../backend/data-sync-helpers.md#4-extensionrolesynchelper) 참조.
---
## 관련 문서
- [menus.md](./menus.md) - 메뉴 권한 시스템
- [hooks.md](./hooks.md) - 훅 권한 시스템
- [module-basics.md](./module-basics.md) - 모듈 기본 구조
- [index.md](./index.md) - 확장 시스템 인덱스
- [../backend/core-config.md](../backend/core-config.md#완전-동기화-원칙) - 완전 동기화 원칙
- [../backend/data-sync-helpers.md](../backend/data-sync-helpers.md) - 데이터 동기화 Helper
- [../backend/user-overrides.md](../backend/user-overrides.md) - 사용자 수정 보존
+64 -2
View File
@@ -215,7 +215,7 @@ class Plugin implements PluginInterface
| 메서드 | 반환 타입 | 설명 |
|--------|----------|------|
| `getIdentifier()` | `string` | 디렉토리명에서 자동 추론 (예: `sirsoft-payment`) |
| `getVendor()` | `string` | 디렉토리명에서 자동 추론 (예: `sirsoft`) |
| `getVendor()` | `string` | `plugin.json` 의 `vendor` 필드를 우선 사용. 값이 없으면 디렉토리명의 첫 단어로 폴백 (예: `sirsoft`) |
### 기본값 제공 메서드 (필요시 오버라이드)
@@ -226,10 +226,14 @@ class Plugin implements PluginInterface
| `activate()` | `true` | 활성화 로직 |
| `deactivate()` | `true` | 비활성화 로직 |
| `getDynamicTables()` | `[]` | 런타임 동적 생성 테이블 목록 (언인스톨 시 Manager가 삭제) |
| `getDynamicPermissionIdentifiers()` | `[]` | 런타임 생성 권한 식별자 — stale cleanup 보존 대상 |
| `getDynamicRoleIdentifiers()` | `[]` | 런타임 생성 역할 식별자 — stale cleanup 보존 대상 |
| `getDependencies()` | `[]` | 의존하는 모듈/플러그인 목록 |
| `getHookListeners()` | `[]` | 훅 리스너 클래스 목록 |
| `upgrades()` | `[]` | 업그레이드 스텝 (`upgrades/` 디렉토리 자동 발견) |
> **동적 식별자 보존 규칙**: `Permission::updateOrCreate()` / `Role::firstOrCreate()` 등으로 런타임에 생성한 엔티티는 업데이트 시 `cleanupStalePluginEntries` 에 의해 "정적 정의에 없는 고아 레코드" 로 판정되어 삭제될 위험이 있습니다. 이를 방지하려면 동적 식별자 목록을 위 3개 훅에서 반환하세요 — 정적 정의 + 동적 식별자가 병합된 expected 목록을 기준으로 판정되어 보존됩니다. 상세는 [extension-update-system.md](extension-update-system.md) 참조.
---
## composer.json 작성법
@@ -311,7 +315,7 @@ plugins/_bundled/sirsoft-payment/
| 디렉토리 | 설명 |
|----------|------|
| `plugin.json` | 메타데이터 SSoT (이름, 버전, 설명, 의존성, 라이선스 등) |
| `plugin.json` | 메타데이터 SSoT (이름, 버전, 설명, 의존성, 라이선스 등) — 버전 제약 정책은 [changelog-rules.md](changelog-rules.md#8-코어-버전-제약-정책) 참조 |
| `plugin.php` | PluginInterface 구현 파일 (루트에 위치) |
| `LICENSE` | 라이선스 전문 (MIT 등) — API 엔드포인트 `GET /api/admin/plugins/{identifier}/license`로 제공 |
| `composer.json` | PSR-4 오토로딩 + 외부 패키지 의존성 설정 |
@@ -1144,6 +1148,64 @@ php artisan plugin:seed sirsoft-payment --force
---
## SEO 변수 선언 (seoVariables)
플러그인이 SEO 메타 데이터(제목/설명)에 동적 변수를 제공하려면 `seoVariables()` 메서드를 오버라이드합니다. 모듈과 동일한 API입니다.
### 오버라이드 시점
- 플러그인이 SEO 대상 페이지(예: 결제 완료 페이지)를 layout_extensions로 확장하는 경우
- 플러그인 설정의 SEO 템플릿에서 `{key}` 변수 치환이 필요한 경우
### 구조
```php
public function seoVariables(): array
{
return [
'_common' => [
'site_name' => ['source' => 'core_setting', 'key' => 'general.site_name'],
],
'checkout' => [
'payment_name' => ['source' => 'setting', 'key' => 'basic.payment_name'],
],
];
}
```
### 소스 타입
| source | 설명 | 자동 해석 |
|--------|------|----------|
| `setting` | 해당 플러그인의 설정 값 | ✅ |
| `core_setting` | 코어 설정 값 | ✅ |
| `query` | URL 쿼리 파라미터 | ✅ |
| `route` | URL 라우트 파라미터 | ✅ |
| `data` | 데이터소스 응답 데이터 (레이아웃 `vars`에서 매핑 필요) | ❌ |
### 레이아웃에서 사용
레이아웃 JSON의 `meta.seo.extensions`에 플러그인을 선언합니다.
```json
{
"meta": {
"seo": {
"extensions": [{ "type": "plugin", "id": "sirsoft-payment" }],
"page_type": "checkout"
}
}
}
```
- `_common` 키: 모든 page_type에 공통 적용 (page_type별 선언이 우선)
- 설치 시 `ValidatesSeoVariables` 트레이트가 변수명 고유성 검증
- `data` 소스 변수만 `vars`에서 표현식 매핑 필요, 나머지 소스는 자동 해석
> 상세: [seo-system.md](../backend/seo-system.md) "SEO 변수 시스템" 참조
---
## 관련 문서
- [index.md](index.md) - 확장 시스템 전체 개요
+24 -11
View File
@@ -1,6 +1,11 @@
# 템플릿 캐싱 전략
> **관련 문서**: [template-basics.md](./template-basics.md) | [template-security.md](./template-security.md) | [index.md](./index.md)
> **관련 문서**: [cache-driver.md](./cache-driver.md) (공통 캐시 인터페이스 · 권장) | [template-basics.md](./template-basics.md) | [template-security.md](./template-security.md) | [index.md](./index.md)
> **⚠️ 중요**: 본 문서는 템플릿 캐싱의 **개념적 계층**을 설명합니다.
> 실제 구현은 [`CacheInterface`](./cache-driver.md) 를 사용해야 하며, `Cache::` 파사드 직접 호출은 금지되었습니다.
> 모든 캐시 키는 드라이버 접두사(`g7:core:` / `g7:module.{id}:` / `g7:plugin.{id}:`)가 자동 적용됩니다.
> TTL 은 `g7_core_settings('cache.*_ttl')` 중앙 관리를 따릅니다.
---
@@ -123,36 +128,44 @@ Cache::rememberForever("template.components.sirsoft-admin_basic", function () us
#### ClearsTemplateCaches Trait
모듈/플러그인/템플릿 매니저에서 사용하는 공통 trait입니다.
모듈/플러그인/템플릿 매니저에서 사용하는 공통 trait입니다. 내부적으로 `CacheInterface` 를 lazy resolve 해서 사용합니다.
```php
<?php
namespace App\Extension\Traits;
use Illuminate\Support\Facades\Cache;
use App\Contracts\Extension\CacheInterface;
use App\Extension\Cache\CoreCacheDriver;
trait ClearsTemplateCaches
{
// 드라이버 접두사 `g7:core:` 가 자동 적용되어 실제 저장 키는 `g7:core:ext.cache_version`
private static string $extensionCacheVersionKey = 'ext.cache_version';
/**
* 확장 기능 캐시 버전을 증가시킵니다.
*
* 모듈/플러그인 활성화/비활성화 시 호출되어
* 프론트엔드가 새로운 캐시 버전으로 API를 요청하도록 합니다.
*/
protected function incrementExtensionCacheVersion(): void
{
Cache::put('extension_cache_version', time());
self::resolveExtensionCache()->put(self::$extensionCacheVersionKey, time());
}
/**
* 현재 확장 기능 캐시 버전을 반환합니다.
*
* @return int 캐시 버전 (타임스탬프) 또는 0 (미설정 시)
*/
public static function getExtensionCacheVersion(): int
{
return (int) Cache::get('extension_cache_version', 0);
return (int) self::resolveExtensionCache()->get(self::$extensionCacheVersionKey, 0);
}
private static function resolveExtensionCache(): CacheInterface
{
try {
return app(CacheInterface::class);
} catch (\Throwable $e) {
return new CoreCacheDriver(config('cache.default', 'array'));
}
}
/**
@@ -294,7 +307,7 @@ Route::get('/extension/cache-version', function () {
| 저장소 | 키 | 값 | 용도 |
|--------|-----|-----|------|
| Laravel Cache | `extension_cache_version` | 타임스탬프 | 서버 측 버전 관리 |
| Laravel Cache | `g7:core:ext.cache_version` | 타임스탬프 | 서버 측 버전 관리 (CacheInterface 경유) |
| localStorage | `g7_extension_cache_version` | 타임스탬프 | 클라이언트 측 버전 유지 |
---
+5 -1
View File
@@ -147,7 +147,7 @@ php artisan template:check-updates sirsoft-admin_basic
템플릿을 업데이트합니다.
```bash
php artisan template:update [identifier] [--layout-strategy=overwrite] [--force]
php artisan template:update [identifier] [--layout-strategy=overwrite] [--force] [--source=auto|bundled|github]
```
**인수**:
@@ -156,6 +156,7 @@ php artisan template:update [identifier] [--layout-strategy=overwrite] [--force]
**옵션**:
- `--layout-strategy=overwrite`: 레이아웃 전략 (`overwrite` | `keep`)
- `--force`: 버전 비교 없이 강제 업데이트 (파일 손상, 수동 수정 복원 시 사용)
- `--source`: 업데이트 소스 강제 (`auto` 기본 = GitHub > `_bundled` 우선순위, `bundled` = `_bundled` 단독, `github` = GitHub 단독)
**수행 작업**:
- 레이아웃 전략 검증 (`overwrite` | `keep` 외 FAILURE)
@@ -174,6 +175,9 @@ php artisan template:update sirsoft-admin_basic --layout-strategy=keep
# 강제 재설치
php artisan template:update sirsoft-admin_basic --force
# GitHub 장애/잘못된 태그 우회 — _bundled 단독 사용
php artisan template:update sirsoft-admin_basic --source=bundled
```
---
+2
View File
@@ -83,6 +83,8 @@ Phase 6: 빌드 및 설치
## Phase 1: 필수 메타데이터 파일
> `g7_version` / `dependencies` 등 버전 제약 작성 규칙은 [changelog-rules.md](changelog-rules.md#8-코어-버전-제약-정책) 참조.
### 1.1 template.json
```json
+414
View File
@@ -0,0 +1,414 @@
# 업그레이드 스텝 작성 가이드 (Upgrade Step Guide)
> 버전 업그레이드 시 실행되는 `upgrades/Upgrade_X_Y_Z.php` 작성 규정
## TL;DR (5초 요약)
```text
1. upgrade step 이 실행되는 환경은 경로에 따라 다르다 — 섹션 9 "업그레이드 경로" 먼저 읽기
2. 대부분의 코어 upgrade step = 경로 B (spawn) → 신규 클래스/메서드 자유 사용 가능
3. 인프라 재설계 릴리즈의 특수 경로 = 경로 C → docblock 에 `@upgrade-path C` 선언 + 로컬 로직 필수
4. 경로 A (모듈/플러그인) · 경로 C 규율: 기존 클래스의 신규 메서드 호출 금지, 로컬 private 헬퍼 우선
5. 모든 분기에 upgrade.log 출력 — 로그 없음 = 디버깅 단서 없음
```
---
## 목차
1. [배경 — 왜 이 가이드가 필요한가](#1-배경--왜-이-가이드가-필요한가)
2. [PHP 클래스 캐싱 제약](#2-php-클래스-캐싱-제약)
3. [작성 규칙](#3-작성-규칙)
4. [허용/금지 패턴](#4-허용금지-패턴)
5. [체크리스트](#5-체크리스트)
6. [sudo 환경 / 소유권 고려사항](#6-sudo-환경--소유권-고려사항)
7. [생명주기와 제거 시점](#7-생명주기와-제거-시점)
8. [실전 사례](#8-실전-사례)
9. [업그레이드 경로별 규율 (모듈/플러그인 · 코어 beta.3+ · 코어 beta.2 특수)](#9-업그레이드-경로별-규율)
---
## 1. 배경 — 왜 이 가이드가 필요한가
`php artisan core:update` 실행 흐름:
```
Step 7 applyUpdate — 디스크의 app/**, config/**, upgrades/** 파일을 새 버전으로 덮어쓰기
Step 8 Composer / vendor — 외부 프로세스 실행으로 vendor 재구성
Step 9 runMigrations — DB 마이그레이션
Step 10 runUpgradeSteps — upgrades/Upgrade_*.php 의 run() 호출 ← 여기
Step 11 Cleanup — 캐시 초기화, 소유권 복원 등
```
**주의**: Step 10 시점에 실행되는 PHP 프로세스는 **Step 1 부터 시작한 "이전 버전" 프로세스** 이다. applyUpdate 로 디스크 파일이 모두 새 버전으로 바뀌어도, 이미 메모리에 로드된 클래스는 재로드되지 않는다.
즉:
- `require_once` 되는 **upgrade 파일 자체** → 신규 파일이므로 새 코드 로드 OK
- upgrade 파일 안에서 참조하는 **다른 클래스** → 이미 메모리에 있는 **이전 버전** 클래스를 사용
## 2. PHP 클래스 캐싱 제약
### 작동 원리
PHP 는 클래스를 한 번 로드하면 동일 프로세스 내에서 재정의 불가. Laravel 의 Composer autoloader 도 마찬가지 — 네임스페이스·클래스명 매핑이 캐시된 뒤에는 파일 교체가 무시된다.
### 구체 시나리오
이전 버전에서 `App\Extension\Helpers\FilePermissionHelper` 가 이미 사용되어 메모리에 로드된 상태에서:
```php
// upgrades/Upgrade_X_Y_Z.php (새 버전 파일)
use App\Extension\Helpers\FilePermissionHelper;
// 새 버전에서 신설한 메서드
FilePermissionHelper::newMethod();
// → Call to undefined method FilePermissionHelper::newMethod() Fatal
```
디스크의 `FilePermissionHelper.php` 는 새 버전으로 바뀌어 `newMethod()` 가 정의되어 있어도, PHP 는 **메모리의 이전 버전 클래스** 를 사용하므로 Fatal.
### 영향 받지 않는 대상
- **신규 추가된 클래스** (이전 버전에 존재하지 않던 파일) → autoload 시 새 코드 로드
- 예: `App\Models\NotificationDefinition` 가 beta.2 에서 처음 도입된 경우, beta.1 → beta.2 upgrade step 에서 사용 가능
### 영향 받는 대상
- **이미 이전 버전에 존재하던 클래스에 새로 추가된 메서드/프로퍼티**
- **이미 이전 버전에 존재하던 클래스의 시그니처 변경**
## 3. 작성 규칙
### 원칙 1 — 로컬 private 로직 우선
upgrade step 이 필요로 하는 로직은 **Upgrade 클래스 내부 private 메서드** 로 직접 작성한다. 공용 Helper 에 유사 로직이 있더라도 **이전 버전에 없는 메서드** 라면 호출 금지.
```php
class Upgrade_7_0_0_beta_2 implements UpgradeStepInterface
{
public function run(UpgradeContext $context): void
{
$this->restoreVendorOwnership($context);
}
// ✅ 로컬 private 메서드 — 메모리의 이전 버전 클래스와 무관
private function restoreVendorOwnership(UpgradeContext $context): void
{
// 로직 인라인 작성
}
}
```
### 원칙 2 — 프레임워크/기존 클래스만 use
use 문은 아래 범주만 허용:
- `Illuminate\*` (Laravel 프레임워크)
- `App\Contracts\Extension\UpgradeStepInterface`, `App\Extension\UpgradeContext`
- **이전 버전에도 이미 존재하던** `App\Models\*`, `App\Services\*` 등
- **새 버전에서 처음 도입된** 클래스 (예: 새 Seeder, 새 Model)
### 원칙 3 — 모든 분기에 upgrade.log 출력
upgrade step 의 로거는 `storage/logs/upgrade-YYYY-MM-DD.log` 에 기록된다. 조기 return 경로에도 **이유를 명시** 하는 로그를 남긴다.
```php
if ($currentOwner === $expectedOwner) {
$context->logger->info('[X.Y.Z] 이미 일치 — 복원 스킵');
return;
}
```
로그 없음은 디버깅 불가를 의미한다. 실패 보고를 받았을 때 **어느 분기에서 return 됐는지 추적할 수 없으면 원인 파악에 많은 시간이 소요**된다.
### 원칙 4 — 멱등성 보장
upgrade step 은 동일 버전으로 재실행될 수 있다(`--force` 옵션). 어떤 분기에서든 반복 실행이 안전해야 한다.
- 파일 생성 전 `File::exists()` 체크
- 테이블/컬럼 조작 전 `Schema::hasTable/hasColumn` 체크
- 데이터 이관은 "이미 이관됨" 플래그로 skip 가능하게 설계
## 4. 허용/금지 패턴
### ❌ 금지 — 기존 클래스의 신규 메서드 호출
```php
use App\Extension\Helpers\FilePermissionHelper;
// FilePermissionHelper 는 이전 버전에도 존재 → 메모리에 구 클래스 로드됨
// inferWebServerOwnership() 가 새 버전에서 신설된 메서드라면 Fatal
FilePermissionHelper::inferWebServerOwnership();
```
### ✅ 허용 — 로컬 헬퍼로 직접 구현
```php
private function inferWebServerOwnershipLocal(): array
{
$baseOwner = @fileowner(base_path());
$candidates = ['storage/logs', 'storage/framework/views', /* ... */];
foreach ($candidates as $candidate) {
$owner = @fileowner(base_path($candidate));
if ($owner !== false && $owner !== $baseOwner) {
return [$owner, @filegroup(base_path($candidate)), $candidate];
}
}
return [$baseOwner, @filegroup(base_path()), 'base_path'];
}
```
### ❌ 금지 — 기존 Model 의 신규 메서드/스코프 호출
```php
use App\Models\User;
// User 가 이전 버전에도 존재 → 메모리 구 클래스
// 새 버전에서 추가된 scope 는 Fatal
User::scopeNewlyAdded()->get();
```
### ✅ 허용 — DB 파사드로 직접 쿼리
```php
use Illuminate\Support\Facades\DB;
DB::table('users')->where(/* ... */)->get();
```
### ✅ 허용 — 새 버전에서 처음 도입된 클래스
```php
// 새 버전에서 처음 추가된 Seeder
use Database\Seeders\NotificationDefinitionSeeder;
(new NotificationDefinitionSeeder())->run();
```
### ✅ 허용 — 프레임워크 파사드
```php
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\File;
use Illuminate\Support\Facades\Schema;
use Illuminate\Support\Facades\DB;
```
## 5. 체크리스트
upgrade step PR 검토 시 아래 항목을 모두 확인:
- [ ] `use App\*` 중 이전 버전에 **이미 존재하던** 클래스의 **새 버전에서 신설된 메서드·프로퍼티** 호출이 없는가?
- [ ] 필요한 로직이 로컬 private 메서드로 작성되어 있는가?
- [ ] 모든 return 분기에 upgrade.log 메시지가 있는가?
- [ ] `--force` 재실행 시 안전한 멱등 동작인가?
- [ ] sudo 실행 환경에서 root 오염이 발생할 수 있는 파일 조작이 있다면 소유권 복원 로직이 포함되었는가?
- [ ] 테스트 환경(`beta.N fresh` → `beta.N+1 update`) 에서 수동 검증을 통과했는가?
## 6. sudo 환경 / 소유권 고려사항
`sudo php artisan core:update` 실행 시:
- 외부 프로세스(composer 등) 가 root 로 파일을 생성
- 파일 시스템 API(`File::copy`, `mkdir` 등) 도 root 소유로 생성
- 원본 소유자(www-data 등) 를 보존하려면 **업데이트 후 명시적 chown 필요**
beta.2 이후 버전은 `CoreUpdateService::snapshotOwnership() + restoreOwnership()` 공통 로직이 Step 11 Cleanup 에서 자동 수행. upgrade step 에서 별도 소유권 복원이 필요한 예외 상황(이전 버전에 해당 로직이 없음) 에서만 인라인 작성.
## 7. 생명주기와 제거 시점
각 upgrade step 은 **해당 버전에서만 필요한 1회성 작업** 을 담당한다. 일반적으로 다음 버전(N+2) 릴리즈 시점에 제거 가능 — 단 아래 조건을 모두 만족해야:
- N → N+1 업그레이드를 수행해야 하는 사용자가 더 이상 없음
- 또는 N → N+2 직접 업그레이드를 공식적으로 미지원
- upgrade step 이 수행한 DB/파일 정리가 새 설치에서는 불필요함
제거 시 upgrade 파일 자체를 삭제하면 된다. upgrade step 내부에서 참조했던 "공용 Helper 메서드" 는 다른 용도로 재사용될 수 있으므로 별도 판단.
## 8. 실전 사례
### 사례 A — beta.2 MailTemplate shim (클래스 캐싱 회피)
beta.1 의 `CoreUpdateService::syncCoreMailTemplates()` 가 `App\Models\MailTemplate::where(...)` 를 호출하는데, beta.2 에서 MailTemplate 이 제거되어 autoload 실패.
해결: beta.2 릴리즈에 `App\Models\MailTemplate` 의 **극소 shim** 을 포함. beta.2 upgrade step 에서 shim 파일과 테이블 자가 정리.
이 경우 shim 파일은 "upgrade step 의 의존성" 이지만 **이전 버전(beta.1) 이 메모리에 올리는 대상** 이므로 upgrade step 밖의 신규 파일로 작성되어야 했다. upgrade step 내부에서 `class_exists` 체크만으로 충분.
### 사례 B — vendor 소유권 복원 (sudo + 비대칭 환경)
beta.1 의 `runComposerInstall(base_path())` 가 sudo 에서 vendor/ 를 root 로 재생성. beta.2 upgrade step 이 storage/ 디렉토리 기준으로 원본 웹서버 계정(www-data) 을 추정하여 vendor/ 복원.
여기서 `FilePermissionHelper::inferWebServerOwnership()` 을 호출했다가 **beta.1 메모리 클래스 캐싱으로 undefined method Fatal** 발생. 로컬 private 메서드로 재작성하여 해결.
이 사례가 본 가이드 작성의 직접 계기다. **"공용 Helper 로 승격" 은 신규 버전 코드 기반에서만 안전** 이라는 교훈.
---
## 9. 업그레이드 경로별 규율
본 가이드의 많은 규칙은 "upgrade step 이 **이전 버전 PHP 프로세스** 메모리에서 실행된다" 는 전제에서 출발한다. 하지만 그누보드7 에는 서로 다른 실행 환경을 가진 **3개 경로** 가 공존하므로, 자신이 작성하는 upgrade step 이 어느 경로인지 먼저 확인해야 한다.
### 경로 A — 모듈/플러그인 upgrade step (기존 규율 유지)
- 실행 주체: `ModuleManager::updateModule()` / `PluginManager::updatePlugin()`
- 실행 환경: **메인 PHP 프로세스** (Artisan 커맨드가 로드된 상태)
- 단, `reloadModule`/`reloadPlugin` 이 `evalFreshModule` 로 **진입점 클래스만 재로드** (`app/Extension/ModuleManager.php` 의 `evalFreshModule`, `PluginManager.php` 의 `evalFreshPlugin` 참조)
- 진입점 메서드(`getPermissions`/`getMenus` 등)는 재로드 덕분에 최신 정의 반환
- 하지만 **그 외 App\* 클래스**(Helper, Service, Model)는 여전히 이전 버전 메모리
- **적용 규율**: 섹션 3~5 의 모든 작성 규칙 적용. 로컬 private 헬퍼 우선, 기존 클래스의 신규 메서드 호출 금지
### 경로 B — 코어 upgrade step (beta.3 이후, 규율 완화)
- 실행 주체: `CoreUpdateCommand` Step 10 → `proc_open` 으로 `core:execute-upgrade-steps` 커맨드 spawn
- 실행 환경: **별도 PHP 프로세스** (새로 시작되어 디스크의 최신 파일로 Composer autoload 수행)
- 모든 클래스·config 가 **최신 버전 기준** 으로 로드됨
- **적용 규율**: 클래스 캐싱 제약 **해제**. upgrade step 이 beta.N+1 의 새 Service/Repository/Controller/Model 등을 자유롭게 호출 가능
- 예외: `proc_open` 미지원 환경에서는 in-process fallback 으로 전환되므로, **신중하게 설계된 upgrade step 은 여전히 경로 A/C 규율도 충족** 하는 것이 안전
- 관련 구현: `app/Console/Commands/Core/ExecuteUpgradeStepsCommand.php`, `CoreUpdateCommand::spawnUpgradeStepsProcess`, `CoreUpdateService::reloadCoreConfigAndResync`
#### spawn 호출 시 필수 env 전파
`proc_open` 을 직접 사용할 때 `$env` 배열은 **반드시 아래 패턴** 으로 구성한다:
```php
$env = array_merge(getenv(), $_ENV, [
'G7_UPDATE_IN_PROGRESS' => '1',
// 필요한 추가 env ...
]);
```
`$_ENV` 단독 사용 금지. `variables_order` php.ini 에 `E` 가 없는 환경에서는 `$_ENV` 가 비어있어 플래그 전파가 누락되고, 자식의 `CoreServiceProvider::validateAndDeactivate*` 가 발동해 활성 확장이 일괄 비활성화되는 회귀가 발생한다. `getenv()` 는 프로세스 environ 테이블을 직접 반환해 `putenv` 로 설정된 값까지 포함한다. 상세 배경: [extension-update-system.md "업데이트 진행 플래그"](extension-update-system.md#업데이트-진행-플래그-g7_update_in_progress).
### 경로 C — 코어 upgrade step (이전 버전 in-process 실행 특수 경로)
- 실행 주체: **이전 버전 CoreUpdateCommand** — 이미 운영 서버에 배포되어 변경 불가
- 실행 환경: **이전 버전의 메인 PHP 프로세스** — 새 릴리즈에서 도입된 spawn 커맨드를 모르므로 호출 안 함
- 새 릴리즈의 재작성된 `CoreUpdateCommand` / `ExecuteUpgradeStepsCommand` 가 설치되어 있어도 이전 버전 CoreUpdateCommand 가 호출하지 않으므로 무용
- **적용 규율**: 섹션 3~5 의 모든 작성 규칙을 **강하게** 적용. upgrade step 파일 내부 로컬 private 로직으로 모든 후처리를 직접 수행
- 허용: 이전 버전에 이미 존재하던 클래스(예: `App\Services\CoreUpdateService`) 의 **기존 메서드** 호출 (예: `syncCoreRolesAndPermissions`, `syncCoreMenus`) — 단 내부에서 `config()` 로 읽는 값이 최신이어야 하므로 `config(['core' => require config_path('core.php')])` 로 선행 재주입 필요
- 금지: 새 릴리즈에서 신설된 메서드(예: `reloadCoreConfigAndResync`) 호출 — 이전 버전 메모리에 존재하지 않음
- 역사적 인스턴스: [`upgrades/Upgrade_7_0_0_beta_2.php`](../../upgrades/Upgrade_7_0_0_beta_2.php) 의 `resyncCorePermissionsAndMenus` 로컬 메서드
### 경로 C 가 필요한 상황 — 발생 조건
대부분의 릴리즈는 경로 B(spawn) 만으로 충분하다. 경로 C 가 필요한 것은 아래 **좁은 조건**일 때만:
**대상 릴리즈가 `CoreUpdateCommand` 의 업그레이드 흐름 자체를 구조적으로 변경** 하여,
- 새 진입점(spawn 커맨드, 신규 Service 메서드, 신규 내부 단계 등)을 도입했고
- 해당 진입점은 **새 버전이 실행 주체일 때만** 활성화되며
- **이전 버전 CoreUpdateCommand 는 그 진입점을 호출하지 않는** 경우
일반적인 기능 추가 / 버그 수정 / 데이터 마이그레이션 릴리즈는 모두 경로 B. 예: beta.3 → beta.4 에서 신규 모듈 도입이나 신규 권한 추가는 모두 경로 B 로 처리된다.
경로 C 는 주로 **인프라 재설계 릴리즈** 에서 1회씩 발생한다. 과거 예: beta.1 → beta.2 의 spawn 구조 도입.
### 경로 C 파일 선언 — 메타데이터 규약
경로 C 로 작성하는 upgrade step 파일은 **docblock 에 메타데이터** 를 명시한다:
```php
/**
* 코어 N.N.N 업그레이드 스텝
*
* @upgrade-path C
*
* 경로 C(이전 버전 CoreUpdateCommand 의 in-process 메모리에서 실행) 선언.
* ... 구체적 사유 ...
*/
class Upgrade_N_N_N implements UpgradeStepInterface
```
`@upgrade-path C` 선언은 아래 자동화 스크립트가 인식한다:
- [`.claude/scripts/validate-upgrade-step.cjs`](../../.claude/scripts/validate-upgrade-step.cjs) — 파일 내용을 파싱하여 경로 C 선언 시 강한 규율 경고 적용
- [`.claude/scripts/file-rules.cjs`](../../.claude/scripts/file-rules.cjs) — 동일 선언 기반으로 `upgradeStep` 규칙이 경로 C 위반(기존 코어 클래스 use 문) 감지
선언이 없으면 **경로 B** 로 판정되어 규율이 완화된다 (신규 클래스/메서드 자유 사용).
### 경로 판별 체크리스트
upgrade step 작성 전 다음을 확인:
1. 확장(모듈/플러그인) upgrade step 인가? → **경로 A**
2. 코어 upgrade step 인가?
- 대상 릴리즈가 인프라 재설계(spawn 구조 등) 를 포함하여 이전 버전이 새 진입점을 모르는가?
- **예** → **경로 C**, 파일에 `@upgrade-path C` 선언 + 로컬 로직 필수
- **아니오** → **경로 B**, 규율 완화 (대부분의 경우)
경로 B 라고 판단했더라도, proc_open 차단 환경에서는 in-process fallback 이 작동하므로 **가능하면 경로 A/C 규율도 충족** 하도록 작성하는 것이 안전하다.
---
## 10. 경로 C 내부 inline spawn 패턴
경로 C 에서 **새 릴리즈 클래스 로직이 꼭 필요한** 경우, upgrade step 파일 자체가 `proc_open` 으로 새 PHP 프로세스를 띄우면 된다. 새 프로세스는 디스크의 최신 파일을 autoload 하므로 클래스 캐싱과 무관.
```php
private function spawnResyncInline(UpgradeContext $context): bool
{
if (! function_exists('proc_open')) {
return false;
}
$basePath = base_path();
$phpCode = <<<'PHP'
$base = getenv('G7_BASE_PATH');
chdir($base);
require $base.'/vendor/autoload.php';
$app = require $base.'/bootstrap/app.php';
$app->make(Illuminate\Contracts\Console\Kernel::class)->bootstrap();
app(App\Services\CoreUpdateService::class)->reloadCoreConfigAndResync();
echo "OK\n";
PHP;
$cmd = escapeshellarg(PHP_BINARY).' -r '.escapeshellarg($phpCode).' 2>&1';
$process = proc_open($cmd, [/* descriptors */], $pipes, $basePath,
array_merge($_ENV, ['G7_BASE_PATH' => $basePath]));
if (! is_resource($process)) return false;
// ... stdout 수집 + proc_close 검증
return $exitCode === 0 && str_contains($stdout, 'OK');
}
```
### 적용 원칙
- **전용 아티산 커맨드 금지**: 1회성 로직이 beta.3 cleanup 시 upgrade step 파일 삭제와 함께 자연 소거되어야 함
- **Fallback 필수**: `proc_open` 미지원 환경에서는 in-process fallback + 수동 복구 안내 로그
- **Idempotent 보장**: spawn 성공/실패 무관하게 재실행 시 no-op
### 역사적 인스턴스
- `upgrades/Upgrade_7_0_0_beta_2.php::spawnResyncInlineLocal` — 경로 C 에서 beta.2 최신 `reloadCoreConfigAndResync()` 호출
---
## 11. 업그레이드 후 데이터 정합성 (완전 동기화)
upgrade step 이 수행하는 데이터 변경은 단순 "마이그레이션" 이 아니라 **완전 동기화** 를 지향한다. 즉:
1. **Upsert**: config/seeder → DB 반영
2. **Orphan Delete**: config 에 없는 DB row 삭제 (user_overrides 무관)
3. **Mapping Diff**: 관계 테이블 재정렬
4. **Dependent Cleanup**: 삭제된 상위 엔티티 하위 정리
세부 정책과 Helper 사용법은 다음을 참조:
- [완전 동기화 원칙](../backend/core-config.md#완전-동기화-원칙) — 4단계 패턴의 상세 정의
- [데이터 동기화 Helper 5종](../backend/data-sync-helpers.md) — Menu/Role/Notification/FilePermission/Generic
- [사용자 수정 보존 (HasUserOverrides)](../backend/user-overrides.md) — trait 사용 및 mass update 투명 추적
---
## 관련 문서
- [코어 업데이트 시스템](../backend/core-update-system.md)
- [확장 업데이트 시스템](extension-update-system.md)
- [Changelog 규칙](changelog-rules.md)
- [데이터 동기화 Helper](../backend/data-sync-helpers.md)
- [사용자 수정 보존](../backend/user-overrides.md)
+274
View File
@@ -0,0 +1,274 @@
# Vendor 번들 시스템 (Vendor Bundle System)
## TL;DR (5초 요약)
```text
- Composer 사용 불가 환경(공유 호스팅 등)을 위해 vendor/ 디렉토리를 zip으로 선탑재
- 개별 빌드: php artisan {core|module|plugin}:vendor-bundle [identifier|--all]
- 일괄 빌드: php artisan vendor-bundle:build-all (코어 + 모든 _bundled)
- 개별/일괄 검증: {core|module|plugin}:vendor-verify, vendor-bundle:verify-all
- 모드: VendorMode = auto | composer | bundled
- 결정 순서: 명시 → DB 이전 모드 → config → 환경감지(composer 가능 시 우선)
```
## 1. 개요
G7 코어와 모듈/플러그인은 PHP 의존성 관리에 Composer를 사용합니다. 그러나 일부 운영 환경(공유 호스팅, 제한된 PaaS)에서는 `proc_open()`/`shell_exec()` 함수가 차단되어 Composer를 실행할 수 없습니다. **Vendor 번들 시스템**은 미리 압축된 `vendor-bundle.zip` 파일을 추출하여 vendor/ 디렉토리를 구성하는 대안 방식을 제공합니다.
### 1.1 핵심 파일
각 코어/확장 루트에 두 파일이 함께 존재합니다:
```text
{root}/
├── composer.json (의존성 정의)
├── composer.lock (락 파일)
├── vendor-bundle.zip (압축된 vendor 디렉토리)
└── vendor-bundle.json (메타파일: SHA256, 패키지 목록 등)
```
`vendor-bundle.json` 스키마 (v1.0):
```json
{
"schema_version": "1.0",
"generated_at": "2026-04-14T12:34:56+09:00",
"generator": "g7 vendor-bundle:build",
"target": "core" | "module:identifier" | "plugin:identifier",
"composer_json_sha256": "...",
"composer_lock_sha256": "...",
"zip_sha256": "...",
"zip_size": 12345678,
"package_count": 142,
"php_requirement": "^8.2",
"g7_version": "7.0.0-beta.4",
"packages": [
{ "name": "laravel/framework", "version": "12.0.5", "type": "library" }
]
}
```
## 2. VendorMode
세 가지 모드가 있습니다:
| 모드 | 설명 |
|------|------|
| `auto` | 환경 감지 — composer 사용 가능 시 composer, 불가 시 bundled |
| `composer` | 강제 composer 실행 (불가 시 예외) |
| `bundled` | 강제 vendor-bundle.zip 추출 (zip 없으면 예외) |
### 2.1 모드 결정 우선순위
`VendorResolver::resolveMode()` 의 우선순위:
```text
1. CLI/API 명시 (--vendor-mode 또는 vendor_mode 파라미터)
└─ composer/bundled 명시 시 그대로 사용
2. 업데이트 시 DB 이전 모드 상속
└─ modules.vendor_mode / plugins.vendor_mode 컬럼이 auto가 아니면 상속
3. 전역 설정 config('app.install.default_vendor_mode')
4. auto 해석 → 환경 감지
a. EnvironmentDetector::canExecuteComposer() == true → Composer
b. composer 불가 + vendor-bundle.zip 존재 → Bundled
c. 둘 다 불가 → 예외 (no_vendor_strategy_available)
```
**핵심 원칙**: auto 모드에서는 **composer가 우선**입니다 (개발 환경과 프로덕션 동작 일치).
## 3. CLI 사용법
본 시스템은 **개별 명령** 6개와 **일괄 알리아스** 2개로 구성됩니다. 개별 명령은 기존
`core:build` / `module:build` / `plugin:build` 패턴과 정렬되어 있습니다.
### 3.1 개별 빌드 — 코어/모듈/플러그인
```bash
# 코어 단독 빌드
php artisan core:vendor-bundle [--check] [--force]
# 특정 모듈 빌드 (positional identifier — module:build 와 동일 패턴)
php artisan module:vendor-bundle sirsoft-ecommerce [--check] [--force]
# 모든 _bundled 모듈 빌드 (--all 명시 필요)
php artisan module:vendor-bundle --all [--check] [--force]
# 특정 플러그인 빌드
php artisan plugin:vendor-bundle sirsoft-payment [--check] [--force]
# 모든 _bundled 플러그인 빌드
php artisan plugin:vendor-bundle --all [--check] [--force]
```
식별자도 `--all` 도 지정하지 않으면 명시적 에러가 발생합니다 (의도하지 않은 일괄
실행 방지). 기존 `module:build` / `plugin:build` 와 동일한 안전 동작입니다.
### 3.2 개별 검증
```bash
php artisan core:vendor-verify
php artisan module:vendor-verify sirsoft-ecommerce
php artisan module:vendor-verify --all
php artisan plugin:vendor-verify sirsoft-payment
php artisan plugin:vendor-verify --all
```
### 3.3 일괄 알리아스 — 운영/CI 시나리오
코어 + 모든 `_bundled` 모듈/플러그인을 한 번에 처리하려면 일괄 알리아스를 사용합니다.
```bash
# 일괄 빌드 (코어 + 모든 _bundled 모듈/플러그인)
php artisan vendor-bundle:build-all [--check] [--force]
# 일괄 검증
php artisan vendor-bundle:verify-all
```
`vendor-bundle:build-all --check` 는 stale 감지 시 종료 코드 1을 반환하므로 CI
파이프라인의 사전 검증 단계에 유용합니다.
### 3.4 옵션 요약
| 옵션 | 동작 |
| ---- | ---- |
| `--check` | 실제 빌드 없이 stale 여부만 확인. stale 발견 시 종료 코드 1 |
| `--force` | composer.json/lock 해시 체크를 무시하고 강제 재빌드 |
| `--all` | (개별 명령에서) 해당 타입의 모든 `_bundled` 확장 대상 |
### 3.5 검증 항목
- vendor-bundle.zip / vendor-bundle.json 파일 존재
- manifest의 schema_version 지원 여부
- zip 파일의 SHA256 해시 일치
- composer.json/composer.lock SHA256 일치 (소스에 존재 시)
## 4. 코어 업데이트
```bash
# Auto 모드 (기본값)
php artisan core:update
# Composer 강제
php artisan core:update --vendor-mode=composer
# 번들 강제 (공유 호스팅 환경)
php artisan core:update --vendor-mode=bundled
# 로컬 + 번들 강제 (개발 시 번들 검증)
php artisan core:update --local --force --vendor-mode=bundled
```
## 5. 확장 설치/업데이트
### 5.1 CLI
```bash
# 모듈 설치 (auto)
php artisan module:install sirsoft-ecommerce
# 모듈 bundled 강제 설치
php artisan module:install sirsoft-ecommerce --vendor-mode=bundled
# 플러그인 업데이트 (이전 모드 상속)
php artisan plugin:update sirsoft-payment
# 플러그인 force 업데이트 + composer 강제
php artisan plugin:update sirsoft-payment --force --vendor-mode=composer
```
### 5.2 Admin UI
관리자 페이지의 모듈/플러그인 설치 모달에 **Vendor 설치 방식** Select 필드가 있습니다:
- 자동 (권장)
- Composer 실행
- 번들 Vendor 사용
### 5.3 API
```http
POST /api/admin/modules/install
Content-Type: application/json
{
"module_name": "sirsoft-ecommerce",
"vendor_mode": "bundled"
}
```
## 6. 웹 인스톨러
`public/install/` 마법사의 Step 3(환경 설정)에서 Vendor 설치 방식을 선택할 수 있습니다.
- 환경 감지: ZipArchive 확장 + proc_open 사용 가능 여부
- 비활성 옵션: 환경에서 사용 불가한 모드는 자동 비활성화
- 자동 폴백: auto 모드에서 composer 실행 불가 시 vendor-bundle.zip이 있으면 자동 전환
## 7. 무결성 검증 및 보안
### 7.1 SHA256 검증
`VendorIntegrityChecker::verify()` 가 다음을 검증합니다:
- vendor-bundle.zip 파일의 실제 SHA256 vs manifest 기록 값
- composer.json SHA256 (소스에 존재 시)
- composer.lock SHA256 (소스에 존재 시)
검증 실패 시 `VendorInstallException` 이 발생하며 설치가 중단됩니다.
### 7.2 Zip Slip 방지
추출 전 zip 내부 모든 파일 경로를 검증합니다:
- `../` 포함 경로 거부
- 절대 경로 거부 (`/...`, `C:/...`)
## 8. 자동 트리거
`composer.json` 또는 `composer.lock` 파일이 변경되면 번들이 stale 상태가 됩니다.
다음 명령으로 재빌드해야 합니다:
```bash
# stale 여부 확인
php artisan vendor-bundle:build-all --check
# 일괄 재빌드
php artisan vendor-bundle:build-all
```
CI 통합 예시:
```yaml
- name: Verify vendor bundles
run: php artisan vendor-bundle:build-all --check
```
## 9. 핵심 클래스
| 클래스 | 책임 |
|--------|------|
| [VendorMode](../../app/Extension/Vendor/VendorMode.php) | 모드 enum (Auto/Composer/Bundled) |
| [VendorResolver](../../app/Extension/Vendor/VendorResolver.php) | 모드 결정 + 전략 디스패치 |
| [VendorBundler](../../app/Extension/Vendor/VendorBundler.php) | zip 빌드 (개발 타임) |
| [VendorBundleInstaller](../../app/Extension/Vendor/VendorBundleInstaller.php) | zip 추출 (런타임) |
| [VendorIntegrityChecker](../../app/Extension/Vendor/VendorIntegrityChecker.php) | SHA256 무결성 검증 |
| [EnvironmentDetector](../../app/Extension/Vendor/EnvironmentDetector.php) | composer/zip 환경 감지 |
| [VendorInstallException](../../app/Extension/Vendor/Exceptions/VendorInstallException.php) | vendor 관련 예외 |
## 10. 트러블슈팅
| 증상 | 원인 | 해결 |
|------|------|------|
| `bundle_zip_missing` | vendor-bundle.zip 파일 없음 | `vendor-bundle:build` 실행 |
| `zip_hash_mismatch` | zip 파일 손상 또는 변조 | `vendor-bundle:build --force` 재빌드 |
| `composer_json_sha_mismatch` | composer.json 변경 후 번들 미갱신 | `vendor-bundle:build` 재빌드 |
| `composer_not_available` | composer 모드 강제했으나 실행 불가 | --vendor-mode=auto 또는 bundled로 변경 |
| `no_vendor_strategy_available` | composer 불가 + 번들 없음 | vendor-bundle.zip 업로드 또는 호스팅 변경 |
| `bundle_contains_unsafe_path` | 외부 zip 파일이 zip slip 시도 | 신뢰할 수 있는 소스에서만 다운로드 |
## 11. 참고
- 본 문서는 vendor 번들 시스템의 사용자 가이드입니다.
- Bundle 자체는 .gitignore 에 등록되어 Git 추적되지 않습니다 (Release asset 형태로 배포 권장).
- 확장 설치 모드는 `modules.vendor_mode` / `plugins.vendor_mode` 컬럼에 기록되며, 업데이트 시 자동 상속됩니다.