HeuJung
58560eefb1
무통장입금 주문의 현금영수증 발급을 관리자·회원·비회원 세 경로에서 제공하고,
입금이 확인되면 자동 발급하며, 부분환불로 금액이 바뀌면 전액취소 후 재발급한다.
발급 프로바이더에 종속되지 않도록 발급/취소는 필터 훅으로 위임한다.
자동발급 리스너는 결제완료 전이(after_payment_complete)와 입금만 기록
(after_deposit_recorded) 두 경로를 모두 구독한다 — 후자가 없으면 관리자가
"입금만 기록"했을 때 자동발급이 통째로 누락된다.
금액 동기화(syncFromOrder)는 트랜잭션이 닫힌 뒤에 부른다. 재발급 실패 이력은
국세청 신고 누락을 막는 원장이라 롤백에 휩쓸리면 안 되고, 프로바이더 왕복 2회
동안 DB 잠금을 붙들 수 없기 때문이다. 환불은 이미 확정됐으므로 어떤 실패도
호출부로 전파하지 않고 FAILED 이력 + 로그로 남겨 관리자 수동 복구에 맡긴다.
식별번호는 재발급용으로만 암호화 보관하고 구매확정 시점에 폐기한다.
그 시점을 잡기 위해 order.after_purchase_confirmed 훅을 신설했다.
함께 고친 사전 결함:
- 취소 시 total_cash_equivalent_amount 가 재계산되지 않아 syncFromOrder 가
"금액 변동 없음"으로 판정, 부분환불 후 재발급이 아예 동작하지 않았다.
산정 규칙을 PaymentMethodEnum::resolveCashEquivalentAmount 로 SSoT 화해
주문 생성 시점과 취소 재계산 시점이 같은 규칙을 쓰게 했다.
- 현금영수증 발급이 payment.receipt_url 을 덮어써 카드 매출전표 URL 이
유실됐다. 한 컬럼이 두 의미를 갖던 문제로, 현금영수증 URL 은 이력 테이블이
보관하도록 분리했다.
- OrderService::confirmOption 이 confirmed_at 을 무조건 now 로 덮어썼다
(v0.16.1 부터 존재). 재확정 시 최초 확정 시점이 소실되고 구매확정 훅이
중복 발화한다. OrderOptionService 와 대칭으로 멱등 가드를 넣었다.
- 코어 api:docgen 이 사람이 작성한 API 문서를 재생성 때마다 지웠다.
@generated 블록 안의 표 셀·응답 본문이 대상이었고, extractGeneratedBlock
이 앞의 `## ` 헤딩까지 거슬러 올라가 여러 엔드포인트를 한 덩어리로 반환하던
문제도 함께 고쳤다. 실측 산출 응답 예시에 @probed 출처 마커를 붙여, 마커가
없는 본문은 사람 작성분으로 보고 보존한다 — 실측 1회의 표본은 사람이 코드에서
읽어낸 사실보다 좁으므로 실측은 기본값이지 덮어쓰기 권한이 아니다.
ParameterDescriber 가 {order} 같은 path 파라미터를 "정렬 방향 asc/desc" 로
설명하던 오염도 정정했다.
431 lines
17 KiB
PHP
431 lines
17 KiB
PHP
<?php
|
|
|
|
namespace Modules\Sirsoft\Ecommerce\Tests\Unit\Services;
|
|
|
|
use App\Extension\HookManager;
|
|
use App\Models\User;
|
|
use Modules\Sirsoft\Ecommerce\Enums\CashReceiptIdentifierType;
|
|
use Modules\Sirsoft\Ecommerce\Enums\CashReceiptIssueStatus;
|
|
use Modules\Sirsoft\Ecommerce\Enums\CashReceiptTransactionType;
|
|
use Modules\Sirsoft\Ecommerce\Enums\CashReceiptType;
|
|
use Modules\Sirsoft\Ecommerce\Enums\OrderStatusEnum;
|
|
use Modules\Sirsoft\Ecommerce\Enums\PaymentMethodEnum;
|
|
use Modules\Sirsoft\Ecommerce\Enums\PaymentStatusEnum;
|
|
use Modules\Sirsoft\Ecommerce\Models\Order;
|
|
use Modules\Sirsoft\Ecommerce\Models\OrderCancel;
|
|
use Modules\Sirsoft\Ecommerce\Models\OrderCashReceipt;
|
|
use Modules\Sirsoft\Ecommerce\Models\OrderOption;
|
|
use Modules\Sirsoft\Ecommerce\Models\OrderPayment;
|
|
use Modules\Sirsoft\Ecommerce\Services\CashReceiptService;
|
|
use Modules\Sirsoft\Ecommerce\Services\EcommerceSettingsService;
|
|
use Modules\Sirsoft\Ecommerce\Services\OrderCancellationService;
|
|
use Modules\Sirsoft\Ecommerce\Tests\ModuleTestCase;
|
|
use PHPUnit\Framework\Attributes\Test;
|
|
|
|
/**
|
|
* 주문 취소 → 현금영수증 동기화 연동 테스트 (A-7)
|
|
*
|
|
* syncFromOrder() 는 취소 트랜잭션이 커밋된 뒤에 호출된다. 따라서:
|
|
* - 재발급이 실패해도 주문 취소는 롤백되지 않는다
|
|
* - 실패 이력(FAILED)이 원장에 남아 관리자 수동 재발급의 근거가 된다
|
|
*/
|
|
class CashReceiptCancellationSyncTest extends ModuleTestCase
|
|
{
|
|
private const PROVIDER = 'tosspayments';
|
|
|
|
private const IDENTIFIER = '01012345678';
|
|
|
|
private bool $issueShouldFail = false;
|
|
|
|
private int $receiptSequence = 0;
|
|
|
|
protected function setUp(): void
|
|
{
|
|
parent::setUp();
|
|
|
|
$this->issueShouldFail = false;
|
|
$this->receiptSequence = 0;
|
|
|
|
app(EcommerceSettingsService::class)->setSetting('order_settings.cash_receipt_provider', self::PROVIDER);
|
|
}
|
|
|
|
/**
|
|
* 발급/취소 프로바이더 리스너를 등록합니다.
|
|
*/
|
|
private function registerProvider(): void
|
|
{
|
|
HookManager::addFilter(
|
|
'sirsoft-ecommerce.cash_receipt.issue',
|
|
function (array $result, Order $order, string $provider, array $payload) {
|
|
if ($provider !== self::PROVIDER) {
|
|
return $result;
|
|
}
|
|
|
|
if ($this->issueShouldFail) {
|
|
return [
|
|
'success' => false,
|
|
'error_code' => 'PROVIDER_ERROR',
|
|
'error_message' => '발급 실패',
|
|
'receipt_key' => null,
|
|
'receipt_url' => null,
|
|
'issue_number' => null,
|
|
'raw_response' => null,
|
|
];
|
|
}
|
|
|
|
$key = 'receipt-'.(++$this->receiptSequence);
|
|
|
|
return [
|
|
'success' => true,
|
|
'error_code' => null,
|
|
'error_message' => null,
|
|
'receipt_key' => $key,
|
|
'receipt_url' => "https://example.test/receipt/{$key}",
|
|
'issue_number' => '12345678',
|
|
'raw_response' => null,
|
|
];
|
|
},
|
|
);
|
|
|
|
HookManager::addFilter(
|
|
'sirsoft-ecommerce.cash_receipt.cancel',
|
|
fn (array $result, Order $order, string $provider, string $receiptKey) => $provider === self::PROVIDER
|
|
? [
|
|
'success' => true,
|
|
'error_code' => null,
|
|
'error_message' => null,
|
|
'receipt_key' => $receiptKey,
|
|
'raw_response' => null,
|
|
]
|
|
: $result,
|
|
);
|
|
}
|
|
|
|
/**
|
|
* 현금영수증이 발급된 무통장 결제완료 주문(옵션 2개)을 생성합니다.
|
|
*
|
|
* @return array{order: Order, options: array<int, OrderOption>}
|
|
*/
|
|
private function makeIssuedOrder(int $unitPrice = 10000, int $optionCount = 2): array
|
|
{
|
|
$total = $unitPrice * $optionCount;
|
|
|
|
$order = Order::factory()->create([
|
|
'user_id' => User::factory()->create()->id,
|
|
'order_status' => OrderStatusEnum::PAYMENT_COMPLETE,
|
|
'subtotal_amount' => $total,
|
|
'total_amount' => $total,
|
|
'total_paid_amount' => $total,
|
|
'total_due_amount' => 0,
|
|
'total_cancelled_amount' => 0,
|
|
'cancellation_count' => 0,
|
|
'paid_at' => now(),
|
|
'promotions_applied_snapshot' => [],
|
|
'shipping_policy_applied_snapshot' => [],
|
|
// 무통장 실입금액 = 전액 현금성. 전액 과세.
|
|
'total_cash_equivalent_amount' => $total,
|
|
'total_tax_amount' => $total,
|
|
'total_tax_free_amount' => 0,
|
|
]);
|
|
|
|
$snapshot = [
|
|
'product_snapshot' => [
|
|
'id' => null, 'name' => ['ko' => 't', 'en' => 't'], 'product_code' => null,
|
|
'sku' => null, 'brand_id' => null, 'list_price' => $unitPrice, 'selling_price' => $unitPrice,
|
|
'currency_code' => 'KRW', 'stock_quantity' => 100, 'tax_status' => 'taxable',
|
|
'tax_rate' => 10, 'has_options' => false, 'option_groups' => null, 'thumbnail_url' => null,
|
|
],
|
|
'option_snapshot' => [
|
|
'id' => null, 'option_code' => null, 'option_values' => null, 'option_name' => 't',
|
|
'price_adjustment' => 0, 'list_price' => $unitPrice, 'selling_price' => $unitPrice,
|
|
'currency_code' => 'KRW', 'stock_quantity' => 100, 'weight' => 0, 'volume' => 0,
|
|
],
|
|
];
|
|
|
|
$options = [];
|
|
for ($i = 0; $i < $optionCount; $i++) {
|
|
$options[] = OrderOption::factory()->forOrder($order)->create(array_merge([
|
|
'quantity' => 1,
|
|
'unit_price' => $unitPrice,
|
|
'subtotal_price' => $unitPrice,
|
|
'subtotal_paid_amount' => $unitPrice,
|
|
'subtotal_discount_amount' => 0,
|
|
'option_status' => OrderStatusEnum::PAYMENT_COMPLETE,
|
|
], $snapshot));
|
|
}
|
|
|
|
OrderPayment::factory()->forOrder($order)->create([
|
|
'payment_method' => PaymentMethodEnum::DBANK,
|
|
'payment_status' => PaymentStatusEnum::PAID,
|
|
'paid_amount_local' => $total,
|
|
'paid_amount_base' => $total,
|
|
'paid_at' => now(),
|
|
]);
|
|
|
|
$order = $order->fresh();
|
|
|
|
app(CashReceiptService::class)->issue(
|
|
$order,
|
|
CashReceiptType::INCOME,
|
|
self::IDENTIFIER,
|
|
CashReceiptIdentifierType::PHONE,
|
|
);
|
|
|
|
return ['order' => $order->fresh(), 'options' => $options];
|
|
}
|
|
|
|
private function activeReceipt(Order $order): ?OrderCashReceipt
|
|
{
|
|
return app(CashReceiptService::class)->findActiveReceipt($order->fresh());
|
|
}
|
|
|
|
#[Test]
|
|
public function 부분취소시_전체취소_후_잔여금액으로_재발급된다(): void
|
|
{
|
|
$this->registerProvider();
|
|
['order' => $order, 'options' => $options] = $this->makeIssuedOrder(10000, 2);
|
|
|
|
$this->assertSame(20000, (int) $this->activeReceipt($order)->amount);
|
|
|
|
app(OrderCancellationService::class)->cancelOrderOptions(
|
|
order: $order,
|
|
cancelItems: [['order_option_id' => $options[0]->id, 'cancel_quantity' => 1]],
|
|
reason: '단순변심',
|
|
reasonDetail: null,
|
|
cancelledBy: null,
|
|
cancelPg: false,
|
|
);
|
|
|
|
$active = $this->activeReceipt($order);
|
|
$this->assertNotNull($active, '잔여 금액에 대한 영수증이 재발급되어야 한다');
|
|
$this->assertSame(10000, (int) $active->amount, '잔여 10000원으로 재발급');
|
|
$this->assertSame(CashReceiptType::INCOME, $active->receipt_type, '발급 용도가 유지된다');
|
|
|
|
// 원장: 최초 발급 + 전체취소 + 재발급 = 3행
|
|
$this->assertSame(3, OrderCashReceipt::where('order_id', $order->id)->count());
|
|
}
|
|
|
|
#[Test]
|
|
public function 전액취소시_영수증은_전체취소만_되고_재발급되지_않는다(): void
|
|
{
|
|
$this->registerProvider();
|
|
['order' => $order] = $this->makeIssuedOrder(10000, 2);
|
|
|
|
app(OrderCancellationService::class)->cancelOrder(
|
|
order: $order,
|
|
reason: '단순변심',
|
|
reasonDetail: null,
|
|
cancelledBy: null,
|
|
cancelPg: false,
|
|
);
|
|
|
|
$this->assertNull($this->activeReceipt($order), '활성 영수증이 없어야 한다');
|
|
|
|
$cancelRow = OrderCashReceipt::where('order_id', $order->id)
|
|
->where('transaction_type', CashReceiptTransactionType::CANCEL)
|
|
->first();
|
|
$this->assertNotNull($cancelRow);
|
|
$this->assertSame(CashReceiptIssueStatus::COMPLETED, $cancelRow->issue_status);
|
|
}
|
|
|
|
#[Test]
|
|
public function 취소는_성공하고_재발급만_실패해도_주문취소_트랜잭션은_롤백되지_않는다(): void
|
|
{
|
|
$this->registerProvider();
|
|
['order' => $order, 'options' => $options] = $this->makeIssuedOrder(10000, 2);
|
|
|
|
// 최초 발급은 성공했고, 재발급 시점부터 프로바이더가 실패한다.
|
|
$this->issueShouldFail = true;
|
|
|
|
app(OrderCancellationService::class)->cancelOrderOptions(
|
|
order: $order,
|
|
cancelItems: [['order_option_id' => $options[0]->id, 'cancel_quantity' => 1]],
|
|
reason: '단순변심',
|
|
reasonDetail: null,
|
|
cancelledBy: null,
|
|
cancelPg: false,
|
|
);
|
|
|
|
// (a) 주문 취소는 확정되어 있어야 한다
|
|
$this->assertSame(1, OrderCancel::where('order_id', $order->id)->count(), '취소 레코드가 남아야 한다');
|
|
$this->assertSame(
|
|
OrderStatusEnum::CANCELLED,
|
|
$options[0]->fresh()->option_status,
|
|
'취소된 옵션 상태가 확정되어야 한다',
|
|
);
|
|
|
|
// (b) 이력 2행: 전체취소 COMPLETED + 재발급 FAILED
|
|
$cancelRow = OrderCashReceipt::where('order_id', $order->id)
|
|
->where('transaction_type', CashReceiptTransactionType::CANCEL)
|
|
->first();
|
|
$this->assertNotNull($cancelRow);
|
|
$this->assertSame(CashReceiptIssueStatus::COMPLETED, $cancelRow->issue_status);
|
|
|
|
$failedIssue = OrderCashReceipt::where('order_id', $order->id)
|
|
->where('transaction_type', CashReceiptTransactionType::ISSUE)
|
|
->where('issue_status', CashReceiptIssueStatus::FAILED)
|
|
->first();
|
|
$this->assertNotNull($failedIssue, '재발급 실패 이력이 원장에 남아야 한다');
|
|
$this->assertSame('PROVIDER_ERROR', $failedIssue->error_code);
|
|
|
|
// (c) 활성 영수증 없음 → 관리자 수동 재발급 경로가 열린다
|
|
$this->assertNull($this->activeReceipt($order));
|
|
}
|
|
|
|
#[Test]
|
|
public function 프로바이더가_예외를_던져도_주문취소는_확정된다(): void
|
|
{
|
|
// syncFromOrder 는 이미 커밋된 취소를 되돌릴 수 없다 — 예외를 삼키고 로그만 남긴다.
|
|
HookManager::addFilter(
|
|
'sirsoft-ecommerce.cash_receipt.issue',
|
|
fn (array $result, Order $order, string $provider, array $payload) => $provider === self::PROVIDER
|
|
? [
|
|
'success' => true, 'error_code' => null, 'error_message' => null,
|
|
'receipt_key' => 'receipt-1', 'receipt_url' => 'https://example.test/r/1',
|
|
'issue_number' => '1', 'raw_response' => null,
|
|
]
|
|
: $result,
|
|
);
|
|
HookManager::addFilter('sirsoft-ecommerce.cash_receipt.cancel', function () {
|
|
throw new \RuntimeException('PG 통신 실패');
|
|
});
|
|
|
|
['order' => $order, 'options' => $options] = $this->makeIssuedOrder(10000, 2);
|
|
|
|
app(OrderCancellationService::class)->cancelOrderOptions(
|
|
order: $order,
|
|
cancelItems: [['order_option_id' => $options[0]->id, 'cancel_quantity' => 1]],
|
|
reason: '단순변심',
|
|
reasonDetail: null,
|
|
cancelledBy: null,
|
|
cancelPg: false,
|
|
);
|
|
|
|
$this->assertSame(1, OrderCancel::where('order_id', $order->id)->count(), '주문 취소는 확정되어야 한다');
|
|
}
|
|
|
|
#[Test]
|
|
public function 발급_이력이_없는_주문의_취소는_영수증을_건드리지_않는다(): void
|
|
{
|
|
$this->registerProvider();
|
|
['order' => $order, 'options' => $options] = $this->makeIssuedOrder(10000, 2);
|
|
|
|
// 발급 이력을 지우고 취소 — syncFromOrder 는 no-op 이어야 한다.
|
|
OrderCashReceipt::where('order_id', $order->id)->delete();
|
|
|
|
app(OrderCancellationService::class)->cancelOrderOptions(
|
|
order: $order,
|
|
cancelItems: [['order_option_id' => $options[0]->id, 'cancel_quantity' => 1]],
|
|
reason: '단순변심',
|
|
reasonDetail: null,
|
|
cancelledBy: null,
|
|
cancelPg: false,
|
|
);
|
|
|
|
$this->assertSame(0, OrderCashReceipt::where('order_id', $order->id)->count());
|
|
}
|
|
|
|
// ─────────────────────────────────────────────
|
|
// recoverFailedIssue() — 관리자 수동 복구
|
|
// ─────────────────────────────────────────────
|
|
|
|
/**
|
|
* "취소 성공 + 재발급 실패" 중간 상태를 만듭니다.
|
|
*
|
|
* @return Order 활성 영수증이 사라진 주문
|
|
*/
|
|
private function makeReissueFailedState(): Order
|
|
{
|
|
['order' => $order, 'options' => $options] = $this->makeIssuedOrder(10000, 2);
|
|
|
|
$this->issueShouldFail = true;
|
|
|
|
app(OrderCancellationService::class)->cancelOrderOptions(
|
|
order: $order,
|
|
cancelItems: [['order_option_id' => $options[0]->id, 'cancel_quantity' => 1]],
|
|
reason: '단순변심',
|
|
reasonDetail: null,
|
|
cancelledBy: null,
|
|
cancelPg: false,
|
|
);
|
|
|
|
$this->assertNull($this->activeReceipt($order), '사전 조건: 활성 영수증이 없어야 한다');
|
|
|
|
return $order->fresh();
|
|
}
|
|
|
|
#[Test]
|
|
public function recover_는_재발급_실패_상태를_잔여금액으로_복구한다(): void
|
|
{
|
|
// syncFromOrder 는 활성 영수증이 없으면 no-op 이므로 이 상태를 복구하지 못한다.
|
|
$this->registerProvider();
|
|
$order = $this->makeReissueFailedState();
|
|
|
|
$this->issueShouldFail = false;
|
|
|
|
$receipt = app(CashReceiptService::class)->recoverFailedIssue($order->fresh());
|
|
|
|
$this->assertNotNull($receipt);
|
|
$this->assertSame(10000, (int) $receipt->amount, '잔여 금액으로 발급되어야 한다');
|
|
$this->assertSame(CashReceiptType::INCOME, $receipt->receipt_type, '최초 발급 용도를 유지한다');
|
|
$this->assertSame(CashReceiptIssueStatus::COMPLETED, $receipt->issue_status);
|
|
}
|
|
|
|
#[Test]
|
|
public function recover_는_활성_영수증이_있으면_금액_동기화로_위임한다(): void
|
|
{
|
|
$this->registerProvider();
|
|
['order' => $order] = $this->makeIssuedOrder(10000, 2);
|
|
|
|
// 금액만 바뀐 상태 (취소 없이 직접 조작)
|
|
$order->fresh()->update(['total_cash_equivalent_amount' => 5000, 'total_tax_amount' => 5000]);
|
|
|
|
$receipt = app(CashReceiptService::class)->recoverFailedIssue($order->fresh());
|
|
|
|
$this->assertNotNull($receipt);
|
|
$this->assertSame(5000, (int) $receipt->amount);
|
|
}
|
|
|
|
#[Test]
|
|
public function recover_는_암호문이_폐기되었으면_실패이력만_남기고_발급하지_않는다(): void
|
|
{
|
|
// 구매확정으로 암호문이 폐기된 경우 — 관리자가 식별번호를 재입력해야 한다.
|
|
$this->registerProvider();
|
|
$order = $this->makeReissueFailedState();
|
|
$this->issueShouldFail = false;
|
|
|
|
app(CashReceiptService::class)->purgeIdentifier($order->fresh());
|
|
|
|
$receipt = app(CashReceiptService::class)->recoverFailedIssue($order->fresh());
|
|
|
|
$this->assertNull($receipt);
|
|
$this->assertNotNull(
|
|
OrderCashReceipt::where('order_id', $order->id)->where('error_code', 'IDENTIFIER_UNAVAILABLE')->first(),
|
|
'식별번호 부재 실패 이력이 남아야 한다',
|
|
);
|
|
}
|
|
|
|
#[Test]
|
|
public function recover_는_발급_시도_이력이_없으면_아무것도_하지_않는다(): void
|
|
{
|
|
// 복구가 아니라 신규 발급이다 — issue() 를 써야 한다.
|
|
$this->registerProvider();
|
|
['order' => $order] = $this->makeIssuedOrder(10000, 2);
|
|
OrderCashReceipt::where('order_id', $order->id)->delete();
|
|
|
|
$this->assertNull(app(CashReceiptService::class)->recoverFailedIssue($order->fresh()));
|
|
$this->assertSame(0, OrderCashReceipt::where('order_id', $order->id)->count());
|
|
}
|
|
|
|
#[Test]
|
|
public function recover_는_발급대상_금액이_0이면_아무것도_하지_않는다(): void
|
|
{
|
|
// 전액 환불된 주문 — 활성 영수증이 없는 것이 정상 결과다.
|
|
$this->registerProvider();
|
|
$order = $this->makeReissueFailedState();
|
|
$order->fresh()->update(['total_cash_equivalent_amount' => 0]);
|
|
|
|
$this->assertNull(app(CashReceiptService::class)->recoverFailedIssue($order->fresh()));
|
|
}
|
|
}
|