feat(ecommerce): 현금영수증 프로바이더 훅 축 + 이력 테이블 + 현금성 금액 + 배송비 과세 정책

현금영수증 발급 프로바이더를 PG 와 독립적으로 선택할 수 있도록 훅 축을 신설한다.
KG이니시스로 결제받으면서 현금영수증만 토스페이먼츠로 발급하는 구성이 가능하다.

발급/취소 원장(ecommerce_order_cash_receipts)이 국세청 신고 근거를 보관한다.
금액이 바뀌면 syncFromOrder 가 주문의 현재 상태에서 발급액을 재계산해
전체취소 → 전액 재발급한다. 부분취소 API 를 쓰지 않으므로 전액취소만 지원하는
벤더도 동일 인터페이스로 수용되고, 증가/감소 방향을 구분하지 않아 향후 반품·교환
배송비 청구가 도입되어도 수정 없이 동작한다.

배송비는 그동안 과세/면세 분류에서 아예 빠져 있었다. 배송비는 단계 3 에서 계산되고
할인은 단계 4 에서 적용되므로 상품 분류 시점(단계 2-b)에는 존재하지 않는다.
따라서 할인 후 배송비가 확정된 Summary 집계 직전에 3가지 정책 중 하나로 분류해
합산하고, 옵션별 과세액에는 배송비를 섞지 않는다.

재발급용 식별번호는 APP_KEY 기반으로 암호화 보관하고 구매확정 시 폐기한다.
이력에는 마스킹 값만 남기며 프로바이더 원응답의 민감 키도 가린다.
주민등록번호는 수집하지 않는다.

cash_receipt_type 은 Enum 캐스트하지 않는다 — 레거시 값(income_deduction)이 남아
있는 동안 Laravel 의 ::from 이 ValueError 를 던져 정규화해야 할 업그레이드 스텝
자신이 그 행을 읽지 못하게 되기 때문이다.
This commit is contained in:
HeuJung committed 2026-08-06 11:48:12 +09:00
1 parent 5b587d7119
commit af1da5fe0b
46 files changed
+3986 -16

No files matched your search

@@ -0,0 +1,97 @@
<?php
namespace Modules\Sirsoft\Ecommerce\Repositories;
use Illuminate\Database\Eloquent\Collection;
use Modules\Sirsoft\Ecommerce\Enums\CashReceiptIssueStatus;
use Modules\Sirsoft\Ecommerce\Enums\CashReceiptTransactionType;
use Modules\Sirsoft\Ecommerce\Models\Order;
use Modules\Sirsoft\Ecommerce\Models\OrderCashReceipt;
use Modules\Sirsoft\Ecommerce\Repositories\Contracts\OrderCashReceiptRepositoryInterface;
/**
* 주문 현금영수증 이력 Repository 구현체
*/
class OrderCashReceiptRepository implements OrderCashReceiptRepositoryInterface
{
public function __construct(
protected OrderCashReceipt $model
) {}
/**
* {@inheritDoc}
*/
public function create(array $data): OrderCashReceipt
{
return $this->model->newQuery()->create($data);
}
/**
* {@inheritDoc}
*/
public function findByOrder(Order $order): Collection
{
return $this->model->newQuery()
->where('order_id', $order->id)
->orderByDesc('id')
->get();
}
/**
* {@inheritDoc}
*/
public function findActiveReceipt(Order $order): ?OrderCashReceipt
{
return $this->findActiveReceipts($order)->first();
}
/**
* {@inheritDoc}
*/
public function findActiveReceipts(Order $order): Collection
{
$rows = $this->model->newQuery()
->where('order_id', $order->id)
->whereIn('transaction_type', [
CashReceiptTransactionType::ISSUE->value,
CashReceiptTransactionType::CANCEL->value,
])
->where('issue_status', CashReceiptIssueStatus::COMPLETED->value)
->orderByDesc('id')
->get();
// 취소 완료된 receipt_key 집합 — 같은 키의 발급 이력은 더 이상 활성이 아니다.
$cancelledKeys = $rows
->filter(fn (OrderCashReceipt $row) => $row->transaction_type === CashReceiptTransactionType::CANCEL)
->pluck('receipt_key')
->filter()
->unique()
->all();
$active = $rows->filter(function (OrderCashReceipt $row) use ($cancelledKeys) {
if ($row->transaction_type !== CashReceiptTransactionType::ISSUE) {
return false;
}
// receipt_key 가 없는 발급 완료 건은 취소 대상을 특정할 수 없다 — 활성으로 보지 않는다.
if ($row->receipt_key === null || $row->receipt_key === '') {
return false;
}
return ! in_array($row->receipt_key, $cancelledKeys, true);
});
return $this->model->newCollection($active->values()->all());
}
/**
* {@inheritDoc}
*/
public function findByReceiptKey(string $receiptKey): ?OrderCashReceipt
{
return $this->model->newQuery()
->where('receipt_key', $receiptKey)
->orderByDesc('id')
->first();
}
}