# 플러그인 시스템 개요
Clinic-OS의 플러그인은 **본관(코어)을 건드리지 않고 기능을 확장**하는 방법입니다. 마치 아파트 옆에 컨테이너 별채를 붙이는 것처럼, 본관은 그대로 두고 원하는 기능을 추가할 수 있습니다.
---
## 왜 플러그인을 사용하나요?
### 1. 안전한 커스터마이징
```
코어 파일 수정 플러그인 사용
────────────── ─────────────
src/pages/index.astro src/plugins/local/custom-homepage/
│ │
▼ ▼
업데이트 시 덮어쓰기 업데이트와 무관
│ │
▼ ▼
내 수정 사항 사라짐 내 코드 그대로 유지
```
**핵심 원리**: 코어 파일은 업데이트 시 새 버전으로 교체되지만, 플러그인 폴더는 건드리지 않습니다.
### 2. 쉬운 on/off 전환
문제가 생겼을 때:
- **코어 수정**: 어디서 뭘 잘못 건드렸는지 찾기 어려움
- **플러그인**: 관리자 화면에서 토글 하나로 비활성화
### 3. 독립적인 개발
각 플러그인은 독립된 폴더에서 관리됩니다:
- 병원 전용 VIP 관리 기능 → `src/plugins/local/vip-management/`
- 병원 전용 리뷰 요청 기능 → `src/plugins/local/review-request/`
하나의 플러그인에 문제가 생겨도 다른 플러그인과 코어는 영향 없음!
---
## 플러그인 종류
| 종류 | 설명 |
|------|------|
| 코어 플러그인 (Core) | Clinic-OS 팀 제공, 공식 플러그인 |
| 검증된 플러그인 (Verified) | 커뮤니티 개발, Clinic-OS 팀 검증 |
| 커뮤니티 플러그인 (Community) | 커뮤니티 자유 공유 |
---
## 플러그인 구조
```
src/plugins/local/my-plugin/
├── manifest.json ← 플러그인 정보 (필수)
├── README.md ← 사용 설명서
├── pages/ ← 페이지 컴포넌트
│ └── index.astro
├── components/ ← 재사용 컴포넌트
├── lib/ ← 헬퍼 함수
│ └── hooks.ts ← 이벤트 핸들러
└── migration.sql ← DB 마이그레이션 (선택)
```
새 로컬 플러그인은 에이전트가 아래 명령으로 시작하는 것이 권장됩니다.
```bash
npm run plugin:create -- --id=my-plugin --type=new-route --with-admin --dry-run --json
```
---
## 플러그인 관리
### 설치된 플러그인 확인
관리자 > 기능 허브에서 설치된 모든 플러그인을 확인할 수 있습니다.
### 플러그인 활성화/비활성화
각 플러그인 상세 페이지에서 토글 버튼으로 on/off 가능합니다.
### 새 플러그인 설치
가장 권장되는 설치 경로는 **로컬 관리자 `/admin/plugins/store`** 입니다.
AI에게 요청하세요:
```
로컬 설치본을 열고 /admin/plugins/store 에서 VIP 관리 플러그인을 설치해줘
```
직접 새 플러그인을 만들고 싶다면:
```
vip-management 플러그인을 새로 만들고, 스캐폴드부터 생성해줘
```
### 플러그인 삭제
```
VIP 관리 플러그인을 삭제해줘
```
---
## 페이지 오버라이드 시스템
### 작동 원리
```
사용자가 "/" 요청
│
▼
플러그인에 "/" 오버라이드가 있나?
│
YES ─┼── 플러그인 페이지 렌더링
│
NO ──┼── 코어 페이지 렌더링
```
### 커스텀 홈페이지 사용법
각 한의원마다 홈페이지 디자인이 다릅니다:
- A 한의원: 사진 갤러리 중심
- B 한의원: 의료진 소개 중심
- C 한의원: 프로모션 배너 중심
플러그인으로 각자 원하는 대로 커스터마이징 가능합니다.
**홈페이지 수정하기:**
1. 파일 열기:
`src/plugins/local/custom-homepage/pages/index.astro`
2. 에이전트에게 요청:
```
홈페이지에 진료 시간 안내 섹션을 추가해줘.
월-금 09:00-18:00, 토 09:00-13:00, 일 휴진
```
3. 결과 확인 후 배포
---
## 훅(Hook) 시스템
플러그인은 코어의 이벤트에 반응할 수 있습니다.
### 사용 가능한 훅
| 이벤트 | 발생 시점 | 활용 예 |
|--------|----------|--------|
| onPaymentCompleted | 결제 완료 시 | VIP 포인트 적립 |
| onPatientCreated | 환자 등록 시 | 웰컴 메시지 발송 |
| onVisitCheckin | 내원 체크인 시 | 리뷰 요청 예약 |
| onReservationCreated | 예약 생성 시 | 알림 발송 |
---
## 플러그인 개발 규칙
### 테이블 명명 규칙
```sql
-- 올바른 예: custom_ 접두사 필수
CREATE TABLE custom_vip_members (...);
CREATE TABLE custom_reviews (...);
-- 잘못된 예: 접두사 없음
CREATE TABLE vip_members (...);
ALTER TABLE patients ADD COLUMN ...; -- 코어 테이블 수정 금지!
```
### API 경로 규칙
```
/api/hub/{plugin-id}/... ← 플러그인 전용 경로
/api/patients/... ← 코어 API 경로 (사용 금지)
```
### 페이지 경로 규칙
```
/admin/hub/{plugin-id}/... ← 플러그인 관리 페이지
```
---
## 플러그인 스토어
[clinic-os-hq.pages.dev/plugins](https://clinic-os-hq.pages.dev/plugins)에서:
- 공개된 플러그인 검색
- 플러그인 상세 정보 확인
- 로컬 관리자 스토어 설치 경로 확인
---
## 요약
| 항목 | 코어 수정 | 플러그인 |
|-----|----------|---------|
| 업데이트 영향 | 덮어쓰기 위험 | 안전 |
| 롤백 | 어려움 | 토글로 간편 |
| 다른 기능 영향 | 있을 수 있음 | 격리됨 |
| 권장 상황 | 불가피할 때만 | 모든 커스터마이징 |
**기억하세요**: 뭔가 커스터마이징하고 싶다면, 먼저 플러그인으로 할 수 있는지 생각하세요!
---
## 관련 콘텐츠
- 📹 **관련 영상**: 커리큘럼 5-6. 플러그인으로 기능 추가
- 📋 **커리큘럼**: Stage 4 M5에서 다룸
- 🎯 **직원 투어**: 관리자 패널에서 **플러그인** 투어를 시작하세요
- [플러그인 공유하기](/guide#plugin-sharing) - HQ 스토어에 등록