HeuJung
494e581973
KISA 신고 4건(KVE-2026-1886/1887/1893/1894)을 검증하고, 미수정 2건과 동종 결함 전수 조사에서 나온 결함을 함께 조치했다. 권한 게이트 (KVE-2026-1893) - NHN KCP 관리자 주문 연동 7경로가 admin 보유 여부만 보고 세부 권한을 보지 않아, 업무 권한 없는 관리자가 주문번호·결제정보·수령인 연락처를 조회하고 에스크로 배송등록까지 할 수 있었다. 조회는 orders.read, 등록은 orders.update, 설정성 경로는 settings.read 로 게이트해 다른 PG 연동과 강도를 맞췄다. - 마케팅 채널 저장은 코어 플러그인 설정과 같은 저장소를 덮어쓰는 우회 경로라 core.plugins.update 를 부착했다. 첨부 해시 노출 (KVE-2026-1894 잔재) - 비밀글의 썸네일 URL 이 목록·상세 응답에 그대로 실려 첨부 해시가 노출됐다. 이미지 서빙은 이미 차단돼 있었으나 식별값 자체가 나갔다. 첨부 목록과 같은 게이트를 써서 값만 가리고 필드는 유지한다. 경쟁 조건 (KVE-2026-1886 + 전수 조사) - 쿠폰 차감을 조회 후 갱신에서 조건부 UPDATE 로 바꿔 1회 제한 쿠폰의 동시 사용을 막고, 선점당한 주문은 409 로 되돌린다. - 라이브 병렬 재현에서 그 롤백이 동작하지 않는 것을 확인했다. Action 훅 기본값이 큐 래핑 + afterCommit 이라 금전 처리가 호출자 커밋 뒤에 실행되고 있었다. 쿠폰·적립금 차감/복원 5개 구독에 sync 를 선언했고, 회귀 테스트는 손 등록이 아니라 실제 등록 경로를 태워 고정했다. - 동시 부분취소의 취소 누적 컬럼 lost update, 적립 lot 의 read-modify-write, 주문옵션당 적립 lot 중복 생성을 각각 행 잠금·컬럼 연산·유니크 제약으로 막았다. 기설치본의 중복 lot 은 인덱스 생성 전에 금액을 합산해 한 줄로 통합한다. 규정·문서 - sync 판정 기준을 hooks.md 에 명문화하고 /AGENTS.md Listener 표와 coverage manifest 에 반영했다. 같은 증상을 다시 만났을 때의 진단 경로를 트러블슈팅 사례로 남겼다.
4.3 KiB
관리자 주문 연동 API 레퍼런스
소유: 플러그인
sirsoft-pay_nhnkcp. 관리자 주문 목록·상세 화면이 호출하는 NHN KCP 연동 경로와 각 경로가 요구하는 세부 권한을 서술한다.
TL;DR (5초 요약)
1. admin 그룹의 모든 경로는 Bearer 토큰(관리자) + 이커머스 세부 권한을 함께 요구한다
2. 조회 경로는 sirsoft-ecommerce.orders.read, 쓰기 경로는 sirsoft-ecommerce.orders.update
3. 설정성 경로(입금통보 주소·시스템 점검)는 sirsoft-ecommerce.settings.read
4. 관리자(type=admin)라도 해당 권한이 없으면 403 이며, 요청은 아무 부작용도 남기지 않는다
5. 다른 결제대행사 플러그인(kginicis·nicepayments)과 동일한 권한 기준이다
권한 매트릭스
admin 미들웨어는 관리자 여부(type=admin 권한 보유)만 판정하고 업무 권한은 판정하지 않는다. 따라서 각 라우트가 요구 권한을 직접 선언한다.
| 메서드/URI | 라우트명 | 요구 권한 |
|---|---|---|
GET /api/plugins/sirsoft-pay_nhnkcp/admin/orders/test-mode-map |
...admin.orders.test-mode-map |
sirsoft-ecommerce.orders.read |
GET /api/plugins/sirsoft-pay_nhnkcp/admin/orders/easy-pay-display-map |
...admin.orders.easy-pay-display-map |
sirsoft-ecommerce.orders.read |
GET /api/plugins/sirsoft-pay_nhnkcp/admin/orders/{orderNumber}/transaction-status |
...admin.orders.transaction-status |
sirsoft-ecommerce.orders.read |
GET /api/plugins/sirsoft-pay_nhnkcp/admin/orders/{orderNumber}/escrow-delivery |
...admin.orders.escrow-delivery.form |
sirsoft-ecommerce.orders.read |
POST /api/plugins/sirsoft-pay_nhnkcp/admin/orders/{orderNumber}/escrow-delivery |
...admin.orders.escrow-delivery.register |
sirsoft-ecommerce.orders.update |
GET /api/plugins/sirsoft-pay_nhnkcp/admin/settings/test-mode-status |
...admin.settings.test-mode-status |
sirsoft-ecommerce.settings.read |
GET /api/plugins/sirsoft-pay_nhnkcp/admin/vbank-notify-url |
...admin.vbank.notify.url |
sirsoft-ecommerce.settings.read |
GET /api/plugins/sirsoft-pay_nhnkcp/admin/health |
...admin.health |
sirsoft-ecommerce.settings.read |
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 관리자가 아니거나, 위 표의 권한을 보유하지 않은 경우 |
| 422 | Validation | 배송등록 요청의 운송장번호·택배사 코드가 형식에 맞지 않는 경우 |
권한 검사는 컨트롤러 진입 전에 수행되므로, 403 으로 거부된 배송등록 요청은 결제 정보(payment_meta)를 포함해 어떤 상태도 변경하지 않는다.
조회 경로
테스트 모드 주문 맵
GET .../admin/orders/test-mode-map
관리자 주문 목록에서 어떤 주문이 테스트 결제인지 배지로 표시하기 위한 맵을 반환한다. 응답 data 는 주문번호를 키로 하는 객체다.
간편결제 표시 맵
GET .../admin/orders/easy-pay-display-map
간편결제(PAYCO 등)로 결제된 주문의 원 결제수단 표시 라벨을 반환한다. 응답 data 는 주문번호를 키로 하며, 각 항목은 embedded_pg_provider_label·payment_method_label·payment_method_display_label 을 포함한다.
거래 상태 조회
GET .../admin/orders/{orderNumber}/transaction-status
상세 필드는 transaction-status.md 참조.
에스크로 배송등록 폼 데이터
GET .../admin/orders/{orderNumber}/escrow-delivery
배송등록 화면의 초기값(주문 정보·기본 배송지·기등록 배송 이력)을 반환한다. 이 주문에 에스크로 결제가 없으면 data 는 null 이다(오류 아님).
쓰기 경로
에스크로 배송등록
POST .../admin/orders/{orderNumber}/escrow-delivery
| 이름 | 위치 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
deli_numb |
body | string | 예 | 운송장번호 |
deli_corp |
body | string | 예 | 택배사 코드 (KCP 공식 코드표) |
NHN KCP 에 운송장 정보를 등록하고, 응답 중 허용된 필드만 정제해 결제 정보에 기록한다. 주문 조회 권한만 보유한 관리자는 이 경로에서 403 을 받는다.