HeuJung
3a0aba85bc
확장 문서의 제품 호칭을 「그누보드7」로 통일했다. 가 지적한 두 문구는 개별 오타가 아니라 생성기가 찍는 정형 문구여서, 산출물이 아니라 방출 지점 세 곳을 먼저 고쳤다 — 그러지 않으면 21번째 확장부터 다시 샌다. 정리 범위는 확장 문서와 그 생성기까지이며, 코어 docs 와 언어팩 표시명은 의도적으로 남긴다. 레이아웃 편집기 대응 문서가 없던 문제는 확장마다 docs/editor-spec.md 를 두어 닫았다. 실측은 EditorSpecCollector 가 유지하며, 합본에 런타임과 같은 EditorSpecAssembler 를 써서 문서가 말하는 스펙과 편집기가 읽는 스펙이 갈라질 경로를 두지 않았다. 스펙을 두지 않은 확장에도 문서를 둔다 — 미보유가 정상일 수 있고, 그 정상 여부를 적을 자리가 없으면 다음 사람이 부재를 누락으로 오해하거나 필요한 시점을 놓친다. 초안이 낸 수치 다섯 건이 틀렸고 전부 오류 없이 "사실" 로 실릴 값이었다. 블록 최상위 키를 세어 팔레트가 79 대신 3 이 되던 것, `_` 접두 일괄 배제가 실제 항목을 삼키던 것 등을 정정했다. 게이트를 인위적으로 깨뜨려 점검한 결과 사각 하나가 드러났다 — 채워 넣으라는 표시만 지우고 서술을 쓰지 않으면 검사를 통과해, 빈 문서가 완비로 집계됐다. 미채움을 두 축으로 만들어 닫았고 되돌림으로 검산했다. 편집기 스펙 편집 시 규정이 주입되지 않던 것과 스캐폴딩 안내가 새 문서를 빠뜨리던 것도 함께 고쳤다.
그누보드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 오토로드 업데이트
빠른 시작 가이드
새 모듈 개발 시
- module-basics.md - 기본 구조 이해
- module-routing.md - 라우트 설정
- module-i18n.md - 다국어 지원
- module-layouts.md - 레이아웃 등록 (필요시)
- hooks.md - 훅 리스너 구현 (필요시)
새 플러그인 개발 시
- plugin-development.md - 플러그인 구조 이해
- hooks.md - 훅 리스너 구현
템플릿 커스터마이징 시
- template-basics.md - 템플릿 타입 이해
- template-routing.md - 라우트/언어 파일
- template-security.md - 보안 규칙
관련 문서
- AGENTS.md - 프로젝트 개발 가이드
- backend/ - 백엔드 개발 가이드
- frontend/ - 프론트엔드 개발 가이드
- database-guide.md - 데이터베이스 가이드