HeuJung
8cf829f953
Modern PHP User Group 2026-09 정기모임 설치 리뷰에서 접수된 제보 2건. 설치 완료·실패·중단·필수파일 안내는 페이지 최상단에 뜨는데, 진행 로그를 보느라 화면이 아래에 머물러 있으면 안내가 눈에 들어오지 않았다. 네 경로 모두 DOM 변경이 끝난 뒤 결과 섹션으로 부드럽게 이동시킨다(모션 최소화 설정 시 즉시 이동). 미인증 3화면의 테마 버튼은 setTheme 을 params.theme 으로 불렀는데 핸들러는 action.target 만 읽는다. 엔진에 상호 폴백이 없어 클릭이 콘솔 경고 한 줄만 남기고 아무 일도 하지 않았다. 로그인 이후 화면은 핸들러를 거치지 않는 ThemeToggle 을 쓰기 때문에 정상이었고, 그래서 이 세 화면에서만 나타났다. 같은 계약 불일치가 편집기 액션 레시피(admin 9·basic 3)와 두 템플릿 문서에도 있어 함께 고쳤다. 편집기로 만든 액션은 생성 즉시 no-op 이 되는데 오류가 남지 않는다. 정적 검사 레지스트리가 오히려 틀린 계약(params.theme 필수)을 강제하고 있어 올바른 형태를 막고 있었으므로 두 미러를 함께 정정했다. 테마를 고치는 과정에서 별개 결함이 드러났다. GDPR 스토리지 인터셉터가 기능 쿠키 미동의 상태에서 필수 목록 밖 저장을 부팅마다 파기하는데, 화면 테마가 그 목록에서 빠져 있었다. 저장소의 setItem 호출을 기계 도출해 대조한 결과 같은 이유로 사라지던 항목이 13건 더 있었다 — 비회원 주문 조회, 결제창 복귀 기록, 본인인증 복귀 기록, 관리자 화면 상태, 자산 주소 형식 캐시. 전량 필수로 분류하고, 동의 안내 문구가 "다크모드는 기능 쿠키" 라고 말하던 부분을 사실에 맞게 정정했다(기설치본의 저장된 문구는 업그레이드 스텝이 정정하며, 운영자가 고친 문구는 건드리지 않는다). 재발 방지는 허용목록을 직접 import 하고 모집단을 디렉토리 순회로 도출하는 커버리지 테스트가 맡는다 — 손으로 열거하지 않으므로 새 저장 키가 등재를 빠뜨리면 붉어진다.
Admin Basic
그누보드7 템플릿 · sirsoft-admin_basic 그누보드7 기본 관리자 템플릿
소개 · 주요 기능 · 동작 방식 · 요구 사항 · 설치 · 제공 컴포넌트 · 사용 방법 · 다른 확장과의 연동 · 문서 · 트러블슈팅 · 변경 이력 · 라이선스
소개
그누보드7 이 기본 제공하는 관리자(admin) 템플릿입니다. 코어 관리자 화면뿐 아니라 설치된 모든 모듈/플러그인의 관리자 화면이 이 템플릿의 컴포넌트와 베이스 레이아웃을 그대로 사용합니다 — 확장을 설치하면 그 확장의 관리자 UI 도 자동으로 이 템플릿의 디자인(사이드바·헤더·색상·다크 모드)을 따릅니다.
이 템플릿은 사용자(방문자)용 화면을 그리지 않습니다 — 방문자 화면은 sirsoft-basic 템플릿의
몫입니다. 또한 완전히 다른 디자인의 관리자 화면이 필요하면 이 템플릿을 고치는 대신 같은
컴포넌트 계약(필수 컴포넌트 35개)을 구현하는 새 admin 템플릿을 만드는 것이 원칙입니다 — 그래야
기존 확장들의 관리자 화면이 새 템플릿에서도 깨지지 않습니다.
주요 기능
| 영역 | 설명 |
|---|---|
| 관리자 셸 | 사이드바(계층형 메뉴, 접힘 지원)·헤더·다크 모드·다국어 전환을 갖춘 공통 화면 골격(_admin_base) |
| 컴포넌트 125개 | HTML 래핑 39개(basic) + UI 패턴 캡슐화 80개(composite) + 페이지 구조 5개(layout) + 모달 1개 |
| 필수 컴포넌트 계약 | 35개 컴포넌트만 사용하면 다른 admin 템플릿으로 교체해도 화면이 보장되는 모듈 호환성 기준 |
| 레이아웃 145개 | 대시보드·사용자·역할·메뉴·설정·확장 관리·스케줄·활동/알림 로그 등 코어 관리자 화면 전체 |
| 확장 관리 UI | 모듈/플러그인/템플릿 설치·활성화·업데이트·삭제와 레이아웃 편집기(코드 편집 + 실시간 미리보기) |
| 본인인증(IDV) 챌린지 | 관리자 민감 작업에 걸리는 본인인증 화면 |
동작 방식
flowchart TD
base["_admin_base (사이드바·헤더·Toast·콘텐츠 슬롯)"] --> list["목록 화면 (PageHeader+DataGrid+Pagination)"]
base --> detail["상세 화면 (PageHeader+Card)"]
base --> form["폼 화면 (Form+FormField)"]
base --> settings["설정 화면 (TabNavigation+_tab_*)"]
auth["인증 화면 (admin_login 등, _admin_base 미상속)"]
errors["에러 화면 (errors/*, 독립 레이아웃)"]
인증 화면(로그인/비밀번호 찾기·재설정)과 에러 화면은 의도적으로 _admin_base 를 상속하지
않습니다 — 로그인 전이거나 정상 화면 렌더링 자체가 불가능한 상황이라 사이드바·헤더 같은
"이미 로그인된 관리자" 전제의 UI 를 보여줄 수 없기 때문입니다.
요구 사항
| 항목 | 값 |
|---|---|
| 그누보드7 코어 | >=7.0.10 |
| PHP | ^8.2 |
설치
# 번들 설치 (코어에 동봉된 소스에서 설치)
php artisan template:install sirsoft-admin_basic
# 활성화
php artisan template:activate sirsoft-admin_basic
# 업데이트 (번들 소스 기준 강제 반영)
php artisan template:update sirsoft-admin_basic --force
저장소: https://github.com/gnuboard/g7-template-sirsoft-admin_basic
제공 컴포넌트
컴포넌트 125개 (루트: src/components).
| 분류 | 개수 |
|---|---|
basic |
39개 |
composite |
80개 |
layout |
5개 |
modals |
1개 |
운영자가 직접 켜고 끄는 설정 항목은 없습니다 — 이 표는 확장(모듈/플러그인) 개발자가 레이아웃을 만들 때 참고하는 컴포넌트 인벤토리입니다. 전체 목록·Props 상세는 docs/components.md 와 코어 component-props.md 를 참고하세요.
사용 방법
새 확장의 관리자 화면 만들기: 확장의 resources/layouts/admin/*.json 에서
"extends": "_admin_base" 로 베이스를 상속하고, slots.content 에 필수 컴포넌트만으로 화면을
구성합니다. 필수 컴포넌트 목록 밖의 컴포넌트를 쓰면 다른 admin 템플릿으로 교체됐을 때 그
화면만 깨집니다.
사이드바 메뉴 등록: 확장이 getAdminMenus() 로 메뉴를 선언하면 이 템플릿의 AdminSidebar
가 자동으로 계층에 반영합니다 — 이 템플릿을 직접 수정할 필요가 없습니다.
레이아웃 실시간 편집: /admin/templates/sirsoft-admin_basic/edit 에서 레이아웃 편집기로
관리자 화면 자체를 코드 편집 + 실시간 미리보기로 수정할 수 있습니다(운영 환경에서는 신중하게
사용).
다른 확장과의 연동
이 확장이 의존하는 확장
없음 — 코어만으로 동작합니다.
이 확장에 의존하는 확장 (이 확장을 비활성화하면 함께 영향을 받습니다)
없음.
formal 의존성이 양쪽 다 "없음"인 것은 이 템플릿이 코어만으로 동작하기 때문이지만, 실질적으로는
모든 번들 모듈/플러그인의 관리자 화면이 이 템플릿의 필수 컴포넌트·_admin_base 계약에
암묵적으로 의존합니다. 이 의존은 manifest 로 선언되지 않습니다 — 어느 admin 템플릿이든 같은
계약(필수 컴포넌트 35개)만 구현하면 되므로, 확장이 "이 템플릿"이 아니라 "이 계약"에 의존하는
형태이기 때문입니다. 이 템플릿의 필수 컴포넌트 Props 를 바꿀 때 영향 범위를 이 템플릿
자신의 dependencies 목록으로는 알 수 없다는 뜻이며, 실제로는 활성 모듈/플러그인 전수의
관리자 레이아웃을 확인해야 합니다.
문서
| 문서 | 내용 | 상태 |
|---|---|---|
| docs/README.md | 문서 통합 목차와 실측 집계 | ✅ |
| docs/architecture.md | 설계 의도·계층 지도·디렉토리 맵 | ✅ |
| docs/components.md | 템플릿이 제공하는 컴포넌트 | ✅ |
| docs/layouts.md | 레이아웃 목록과 라우트 매핑 | ✅ |
| docs/handlers.md | 템플릿 전용 핸들러와 부트스트랩 | ✅ |
| docs/editor-spec.md | 레이아웃 편집기에 선언한 팔레트·컨트롤·샘플 데이터 | ✅ |
| CHANGELOG.md | 변경 이력 | ✅ |
트러블슈팅
| 증상 | 원인 | 조치 |
|---|---|---|
| 사이드바 메뉴 아이콘이 안 보임 | Icon 컴포넌트로 렌더 시도(API 는 FontAwesome 클래스 문자열을 내려줌) |
I 컴포넌트로 교체 (docs/components.md "AdminSidebar 상세" 참고) |
| 다른 admin 템플릿으로 교체 후 특정 확장 화면이 깨짐 | 그 확장이 필수 컴포넌트 목록 밖의 컴포넌트를 사용 | 그 확장의 레이아웃을 필수 컴포넌트(35개)만으로 재작성하거나, 새 템플릿에 같은 컴포넌트를 구현 |
| 사이드바 접힘 상태가 새로고침 후 풀림 | localStorage 접근 실패(시크릿 모드 등) 또는 부트스트랩 순서 문제 | initSidebar() 가 템플릿 부트스트랩에서 호출되는지 확인 (src/index.ts) |
| 로그인 화면에 다크 모드/언어 전환이 적용 안 됨 | 로그인 화면은 _admin_base 를 상속하지 않아 초기화 경로가 다름 |
admin_login.json 자체의 초기화 액션을 확인 — _admin_base 수정으로는 반영되지 않는다 |
변경 이력
라이선스
MIT