HeuJung
8328b1db77
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 를 편입했다.
10 KiB
NHN KCP — 확장점
발행/구독 훅·미들웨어·채널·스케줄 · 진입점: AGENTS.md
발행 훅
발행 훅 8종 / 호출 지점 8곳. 이 중 4종은 getHooks() 선언에 없어 소스에서 자동 감지한 것입니다 — 선언에 추가하면 유형과 설명이 함께 실립니다.
| 훅 이름 | 유형 | 설명 | 발행 위치 |
|---|---|---|---|
sirsoft-pay_nhnkcp.escrow.delivery_started |
action | — | src/Controllers/EscrowCommonNotifyController.php:101 |
sirsoft-pay_nhnkcp.escrow.denial_confirmed |
action | — | src/Controllers/EscrowCommonNotifyController.php:98 |
sirsoft-pay_nhnkcp.escrow.purchase_cancelled |
action | — | src/Controllers/EscrowCommonNotifyController.php:97 |
sirsoft-pay_nhnkcp.escrow.purchase_confirmed |
action | — | src/Controllers/EscrowCommonNotifyController.php:96 |
sirsoft-pay_nhnkcp.payment.after_cancel |
action | KCP 결제 취소 완료 후 | src/Services/NhnKcpApiService.php:250 |
sirsoft-pay_nhnkcp.payment.after_confirm |
action | KCP 결제 승인 확인 완료 후 | src/Controllers/PaymentCallbackController.php:279 |
sirsoft-pay_nhnkcp.payment.before_cancel |
action | KCP 결제 취소 API 호출 전 (본인인증 등 확장 지점) | src/Services/NhnKcpApiService.php:229 |
sirsoft-pay_nhnkcp.payment.before_confirm |
action | KCP 결제 승인 확인 전 | src/Controllers/PaymentCallbackController.php:274 |
escrow.* 4종에 유형/설명이 비어 있는 것은 실수가 아니라 선언 누락입니다 — 소스에서
자동 감지된 훅이라 getHooks()에 등록하면 이름 그대로도 의미가 분명해 설명을 생략했습니다.
before_confirm/before_cancel은 KCP API 호출 전 개입 지점이라 여기서 예외를 던지면
실제 KCP 호출 자체가 일어나지 않습니다(예: 고액 결제에 추가 인증을 요구하고 싶은 확장이
before_cancel에서 조건 미충족 시 예외). after_*는 응답을 받은 뒤 부가효과(로그, 알림)를
붙이는 자리입니다.
구독 훅
| 훅 이름 | 유형 | 리스너 | 메서드 | 우선순위 |
|---|---|---|---|---|
core.layout_extension.after_apply |
filter | AdjustEcommercePaymentMethodsLayoutListener |
adjustPaymentMethodsLayout |
30 |
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 |
30 |
RegisterPgProviderListener 가 우선순위 10 으로 두 훅(get_client_config/
registered_pg_providers)을 모두 구독하는 이유는 "이 PG 가 존재한다는 사실"과 "체크아웃
화면이 필요로 하는 클라이언트 설정값"이 같은 리스너의 책임이기 때문입니다 — 등록과 설정
노출이 다른 리스너로 갈라지면 한쪽만 갱신되는 사각이 생깁니다. PaymentRefundListener(10)
가 CancelActivityLogListener(20)보다 먼저 실행되도록 우선순위를 명시한 것은 실제 취소가
성공한 뒤에야 활동 로그를 남기기 위함입니다 — 순서가 뒤바뀌면 "로그는 있는데 취소는 실패"가
생깁니다.
훅 리스너
| 리스너 | 구독 훅 | 등록 방식 | 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를 구현하는 것은
auto-discovery 대상이라는 뜻이 아니라 이 저장소의 전 리스너 공통 계약입니다.
레이아웃 확장
| 대상 | 설명 |
|---|---|
resources/extensions/admin_order_list_test_badge.json |
다른 확장/템플릿 레이아웃에 주입되는 조각 |
resources/extensions/admin_order_payment_query.json |
다른 확장/템플릿 레이아웃에 주입되는 조각 |
resources/extensions/checkout_easy_pay.json |
다른 확장/템플릿 레이아웃에 주입되는 조각 |
resources/extensions/user_order_complete_receipt.json |
다른 확장/템플릿 레이아웃에 주입되는 조각 |
resources/extensions/user_order_show.json |
다른 확장/템플릿 레이아웃에 주입되는 조각 |
5개 조각은 각각 독립적인 화면 관심사입니다 — 관리자 주문 목록의 테스트배지, 관리자 주문 상세의 거래조회 UI, 체크아웃의 간편결제 버튼, 주문완료/마이페이지의 영수증 버튼이 서로 다른 화면·다른 컴포넌트 트리에 주입되므로 하나의 조각으로 합치지 않았습니다. 새 KCP 기능이 필요로 하는 화면이 이 5개 중 하나에 해당하면 새 조각을 만들지 말고 기존 조각을 확장합니다.
미들웨어
| 미들웨어 | 부착 대상(targets) | 우선순위 |
|---|---|---|
RestrictKcpIp |
web.plugins.sirsoft-pay_nhnkcp.payment.vbank-notify, web.plugins.sirsoft-pay_nhnkcp.payment.escrow-common-notify |
- |
결제 결과 Return URL(/payment/callback)에는 이 미들웨어가 붙지 않습니다 — 그 경로는
브라우저가 POST 하는 경로라 발신 IP 가 사용자마다 다르기 때문입니다. IP 화이트리스트가
의미 있는 것은 KCP 서버가 직접 호출하는 두 통보 경로(가상계좌 입금통보·에스크로 공통통보)
뿐입니다. 테스트 모드에서는 개발 편의와 KCP testadmin 모의입금을 위해 이 제한을 우회합니다
— 운영 모드로 전환할 때 이 우회가 함께 꺼지는지 확인해야 합니다.
브로드캐스트 채널
등록하는 브로드캐스트 채널이 없습니다.
결제 승인·통보는 전부 동기 HTTP 요청/응답 안에서 끝나는 흐름이라 실시간 브로드캐스트가 필요한 지점이 없습니다 — 가상계좌 입금통보조차 KCP 서버의 POST 요청 하나로 완결됩니다.
스케줄
등록하는 스케줄이 없습니다.
가상계좌 만료 처리(§settings.md vbank_expire_days)는 이 플러그인이 크론으로 직접 만료
스캔을 하지 않고, 만료 이후 도착하는 KCP 입금통보를 거부하는 방식으로 처리됩니다 — 별도
스케줄 작업이 필요 없습니다.
알림 정의
등록하는 알림 정의가 없습니다.
결제 완료/실패 알림은 이커머스 모듈이 주문 상태 변화를 기준으로 발송하는 공용 알림에 이미 포함됩니다 — PG 마다 별도 알림 정의를 만들면 같은 이벤트(결제완료)에 대해 PG 수만큼 중복 알림 정의가 생깁니다.