HeuJung
8328b1db77
S1 파일럿 3종(sirsoft-board · sirsoft-gdpr · sirsoft-admin_basic)에 이어
결제·본인인증 동형군 6종의 AGENTS.md · README.md · docs/ 5문서를 집필했다.
확장을 고치려는 쪽이 매번 src/ 를 훑어 구조를 재발견하지 않도록, 설계 의도와
확장점(발행·구독 훅)·수정 시 동반 의무·금지 패턴을 코드 근거로 서술했다.
생성기(ExtensionDocScaffolder)에서 표를 무의미하게 만들던 세 결함을 함께 고쳤다.
getLayoutExtensions 기본 구현이 돌려주는 절대경로가 파일 목록과 중복돼 로컬
머신 경로가 커밋 문서에 실리던 문제, getNotificationDefinitions 를 'key'/'event'
로 읽어 모든 행이 '-' 로 찍히던 문제, getSettingsLayout 절대경로가 정규화 없이
노출되던 문제다. 셋 다 예외를 남기지 않고 표만 조용히 망가뜨리므로
ExtensionDocContractTest 에 각각의 되돌림 red 를 확인한 단언을 두었다.
템플릿의 extensions/{id}/ 는 모듈·플러그인의 발행과 반대 방향(오버라이드)이라
별도 블록(template-overrides)으로 분리했다.
sirsoft-admin_basic 의 컴포넌트·핸들러·레이아웃 문서를 코어 docs/ 에서 그 템플릿
소유로 이관하고, 남은 참조 6축을 재는 가드를 추가했다. 이관 후 남은 옛 경로는
오류가 아니라 헛걸음으로만 나타나 드러나지 않는다. 의 상대 링크가
한 단계 얕아 공유 docs/ 대신 를 가리키던 문제도 함께 고쳤다.
README 상단의 확장명 이미지 배지를 평문 H1 로 바꿨다( 지시 2026-08-31).
루트 README.md · README.ko.md 도 같은 기준을 적용했다. 정보 배지는 유지한다.
sirsoft-gdpr: 회원탈퇴로 자동 철회된 동의가 관리자 동의 이력 화면의 출처 필터로
걸러지지 않던 문제를 고쳤다. Repository 가 'withdraw' 리터럴을 직접 UPDATE 에
싣는데 그 값이 ConsentSource enum 에 없어, 화면 필터 옵션·라벨 어느 쪽에도
도달하지 못했다. 어휘를 enum 단일 출처로 모으고 ko·en·ja 라벨과 필터 옵션을
함께 채웠으며, 어휘 대조 테스트의 모집단에 Repository 를 편입했다.
7.6 KiB
7.6 KiB
그누보드7 프론트엔드 개발 가이드
이 문서는 그누보드7의 프론트엔드 및 템플릿 시스템 개발 규칙의 인덱스입니다.
핵심 원칙
필수: 기본 컴포넌트 사용 (HTML 태그 직접 사용 금지)
필수: 기본 컴포넌트만 사용 (Div, Button, H2 등)
✅ 필수: 집합 컴포넌트 재사용 우선
✅ 필수: 다크 모드 light/dark variant 함께 지정
템플릿 시스템 개요
그누보드7 템플릿 엔진은 JSON 기반 레이아웃 정의를 통해 화면을 동적으로 생성하는 시스템입니다.
핵심 특징:
- JSON 기반 레이아웃 정의 (코드 수정 없이 UI 변경)
- 컴포넌트 기반 아키텍처 (재사용성)
- 동적 데이터 바인딩 (API 자동 연결)
- 자동 발견 메커니즘 (
/templates디렉토리 스캔) - 코어 렌더링 엔진과 템플릿 컴포넌트 분리
템플릿 타입:
| 타입 | 레이아웃 편집 | 버전 히스토리 | 용도 |
|---|---|---|---|
| admin | ❌ 불가 | ❌ 미사용 | 관리자 인터페이스 |
| user | ✅ 가능 | ✅ 자동 생성 | 사용자 웹사이트 |
템플릿별 레퍼런스
| 템플릿 식별자 | 컴포넌트 | 핸들러 | 레이아웃 |
|---|---|---|---|
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, 생명주기, 슬롯) |
레이아웃 및 데이터
스타일링 및 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
관련 문서
- AGENTS.md - 그누보드7 개발 가이드 (메인)
- backend/ - 백엔드 개발 규칙
- database-guide.md - 데이터베이스 규칙
- testing-guide.md - 테스트 규칙