feat(tosspayments,ecommerce,core): 토스 주문서형 결제수단·가상계좌·에스크로 + API 문서 web 라우트 확장

토스페이먼츠 플러그인을 프로덕션 수준으로 완성한다 (계획서 S4).

주문서형 결제(9종 동적등록)
- 플러그인이 filter_available_payment_methods 로 결제수단을 주입하면 체크아웃에
 독립 항목으로 노출된다. 서버 전송 시에는 core_payment_method 로 번역해 보낸다 —
 코어 PaymentMethodEnum 은 toss_* 를 거부하므로 번역 없이는 주문 자체가 422 로 실패했다.
 번역 근거인 core_payment_method 가 설정 병합/스냅샷의 화이트리스트에서 탈락하던 것을
 provider-agnostic 하게 보존하도록 고쳤다 (토스 전용 분기 없음).

가상계좌·웹훅·에스크로
- 입금통보/결제상태 웹훅 2종 신설. secret 대조(hash_equals)·리플레이 멱등·CSRF 면제.
- 에스크로 3상태(off/on/buyer_choice). escrowProducts 를 가상계좌·계좌이체 양쪽
 SDK 페이로드에 싣는다 — 서버가 조립해도 SDK 로 전달되지 않으면 토스가 결제를 거부한다.
 E2E 가 SDK 경계를 직접 캡처해 이 계약의 나머지 절반을 잠근다.
- 관리자 설정 저장 시 입금기한·에스크로 값 범위를 서버에서 검증한다 (UI max 는 클라 힌트라
 API 직접 호출을 막지 못한다).

레이아웃 리스너 실행 순서
- KG 는 no-PG 리스트를 통짜 리터럴로 str_replace 하므로 토스가 먼저 append 하면 KG 의
 매치가 깨진다. HookManager 는 ksort 오름차순이므로 토스 priority 를 30 으로 두어
 "KG(20) 먼저" 를 플러그인 로드 순서와 무관한 불변식으로 고정했다.

코어 — API 문서 생성기가 확장 web 라우트도 수집
- PG 콜백·웹훅은 CSRF/세션 특성상 web.php 에 등록되지만 외부 시스템이 호출하는
 machine-facing 엔드포인트라 API 레퍼런스 대상이다. api/ prefix 만 수집하던 탓에
 영구 무문서였다. 확장 소유 web 라우트를 수집하되 관리자 화면(admin 컨텍스트)은 제외한다.
 코어 라우트 수집 결과는 291건으로 불변.

하네스 — 확장 테스트 베이스클래스 룰 신설
- coverage.json 의 test-extension-base-class 가 status:todo(룰 미구현)라 규정이 있어도
 검출되지 않았고, 실제로 이번 신설 테스트가 그 사각에 빠졌다. 룰을 구현해 봉인한다.
This commit is contained in:
HeuJung committed 2026-08-06 12:46:48 +09:00
1 parent 42eb21320b
commit a9f85ff92b
63 files changed
+4951 -117

No files matched your search

