|
| 1 | +# 플러그인 시스템 설계 (Plugin System Design) |
| 2 | + |
| 3 | +> **상태:** 초안 (Draft) |
| 4 | +> **최종 업데이트:** 2026-03-25 |
| 5 | +> **관련 결정 사항:** `architecture/01-decisions.md` 결정 #1, #5 |
| 6 | +
|
| 7 | +--- |
| 8 | + |
| 9 | +## 1. 개요 (Overview) |
| 10 | + |
| 11 | +Fieldstack의 플러그인 시스템은 Core의 최소 기능을 유지하면서, 시스템 전반에 걸친 **리소스 확장**과 **고급 기능 추가**를 가능하게 하는 **확장 계층(Extension Layer)**입니다. |
| 12 | + |
| 13 | +사용자는 마켓플레이스를 통해 새로운 언어 팩, 테마, 혹은 고성능 데이터 인터페이스(GraphQL) 등을 자유롭게 설치하고 관리할 수 있습니다. |
| 14 | + |
| 15 | +--- |
| 16 | + |
| 17 | +## 2. Core / Resource / Functional 구분 |
| 18 | + |
| 19 | +플러그인은 역할과 배포 방식에 따라 크게 세 가지 유형으로 구분됩니다. |
| 20 | + |
| 21 | +### 2.1 Core Systems (기본 내장) |
| 22 | +Core 엔진에 기본적으로 포함되어 항상 작동하는 핵심 인프라입니다. |
| 23 | +- **i18n 엔진**: 언어 팩 로딩, 번역 함수(`t()`), 날짜/숫자 포맷팅. |
| 24 | +- **Theme 엔진**: Light/Dark 모드 전환, CSS 변수 관리, 시스템 폰트 제어. |
| 25 | +- **지원**: 한국어(기본), 영어(기본), 공식 Default Light/Dark 테마. |
| 26 | + |
| 27 | +### 2.2 리소스 플러그인 (Resource Plugins) |
| 28 | +데이터 파일(JSON, CSS) 위주로 구성된 확장 팩입니다. 전용 리소스 폴더에 설치되어 Core 엔진에 의해 로드됩니다. |
| 29 | +- **다국어 팩 (i18n Packs)**: 공식 번역 플랫폼에서 검수된 추가 언어 파일. 마켓플레이스에서 다운로드하거나 공식 패치를 통해 자동 업데이트. |
| 30 | +- **테마 팩 (Theme Packs)**: 시즌 테마, 콜라보 테마 등 공식적으로 제공되는 시각적 스킨. 전용 테마 폴더에 위치하며 설정 메뉴에서 즉시 선택 가능. |
| 31 | + |
| 32 | +### 2.3 기능형 플러그인 (Functional Plugins) |
| 33 | +시스템의 동작 방식이나 데이터 인터페이스를 확장하는 로직 중심의 확장 모듈입니다. |
| 34 | +- **GraphQL Gateway**: REST API를 분석하여 통합 GraphQL 엔드포인트를 노출하는 고성능 데이터 레이어. |
| 35 | +- **특징**: 런타임에 로드되며, 사용자의 하드웨어 리소스 상황에 따라 선택적으로 활성/비활성화 가능. |
| 36 | + |
| 37 | +--- |
| 38 | + |
| 39 | +## 3. 플러그인 관리 및 배포 (Deployment) |
| 40 | + |
| 41 | +### 3.1 마켓플레이스 통합 |
| 42 | +사용자는 관리 UI의 마켓플레이스 탭에서 원하는 리소스나 기능을 검색하고 설치할 수 있습니다. |
| 43 | +- **설치**: 설치 버튼 클릭 시 백그라운드에서 해당 리소스 폴더(예: `locales/`, `themes/`, `plugins/`)로 파일이 다운로드 및 배치됩니다. |
| 44 | +- **업데이트**: 공식 다국어 패치나 테마 업데이트가 있을 경우 알림을 통해 자동으로 최신 버전을 적용할 수 있습니다. |
| 45 | + |
| 46 | +### 3.2 공식 다국어 작업 프로세스 |
| 47 | +- **검수**: 별도의 공식 번역 플랫폼에서 작업된 내용은 검수를 거쳐 공식 패치 또는 다음 정기 업데이트에 포함됩니다. |
| 48 | +- **적용**: 사용자는 업데이트를 통해 새로운 언어 지원을 즉시 받을 수 있습니다. |
| 49 | + |
| 50 | +--- |
| 51 | + |
| 52 | +## 4. 기술적 동작 원리: Hook 시스템 |
| 53 | + |
| 54 | +기능형 플러그인(GraphQL 등)은 Core와 모듈이 제공하는 **Hooks**를 통해 시스템에 개입합니다. |
| 55 | + |
| 56 | +1. **Lifecycle Hooks**: 시스템 시작 시 플러그인 초기화 및 스키마 생성. |
| 57 | +2. **Action Hooks**: 특정 API 호출 시 데이터를 가로채거나 추가 로직 수행. |
| 58 | +3. **Filter Hooks**: 번역 텍스트나 테마 설정값을 실시간으로 변조하여 적용. |
| 59 | + |
| 60 | +--- |
| 61 | + |
| 62 | +## 5. 향후 과제 (Future Works) |
| 63 | + |
| 64 | +- [ ] **Resource Loader**: 각 리소스 폴더(`locales/`, `themes/`)의 변화를 실시간으로 감지하고 UI에 반영하는 로직 구현. |
| 65 | +- [ ] **GraphQL Introspection**: OpenAPI 스펙을 GraphQL 스키마로 자동 변환하는 엔진 개발. |
| 66 | +- [ ] **보안 및 권한**: 외부 리소스/플러그인이 시스템의 핵심 보안을 해치지 않도록 검증 프로세스 수립. |
| 67 | + |
| 68 | +--- |
| 69 | + |
| 70 | +## 📚 관련 문서 |
| 71 | +- 📖 `architecture/02-core-principles.md` - Core / Module / Plugin 분리 철학 |
| 72 | +- 📖 `ui/02-theme-policy.md` - 공식 테마 운영 정책 |
| 73 | +- 📖 `roadmap/01-development-plan.md` - 기술 로드맵 |
0 commit comments