HeuJung
15cd4452bf
nginx 의 정규식 location 은 프리픽스 location 보다 먼저 매칭되므로, `location ~* \.(js|css|json)$` 블록이 있는 서버에서는 확장자 붙은 동적 엔드포인트가 `try_files ... /index.php` 폴백이 실행될 기회 없이 404 가 된다. aaPanel/CyberPanel/Plesk 기본 템플릿에 들어있어 드물지 않으며, 관리자 화면조차 뜨지 않아 "서버 설정을 고치세요" 안내가 순환 참조가 된다. 관례를 깬 쪽이 G7 이므로 해소 책임도 G7 에 두고, 두 형태를 모두 서빙한 뒤 환경에 따라 택일한다. 확장자 형태는 영구 유지한다 — 제거하면 URL 을 하드코딩한 서드파티 확장이 깨진다. - 라우트: dualSuffix / dualSuffixSegment / dualAsset 매크로로 23개 엔드포인트와 프로브를 이중 등록. 확장자 형태를 먼저 등록한다 — 확장자 없는 쪽이 더 느슨한 패턴이라 순서가 뒤집히면 `.json` 요청까지 삼킨다 - URL 생성: 서버 App\Support\AssetUrl, 프론트 core/support/assetUrl.ts 로 집약. 기본 모드에서 생성 결과는 치환 이전과 문자열까지 동일하다 (쿼리 순서 포함 — 순서가 바뀌면 의미는 같아도 HTTP 캐시 키가 갈린다) - 자가 복구: 부트스트랩 자산 로드 실패 시 확장자 없는 형태로 1회 단방향 전환. 역방향 금지 + 기존 재시도 예산 공유로 무한 왕복을 막는다 - 감지·전환: 인스톨러 프로브(설치 시 확정) / 관리자 환경설정 일반 탭 / g7:asset-url-mode. 판정은 상태코드가 아니라 매직 토큰 + Content-Type 으로 한다. 상태코드만 보면 "404 대신 200 + 에러 HTML" 환경에서 영원히 오판한다 - 봇은 JavaScript 를 실행하지 않아 자가 복구가 닿지 않으므로, 모드 변경 시 SEO 프리렌더 캐시를 비워 재생성시킨다 가드: audit 룰 2종(dynamic-route-static-extension / asset-url-builder-required), Playwright 6건(정적 블록 가로채기 시뮬레이션), 루프 방지 불변식 L1~L9 전수 red 증명. 부수 정리: 양 Composer 에 중복돼 있던 확장 에셋 수집 123줄을 트레이트로 통합하고, 자산 확장자 화이트리스트 누락(.map)과 경로 정규화 우회 가능성을 함께 교정. sir.kr 커뮤니티의 hang 님께서 제보해주셨습니다.
그누보드7 문서 인덱스
그누보드7 오픈소스 CMS 플랫폼의 개발 가이드 문서입니다.
카테고리별 통계
| 카테고리 | 문서 수 | 링크 상태 |
|---|---|---|
| 백엔드 | 33개 | 정상 |
| 프론트엔드 | 51개 | 정상 |
| 확장 시스템 | 31개 | 정상 |
| 공통 | 20개 | 정상 |
| AI 도구 | - | 정상 |
API 레퍼런스
G7 이 제공하는 REST API 의 엔드포인트별 요청 파라미터·응답 필드·요청/응답 예시입니다.
템플릿의 data_sources 를 작성하거나 외부에서 G7 을 연동할 때 참고하세요.
| 문서 | 설명 |
|---|---|
| backend/api/README.md | API 레퍼런스 진입점 — 공통 규약(인증·응답 봉투·페이지네이션·에러) + 코어/확장 전체 목차 |
| backend/api-documentation.md | API 문서 작성·갱신 규정 (기여자용) |
작업 유형별 필수 문서
레이아웃 JSON 작성
| 순서 | 문서 | TL;DR 핵심 |
|---|---|---|
| 1 | 레이아웃 JSON 스키마 | HTML 태그 직접 사용 금지 → 기본 컴포넌트 사용 (Div, Button, Span) |
| 2 | 레이아웃 JSON - 컴포넌트 | if: 조건부 렌더링 (type: "conditional" 사용 금지!) |
| 3 | 레이아웃 JSON - 기능 | classMap: 조건부 CSS 클래스 (key → variants 매핑) |
| 4 | 레이아웃 JSON - 상속 | extends: 베이스 레이아웃 상속 (type: "slot" 위치에 삽입) |
| 5 | 컴포넌트 개발 규칙 | HTML 태그 직접 사용 금지 |
| 6 | 컴포넌트 Props 레퍼런스 | - |
| 7 | sirsoft-admin_basic 컴포넌트 | Basic (37개), Composite (66개), Layout (8개) |
| 8 | 데이터 바인딩 및 표현식 | API 데이터: {{user.name}}, URL 파라미터: {{route.id}} |
| 9 | 데이터 바인딩 - 다국어 처리 | - |
| 10 | 액션 핸들러 가이드 | 구조: type 또는 event(이벤트), handler(핸들러명), params(옵션) |
| 11 | 액션 핸들러 - 핸들러별 상세 사용법 | navigate: 페이지 이동 (path, query, mergeQuery 옵션) |
| 12 | 전역 상태 관리 | 전역 상태: _global.속성명 (앱 전체 공유, 페이지 이동 시 유지) |
| 13 | 데이터 소스 | data_sources 배열에 API 정의: id, endpoint, method |
| 14 | 다크 모드 지원 | Tailwind dark: variant 사용 |
컨트롤러 작성
| 순서 | 문서 | TL;DR 핵심 |
|---|---|---|
| 1 | 컨트롤러 계층 구조 | AdminBaseController / AuthBaseController / PublicBaseController |
| 2 | 라우트 네이밍 및 경로 | 모든 라우트는 name() 필수 |
| 3 | 검증 (Validation) | FormRequest 사용 필수 (Service에 검증 로직 금지) |
| 4 | API 응답 규칙 (ResponseHelper) | 모든 API 응답은 ResponseHelper 사용 |
Service/Repository 작성
| 순서 | 문서 | TL;DR 핵심 |
|---|---|---|
| 1 | Service-Repository 패턴 | RepositoryInterface 주입 필수 (구체 클래스 직접 주입 금지) |
| 2 | 훅 시스템 | Action 훅: doAction() - 부가 작업 (로그, 알림, 캐시) |
마이그레이션 작성
| 순서 | 문서 | TL;DR 핵심 |
|---|---|---|
| 1 | 데이터베이스 개발 가이드 | 마이그레이션: 한국어 comment 필수, down() 구현 필수 |
모듈 개발
| 순서 | 문서 | TL;DR 핵심 |
|---|---|---|
| 1 | 모듈 개발 기초 | 디렉토리: vendor-module (예: sirsoft-ecommerce) |
| 2 | 모듈 라우트 규칙 | URL prefix 자동: /api/admin/[vendor-module]/... |
| 3 | 모듈 레이아웃 시스템 | modules/_bundled/vendor-module/resources/layouts/ |
| 4 | 모듈 다국어 시스템 | 백엔드: /lang/{locale}/*.php |
| 5 | 훅 시스템 | Action 훅: doAction() |
테스트 작성
| 순서 | 문서 | TL;DR 핵심 |
|---|---|---|
| 1 | 테스트 가이드 | 테스트 통과 = 작업 완료 (작성만으로 불충분!) |
| 2 | 레이아웃 렌더링 테스트 가이드 | createLayoutTest()로 테스트 헬퍼 생성 |
API 리소스 작성
| 순서 | 문서 | TL;DR 핵심 |
|---|---|---|
| 1 | API 리소스 | BaseApiResource 상속 필수 |
| 2 | API 응답 규칙 (ResponseHelper) | 모든 API 응답은 ResponseHelper 사용 |
FormRequest 작성
| 순서 | 문서 | TL;DR 핵심 |
|---|---|---|
| 1 | 검증 (Validation) | FormRequest 사용 필수 (Service에 검증 로직 금지) |
| 2 | Custom Exception 다국어 처리 | 예외 메시지 하드코딩 금지 → __() 함수 필수 |
권한/메뉴 추가
| 순서 | 문서 | TL;DR 핵심 |
|---|---|---|
| 1 | 권한 시스템 | 구조: User → Role → Permission (기능 레벨) |
| 2 | 메뉴 시스템 | 구조: User → Role → role_menus 피벗 → Menu |
다국어 추가
| 순서 | 문서 | TL;DR 핵심 |
|---|---|---|
| 1 | 모듈 다국어 시스템 | 백엔드: /lang/{locale}/*.php |
| 2 | 데이터베이스 개발 가이드 | 마이그레이션: 한국어 comment 필수, down() 구현 필수 |
| 3 | 데이터 바인딩 - 다국어 처리 | - |
카테고리별 전체 문서 목록
백엔드 (33개)
| 문서 | 제목 |
|---|---|
| activity-log-hooks.md | 활동 로그 훅 레퍼런스 (Activity Log Hooks Reference) |
| activity-log.md | 활동 로그 시스템 (Activity Log System) |
| admin-settings-access.md | Admin 환경설정 값 접근 (g7_core_settings vs config()) |
| api-documentation.md | API 레퍼런스 문서 규정 (API Documentation) |
| api-resources.md | API 리소스 |
| authentication.md | 인증 및 세션 처리 |
| broadcasting.md | Broadcasting (실시간 이벤트) |
| console-confirm.md | 콘솔 yes/no 프롬프트 (ConsoleConfirm) |
| controllers.md | 컨트롤러 계층 구조 |
| core-config.md | 코어 설정 (config/core.php) |
| core-update-system.md | 코어 업데이트 시스템 (Core Update System) |
| data-sync-helpers.md | 데이터 동기화 Helper (Data Sync Helpers) |
| dto.md | DTO (Data Transfer Object) 사용 규칙 |
| enum.md | Enum 사용 규칙 |
| exceptions.md | Custom Exception 다국어 처리 |
| geoip.md | GeoIP 시스템 (MaxMind GeoLite2) |
| identity-messages.md | 본인인증 메시지 템플릿 시스템 (Identity Messages) |
| identity-policies.md | 본인인증 정책 시스템 (Identity Policies) |
| identity-providers.md | IDV Provider 작성 가이드 (Identity Verification Providers) |
| language-pack-service.md | LanguagePackService (백엔드 Service 레이어) |
| middleware.md | 미들웨어 등록 규칙 |
| notification-system.md | 알림 시스템 (Notification System) |
| README.md | 백엔드 개발 가이드 |
| response-helper.md | API 응답 규칙 (ResponseHelper) |
| routing.md | 라우트 네이밍 및 경로 |
| search-system.md | Scout 검색 엔진 시스템 (Search System) |
| seo-system.md | SEO 페이지 생성기 시스템 (SEO Page Generator) |
| service-provider.md | 서비스 프로바이더 안전성 |
| service-repository.md | Service-Repository 패턴 |
| settings-multilingual-enrichment.md | Settings 카탈로그 다국어 자동 보강 |
| translatable-seeders.md | 다국어 시더 인터페이스 (Translatable Seeders) |
| user-overrides.md | 사용자 수정 보존 (HasUserOverrides Trait) |
| validation.md | 검증 (Validation) |
프론트엔드 (51개)
| 문서 | 제목 |
|---|---|
| actions-g7core-api.md | 액션 시스템 - G7Core API (React 컴포넌트용) |
| actions-handlers-navigation.md | 액션 핸들러 - 네비게이션 |
| actions-handlers-state.md | 액션 핸들러 - 상태 관리 |
| actions-handlers-ui.md | 액션 핸들러 - UI 인터랙션 |
| actions-handlers.md | 액션 핸들러 - 핸들러별 상세 사용법 |
| actions.md | 액션 핸들러 가이드 |
| auth-system.md | 인증 시스템 (AuthManager) |
| component-props-composite.md | 컴포넌트 Props 레퍼런스 - Composite |
| component-props.md | 컴포넌트 Props 레퍼런스 |
| components-advanced.md | 컴포넌트 고급 기능 |
| components-patterns.md | 컴포넌트 패턴 및 다국어 |
| components-types.md | 컴포넌트 타입별 개발 규칙 |
| components.md | 컴포넌트 개발 규칙 |
| dark-mode.md | 다크 모드 지원 (engine-v1.1.0+) |
| data-binding-i18n.md | 데이터 바인딩 - 다국어 처리 |
| data-binding.md | 데이터 바인딩 및 표현식 |
| data-sources-advanced.md | 데이터 소스 - 고급 기능 |
| data-sources.md | 데이터 소스 (Data Sources) |
| editors.md | 에디터 컴포넌트 가이드 |
| g7core-api-advanced.md | G7Core 전역 API 레퍼런스 - 고급 |
| g7core-api.md | G7Core 전역 API 레퍼런스 |
| g7core-helpers.md | G7Core 헬퍼 API |
| identity-guard-interceptor.md | IdentityGuardInterceptor — 코어 본인인증 인터셉터 레퍼런스 |
| identity-verification-ui.md | 본인인증(IDV) 공통 UI 가이드 |
| layout-json-components-loading.md | 레이아웃 JSON - 데이터 로딩 및 생명주기 |
| layout-json-components-rendering.md | 레이아웃 JSON - 조건부/반복 렌더링 |
| layout-json-components-slots.md | 레이아웃 JSON - 슬롯 시스템 |
| layout-json-components.md | 레이아웃 JSON - 컴포넌트 (반복 렌더링, Blur, 생명주기, 슬롯) |
| layout-json-features-actions.md | 레이아웃 JSON - 초기화, 모달, 액션, 스크립트 |
| layout-json-features-error.md | 레이아웃 JSON - 에러 핸들링 |
| layout-json-features-styling.md | 레이아웃 JSON - 스타일 및 계산된 값 |
| layout-json-features.md | 레이아웃 JSON - 기능 (에러 핸들링, 초기화, 모달, 액션) |
| layout-json-inheritance.md | 레이아웃 JSON - 상속 (Extends, Partial, 병합) |
| layout-json.md | 레이아웃 JSON 스키마 |
| layout-testing.md | 그누보드7 레이아웃 파일 렌더링 테스트 가이드 |
| modal-usage.md | Modal 컴포넌트 사용 가이드 |
| README.md | 그누보드7 프론트엔드 개발 가이드 |
| responsive-layout.md | 반응형 레이아웃 개발 (engine-v1.1.0+) |
| security.md | 보안 및 검증 |
| state-management-advanced.md | 상태 관리 - 고급 기능 |
| state-management-forms.md | 상태 관리 - 폼 자동 바인딩 및 setState |
| state-management.md | 전역 상태 관리 |
| tailwind-safelist.md | Tailwind Safelist 가이드 |
| template-development.md | 템플릿 개발 가이드라인 |
| template-handlers.md | 템플릿 전용 핸들러 |
| components.md | sirsoft-admin_basic 컴포넌트 |
| handlers.md | sirsoft-admin_basic 핸들러 |
| layouts.md | sirsoft-admin_basic 레이아웃 |
| components.md | sirsoft-basic 컴포넌트 |
| handlers.md | sirsoft-basic 핸들러 |
| layouts.md | sirsoft-basic 레이아웃 |
확장 시스템 (31개)
| 문서 | 제목 |
|---|---|
| cache-driver.md | 캐시 드라이버 시스템 (CacheInterface) |
| changelog-rules.md | Changelog 규칙 (Changelog Rules) |
| editor-spec.md | 편집기 스펙 (editor-spec.json) |
| extension-manager.md | ExtensionManager (확장 관리자) |
| extension-update-system.md | 확장 업데이트 시스템 (Extension Update System) |
| hooks.md | 훅 시스템 (Hook System) |
| language-packs.md | 언어팩 시스템 (Language Packs) |
| layout-extensions.md | 레이아웃 확장 시스템 (Layout Extensions) |
| menus.md | 메뉴 시스템 |
| module-assets.md | 모듈 프론트엔드 에셋 시스템 |
| module-basics.md | 모듈 개발 기초 |
| module-commands.md | 모듈 Artisan 커맨드 |
| module-i18n.md | 모듈 다국어 시스템 |
| module-identity-settings.md | 모듈/플러그인 본인인증(IDV) 설정 통합 가이드 |
| module-layouts.md | 모듈 레이아웃 시스템 |
| module-routing.md | 모듈 라우트 규칙 |
| module-settings.md | 모듈 환경설정 시스템 개발 가이드 |
| permissions.md | 권한 시스템 |
| plugin-development.md | 플러그인 개발 가이드 |
| README.md | 그누보드7 확장 시스템 개발 가이드 |
| sample-extensions.md | 학습용 샘플 확장 (Sample Extensions) |
| storage-driver.md | 스토리지 드라이버 시스템 (StorageInterface) |
| template-basics.md | 템플릿 시스템 기초 |
| template-caching.md | 템플릿 캐싱 전략 |
| template-commands.md | 템플릿 Artisan 커맨드 |
| template-idv-bootstrap.md | 템플릿 IDV launcher 등록 가이드 |
| template-routing.md | 템플릿 라우트/언어 파일 규칙 |
| template-security.md | 템플릿 보안 정책 |
| template-workflow.md | 템플릿 개발 워크플로우 |
| upgrade-step-guide.md | 업그레이드 스텝 작성 가이드 (Upgrade Step Guide) |
| vendor-bundle.md | Vendor 번들 시스템 (Vendor Bundle System) |
공통 (20개)
| 문서 | 제목 |
|---|---|
| README.md | 그누보드7 Multi-Agent System |
| README.md | 그누보드7 DevTools MCP 서버 |
| README.md | 그누보드7 AI 도구 |
| create-module.md | 모듈 스캐폴딩 (create-module) |
| create-plugin.md | 플러그인 스캐폴딩 (create-plugin) |
| create-template.md | 템플릿 스캐폴딩 (create-template) |
| extract-i18n-keys.md | 다국어 키 추출 (extract-i18n-keys) |
| run-tests.md | 테스트 실행 (run-tests) |
| validate-backend.md | 백엔드 코드 패턴 검증 (validate-backend) |
| validate-frontend.md | 프론트엔드 검증 (validate-frontend) |
| validate-hook.md | 훅 패턴 검증 (validate-hook) |
| validate-i18n.md | 다국어 검증 (validate-i18n) |
| validate-migration.md | 마이그레이션 검증 (validate-migration) |
| cheatsheet.md | 그누보드7 자주 쓰는 명령어 치트시트 |
| database-guide.md | 그누보드7 데이터베이스 개발 가이드 |
| README.md | 그누보드7 문서 인덱스 |
| requirements.md | 그누보드7 시스템 요구사항 (System Requirements) |
| SECURITY.md | 그누보드7 템플릿 엔진 보안 가이드 |
| testing-guide.md | 그누보드7 테스트 가이드 |
| e2e-testing.md | 그누보드7 Playwright E2E 테스트 가이드 |
AI 도구
| 문서 | 설명 |
|---|---|
| ai-tools/README.md | AI 도구 개요 |
| ai-tools/skills/ | AI 코딩 도구 스킬 |
| ai-tools/agents/ | 멀티에이전트 시스템 소스 |