Files
Gnuboard7/docs/frontend
HeuJung 3945b6f1b3 feat(core,extensions): 구동 에셋 자체 제공 · 자산 실패 폴백 · 운영자 추가 에셋(custom/)
공개 저장소 이슈 gnuboard/g7 (@bigmsg) 제보에서 출발한 작업이다.

브라우저가 화면을 그리려고 제3자 CDN 에 도달해야 하면, 그 도달 실패는 예외도 로그도
남기지 않고 화면 기능만 조용히 사라진다. 폐쇄망·방화벽·광고차단기에서 재현되는데
자체 서버 로그에는 흔적이 없어 운영자가 원인을 특정할 수 없다. 제보된 것은 편집기
하나였지만 같은 구조가 아이콘·글꼴·코드편집기·압축 라이브러리·설치 마법사·개발
대시보드에 똑같이 있었으므로, 번들 확장과 템플릿 전체를 자체 제공으로 옮겼다.
런타임에 외부로 나가는 것은 주소 검색 서비스 하나만 남았다.

자체 제공만으로는 부족하다 — 자기 서버에서 받는 파일도 실패할 수 있고, 종전에는 그
실패가 무음이었다. CSS 경로에 재시도 계층을 세우고(스크립트 경로와 동형), 서버가 HTML
에 직접 심는 externals 까지 실패를 붙잡아 안내 배너와 [다시 시도]로 표면화했다.
편집기·코드편집기는 확보 실패 시 평문 입력으로 내려앉되 저장 계약을 유지한다.

두 번째 축은 운영자가 CSS 를 덧붙일 자리가 없던 문제다(sir.kr 문의). 확장 디렉토리의
custom/ 을 운영자 소유로 정해, 확장 교체가 그 디렉토리만은 보존하게 했다. 출처에
의존하지 않는 서술자로 해석하므로 나중에 다른 출처가 붙어도 소비자는 바뀌지 않는다.
확장 자산과 같은 메커니즘으로 정적 게시되어 CSS 내부 상대 url 도 해석되고, 파일을
고치면 그 변경을 감지해 재게시까지 예약된다.

FTP 접근이 없는 운영자에게는 그 자리도 없는 것과 같으므로 레이아웃 편집기에서 직접
넣고 고칠 수 있게 했다. 모듈·플러그인·템플릿이 한 엔드포인트를 공유한다 — 타입별로
나누면 같은 검증이 세 벌로 갈리고 그중 약한 하나가 우회로가 된다. 여기서 올린
스크립트는 그 레이아웃 한 장이 아니라 사이트 전 화면에서 실행되므로 레이아웃 편집과
분리된 전용 권한으로 연다. 운영자 CSS 가 화면을 조작 불능으로 만들면 그것을 고칠
화면에도 같은 CSS 가 실려 스스로 갇히므로, 서버가 목록을 비우는 탈출구(?custom=off)를
함께 뒀다.

동봉 자산은 재생성 경로에 버전 대조 가드를 붙였다. 선언과 다른 버전을 버전 디렉토리에
써 넣는 조용한 거짓말은 배포된 뒤에는 드러나지 않는다.
2026-08-27 16:47:14 +09:00
..
2026-04-01 10:30:52 +09:00
2026-07-01 10:30:32 +09:00
2026-04-20 20:37:49 +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
2026-07-01 10:30:32 +09:00
2026-05-11 11:29:41 +09:00
2026-04-01 10:30:52 +09:00
2026-04-01 10:30:52 +09:00
2026-04-01 10:30:52 +09:00
2026-07-01 10:30:32 +09:00
2026-07-01 10:30:32 +09:00
2026-04-01 10:30:52 +09:00
2026-04-01 10:30:52 +09:00
2026-05-11 11:29:41 +09:00
2026-05-11 11:29:41 +09:00
2026-04-01 10:30:52 +09:00
2026-04-01 10:30:52 +09:00

그누보드7 프론트엔드 개발 가이드

이 문서는 그누보드7의 프론트엔드 및 템플릿 시스템 개발 규칙의 인덱스입니다.


핵심 원칙

필수: 기본 컴포넌트 사용 (HTML 태그 직접 사용 금지)
필수: 기본 컴포넌트만 사용 (Div, Button, H2 등)
✅ 필수: 집합 컴포넌트 재사용 우선
✅ 필수: 다크 모드 light/dark variant 함께 지정

