플러그인 시스템 개요

# 플러그인 시스템 개요 Clinic-OS의 플러그인은 **본관(코어)을 건드리지 않고 기능을 확장**하는 방법입니다. 마치 아파트 옆에 컨테이너 별채를 붙이는 것처럼, 본관은 그대로 두고 원하는 기능을 추가할 수 있습니다. ![플러그인 개요](/images/guides/plugin-overview.png) --- ## 왜 플러그인을 사용하나요? ### 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.moden.marketing/plugins](https://clinic-os.moden.marketing/plugins)에서: - 공개된 플러그인 검색 - 플러그인 상세 정보 확인 - 로컬 관리자 스토어 설치 경로 확인 --- ## 요약 | 항목 | 코어 수정 | 플러그인 | |-----|----------|---------| | 업데이트 영향 | 덮어쓰기 위험 | 안전 | | 롤백 | 어려움 | 토글로 간편 | | 다른 기능 영향 | 있을 수 있음 | 격리됨 | | 권장 상황 | 불가피할 때만 | 모든 커스터마이징 | **기억하세요**: 뭔가 커스터마이징하고 싶다면, 먼저 플러그인으로 할 수 있는지 생각하세요! --- ## 관련 콘텐츠 - 📹 **관련 영상**: 커리큘럼 5-6. 플러그인으로 기능 추가 - 📋 **워크숍**: W4 M5에서 다룸 - 🎯 **직원 투어**: 관리자 패널에서 **플러그인** 투어를 시작하세요 - [플러그인 공유하기](/guides/plugin-sharing) - HQ 스토어에 등록

플러그인 시스템 개요

이 페이지에서 확인할 내용