HeuJung
85e266d361
https://github.com/gnuboard/g7/issues/125 — 상품 상세설명을 HTML 로 저장할 때 HTMLPurifier 가 모듈 vendor 폴더 안에 정의 캐시를 만들려다 실패해 저장이 매번 500 으로 끝나던 문제를 고친다. vendor 를 읽기 전용으로 두는 표준 배포에서 그 쓰기는 예외가 아니라 PHP 경고로 나오고 Laravel 이 이를 ErrorException 으로 승격시킨다. 캐시는 설정 해시당 1회만 기록되므로 캐시가 영영 생기지 않아 재시도해도 같은 결과였다. 캐시 경로를 storage 아래로 옮기고, 그 경로마저 확보하지 못하면 캐시만 끄고 정화는 그대로 수행한다 — 캐시는 성능 장치이고 정화는 보안 장치라, 전자의 실패가 후자를 건너뛰게 만들면 안 된다. 저장은 성공하므로 운영자에게 도달하는 흔적이 로그 하나뿐이라 error 수준으로 남긴다 (출하 기본 로그 수준이 error 라 warning 은 기본 설치 상태에서 파일에 남지 않는다). 그 과정에서 갈라져 있던 두 축을 코어 한 곳으로 모은다. - 쓰기 디렉토리 확보: 억제 생성·chmod·setgid·소유권 상속·쓰기 판정 절차가 정적 게시와 정의 캐시 두 곳에 서로 다른 하드닝으로 복제돼 있었다(억제 mkdir·setgid·clearstatcache 가 사본마다 한쪽씩 빠져 있었다). FilePermissionHelper 의 ensureWritableDirectory 와 hardenDirectory 로 통합하고, 실패 사유는 out 파라미터로 올려 정책(조용한 성능 저하 대 시끄러운 실패)은 호출부가 정하게 둔다. - 확장 저장 경로: storage_path('app/modules/…') 손조립이 30곳에 흩어져 있어 테스트 격리 분기를 넣으려면 사본마다 복제해야 했고, 한 곳만 빠뜨려도 그 확장의 테스트가 운영 설정 파일을 덮어쓴다. 디스크 root 를 단일 출처로 읽는 ExtensionStoragePath 로 전환하고 테스트 분기는 config/filesystems.php 한 줄에서 끝낸다. 함께 고친 것 - 테스트가 운영 라우트 캐시로 부팅해 확장 allowlist 가 라우트 축에서 통째로 무력화되던 문제. 삭제가 아니라 경로를 돌린다 — 라우트 캐시는 확장 작업 전까지 재생성되지 않아, 삭제하면 운영 사이트가 그때까지 라우트 파일 스캔 경로로 떨어진다. - PHPUnit 프로세스가 확장 vendor 의 제3자 composer 패키지를 오토로드하지 않아 그 패키지를 쓰는 코드 경로가 통째로 테스트 불가였던 문제. 확장 자신의 오토로더를 그대로 쓰면 활성 디렉토리가 _bundled 를 이기고 base path 유추까지 깨지므로, 생성된 맵에서 제3자 항목만 골라 별도 로더로 등록한다. - 게시 폴더가 setgid 를 갖지 않아, 명령줄과 웹이 번갈아 만든 하위 폴더를 다른 쪽이 쓰지 못하던 문제. - 관리자 템플릿이 HTML 정화 라이브러리를 직접 지정하지 않아 전이 의존으로 딸려온 구버전이 쓰이던 문제. 동반 산출물 - 규정 표(·AGENTS.md) 6행 + storage-driver/service-repository/testing-guide 문서 - audit 룰 2종 + coverage 6항목. 저장소가 이미 전량 전환돼 전수 실행이 공허 통과하므로 판정식은 픽스처 36건이 잠근다 - INSTALL.md 에 설치 후 파일 권한 절 추가 (vendor 쓰기 권한 불요를 명시)
그누보드7 문서 인덱스
그누보드7 오픈소스 CMS 플랫폼의 개발 가이드 문서입니다.
카테고리별 통계
| 카테고리 | 문서 수 | 링크 상태 |
|---|---|---|
| 백엔드 | 36개 | 정상 |
| 프론트엔드 | 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 | 데이터 바인딩 - 다국어 처리 | - |
카테고리별 전체 문서 목록
백엔드 (36개)
| 문서 | 제목 |
|---|---|
| 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) |
| 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) |
프론트엔드 (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/ | 멀티에이전트 시스템 소스 |