# 🏥 팜큐(FARMQ) Headplane 커스터마이징 기획서

## 📋 프로젝트 개요

### 회사 현황
- **회사명**: 팜큐(FARMQ)
- **사업 규모**: 약국 100개소
- **인프라**: 각 약국마다 Proxmox 호스트 PC 납품
- **관리 대상**: 약국별 VM 환경 원격 관리
- **네트워크**: WireGuard 기반 Headscale + Headplane 전환 완료

### 현재 환경
- ✅ **Headscale 서버**: http://192.168.0.151:8070 (정상 운영)
- ✅ **Headplane UI**: http://192.168.0.151:3000/admin/ (정상 운영)
- ✅ **VPN 네트워크**: 100.64.0.0/10 대역 할당
- ✅ **기본 기능**: Machine/User 관리 가능

### 개선 목표
현재 기본 Headplane UI를 **팜큐 전용 약국 관리 시스템**으로 확장

## 🎯 요구사항 분석

### 1. 데이터 확장 요구사항

#### 현재 User 테이블 구조
```
User    | Role      | Created At  | Last Seen
myuser  | Unmanaged | 2025.9.9    | Connected
```

#### 확장 요구사항
```
User     | 약국명    | 사업자번호     | Role      | Created At  | Last Seen
myuser   | 서울약국   | 123-45-67890  | Unmanaged | 2025.9.9    | Connected
```

#### Machine 정보 확장 요구사항
- **현재**: Machine 이름만 관리
- **확장 후**: 
  - 약국명 연동
  - PC 사양 정보 (CPU, RAM, Storage)
  - Proxmox 호스트 정보
  - 실시간 하드웨어 모니터링

### 2. 모니터링 요구사항
- **Proxmox API 연동**: CPU 온도, 사용률, VM 상태
- **실시간 대시보드**: 약국별 시스템 현황
- **알림 시스템**: 장애 발생 시 실시간 알림

## 🏗️ 아키텍처 설계

### 시스템 구조
```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Headplane UI  │───►│  Custom Backend  │───►│  Proxmox Hosts  │
│  (Frontend)     │    │   (API Server)   │    │  (100개 약국)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         │                       ▼                       │
         │              ┌──────────────────┐             │
         └─────────────►│   Headscale DB   │◄────────────┘
                        │   (Extended)     │
                        └──────────────────┘
```

### 데이터베이스 확장 설계

#### 새로운 테이블: `pharmacy_info`
```sql
CREATE TABLE pharmacy_info (
    id SERIAL PRIMARY KEY,
    user_id VARCHAR(255) UNIQUE REFERENCES users(name),
    pharmacy_name VARCHAR(255) NOT NULL,
    business_number VARCHAR(20),
    address TEXT,
    phone VARCHAR(20),
    manager_name VARCHAR(100),
    proxmox_host VARCHAR(255),
    proxmox_api_token TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
```

#### 새로운 테이블: `machine_specs`
```sql
CREATE TABLE machine_specs (
    id SERIAL PRIMARY KEY,
    machine_id BIGINT REFERENCES machines(id),
    pharmacy_id INTEGER REFERENCES pharmacy_info(id),
    cpu_model VARCHAR(255),
    cpu_cores INTEGER,
    ram_gb INTEGER,
    storage_gb INTEGER,
    gpu_model VARCHAR(255),
    last_updated TIMESTAMP DEFAULT NOW()
);
```

#### 새로운 테이블: `monitoring_data`
```sql
CREATE TABLE monitoring_data (
    id SERIAL PRIMARY KEY,
    machine_id BIGINT REFERENCES machines(id),
    cpu_usage DECIMAL(5,2),
    memory_usage DECIMAL(5,2),
    disk_usage DECIMAL(5,2),
    cpu_temperature INTEGER,
    network_rx_bytes BIGINT,
    network_tx_bytes BIGINT,
    vm_count INTEGER,
    vm_running INTEGER,
    collected_at TIMESTAMP DEFAULT NOW()
);
```

## 🛠️ 구현 방안

### 방안 1: Headplane 포크 + 직접 수정 (권장)
**장점**: 완전한 커스터마이징 가능  
**단점**: 업스트림 업데이트 반영 어려움  
**개발 기간**: 2-3주

#### 구현 단계:
1. **포크 및 개발환경 구성**
2. **데이터베이스 스키마 확장**
3. **API 엔드포인트 추가**
4. **UI 컴포넌트 커스터마이징**
5. **Proxmox API 연동 모듈 개발**
6. **모니터링 대시보드 구현**

