Files

T

HeuJung 403154167a fix(core): api:docgen 재생성이 문서를 손실·열화시키는 결함 수정

재생성이 사람이 채운 서술과 이전 실측 결과를 지우고, 코드가 바뀌지 않은
문서까지 매 실행마다 흔들던 결함 5건을 고쳤다.

- 중첩 객체 파라미터가 문서에서 통째로 누락되던 문제: 배열 요소(items.*.id)를
상위로 대표시키려던 스킵 조건이 점(.) 포함 여부만 봐서, 와일드카드가 없는
중첩 객체 필드(refund_bank.*, general.*, content.* 등 17개 엔드포인트 수백 개)
까지 함께 버렸다. 와일드카드가 있을 때만 스킵하도록 좁혔다.
- 사람이 보강한 에러 응답 표가 자동 추론 초안에 덮여 사라지던 문제:
상태코드 키 단위로 병합한다.
- 실측 실패가 이전에 관측해 둔 응답 예시를 지우던 문제: 실측 성패는 호출 시점
데이터 유무에 좌우되므로(DELETE /checkout 은 대상이 없으면 404), 실패는
"새로 관측하지 못했다"는 뜻이지 기존 관측이 무효라는 뜻이 아니다.
- 실측 예시값·응답 예시 JSON 이 DB 상태를 그대로 반영해 비멱등하던 문제:
값이 아니라 스펙(필드 집합·타입)이 바뀐 경우에만 갱신한다. nullable 이
null 로 관측된 것은 타입 변경이 아니므로 기존 값을 유지한다.
- 요청 예시 path 파라미터가 실측 성패에 따라 흔들리던 문제: placeholder 로 고정.

결과: 문서 63개 전수 대조에서 손실 0(서술·표 셀·응답 예시), 전 scope 연속
재생성 시 diff 0(멱등).

2026-08-06 13:54:35 +09:00

7.5 KiB

Raw Blame History

Identity API 레퍼런스

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

TL;DR (5초 요약)

1. 이 문서는 실제 API 호출로 실측한 Identity 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
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 내부)

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "messages.success",
    "data": null
}

에러 응답

상태코드	의미	발생 조건
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