Files
Gnuboard7/modules/_bundled/sirsoft-ecommerce/src/Repositories/OrderCashReceiptRepository.php
T
HeuJung 58560eefb1 feat(ecommerce): 현금영수증 발급 API + 입금완료 자동발급 + 금액변동 연동
무통장입금 주문의 현금영수증 발급을 관리자·회원·비회원 세 경로에서 제공하고,
입금이 확인되면 자동 발급하며, 부분환불로 금액이 바뀌면 전액취소 후 재발급한다.

발급 프로바이더에 종속되지 않도록 발급/취소는 필터 훅으로 위임한다.
자동발급 리스너는 결제완료 전이(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" 로
 설명하던 오염도 정정했다.
2026-08-06 12:17:24 +09:00

90 lines
2.5 KiB
PHP

<?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
{
// DB 에서 후보(발급 완료 건 + 취소 완료 건)만 좁힌 뒤,
// 활성 판정은 OrderCashReceipt::filterActive() SSoT 에 위임한다.
$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();
return $this->model->newCollection(OrderCashReceipt::filterActive($rows));
}
/**
* {@inheritDoc}
*/
public function findByReceiptKey(string $receiptKey): ?OrderCashReceipt
{
return $this->model->newQuery()
->where('receipt_key', $receiptKey)
->orderByDesc('id')
->first();
}
/**
* {@inheritDoc}
*/
public function countIssues(Order $order): int
{
return $this->model->newQuery()
->where('order_id', $order->id)
->where('transaction_type', CashReceiptTransactionType::ISSUE->value)
->count();
}
}