0 Fork 0

Files

T

HeuJung b10e89bef0 fix(core,board,ecommerce,page,gdpr,ckeditor5,kginicis,admin_basic,basic): 목록 조회·검증 계층 정비 및 감사 지적 전건 처리

목록 조회 성능 축(깊은 OFFSET·정렬·색인)과 그 검증 계층에서 계획서 전수검수와 3회에 걸친
감사가 지적한 항목을 처리했다. 세부 경위는 의 각 회차 문서에 있다.

검증 계층 — 컨트롤러가 base Request 를 직접 주입받던 확장 13곳을 전용 FormRequest 로 옮겼다.
옮기면서 기존 동작 계약은 그대로 두었다: 상한 초과 limit 을 거부하지 않고 상한까지 반환하던
공개 API, per_page 를 범위로 조정하던 관리자 목록, 미지원 period 를 year 로 해석하던 인기글
목록 모두 종전과 같은 응답을 낸다. 상한/폴백을 rules 로 승격시키면 200 이던 응답이 422 가
되어 기존 링크가 깨지므로, 규칙은 타입만 닫고 클램프·폴백은 접근자가 맡는다. period 는
접근자가 닫힌 집합만 반환해 캐시 키 공간도 함께 닫힌다.

ckeditor5 이미지 업로드만 ResponseHelper 봉투를 쓰지 않는다. 응답을 파싱하는 주체가 CDN 으로
로드되는 상위 CKEditor5 43.3.1 의 SimpleUploadAdapter 라 규약을 바꿀 수 없어, 각 응답 지점에
사유를 명시한 면제를 부착하고 근거를 API 문서에 남겼다.

하네스 — 룰 5개의 대상 경로 패턴이 매처와 맞지 않아 번들 확장 컨트롤러가 검사 대상에서
통째로 빠져 있었다. 패턴을 고치자 확장 위반 17건이 드러나 전건 처리했다. severity 오타가
요약 집계 양쪽에 안 잡혀 "0 error" 로 보고되던 문제도 런너 사전 검증으로 막았다.

정렬 게이트 대조 하네스는 관계 정렬 변형만 쓰는 저장소를 탐지하지 못한 채 통과시키고 있었다.
탐지·제외·인자 파싱을 함께 고치고 단위 테스트를 신설했다.

2026-08-02 15:29:29 +09:00

7.2 KiB

Raw Blame History

Identity API 레퍼런스

