Files
Gnuboard7/docs/extension
HeuJung dd8f9a49c4 fix(core,template): 편집기 image 위젯 값 형태·데이터 연결 값 보호·상속 노드 편집 표면 수정
공개 는 헤더 「로고 이미지」에 이미지를 지정하면 화면이 엑박이 되는 제보였다.
image 위젯은 배경용으로 설계되어 {url,size,repeat,position} 객체를 내보내는데, 값 슬롯이
하나뿐인 apply 경로(propValue/cssVar/단일 styleProp)가 그 객체를 그대로 props 에 기록해
소비 컴포넌트가 [object Object] 를 URL 로 받았다. 예외도 콘솔 오류도 서버 로그도 남지
않는다 — 깨진 이미지 요청은 SPA catch-all 때문에 404 조차 아니라 200(HTML)이고, 편집기
미리보기는 정상이라 조작 중에는 이상이 보이지 않는다.

방어선을 넷으로 세웠다. 쓰기 축약(공용 헬퍼 scalarizeImageValue 단일 지점, 게이트는 위젯
이름이며 값 형태 sniffing 이 아니다) · 읽기 역조립(표현식 문자열도 되감아 업로드 1클릭에
소실되지 않게 한다) · 런타임 방어(업그레이드 전 화면을 위해 템플릿 Img 가 url 을 해석하고
손상값이면 src 를 아예 붙이지 않는다) · 저장 데이터 백필(업그레이드 스텝). 런타임과 백필은
완전히 같은 엄격 판정식(키 집합 ⊆ 4키 AND url 보유)을 쓴다 — 엔진의 느슨한 판정식을 백필에
이식하면 레이아웃 전수에서 정상 props 2,219건을 파괴한다(실측).

전수조사에서 파생한 인접 결함 넷을 함께 고쳤다.

- number 위젯이 코어 레지스트리에 미등록이라 「탭 표시 게시판 수」 같은 컨트롤이
 「지원하지 않는 컨트롤」로 폴백해 편집 자체가 불가했다. nodeKey apply 는 coreProps 가
 선언만 하고 엔진 switch 에 case 가 없어 무음 no-op 이었다.
- 상속(base)·주입(extension) 노드 중 바인딩을 가진 것이 data_bound 로 분류돼 편집이
 열려 있었는데, 저장 마스킹이 그 노드를 통째로 폐기하므로 편집분이 오류도 경고도 없이
 사라졌다(저장은 200 이고 history 는 clear 돼 undo 도 불가). 출처 잠금이 항상 우선하도록
 판정 순서를 통일하고, 단일 판정 헬퍼로 인라인 편집·복제·Delete·잘라내기·드래그 commit
 까지 전 표면을 같은 기준으로 막았다.
- prop 자리의 표현식 값을 위젯이 해석하지 못해 빈 컨트롤로 보이고, 조작하는 순간 환경설정
 과의 연결이 소리 없이 끊겼다. 판정·배지·잠금·해제·복구를 ControlRenderer 공용 게이트
 한 곳으로 올려 신규 위젯에도 자동 적용되게 했다. 「직접 지정으로 바꾸기」에는 「되돌리기」를
 동반해 편도가 되지 않게 한다.
- 편집기 모드에서 updateTemplateData 가 빈 레이아웃으로 같은 reactRoot 에 두 번째 커밋을
 걸어 편집기 트리를 통째로 제거했다. renderTemplate 의 편집기 분기가 비동기라 부팅 중
 setGlobalState 가 그 커밋 뒤에 도착할 때만 발현하는 경합이었다.
2026-09-08 17:20:01 +09:00
..
2026-05-11 11:29:41 +09:00
2026-04-20 20:37:49 +09:00
2026-04-20 20:37:49 +09:00
2026-05-11 11:29:41 +09:00
2026-04-01 10:30:52 +09:00

그누보드7 확장 시스템 개발 가이드

이 문서는 그누보드7의 확장 시스템 전체 개요와 각 상세 문서에 대한 링크를 제공합니다.


핵심 원칙

필수: /modules, /plugins 디렉토리 스캔으로 자동 발견 (composer.json 하드코딩 금지)
필수: 모든 확장 작업은 Artisan 커맨드로 수행
✅ 필수: 훅 시스템을 통한 코어 수정 최소화

확장 시스템 개요

G7은 동적 로딩 기반의 확장 시스템을 제공합니다:

  • 모듈: 독립적인 비즈니스 기능 단위 (예: 이커머스, 블로그)
  • 플러그인: 특정 기능 확장 (예: 결제, 배송)
  • 템플릿: UI 렌더링 및 레이아웃 정의 (Admin, User)
  • 훅 시스템: 코어 수정 없이 로직 확장