### 방안 2: 별도 관리 시스템 + Headplane 연동
**장점**: 기존 Headplane 유지, 독립적 개발  
**단점**: 시스템 분리로 복잡도 증가  
**개발 기간**: 3-4주

### 방안 3: Headplane 플러그인 시스템 구축
**장점**: 모듈러 구조, 확장성 좋음  
**단점**: 플러그인 시스템 자체 개발 필요  
**개발 기간**: 4-5주

## 📋 세부 기능 명세

### 1. 약국 정보 관리
#### 1-1. 약국 등록/수정 화면
```
┌─────────────────────────────────────┐
│ 약국 정보 등록                       │
├─────────────────────────────────────┤
│ 약국명: [서울중앙약국           ]    │
│ 사업자번호: [123-45-67890       ]   │
│ 주소: [서울시 강남구...        ]    │
│ 전화번호: [02-1234-5678        ]    │
│ 담당자: [홍길동               ]     │
│ Proxmox 호스트: [192.168.1.100 ]   │
│ API 토큰: [********************]   │
│                                     │
│ [저장] [취소]                       │
└─────────────────────────────────────┘
```

#### 1-2. 사용자 테이블 확장
```
User     | 약국명      | 사업자번호     | 전화번호      | Role      | Last Seen
pharmacy1| 서울중앙약국 | 123-45-67890  | 02-1234-5678 | Active    | 5분 전
pharmacy2| 부산해운약국 | 987-65-43210  | 051-9876-5432| Active    | 1시간 전
```

### 2. 머신 정보 확장
#### 2-1. 머신 상세 정보 화면
```
┌─────────────────────────────────────┐
│ 머신 상세 정보: pharmacy1-main       │
├─────────────────────────────────────┤
│ 약국명: 서울중앙약국                 │
│ IP 주소: 100.64.0.15               │
│ 마지막 접속: 2분 전                 │
│                                     │
│ 하드웨어 정보:                      │
│ CPU: Intel i7-12700 (12코어)       │
│ RAM: 32GB                          │
│ Storage: 1TB NVMe SSD              │
│                                     │
│ 실시간 모니터링:                    │
│ CPU 사용률: ████████░░ 80%         │
│ CPU 온도: 65°C                     │
│ 메모리 사용률: ██████░░░░ 60%      │
│ 디스크 사용률: ███░░░░░░░ 30%      │
│                                     │
│ VM 상태:                           │
│ 총 VM: 5개 | 실행중: 4개 | 정지: 1개│
└─────────────────────────────────────┘
```

### 3. 통합 대시보드
#### 3-1. 메인 대시보드 레이아웃
```
┌────────────────────────────────────────────────────────────┐
│ 팜큐 약국 관리 시스템                    [사용자: admin]   │
├────────────────────────────────────────────────────────────┤
│ 📊 전체 현황                                               │
│ ┌──────────┬──────────┬──────────┬──────────────────────┐  │
│ │총 약국 수 │온라인    │오프라인   │평균 CPU 온도         │  │
│ │   100    │   95     │    5     │       62°C           │  │
│ └──────────┴──────────┴──────────┴──────────────────────┘  │
│                                                            │
│ 🚨 알림                                                    │
│ • 부산해운약국: CPU 온도 85°C (경고)                      │
│ • 대구중앙약국: 디스크 사용률 95% (위험)                  │
│                                                            │
│ 📈 약국별 상태                                             │
│ ┌─────────────┬────────┬────────┬────────┬──────────────┐ │
│ │약국명        │상태    │CPU온도  │메모리   │마지막 접속    │ │
│ ├─────────────┼────────┼────────┼────────┼──────────────┤ │
│ │서울중앙약국   │🟢 온라인│  65°C  │  80%   │    2분 전    │ │
│ │부산해운약국   │🟡 경고  │  85°C  │  60%   │    5분 전    │ │
│ │대구중앙약국   │🔴 위험  │  70°C  │  95%   │   10분 전    │ │
│ └─────────────┴────────┴────────┴────────┴──────────────┘ │
└────────────────────────────────────────────────────────────┘
```

