Files

T

HeuJung 8328b1db77 docs(core,extensions): 확장 개발자 문서 9세트 집필과 생성기 정합 보강

S1 파일럿 3종(sirsoft-board · sirsoft-gdpr · sirsoft-admin_basic)에 이어
결제·본인인증 동형군 6종의 AGENTS.md · README.md · docs/ 5문서를 집필했다.
확장을 고치려는 쪽이 매번 src/ 를 훑어 구조를 재발견하지 않도록, 설계 의도와
확장점(발행·구독 훅)·수정 시 동반 의무·금지 패턴을 코드 근거로 서술했다.

생성기(ExtensionDocScaffolder)에서 표를 무의미하게 만들던 세 결함을 함께 고쳤다.
getLayoutExtensions 기본 구현이 돌려주는 절대경로가 파일 목록과 중복돼 로컬
머신 경로가 커밋 문서에 실리던 문제, getNotificationDefinitions 를 'key'/'event'
로 읽어 모든 행이 '-' 로 찍히던 문제, getSettingsLayout 절대경로가 정규화 없이
노출되던 문제다. 셋 다 예외를 남기지 않고 표만 조용히 망가뜨리므로
ExtensionDocContractTest 에 각각의 되돌림 red 를 확인한 단언을 두었다.
템플릿의 extensions/{id}/ 는 모듈·플러그인의 발행과 반대 방향(오버라이드)이라
별도 블록(template-overrides)으로 분리했다.

sirsoft-admin_basic 의 컴포넌트·핸들러·레이아웃 문서를 코어 docs/ 에서 그 템플릿
소유로 이관하고, 남은 참조 6축을 재는 가드를 추가했다. 이관 후 남은 옛 경로는
오류가 아니라 헛걸음으로만 나타나 드러나지 않는다. 의 상대 링크가
한 단계 얕아 공유 docs/ 대신 를 가리키던 문제도 함께 고쳤다.

README 상단의 확장명 이미지 배지를 평문 H1 로 바꿨다( 지시 2026-08-31).
루트 README.md · README.ko.md 도 같은 기준을 적용했다. 정보 배지는 유지한다.

sirsoft-gdpr: 회원탈퇴로 자동 철회된 동의가 관리자 동의 이력 화면의 출처 필터로
걸러지지 않던 문제를 고쳤다. Repository 가 'withdraw' 리터럴을 직접 UPDATE 에
싣는데 그 값이 ConsentSource enum 에 없어, 화면 필터 옵션·라벨 어느 쪽에도
도달하지 못했다. 어휘를 enum 단일 출처로 모으고 ko·en·ja 라벨과 필터 옵션을
함께 채웠으며, 어휘 대조 테스트의 모집단에 Repository 를 편입했다.

2026-08-31 15:57:44 +09:00

9.2 KiB

Raw Blame History

나이스페이먼츠 — 확장점

발행/구독 훅·미들웨어·채널·스케줄 · 진입점: AGENTS.md

발행 훅

발행 훅 5종 / 호출 지점 5곳. 이 중 1종은 getHooks() 선언에 없어 소스에서 자동 감지한 것입니다 — 선언에 추가하면 유형과 설명이 함께 실립니다.

훅 이름	유형	설명	발행 위치
`sirsoft-pay_nicepayments.payment.after_authorize`	action	나이스페이먼츠 서버 승인 완료 후	`src/Controllers/PaymentCallbackController.php:257`
`sirsoft-pay_nicepayments.payment.after_cancel`	action	나이스페이먼츠 결제 취소 완료 후	`src/Services/NicePaymentsApiService.php:308`
`sirsoft-pay_nicepayments.payment.before_authorize`	action	나이스페이먼츠 서버 승인 API 호출 전	`src/Controllers/PaymentCallbackController.php:252`
`sirsoft-pay_nicepayments.payment.before_cancel`	action	나이스페이먼츠 결제 취소 API 호출 전 (본인인증 등 확장 지점)	`src/Services/NicePaymentsApiService.php:285`
`sirsoft-pay_nicepayments.payment.refund_failed`	action	—	`src/Listeners/PaymentRefundListener.php:131`

before_authorize/before_cancel은 API 호출 전 개입 지점입니다 — 예외를 던지면 실제 나이스페이먼츠 호출 자체가 일어나지 않습니다. refund_failed는 getHooks() 선언 없이 소스에서 자동 감지된 훅으로, after_cancel(성공 응답)과 달리 취소 API 호출이 실패했을 때만 발화합니다 — 운영 알림을 붙이려는 확장은 이 훅을 구독해야 합니다.

구독 훅

훅 이름	유형	리스너	메서드	우선순위
`core.layout_extension.after_apply`	filter	`AdjustEcommercePaymentMethodsLayoutListener`	`adjustPaymentMethodsLayout`	40
`core.layout_extension.after_apply`	filter	`EnsureAdminOrderDetailPaymentQueryLayoutListener`	`ensurePaymentQueryLayout`	66
`core.layout_extension.after_apply`	filter	`EnsureAdminOrderListTestBadgeLayoutListener`	`ensureTestBadgeLayout`	60
`core.plugins.updated`	action	`RestoreLayoutExtensionsAfterUpdateListener`	`restoreCurrentExtensionsAfterUpdate`	20
`sirsoft-ecommerce.payment.get_client_config`	filter	`RegisterPgProviderListener`	`getClientConfig`	10
`sirsoft-ecommerce.payment.refund`	filter	`CancelActivityLogListener`	`logCancelConfirmed`	20
`sirsoft-ecommerce.payment.refund`	filter	`PaymentRefundListener`	`processRefund`	10
`sirsoft-ecommerce.payment.registered_pg_providers`	filter	`RegisterPgProviderListener`	`registerProvider`	10
`sirsoft-ecommerce.settings.filter_available_payment_methods`	filter	`RegisterEasyPayMethodsListener`	`injectEasyPayMethods`	40

