Files
Gnuboard7/upgrades/data/7.1.0/migrations/01_NullifyUntouchedSeoCacheOverrides.php
T
HeuJung 21f666e4b5 feat(seo): 사이트맵 스트리밍 생성 + SEO 캐시 설정 정합화
대용량 사이트에서 사이트맵 생성이 메모리 부족으로 반복 실패하던 문제(공개 )의
1단계로, 전체 URL을 메모리에 적재하던 구조를 스트리밍 분할 생성으로 교체한다.

사이트맵 스트리밍 코어:
- SitemapWriter — 자식 파일 1개 분량만 버퍼링하고 임계 도달 시 flush.
 StorageInterface가 append를 제공하지 않아(put이 전체 덮어쓰기) 택한 구조이며,
 최대 메모리가 "자식 파일 1개 크기"로 유계가 된다. URL 수(50,000)와
 바이트(45MB) 두 임계로 분할해 sitemaps.org 프로토콜을 지킨다.
- 커밋은 _tmp 전량 기록 → live 재배치 → manifest 마지막 기록 순. manifest 존재가
 커밋 완료 신호다. 기존 manifest를 먼저 지우지 않아 스왑 중 봇에게 503이 나가지 않는다.
- SitemapFileStore — 읽기측 + 파일 경로 SSoT. SitemapXmlRenderer — escape 단일 출처.

데이터 접근 계층 정리:
- contributor 3종이 쿼리를 직접 조립하던 것을 Repository 위임으로 전환.
 MySQL 버퍼드 쿼리에서 cursor는 결과셋 전체를 적재하므로 lazyById를 쓴다.
- SeoCacheStatsService → SeoCacheStatRepository 신설 (집계 4쿼리 → 1쿼리).
- audit 룰 service-direct-data-access의 사각 2건 수정 — 확장 디렉토리 정규식이
 상대경로를 매칭하지 못해 *Contributor처럼 접미사 없는 클래스가 전부 미검출이었다.

SEO 캐시 설정 정합화:
- SEO 설정의 캐시 3키가 cache 카테고리 형제 키에 항상 져서 운영자 입력이 조용히
 무시되고 있었다(설정을 cache 카테고리로 이관하며 SEO 탭 옛 칸을 미제거).
 고급 탭을 기준값으로 두되 SEO 탭에 지정이 있으면 오버라이드하도록 SeoCacheSettings
 단일 출처로 정리. "지정 여부"는 null로 판정하므로 기본값을 비웠다.
- 기존 설치는 Upgrade_7_1_0이 이행 — 옛 기본값과 같으면 미설정으로 비우고, 다르면
 운영자 의도로 보아 보존한다.

코어 버전 bump와 루트 CHANGELOG는 계획서 결정(D20)에 따라 마감 단계에서 일괄 수행한다.
2026-07-17 19:59:40 +09:00

187 lines
7.1 KiB
PHP

