플러그인 확장하기

이 가이드는 병원에 필요한 기능을 에이전트와 새 플러그인으로 추가할 때 쓰는 작업 안내입니다. 기능을 둘 위치, 켜고 끄는 방법, 업데이트 뒤 확인 순서를 따라가면 홈페이지 본체를 직접 바꾸지 않고 확장할 수 있습니다.

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

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/
커스텀 홈페이지 → src/plugins/local/custom-homepage/

하나의 플러그인에 문제가 생겨도 다른 플러그인과 코어는 영향 없음!

플러그인과 스킨의 차이

둘 다 에이전트가 다루는 재사용 단위지만 목적이 다릅니다.

플러그인: 기능, 경로, API, 관리자 탭을 확장
스킨: 퍼블릭 페이지의 분위기, 상세 템플릿, Hero override를 조정

즉, 새 기능이 필요하면 플러그인, 디자인 시스템 단위로 퍼블릭을 바꾸고 싶으면 스킨 경로를 쓰는 편이 맞습니다.

스킨 쪽은 스킨 라이브러리와 에이전트 드리븐 스킨 작업에서 따로 다룹니다.

플러그인 종류

코어 플러그인 (Core)

Clinic-OS 팀에서 제공하는 공식 플러그인. 기본 설치되어 있거나 스토어에서 무료로 설치 가능.

플러그인	설명	기본 설치
커스텀 홈페이지	메인 페이지 자유 커스터마이징	O

검증된 플러그인 (Verified)

커뮤니티 개발자가 만들고, Clinic-OS 팀에서 검증한 플러그인.

커뮤니티 플러그인 (Community)

커뮤니티 개발자가 자유롭게 공유하는 플러그인.

플러그인 구조

플러그인 폴더는 이런 구조로 되어 있습니다:

src/plugins/local/my-plugin/
├── manifest.json       ← 플러그인 정보 (필수)
├── README.md          ← 사용 설명서
├── pages/             ← 페이지 컴포넌트
│   └── index.astro    ← 홈페이지 오버라이드
├── components/        ← 재사용 컴포넌트
├── lib/               ← 헬퍼 함수
│   └── hooks.ts       ← 이벤트 핸들러
└── migration.sql      ← DB 마이그레이션 (선택)

manifest.json 예시

{
  "id": "custom-homepage",
  "name": "커스텀 홈페이지",
  "description": "메인 홈페이지를 자유롭게 커스터마이징",
  "version": "1.0.0",
  "author": "Clinic-OS",
  "category": "customization",
  "documentation": {
    "summary": "코어 코드를 건드리지 않고...",
    "features": ["홈페이지 오버라이드", "..."],
    "howToEdit": "pages/index.astro 수정"
  },
  "overrides": [
    { "path": "/", "file": "pages/index.astro", "priority": 10 }
  ]
}

플러그인 관리

설치된 플러그인 확인

관리자 > 기능 허브에서 설치된 모든 플러그인을 확인할 수 있습니다.

플러그인 활성화/비활성화

각 플러그인 상세 페이지에서 토글 버튼으로 on/off 가능. (super_admin 권한 필요)

새 플러그인 설치

AI에게 요청하세요: 로컬 설치본을 열고 /admin/plugins/store 에서 VIP 관리 플러그인을 설치해줘

또는 스토어에서 원하는 플러그인을 찾아 설치를 요청: 이 플러그인을 로컬 관리자 스토어에서 설치해줘: https://clinic-os.moden.marketing/plugins/vip-management

새 플러그인 생성

사람이 구조를 외우기보다 에이전트에게 이렇게 요청하는 편이 맞습니다.

vip-management 플러그인 뼈대를 만들어줘.
관리 탭과 API도 같이 필요해.

에이전트는 내부적으로 npm run plugin:create 를 사용해 구조를 만들고, 그 다음 세부 구현을 이어갑니다.

플러그인 삭제

VIP 관리 플러그인을 삭제해줘

커스텀 홈페이지 사용법

왜 홈페이지가 플러그인인가요?

각 한의원마다 홈페이지 디자인이 다릅니다:

A 한의원: 사진 갤러리 중심
B 한의원: 의료진 소개 중심
C 한의원: 프로모션 배너 중심

코어에 고정하면: 모든 한의원이 같은 홈페이지를 써야 함 플러그인이면: 각자 원하는 대로 커스터마이징 가능

홈페이지 수정하기

파일 열기:

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

에이전트에게 요청:

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

결과 확인 후 배포:

수정 내용 확인했어. 배포해줘

원본 홈페이지로 돌아가기

관리자 > 기능 허브 > 커스텀 홈페이지
토글 버튼 클릭 → 비활성화
코어의 기본 홈페이지가 표시됨

페이지 오버라이드 시스템

작동 원리

사용자가 "/" 요청
       ↓
플러그인에 "/" 오버라이드가 있나?
       ↓
  YES → 플러그인 페이지 렌더링
  NO  → 코어 페이지 렌더링

우선순위

여러 플러그인이 같은 경로를 오버라이드하면 priority 값이 높은 것이 적용됩니다.

// manifest.json
{
  "overrides": [
    { "path": "/", "file": "pages/index.astro", "priority": 10 }
  ]
}

훅(Hook) 시스템

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

사용 가능한 훅

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

훅 핸들러 예시

// src/plugins/local/vip-management/lib/hooks.ts

export async function addPoints(context: HookContext) {
  const { db, data } = context;
  const { patientId, amount } = data;

  // VIP 포인트 적립 로직
  await db.prepare(`
    INSERT INTO custom_vip_point_history (patient_id, amount, type)
    VALUES (?, ?, 'earn')
  `).bind(patientId, Math.floor(amount * 0.01)).run();
}

플러그인 개발 규칙

테이블 명명 규칙

-- 올바른 예: 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}/...  ← 플러그인 관리 페이지
오버라이드 시스템 사용       ← 퍼블릭 페이지 교체
코어 페이지 직접 수정 금지

실전 예제: 리뷰 요청 플러그인

고객이 시술을 받고 나면 자동으로 리뷰 요청 문자를 보내는 플러그인을 만들어봅시다.

에이전트에게 한 번에 요청

AI에게 이렇게 요청하면 됩니다:

리뷰 요청 플러그인을 만들어줘.

기능:
- 환자가 체크인하면 24시간 후에 리뷰 요청 문자 발송
- custom_review_requests 테이블에 예약 정보 저장
- 관리자 페이지에서 발송 내역 확인 가능

훅:
- onVisitCheckin 이벤트에 연결

AI가 자동으로:

src/plugins/review-request/ 폴더 생성
manifest.json 작성
훅 핸들러 코드 작성
마이그레이션 SQL 생성
installed.json 업데이트

결과물 구조

src/plugins/review-request/
├── manifest.json       ← 플러그인 메타데이터
├── lib/
│   └── hooks.ts        ← onVisitCheckin 핸들러
├── pages/
│   └── admin.astro     ← 발송 내역 페이지
└── migration.sql       ← 테이블 생성 SQL

플러그인 스토어

HQ 플러그인 스토어

clinic-os.moden.marketing/plugins에서:

공개된 플러그인 검색
플러그인 상세 정보 확인
설치 방법 안내

스토어에서 마음에 드는 플러그인을 찾으면:

이 플러그인 설치해줘: [플러그인 URL]

내 플러그인 공유하기

AI에게 요청하세요:

이 플러그인을 HQ 스토어에 제출해줘