PaymentRefundListener(10)가 CancelActivityLogListener(20)보다 먼저 실행되도록 우선순위를 명시한 것은 실제 취소가 성공한 뒤에야 활동 로그를 남기기 위함입니다 — 순서가 뒤바뀌면 "로그는 있는데 취소는 실패"가 생깁니다. RegisterEasyPayMethodsListener가 8종의 간편결제 방식을 하나의 필터 훅에서 한 번에 주입하는 이유는 §settings.md 의 설정 스키마와 대칭을 맞추기 위함입니다 — 설정 키가 8개인데 훅 등록이 여러 곳으로 흩어지면 한쪽만 갱신되는 사각이 생깁니다.

훅 리스너

리스너	구독 훅	등록 방식	HookListenerInterface	파일
`AdjustEcommercePaymentMethodsLayoutListener`	1개	명시 등록	✅	`src/Listeners/AdjustEcommercePaymentMethodsLayoutListener.php`
`CancelActivityLogListener`	1개	명시 등록	✅	`src/Listeners/CancelActivityLogListener.php`
`EnsureAdminOrderDetailPaymentQueryLayoutListener`	1개	명시 등록	✅	`src/Listeners/EnsureAdminOrderDetailPaymentQueryLayoutListener.php`
`EnsureAdminOrderListTestBadgeLayoutListener`	1개	명시 등록	✅	`src/Listeners/EnsureAdminOrderListTestBadgeLayoutListener.php`
`PaymentRefundListener`	1개	명시 등록	✅	`src/Listeners/PaymentRefundListener.php`
`RegisterEasyPayMethodsListener`	1개	명시 등록	✅	`src/Listeners/RegisterEasyPayMethodsListener.php`
`RegisterPgProviderListener`	2개	명시 등록	✅	`src/Listeners/RegisterPgProviderListener.php`
`RestoreLayoutExtensionsAfterUpdateListener`	1개	명시 등록	✅	`src/Listeners/RestoreLayoutExtensionsAfterUpdateListener.php`

RestoreLayoutExtensionsAfterUpdateListener는 plugin:update가 레이아웃 확장 조각(§레이아웃 확장)의 활성/비활성 상태를 초기화할 수 있어서 존재합니다 — 운영자가 특정 화면을 꺼둔 상태로 업데이트해도 그 선택이 사라지지 않도록 복원합니다. 8개 리스너 전부가 HookListenerInterface를 구현하는 것은 이 저장소의 전 리스너 공통 계약입니다.

레이아웃 확장

대상	설명
`resources/extensions/admin_order_list_test_badge.json`	다른 확장/템플릿 레이아웃에 주입되는 조각
`resources/extensions/admin_order_payment_query.json`	다른 확장/템플릿 레이아웃에 주입되는 조각
`resources/extensions/checkout_easy_pay.json`	다른 확장/템플릿 레이아웃에 주입되는 조각
`resources/extensions/user_mypage_order_receipt.json`	다른 확장/템플릿 레이아웃에 주입되는 조각
`resources/extensions/user_order_complete_receipt.json`	다른 확장/템플릿 레이아웃에 주입되는 조각

5개 조각은 각각 독립적인 화면 관심사입니다 — 관리자 주문 목록의 테스트배지, 관리자 주문 상세의 거래조회 UI, 체크아웃의 간편결제 버튼, 마이페이지·주문완료의 영수증 버튼이 서로 다른 화면에 주입되므로 하나로 합치지 않았습니다. user_mypage_order_receipt.json과 user_order_complete_receipt.json이 별도 파일인 것은 두 화면의 컴포넌트 트리와 데이터 소스가 다르기 때문입니다(§AGENTS.md "설계 원칙" — 상태는 이커머스 소유이므로 화면마다 필요한 조회 방식이 다를 수 있습니다).

미들웨어

미들웨어	부착 대상(targets)	우선순위
`VbankNotifyIpWhitelist`	`web.plugins.sirsoft-pay_nicepayments.payment.vbank-notify`	-

결제 결과 콜백(/payment/callback)에는 이 미들웨어가 붙지 않습니다 — 그 경로는 브라우저가 POST 하는 경로라 발신 IP 가 사용자마다 다르기 때문입니다. IP 화이트리스트가 의미 있는 것은 나이스페이먼츠 서버가 직접 호출하는 가상계좌 입금통보뿐입니다. 로컬/테스트 환경에서는 이 제한을 자동 우회합니다.

브로드캐스트 채널

등록하는 브로드캐스트 채널이 없습니다.

결제 승인·통보는 전부 동기 HTTP 요청/응답 안에서 끝나는 흐름이라 실시간 브로드캐스트가 필요한 지점이 없습니다.

스케줄

등록하는 스케줄이 없습니다.

가상계좌 만료는 이 플러그인이 크론으로 스캔하지 않고, 만료 이후 도착하는 나이스페이먼츠 입금통보를 거부하는 방식으로 처리됩니다.

알림 정의

등록하는 알림 정의가 없습니다.

결제 완료/실패 알림은 이커머스 모듈이 주문 상태 변화를 기준으로 발송하는 공용 알림에 이미 포함됩니다 — PG 마다 별도 알림 정의를 만들면 같은 이벤트에 대해 PG 수만큼 중복 정의가 생깁니다. 운영자에게 실패를 알리고 싶은 확장은 §발행 훅의 refund_failed 를 구독합니다.

9.2 KiB Raw Blame History