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

+226 -102
View File
@@ -9,9 +9,9 @@
```text
1. Laravel Reverb 사용 (WebSocket)
2. 이벤트: ShouldBroadcast 인터페이스 구현
3. 채널: public, private, presence
4. 훅 연동: HookManager에서 broadcast() 호출
2. 브로드캐스트 필수: HookManager::broadcast($channel, $eventName, $payload) 사용
3. 채널: public, private, presence (인증은 routes/channels.php)
4. 개별 Event 클래스 직접 생성 금지 → HookManager::broadcast() 사용
5. 클라이언트: Laravel Echo + Pusher-js
```
@@ -103,64 +103,84 @@ VITE_REVERB_SCHEME="${REVERB_SCHEME}"
> **주의**: 프로덕션 환경에서는 `REVERB_VERIFY_SSL=true`로 설정해야 합니다.
### 클라이언트/서버 endpoint 분리 (리버스 프록시 환경)
WebSocket은 두 가지 endpoint를 가집니다:
| Endpoint | 용도 | 사용 주체 | 예시 |
|----------|------|---------|------|
| 클라이언트 (외부) | 브라우저가 WebSocket 접속 | 브라우저 → Reverb (직접 또는 리버스 프록시 경유) | `g7.dev:443` (https) |
| 서버 (내부) | 백엔드가 broadcast HTTP API 호출 | Pusher SDK → Reverb (Laravel queue worker 내부) | `127.0.0.1:8080` (http) |
**환경설정 → 드라이버 → 웹소켓**에서 두 endpoint를 분리 입력할 수 있습니다:
- 호스트/포트/프로토콜 (클라이언트) — 브라우저용 외부 endpoint
- 서버 호스트/포트/프로토콜 (내부) — 백엔드 broadcast HTTP API용
서버 endpoint가 비어있으면 클라이언트 값으로 fallback (단일 호스트 환경 호환). 리버스 프록시 환경(예: Apache가 `/apps/*`를 Reverb로 프록시하지 못하는 경우)에서는 반드시 server endpoint를 `127.0.0.1:8080` 등 내부 직접 주소로 입력해야 합니다. 그렇지 않으면 Pusher SDK가 외부 host로 POST하여 Apache가 받아 `Method Not Allowed` 발생.
`SettingsServiceProvider::applyWebsocketConfig()`는 클라이언트 endpoint를 `g7.websocket.client.{host,port,scheme}` config 키에, 서버 endpoint를 `broadcasting.connections.reverb.options.*` 및 `reverb.apps.apps.0.options.*`에 분리 적용합니다. Blade(`admin.blade.php`/`app.blade.php`)는 `g7.websocket.client.*`를 우선 읽어 브라우저로 전달합니다.
### Settings 저장 시 큐 워커 재시작 자동화
`SettingsService::saveSettings()`는 drivers 탭 저장 시 자동으로 `Artisan::call('queue:restart')`를 호출합니다. 이는 long-running queue worker가 SettingsServiceProvider boot 시점의 config를 메모리에 캐싱하기 때문입니다. drivers 변경이 워커에 반영되려면 워커가 정상 종료 후 supervisor/스크립트로 재시작되어야 합니다.
---
## 브로드캐스트 이벤트 생성
## HookManager::broadcast() API
### 기본 구조
### 사용법
```php
<?php
use App\Extension\HookManager;
namespace App\Events\Dashboard;
// 기본 사용법 — 채널, 이벤트명, 데이터
HookManager::broadcast('core.admin.dashboard', 'dashboard.stats.updated', [
'type' => 'stats',
'data' => $statsData,
]);
use Illuminate\Broadcasting\Channel;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;
/**
* 대시보드 업데이트 브로드캐스트 이벤트
*/
class DashboardUpdated implements ShouldBroadcast
{
use Dispatchable, InteractsWithSockets, SerializesModels;
/**
* 이벤트 인스턴스를 생성합니다.
*
* @param string $type 업데이트 타입 ('stats', 'resources', 'activities')
* @param array $data 업데이트된 데이터
*/
public function __construct(
public string $type,
public array $data
) {}
/**
* 브로드캐스트할 채널을 반환합니다.
*
* @return array<int, \Illuminate\Broadcasting\Channel>
*/
public function broadcastOn(): array
{
return [new PrivateChannel('admin.dashboard')];
}
/**
* 브로드캐스트 이벤트명을 반환합니다.
*
* @return string
*/
public function broadcastAs(): string
{
return "dashboard.{$this->type}.updated";
}
}
// 사용자별 알림 브로드캐스트 — UUID 사용 (User ID 노출 방지, 보안 강화)
HookManager::broadcast("core.user.notifications.{$user->uuid}", 'notification.received', [
'subject' => '새 주문',
'body' => '주문이 접수되었습니다.',
'type' => 'order_created',
]);
```
### 파라미터
| 파라미터 | 타입 | 설명 | 예시 |
|---------|------|------|------|
| `$channel` | string | Private 채널명 | `'core.admin.dashboard'`, `'core.user.notifications.{uuid}'` |
| `$eventName` | string | 클라이언트 수신 이벤트명 | `'dashboard.stats.updated'` |
| `$payload` | array | 브로드캐스트 데이터 | `['type' => 'stats', 'data' => [...]]` |
### 절대 금지
```
❌ broadcast(new SpecificEvent(...)) — 개별 Event 클래스 직접 생성/사용 금지
❌ event(new SpecificEvent(...)) — event() 헬퍼 직접 사용 금지
✅ HookManager::broadcast(...) — 유일한 브로드캐스트 방법
```
내부적으로 `GenericBroadcastEvent`를 사용하지만, 이는 HookManager의 구현 디테일이므로 외부에서 직접 참조하지 않습니다.
### Graceful Skip (안전한 건너뛰기)
`HookManager::broadcast()`는 아래 조건에서 브로드캐스트를 **시도하지 않고 즉시 반환**합니다:
| 조건 | 동작 |
|------|------|
| 관리자 환경설정 → 드라이버 → 웹소켓 사용 OFF (`websocket_enabled=false`) | `SettingsServiceProvider::applyWebsocketConfig()`가 `broadcasting.default`를 `'null'`로 강제 → 즉시 return |
| `BROADCAST_CONNECTION=null` 또는 `log` | 즉시 return (연결 시도 없음) |
| 드라이버의 `host` 미설정 (예: `REVERB_HOST` 비어있음) | 즉시 return (연결 시도 없음) |
| 설정 정상이나 서버 미실행 (cURL 연결 실패) | `Log::warning` 기록 후 return (예외 미전파) |
브로드캐스팅은 부가 기능이므로 실패해도 메인 작업(사용자 업데이트, 주문 처리, 알림 발송 등)을 중단시키지 않습니다. 개별 리스너에서 try-catch를 추가할 필요가 없습니다.
> **중요**: 웹소켓 OFF 시 `broadcasting.default`가 `'null'`로 강제되는 동작은 `.env`의 `BROADCAST_CONNECTION` 값을 무시하고 적용됩니다. 따라서 PO가 환경설정에서 OFF한 경우, `.env`에 `REVERB_HOST=localhost` 등이 남아 있어도 broadcast 시도가 발생하지 않습니다. 알림 시스템(mail/database 채널)은 이 설정과 독립적으로 정상 동작합니다.
### 채널 타입
| 타입 | 클래스 | 용도 | 인증 필요 |
@@ -169,17 +189,96 @@ class DashboardUpdated implements ShouldBroadcast
| Private | `PrivateChannel` | 인증된 사용자만 접근 | ✅ |
| Presence | `PresenceChannel` | 인증 + 접속자 목록 공유 | ✅ |
### 이벤트 발생
현재 `HookManager::broadcast()`는 Private 채널만 지원합니다. Public/Presence 채널이 필요한 경우 HookManager 확장이 필요합니다.
---
## 채널 네이밍 규칙
코어와 확장(모듈/플러그인) 간 채널명 충돌을 방지하기 위한 필수 컨벤션:
| 소스 | 패턴 | 예시 |
|------|------|------|
| 코어 | `core.*` | `core.admin.dashboard`, `core.user.notifications.{id}` |
| 모듈 | `module.{identifier}.*` | `module.sirsoft-ecommerce.orders.{id}` |
| 플러그인 | `plugin.{identifier}.*` | `plugin.sirsoft-payment.status.{id}` |
---
## 모듈/플러그인 채널 등록
모듈/플러그인에서 WebSocket 채널이 필요한 경우 `getChannels()` 메서드를 오버라이드합니다.
`ModuleManager`/`PluginManager`가 로드 시 자동으로 `Broadcast::channel()`에 등록합니다.
### 모듈 예시
```php
// 방법 1: broadcast() 헬퍼 (권장)
broadcast(new DashboardUpdated('stats', $statsData));
// modules/sirsoft-ecommerce/src/module.php
class EcommerceModule extends AbstractModule
{
public function getChannels(): array
{
return [
'module.sirsoft-ecommerce.orders.{id}' => [
'permission' => 'sirsoft-ecommerce.orders.read',
],
'module.sirsoft-ecommerce.cart.{cartKey}' => [
// permission 없음 → 인증만 필요
],
];
}
}
```
// 방법 2: event() 헬퍼
event(new DashboardUpdated('resources', $resourceData));
### 플러그인 예시
// 방법 3: 즉시 전송 (큐 미사용)
broadcast(new DashboardUpdated('alerts', $alertData))->toOthers();
```php
// plugins/sirsoft-payment/src/plugin.php
class PaymentPlugin extends AbstractPlugin
{
public function getChannels(): array
{
return [
'plugin.sirsoft-payment.status.{id}' => [
'permission' => 'sirsoft-payment.payments.read',
],
];
}
}
```
### 채널 정의 형식
| 키 | 타입 | 설명 | 기본값 |
|-----|------|------|--------|
| `permission` | `string\|null` | 권한 식별자 (`hasPermission()` 체크) | `null` (인증만) |
| `type` | `string` | 채널 타입 (`private`) | `private` |
### 프론트엔드에서 수신
모듈 레이아웃에서 WebSocket 데이터소스를 정의합니다:
```json
{
"id": "order_updates_ws",
"type": "websocket",
"channel": "module.sirsoft-ecommerce.orders.{{_global.currentUser?.id}}",
"event": "order.updated",
"channel_type": "private",
"target_source": "orders"
}
```
### 모듈에서 브로드캐스트 전송
훅 리스너에서 `HookManager::broadcast()`를 호출합니다:
```php
HookManager::broadcast(
"module.sirsoft-ecommerce.orders.{$userId}",
'order.updated',
['order_id' => $order->id, 'status' => $order->status]
);
```
---
@@ -193,19 +292,40 @@ broadcast(new DashboardUpdated('alerts', $alertData))->toOthers();
use Illuminate\Support\Facades\Broadcast;
// 사용자별 Private 채널
Broadcast::channel('App.Models.User.{id}', function ($user, $id) {
return (int) $user->id === (int) $id;
// 사용자별 Private 채널 — UUID 사용 (User ID 노출 방지)
Broadcast::channel('core.user.notifications.{uuid}', function ($user, $uuid) {
return $user->uuid === $uuid && $user->hasPermission('core.user-notifications.read', \App\Enums\PermissionType::User);
});
// 관리자 대시보드 채널 - 권한 체크
Broadcast::channel('admin.dashboard', function ($user) {
Broadcast::channel('core.admin.dashboard', function ($user) {
return $user->hasPermission('core.dashboard.read');
});
// 특정 리소스 채널
Broadcast::channel('orders.{orderId}', function ($user, $orderId) {
return $user->hasPermission('ecommerce.orders.read');
// 모듈 리소스 채널 (모듈의 getChannels()로 자동 등록 — 참고용 예시)
// Broadcast::channel('module.sirsoft-ecommerce.orders.{orderId}', function ($user, $orderId) {
// return $user->hasPermission('sirsoft-ecommerce.orders.read');
// });
```
### 사용자별 채널은 UUID 사용 (보안)
```php
// ✅ DO: UUID 기반 — 다른 사용자 채널 추측 사실상 불가능
Broadcast::channel('core.user.notifications.{uuid}', function ($user, $uuid) {
return $user->uuid === $uuid && $user->hasPermission('core.user-notifications.read', \App\Enums\PermissionType::User);
});
// 백엔드 broadcast 시
HookManager::broadcast(
"core.user.notifications.{$user->uuid}",
'notification.received',
['subject' => '...', 'body' => '...']
);
// ❌ DON'T: 정수 ID — 1, 2, 3... 순차 ID 노출로 채널 추측 가능
Broadcast::channel('core.user.notifications.{id}', function ($user, $id) {
return (int) $user->id === (int) $id;
});
```
@@ -213,7 +333,7 @@ Broadcast::channel('orders.{orderId}', function ($user, $orderId) {
```php
// ✅ DO: boolean 반환 (Private 채널)
Broadcast::channel('admin.dashboard', function ($user) {
Broadcast::channel('core.admin.dashboard', function ($user) {
return $user->hasPermission('core.dashboard.read');
});
@@ -226,7 +346,7 @@ Broadcast::channel('chat.{roomId}', function ($user, $roomId) {
});
// ❌ DON'T: 예외 던지기
Broadcast::channel('admin.dashboard', function ($user) {
Broadcast::channel('core.admin.dashboard', function ($user) {
throw new \Exception('Unauthorized'); // 금지
});
```
@@ -263,58 +383,60 @@ const pusherOptions = {
---
## 훅을 통한 이벤트 발생
## 훅을 통한 브로드캐스트 발생
Service 계층에서 데이터 변경 시 훅 리스너를 통해 브로드캐스트 이벤트를 발생시킵니다.
Service 계층에서 데이터 변경 시 훅 리스너를 통해 `HookManager::broadcast()`를 호출합니다.
### config/hooks.php
```php
return [
'listeners' => [
// 대시보드 통계 업데이트 시 브로드캐스트
'core.dashboard.stats_updated' => [
\App\Listeners\BroadcastDashboardStats::class,
],
// 사용자 생성 시 대시보드 통계 업데이트
'core.user.after_create' => [
\App\Listeners\UpdateDashboardStatsOnUserChange::class,
],
],
];
```
### 리스너 구현
### 리스너 구현 패턴
```php
<?php
namespace App\Listeners;
namespace App\Listeners\Dashboard;
use App\Events\Dashboard\DashboardUpdated;
use App\Contracts\Extension\HookListenerInterface;
use App\Extension\HookManager;
use App\Services\DashboardService;
class BroadcastDashboardStats
class DashboardStatsListener implements HookListenerInterface
{
public static function getSubscribedHooks(): array
{
return [
'core.user.after_create' => ['method' => 'handleStatsUpdate', 'priority' => 10],
'core.user.after_update' => ['method' => 'handleStatsUpdate', 'priority' => 10],
];
}
public function __construct(
private DashboardService $dashboardService
) {}
public function handle(...$args): void {}
/**
* 대시보드 통계 브로드캐스트
*
* @param array $data 훅 데이터
* @return void
* 대시보드 통계 업데이트를 브로드캐스트합니다.
*/
public function handle(array $data): void
public function handleStatsUpdate(...$args): void
{
$stats = $this->dashboardService->getStats();
broadcast(new DashboardUpdated('stats', $stats));
HookManager::broadcast('core.admin.dashboard', 'dashboard.stats.updated', [
'type' => 'stats',
'data' => $this->dashboardService->getStats(),
]);
}
}
```
### 큐 워커에서의 사용자 컨텍스트
훅 리스너는 기본적으로 큐로 디스패치되며, 큐 워커는 별도 프로세스이므로 `Auth::user()`/`request()->ip()`/`App::getLocale()`이 모두 리셋됩니다. 그러나 G7은 디스패치 시점의 컨텍스트를 자동 캡처/복원하므로 워커에서도 평소처럼 사용할 수 있습니다:
- broadcast 페이로드에 `Auth::user()->name` 같은 사용자 정보를 포함시켜도 안전
- 활동로그/알림 발송 시 행위자가 실제 로그인 사용자로 정상 기록
- 다국어 메시지가 원래 요청 로케일로 발송
> 자세한 동작과 플러그인 확장 방법은 [extension/hooks.md "사용자 컨텍스트 자동 복원"](../extension/hooks.md) 참조
---
## 스케줄러를 통한 주기적 브로드캐스트
@@ -328,7 +450,7 @@ class BroadcastDashboardStats
namespace App\Console\Commands;
use App\Events\Dashboard\DashboardUpdated;
use App\Extension\HookManager;
use App\Services\DashboardService;
use Illuminate\Console\Command;
@@ -339,8 +461,10 @@ class BroadcastDashboardResources extends Command
public function handle(DashboardService $dashboardService): int
{
$resources = $dashboardService->getSystemResources();
broadcast(new DashboardUpdated('resources', $resources));
HookManager::broadcast('core.admin.dashboard', 'dashboard.resources.updated', [
'type' => 'resources',
'data' => $dashboardService->getSystemResources(),
]);
$this->info('시스템 리소스 정보가 브로드캐스트되었습니다.');
return Command::SUCCESS;