Files
Gnuboard7/modules/_bundled/sirsoft-ecommerce/src/Repositories/OrderPaymentRepository.php
T
HeuJung a9f85ff92b 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(룰 미구현)라 규정이 있어도
 검출되지 않았고, 실제로 이번 신설 테스트가 그 사각에 빠졌다. 룰을 구현해 봉인한다.
2026-08-06 12:46:48 +09:00

129 lines
3.8 KiB
PHP

<?php
namespace Modules\Sirsoft\Ecommerce\Repositories;
use Modules\Sirsoft\Ecommerce\Enums\CashReceiptIdentifierType;
use Modules\Sirsoft\Ecommerce\Enums\CashReceiptType;
use Modules\Sirsoft\Ecommerce\Enums\PaymentStatusEnum;
use Modules\Sirsoft\Ecommerce\Models\OrderCashReceipt;
use Modules\Sirsoft\Ecommerce\Models\OrderPayment;
use Modules\Sirsoft\Ecommerce\Repositories\Contracts\OrderPaymentRepositoryInterface;
/**
* 주문 결제 Repository 구현체
*/
class OrderPaymentRepository implements OrderPaymentRepositoryInterface
{
/**
* {@inheritDoc}
*/
public function markCashReceiptIssued(
OrderPayment $payment,
OrderCashReceipt $receipt,
CashReceiptType $type,
string $identifier,
string $identifierMasked,
?CashReceiptIdentifierType $identifierType,
): OrderPayment {
// receipt_url 은 건드리지 않는다 — 그 컬럼은 PG 영수증(카드 매출전표) URL 전용이고
// PG 플러그인이 결제 승인 시 기록한다. 현금영수증 URL 은 이력 테이블
// (ecommerce_order_cash_receipts.receipt_url) 이 보관하며 OrderResource 가 따로 노출한다.
// 여기서 덮어쓰면 카드 매출전표 URL 이 유실되고 한 컬럼이 두 의미를 갖게 된다.
$payment->update([
'is_cash_receipt_issued' => true,
'cash_receipt_type' => $type->value,
'cash_receipt_identifier' => $identifierMasked,
'cash_receipt_identifier_type' => $identifierType,
'cash_receipt_identifier_encrypted' => $identifier,
'cash_receipt_issued_at' => $receipt->issued_at,
]);
return $payment;
}
/**
* {@inheritDoc}
*/
public function markCashReceiptCancelled(OrderPayment $payment): OrderPayment
{
$payment->update([
'is_cash_receipt_issued' => false,
'cash_receipt_issued_at' => null,
]);
return $payment;
}
/**
* {@inheritDoc}
*/
public function purgeCashReceiptIdentifier(OrderPayment $payment): OrderPayment
{
if (! $this->hasCashReceiptIdentifier($payment)) {
return $payment;
}
$payment->update(['cash_receipt_identifier_encrypted' => null]);
return $payment;
}
/**
* {@inheritDoc}
*/
public function resolveCashReceiptIdentifier(OrderPayment $payment): ?string
{
try {
$identifier = $payment->cash_receipt_identifier_encrypted;
} catch (\Throwable $e) {
// APP_KEY 로테이션 등으로 복호화 실패
return null;
}
return is_string($identifier) && $identifier !== '' ? $identifier : null;
}
/**
* {@inheritDoc}
*/
public function hasCashReceiptIdentifier(OrderPayment $payment): bool
{
return $payment->getRawOriginal('cash_receipt_identifier_encrypted') !== null;
}
/**
* {@inheritDoc}
*/
public function updateRefundBank(
OrderPayment $payment,
string $bankCode,
string $bankName,
string $accountNumber,
string $holder,
): OrderPayment {
$payment->update([
'refund_bank_code' => $bankCode,
'refund_bank_name' => $bankName,
'refund_bank_account' => $accountNumber,
'refund_bank_holder' => $holder,
]);
return $payment;
}
/**
* {@inheritDoc}
*/
public function isTransactionPaid(?string $transactionId): bool
{
if ($transactionId === null || $transactionId === '') {
return false;
}
return OrderPayment::query()
->where('transaction_id', $transactionId)
->where('payment_status', PaymentStatusEnum::PAID->value)
->exists();
}
}