v7.0.0 release

This commit is contained in:
HeuJung committed 2026-07-01 10:30:32 +09:00
1 parent 0e7fa04b03
commit c4ea9a6cd1
3582 files changed
+626189 -160151

No files matched your search

+12
View File
@@ -181,6 +181,18 @@ HookManager::broadcast("core.user.notifications.{$user->uuid}", 'notification.re
> **중요**: 웹소켓 OFF 시 `broadcasting.default`가 `'null'`로 강제되는 동작은 `.env`의 `BROADCAST_CONNECTION` 값을 무시하고 적용됩니다. 따라서 운영자가 환경설정에서 OFF한 경우, `.env`에 `REVERB_HOST=localhost` 등이 남아 있어도 broadcast 시도가 발생하지 않습니다. 알림 시스템(mail/database 채널)은 이 설정과 독립적으로 정상 동작합니다.
#### 웹소켓 토글은 전 계층 SSoT (송신 · 프론트연결 · 채널인증)
웹소켓 사용 OFF 는 **송신 계층만** 막는 것이 아니라 다음 세 계층을 모두 차단합니다 (`websocket_enabled` 가 단일 SSoT):
| 계층 | OFF 시 동작 | 구현 |
|------|------------|------|
| ① 백엔드 송신 | `broadcasting.default='null'` → `HookManager::broadcast()` 즉시 return | `applyWebsocketConfig()` |
| ② 프론트 연결 | `broadcasting.connections.reverb.key` 를 빈 문자열로 무력화 → Blade `@if(reverb.key)` false → 브라우저 WebSocket 미연결 | `applyWebsocketConfig()` OFF 분기 |
| ③ 채널 인증 | `POST /api/broadcasting/auth` 가 `broadcasting.default==='null'` 이면 403 | `routes/api.php` 가드 |
따라서 `.env` 에 `REVERB_APP_KEY` 가 살아 있고 Reverb 서버가 운영자 OS 레벨로 기동 중이어도, 토글 OFF 면 프론트가 연결을 시도하지 않고 직접 연결 시도도 채널 인증 단계에서 거부됩니다. `.env` 는 토글 ON 일 때만 자격증명·endpoint 소스로 사용됩니다.
### 채널 타입
| 타입 | 클래스 | 용도 | 인증 필요 |
+56 -1
View File
@@ -28,9 +28,19 @@ applies_to 는 permission 기반 admin 판정 (User::isAdmin() — type='admin'
| `enabled` | 활성 여부 | bool |
| `grace_minutes` | 통과 유예 시간 | 0 = 매번 요구, n = n분 내 verified 있으면 통과 |
| `fail_mode` | 실패 시 동작 | `block` (예외) / `log_only` (감사 로그만) |
| `priority` | 매칭 우선순위 | 높을수록 먼저 평가 |
| `priority` | 매칭 우선순위 | 높을수록 먼저 평가. 동률이면 id 오름차순(먼저 생성된 정책 우선)으로 결정적 정렬. 운영자 UI 에서 같은 scope+target 에 동률 활성 정책 저장은 차단 — §1.1 |
| `conditions` | 추가 매칭 조건 (JSON) | `http_method` / `changed_fields` / `user_role` / `signup_stage` |
### 1.1 priority 동률 처리
같은 `scope`+`target` 에 여러 정책이 걸릴 수 있고, enforce 는 `priority` 내림차순으로 순회해 가장 먼저 차단(428)하는 정책을 적용한다. `priority` 가 같으면 적용 순서가 비결정적이 되어 "운영자가 의도한 정책(예: 성인 인증)이 무시되고 임의 정책이 먼저 적용"되는 결함이 발생했다. 두 층위로 차단한다:
1. **결정적 정렬** — `IdentityPolicyRepository::resolveByScopeTarget()` / `getRouteScopeIndex()` 가 `orderByDesc('priority')->orderBy('id')` 로 정렬. 동률이어도 항상 id 오름차순(먼저 생성된 정책 우선)이라 enforce 순서가 캐시 재빌드/실행계획과 무관하게 고정된다.
2. **동률 저장 차단** — 운영자가 관리자 UI 에서 정책을 생성/수정할 때, 같은 `scope`+`target` 에 **동일 priority 활성 정책**이 이미 있으면 422 로 거부한다 (`App\Rules\UniquePolicyPriorityPerTarget`, Store/Update FormRequest). 비활성(`enabled=false`) 정책은 enforce 대상이 아니므로 동률이어도 무해 — 저장하려는 정책과 기존 정책이 **둘 다 활성**일 때만 충돌로 본다.
운영자 입력 UI: 정책 폼 모달의 "우선순위" 입력칸(0~65535, 기본 100) + 정책 목록의 "우선순위" 컬럼. 코어(`sirsoft-admin_basic`)·모듈(`sirsoft-board`/`sirsoft-ecommerce`) 환경설정 정책 탭 모두 동일.
## 2. 두 가지 enforce 경로 (모두 동적 — 정책 DB toggle 만으로 즉시 효과)
### 2.1 라우트 자동 매핑 (scope=route)
@@ -120,6 +130,51 @@ HookManager::addFilter(
**보안**: 훅이 `IdentityPolicy` 외 타입(`null` 등)을 반환하면 원본 정책이 그대로 유지됩니다 (silent retention). 의도적으로 정책을 변경하려면 반드시 `IdentityPolicy` 인스턴스를 반환할 것.
## 5.1 정책 provider_id 해석 — fallback 체인
`IdentityPolicyService::enforce()` 는 정책 위반 시 `IdentityVerificationRequiredException` 을 던지는데, 정책에 `provider_id` 가 명시되지 않은 경우 `resolveProviderId()` 가 환경설정의 기본 프로바이더로 자동 fallback 합니다. 운영자가 정책마다 provider 를 일일이 지정하지 않아도 환경설정 default 가 일관 적용되도록 보장합니다.
해석 순서:
1. 정책 `provider_id` 가 등록된 provider 면 그대로 사용
2. 정책 미명시 또는 미등록 provider → `IdentityVerificationManager::resolveForPurpose()` 호출 (purpose 기반 fallback 체인 — 환경설정 `purpose_providers.{purpose}` → `default_provider` → 등록된 첫 provider)
3. Manager 예외 시 정책의 원본 provider_id 그대로 반환 (정책 정보 보존)
`resolveRenderHint()` 와 동일한 우선순위 체인을 적용하여 정책에 provider 가 지정되지 않아도 환경설정 default 가 모달 launcher payload 의 `provider_id` 로 정확히 전달됩니다.
## 5.2 Service 라이프사이클 훅 (cancel / consume_token)
`IdentityVerificationService` 는 challenge 라이프사이클 각 단계마다 `before_*` / `after_*` 페어로 hook 을 발행합니다. 외부 plugin 이 자기 record 정리·후속 작업을 listener 로 분리할 수 있습니다.
| 단계 | before hook | after hook |
| --- | --- | --- |
| Challenge 발급 | `core.identity.before_request` | `core.identity.after_request` |
| Verify | `core.identity.before_verify` | `core.identity.after_verify` |
| Cancel | `core.identity.before_cancel` | `core.identity.after_cancel` |
| Consume Token | `core.identity.before_consume_token` | `core.identity.after_consume_token` |
`after_cancel` / `after_consume_token` 의 세 번째 인자는 작업 성공 여부 (`bool`). 대상 log 가 없는 경우 두 번째 인자(`$log`) 는 `null` 이고 성공 여부는 `false`. 모든 경우에 before/after 둘 다 발행됩니다.
```php
// 예: 이니시스 challenge cancel 시 자기 mapping row 정리
class CleanInicisMappingOnCancel implements HookListenerInterface
{
public static function getSubscribedHooks(): array
{
return [
'core.identity.after_cancel' => ['method' => 'handle', 'priority' => 20],
];
}
public function handle(string $challengeId, ?IdentityVerificationLog $log, bool $success): void
{
if ($success && $log?->provider_id === 'inicis') {
$this->mappingRepository->deleteByChallengeId($challengeId);
}
}
}
```
## 6. 시드 정책 (코어 기본 9종, 모두 `core.*` namespace)
`config/core.php` `identity_policies` 블록에 선언. `IdentityPolicySeeder` 가 동기화하며 `HasUserOverrides` 트레이트가 운영자 수정값을 보존합니다.
+42
View File
@@ -92,6 +92,48 @@ final class SmsIdentityProvider implements VerificationProviderInterface
**target 식별자 규약**: SMS 라면 E.164 정규화된 휴대폰번호, 이메일이라면 소문자, 외부 ID 라면 안정 식별자. 핵심은 challenge 시작과 verify 후 listener 가 같은 식별자를 SHA256 한다는 일관성입니다.
## 3.1 VerificationChallenge DTO 필드 규약
`requestChallenge()` 가 반환하는 `VerificationChallenge` DTO 는 프론트 launcher 가 모달 상태 초기화에 그대로 사용합니다. 모든 필드는 named arguments 로 호출하며, 향후 코어가 신규 필드를 추가해도 기본값으로 자동 처리되도록 named args 패턴을 유지합니다.
| 필드 | 타입 | 의미 |
| --- | --- | --- |
| `id` | string | challenge UUID |
| `providerId` | string | provider 식별자 |
| `purpose` | string | signup / password_reset / self_update / sensitive_action / 확장 정의 |
| `channel` | string | email / sms / ipin / 확장 채널 |
| `targetHash` | string | SHA256(식별자) |
| `expiresAt` | CarbonInterface | 만료 시각 |
| `renderHint` | string | text_code / link / external_redirect |
| `redirectUrl` | ?string | external_redirect 분기 시 외부 URL |
| `publicPayload` | array | 프론트 노출용 공개 페이로드 (민감정보 제외) |
| `metadata` | array | 서버 내부 참조용 |
| `maxAttempts` | int (기본 0) | 허용 최대 시도 횟수. 0 은 무제한(popup/SDK 형 provider 의 기본) |
`maxAttempts` 는 `toArray()` 출력의 `max_attempts` 키로 노출되어 `ChallengeResource` 응답에 그대로 전달됩니다. 프론트 launcher 는 이 값으로 모달의 "남은 시도 횟수" UI 를 초기화합니다.
**코어 mail provider 패턴**:
```php
return new VerificationChallenge(
id: $log->id,
providerId: self::ID,
// ... 기존 필드
maxAttempts: $maxAttempts, // config('settings.identity.max_attempts', 5)
);
```
**popup/SDK 형 provider 패턴** (KG이니시스 등):
```php
return new VerificationChallenge(
id: $challengeId,
providerId: self::PROVIDER_ID,
// ... 기존 필드
// maxAttempts 미전달 시 DTO 기본값 0 (무제한)
);
```
## 4. verification_token 생성 방법
외부 SDK 가 자체 토큰(거래번호 등)을 주더라도 **절대 그대로 client 에 전달하지 마세요**. 우리 인프라용 토큰을 별도로 생성합니다:
+82 -3
View File
@@ -170,11 +170,18 @@ notification_definitions 레코드:
알림 발송 리스너는 기본적으로 큐로 디스패치되며, 큐 워커는 별도 프로세스라 `Auth::user()`/`App::getLocale()`이 모두 리셋됩니다. 그러나 G7은 디스패치 시점의 컨텍스트를 자동 복원하므로 다음이 보장됩니다:
- 발송 시점의 사용자 로케일이 자동 복원되어 다국어 메시지(메일 본문, 푸시 텍스트 등)가 원래 요청 언어로 정확히 발송
- 알림 발송 로그(`NotificationLogListener`)의 행위자가 실제 트리거한 사용자로 정상 기록
리스너 코드는 변경 불필요 — 평소처럼 `Auth::user()`, `__('...')` 호출하면 됩니다.
#### 알림 언어는 수신자 기준
알림 본문/제목의 렌더 언어는 요청자(트리거한 관리자/사용자)의 app locale 이 아니라 **수신자 본인 언어(`users.language`)** 로 결정됩니다. 관리자가 한국어 UI 에서 영어 사용자에게 주문 알림을 보내도, 그 알림은 수신자 언어로 렌더됩니다.
- `User` 는 Laravel `HasLocalePreference` contract 를 구현하며, `preferredLocale()` 이 `users.language`(SSoT)를 반환합니다. 빈값/미지원 로케일이면 `config('app.locale')` 으로 폴백합니다 (요청자 locale 폴백 없음).
- 비회원(`GuestNotifiable`)도 동일 contract 를 구현하며, 발송 트리거 시점에 저장된 로케일(예: 주문 시 `orderer_locale`)을 `guest_recipient.locale` 로 받아 `preferredLocale()` 이 반환합니다. 미저장 시 `app locale` 폴백.
- 렌더 3지점(`GenericNotification::toMail`/`toArray`, `NotificationDispatcher::resolveRenderedContent`)은 `BaseNotification::resolveNotifiableLocale($notifiable)` 헬퍼로 수신자 선호 로케일을 우선 해석합니다. 알림 렌더에서 `$notifiable->locale` 을 직접 참조하지 않습니다 (해당 속성은 존재하지 않아 항상 폴백됨).
> 자세한 동작은 [extension/hooks.md "사용자 컨텍스트 자동 복원"](../extension/hooks.md) 참조
---
@@ -190,11 +197,13 @@ notification_definitions 레코드:
| type | 설명 | value | 예시 |
|------|------|-------|------|
| `trigger_user` | 이벤트 유발자 | - | 주문자, 가입자 |
| `trigger_user` | 이벤트 유발자 (회원 User 또는 비회원 게스트) | - | 주문자, 가입자 |
| `related_user` | 관련 사용자 | relation 키 | 문의 작성자 |
| `role` | 역할 기반 | role identifier | admin, manager |
| `specific_users` | 특정 사용자 | user UUID 배열 | ["uuid1", "uuid2"] |
> `trigger_user` 는 회원/비회원을 동일 규칙으로 처리합니다. context 에 `trigger_user_id` 가 있으면 회원(User), 없고 표준 키 `guest_recipient` 가 있으면 비회원([비회원 발송](#비회원게스트-알림-발송) 참조)으로 해석됩니다.
### JSON 구조
```json
@@ -285,10 +294,13 @@ return [
| order_shipped | sirsoft-ecommerce.order.after_ship | mail, database |
| order_completed | sirsoft-ecommerce.order.after_complete | mail, database |
| order_cancelled | sirsoft-ecommerce.order.after_cancel | mail, database |
| new_order_admin | sirsoft-ecommerce.order.after_create | mail, database |
| order_pending_deposit | sirsoft-ecommerce.order.after_create | mail, database |
| new_order_admin | sirsoft-ecommerce.order.after_admin_notify | mail, database |
| inquiry_received | sirsoft-ecommerce.product_inquiry.after_create | mail, database |
| inquiry_replied | sirsoft-ecommerce.product_inquiry.after_reply | mail, database |
> `new_order_admin` 의 `order.after_admin_notify` 훅은 결제수단별로 발화 시점이 다르다. `OrderProcessingService` 가 무통장/비-PG/0원 주문은 주문 생성 시점에, 카드(PG) 주문은 결제완료(`completePayment`) 시점에 1회 발화한다. 카드 주문은 생성 시점이 `pending_order`(결제 전)라 그 시점 발송 시 결제 미완료/이탈 주문에 오발송된다. `order_pending_deposit` 는 무통장 한정으로 `EcommerceNotificationDataListener` 가 dbank 외 결제수단을 빈 결과로 게이팅한다.
**발송 리스너**: `EcommerceNotificationListener` (방식 A — 직접 호출)
게시판과 동일하게 각 훅 메서드에서 수신자를 결정하고 `$user->notify(new GenericNotification(...))` 직접 호출합니다.
@@ -565,6 +577,73 @@ HookManager::addFilter(
GenericNotification의 `__call()`이 `toFcm()` 호출을 `{hookPrefix}.notification.to_fcm` Filter 훅으로 위임합니다.
---
## 비회원(게스트) 알림 발송
user_id 없는 비회원(주문자 이메일/이름만 보유)도 회원과 동일한 발송 경로로 알림(이메일)을 받습니다. 비회원을 위한 별도 발송 흐름을 만들지 않고, **1급 수신자 값 객체**로 승격하여 기존 파이프라인을 그대로 탑니다.
### 핵심 구성
| 구성 | 위치 | 역할 |
|------|------|------|
| `GuestNotifiable` | `app/Notifications/GuestNotifiable.php` | 비회원 1급 수신자. Laravel `Notifiable` 트레잇 + `HasLocalePreference` 구현 (User 와 동일 계약). email/name/locale 보유 |
| `GuestRecipientInterface` | `app/Contracts/Notifications/GuestRecipientInterface.php` | 게스트 판별 코어 계약 (`isGuest()`). 게이트가 구체 타입(User) 검사 대신 이 계약 사용 |
| 표준 context 키 `guest_recipient` | `{email, name, locale}` | resolver 의 `trigger_user` 규칙이 user_id 없을 때 이 키로 GuestNotifiable 생성 |
### 수신자 해석 (NotificationRecipientResolver)
`trigger_user` 규칙은 회원/비회원 분기 없이 동작합니다.
```php
// extract_data 필터에서 비회원 컨텍스트 제공
'context' => [
'trigger_user_id' => null, // 비회원이므로 null
'guest_recipient' => [ // 코어 표준 키
'email' => $ordererEmail,
'name' => $ordererName,
'locale' => $ordererLocale, // 없으면 null → app locale 폴백
],
]
```
- `trigger_user_id` 가 있으면 User, 없고 `guest_recipient` 가 있으면 GuestNotifiable 을 수신자로 반환합니다.
- 중복 제거 키는 네임스페이스 분리: 회원 `user:{id}` / 비회원 `guest:{이메일 해시}` — null-id 게스트가 하나로 뭉개지지 않습니다.
- `exclude_trigger_user` 는 회원(user_id) 기준이라 게스트 수신자를 깨뜨리지 않습니다.
### 채널별 비회원 발송 허용 (allow_guest)
채널이 비회원 발송을 허용하는지는 `config/notification.php` 채널 메타의 `allow_guest` 로 선언합니다.
```php
['id' => 'mail', ..., 'allow_guest' => true ], // 비회원 가능
['id' => 'database', ..., 'allow_guest' => false], // 비회원 불가 (사이트내 알림)
```
- **미선언 채널은 기본 차단(false)** — 비회원 개인정보(이메일 등)가 의도치 않게 새 프로바이더로 노출되는 것을 막는 opt-in 정책입니다. (확장 단위 채널 활성 `isChannelEnabledForExtension` 의 "미선언=활성" 과 반대 방향)
- 모듈/플러그인이 `core.notification.filter_available_channels` 훅으로 추가하는 신규 채널(SMS·알림톡·앱푸시 등)도 동일하게 `allow_guest` 를 명시해야 비회원 발송이 허용됩니다.
- `NotificationChannelService::isChannelGuestAllowed($channelId)` 가 단일 진입점이며, `core.notification.channel_guest_allowed` 필터 훅으로 동적 재정의 가능합니다.
### 게이트 적용 지점
`GenericNotification::via()` 의 게이트 체인에 게스트 게이트가 합류합니다 (회원은 무영향).
```text
via()
├→ [게스트 게이트] notifiable 이 게스트 + 채널 allow_guest=false → 제외(skipped)
├→ isChannelEnabledForExtension (확장 채널 토글)
└→ ChannelReadinessChecker (채널 설정 완료)
```
게스트 + database → 게이트 제외 → 발송 안 됨. database 가 차단되므로 `notifications` morph 테이블에 null-id 행이 생기지 않습니다.
### 발송 로깅
비회원 발송도 기존 `notification_logs` 에 정상 기록됩니다 (`NotificationDispatcher::buildContext`).
- 게스트는 `recipient_user_id = null` + `recipient_identifier = 이메일` 로 기록됩니다. 게스트의 합성 키(`guest:...`)는 정수 FK 컬럼에 넣지 않습니다.
- 관리자 발송 이력 조회(`GET /api/admin/notification-logs?search={이메일}`)에서 `recipient_identifier` LIKE 검색으로 비회원 발송을 찾을 수 있습니다 (전체 접근 권한 기준).
### 채널 메타데이터 다국어 규칙
채널의 이름(`name`), 설명(`description`), 출처 라벨(`source_label`)은 **`{field}_key` 패턴으로 lang key 만 선언**하고, `NotificationChannelService::getAvailableChannels()` 가 활성 locale 기준으로 string 으로 해석해 반환합니다 (registry payload `name_key` 계약, 7.0.0-beta.4+).
+95
View File
@@ -162,6 +162,23 @@ SEO 렌더링 시 `_global` 컨텍스트에 프론트엔드 설정 데이터를
| `_global.settings` | `SettingsService` | 코어 프론트엔드 설정 (사이트명, 로고 등) |
| `_global.modules` | `SettingsService` | 활성 모듈 목록 |
| `_global.pluginSettings` | `PluginSettingsService` | 플러그인 설정 데이터 |
| `_global.site_name` | `general.site_name` | 사이트 이름. `resolveLocalizedValue` 통과 (다국어 array 안전) |
| `_global.site_url` | `general.site_url` | 사이트 URL |
### site_name SSoT 체인 (다국어 일관성)
`general.site_name` 은 사이트 식별 기준값(SSoT)이며, 다음 경로에서 사용된다. 운영자가 다국어 JSON array 로 저장할 수 있으므로 **모든 경로가 현재 로케일 string 으로 정규화**해야 한다 (array 를 그대로 `(string)`/Blade `e()` 캐스팅하면 "Array to string conversion" TypeError 발생).
| 경로 | 출처 | 정규화 |
|------|------|--------|
| OG `og:site_name` | `seo.og_default_site_name ?? general.site_name` (`SeoMetaResolver`) | `resolveLocalizedValue` ✅ |
| JSON-LD `WebSite.name` / `{site_name}` 치환 | `_global.site_name` ← `general.site_name` (`SeoRenderer::buildGlobalContext`) | `resolveLocalizedValue` ✅ |
| SPA `<title>` | `config('app.name')` ← `general.site_name` (`SettingsServiceProvider::applyAppConfig`) | `localizeSettingValue` ✅ |
| canonical | URL 기반, site_name 미사용 (`seo.blade.php`) | N/A (무관) |
> **OG 직접입력은 의도된 override**: `seo.og_default_site_name` 에 값을 입력하면 그 값이 우선하고, 비우면 `general.site_name` 을 따른다. admin SEO 탭의 OG 입력칸 라벨/안내가 이 "선택 재정의" 위상을 명시한다. 자동 동기화/칸 제거는 하지 않는다 (drift 는 명시적 override 로 허용).
>
> `resolveLocalizedValue` 의 SSoT 는 `app/Seo/Concerns/LocalizesSeoValues` 트레이트. `SettingsServiceProvider` 는 `register()` 단계(DI 전)라 트레이트 대신 동일 의미의 `localizeSettingValue` 를 인라인한다.
### initGlobal 매핑
@@ -1477,6 +1494,36 @@ public function seoVariables(): array
- `setting`, `core_setting`, `query`, `route` 소스는 SeoRenderer가 **자동으로 해석**합니다.
- `data` 소스는 레이아웃 JSON의 `meta.seo.vars`에서 표현식으로 매핑해야 합니다.
#### source 타입과 값 공급 주체
변수의 `source` 타입이 "값을 누가 채우는지"를 결정합니다. 같은 변수명을 모듈과 레이아웃이 동시에 선언해도, 값의 주인은 `source`가 정합니다.
| source | 값의 주인 | 레이아웃 `vars`로 덮어쓰기 |
|--------|----------|---------------------------|
| `setting` | 모듈/플러그인 설정 | 불가 (출처가 강제) |
| `core_setting` | 코어 설정 | 불가 |
| `query` | URL 쿼리 | 불가 |
| `route` | 라우트 파라미터 | 불가 |
| `data` | 레이아웃 `vars` | 유일하게 레이아웃이 값 공급 |
`source: data` 변수만 레이아웃 `vars`가 값을 공급하고, 나머지 타입은 각 출처(모듈 설정/코어 설정/URL/라우트)가 값을 강제하므로 레이아웃 `vars`로 덮을 수 없습니다.
> 주의: `source: core_setting` 변수도 **정의 주체는 모듈/플러그인**입니다 (코어는 `seoVariables()` 같은 정의 인프라를 갖지 않음). 코어 설정은 그 변수의 "값이 저장된 창고"일 뿐, 변수를 정의하지 않습니다.
#### required 플래그
변수 정의에 `required: true`를 지정하면, 해석 결과가 빈 문자열일 때 경고 로그를 남깁니다.
```php
'product_name' => ['source' => 'data', 'required' => true],
```
- 값이 비면 `Log::warning('[SEO] Required variable not resolved', ...)` 기록 (SeoRenderer)
- 렌더링을 **중단하지 않음** — 빈 값으로 계속 진행 (부분 누락 허용)
- 기본값 주입/예외 발생 없음 — 누락을 감지하는 진단용 표시
SEO 렌더링은 변수 하나가 비어도 나머지 메타태그를 정상 출력해야 하므로, `required`는 강제력 없이 경고만 수행합니다.
### meta.seo.extensions — 확장 변수 로드 선언
레이아웃 JSON에서 SEO 변수를 제공하는 확장을 선언합니다.
@@ -1539,6 +1586,54 @@ _seo.{page_type}.description — 해석된 SEO 설명
- `_common` 변수와 page_type별 변수 간 중복도 검증 대상
- 서로 다른 확장 간 동일 page_type의 변수명 충돌 시 경고 발생
### vars의 두 출처와 소비처
vars는 "정의 주체"에 따라 두 갈래로 나뉘며, 소비처도 분리됩니다. 두 소비처는 **서로 다른 변수 풀**을 봅니다.
| 정의 주체 | 처리 경로 | 소비처 |
|-----------|----------|--------|
| 모듈/플러그인 `seoVariables()` | `resolveSeoContext` | 확장 SEO 설정 탭의 제목/설명 템플릿 `{key}` 치환 |
| 레이아웃 `meta.seo.vars` | `resolveSeoVars` → `htmlMapper->setSeoVars` | seo-config.json의 `format`/`fields` 렌더 모드 컴포넌트 |
- **확장 SEO 설정 탭** ← 모듈 `seoVariables()` 기준. 운영자가 입력한 `meta_{page_type}_title` 등의 `{key}` 빈칸을 채움 (`data` 소스 변수가 여기로)
- **seo-config.json** ← 레이아웃 `meta.seo.vars` 기준. `format` 모드 `{key}` 치환(ComponentHtmlMapper)과 `fields` 모드 link `base_url`(`$var:xxx`)에 사용
겹치는 경우는 같은 변수를 **양쪽에 모두 선언**했을 때뿐입니다. 모듈이 정의한 변수는 레이아웃 `vars`에도 적지 않는 한 seo-config.json에서 쓸 수 없고, 레이아웃 임의 변수는 확장 SEO 탭에서 쓸 수 없습니다.
> 죽은 변수 주의: 레이아웃 `meta.seo.vars`에 선언만 하고 어느 소비처(확장 제목 템플릿 / seo-config.json 컴포넌트)에서도 참조하지 않으면, 해석은 되지만 출력 어디에도 반영되지 않습니다. 헤더/푸터 등 공통 컴포넌트 변수(`siteName`, `shopBase` 등)는 보통 베이스 레이아웃(`_user_base`)에서 소비되므로, 개별 페이지 레이아웃에 중복 선언된 동일 변수는 해당 페이지에서 미사용 상태로 남을 수 있습니다.
### og / twitter / structured_data 캐스케이드 경합
세 항목 모두 우선순위 서열은 `코어 < 모듈/플러그인 declaration < 레이아웃 override < 훅`이지만, 합쳐지는 단위가 다릅니다.
| 항목 | 코어 fallback | 모듈+플러그인 동시 제공 | 레이아웃 부분 재정의 | 병합 단위 |
|------|--------------|------------------------|---------------------|----------|
| `og` / `twitter` | 일부 키 제공 (site_name, image_width, type / card, site) | 키 단위 병합 (공존) | 가능 (키 단위) | 키 (`fillEmptyKeys`) |
| `structured_data` | 없음 | 마지막 확장 하나가 통째로 (extensions 배열 순서) | 불가 (통째로 전체 작성) | 문서 전체 (`=== null`일 때만 모듈) |
- **og/twitter**: `resolveOgData`가 (코어 fallback + 레이아웃 og)를 먼저 합치고, 모듈 declaration은 `fillEmptyKeys`로 **비어있는 키만** 채웁니다. 따라서 코어가 이미 채운 키(site_name, image_width, type)는 모듈이 못 덮고, 코어가 비워둔 키(image, image_alt, extra)만 모듈이 채웁니다. 레이아웃에 명시한 키는 항상 우선합니다.
- **structured_data**: 코어 fallback이 없습니다. 모듈/플러그인이 둘 다 제공하면 `meta.seo.extensions` 배열에서 **마지막에 선언된 확장**이 통째로 이깁니다(병합 아님). 레이아웃이 `meta.seo.structured_data`를 선언하면 모듈/플러그인 declaration은 전부 무시되며, 부분 재정의가 불가하므로 완성된 전체 구조를 작성해야 합니다.
- 세 항목 모두 마지막에 `core.seo.filter_og_data` / `filter_twitter_data` / `filter_structured_data` 훅이 제약 없이 통째로 덮을 수 있습니다 (이미 채워진 키도 변경 가능).
`og.type` 함정: 모듈 `seoOgDefaults`가 `type => 'product'`를 반환해도, 레이아웃에 `og.type`이 없으면 `resolveOgData`가 코어 기본값 `'website'`를 먼저 채워 모듈 값이 무시됩니다. 도메인 og:type이 필요한 레이아웃은 `og.type`을 직접 명시해야 합니다.
### meta.seo 표현식에서 참조 가능한 컨텍스트
SeoRenderer가 `$context`에 주입하는 데이터를 `og`/`structured_data`/`vars` 표현식에서 참조할 수 있습니다.
| 참조 경로 | 내용 |
|-----------|------|
| data_source ID (`product`, `reviews` 등) | `meta.seo.data_sources`로 로드한 API 응답 |
| `route` | 라우트 파라미터 + `route.path`(현재 URL 경로) |
| `query` | URL 쿼리스트링 |
| `_global` | 코어 설정(`settings`)·모듈(`modules`)·플러그인 설정 + `initGlobal` 매핑 데이터 |
| `_local` | init_actions의 `setState(target: local)` 평가 결과 |
| `_computed` / `$computed` | `computed` 섹션 평가 결과 |
| `_seo.{page_type}` | 엔진이 해석한 SEO 제목/설명 (`extensions` + vars + 운영자 템플릿 결과물) |
- `_seo`는 직접 작성하지 않고 SeoRenderer가 자동 주입합니다. 런타임에는 레이아웃이 선언한 `page_type` 하나만 채워집니다 (`_seo.product` 등). `og.title`에서 `{{_seo.{page_type}.title ?? <fallback>}}` 패턴으로 참조하는 것이 표준입니다.
- `_seo.{page_type}`의 가능한 page_type 목록은 코어 고정값이 아니라, 각 모듈/플러그인의 `seoVariables()` 키 + 설정의 `meta_{page_type}_title` 키에서 도출됩니다 (확장마다 다름).
## 개발 체크리스트
```
+62
View File
@@ -100,6 +100,7 @@ class WhitelistedEndpoint implements ValidationRule
{
public function validate(string $attribute, mixed $value, Closure $fail): void
{
// 실제 룰은 /api/(modules|plugins)/{vendor-id}/ 확장 프리픽스도 허용 — app/Rules/WhitelistedEndpoint.php 참조
if (!preg_match('/^\/api\/(admin|auth|public)\//', $value)) {
$fail(__('validation.custom.whitelisted_endpoint'));
}
@@ -1021,6 +1022,67 @@ Rule::exists("board_{$slug}_posts", 'id'),
---
## Service-Repository 패턴 {#service-repository-패턴}
FormRequest 의 검증 로직(closure rule, `prepareForValidation`, `withValidator`,
`messages` 등)이 데이터 조회를 필요로 할 때, Service 와 동일하게 Repository
Interface 경유 패턴을 따른다.
### 금지 — Model facade 직접 호출
```php
// ❌ Closure rule 안에서 Model::where 직접 호출
protected function uniqueRule(): Closure
{
return function ($attribute, $value, $fail) {
$exists = User::where('email', $value)->exists(); // ❌
if ($exists) { $fail(__('...')); }
};
}
// ❌ prepareForValidation 안에서 Model facade
protected function prepareForValidation(): void
{
$template = Template::where('identifier', $name)->first(); // ❌
}
```
### 필수 — Repository Interface 경유
FormRequest 는 생성자 주입 대신 `app(Interface::class)` 로 해석한다 (Laravel
의 FormRequest 는 컨테이너 해석 시점이 다르며, 모든 검증 closure 가 인스턴스
스코프 안에서 동작하므로 helper 호출이 가장 단순).
```php
use App\Contracts\Repositories\UserRepositoryInterface;
protected function uniqueRule(): Closure
{
return function ($attribute, $value, $fail) {
$exists = app(UserRepositoryInterface::class)->existsByEmail($value);
if ($exists) { $fail(__('...')); }
};
}
protected function prepareForValidation(): void
{
$template = app(TemplateRepositoryInterface::class)
->findByIdentifier($this->route('templateName'));
}
```
조회에 필요한 메서드가 Repository Interface 에 없으면 **Interface 에 메서드를
추가** 한 뒤 호출한다 (검증 로직 자체를 Service 로 옮기지 않는다 — 검증은
FormRequest 책임).
### 자동 검증
audit 룰 `formrequest-direct-data-access` 가 FormRequest 내 DB facade / Model
정적 호출 / 영속 메서드(`save`/`saveQuietly`/`forceDelete`) 직접 호출을 자동
차단한다. `Rule::exists(Model::class, ...)` 같은 validation rule helper 는 면제.
---
## 관련 문서
- [예외 처리 (exceptions.md)](exceptions.md) - Custom Exception 다국어 처리