+91 -35
View File
@@ -29,13 +29,13 @@ class ApiRouteInventory
/** @var Route $route */
$uri = $route->uri();
if (! Str::startsWith($uri, 'api/')) {
continue;
}
$name = $route->getName() ?? '';
$owner = $this->resolveOwner($name, $uri);
if (! $this->isDocumentable($uri, $name, $owner)) {
continue;
}
if ($scope !== null && ! $this->matchesScope($owner, $scope)) {
continue;
}
@@ -57,6 +57,42 @@ class ApiRouteInventory
return $routes;
}
/**
* 라우트가 API 레퍼런스 문서 대상인지 판별합니다.
*
* 두 부류를 수집한다:
* 1. `api/` prefix 라우트 (코어 + 확장의 src/routes/api.php)
* 2. 확장 소유가 확정된 web 라우트 중 관리자 화면(admin 컨텍스트)이 아닌 것
*
* (2)가 필요한 이유: PG 결제 콜백·웹훅은 외부 시스템(PG사 서버, 브라우저 리다이렉트)이
* 호출하는 machine-facing 엔드포인트라 API 레퍼런스 대상이지만, CSRF 토큰 부재·세션 특성상
* `api.php` 가 아니라 `web.php` 에 등록된다. `api/` 만 수집하면 이들이 영구히 무문서가 된다.
*
* 제외 대상:
* - 코어 web 라우트 (블레이드 화면·SPA 진입점 등) — 소유가 'core'
* - 확장의 관리자 화면 web 라우트 (`web.{dir}.{id}.admin.*`) — 사람이 브라우저로 여는
* 화면이라 API 레퍼런스 대상이 아니다. 코어 admin API 는 `api/` prefix 라 영향 없다.
*
* @param string $uri 라우트 URI
* @param string $name 라우트명
* @param array{type: string, id: string|null, key: string} $owner 소유 주체
* @return bool 문서 대상 여부
*/
private function isDocumentable(string $uri, string $name, array $owner): bool
{
if (Str::startsWith($uri, 'api/')) {
return true;
}
// 코어 web 라우트(화면)는 대상 아님
if ($owner['type'] === 'core') {
return false;
}
// 확장 web 라우트 중 관리자 화면(admin 컨텍스트)은 대상 아님
return ! preg_match('/^web\.(?:modules|plugins)\.[^.]+\.admin\./', $name);
}
/**
* 하나의 라우트를 HTTP 메서드별 정규화 엔트리 배열로 변환합니다.
*
@@ -115,13 +151,18 @@ class ApiRouteInventory
* 비활성/미설치 확장의 번들 라우트 파일을 임시 라우터에 로드해 수집합니다.
*
* 프로바이더(`ModuleRouteServiceProvider`/`PluginRouteServiceProvider`)와 동일한
* prefix(`api/{modules|plugins}/{id}`)·name(`api.{modules|plugins}.{id}.`)·`api`
* 미들웨어 그룹으로 `src/routes/api.php` 를 라우터에 로드한다. `api/` 로 시작하는
* 라우트만 대상이므로 web(admin) 라우트는 자동 제외된다(그 라우트는 API 문서 대상이 아니다).
* prefix·name·미들웨어 규약으로 번들 라우트 파일을 라우터에 로드한다:
* - `src/routes/api.php` → prefix `api/{dir}/{id}`, name `api.{dir}.{id}.`, middleware `api`
* - `src/routes/web.php` → prefix `{dir}/{id}`, name `web.{dir}.{id}.`, middleware `web`
*
* web 라우트를 함께 로드하는 이유: PG 결제 콜백·웹훅은 CSRF/세션 특성상 web.php 에
* 등록되지만 외부 시스템이 호출하는 machine-facing 엔드포인트라 API 문서 대상이다.
* 관리자 화면용 web 라우트는 문서에 섞이지만, 확장 소유 라우트는 모두 문서 대상이라는
* 활성 경로(`isDocumentable`)의 판정과 일관된다.
*
* 라우트 파일은 `use Illuminate\Support\Facades\Route` 로 전역 파사드에 등록하므로,
* 등록 전 라우트 이름 스냅샷을 떠서 이번 로드로 추가된 라우트만 골라낸다. 이 커맨드는
* CLI 단발 프로세스라 전역 라우트 테이블 추가가 웹 요청에 영향을 주지 않는다.
* 등록 후 uri/name prefix 로 이 확장 소유 라우트만 골라낸다. 이 커맨드는 CLI 단발
* 프로세스라 전역 라우트 테이블 추가가 웹 요청에 영향을 주지 않는다.
*
* @param string $scope 범위 필터 (`module:{id}` / `plugin:{id}`)
* @return array<int, array<string, mixed>> 정규화된 라우트 메타데이터 목록
@@ -134,43 +175,55 @@ class ApiRouteInventory
[$type, $id] = [$m[1], $m[2]];
$dir = $type === 'module' ? 'modules' : 'plugins';
$apiRouteFile = base_path("{$dir}/_bundled/{$id}/src/routes/api.php");
if (! is_file($apiRouteFile)) {
$groups = [
['file' => base_path("{$dir}/_bundled/{$id}/src/routes/api.php"), 'prefix' => "api/{$dir}/{$id}", 'name' => "api.{$dir}.{$id}.", 'middleware' => 'api'],
['file' => base_path("{$dir}/_bundled/{$id}/src/routes/web.php"), 'prefix' => "{$dir}/{$id}", 'name' => "web.{$dir}.{$id}.", 'middleware' => 'web'],
];
$loaded = false;
foreach ($groups as $group) {
if (! is_file($group['file'])) {
continue;
}
try {
RouteFacade::prefix($group['prefix'])
->name($group['name'])
->middleware($group['middleware'])
->group($group['file']);
$loaded = true;
} catch (\Throwable) {
// 개별 라우트 파일 로드 실패는 그 파일만 건너뛴다 (나머지는 계속 수집).
continue;
}
}
if (! $loaded) {
return [];
}
$urlPrefix = "api/{$dir}/{$id}";
$namePrefix = "api.{$dir}.{$id}.";
try {
RouteFacade::prefix($urlPrefix)
->name($namePrefix)
->middleware('api')
->group($apiRouteFile);
RouteFacade::getRoutes()->refreshNameLookups();
} catch (\Throwable) {
return [];
}
RouteFacade::getRoutes()->refreshNameLookups();
// 이 확장 소유로 확정된 라우트를 전역 라우트 테이블에서 prefix(uri/name) 로 직접 골라낸다.
// object-id 스냅샷 방식은 refreshNameLookups() 가 RouteCollection 을 재색인하며 객체를
// 다시 만들어 dedup 이 어긋나므로(활성 확장 로드 순서·중복 로드에 취약) 쓰지 않는다.
// 대상 확장은 uri 가 `api/{dir}/{id}/`, name 이 `api.{dir}.{id}.` 로 시작해 결정적으로 식별된다.
// 대상 확장은 uri/name 이 `{api/}{dir}/{id}/` · `{api|web}.{dir}.{id}.` 로 시작해
// 결정적으로 식별된다.
$seen = [];
$routes = [];
foreach (RouteFacade::getRoutes() as $route) {
/** @var Route $route */
$uri = $route->uri();
if (! Str::startsWith($uri, 'api/')) {
continue;
}
$name = $route->getName() ?? '';
$owner = $this->resolveOwner($name, $uri);
if (! $this->isDocumentable($uri, $name, $owner)) {
continue;
}
// 폴백 대상 확장 소유로 확정되지 않으면(코어·타 확장) 제외
if ($owner['key'] !== $scope) {
continue;
@@ -199,20 +252,22 @@ class ApiRouteInventory
*/
private function resolveOwner(string $name, string $uri): array
{
if (preg_match('/^api\.modules\.([^.]+)\./', $name, $m) && $this->isRealExtensionId($m[1])) {
// 라우트명 규약: api 라우트는 `api.{modules|plugins}.{id}.*`,
// web 라우트(PG 콜백/웹훅)는 `web.{modules|plugins}.{id}.*`
if (preg_match('/^(?:api|web)\.modules\.([^.]+)\./', $name, $m) && $this->isRealExtensionId($m[1])) {
return ['type' => 'module', 'id' => $m[1], 'key' => 'module:'.$m[1]];
}
if (preg_match('/^api\.plugins\.([^.]+)\./', $name, $m) && $this->isRealExtensionId($m[1])) {
if (preg_match('/^(?:api|web)\.plugins\.([^.]+)\./', $name, $m) && $this->isRealExtensionId($m[1])) {
return ['type' => 'plugin', 'id' => $m[1], 'key' => 'plugin:'.$m[1]];
}
// 라우트명이 비어도 URI prefix 로 보조 판별
if (preg_match('#^api/modules/([^/{]+)/#', $uri, $m) && $this->isRealExtensionId($m[1])) {
// 라우트명이 비어도 URI prefix 로 보조 판별 (api: `api/{dir}/{id}/`, web: `{dir}/{id}/`)
if (preg_match('#^(?:api/)?modules/([^/{]+)/#', $uri, $m) && $this->isRealExtensionId($m[1])) {
return ['type' => 'module', 'id' => $m[1], 'key' => 'module:'.$m[1]];
}
if (preg_match('#^api/plugins/([^/{]+)/#', $uri, $m) && $this->isRealExtensionId($m[1])) {
if (preg_match('#^(?:api/)?plugins/([^/{]+)/#', $uri, $m) && $this->isRealExtensionId($m[1])) {
return ['type' => 'plugin', 'id' => $m[1], 'key' => 'plugin:'.$m[1]];
}
@@ -391,7 +446,8 @@ class ApiRouteInventory
// 'modules'/'plugins' 는 확장 소유 prefix(api.modules.{id}.*)로도, 코어 확장관리
// 리소스(api.admin.modules.*)로도 쓰인다. 소유 prefix 는 owner['id'] 스킵으로 이미
// 걷히므로, leading 에는 순수 컨텍스트(api/admin/user/me/public)만 둔다.
$leading = ['api', 'admin', 'user', 'me', 'public'];
// 'web' 은 확장 PG 콜백/웹훅 라우트명(web.plugins.{id}.*)의 leading 컨텍스트다.
$leading = ['api', 'web', 'admin', 'user', 'me', 'public'];
$segments = array_values(array_filter(explode('.', $name), fn ($s) => $s !== ''));
$i = 0;