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" 로 보고되던 문제도 런너 사전 검증으로 막았다.

정렬 게이트 대조 하네스는 관계 정렬 변형만 쓰는 저장소를 탐지하지 못한 채 통과시키고 있었다.
탐지·제외·인자 파싱을 함께 고치고 단위 테스트를 신설했다.
This commit is contained in:
HeuJung committed 2026-08-02 15:29:29 +09:00
1 parent 5f4a733b3b
commit b10e89bef0
276 files changed
+12519 -1438

No files matched your search

@@ -64,6 +64,7 @@ Content-Type: application/octet-stream
CKEditor5 의 SimpleUploadAdapter 가 에디터에 드롭/붙여넣은 이미지를 업로드하는 관리자 엔드포인트다. 컨트롤러가 `AdminBaseController` 를 상속하므로 실제 인증은 `auth:sanctum` **에 더해 관리자(admin) 미들웨어**가 적용된다(생성기 표기는 `auth:sanctum` 만 노출).
- **응답 형식이 표준 envelope 가 아니다.** SimpleUploadAdapter 규격상 성공 시 HTTP 201 + 최상위 `{"url": "..."}`, 실패 시 4xx/5xx + `{"error": {"message": "..."}}` 를 반환한다. `ResponseHelper` 를 쓰지 않으므로 `data`/`success` 필드가 없다.
이 규격은 우리 코드가 정한 것이 아니다 — 응답을 파싱하는 주체가 CDN 으로 로드되는 CKEditor5 43.3.1 의 `SimpleUploadAdapter`(`resources/js/handlers/initEditor.ts` 의 `editorConfig.simpleUpload`)이므로 파싱 규약을 바꿀 수 없다. 컨트롤러의 각 응답 지점에는 이 사유로 `audit:allow response-helper-bypass` 를 명시해 두었으니, envelope 로 감싸는 "수정" 을 하면 에디터의 이미지 업로드가 조용히 실패한다.
- **요청 파라미터**: multipart body 의 `upload` 필드(이미지 파일 1개). 허용 MIME 은 `jpeg,jpg,png,gif,webp`, 최대 크기는 플러그인 설정 `imageMaxSizeMb`(기본 2MB) 로 동적 결정된다. 검증 실패도 CKEditor 규격(`{"error":{"message":...}}`, HTTP 422)으로 응답한다.
- **선택 권한 게이트**: query 파라미터 `permission` 이 주어지면, 현재 사용자가 해당 권한을 갖지 못한 경우 403 `{"error":{"message":...}}`. 에디터를 임베드하는 화면이 업로드 권한을 세분화할 때 사용한다.
- 업로드 성공 시 반환하는 `url` 은 공개 서빙 엔드포인트(`GET /images/{hash}`)의 절대 URL 이다.
@@ -14,8 +14,10 @@ use Plugins\Sirsoft\Ckeditor5\Services\ImageUploadService;
* CKEditor5 SimpleUploadAdapter가 요구하는 형식으로 이미지를 저장하고
* 공개 URL을 반환합니다.
*
* 응답 형식: { "url": "https://..." }
* ResponseHelper 사용 불가 — CKEditor SimpleUploadAdapter는 최상위 { url } 키를 요구합니다.
* 응답 형식: { "url": "https://..." } / 실패 시 { "error": { "message": "..." } }
* ResponseHelper 사용 불가 — 응답을 파싱하는 SimpleUploadAdapter 가 CDN 으로 로드되는
* CKEditor5 43.3.1 상위 코드라 봉투 구조를 해석하지 못합니다 (파싱 규약 변경 불가).
* 이 사유로 각 응답 지점에 audit:allow response-helper-bypass 를 명시했습니다.
*/
class ImageUploadController extends AdminBaseController
{
@@ -41,6 +43,7 @@ class ImageUploadController extends AdminBaseController
$user = $this->getCurrentUser();
if ($uploadPermission && $user && ! $user->hasPermission($uploadPermission)) {
// audit:allow response-helper-bypass reason: CDN 상위 SimpleUploadAdapter 가 최상위 error.message 를 읽는다 (봉투 불가)
return response()->json([
'error' => ['message' => __('sirsoft-ckeditor5::messages.upload.forbidden')],
], 403);
@@ -52,13 +55,14 @@ class ImageUploadController extends AdminBaseController
$user?->id
);
// CKEditor SimpleUploadAdapter가 요구하는 최상위 { url } 형식
// audit:allow response-helper-bypass reason: CDN 상위 SimpleUploadAdapter 가 최상위 url 을 읽는다 (봉투 불가)
return response()->json(['url' => $image->download_url], 201);
} catch (\Exception $e) {
Log::error('[sirsoft-ckeditor5] 이미지 업로드 실패', [
'error' => $e->getMessage(),
]);
// audit:allow response-helper-bypass reason: CDN 상위 SimpleUploadAdapter 가 최상위 error.message 를 읽는다 (봉투 불가)
return response()->json([
'error' => ['message' => __('sirsoft-ckeditor5::messages.upload.failed')],
], 500);
@@ -13,6 +13,12 @@
- 거부 후 다시 동의하면 상태가 동의로 갱신되며, 거부·동의 이력은 모두 보존됩니다.
- 마이페이지 「쿠키 동의 관리」에 「모두 동의」 버튼 추가 — 동의하지 않은 선택 항목을 한 번에 동의할 수 있습니다.
- 자동 차단 정책 안내에 보호 범위 한계를 명시했습니다 — 이 자동 차단은 플러그인·모듈이 등록한 스크립트만 대상이며, 운영자가 템플릿 외부 스크립트 등으로 head 영역에 직접 삽입한 외부 스크립트는 보호 범위 밖임을 안내합니다.
### Fixed
- 정책 버전 발행 이력이 20건까지만 보이고 그보다 오래된 이력은 열어볼 방법이 없던 문제를 수정했습니다. 이력 아래에 이전·다음 이동과 총 건수 표시를 추가해 전체 이력을 확인할 수 있습니다.
- 관리자 「GDPR 동의 이력」의 출처 칸에 "회원가입", "마이페이지 일괄 재동의" 대신 번역되지 않은 내부 문자열이 그대로 보이던 문제를 수정했습니다.
- 「GDPR 동의 이력」의 출처 필터에 "회원가입"과 "마이페이지 일괄 재동의"가 빠져 있어, 그 경로로 남은 동의 기록만 골라볼 수 없던 문제를 수정했습니다.
- 정책 버전 목록의 정렬 기준을 고정해, 페이지를 넘길 때 순서가 흔들리지 않도록 했습니다.
### Changed
@@ -47,7 +47,7 @@ _목록 응답: `data.data[]` 배열 항목의 필드 + `data.pagination`._
| session_id | string | `c50916f6-58ee-42a6-a046-60a0c9ecfad2` | session 식별자 (연관 리소스 참조) |
| consent_key | string | `cookie_marketing` | 변경된 동의 항목 키 (쿠키 카테고리 키). 어떤 동의 항목의 부여/철회가 기록된 행인지 나타냅니다 |
| action | string | `revoked` | 이 이력 행의 변경 유형 (`granted`=동의 부여, `revoked`=철회, `rejected`=명시적 거부). `rejected`는 배너에서 "동의하지 않고 계속하기"로 선택형 카테고리를 거부한 행위이며 관리자 화면에 amber 배지로 표시됩니다. Art.7(1) 입증 트레일의 행위 구분입니다 |
| source | string | `banner` | 동의 변경이 발생한 경로 (`banner`=쿠키 배너, `preference_center`=환경설정 센터, `mypage`=마이페이지, 그 외 `register`/`order`/`withdraw`) |
| source | string | `banner` | 동의 변경이 발생한 경로. 허용 어휘는 `ConsentSource` enum 5종 — `banner`=쿠키 배너, `preference_center`=환경설정 센터, `register`=회원가입, `mypage`=마이페이지, `mypage_renew_all`=정책 개정 후 마이페이지 일괄 재동의(서버 자체 기록) |
| policy_version | string | `10` | 변경 시점의 정책 버전 문자열. 해당 동의가 어느 정책 버전 기준으로 표명되었는지 기록해 정책 갱신 후 재동의 판정과 감사에 사용됩니다 |
| categories | object | `{"cookie_analytics":false,"cookie_marketing":false,"cooki…` | 변경 시점 전체 카테고리별 동의 여부 스냅샷 (키→boolean). MySQL JSON 컬럼이라 키가 알파벳 순으로 정규화 저장됩니다 |
| categories_snapshot | array | `[{"key":"cookie_necessary","label_key":"sirsoft-gdpr.cons…` | `categories` 객체를 관리자 화면 iteration 친화 배열(`{key, label_key, granted}`)로 변환한 것. 필수→분석→마케팅 UX 위계 순으로 재정렬되며 `label_key`는 프론트가 다국어로 해석합니다 |
@@ -89,6 +89,6 @@ HTTP/1.1 200
<!-- @generated:end -->
**설명** 관리자 감사 화면에서 `gdpr_user_consent_histories` 테이블의 동의 로그를 페이지네이션으로 조회합니다. `auth:sanctum`과 `sirsoft-gdpr.privacy.view` 권한이 필요합니다. `email`, `session_id`, `consent_keys[]`, `actions[]`(granted|revoked|rejected), `sources[]`(banner|preference_center|mypage), `per_page`(1~100, 기본 20) 쿼리 필터를 지원합니다. DPO 감사 용도로 IP 주소와 User-Agent까지 노출되는 조회 전용 엔드포인트입니다.
**설명** 관리자 감사 화면에서 `gdpr_user_consent_histories` 테이블의 동의 로그를 페이지네이션으로 조회합니다. `auth:sanctum`과 `sirsoft-gdpr.privacy.view` 권한이 필요합니다. `email`, `session_id`, `consent_keys[]`, `actions[]`(granted|revoked|rejected — `ConsentAction` enum 전 케이스), `sources[]`(banner|preference_center|register|mypage|mypage_renew_all — `ConsentSource` enum 전 케이스), `per_page`(1~100, 기본 20) 쿼리 필터를 지원합니다. DPO 감사 용도로 IP 주소와 User-Agent까지 노출되는 조회 전용 엔드포인트입니다.
@@ -138,6 +138,9 @@ return [
'snapshot_action' => 'Snapshot',
],
],
'history_page_summary' => ':total total · page :current / :last',
'history_prev' => 'Previous',
'history_next' => 'Next',
'snapshot_view_short' => 'View',
'material_modal' => [
'title' => 'Publish new policy version + trigger re-consent',
@@ -195,7 +198,9 @@ return [
'source' => [
'banner' => 'Banner',
'preference_center' => 'Preferences',
'register' => 'Sign-up',
'mypage' => 'MyPage',
'mypage_renew_all' => 'MyPage bulk re-consent',
],
'col' => [
'created_at' => 'Time',
@@ -138,6 +138,9 @@ return [
'snapshot_action' => '본문',
],
],
'history_page_summary' => '총 :total건 · :current / :last 페이지',
'history_prev' => '이전',
'history_next' => '다음',
'snapshot_view_short' => '보기',
'material_modal' => [
'title' => '정책 버전 발행 + 재동의 트리거',
@@ -195,7 +198,9 @@ return [
'source' => [
'banner' => '배너',
'preference_center' => '환경설정',
'register' => '회원가입',
'mypage' => '마이페이지',
'mypage_renew_all' => '마이페이지 일괄 재동의',
],
'col' => [
'created_at' => '시점',
@@ -45,7 +45,7 @@
"title": "GDPR Settings",
"description": "Operators control the cookie consent banner and the MyPage privacy card.",
"section": {
"operator": "Operator \/ Privacy Policy",
"operator": "Operator / Privacy Policy",
"operator_desc": "Register the operator name, data storage location, and privacy policy page slug shown in the cookie banner and policy page.",
"cookie_banner": "Cookie Consent Banner",
"cookie_banner_desc": "Configure visibility, position, categories, and policy version of the cookie consent banner — all in one place.",
@@ -77,14 +77,14 @@
"placeholder": "e.g., privacy-policy"
},
"legal_entity_name": {
"label": "Legal Entity \/ Operator Name",
"label": "Legal Entity / Operator Name",
"hint": "The operator name shown in the cookie banner and MyPage.",
"placeholder": "e.g., Acme Corp."
},
"data_storage_location": {
"label": "Data Storage Location",
"hint": "Country where user data is stored, shown to users. e.g., \"United States (AWS)\", \"Germany\". Do not enter IP addresses, cloud region codes (e.g., ap-northeast-2), or datacenter addresses — these are security-sensitive.",
"placeholder": "e.g., Korea (self-hosted IDC) \/ United States (AWS)"
"placeholder": "e.g., Korea (self-hosted IDC) / United States (AWS)"
},
"banner_enabled": {
"label": "Show Cookie Banner",
@@ -201,7 +201,10 @@
"open_policy_page": "Open policy page",
"no_policy_slug": "No privacy policy page registered."
},
"not_found": "Policy version not found."
"not_found": "Policy version not found.",
"history_page_summary": "{total} total · page {current} / {last}",
"history_prev": "Previous",
"history_next": "Next"
}
},
"admin": {
@@ -233,7 +236,9 @@
"source": {
"banner": "Banner",
"preference_center": "Preferences",
"mypage": "MyPage"
"mypage": "MyPage",
"register": "Sign-up",
"mypage_renew_all": "MyPage bulk re-consent"
},
"col": {
"created_at": "Time",
@@ -45,10 +45,10 @@
"title": "GDPR 설정",
"description": "쿠키 동의 배너와 마이페이지 동의 관리 카드의 동작을 운영자가 제어합니다.",
"section": {
"operator": "운영 주체 \/ 개인정보처리방침",
"operator": "운영 주체 / 개인정보처리방침",
"operator_desc": "쿠키 배너·정책 페이지에 표시될 운영 주체, 데이터 저장 위치, 정책 페이지 슬러그를 등록합니다.",
"cookie_banner": "쿠키 동의 배너",
"cookie_banner_desc": "방문자에게 표시되는 쿠키 동의 배너의 노출\/위치\/카테고리\/정책 버전을 한 곳에서 설정합니다.",
"cookie_banner_desc": "방문자에게 표시되는 쿠키 동의 배너의 노출/위치/카테고리/정책 버전을 한 곳에서 설정합니다.",
"cookie_banner_settings": "배너 표시 설정",
"cookie_categories": "쿠키 카테고리",
"cookie_policy_version": "쿠키 정책 버전",
@@ -77,14 +77,14 @@
"placeholder": "예: privacy-policy"
},
"legal_entity_name": {
"label": "법인명 \/ 운영 주체",
"label": "법인명 / 운영 주체",
"hint": "쿠키 배너와 마이페이지에 표시되는 사이트 운영 주체 이름입니다.",
"placeholder": "예: (주)회사명"
},
"data_storage_location": {
"label": "데이터 저장 위치",
"hint": "사용자에게 안내할 데이터 저장 국가를 입력하세요. 예: \"대한민국\", \"미국 (AWS)\". IP 주소, 클라우드 리전 코드(예: ap-northeast-2), 데이터센터 주소는 보안상 입력하지 마세요.",
"placeholder": "예: 대한민국 (자체 데이터센터) \/ 미국 (AWS)"
"placeholder": "예: 대한민국 (자체 데이터센터) / 미국 (AWS)"
},
"banner_enabled": {
"label": "쿠키 배너 노출",
@@ -201,13 +201,16 @@
"open_policy_page": "본문 페이지 열기",
"no_policy_slug": "등록된 정책 본문 페이지가 없습니다."
},
"not_found": "해당 정책 버전을 찾을 수 없습니다."
"not_found": "해당 정책 버전을 찾을 수 없습니다.",
"history_page_summary": "총 {total}건 · {current} / {last} 페이지",
"history_prev": "이전",
"history_next": "다음"
}
},
"admin": {
"consent_log": {
"title": "GDPR 동의 이력",
"description": "회원·게스트의 동의\/철회 변경 이력을 조회합니다. IP·User-Agent 등 감사 정보가 함께 노출됩니다.",
"description": "회원·게스트의 동의/철회 변경 이력을 조회합니다. IP·User-Agent 등 감사 정보가 함께 노출됩니다.",
"refresh": "새로고침",
"empty": "조회된 동의 이력이 없습니다.",
"clear_filters": "필터 초기화",
@@ -233,7 +236,9 @@
"source": {
"banner": "배너",
"preference_center": "환경설정",
"mypage": "마이페이지"
"mypage": "마이페이지",
"register": "회원가입",
"mypage_renew_all": "마이페이지 일괄 재동의"
},
"col": {
"created_at": "시점",
@@ -259,7 +264,7 @@
"title": "쿠키 동의 관리",
"description": "사이트가 사용 중인 쿠키 항목에 대한 동의를 변경하거나 철회할 수 있습니다.",
"section_consents": "내 동의 현황",
"section_consents_hint": "동의\/철회 시점에 따라 즉시 반영됩니다. 필수 항목은 철회할 수 없습니다.",
"section_consents_hint": "동의/철회 시점에 따라 즉시 반영됩니다. 필수 항목은 철회할 수 없습니다.",
"col_consent_key": "동의 항목",
"col_consented": "상태",
"col_consented_at": "동의일",
@@ -312,7 +317,7 @@
"save": "선택 저장",
"policy_link": "개인정보처리방침",
"preferences_title": "쿠키 환경설정",
"preferences_description": "카테고리별 쿠키 사용을 개별 동의\/철회할 수 있습니다. 필수 카테고리는 끌 수 없습니다.",
"preferences_description": "카테고리별 쿠키 사용을 개별 동의/철회할 수 있습니다. 필수 카테고리는 끌 수 없습니다.",
"category_required_badge": "필수",
"view_policy_label": "변경된 정책 본문 보기",
"operator_and_storage_line": "본 사이트는 {entity}이(가) 운영하며, 데이터는 {location}에 저장됩니다",
@@ -1027,6 +1027,98 @@
"text": "$t:sirsoft-gdpr.admin.consent_log.source.mypage"
}
]
},
{
"type": "basic",
"name": "Label",
"props": {
"className": "inline-clickable"
},
"children": [
{
"type": "basic",
"name": "Input",
"props": {
"type": "checkbox",
"className": "checkbox",
"checked": "{{(_local.filter.sources || []).includes('register')}}"
},
"actions": [
{
"type": "change",
"handler": "sequence",
"params": {
"actions": [
{
"handler": "setState",
"params": {
"target": "local",
"filter.sources": "{{$event.target.checked ? [...(_local.filter.sources || []).filter(s => s !== 'register'), 'register'] : (_local.filter.sources || []).filter(s => s !== 'register')}}"
}
},
{
"actionRef": "searchConsentLogs"
}
]
}
}
]
},
{
"type": "basic",
"name": "Span",
"props": {
"className": "text-label"
},
"text": "$t:sirsoft-gdpr.admin.consent_log.source.register"
}
]
},
{
"type": "basic",
"name": "Label",
"props": {
"className": "inline-clickable"
},
"children": [
{
"type": "basic",
"name": "Input",
"props": {
"type": "checkbox",
"className": "checkbox",
"checked": "{{(_local.filter.sources || []).includes('mypage_renew_all')}}"
},
"actions": [
{
"type": "change",
"handler": "sequence",
"params": {
"actions": [
{
"handler": "setState",
"params": {
"target": "local",
"filter.sources": "{{$event.target.checked ? [...(_local.filter.sources || []).filter(s => s !== 'mypage_renew_all'), 'mypage_renew_all'] : (_local.filter.sources || []).filter(s => s !== 'mypage_renew_all')}}"
}
},
{
"actionRef": "searchConsentLogs"
}
]
}
}
]
},
{
"type": "basic",
"name": "Span",
"props": {
"className": "text-label"
},
"text": "$t:sirsoft-gdpr.admin.consent_log.source.mypage_renew_all"
}
]
}
]
}
@@ -38,10 +38,11 @@
"id": "gdprPolicyVersionHistory",
"label_key": "$t:sirsoft-gdpr.editor.data_source.gdprPolicyVersionHistory",
"type": "api",
"endpoint": "/api/plugins/sirsoft-gdpr/admin/policy-versions",
"endpoint": "/api/plugins/sirsoft-gdpr/admin/policy-versions?page={{_local.policyHistoryPage ?? 1}}",
"method": "GET",
"auto_fetch": false,
"auth_required": true
"auth_required": true,
"comment": "정책 버전 이력 — 페이지는 _local.policyHistoryPage 로 관리하고 페이저가 setState + refetchDataSource 로 이동시킨다."
},
{
"comment": "정책 버전 단건 snapshot — _global.viewingPolicyVersion 정수를 endpoint path 에 보간. v배지/이력 행 클릭 시 setState global.viewingPolicyVersion → openModal policy_version_snapshot_modal 시퀀스에서 자동 fetch.",
@@ -63,7 +64,8 @@
"isSaving": false,
"hasChanges": false,
"errors": null,
"policyHistoryOpen": false
"policyHistoryOpen": false,
"policyHistoryPage": 1
}
}
],
@@ -929,7 +931,8 @@
"handler": "setState",
"params": {
"target": "local",
"policyHistoryOpen": "{{!_local.policyHistoryOpen}}"
"policyHistoryOpen": "{{!_local.policyHistoryOpen}}",
"policyHistoryPage": 1
}
},
{
@@ -1171,6 +1174,103 @@
]
}
]
},
{
"id": "policy_version_history_pager",
"comment": "이력 페이저 — 총건수/현재 페이지를 함께 표시한다. 없으면 최신 20건만 보이고 나머지가 조용히 잘린다.",
"type": "basic",
"name": "Div",
"if": "{{(gdprPolicyVersionHistory?.data?.pagination?.last_page ?? 1) > 1}}",
"props": {
"className": "flex items-center justify-between gap-3 pt-3 mt-3 border-t border-gray-200 dark:border-gray-700"
},
"children": [
{
"type": "basic",
"name": "Span",
"props": {
"className": "text-label-subtle text-sm"
},
"text": "$t:sirsoft-gdpr.settings.policy_version.history_page_summary|current={{gdprPolicyVersionHistory?.data?.pagination?.current_page ?? 1}}|last={{gdprPolicyVersionHistory?.data?.pagination?.last_page ?? 1}}|total={{gdprPolicyVersionHistory?.data?.pagination?.total ?? 0}}"
},
{
"type": "basic",
"name": "Div",
"props": {
"className": "flex items-center gap-2"
},
"children": [
{
"id": "policy_history_prev",
"type": "basic",
"name": "Button",
"props": {
"type": "button",
"className": "btn btn-sm btn-neutral",
"disabled": "{{(gdprPolicyVersionHistory?.data?.pagination?.current_page ?? 1) <= 1}}"
},
"text": "$t:sirsoft-gdpr.settings.policy_version.history_prev",
"actions": [
{
"type": "click",
"handler": "sequence",
"params": {
"actions": [
{
"handler": "setState",
"params": {
"target": "local",
"policyHistoryPage": "{{Math.min(Math.max(1, (_local.policyHistoryPage ?? 1) + (-1)), gdprPolicyVersionHistory?.data?.pagination?.last_page ?? 1)}}"
}
},
{
"handler": "refetchDataSource",
"params": {
"dataSourceId": "gdprPolicyVersionHistory"
}
}
]
}
}
]
},
{
"id": "policy_history_next",
"type": "basic",
"name": "Button",
"props": {
"type": "button",
"className": "btn btn-sm btn-neutral",
"disabled": "{{(gdprPolicyVersionHistory?.data?.pagination?.current_page ?? 1) >= (gdprPolicyVersionHistory?.data?.pagination?.last_page ?? 1)}}"
},
"text": "$t:sirsoft-gdpr.settings.policy_version.history_next",
"actions": [
{
"type": "click",
"handler": "sequence",
"params": {
"actions": [
{
"handler": "setState",
"params": {
"target": "local",
"policyHistoryPage": "{{Math.min(Math.max(1, (_local.policyHistoryPage ?? 1) + (1)), gdprPolicyVersionHistory?.data?.pagination?.last_page ?? 1)}}"
}
},
{
"handler": "refetchDataSource",
"params": {
"dataSourceId": "gdprPolicyVersionHistory"
}
}
]
}
}
]
}
]
}
]
}
]
}
@@ -0,0 +1,66 @@
<?php
namespace Plugins\Sirsoft\Gdpr\Enums;
/**
* 동의 기록의 발생 경로 (출처)
*
* `gdpr_user_consent_histories.source` / `gdpr_user_consents.last_source` 에 저장되는 값의
* 단일 출처(SSoT)입니다. 관리자 동의 이력 화면의 출처 필터 옵션과 라벨도 이 목록에서 파생합니다.
*
* 어휘를 이 enum 밖(FormRequest `in:` 문자열, 서비스/리스너 리터럴)에 흩어 두면
* 화면 필터가 실제 기록 어휘의 부분집합이 되어 일부 행이 어떤 필터로도 도달하지 못하고,
* 라벨 키가 없는 값은 목록 셀에 원시 키 문자열로 노출됩니다 (#492 실측 결함).
*
* - banner: 쿠키 배너에서 동의/거부
* - preference_center: 환경설정(선호 센터)에서 변경
* - register: 회원가입 시 동의 (GdprAuthConsentListener)
* - mypage: 마이페이지 동의 관리에서 변경
* - mypage_renew_all: 정책 개정 후 마이페이지에서 일괄 재동의 (GdprConsentService::renewAll)
*/
enum ConsentSource: string
{
case Banner = 'banner';
case PreferenceCenter = 'preference_center';
case Register = 'register';
case Mypage = 'mypage';
case MypageRenewAll = 'mypage_renew_all';
/**
* 사용자 친화 라벨을 반환합니다.
*
* @return string lang 키 해석 결과 (locale 자동 반영)
*/
public function label(): string
{
return __('sirsoft-gdpr::messages.admin.consent_log.source.'.$this->value);
}
/**
* 모든 케이스의 string 값 목록.
*
* @return array<int, string>
*/
public static function allValues(): array
{
return array_column(self::cases(), 'value');
}
/**
* 사용자 요청으로 직접 지정할 수 있는 출처 값 목록.
*
* `register` / `mypage_renew_all` 은 서버가 스스로 기록하는 경로이므로
* 공개 요청 본문에서 지정할 수 없습니다.
*
* @return array<int, string>
*/
public static function requestSelectableValues(): array
{
return [
self::Banner->value,
self::PreferenceCenter->value,
self::Register->value,
self::Mypage->value,
];
}
}
@@ -5,7 +5,7 @@ namespace Plugins\Sirsoft\Gdpr\Http\Controllers\Admin;
use App\Helpers\ResponseHelper;
use App\Http\Controllers\Api\Base\AdminBaseController;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Plugins\Sirsoft\Gdpr\Http\Requests\IndexConsentLogRequest;
use Plugins\Sirsoft\Gdpr\Http\Resources\GdprConsentLogResource;
use Plugins\Sirsoft\Gdpr\Services\GdprConsentLogService;
@@ -40,25 +40,15 @@ class GdprAdminConsentLogController extends AdminBaseController
* - session_id: 게스트 세션 ID 부분 일치 (DataGrid 가 앞 8자만 표시하므로 prefix/중간 모두 허용)
* - consent_keys[]: 동의 항목 키 배열 (whereIn)
* - actions[]: granted|revoked 배열
* - sources[]: banner|preference_center|mypage 배열
* - sources[]: 출처 배열 (허용 어휘는 ConsentSource enum — banner|preference_center|register|mypage|mypage_renew_all)
* - per_page: 페이지 크기 (1~100, 기본 20)
*
* @param Request $request HTTP 요청
* @param IndexConsentLogRequest $request HTTP 요청
* @return JsonResponse
*/
public function index(Request $request): JsonResponse
public function index(IndexConsentLogRequest $request): JsonResponse
{
$filters = [
'email' => $request->query('email'),
'session_id' => $request->query('session_id'),
'consent_keys' => $this->normalizeArrayParam($request->query('consent_keys')),
'actions' => $this->normalizeArrayParam($request->query('actions')),
'sources' => $this->normalizeArrayParam($request->query('sources')),
];
$perPage = max(1, min(100, (int) $request->query('per_page', 20)));
$paginator = $this->consentLogService->paginateForAdmin($filters, $perPage);
$paginator = $this->consentLogService->paginateForAdmin($request->filters(), $request->perPage());
return ResponseHelper::success('messages.success', [
'data' => GdprConsentLogResource::collection($paginator->items()),
@@ -72,26 +62,4 @@ class GdprAdminConsentLogController extends AdminBaseController
],
]);
}
/**
* 쿼리 파라미터 배열을 정규화합니다.
*
* `?consent_keys[]=a&consent_keys[]=b` → ['a', 'b']
* `?consent_keys=a` → ['a'] (단일 값도 배열로 정규화)
* `null` 또는 빈 값 → []
*
* @param mixed $value 쿼리 값
* @return array<int, string>
*/
private function normalizeArrayParam(mixed $value): array
{
if ($value === null || $value === '') {
return [];
}
if (is_array($value)) {
return array_values(array_filter(array_map('strval', $value), fn ($v) => $v !== ''));
}
return [(string) $value];
}
}
@@ -5,7 +5,7 @@ namespace Plugins\Sirsoft\Gdpr\Http\Controllers\Admin;
use App\Helpers\ResponseHelper;
use App\Http\Controllers\Api\Base\AdminBaseController;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Plugins\Sirsoft\Gdpr\Http\Requests\IndexPolicyVersionRequest;
use Plugins\Sirsoft\Gdpr\Http\Requests\PublishPolicyVersionRequest;
use Plugins\Sirsoft\Gdpr\Http\Resources\GdprPolicyVersionDetailResource;
use Plugins\Sirsoft\Gdpr\Http\Resources\GdprPolicyVersionResource;
@@ -28,8 +28,8 @@ class GdprAdminPolicyVersionController extends AdminBaseController
/**
* GdprAdminPolicyVersionController 생성자
*
* @param GdprPolicyVersionService $service 정책 버전 서비스
* @param GdprSettingsService $settingsService 현재 settings snapshot 캡처용
* @param GdprPolicyVersionService $service 정책 버전 서비스
* @param GdprSettingsService $settingsService 현재 settings snapshot 캡처용
*/
public function __construct(
private readonly GdprPolicyVersionService $service,
@@ -44,14 +44,12 @@ class GdprAdminPolicyVersionController extends AdminBaseController
* 쿼리 파라미터:
* - per_page: 페이지 크기 (1~100, 기본 20)
*
* @param Request $request HTTP 요청
* @param IndexPolicyVersionRequest $request HTTP 요청
* @return JsonResponse
*/
public function index(Request $request): JsonResponse
public function index(IndexPolicyVersionRequest $request): JsonResponse
{
$perPage = max(1, min(100, (int) $request->query('per_page', 20)));
$paginator = $this->service->paginate($perPage);
$paginator = $this->service->paginate($request->perPage());
return ResponseHelper::success('messages.success', [
'data' => GdprPolicyVersionResource::collection($paginator->items()),
@@ -77,7 +75,7 @@ class GdprAdminPolicyVersionController extends AdminBaseController
* 호출 시 현재 settings snapshot 을 자동 캡처하여 새 정책 버전 발행
* (settings 자체는 변경되지 않음 — 발행만 수행).
*
* @param PublishPolicyVersionRequest $request memo 필수 검증
* @param PublishPolicyVersionRequest $request memo 필수 검증
* @return JsonResponse
*/
public function store(PublishPolicyVersionRequest $request): JsonResponse
@@ -118,7 +116,7 @@ class GdprAdminPolicyVersionController extends AdminBaseController
*
* 권한: sirsoft-gdpr.privacy.view (라우트 미들웨어에서 검증).
*
* @param int $version 조회할 정책 버전 정수 (URL path param)
* @param int $version 조회할 정책 버전 정수 (URL path param)
* @return JsonResponse 200 + detail / 404 (버전 부재)
*/
public function show(int $version): JsonResponse
@@ -6,6 +6,9 @@ use App\Helpers\ResponseHelper;
use App\Http\Controllers\Api\Base\PublicBaseController;
use Illuminate\Http\JsonResponse;
use Plugins\Sirsoft\Gdpr\Concerns\IssuesGuestSessionCookie;
use Illuminate\Http\Request;
use Illuminate\Support\Str;
use Plugins\Sirsoft\Gdpr\Http\Requests\CookieConsentStatusRequest;
use Plugins\Sirsoft\Gdpr\Http\Requests\StoreCookieConsentRequest;
use Plugins\Sirsoft\Gdpr\Services\GdprConsentService;
@@ -24,7 +27,7 @@ class GdprCookieConsentController extends PublicBaseController
/**
* GdprCookieConsentController 생성자
*
* @param GdprConsentService $consentService GDPR 동의 서비스
* @param GdprConsentService $consentService GDPR 동의 서비스
*/
public function __construct(
private readonly GdprConsentService $consentService,
@@ -38,7 +41,7 @@ class GdprCookieConsentController extends PublicBaseController
* 회원이면 user_id 기반 status upsert + history INSERT,
* 게스트면 session_id 기반 history INSERT.
*
* @param StoreCookieConsentRequest $request 검증된 요청
* @param StoreCookieConsentRequest $request 검증된 요청
* @return JsonResponse
*/
public function store(StoreCookieConsentRequest $request): JsonResponse
@@ -90,10 +93,10 @@ class GdprCookieConsentController extends PublicBaseController
* 배너 표시 여부 결정용. has_consented = 현재 정책 버전으로 동의 완료 여부.
* 회원이 sanctum 토큰으로 호출하면 user_id 기반, 미인증이면 session_id 기반.
*
* @param \Illuminate\Http\Request $request 요청
* @param CookieConsentStatusRequest $request 요청
* @return JsonResponse
*/
public function status(\Illuminate\Http\Request $request): JsonResponse
public function status(CookieConsentStatusRequest $request): JsonResponse
{
$userId = $request->user()?->id;
$sessionId = $userId === null ? $this->resolveGuestSessionId($request) : null;
@@ -127,7 +130,7 @@ class GdprCookieConsentController extends PublicBaseController
* (위조된 값은 미식별 게스트로 취급). 쿠키가 없으면 Laravel session ID를
* fallback으로 사용합니다.
*
* @param \Illuminate\Http\Request $request 요청
* @param Request $request 요청
* @return string|null
*/
private function resolveGuestSessionId($request): ?string
@@ -153,7 +156,7 @@ class GdprCookieConsentController extends PublicBaseController
*/
private function issueGuestSessionId(): string
{
return (string) \Illuminate\Support\Str::uuid();
return (string) Str::uuid();
}
/**
@@ -162,8 +165,8 @@ class GdprCookieConsentController extends PublicBaseController
* 1년 유효, path=/, SameSite=Lax. HTTPS 환경에서는 Secure 자동 적용.
* 쿠키 값은 HMAC 서명이 붙어 위변조 시 서버가 거부합니다.
*
* @param JsonResponse $response 응답
* @param string $sessionId 발급된 세션 ID
* @param JsonResponse $response 응답
* @param string $sessionId 발급된 세션 ID
* @return void
*/
private function attachGuestSessionCookie(JsonResponse $response, string $sessionId): void
@@ -5,6 +5,7 @@ namespace Plugins\Sirsoft\Gdpr\Http\Controllers\User;
use App\Helpers\ResponseHelper;
use App\Http\Controllers\Api\Base\AuthBaseController;
use Illuminate\Http\JsonResponse;
use Plugins\Sirsoft\Gdpr\Enums\ConsentSource;
use Plugins\Sirsoft\Gdpr\Http\Requests\GrantConsentRequest;
use Plugins\Sirsoft\Gdpr\Http\Requests\RevokeConsentRequest;
use Plugins\Sirsoft\Gdpr\Http\Resources\GdprUserConsentHistoryResource;
@@ -23,7 +24,7 @@ class GdprConsentController extends AuthBaseController
/**
* GdprConsentController 생성자
*
* @param GdprConsentService $consentService GDPR 동의 서비스
* @param GdprConsentService $consentService GDPR 동의 서비스
*/
public function __construct(
private readonly GdprConsentService $consentService,
@@ -78,7 +79,7 @@ class GdprConsentController extends AuthBaseController
/**
* 본인 동의 철회.
*
* @param RevokeConsentRequest $request 검증된 요청
* @param RevokeConsentRequest $request 검증된 요청
* @return JsonResponse
*/
public function revoke(RevokeConsentRequest $request): JsonResponse
@@ -95,7 +96,7 @@ class GdprConsentController extends AuthBaseController
sessionId: null,
consentKey: $consentKey,
value: false,
source: 'mypage',
source: ConsentSource::Mypage->value,
);
return ResponseHelper::success('sirsoft-gdpr::messages.consent.revoked', [
@@ -109,7 +110,7 @@ class GdprConsentController extends AuthBaseController
* Art.7(3) 자유 변경권의 부여 방향 — 마이페이지 「내 동의 현황」 에서
* 「다시 동의」 / 「동의」 버튼 클릭 시 호출. 화이트리스트 검사는 FormRequest 가 수행.
*
* @param GrantConsentRequest $request 검증된 요청
* @param GrantConsentRequest $request 검증된 요청
* @return JsonResponse
*/
public function grant(GrantConsentRequest $request): JsonResponse
@@ -126,7 +127,7 @@ class GdprConsentController extends AuthBaseController
sessionId: null,
consentKey: $consentKey,
value: true,
source: 'mypage',
source: ConsentSource::Mypage->value,
);
return ResponseHelper::success('sirsoft-gdpr::messages.consent.granted_again', [
@@ -162,5 +163,4 @@ class GdprConsentController extends AuthBaseController
['renewed' => $renewed],
);
}
}
@@ -0,0 +1,34 @@
<?php
namespace Plugins\Sirsoft\Gdpr\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;
/**
* 현재 방문자의 쿠키 동의 상태 조회 요청을 검증합니다.
*
* 회원 식별은 optional.sanctum 미들웨어가, 게스트 식별은 쿠키/세션이 담당하므로 요청
* 파라미터를 읽지 않습니다.
*/
class CookieConsentStatusRequest extends FormRequest
{
/**
* 요청 권한 — 공개 엔드포인트이므로 true 고정.
*
* @return bool 항상 true
*/
public function authorize(): bool
{
return true;
}
/**
* 검증 규칙을 반환합니다.
*
* @return array<string, array<int, mixed>> 검증 규칙 (사용 파라미터 없음)
*/
public function rules(): array
{
return [];
}
}
@@ -0,0 +1,137 @@
<?php
namespace Plugins\Sirsoft\Gdpr\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
use Plugins\Sirsoft\Gdpr\Enums\ConsentAction;
use Plugins\Sirsoft\Gdpr\Enums\ConsentSource;
/**
* 관리자 동의 로그 목록 조회 요청을 검증합니다.
*
* 행위(`actions`)·출처(`sources`) 허용 어휘는 ConsentAction / ConsentSource enum 단일 출처에서
* 파생합니다 — 여기에 리터럴을 다시 적으면 화면 필터가 실제 기록 어휘의 부분집합이 되어
* 일부 행이 도달 불가해집니다(거부 이력이 그 형태로 조회 불가였습니다).
*/
class IndexConsentLogRequest extends FormRequest
{
/** 기본 페이지 크기 */
public const DEFAULT_PER_PAGE = 20;
/** 페이지 크기 상한 */
public const MAX_PER_PAGE = 100;
/**
* 배열로 받는 필터 키 목록.
*
* @var array<int, string>
*/
private const ARRAY_FILTERS = ['consent_keys', 'actions', 'sources'];
/**
* 요청 권한 — 라우트 permission 미들웨어가 담당하므로 true 고정.
*
* @return bool 항상 true
*/
public function authorize(): bool
{
return true;
}
/**
* 단일 값으로 도착한 배열 필터를 검증 전에 배열로 정규화합니다.
*
* `?sources[]=banner` 와 `?sources=banner` 를 모두 허용하기 위한 것으로, 정규화하지
* 않으면 후자가 `array` 규칙에 걸려 목록 전체가 422 가 됩니다.
*/
protected function prepareForValidation(): void
{
$normalized = [];
foreach (self::ARRAY_FILTERS as $key) {
if (! $this->has($key)) {
continue;
}
$value = $this->input($key);
if (is_array($value)) {
continue;
}
$normalized[$key] = ($value === null || $value === '') ? [] : [(string) $value];
}
if ($normalized !== []) {
$this->merge($normalized);
}
}
/**
* 검증 규칙을 반환합니다.
*
* @return array<string, array<int, mixed>> 검증 규칙
*/
public function rules(): array
{
return [
'email' => ['nullable', 'string', 'max:255'],
'session_id' => ['nullable', 'string', 'max:100'],
'consent_keys' => ['nullable', 'array'],
'consent_keys.*' => ['string', 'max:100'],
'actions' => ['nullable', 'array'],
'actions.*' => ['string', Rule::in(ConsentAction::allValues())],
'sources' => ['nullable', 'array'],
'sources.*' => ['string', Rule::in(ConsentSource::allValues())],
// 상·하한은 규칙이 아니라 접근자에서 클램프한다 — 기존 컨트롤러가 범위를 벗어난
// per_page 를 거부하지 않고 조정해 응답하던 계약을 유지한다.
'per_page' => ['nullable', 'integer'],
];
}
/**
* 목록 필터를 반환합니다.
*
* @return array<string, mixed> 필터 배열 (배열 필터는 항상 배열)
*/
public function filters(): array
{
return [
'email' => $this->validated('email'),
'session_id' => $this->validated('session_id'),
'consent_keys' => $this->arrayFilter('consent_keys'),
'actions' => $this->arrayFilter('actions'),
'sources' => $this->arrayFilter('sources'),
];
}
/**
* 페이지 크기를 반환합니다.
*
* @return int 페이지 크기 (1 ~ 상한으로 클램프)
*/
public function perPage(): int
{
$perPage = (int) ($this->validated('per_page') ?? self::DEFAULT_PER_PAGE);
return max(1, min(self::MAX_PER_PAGE, $perPage));
}
/**
* 배열 필터에서 빈 값을 제거해 반환합니다.
*
* @param string $key 필터 키
* @return array<int, string> 정규화된 값 목록
*/
private function arrayFilter(string $key): array
{
/** @var array<int, string> $values */
$values = $this->validated($key) ?? [];
return array_values(array_filter(
array_map('strval', $values),
fn (string $value) => $value !== ''
));
}
}
@@ -0,0 +1,53 @@
<?php
namespace Plugins\Sirsoft\Gdpr\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;
/**
* 관리자 정책 버전 이력 목록 조회 요청을 검증합니다.
*/
class IndexPolicyVersionRequest extends FormRequest
{
/** 기본 페이지 크기 */
public const DEFAULT_PER_PAGE = 20;
/** 페이지 크기 상한 */
public const MAX_PER_PAGE = 100;
/**
* 요청 권한 — 라우트 permission 미들웨어가 담당하므로 true 고정.
*
* @return bool 항상 true
*/
public function authorize(): bool
{
return true;
}
/**
* 검증 규칙을 반환합니다.
*
* @return array<string, array<int, mixed>> 검증 규칙
*/
public function rules(): array
{
// 상·하한은 규칙이 아니라 접근자에서 클램프한다 — 기존 컨트롤러가 범위를 벗어난
// per_page 를 거부하지 않고 조정해 응답하던 계약을 유지한다.
return [
'per_page' => ['nullable', 'integer'],
];
}
/**
* 페이지 크기를 반환합니다.
*
* @return int 페이지 크기 (1 ~ 상한으로 클램프)
*/
public function perPage(): int
{
$perPage = (int) ($this->validated('per_page') ?? self::DEFAULT_PER_PAGE);
return max(1, min(self::MAX_PER_PAGE, $perPage));
}
}
@@ -3,6 +3,9 @@
namespace Plugins\Sirsoft\Gdpr\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
use Illuminate\Validation\Validator;
use Plugins\Sirsoft\Gdpr\Enums\ConsentSource;
use Plugins\Sirsoft\Gdpr\Services\CookieCategoryService;
/**
@@ -18,7 +21,7 @@ class StoreCookieConsentRequest extends FormRequest
/**
* StoreCookieConsentRequest 생성자
*
* @param CookieCategoryService $categoryService 쿠키 카테고리 설정 서비스
* @param CookieCategoryService $categoryService 쿠키 카테고리 설정 서비스
*/
public function __construct(private readonly CookieCategoryService $categoryService)
{
@@ -45,7 +48,8 @@ class StoreCookieConsentRequest extends FormRequest
return [
'consents' => ['required', 'array', 'min:1'],
'consents.*' => ['required', 'boolean'],
'source' => ['required', 'string', 'in:banner,preference_center,register,mypage'],
// 허용 어휘의 SSoT 는 ConsentSource enum 이다 (화면 필터·라벨도 같은 목록에서 파생)
'source' => ['required', 'string', Rule::in(ConsentSource::requestSelectableValues())],
// 명시적 거부 신호 (이슈 #430). 배너 "동의하지 않고 계속하기" 버튼이 전송.
// 미전송(null) 시 일반 저장(기존 동작). 값은 'reject' 만 허용.
'intent' => ['sometimes', 'nullable', 'string', 'in:reject'],
@@ -71,12 +75,12 @@ class StoreCookieConsentRequest extends FormRequest
/**
* 검증 후 동의 키 화이트리스트 + 필수 항목 false 차단.
*
* @param \Illuminate\Validation\Validator $validator
* @param Validator $validator
* @return void
*/
public function withValidator(\Illuminate\Validation\Validator $validator): void
public function withValidator(Validator $validator): void
{
$validator->after(function (\Illuminate\Validation\Validator $validator) {
$validator->after(function (Validator $validator) {
$consents = (array) $this->input('consents', []);
$allowedKeys = $this->categoryService->getAllConsentKeys();
@@ -4,6 +4,7 @@ namespace Plugins\Sirsoft\Gdpr\Listeners;
use App\Contracts\Extension\HookListenerInterface;
use App\Models\User;
use Plugins\Sirsoft\Gdpr\Enums\ConsentSource;
use Plugins\Sirsoft\Gdpr\Services\CookieCategoryService;
use Plugins\Sirsoft\Gdpr\Services\GdprConsentService;
@@ -29,8 +30,8 @@ class GdprAuthConsentListener implements HookListenerInterface
/**
* GdprAuthConsentListener 생성자
*
* @param GdprConsentService $consentService 동의 서비스
* @param CookieCategoryService $categoryService 쿠키 카테고리 서비스 (키 화이트리스트)
* @param GdprConsentService $consentService 동의 서비스
* @param CookieCategoryService $categoryService 쿠키 카테고리 서비스 (키 화이트리스트)
*/
public function __construct(
private readonly GdprConsentService $consentService,
@@ -58,7 +59,7 @@ class GdprAuthConsentListener implements HookListenerInterface
/**
* 인터페이스 요구 메서드.
*
* @param mixed ...$args
* @param mixed ...$args
* @return void
*/
public function handle(...$args): void
@@ -69,10 +70,10 @@ class GdprAuthConsentListener implements HookListenerInterface
/**
* 회원가입 시 폼 데이터에서 GDPR 쿠키 동의를 추출하여 기록.
*
* @param User $user 가입 완료된 사용자
* @param array $data 요청 데이터
* @param string|null $agreedAt ISO8601 문자열 동의 일시 (코어 AuthService 가 toIso8601String 으로 직렬화 후 전달, 현재 미사용)
* @param string|null $ip IP 주소 (현재 미사용, Service 가 request()->ip() 직접 사용)
* @param User $user 가입 완료된 사용자
* @param array $data 요청 데이터
* @param string|null $agreedAt ISO8601 문자열 동의 일시 (코어 AuthService 가 toIso8601String 으로 직렬화 후 전달, 현재 미사용)
* @param string|null $ip IP 주소 (현재 미사용, Service 가 request()->ip() 직접 사용)
* @return void
*/
public function recordRegisterConsents(User $user, array $data, ?string $agreedAt = null, ?string $ip = null): void
@@ -88,7 +89,7 @@ class GdprAuthConsentListener implements HookListenerInterface
userId: $user->id,
sessionId: null,
consents: $consents,
source: 'register',
source: ConsentSource::Register->value,
);
}
@@ -99,8 +100,8 @@ class GdprAuthConsentListener implements HookListenerInterface
* - agree_cookie_analytics (sirsoft-marketing 컨벤션)
* - cookie_analytics (직접)
*
* @param array $data 요청 데이터
* @param array<int, string> $allowedKeys 허용된 동의 키 목록
* @param array $data 요청 데이터
* @param array<int, string> $allowedKeys 허용된 동의 키 목록
* @return array<string, bool> [consent_key => bool]
*/
private function extractConsents(array $data, array $allowedKeys): array
@@ -20,6 +20,8 @@ class GdprPolicyVersionRepository implements GdprPolicyVersionRepositoryInterfac
{
return GdprPolicyVersion::query()
->orderByDesc('version')
// 전순서 보장 — version 이 유니크하더라도 정렬 계약을 키로 닫아 둔다
->orderByDesc('id')
->first();
}
@@ -62,6 +64,8 @@ class GdprPolicyVersionRepository implements GdprPolicyVersionRepositoryInterfac
return GdprPolicyVersion::query()
->with('createdBy')
->orderByDesc('version')
// 전순서 보장 — version 이 유니크하더라도 정렬 계약을 키로 닫아 둔다
->orderByDesc('id')
// audit:allow repository-paginate-column-pruning reason: 발행 이력은 정책 변경 시에만
// 늘어나는 정의성 테이블이라 깊은 OFFSET 이 성립하지 않는다. 넓은 컬럼(snapshot JSON)은
// 아래 컬럼 목록에서 제외했고, 본문은 상세 조회(getByVersion)에서만 읽는다.
@@ -7,6 +7,7 @@ use App\Services\PluginSettingsService;
use Illuminate\Support\Collection;
use Illuminate\Support\Facades\DB;
use Plugins\Sirsoft\Gdpr\Enums\ConsentAction;
use Plugins\Sirsoft\Gdpr\Enums\ConsentSource;
use Plugins\Sirsoft\Gdpr\Models\GdprUserConsent;
use Plugins\Sirsoft\Gdpr\Models\GdprUserConsentHistory;
use Plugins\Sirsoft\Gdpr\Repositories\Contracts\GdprUserConsentHistoryRepositoryInterface;
@@ -28,11 +29,11 @@ class GdprConsentService
/**
* GdprConsentService 생성자
*
* @param GdprUserConsentRepositoryInterface $statusRepository 동의 상태 Repository
* @param GdprUserConsentHistoryRepositoryInterface $historyRepository 동의 이력 Repository
* @param PluginSettingsService $pluginSettings 플러그인 설정 서비스
* @param CookieCategoryService $categoryService 쿠키 카테고리 카탈로그 서비스
* @param GdprPolicyVersionService|null $policyVersionService 정책 버전 서비스 — null 인 경우 lazy resolve (테스트 호환성)
* @param GdprUserConsentRepositoryInterface $statusRepository 동의 상태 Repository
* @param GdprUserConsentHistoryRepositoryInterface $historyRepository 동의 이력 Repository
* @param PluginSettingsService $pluginSettings 플러그인 설정 서비스
* @param CookieCategoryService $categoryService 쿠키 카테고리 카탈로그 서비스
* @param GdprPolicyVersionService|null $policyVersionService 정책 버전 서비스 — null 인 경우 lazy resolve (테스트 호환성)
*/
public function __construct(
private readonly GdprUserConsentRepositoryInterface $statusRepository,
@@ -68,13 +69,13 @@ class GdprConsentService
* 게스트: history만 INSERT (status 미사용).
* 동일 상태 재요청은 noop으로 처리하여 중복 이력 방지.
*
* @param int|null $userId 회원 ID (게스트면 NULL)
* @param string|null $sessionId 게스트 세션 ID (회원이면 NULL)
* @param string $consentKey 동의 항목 키
* @param bool $value 동의 여부
* @param string $source 변경 경로 (banner/preference_center/register/mypage/order/withdraw)
* @param array|null $categories 카테고리 스냅샷 (배너 일괄 변경 시)
* @param bool $isRejection 명시적 거부 신호 (이슈 #430). 선택형 미동의 항목을 is_rejected=true 로 저장.
* @param int|null $userId 회원 ID (게스트면 NULL)
* @param string|null $sessionId 게스트 세션 ID (회원이면 NULL)
* @param string $consentKey 동의 항목 키
* @param bool $value 동의 여부
* @param string $source 변경 경로 (허용 어휘는 ConsentSource enum — banner/preference_center/register/mypage/mypage_renew_all)
* @param array|null $categories 카테고리 스냅샷 (배너 일괄 변경 시)
* @param bool $isRejection 명시적 거부 신호 (이슈 #430). 선택형 미동의 항목을 is_rejected=true 로 저장.
* @return void
*/
public function updateConsent(
@@ -136,8 +137,8 @@ class GdprConsentService
$data['consent_count'] = ($existing?->consent_count ?? 0) + 1;
}
HookManager::doAction(self::PLUGIN_ID . '.consent.before_update', $userId, $consentKey, $data);
$data = HookManager::applyFilters(self::PLUGIN_ID . '.consent.filter_update_data', $data, $userId, $consentKey);
HookManager::doAction(self::PLUGIN_ID.'.consent.before_update', $userId, $consentKey, $data);
$data = HookManager::applyFilters(self::PLUGIN_ID.'.consent.filter_update_data', $data, $userId, $consentKey);
$consent = $this->statusRepository->upsert($userId, $consentKey, $data);
}
@@ -166,19 +167,19 @@ class GdprConsentService
}
$hookName = $value
? self::PLUGIN_ID . '.consent.granted'
: self::PLUGIN_ID . '.consent.revoked';
? self::PLUGIN_ID.'.consent.granted'
: self::PLUGIN_ID.'.consent.revoked';
HookManager::doAction($hookName, $consent, $source);
}
/**
* 여러 동의 항목을 일괄 업데이트합니다.
*
* @param int|null $userId 회원 ID
* @param string|null $sessionId 게스트 세션 ID
* @param array<string, bool> $consents 동의 데이터 [key => bool]
* @param string $source 변경 경로
* @param bool $isRejection 명시적 거부 신호 (이슈 #430). 선택형 미동의 항목을 is_rejected=true 로 저장.
* @param int|null $userId 회원 ID
* @param string|null $sessionId 게스트 세션 ID
* @param array<string, bool> $consents 동의 데이터 [key => bool]
* @param string $source 변경 경로
* @param bool $isRejection 명시적 거부 신호 (이슈 #430). 선택형 미동의 항목을 is_rejected=true 로 저장.
* @return void
*/
public function updateConsents(?int $userId, ?string $sessionId, array $consents, string $source, bool $isRejection = false): void
@@ -195,7 +196,7 @@ class GdprConsentService
*
* 로그인 후 클라이언트 동기화에 사용됩니다.
*
* @param int $userId 회원 ID
* @param int $userId 회원 ID
* @return Collection<int, GdprUserConsent>
*/
public function getActiveConsents(int $userId): Collection
@@ -215,7 +216,7 @@ class GdprConsentService
* (consent_count=0, is_consented=false)
* - 카탈로그에 없는 status row (예: 운영자가 카테고리 삭제) → 결과에서 제외 (UI 노출 부적합)
*
* @param int $userId 회원 ID
* @param int $userId 회원 ID
* @return Collection<int, GdprUserConsent>
*/
public function getMyConsentMatrix(int $userId): Collection
@@ -230,7 +231,7 @@ class GdprConsentService
continue;
}
$consentKey = 'cookie_' . $bareKey;
$consentKey = 'cookie_'.$bareKey;
if ($statusByKey->has($consentKey)) {
$rows->push($statusByKey->get($consentKey));
@@ -251,7 +252,7 @@ class GdprConsentService
/**
* 회원의 모든 동의 상태를 반환합니다 (활성·철회 포함).
*
* @param int $userId 회원 ID
* @param int $userId 회원 ID
* @return Collection<int, GdprUserConsent>
*/
public function getAllConsents(int $userId): Collection
@@ -262,7 +263,7 @@ class GdprConsentService
/**
* 회원의 동의 이력을 반환합니다.
*
* @param int $userId 회원 ID
* @param int $userId 회원 ID
* @return Collection<int, GdprUserConsentHistory>
*/
public function getHistories(int $userId): Collection
@@ -273,7 +274,7 @@ class GdprConsentService
/**
* 게스트 세션의 동의 이력을 반환합니다.
*
* @param string $sessionId 게스트 세션 ID
* @param string $sessionId 게스트 세션 ID
* @return Collection<int, GdprUserConsentHistory>
*/
public function getGuestHistories(string $sessionId): Collection
@@ -287,7 +288,7 @@ class GdprConsentService
* status 테이블의 is_consented=true 행을 false로 UPDATE +
* 각 항목별 history에 source=withdraw로 revoked 행 INSERT.
*
* @param int $userId 회원 ID
* @param int $userId 회원 ID
* @return void
*/
public function revokeAllOnWithdraw(int $userId): void
@@ -306,7 +307,7 @@ class GdprConsentService
* history 테이블은 user_id·ip_address·user_agent를 NULL로 익명화하여
* 감사 추적용 행을 보존합니다 (GDPR Art.17 + Art.7(1) 양립).
*
* @param int $userId 회원 ID
* @param int $userId 회원 ID
* @return void
*/
public function purgeOnUserDelete(int $userId): void
@@ -320,7 +321,7 @@ class GdprConsentService
*
* 회원의 가장 최근 동의가 현재 정책 버전과 다르면 재동의 트리거 대상.
*
* @param int $userId 회원 ID
* @param int $userId 회원 ID
* @return bool 재동의 필요 여부
*/
public function needsRenewal(int $userId): bool
@@ -362,7 +363,7 @@ class GdprConsentService
* - 활성 + 옛 버전 → policy_version = current, last_source = 'mypage_renew_all'
* - 각 갱신 행마다 history append (action=granted, source=mypage_renew_all) — Art.7(1) 입증 트레일
*
* @param int $userId 회원 ID
* @param int $userId 회원 ID
* @return int 갱신된 동의 행 수
*/
public function renewAllForCurrentPolicy(int $userId): int
@@ -392,13 +393,13 @@ class GdprConsentService
$data = [
'is_consented' => true,
'policy_version' => $current,
'last_source' => 'mypage_renew_all',
'last_source' => ConsentSource::MypageRenewAll->value,
'consent_category' => $this->resolveCategory($consentKey),
'consent_count' => (int) $consent->consent_count + 1,
];
HookManager::doAction(self::PLUGIN_ID . '.consent.before_update', $userId, $consentKey, $data);
$data = HookManager::applyFilters(self::PLUGIN_ID . '.consent.filter_update_data', $data, $userId, $consentKey);
HookManager::doAction(self::PLUGIN_ID.'.consent.before_update', $userId, $consentKey, $data);
$data = HookManager::applyFilters(self::PLUGIN_ID.'.consent.filter_update_data', $data, $userId, $consentKey);
$updated = $this->statusRepository->upsert($userId, $consentKey, $data);
@@ -407,14 +408,14 @@ class GdprConsentService
'session_id' => null,
'consent_key' => $consentKey,
'action' => 'granted',
'source' => 'mypage_renew_all',
'source' => ConsentSource::MypageRenewAll->value,
'policy_version' => $current,
'categories' => $this->buildCategoriesSnapshotForUser($userId),
'ip_address' => request()->ip(),
'user_agent' => substr((string) request()->userAgent(), 0, 500),
]);
HookManager::doAction(self::PLUGIN_ID . '.consent.granted', $updated, 'mypage_renew_all');
HookManager::doAction(self::PLUGIN_ID.'.consent.granted', $updated, ConsentSource::MypageRenewAll->value);
$renewed++;
}
@@ -429,8 +430,8 @@ class GdprConsentService
* 회원: status 테이블에서 cookie_ 접두사 동의 중 정책 버전 일치하는 항목이 1개 이상이면 동의 완료.
* 게스트: history 의 가장 최근 항목 중 정책 버전 일치하는 cookie_ 접두사 동의가 1개 이상이면 동의 완료.
*
* @param int|null $userId 회원 ID (게스트면 NULL)
* @param string|null $sessionId 게스트 세션 ID (회원이면 NULL)
* @param int|null $userId 회원 ID (게스트면 NULL)
* @param string|null $sessionId 게스트 세션 ID (회원이면 NULL)
* @return bool 현재 정책 버전으로 동의 완료 여부
*/
public function hasCurrentCookieConsent(?int $userId, ?string $sessionId): bool
@@ -474,8 +475,8 @@ class GdprConsentService
* 회원: status 테이블에서 cookie_ 접두사 1건 이상 → true
* 게스트: history 테이블에서 session_id + cookie_ 접두사 1건 이상 → true
*
* @param int|null $userId 회원 ID (게스트면 NULL)
* @param string|null $sessionId 게스트 세션 ID (회원이면 NULL)
* @param int|null $userId 회원 ID (게스트면 NULL)
* @param string|null $sessionId 게스트 세션 ID (회원이면 NULL)
* @return bool 동의 이력 존재 여부
*/
public function hasAnyConsentHistory(?int $userId, ?string $sessionId): bool
@@ -515,8 +516,8 @@ class GdprConsentService
* 회원: status 테이블의 cookie_ 접두사 + 정책 버전 일치 행을 카테고리별로 매핑.
* 게스트: history 의 정책 버전 일치 cookie_ 접두사 항목 중 가장 최근 action 을 사용.
*
* @param int|null $userId 회원 ID (게스트면 NULL)
* @param string|null $sessionId 게스트 세션 ID (회원이면 NULL)
* @param int|null $userId 회원 ID (게스트면 NULL)
* @param string|null $sessionId 게스트 세션 ID (회원이면 NULL)
* @return array<string, bool> 카테고리 키 → 동의 여부 (예: ['necessary' => true, 'analytics' => false])
*/
public function getCurrentCookieConsents(?int $userId, ?string $sessionId): array
@@ -571,7 +572,7 @@ class GdprConsentService
/**
* consent_key로부터 category 분류를 추정합니다.
*
* @param string $consentKey 동의 항목 키
* @param string $consentKey 동의 항목 키
* @return string|null
*/
private function resolveCategory(string $consentKey): ?string
@@ -592,7 +593,7 @@ class GdprConsentService
*
* 동의 row 가 한 건도 없는 회원은 null 반환 — history.categories null 과 동일 의미.
*
* @param int $userId 회원 ID
* @param int $userId 회원 ID
* @return array<string, bool>|null 카테고리 키 → 동의 여부 매트릭스
*/
private function buildCategoriesSnapshotForUser(int $userId): ?array
@@ -0,0 +1,182 @@
<?php
namespace Plugins\Sirsoft\Gdpr\Tests\Unit;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;
use Plugins\Sirsoft\Gdpr\Enums\ConsentSource;
/**
* 동의 출처 어휘 3계층 정합 가드
*
* 불변식: **기록 어휘(ConsentSource) = 화면 필터 옵션 = 라벨 키**
*
* 어긋나면 두 가지가 동시에 깨집니다 (#492 브라우저 실측에서 확인된 결함 D-35):
* - 화면 필터에 없는 출처로 기록된 행은 어떤 필터 조합으로도 도달할 수 없다 (60행 중 20행)
* - 라벨 키가 없는 출처는 목록 셀에 원시 키 문자열이 그대로 노출된다
*
* DB·라우트에 의존하지 않는 정적 검사이므로 `Tests\TestCase` 가 아니라 순수 TestCase 를 상속합니다.
*/
class ConsentSourceVocabularyParityTest extends TestCase
{
/** 플러그인 루트 경로 */
private function pluginPath(string $relative): string
{
return dirname(__DIR__, 2).'/'.$relative;
}
/**
* 소스 코드가 실제로 기록하는 출처 값이 모두 enum 에 선언되어 있는지 검사합니다.
*
* enum 밖에 리터럴을 두면 화면·라벨이 그 값을 영영 모릅니다.
*/
#[Test]
public function 기록_경로의_출처_값이_전부_enum_에_선언되어_있다(): void
{
$declared = ConsentSource::allValues();
// 실제 기록 지점 — source:/'source' =>/'last_source' => 인자로 넘어가는 리터럴
$sources = [
'src/Listeners/GdprAuthConsentListener.php',
'src/Services/GdprConsentService.php',
'src/Http/Controllers/User/GdprConsentController.php',
];
$literals = [];
foreach ($sources as $relative) {
$code = file_get_contents($this->pluginPath($relative));
// 기록 지점이 enum 을 참조하고 있어야 한다 — 리터럴로 되돌아가면 화면·라벨이 그 값을 모른다
$this->assertStringContainsString(
'ConsentSource::',
$code,
"{$relative} 이 출처를 enum 이 아닌 값으로 기록합니다."
);
preg_match_all("/(?:source:|'source'\s*=>|'last_source'\s*=>)\s*'([a-z_]+)'/", $code, $m);
$literals = array_merge($literals, $m[1]);
}
foreach (array_unique($literals) as $literal) {
$this->assertContains(
$literal,
$declared,
"기록 경로가 enum 에 없는 출처 '{$literal}' 를 저장합니다 — ConsentSource 에 케이스를 추가하세요."
);
}
}
/**
* 관리자 동의 이력 화면의 출처 필터 옵션이 enum 전 케이스를 덮는지 검사합니다.
*/
#[Test]
public function 화면_출처_필터_옵션이_enum_전_케이스를_덮는다(): void
{
$layout = file_get_contents(
$this->pluginPath('resources/layouts/admin/gdpr_consent_log.json')
);
foreach (ConsentSource::allValues() as $value) {
$this->assertStringContainsString(
"includes('{$value}')",
$layout,
"출처 필터에 '{$value}' 체크박스가 없습니다 — 그 출처로 기록된 행은 어떤 필터로도 도달할 수 없습니다."
);
$this->assertStringContainsString(
"consent_log.source.{$value}",
$layout,
"출처 필터 '{$value}' 의 라벨 바인딩이 없습니다."
);
}
}
/**
* 모든 출처 값에 ko/en 라벨이 정의되어 있는지 검사합니다.
*
* 백엔드(`lang/{locale}/messages.php`)와 프론트엔드(`resources/lang/{locale}.json`)를
* **둘 다** 봅니다. 관리자 화면의 `$t:` 는 프론트엔드 JSON 에서 해석되므로 PHP 쪽만
* 채우면 화면에는 여전히 원시 키가 남습니다 (#492 7차에서 실제로 겪은 누락).
*/
#[Test]
public function 모든_출처_값에_ko_en_라벨이_정의되어_있다(): void
{
foreach (['ko', 'en'] as $locale) {
$backend = require $this->pluginPath("lang/{$locale}/messages.php");
$frontend = json_decode(
file_get_contents($this->pluginPath("resources/lang/{$locale}.json")),
true
);
$surfaces = [
"lang/{$locale}/messages.php" => $backend['admin']['consent_log']['source'] ?? [],
"resources/lang/{$locale}.json" => $frontend['admin']['consent_log']['source'] ?? [],
];
foreach ($surfaces as $where => $labels) {
foreach (ConsentSource::allValues() as $value) {
$this->assertArrayHasKey(
$value,
$labels,
"{$where} 에 출처 '{$value}' 라벨이 없습니다 — 목록 셀에 원시 키가 노출됩니다."
);
$this->assertNotSame('', trim((string) $labels[$value]));
}
}
}
}
/**
* 정책 버전 이력 페이저가 쓰는 다국어 키가 양쪽 표면에 모두 정의되어 있는지 검사합니다.
*/
#[Test]
public function 정책_버전_이력_페이저_라벨이_양쪽_표면에_있다(): void
{
$keys = ['history_page_summary', 'history_prev', 'history_next'];
foreach (['ko', 'en'] as $locale) {
$backend = require $this->pluginPath("lang/{$locale}/messages.php");
$frontend = json_decode(
file_get_contents($this->pluginPath("resources/lang/{$locale}.json")),
true
);
$surfaces = [
"lang/{$locale}/messages.php" => $backend['settings']['policy_version'] ?? [],
"resources/lang/{$locale}.json" => $frontend['settings']['policy_version'] ?? [],
];
foreach ($surfaces as $where => $labels) {
foreach ($keys as $key) {
$this->assertArrayHasKey($key, $labels, "{$where} 에 '{$key}' 가 없습니다.");
}
}
// 치환 문법이 표면마다 다르다 — 백엔드(Laravel)는 `:name`, 프론트 엔진은 `{name}` 만 치환한다.
// 뒤바꿔 적으면 키는 해석되지만 숫자가 자리표시자 그대로 화면에 남는다.
foreach (['total', 'current', 'last'] as $param) {
$this->assertStringContainsString(
':'.$param,
(string) ($backend['settings']['policy_version']['history_page_summary'] ?? ''),
"lang/{$locale}/messages.php 는 Laravel 문법 ':{$param}' 을 써야 합니다."
);
$this->assertStringContainsString(
'{'.$param.'}',
(string) ($frontend['settings']['policy_version']['history_page_summary'] ?? ''),
"resources/lang/{$locale}.json 은 프론트 엔진 문법 '{{$param}}' 을 써야 합니다 — ':{$param}' 는 치환되지 않고 그대로 노출됩니다."
);
}
}
}
/**
* 공개 요청으로 지정 가능한 출처는 서버 자체 기록 경로를 포함하지 않아야 합니다.
*/
#[Test]
public function 서버_자체_기록_출처는_요청으로_지정할_수_없다(): void
{
$selectable = ConsentSource::requestSelectableValues();
$this->assertNotContains(ConsentSource::MypageRenewAll->value, $selectable);
$this->assertContains(ConsentSource::Banner->value, $selectable);
}
}
@@ -4,12 +4,13 @@ All notable changes to this plugin will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
## [1.0.2] - 2026-07-29
## [1.0.2] - 2026-08-01
### Changed
- 코어 최소 요구 버전을 7.0.6 으로 상향했습니다. 운영 모드 전환 시 라이브 자격증명을 필수로 검사하는 기능이 코어 7.0.6 의 설정 저장 검증 표면을 사용합니다. 그보다 낮은 코어에서는 이 검사가 동작하지 않아 라이브 모드를 빈 자격증명으로 저장할 수 있으므로, 플러그인을 업데이트하기 전에 코어를 7.0.6 이상으로 먼저 업데이트해 주세요.
- 설정 화면의 중복 가입 관련 항목 이름을 「중복체크 기준」·「중복 가입 차단」으로 통일했습니다. 같은 화면에 다른 본인확인 수단의 카드가 함께 놓일 때 용어가 갈리지 않도록 맞췄습니다.
- 본인인증 팝업의 결과 전달 페이지가 주소로 전달받은 값의 형태를 먼저 확인하도록 정비했습니다. 정상 인증 흐름은 그대로이며, 주소를 임의로 조작해 들어오는 요청이 결과 페이지 안으로 흘러들지 않습니다.
### Fixed
@@ -105,3 +105,46 @@ Authorization: Bearer {YOUR_TOKEN}
```
---
## 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`
**요청 파라미터**
| 이름 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| verification_token | string | 아니오 | 인증 성공 시 코어가 발급한 검증 토큰 |
| challenge_id | string | 아니오 | 인증 시도 식별자 |
| identity_error | string | 아니오 | 인증 실패 사유 키 |
길이 상한을 두지 않는다 — 토큰 길이는 코어 발급 정책에 종속되므로, 여기서 상한을 정하면 정책이
바뀔 때 사용자가 팝업 안에서 오류 화면을 보게 된다.
**응답**: `200 text/html` — 데스크톱(`window.opener` 존재)은 부모창에 `postMessage` 후 창을 닫고,
모바일은 `sessionStorage` 의 redirectStash 를 복원해 원래 페이지로 이동한다.
@@ -4,7 +4,7 @@ namespace Plugins\Sirsoft\VerificationKginicis\Http\Controllers;
use App\Http\Controllers\Api\Base\PublicBaseController;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Plugins\Sirsoft\VerificationKginicis\Http\Requests\InicisCallbackRequest;
use Plugins\Sirsoft\VerificationKginicis\Services\InicisCallbackResolver;
/**
@@ -15,8 +15,9 @@ use Plugins\Sirsoft\VerificationKginicis\Services\InicisCallbackResolver;
* 본 컨트롤러는 InicisCallbackResolver Service 에 비즈니스 로직을 위임하고, 결과를
* popup-bridge 페이지로 302 redirect 한다.
*
* FormRequest 미사용 사유: 외부 PG 가 보내는 임의 필드를 strict validation 으로 차단하면
* 이니시스 응답을 받을 수 없다. 본 컨트롤러는 raw form POST 를 그대로 Resolver 에 전달.
* 검증 규칙을 두지 않는 사유: 외부 PG 가 보내는 임의 필드를 strict validation 으로 차단하면
* 이니시스 응답을 받을 수 없다. 본 컨트롤러는 raw form POST 를 그대로 Resolver 에 전달하며,
* 그 결정을 InicisCallbackRequest (빈 규칙) 로 명시한다.
*
* @since 1.0.0-beta.1
*/
@@ -34,10 +35,10 @@ class InicisCallbackController extends PublicBaseController
/**
* 이니시스 콜백 수신 + Resolver 위임 + bridge 페이지로 302 redirect.
*
* @param Request $request 이니시스 form POST body
* @param InicisCallbackRequest $request 이니시스 form POST body
* @return RedirectResponse
*/
public function handle(Request $request): RedirectResponse
public function handle(InicisCallbackRequest $request): RedirectResponse
{
$outcome = $this->resolver->resolve(
callbackInput: $request->all(),
@@ -3,8 +3,8 @@
namespace Plugins\Sirsoft\VerificationKginicis\Http\Controllers;
use App\Http\Controllers\Api\Base\PublicBaseController;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Plugins\Sirsoft\VerificationKginicis\Http\Requests\InicisPopupBridgeRequest;
/**
* 이니시스 매뉴얼 STEP4 결과 전달 페이지 — 데스크톱 팝업 / 모바일 redirect 분기.
@@ -30,16 +30,15 @@ class InicisPopupBridgeController extends PublicBaseController
/**
* Bridge 페이지를 렌더링한다.
*
* @param Request $request callback 컨트롤러가 전달한 query (verification_token / challenge_id / identity_error)
* @param InicisPopupBridgeRequest $request callback 컨트롤러가 전달한 query (verification_token / challenge_id / identity_error)
* @return Response
*/
public function show(Request $request): Response
public function show(InicisPopupBridgeRequest $request): Response
{
$payloadJson = json_encode([
'verification_token' => (string) $request->query('verification_token', ''),
'challenge_id' => (string) $request->query('challenge_id', ''),
'identity_error' => (string) $request->query('identity_error', ''),
], JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_UNESCAPED_UNICODE);
$payloadJson = json_encode(
$request->bridgePayload(),
JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_UNESCAPED_UNICODE
);
return $this->htmlResponse($this->renderBridgeHtml($payloadJson));
}
@@ -0,0 +1,39 @@
<?php
namespace Plugins\Sirsoft\VerificationKginicis\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;
/**
* 이니시스 매뉴얼 STEP2 콜백 본문을 수신합니다.
*
* 규칙이 비어 있는 이유: 이니시스는 매뉴얼에 명시되지 않은 필드를 함께 보내며 그 목록이
* 가맹점 설정·인증 수단에 따라 달라집니다. 여기서 화이트리스트를 닫으면 정상 콜백이 422 로
* 거부되어 인증이 끊깁니다. 콜백 본문의 의미 검증(서명·거래 대조·challenge 해석)은
* `InicisCallbackResolver` 가 단독으로 담당합니다.
*
* base `Request` 대신 이 클래스를 두는 것은, "검증하지 않는다" 가 누락이 아니라 결정임을
* 코드에 남기기 위해서입니다.
*/
class InicisCallbackRequest extends FormRequest
{
/**
* 요청 권한 — 외부 PG 가 호출하는 공개 콜백이므로 true 고정.
*
* @return bool 항상 true
*/
public function authorize(): bool
{
return true;
}
/**
* 검증 규칙을 반환합니다.
*
* @return array<string, array<int, mixed>> 빈 규칙 (사유는 클래스 설명 참조)
*/
public function rules(): array
{
return [];
}
}
@@ -0,0 +1,53 @@
<?php
namespace Plugins\Sirsoft\VerificationKginicis\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;
/**
* 이니시스 매뉴얼 STEP4 bridge 페이지 진입 쿼리를 검증합니다.
*
* 콜백 컨트롤러가 302 redirect 로 붙여 보내는 세 값만 받습니다. 길이 상한을 두지 않는 이유는
* 토큰 길이가 코어 발급 정책에 종속되어 있어, 여기서 상한을 정하면 정책 변경 시 사용자가
* 팝업 안에서 JSON 오류를 보게 되기 때문입니다.
*/
class InicisPopupBridgeRequest extends FormRequest
{
/**
* 요청 권한 — PG 인증 후 사용자 브라우저가 진입하는 공개 페이지이므로 true 고정.
*
* @return bool 항상 true
*/
public function authorize(): bool
{
return true;
}
/**
* 검증 규칙을 반환합니다.
*
* @return array<string, array<int, mixed>> 검증 규칙
*/
public function rules(): array
{
return [
'verification_token' => ['nullable', 'string'],
'challenge_id' => ['nullable', 'string'],
'identity_error' => ['nullable', 'string'],
];
}
/**
* bridge 스크립트에 전달할 payload 를 반환합니다.
*
* @return array<string, string> 세 값 (미지정은 빈 문자열)
*/
public function bridgePayload(): array
{
return [
'verification_token' => (string) ($this->validated('verification_token') ?? ''),
'challenge_id' => (string) ($this->validated('challenge_id') ?? ''),
'identity_error' => (string) ($this->validated('identity_error') ?? ''),
];
}
}