템플릿 시스템 개요

그누보드7 템플릿 엔진은 JSON 기반 레이아웃 정의를 통해 화면을 동적으로 생성하는 시스템입니다.

핵심 특징:

  • JSON 기반 레이아웃 정의 (코드 수정 없이 UI 변경)
  • 컴포넌트 기반 아키텍처 (재사용성)
  • 동적 데이터 바인딩 (API 자동 연결)
  • 자동 발견 메커니즘 (/templates 디렉토리 스캔)
  • 코어 렌더링 엔진과 템플릿 컴포넌트 분리

템플릿 타입:

타입 레이아웃 편집 버전 히스토리 용도
admin ❌ 불가 ❌ 미사용 관리자 인터페이스
user ✅ 가능 ✅ 자동 생성 사용자 웹사이트

템플릿별 레퍼런스

템플릿 식별자 컴포넌트 핸들러 레이아웃
sirsoft-admin_basic components.md handlers.md layouts.md
sirsoft-basic components.md handlers.md layouts.md

컴포넌트 개발

문서 설명
component-props-composite.md 컴포넌트 Props 레퍼런스 - Composite
component-props.md 컴포넌트 Props 레퍼런스
components-advanced.md 컴포넌트 고급 기능
components-patterns.md 컴포넌트 패턴 및 다국어
components-types.md 컴포넌트 타입별 개발 규칙
components.md 컴포넌트 개발 규칙
layout-json-components-loading.md 레이아웃 JSON - 데이터 로딩 및 생명주기
layout-json-components-rendering.md 레이아웃 JSON - 조건부/반복 렌더링
layout-json-components-slots.md 레이아웃 JSON - 슬롯 시스템
layout-json-components.md 레이아웃 JSON - 컴포넌트 (반복 렌더링, Blur, 생명주기, 슬롯)

레이아웃 및 데이터

문서 설명
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 액션 핸들러 가이드
data-binding-i18n.md 데이터 바인딩 - 다국어 처리
data-binding.md 데이터 바인딩 및 표현식
data-sources-advanced.md 데이터 소스 - 고급 기능
data-sources.md 데이터 소스 (Data Sources)
g7core-api-advanced.md G7Core 전역 API 레퍼런스 - 고급
g7core-api.md G7Core 전역 API 레퍼런스
g7core-helpers.md G7Core 헬퍼 API
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 스키마
state-management-advanced.md 상태 관리 - 고급 기능
state-management-forms.md 상태 관리 - 폼 자동 바인딩 및 setState
state-management.md 전역 상태 관리

스타일링 및 UI

문서 설명
dark-mode.md 다크 모드 지원 (engine-v1.1.0+)
responsive-layout.md 반응형 레이아웃 개발 (engine-v1.1.0+)
tailwind-safelist.md Tailwind Safelist 가이드

템플릿 개발

문서 설명
editors.md 에디터 컴포넌트 가이드
template-development.md 템플릿 개발 가이드라인
template-handlers.md 템플릿 전용 핸들러

테스트

문서 설명
layout-testing.md 그누보드7 레이아웃 파일 렌더링 테스트 가이드

인증 및 보안

문서 설명
auth-system.md 인증 시스템 (AuthManager)
modal-usage.md Modal 컴포넌트 사용 가이드
security.md 보안 및 검증

기타

문서 설명
identity-guard-interceptor.md IdentityGuardInterceptor — 코어 본인인증 인터셉터 레퍼런스
identity-verification-ui.md 본인인증(IDV) 공통 UI 가이드

컴포넌트 타입 요약

타입 설명 예시
basic HTML 태그 래핑 Button, Input, Div, Icon
composite 기본 컴포넌트 조합 Card, Modal, PageHeader, DataGrid
layout 자식 요소 배치 Container, Grid, Flex

데이터 바인딩 문법 (빠른 참조)

{
  "props": {
    "title": "{{user.name}}",              // API 데이터
    "userId": "{{route.id}}",              // URL 파라미터
    "label": "$t:dashboard.title",         // 다국어
    "total": "{{users?.data?.total ?? 0}}" // Optional Chaining + Nullish Coalescing
  }
}

다크 모드 색상 매핑 (빠른 참조)

배경:   bg-white dark:bg-gray-800
테두리: border-gray-200 dark:border-gray-700
텍스트: text-gray-900 dark:text-white
강조:   bg-green-50 dark:bg-green-900/20

관련 문서