feat(seo): 사이트맵 재생성 알림·폴링 폴백 + 코어 7.0.6 확정

이슈 후속(S7) 마감 + 릴리스 버전 확정.

기능(S7):
- 사이트맵 전체 재생성 완료/실패 시 실행 관리자에게 알림(수동 실행 한정).
 스케줄러·증분·봇 재생성은 알림 없음(triggered_by 부재 시 skip).
- 최종 실패 전용 알림 + 재생성 전용 큐 + WS 진행상황 payload 봉투 정정.
- Reverb OFF 폴링 폴백 경로 수정(실브라우저 폴링에서만 드러난 결함).

버전(D28 — 정정, D20 번복):
- 릴리스를 7.0.5→7.0.6(patch)로 확정. 7.1.0(minor)은 다른 브랜치에서 별도 진행.
- config/app.php + .env + README + INSTALL + CHANGELOG + 모듈 3 requires 를 7.0.6 로.
- D19 SEO 캐시 이행 업그레이드 스텝을 Upgrade_7_0_6 로 리네임.
 이유: 스텝 버전 게이팅이 version<=toVersion 이라, 7.1.0 이름이면
 7.0.5→7.0.6 업그레이드에서 이행이 실행되지 않는다.

검증: composer test-smoke OK(2·29) · 재생성 알림/업그레이드 이행/진행상황 테스트 green ·
version-sync/version-bump(new-bump)/extension-require green · audit 0 error.
This commit is contained in:
HeuJung committed 2026-07-19 18:57:51 +09:00
1 parent 3dd34104cc
commit 124433148c
35 files changed
+698 -53

No files matched your search

