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 를 편입했다.
4.1 KiB
GDPR (일반 데이터 보호 규정) — 프론트엔드
레이아웃·액션 핸들러·전역 진입점·에셋 · 진입점: AGENTS.md
레이아웃
레이아웃 4개 (루트: resources/layouts).
| 그룹 | 개수 |
|---|---|
admin |
4개 |
| 레이아웃 | 그룹 | 종류 | extends |
|---|---|---|---|
gdpr_consent_log |
admin |
화면 | _admin_base |
_policy_version_snapshot_modal |
admin |
partial | - |
_policy_version_publish_modal |
admin |
partial | - |
plugin_settings |
admin |
화면 | _admin_base |
관리자 화면 4개뿐이고 쿠키 배너·마이페이지 동의 탭은 이 표에 없습니다 — 그 둘은
"레이아웃"이 아니라 "레이아웃 확장 조각"(resources/extensions/cookie_banner.json,
mypage_privacy_tab.json, §extension-points.md)으로 다른 확장/템플릿 레이아웃에 주입되는
형태라 별도 수집 축에 잡힙니다. 방문자가 실제로 보는 UI를 찾으려면 이 표가 아니라
확장점 문서를 봐야 합니다.
액션 핸들러
핸들러 1개 (정의: resources/js/index.ts).
| 핸들러 | 레이아웃에서 부르는 이름 |
|---|---|
syncConsent |
sirsoft-gdpr.syncConsent |
syncConsent 하나뿐인 이유는 배너·마이페이지 UI 가 사실상 "동의 상태를 서버에 반영하고
화면을 갱신한다"는 단일 동작만 필요로 하기 때문입니다. 자동 차단/복원 로직(외부 스크립트·
iframe·1st-party 저장소 게이팅)은 이 액션 핸들러가 아니라 dist/js/plugin.iife.js 가 페이지
로드 시 스스로 수행합니다 — 사용자 조작에 반응하는 것과 페이지 로드마다 항상 실행되는 것을
액션 핸들러/전역 스크립트로 구분한 것입니다.
전역 진입점
| 항목 | 값 |
|---|---|
| 엔트리 파일 | resources/js/index.ts |
| 전역 객체 | window.__SirsoftGdpr |
| 재등록 진입점 | initPlugin() |
로케일 전환 시 코어가 이 진입점을 호출해 핸들러를 다시 등록합니다. 진입점은 핸들러 재등록만 수행하고 1회성 부팅 작업을 포함하지 않습니다.
initPlugin() 이 "핸들러 재등록만" 하도록 좁혀 둔 것은 코어 규정(§CLAUDE.md "확장 미들웨어는
...")을 그대로 따른 결과입니다 — 자동 차단 스크립트의 부팅(도메인 카탈로그 로드, DOM 스캔
시작)을 여기 넣으면 로케일 전환마다 그 부팅이 중복 실행됩니다. 자동 차단 부팅은 blocker.ts/
preblocker.ts 가 페이지 최초 로드 시 1회만 수행합니다.
에셋
| 경로 | 구분 |
|---|---|
dist/css/plugin.css |
빌드 산출물 (커밋 대상) |
dist/js/plugin.iife.js |
빌드 산출물 (커밋 대상) |
editor-spec.json |
레이아웃 편집기 스펙 (manifest) |
로딩 설정: {"strategy":"global","priority":0,"dependencies":[]}
priority: 0(다른 확장보다 먼저 로드)인 이유는 자동 차단이 다른 확장의 추적 스크립트가
실행되기 전에 걸려 있어야 하기 때문입니다 — 이 플러그인이 늦게 로드되면 동의 없이 이미
로드된 스크립트를 사후에 막을 방법이 없습니다. strategy: "global" 도 같은 이유로, 특정
페이지에서만 지연 로드하면 그 페이지에서는 동의 전 차단이 통째로 빠집니다.