Files

T

HeuJung 8328b1db77 docs(core,extensions): 확장 개발자 문서 9세트 집필과 생성기 정합 보강

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 를 편입했다.

2026-08-31 15:57:44 +09:00

3.5 KiB

Raw Blame History

Admin Basic — 아키텍처

설계 의도와 계층 구조 · 진입점: AGENTS.md

설계 의도

이 템플릿의 설계는 "관리자 화면 디자인"과 "관리자 화면 구성"을 분리하는 데 집중합니다. 컴포넌트(디자인 구현)는 이 템플릿이 소유하지만, 어떤 화면을 어떻게 구성할지(레이아웃 JSON)는 코어와 모든 번들 확장이 각자 소유합니다 — 이 템플릿은 그 구성을 그릴 부품만 제공합니다. 그래서 이 템플릿의 실질 소스는 컴포넌트(src/components/)와 코어 화면 레이아웃뿐이고, 확장 관리자 화면(모듈/플러그인이 소유)은 이 템플릿 디렉토리 밖(modules/, plugins/)에 있습니다.

필수 컴포넌트 계약(§AGENTS.md)이 이 분리를 지탱합니다 — 계약이 없으면 확장 개발자가 이 템플릿에만 있는 컴포넌트를 무심코 써버려 "관리자 화면 디자인 교체"가 사실상 불가능해집니다.

계층 지도

routes.json (URL → 레이아웃 이름 매핑)
        │
        ▼
layouts/*.json (extends: _admin_base)
        │
        ▼
_admin_base.json (사이드바·헤더·Toast·PageTransitionIndicator·콘텐츠 슬롯·푸터)
        │
        ▼
src/components/{basic,composite,layout}/*.tsx (필수 컴포넌트 35개 포함 125개)
        │
        ▼
src/handlers/*.ts (이 템플릿 전용 핸들러 17개 — 범용 핸들러는 코어 ActionDispatcher)

이 트리는 코어 화면에만 적용되는 것이 아닙니다 — 모듈/플러그인의 관리자 레이아웃도 같은 _admin_base → 컴포넌트 경로를 그대로 타므로, 이 템플릿을 고치면 그 확장들의 화면도 같은 방향으로 바뀝니다(§AGENTS.md "수정 시 동반 의무" 참고).

디렉토리

경로	역할	수정 시 필요한 절차
`template.json`	manifest (버전 SSoT)	version 변경 시 package.json·package-lock.json 동기화
`routes.json`	라우트 → 레이아웃 매핑	`php artisan template:update sirsoft-admin_basic --force`
`layouts/`	레이아웃 JSON	`php artisan template:update sirsoft-admin_basic --force` (빌드 불필요)
`src/components/`	React 컴포넌트	`php artisan template:build` → `php artisan template:update sirsoft-admin_basic --force`
`src/handlers/`	템플릿 전용 액션 핸들러	`php artisan template:build` → `php artisan template:update sirsoft-admin_basic --force`
`dist/`	커밋되는 빌드 산출물	`--production` 으로 재빌드 (sourceMappingURL 잔존 금지)
`editor-spec.json`	레이아웃 편집기 스펙	`php artisan template:update sirsoft-admin_basic --force`
`editor-spec/`	분할 편집기 스펙	`php artisan template:update sirsoft-admin_basic --force`
`tests/`	테스트	변경 범위만 필터 실행
`CHANGELOG.md`	변경 이력	버전 상향 시 항목 추가 (미기재 시 버전 상향 불가)
`components.json`	편집기 컴포넌트 선언 (레이아웃 저작자가 읽는 props 계약)	`php artisan template:update sirsoft-admin_basic --force`
`docs/`	개발자 문서	표면 변경 시 `php artisan ext:docgen` 재실행
`lang/`	다국어	키 추가 시 ko·en 동시 반영 + 번들 ja 팩 동기화

3.5 KiB Raw Blame History

Admin Basic — 아키텍처

설계 의도

계층 지도

디렉토리

3.5 KiB

Raw Blame History