From 247b9dbee7e4f5ef396f5c71efe1aff1d4727c95 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=8B=9C=EA=B3=A8=EC=95=BD=EC=82=AC?= <thug0bin@gmail.com>
Date: Tue, 9 Sep 2025 15:34:12 +0900
Subject: [PATCH] =?UTF-8?q?=F0=9F=8F=A5=20Add=20FARMQ=20Headplane=20custom?=
 =?UTF-8?q?ization=20business=20plan?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comprehensive business plan for customizing Headplane for FARMQ:
- Company overview: 100 pharmacies with Proxmox infrastructure
- Current system analysis: Working Headscale + Headplane setup
- Enhancement requirements: Pharmacy info, machine specs, monitoring
- Database schema design: pharmacy_info, machine_specs, monitoring_data
- Implementation approaches: Fork vs separate system vs plugin
- Technical specifications: React frontend + API backend + Proxmox integration
- Development roadmap: 4-5 weeks phased implementation
- Success metrics and cost analysis

Ready for pharmacy management system development based on existing Headplane.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 FARMQ_HEADPLANE_CUSTOMIZATION_PLAN.md | 349 ++++++++++++++++++++++++++
 1 file changed, 349 insertions(+)
 create mode 100644 FARMQ_HEADPLANE_CUSTOMIZATION_PLAN.md

diff --git a/FARMQ_HEADPLANE_CUSTOMIZATION_PLAN.md b/FARMQ_HEADPLANE_CUSTOMIZATION_PLAN.md
new file mode 100644
index 0000000..24f6227
--- /dev/null
+++ b/FARMQ_HEADPLANE_CUSTOMIZATION_PLAN.md
@@ -0,0 +1,349 @@
+# 🏥 팜큐(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 인프라 관리 시스템
\ No newline at end of file