<?php
namespace App\Upgrades\Data\V7_1_0\Migrations;
use App\Extension\Upgrade\DataMigration;
use App\Extension\UpgradeContext;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Storage;
/**
* SEO 캐시 설정을 "미설정(null) = 고급 탭 값 사용" 의미로 이행 (결정 D19).
*
* 배경:
* 캐시 설정은 `cache.*`(고급 탭)로 이관되었으나 SEO 탭의 옛 칸(`seo.cache_enabled`,
* `seo.cache_ttl`, `seo.sitemap_cache_ttl`)이 제거되지 않았고, 코드가
* `g7_core_settings('cache.X', g7_core_settings('seo.Y', 기본값))` 형태로 cache 를
* **항상** 우선시켜 SEO 탭 입력이 조용히 무시되었다(운영자가 저장해도 무효).
*
* 7.1.0 의 새 의미:
* 고급 탭 = 메인, SEO 탭에 **별도 지정이 있으면** 그것이 오버라이드.
* "별도 지정" 판정은 null 여부로 하므로 미설정 상태를 표현할 수 있어야 한다.
*
* 본 마이그레이션의 동작 (옛 기본값 기준 추정):
*
* | 저장된 seo.* 값 | 판정 | 동작 |
* |------------------|-----------------------|--------------------------|
* | 키 부재 | 미설정 | no-op |
* | 이미 null | 미설정 | no-op (멱등) |
* | 옛 기본값과 동일 | 안 건드린 것으로 추정 | null 로 비움 |
* | 옛 기본값과 다름 | 의도적으로 바꾼 것 | 보존 → 오버라이드로 발동 |
*
* 즉 값을 실제로 바꿔둔 운영자의 의도만 살아난다. 그 결과 **업그레이드 후 동작이
* 바뀔 수 있다** — 예: `seo.cache_ttl=3600` 을 설정해 둔 사이트는 그동안 무시된 채
* `cache.seo_ttl`(7200)로 돌았으나 이제 3600 이 발동한다. 이것이 원래 의도였으므로
* 의도된 변경이며 CHANGELOG 에 고지한다.
*
* 멱등: 재실행 시 이미 null 인 키는 건드리지 않는다.
*
* 실패 정책: 설정 정리 실패가 업그레이드 전체를 막지 않는다(경고 후 계속). 비우지 못하면
* 해당 키는 옛 기본값을 유지한 채 오버라이드로 동작하는데, 그 값이 곧 고급 탭 기본값과
* 같으므로 관측되는 동작은 변하지 않는다.
*
* 격리 원칙 (docs/extension/upgrade-step-guide.md §13):
* `SeoCacheSettings` 등 신규 코어 클래스를 참조하지 않는다. 옛 기본값 목록과 설정
* 읽기/쓰기를 본 클래스 안에 로컬로 인라인 구현해 V-1 안전을 확보한다.
*/
final class NullifyUntouchedSeoCacheOverrides implements DataMigration
{
/**
* 설정 카테고리 파일 (settings 디스크 기준 상대 경로)
*/
private const SEO_SETTINGS_FILE = 'seo.json';
/**
* 7.0.x 시점의 seo 카테고리 캐시 키 기본값.
*
* 저장된 값이 이 값과 같으면 "운영자가 안 건드린 것" 으로 추정해 null 로 비운다.
* 격리를 위해 defaults.json 을 읽지 않고 로컬 상수로 고정한다 — 미래 버전에서
* defaults.json 이 바뀌어도 본 스텝의 판정 기준은 동결되어야 한다.
*/
private const LEGACY_DEFAULTS = [
'cache_enabled' => true,
'cache_ttl' => 7200,
'sitemap_cache_ttl' => 86400,
];
/**
* 마이그레이션 식별자 (로그용).
*
* @return string 식별자
*/
public function name(): string
{
return 'NullifyUntouchedSeoCacheOverrides';
}
/**
* 옛 기본값 그대로인 SEO 캐시 키를 null(미설정)로 비웁니다.
*
* @param UpgradeContext $context 업그레이드 컨텍스트
*/
public function run(UpgradeContext $context): void
{
try {
$this->runInternal($context);
} catch (\Throwable $e) {
// 업그레이드 중단 금지 — 설정 정리 실패가 업그레이드 전체를 막지 않는다.
$context->logger->warning(sprintf(
'[7.1.0] NullifyUntouchedSeoCacheOverrides 실패 (seo.json 보존, 계속 진행): %s',
$e->getMessage(),
));
Log::warning('7.1.0 NullifyUntouchedSeoCacheOverrides 실패', [
'error' => $e->getMessage(),
'trace' => $e->getTraceAsString(),
]);
}
}
/**
* 실제 이행 로직.
*
* @param UpgradeContext $context 업그레이드 컨텍스트
*/
private function runInternal(UpgradeContext $context): void
{
$settings = $this->readSeoSettings($context);
if ($settings === null) {
return;
}
$cleared = [];
$kept = [];
foreach (self::LEGACY_DEFAULTS as $key => $legacyDefault) {
if (! array_key_exists($key, $settings) || $settings[$key] === null) {
continue;
}
// 옛 기본값과 완전히 같을 때만 "안 건드림" 으로 본다 (타입까지 일치 요구)
if ($settings[$key] === $legacyDefault) {
$settings[$key] = null;
$cleared[] = $key;
continue;
}
$kept[$key] = $settings[$key];
}
foreach ($kept as $key => $value) {
$context->logger->info(sprintf(
'[7.1.0] seo.%s = %s 는 옛 기본값과 달라 오버라이드로 보존 — 이제부터 실제 적용됩니다',
$key,
var_export($value, true),
));
}
if ($cleared === []) {
$context->logger->info('[7.1.0] SEO 캐시 설정 — 비울 대상 없음 (이미 이행 완료이거나 전부 오버라이드)');
return;
}
$this->writeSeoSettings($settings);
$context->logger->info('[7.1.0] SEO 캐시 설정 — 미설정(null)으로 비운 키: '.implode(', ', $cleared));
}
/**
* seo 설정 카테고리를 읽습니다.
*
* @param UpgradeContext $context 업그레이드 컨텍스트
* @return array<string, mixed>|null 설정 배열 (파일 부재/손상 시 null)
*/
private function readSeoSettings(UpgradeContext $context): ?array
{
if (! Storage::disk('settings')->exists(self::SEO_SETTINGS_FILE)) {
$context->logger->info('[7.1.0] seo.json 부재 — 정리 대상 없음, skip');
return null;
}
$decoded = json_decode((string) Storage::disk('settings')->get(self::SEO_SETTINGS_FILE), true);
if (! is_array($decoded)) {
// 손상 파일을 덮어쓰지 않는다 (파괴 금지)
$context->logger->warning('[7.1.0] seo.json 파싱 실패 — 파일 보존하고 skip');
return null;
}
return $decoded;
}
/**
* seo 설정 카테고리를 저장합니다.
*
* @param array<string, mixed> $settings 저장할 설정 배열
*/
private function writeSeoSettings(array $settings): void
{
Storage::disk('settings')->put(
self::SEO_SETTINGS_FILE,
json_encode($settings, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE),
);
}
}