플러그인 시스템 개요

플러그인은 홈페이지 본체를 직접 고치지 않고 예약·후기·VIP 관리 같은 기능을 추가하는 방법입니다. 문제가 생기면 해당 기능만 끌 수 있고, ClinicOS 업데이트를 받아도 병원별 기능을 따로 유지할 수 있습니다.

왜 플러그인을 사용하나요?

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 마이그레이션 (선택)

새 로컬 플러그인은 에이전트가 아래 명령으로 시작하는 것이 권장됩니다.

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 한의원: 프로모션 배너 중심

플러그인으로 각자 원하는 대로 커스터마이징 가능합니다.

홈페이지 수정하기:

파일 열기:

src/plugins/local/custom-homepage/pages/index.astro

에이전트에게 요청:

홈페이지에 진료 시간 안내 섹션을 추가해줘.
월-금 09:00-18:00, 토 09:00-13:00, 일 휴진

결과 확인 후 배포

훅(Hook) 시스템

플러그인은 코어의 이벤트에 반응할 수 있습니다.

사용 가능한 훅

이벤트	발생 시점	활용 예
onPaymentCompleted	결제 완료 시	VIP 포인트 적립
onPatientCreated	환자 등록 시	웰컴 메시지 발송
onVisitCheckin	내원 체크인 시	리뷰 요청 예약
onReservationCreated	예약 생성 시	알림 발송

플러그인 개발 규칙

테이블 명명 규칙

-- 올바른 예: 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에서:

공개된 플러그인 검색
플러그인 상세 정보 확인
로컬 관리자 스토어 설치 경로 확인

요약

항목	코어 수정	플러그인
업데이트 영향	덮어쓰기 위험	안전
롤백	어려움	토글로 간편
다른 기능 영향	있을 수 있음	격리됨
권장 상황	불가피할 때만	모든 커스터마이징

기억하세요: 뭔가 커스터마이징하고 싶다면, 먼저 플러그인으로 할 수 있는지 생각하세요!