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 를 편입했다.
5.2 KiB
NHN KCP — 설정·권한·라우트
설정 스키마·권한·메뉴·라우트·의존 관계 · 진입점: AGENTS.md
설정 스키마
| 키 | 타입 | 기본값 | 설명 |
|---|---|---|---|
is_test_mode |
boolean |
true |
테스트 모드 |
test_site_cd |
string |
T0000 |
테스트 사이트 코드 (site_cd) |
test_site_key |
string |
- | 테스트 사이트 키 (site_key) |
live_site_cd |
string |
- | 라이브 사이트 코드 (site_cd) |
live_site_key |
string |
- | 라이브 사이트 키 (site_key) |
redirect_success_url |
string |
{shopBase}/orders/{orderId}/complete |
결제 성공 리다이렉트 URL |
redirect_fail_url |
string |
{shopBase}/checkout |
결제 실패 리다이렉트 URL |
use_escrow |
boolean |
false |
에스크로 결제 활성화 |
escrow_test_site_cd |
string |
- | 테스트 에스크로 사이트 코드 |
vbank_expire_days |
integer |
3 |
가상계좌 입금 만료(일) |
easy_pay_allow_with_other_pg |
boolean |
false |
- |
easy_pay_payco |
boolean |
false |
- |
easy_pay_naverpay |
boolean |
false |
- |
easy_pay_naverpay_point |
boolean |
false |
- |
easy_pay_kakaopay |
boolean |
false |
- |
easy_pay_applepay |
boolean |
false |
- |
기본값 파일: config/settings/defaults.json · 설정 화면 레이아웃: resources/layouts/admin/plugin_settings.json
test_*/live_* 쌍 구조는 sirsoft-pay_kginicis와 동일한 이유입니다 — 테스트 모드와 운영
모드가 완전히 다른 자격증명 집합을 쓰므로 is_test_mode를 켜고 꺼도 서로의 값을 덮어쓰지
않습니다. kginicis 와 달리 japan_* 설정군이 전혀 없는 것은 이 플러그인이 KCP 의 일본/CBT
결제 상품을 구현하지 않기 때문입니다(§data-model.md, §architecture.md) — 이 플러그인에
일본 결제를 요구하는 요청이 오면 새 설정 키를 추가하는 대신 별도 플러그인 여부를 먼저
검토해야 합니다.
권한
선언된 권한이 없습니다.
결제 설정 접근 권한은 이커머스의 관리자 권한 체계 안에서 다뤄집니다 — PG 마다 별도 권한을 선언하면 PG 를 여러 개 설치했을 때 "결제 설정을 볼 수 있는 사람"이라는 하나의 개념이 플러그인 수만큼 중복 정의됩니다.
메뉴
등록하는 메뉴가 없습니다.
설정 화면(plugin_settings.json)은 코어의 "플러그인 관리 > 설정" 공통 진입점을 통해
접근합니다 — PG 플러그인마다 전용 사이드바 메뉴를 만들면 PG 를 여러 개 설치했을 때 메뉴가
난립합니다.
라우트
| 종류 | 파일 | URL prefix |
|---|---|---|
api |
src/routes/api.php |
/api/plugins/sirsoft-pay_nhnkcp/... |
web |
src/routes/web.php |
/plugins/sirsoft-pay_nhnkcp/... |
확장 라우트는 활성 상태인 확장의 것만 등록됩니다. 라우트 정의를 바꾸면 라우트 캐시 재생성이 필요합니다.
api(Bearer 토큰 인증, 모바일 승인키 발급처럼 로그인 사용자가 브라우저에서 직접 호출하는
엔드포인트)와 web(콜백·입금통보·공통통보처럼 KCP 서버나 리다이렉트로 도달하는
엔드포인트)이 분리된 이유는 인증 방식이 다르기 때문입니다 — KCP 는 우리 서비스의 Bearer
토큰을 모르므로 콜백 라우트에 api 인증 미들웨어를 걸 수 없습니다. 새 KCP 콜백을 추가할
때는 web 쪽에 둡니다.
의존 관계
이 확장이 의존하는 확장
| 확장 | 유형 | 버전 제약 | 번들 |
|---|---|---|---|
sirsoft-ecommerce |
모듈 | >=1.1.0 |
✅ |
이 확장에 의존하는 확장 (이 확장을 비활성화하면 함께 영향을 받습니다)
없음.
sirsoft-ecommerce >=1.1.0 하드 의존은 §data-model.md 에서 설명한 구조(결제 상태는
이커머스가 소유, 이 플러그인은 절차만 소유)의 직접적 결과입니다 — 이커머스 없이는 이
플러그인이 다룰 주문 자체가 존재하지 않습니다. 이커머스의 PG 등록 훅이나 Order 모델
구조가 바뀌면 이 최소 버전을 올려야 합니다(§CLAUDE.md "확장 → 확장 동기화").