### 4. Proxmox API 연동
#### 4-1. 데이터 수집 프로세스
```python
# proxmox_monitor.py
class ProxmoxMonitor:
    def collect_host_info(self, proxmox_host, api_token):
        """Proxmox 호스트 정보 수집"""
        # CPU 온도, 사용률
        # 메모리 사용률
        # 디스크 사용률
        # VM 상태 및 개수
        # 네트워크 트래픽
        
    def collect_vm_info(self, proxmox_host, vm_id):
        """개별 VM 정보 수집"""
        # VM 상태 (running, stopped)
        # 리소스 할당량
        # 실제 리소스 사용량
```

## 🔧 기술 스택

### Frontend (Headplane 기반)
- **React 19.1.0** + TypeScript
- **Tailwind CSS** (스타일링)
- **React Router** (라우팅)
- **Chart.js** (모니터링 차트)
- **Socket.io Client** (실시간 업데이트)

### Backend (확장 API 서버)
- **Node.js** + Express.js 또는 **Python FastAPI**
- **PostgreSQL** (확장된 데이터베이스)
- **Socket.io** (실시간 통신)
- **Proxmox API Client**
- **Cron Jobs** (주기적 데이터 수집)

### 모니터링 스택
- **Proxmox API** (호스트 정보)
- **Glances API** (시스템 메트릭)
- **InfluxDB** (시계열 데이터 저장)
- **Redis** (캐싱 및 실시간 데이터)

## 📅 개발 로드맵

### Phase 1: 기반 구축 (1주)
- [ ] Headplane 포크 및 개발환경 구성
- [ ] 데이터베이스 스키마 설계 및 확장
- [ ] 기본 약국 정보 CRUD API 구현
- [ ] UI 기본 레이아웃 수정

### Phase 2: 핵심 기능 (2주)
- [ ] 사용자 테이블에 약국 정보 연동
- [ ] 머신 정보 확장 및 UI 개선
- [ ] Proxmox API 연동 모듈 개발
- [ ] 기본 모니터링 대시보드 구현

### Phase 3: 고도화 (1주)
- [ ] 실시간 모니터링 구현
- [ ] 알림 시스템 구축
- [ ] 통합 대시보드 완성
- [ ] 성능 최적화 및 테스트

### Phase 4: 배포 및 운영 (1주)
- [ ] 프로덕션 환경 배포
- [ ] 100개 약국 데이터 마이그레이션
- [ ] 운영 매뉴얼 작성
- [ ] 사용자 교육 및 피드백 수집

## 💰 예상 비용 및 리소스

### 개발 리소스
- **개발 기간**: 4-5주
- **개발자**: 풀스택 개발자 1명
- **디자이너**: UI/UX 디자이너 0.5명

### 인프라 비용
- **확장 서버**: 추가 서버 인스턴스 (모니터링 데이터 처리)
- **데이터베이스**: PostgreSQL + InfluxDB
- **스토리지**: 시계열 데이터 저장용

## 🚀 시작하기

### 1단계: 요구사항 확정
- [ ] 약국 정보 필드 최종 확정
- [ ] 모니터링 지표 우선순위 결정
- [ ] UI/UX 디자인 컨셉 결정

### 2단계: 개발환경 구성
- [ ] Headplane 포크 및 클론
- [ ] 로컬 개발환경 세팅
- [ ] 테스트용 Proxmox 호스트 준비

### 3단계: 프로토타입 개발
- [ ] 약국 정보 등록 화면 구현
- [ ] 기본 모니터링 기능 구현
- [ ] 초기 버전 데모

## 📊 성공 지표

### 기능적 지표
- [ ] 100개 약국 정보 완전 등록
- [ ] 실시간 모니터링 정확도 95% 이상
- [ ] 알림 반응 시간 1분 이내
- [ ] 시스템 가용성 99.5% 이상

### 사용성 지표
- [ ] 관리자 업무 효율 50% 향상
- [ ] 장애 발견 시간 80% 단축
- [ ] 사용자 만족도 4.5/5.0 이상

## 📝 체크리스트

### 즉시 검토 필요사항
- [ ] 현재 Headscale DB 구조 분석
- [ ] Proxmox API 접근 권한 확인
- [ ] 약국별 네트워크 접근성 테스트
- [ ] 추가 하드웨어 리소스 요구사항 검토

### 장기적 고려사항
- [ ] 확장성: 약국 수 증가 대비
- [ ] 보안: 약국 데이터 보호
- [ ] 백업: 중요 데이터 백업 전략
- [ ] 업데이트: 원활한 시스템 업데이트 방안

---
**📅 작성일**: 2025-09-09  
**👤 작성자**: Claude Code Assistant  
**🏢 대상**: 팜큐(FARMQ) - 약국 IT 인프라 관리 시스템