소유: plugin sirsoft-verification_kginicis · 생성: php artisan api:docgen (실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.

TL;DR (5초 요약)

1. 이 문서는 실제 API 호출로 실측한 Identity 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다

GET /api/plugins/sirsoft-verification_kginicis/me/identity/inicis

라우트명: api.plugins.sirsoft-verification_kginicis.me.identity.inicis.show
컨트롤러: \Plugins\Sirsoft\VerificationKginicis\Http\Controllers\MyInicisIdentityShowController@show
인증/권한: auth:sanctum

요청 파라미터

요청 파라미터 없음.

요청 예시

GET /api/plugins/sirsoft-verification_kginicis/me/identity/inicis HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우

설명

로그인한 사용자가 마이페이지 본인인증 카드에서 자신의 KG이니시스 본인확인 정보(마스킹)를 조회하는 엔드포인트다. AuthBaseController 를 상속하므로 auth:sanctum 인증이 필수이며, 라우트에 check.user_status:active 미들웨어가 걸려 활성 상태 사용자만 호출할 수 있다(정지/탈퇴 대기 사용자는 차단). 조회 전용이며 부수 효과는 없다.

요청 파라미터 없음: 대상은 항상 인증된 본인(Auth::id())이며, 다른 사용자의 정보를 조회할 수 없다. 컨트롤러가 InicisIdentityCardService::findForUser(Auth::id()) 로 본인 record 만 조회한다.
미인증 사용자(record 없음): 아직 본인인증을 하지 않은 사용자는 data: null 로 응답한다(코어 표준 null 처리 — HTTP 200, success: true). 프론트는 data 가 null 인 경우 「본인인증 하기」 유도 UI 를, 값이 있으면 본인확인 카드를 렌더한다.
PII 마스킹: 평문 개인정보는 서버에서 마스킹 후 노출한다(PIPC 사용자 본인 PII 열람권 충족). di/ci 등 식별값은 일체 노출하지 않는다. 이름은 첫 글자만(홍**), 생년월일은 연도만(1990-**-**), 휴대폰은 앞 3자리+뒤 4자리(010-****-5678)로 마스킹된다.

응답 필드 (data 내부, record 존재 시 — InicisIdentityResource):

필드	타입	예시값	용도/설명
method	string	`"KG이니시스 본인확인"`	본인확인 수단 표시 라벨(고정 문자열).
verified_at	string\|null	`"2026-07-01 14:22:10"`	최종 본인확인 시각(`Y-m-d H:i:s`). 재인증이 있었으면 `re_verified_at`, 없으면 최초 `verified_at`.
name_masked	string	`"홍**"`	마스킹된 실명(첫 글자 + 나머지 `*`).
birthday_masked	string	`"1990--"`	마스킹된 생년월일(연도만 노출).
phone_masked	string	`"010-****-5678"`	마스킹된 휴대폰 번호(앞 3 + 뒤 4자리).
is_adult	boolean	`true`	성인 여부(연령 게이팅 판정에 사용).
is_foreigner	boolean	`false`	외국인 여부.

이 외에 BaseApiResource 공통 메타 is_owner(항상 본인이므로 true) + abilities 가 함께 붙는다.

응답 예시 주의: 실측 시 샘플 사용자에게 본인인증 record 가 없어 data: null(record 없음) 응답만 관측된다. 아래 두 응답 예시 중 "record 존재 시" 는 InicisIdentityResource 구조 기준 정적 작성이다. 실제 record 가 있는 사용자로 실측하면 마스킹된 본인확인 정보가 채워진다.

응답 예시 (record 존재 시 — 정적, InicisIdentityResource 구조 기준)

{
  "success": true,
  "data": {
    "method": "KG이니시스 본인확인",
    "verified_at": "2026-07-01 14:22:10",
    "name_masked": "홍**",
    "birthday_masked": "1990-**-**",
    "phone_masked": "010-****-5678",
    "is_adult": true,
    "is_foreigner": false,
    "is_owner": true,
    "abilities": {}
  },
  "message": "성공적으로 처리되었습니다.",
  "error": null
}

응답 예시 (본인인증 이력 없음 — record 없음)

{
  "success": true,
  "data": null,
  "message": "성공적으로 처리되었습니다.",
  "error": null
}

PG 연동 web 엔드포인트 (docgen 수집 범위 밖)

아래 두 경로는 src/routes/web.php 에 선언된 브라우저 왕복 경로라 api:docgen 의 라우트 수집 대상(/api/plugins/...)에 포함되지 않는다. JSON API 가 아니므로 응답 필드 표 대신 요청 계약과 분기 동작만 기재한다.

POST /plugin/inicis/callback

라우트명: plugin.verification_kginicis.callback
호출자: KG이니시스 (매뉴얼 STEP2 — 외부 form POST)
미들웨어: web (CSRF 검증은 ValidateCsrfToken 제외 — 외부 호출이라 토큰이 없다)
FormRequest: InicisCallbackRequest — 검증 규칙 없음(의도된 결정)

이니시스는 매뉴얼에 명시되지 않은 필드를 가맹점 설정·인증 수단에 따라 함께 보낸다. 요청 파라미터를 화이트리스트로 닫으면 정상 콜백이 422 로 거부되어 인증이 끊기므로, 이 엔드포인트는 본문을 그대로 통과시키고 의미 검증(서명 대조·거래 매칭·challenge 해석)은 전적으로 InicisCallbackResolver 가 담당한다. 빈 규칙의 FormRequest 를 두는 이유는 "검증하지 않는다" 가 누락이 아니라 결정임을 코드에 남기기 위해서다.

응답: 항상 302 — /plugin/inicis/popup-bridge 로 결과 query 를 붙여 redirect 한다.

GET /plugin/inicis/popup-bridge

라우트명: plugin.verification_kginicis.popup-bridge
호출자: 사용자 브라우저 (callback 이 redirect)
FormRequest: InicisPopupBridgeRequest