문서 구조

훅 시스템

문서 설명
hooks.md Action/Filter Hook, 리스너 구현, 우선순위

모듈 개발

문서 설명
module-basics.md AbstractModule, 디렉토리 구조, 네이밍 규칙
module-routing.md API/Web 라우트, 자동 Prefix, routes.json
module-layouts.md 레이아웃 등록, 오버라이드, 상속
module-commands.md Artisan 커맨드 (install, activate, uninstall)
module-i18n.md 백엔드/프론트엔드 다국어 분리

레이아웃 확장

문서 설명
layout-extensions.md 동적 UI 주입 (Overlay, Extension Point), 템플릿 오버라이드

플러그인 개발

문서 설명
plugin-development.md PluginInterface, 격리성, 의존성 원칙

확장 관리자

문서 설명
extension-manager.md Composer 오토로드, 서비스 등록, hidden 필터링

학습용 샘플

문서 설명
sample-extensions.md 학습용 최소 샘플 확장 4종 (gnuboard7-hello_*) — 계층 1:1 비교 레퍼런스

템플릿 시스템

문서 설명
template-basics.md Admin/User 템플릿, 메타데이터, 버전 히스토리
template-routing.md 라우트 정의, 언어 파일 경로 규칙
template-security.md API 서빙, 파일 확장자 화이트리스트
template-caching.md 캐시 계층, 무효화 전략
template-commands.md Artisan 커맨드 (install, activate)

권한 및 메뉴 시스템

문서 설명
permissions.md Role, Permission, 자동 관리
menus.md 메뉴 권한, 시더

확장 문서화

문서 설명
extension-documentation.md AGENTS.md/README.md/docs 역할 경계, 자동 생성 블록 규약, ext:docgen
changelog-rules.md 버전 상향 시 CHANGELOG 기재 의무

확장 타입별 네이밍 규칙

타입 디렉토리명 네임스페이스 Composer 경로
모듈 vendor-module Modules\Vendor\Module\ modules/vendor-module
플러그인 vendor-plugin Plugins\Vendor\Plugin\ plugins/vendor-plugin
템플릿 vendor-template - templates/vendor-template

예시:

  • 모듈: sirsoft-ecommerce → Modules\Sirsoft\Ecommerce\
  • 플러그인: sirsoft-payment → Plugins\Sirsoft\Payment\
  • 템플릿: sirsoft-admin_basic

훅 네이밍 규칙

[vendor-module].[entity].[action]_[timing]

타이밍 접미사:

  • before_*: 작업 실행 전
  • after_*: 작업 실행 후
  • on_*: 특정 이벤트 발생 시
  • filter_*: 데이터 필터링

예시:

sirsoft-ecommerce.product.before_create
sirsoft-ecommerce.product.after_update
sirsoft-ecommerce.product.filter_create_data
sirsoft-ecommerce.order.on_payment_success

주요 Artisan 커맨드

모듈 관련

php artisan module:list                    # 모듈 목록 조회
php artisan module:install [identifier]    # 모듈 설치
php artisan module:activate [identifier]   # 모듈 활성화
php artisan module:deactivate [identifier] # 모듈 비활성화
php artisan module:uninstall [identifier]  # 모듈 제거
php artisan module:cache-clear             # 모듈 캐시 정리

템플릿 관련

php artisan template:list                    # 템플릿 목록 조회
php artisan template:install [identifier]    # 템플릿 설치
php artisan template:activate [identifier]   # 템플릿 활성화
php artisan template:deactivate [identifier] # 템플릿 비활성화
php artisan template:uninstall [identifier]  # 템플릿 제거
php artisan template:cache-clear             # 템플릿 캐시 정리

확장 관리자

php artisan extension:update-autoload   # Composer 오토로드 업데이트

빠른 시작 가이드

새 모듈 개발 시

  1. module-basics.md - 기본 구조 이해
  2. module-routing.md - 라우트 설정
  3. module-i18n.md - 다국어 지원
  4. module-layouts.md - 레이아웃 등록 (필요시)
  5. hooks.md - 훅 리스너 구현 (필요시)

새 플러그인 개발 시

  1. plugin-development.md - 플러그인 구조 이해
  2. hooks.md - 훅 리스너 구현

템플릿 커스터마이징 시

  1. template-basics.md - 템플릿 타입 이해
  2. template-routing.md - 라우트/언어 파일
  3. template-security.md - 보안 규칙

관련 문서