HeuJung
f32729e20e
KVE-2026-2191 대응에서 계획 안 세부를 자율 결정한 지점을 회귀 전수조사해 정합 결함 5건을 고쳤다. 넷은 같은 미출시 버전이 만든 자기교정이고, 마지막 하나는 7.0.10 및 그 이전부터 있던 결함이라 공개 CHANGELOG 에 항목을 넣었다. - 적중 통계의 레이아웃명이 항상 비어 화면별 표가 성립하지 않던 것 → 페이지 캐시 값에 레이아웃명을 함께 담고 적중 경로가 그것으로 귀속한다. 이전 버전이 문자열로만 저장한 항목은 그대로 읽어 배포 직후 살아 있는 캐시를 버리지 않는다. 인터페이스는 불변이고 코어 구현일 때만 항목 전체를 읽는다. - 통계 url 컬럼(255)이 캐시 키 URL(정규화 쿼리 최대 512바이트)보다 짧아 긴 주소의 기록이 엄격 모드에서 실패하고 그 예외를 서비스가 삼키던 것 → 768 로 확장(utf8mb4 인덱스 키 상한 3072바이트). down 은 잘리는 행을 먼저 지운다. - 경로당 변종 상한이 언어를 합산해 다국어 사이트의 실효 상한이 언어 수만큼 줄던 것 → 인덱스 항목이 url|locale 별이므로 경로·언어 조합 단위로 판정한다. - 그릴 게 없는 요청(미라우트 404·SEO 비활성)이 렌더 예산을 소모해, 캐시에 남지 않는 죽은 주소 재크롤이 정상 페이지의 예산을 태우던 것 → null 렌더는 차감을 환급한다. 렌더 도중 예외는 비용을 이미 치른 것이라 환급하지 않는다. - 병합 단계에서 건너뛴 확장이 있는 결과가 캐시로 굳어 버전 bump 전까지 그 확장 자산이 사라진 채 고정되던 것 → 병합 루프를 mergeJs/mergeCss 로 분리해 건너뛴 확장을 함께 돌려주고, 하나라도 있으면 캐시하지 않고 Log::error 로 남긴다. 캐시 없이 돌면 호출측이 매 요청 다시 병합하므로 원인이 사라지는 즉시 회복한다. 기본 로그 수준이 error 라 종전 per-extension warning 은 기록되지 않아 흔적이 없었다. 회귀 테스트 8건은 red 확인 후 green 으로 전환했고, 변경 심볼의 소비자 모집단(테스트 클래스 9종)을 프로세스 분할로 재실행해 189건 통과를 확인했다.
그누보드7 문서 인덱스
그누보드7 오픈소스 CMS 플랫폼의 개발 가이드 문서입니다.
카테고리별 통계
| 카테고리 | 문서 수 | 링크 상태 |
|---|---|---|
| 백엔드 | 37개 | 정상 |
| 프론트엔드 | 46개 | 정상 |
| 확장 시스템 | 32개 | 정상 |
| 공통 | 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-basic 컴포넌트 | 확장 소유 문서 (basic / composite / layout) |
| 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 사용 |
sirsoft-admin_basic 컴포넌트 문서는 확장이 소유합니다 — templates/_bundled/sirsoft-admin_basic/docs/components.md 를 참고하세요.
컨트롤러 작성
| 순서 | 문서 | 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 | 데이터 바인딩 - 다국어 처리 | - |
카테고리별 전체 문서 목록
백엔드 (37개)
| 문서 | 제목 |
|---|---|
| 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 | 인증 및 세션 처리 |
| benchmark.md | 성능 계측 시스템 (Benchmark) |
| 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) |
| pagination.md | 대용량 목록 페이지네이션 (Pagination) |
| README.md | 백엔드 개발 가이드 |
| response-helper.md | API 응답 규칙 (ResponseHelper) |
| reverse-proxy.md | 리버스 프록시 환경 (Reverse Proxy) |
| 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 카탈로그 다국어 자동 보강 |
| static-asset-publishing.md | 부트스트랩 리소스 정적 게시 (Static Asset Publishing) |
| translatable-seeders.md | 다국어 시더 인터페이스 (Translatable Seeders) |
| user-overrides.md | 사용자 수정 보존 (HasUserOverrides Trait) |
| validation.md | 검증 (Validation) |
프론트엔드 (46개)
| 문서 | 제목 |
|---|---|
| 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 | 템플릿 전용 핸들러 |
| README.md | 템플릿별 컴포넌트·핸들러·레이아웃 문서 |
확장 시스템 (32개)
| 문서 | 제목 |
|---|---|
| cache-driver.md | 캐시 드라이버 시스템 (CacheInterface) |
| changelog-rules.md | Changelog 규칙 (Changelog Rules) |
| editor-spec.md | 편집기 스펙 (editor-spec.json) |
| extension-documentation.md | 확장 개발자 문서 (Extension Documentation) |
| 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/ | 멀티에이전트 시스템 소스 |