@@ -12,6 +12,7 @@ use App\Seo\SitemapManager;
use App\Seo\SitemapProgress;
use Carbon\Carbon;
use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\Auth;
/**
* SEO 캐시 관리 컨트롤러
@@ -115,7 +116,8 @@ class SeoCacheController extends AdminBaseController
}
// 관리자 수동 재생성은 항상 전체(Full) — 현 생성 상태와 무관하게 전량 재생성 (D7)
GenerateSitemapJob::dispatch(SitemapGenerationMode::Full);
// 실행한 관리자 ID 를 함께 실어, 완료/실패 시 그 관리자에게만 알림이 발송되게 한다.
GenerateSitemapJob::dispatch(SitemapGenerationMode::Full, Auth::id());
// 큐 대기 중에도 UI 가 'queued' 를 표시하도록 즉시 기록
$this->sitemapProgress->start(SitemapGenerationMode::Full->value);
+28 -2
View File
@@ -3,6 +3,7 @@
namespace App\Jobs;
use App\Enums\SitemapGenerationMode;
use App\Extension\HookManager;
use App\Seo\SitemapManager;
use App\Seo\SitemapProgress;
use Illuminate\Bus\Queueable;
@@ -26,6 +27,15 @@ class GenerateSitemapJob implements ShouldBeUnique, ShouldQueue
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
/**
* @var string 전용 큐 이름 — 대용량·장시간 사이트맵 생성을 default 큐에서 분리한다.
*
* 이 큐에는 반드시 워커를 1개만 배치한다(동시 중복 생성 방지). 그러면
* 긴 생성 작업이 default 큐의 방송/알림을 막지 않아 진행상황이 실시간으로 흐르고,
* 워커가 1개뿐이라 잡이 동시에 두 번 실행되지 않는다.
*/
public const QUEUE = 'sitemap';
/**
* @var int 최대 재시도 횟수
*/
@@ -50,8 +60,15 @@ class GenerateSitemapJob implements ShouldBeUnique, ShouldQueue
* GenerateSitemapJob 생성자
*
* @param SitemapGenerationMode $mode 재생성 모드 — SitemapManager 로 전달
* @param int|null $triggeredBy 관리자 수동 재생성을 실행한 사용자 ID(스케줄러/증분/봇 = null).
* 완료/실패 알림의 수신자(수동 실행자) 판정에 사용됩니다.
*/
public function __construct(public SitemapGenerationMode $mode = SitemapGenerationMode::Auto) {}
public function __construct(
public SitemapGenerationMode $mode = SitemapGenerationMode::Auto,
public ?int $triggeredBy = null,
) {
$this->onQueue(self::QUEUE);
}
/**
* 유니크 락 식별자를 반환합니다.
@@ -84,7 +101,7 @@ class GenerateSitemapJob implements ShouldBeUnique, ShouldQueue
*/
public function handle(SitemapManager $manager): void
{
$result = $manager->regenerate($this->mode);
$result = $manager->regenerate($this->mode, $this->triggeredBy);
if (($result['status'] ?? null) === 'disabled') {
Log::info('[SEO] Sitemap generation skipped (disabled)');
@@ -112,6 +129,15 @@ class GenerateSitemapJob implements ShouldBeUnique, ShouldQueue
// 잡 최종 실패(재시도 소진/타임아웃) 시 진행상황을 'failed' 로 고정 — 무한 running 방지
app(SitemapProgress::class)->fail($exception->getMessage());
// 최종 실패 전용 훅 — 매 시도마다 발화하는 core.seo.sitemap.after_regenerate_failed 와 달리
// 재시도가 모두 소진된 뒤 딱 한 번만 발화한다. 재시도 중 성공하면 발화하지 않으므로
// 실패 알림이 중복되거나(각 시도) 결국 성공했는데도 발송되는 일이 없다.
HookManager::doAction('core.seo.sitemap.regenerate_failed_final', [
'success' => false,
'status' => 'failed',
'message' => $exception->getMessage(),
], $this->triggeredBy);
Log::error('[SEO] Sitemap generation failed', [
'error' => $exception->getMessage(),
]);
@@ -0,0 +1,133 @@
<?php
namespace App\Listeners;
use App\Contracts\Extension\HookListenerInterface;
/**
* SEO 알림 데이터 필터 리스너
*
* notification_definitions 의 `core.seo.notification.extract_data` 필터를 처리하여
* 사이트맵 재생성 완료/실패 알림 발송에 필요한 데이터와 컨텍스트를 제공합니다.
*
* 정책: 사이트맵 재생성은 스케줄러/증분/봇에 의해서도 완료되므로, 관리자가 직접
* 실행(수동 재생성)한 경우에만 알림을 보냅니다. 수동 실행 여부는 훅에 함께 전달된
* 사용자 ID(triggered_by)로 판정하며, 없으면 context.skip 으로 발송을 중단시킵니다.
* 수신자 결정은 notification_definitions.recipients(trigger_user) 설정에 위임합니다.
*/
class SeoNotificationDataListener implements HookListenerInterface
{
/**
* 구독할 훅 목록을 반환합니다.
*
* @return array 훅 이름 → 메서드/우선순위/타입 매핑
*/
public static function getSubscribedHooks(): array
{
return [
'core.seo.notification.extract_data' => [
'method' => 'extractData',
'priority' => 20,
'type' => 'filter',
],
];
}
/**
* 훅 이벤트를 처리합니다(HookListenerInterface 필수 메서드).
*
* @param mixed ...$args 훅에서 전달된 인수들
*/
public function handle(...$args): void {}
/**
* 알림 유형에 따라 데이터와 컨텍스트를 추출합니다.
*
* @param array $default 기본 extract_data 구조
* @param string $type 알림 정의 유형
* @param array $args 훅에서 전달된 원본 인수 [$result, $triggeredBy]
* @return array{notifiable: null, notifiables: null, data: array, context: array}
*/
public function extractData(array $default, string $type, array $args): array
{
return match ($type) {
'sitemap_regenerated' => $this->extractRegenerated($args),
'sitemap_regenerate_failed' => $this->extractRegenerateFailed($args),
default => $default,
};
}
/**
* 사이트맵 재생성 완료 알림 데이터를 추출합니다.
*
* @param array $args 훅 인수 [$result, $triggeredBy]
* @return array
*/
private function extractRegenerated(array $args): array
{
$triggeredBy = $args[1] ?? null;
if (! is_int($triggeredBy)) {
return $this->skip();
}
$result = is_array($args[0] ?? null) ? $args[0] : [];
$data = $result['data'] ?? [];
$baseUrl = config('app.url');
return [
'notifiable' => null,
'notifiables' => null,
'data' => [
'app_name' => config('app.name'),
'url_count' => (string) ($data['url_count'] ?? 0),
'child_count' => (string) ($data['child_count'] ?? 1),
'action_url' => "{$baseUrl}/admin/settings?tab=seo",
'site_url' => $baseUrl,
],
'context' => [
'trigger_user_id' => $triggeredBy,
],
];
}
/**
* 사이트맵 재생성 실패 알림 데이터를 추출합니다.
*
* @param array $args 훅 인수 [$result, $triggeredBy]
* @return array
*/
private function extractRegenerateFailed(array $args): array
{
$triggeredBy = $args[1] ?? null;
if (! is_int($triggeredBy)) {
return $this->skip();
}
$result = is_array($args[0] ?? null) ? $args[0] : [];
$baseUrl = config('app.url');
return [
'notifiable' => null,
'notifiables' => null,
'data' => [
'app_name' => config('app.name'),
'error' => (string) ($result['message'] ?? ''),
'action_url' => "{$baseUrl}/admin/settings?tab=seo",
'site_url' => $baseUrl,
],
'context' => [
'trigger_user_id' => $triggeredBy,
],
];
}
/**
* 발송을 건너뛰도록 지시하는 결과를 반환합니다(비수동 재생성 = 유발 관리자 없음).
*
* @return array
*/
private function skip(): array
{
return ['notifiable' => null, 'notifiables' => null, 'data' => [], 'context' => ['skip' => true]];
}
}
+5 -3
View File
@@ -48,10 +48,12 @@ class SitemapManager
* - auto: 저장소가 비어 있으면 full, 아니면 incremental.
*
* @param SitemapGenerationMode $mode 재생성 모드
* @param int|null $triggeredBy 이 재생성을 유발한 관리자 사용자 ID(관리자 수동 재생성만 지정, 스케줄러/증분/봇 = null).
* 완료/실패 훅에 함께 전달되어 알림 발송 대상(수동 실행자) 판정에 쓰입니다.
* @return array{success: bool, status: string, message?: string, data?: array<string, mixed>}
* status: 'updated' | 'disabled' | 'failed'
*/
public function regenerate(SitemapGenerationMode $mode = SitemapGenerationMode::Auto): array
public function regenerate(SitemapGenerationMode $mode = SitemapGenerationMode::Auto, ?int $triggeredBy = null): array
{
$enabled = (bool) g7_core_settings('seo.sitemap_enabled', true);
if (! $enabled) {
@@ -103,7 +105,7 @@ class SitemapManager
$this->progress->complete($meta);
HookManager::doAction('core.seo.sitemap.after_regenerate', $result);
HookManager::doAction('core.seo.sitemap.after_regenerate', $result, $triggeredBy);
return $result;
} catch (\Throwable $e) {
@@ -119,7 +121,7 @@ class SitemapManager
'message' => __('seo.sitemap_generate_failed', ['error' => $e->getMessage()]),
];
HookManager::doAction('core.seo.sitemap.after_regenerate_failed', $result);
HookManager::doAction('core.seo.sitemap.after_regenerate_failed', $result, $triggeredBy);
return $result;
}
+28 -10
View File
@@ -135,7 +135,8 @@ final class SitemapProgress
$state['urls'] = $meta['url_count'] ?? ($state['urls'] ?? 0);
$state['message'] = null;
$this->persist($state, broadcast: true);
// 완료 시점엔 방금 커밋된 새 생성 시각을 실어 "마지막 생성"이 실시간 갱신되게 한다.
$this->persist($state, broadcast: true, lastUpdatedAt: $meta['generated_at'] ?? null);
}
/**
@@ -189,22 +190,39 @@ final class SitemapProgress
/**
* 진행상황을 캐시에 기록하고, 필요 시 관리자 채널로 방송합니다.
*
* 방송 payload 는 상태 API 응답의 `data` 형태(`progress` + `realtime_enabled`)와 동형입니다.
* websocket 데이터소스가 `target_source` 로 대상 소스를 통째로 교체하므로, 동형이어야
* 형제 필드(realtime_enabled)를 잃지 않고 UI 바인딩이 유지됩니다(D27).
* 방송 payload 는 상태 API 응답 봉투와 동형입니다 — 최상위 `data` 봉투 안에
* `progress`/`last_updated_at`/`realtime_enabled` 를 담습니다(대시보드 방송과 동일 규약).
* websocket 데이터소스가 `target_source` 로 대상 소스의 저장값을 통째 교체하므로, 봉투
* 형태여야 교체 후에도 템플릿의 `sitemap_status.data.*` 바인딩이 유지됩니다(D27).
*
* @param array<string, mixed> $state 진행상황 상태
* @param bool $broadcast 방송 여부(스로틀 판정 결과)
* @param string|null $lastUpdatedAt 이 방송에 실을 마지막 생성 시각(완료 시 새 시각, 그 외 직전 값)
*/
private function persist(array $state, bool $broadcast): void
private function persist(array $state, bool $broadcast, ?string $lastUpdatedAt = null): void
{
$this->cache->put(self::KEY, $state, self::TTL);
if ($broadcast) {
HookManager::broadcast(self::CHANNEL, self::EVENT, [
'realtime_enabled' => true,
'progress' => $state,
]);
if (! $broadcast) {
return;
}
// 미지정(진행 중 단계)이면 직전 완료 시각(settings)을 싣는다. target_source 가 대상 소스
// data 를 통째 교체하므로 매 방송마다 형제 필드를 온전히 실어야 "마지막 생성"이 유지된다.
if ($lastUpdatedAt === null) {
$stored = (string) g7_core_settings('seo.sitemap_last_updated_at', '');
$lastUpdatedAt = $stored !== '' ? $stored : null;
}
// 방송 payload 는 상태 API 응답 봉투와 동형이어야 한다(대시보드 방송과 동일 규약).
// 최상위 data 봉투 안에 progress/last_updated_at/realtime_enabled 를 담아야
// target_source 교체 후에도 템플릿의 `sitemap_status.data.*` 바인딩이 유지된다.
HookManager::broadcast(self::CHANNEL, self::EVENT, [
'data' => [
'last_updated_at' => $lastUpdatedAt,
'progress' => $state,
'realtime_enabled' => true,
],
]);
}
}