thug0bin/headscale-tailscale-replacement
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

PharmQ SaaS 구독 서비스 관리 시스템 완전 구현

Browse Source 
📋 기획 및 설계:
- PharmQ SaaS 서비스 기획서 작성
- 구독 서비스 라인업 정의 (클라우드PC, AI CCTV, CRM)
- DB 스키마 설계 및 API 아키텍처 설계

🗄️ 데이터베이스 구조:
- service_products: 서비스 상품 마스터 테이블
- pharmacy_subscriptions: 약국별 구독 현황 테이블
- subscription_usage_logs: 서비스 이용 로그 테이블
- billing_history: 결제 이력 테이블
- 샘플 데이터 자동 생성 (21개 구독, 월 118만원 매출)

🔧 백엔드 API 구현:
- 구독 현황 통계 API (/api/subscriptions/stats)
- 약국별 구독 조회 API (/api/pharmacies/subscriptions)
- 구독 상세 정보 API (/api/pharmacy/{id}/subscriptions)
- 구독 생성/해지 API (/api/subscriptions)

🖥️ 프론트엔드 UI 구현:
- 대시보드 구독 현황 카드 (월 매출, 구독 수, 구독률 등)
- 약국 목록에 구독 상태 아이콘 및 월 구독료 표시
- 약국 상세 페이지 구독 서비스 섹션 추가
- 실시간 구독 생성/해지 기능 구현

✨ 주요 특징:
- 서비스별 색상 코딩 및 이모지 아이콘 시스템
- 실시간 업데이트 (구독 생성/해지 즉시 반영)
- 반응형 디자인 (모바일/태블릿 최적화)
- 툴팁 기반 상세 정보 표시

📊 현재 구독 현황:
- 총 월 매출: ₩1,180,000
- 구독 약국: 10/14개 (71.4%)
- AI CCTV: 6개 약국, CRM: 10개 약국, 클라우드PC: 5개 약국

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
시골약사
2025-09-11 19:48:12 +09:00
parent c37cf023c1
commit 35ecd4748e
15 changed files with 3967 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

297
PharmQ-SaaS-Service-Plan.md Normal file
View File

@@ -0,0 +1,297 @@
# PharmQ SaaS 구독 서비스 관리 시스템 기획서
## 1. 프로젝트 개요
### 1.1 목적
- PharmQ가 제공하는 다양한 서비스에 대한 약국별 구독 관리
- SaaS 형태의 과금 서비스 기반 마련
- 약국별 서비스 이용 현황 실시간 모니터링
### 1.2 서비스 라인업
1. **클라우드 PC** (Proxmox 기반 가상 데스크톱)
2. **AI CCTV** (인공지능 기반 보안 모니터링)
3. **CRM** (고객 관계 관리 시스템)
## 2. 데이터베이스 스키마 설계
### 2.1 새로 추가할 테이블
#### 2.1.1 `service_products` - 서비스 상품 마스터
```sql
CREATE TABLE service_products (
id INTEGER PRIMARY KEY AUTOINCREMENT,
product_code VARCHAR(20) UNIQUE NOT NULL, -- 'CLOUD_PC', 'AI_CCTV', 'CRM'
product_name VARCHAR(100) NOT NULL, -- '클라우드 PC', 'AI CCTV', 'CRM'
description TEXT, -- 서비스 상세 설명
monthly_price DECIMAL(10,2) NOT NULL, -- 월 구독료
setup_fee DECIMAL(10,2) DEFAULT 0, -- 초기 설치비
is_active BOOLEAN DEFAULT TRUE, -- 서비스 활성화 여부
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
#### 2.1.2 `pharmacy_subscriptions` - 약국별 구독 현황
```sql
CREATE TABLE pharmacy_subscriptions (
id INTEGER PRIMARY KEY AUTOINCREMENT,
pharmacy_id INTEGER NOT NULL, -- pharmacy_info.id 참조
product_id INTEGER NOT NULL, -- service_products.id 참조
subscription_status VARCHAR(20) NOT NULL, -- 'ACTIVE', 'SUSPENDED', 'CANCELLED'
start_date DATE NOT NULL, -- 구독 시작일
end_date DATE, -- 구독 종료일 (NULL이면 무제한)
next_billing_date DATE, -- 다음 결제일
monthly_fee DECIMAL(10,2) NOT NULL, -- 실제 적용 월 구독료
notes TEXT, -- 특이사항
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (pharmacy_id) REFERENCES pharmacy_info(id),
FOREIGN KEY (product_id) REFERENCES service_products(id),
UNIQUE(pharmacy_id, product_id) -- 약국-상품당 하나의 구독만
);
```
#### 2.1.3 `subscription_usage_logs` - 서비스 이용 로그
```sql
CREATE TABLE subscription_usage_logs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
subscription_id INTEGER NOT NULL, -- pharmacy_subscriptions.id 참조
usage_type VARCHAR(50) NOT NULL, -- 'LOGIN', 'API_CALL', 'STORAGE_USE' 등
usage_amount INTEGER DEFAULT 1, -- 사용량 (로그인 횟수, API 호출 수 등)
usage_date DATE NOT NULL, -- 사용일
metadata JSON, -- 추가 메타데이터
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (subscription_id) REFERENCES pharmacy_subscriptions(id)
);
```
#### 2.1.4 `billing_history` - 결제 이력
```sql
CREATE TABLE billing_history (
id INTEGER PRIMARY KEY AUTOINCREMENT,
subscription_id INTEGER NOT NULL, -- pharmacy_subscriptions.id 참조
billing_period_start DATE NOT NULL, -- 과금 기간 시작
billing_period_end DATE NOT NULL, -- 과금 기간 종료
amount DECIMAL(10,2) NOT NULL, -- 청구 금액
billing_status VARCHAR(20) NOT NULL, -- 'PENDING', 'PAID', 'OVERDUE', 'CANCELLED'
billing_date DATE, -- 실제 결제일
payment_method VARCHAR(50), -- 결제 수단
invoice_number VARCHAR(100), -- 청구서 번호
notes TEXT, -- 결제 관련 메모
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (subscription_id) REFERENCES pharmacy_subscriptions(id)
);
```
### 2.2 기존 테이블 연동
- `pharmacy_info` 테이블과 `pharmacy_subscriptions` 테이블을 연결
- 사용자 관리에서 약국별 구독 서비스 현황 표시
## 3. 프론트엔드 UI/UX 설계
### 3.1 대시보드 개선
#### 3.1.1 메인 대시보드 (`/`)
- **구독 서비스 현황 카드** 추가
```
┌─────────────────────────────────────────┐
│ 📊 구독 서비스 현황 │
├─────────────────────────────────────────┤
│ 클라우드 PC │ 12/14 약국 (85.7%) │
│ AI CCTV │ 8/14 약국 (57.1%) │
│ CRM │ 10/14 약국 (71.4%) │
├─────────────────────────────────────────┤
│ 총 월 매출 │ ₩2,450,000 │
└─────────────────────────────────────────┘
```
#### 3.1.2 서비스별 상태 인디케이터
- 각 서비스별 색상 코드 적용
- 🟢 클라우드 PC (녹색)
- 🔵 AI CCTV (파란색)
- 🟡 CRM (노란색)
### 3.2 약국 관리 페이지 개선 (`/pharmacy`)
#### 3.2.1 약국 목록에 구독 상태 표시
```
┌─────────────────────────────────────────────────────────────────┐
│ 약국명 │ 위치 │ 구독 서비스 │ 월 구독료 │ 액션 │
├─────────────────────────────────────────────────────────────────┤
│ 서울약국 │ 서울 강남구 │ 🟢 💻 🔵 📷 🟡 📊 │ ₩180,000 │ ⚙️ │
│ 부산약국 │ 부산 해운대 │ 🟢 💻 🔵 📷 │ ₩120,000 │ ⚙️ │
│ 대구약국 │ 대구 중구 │ 🟢 💻 │ ₩60,000 │ ⚙️ │
└─────────────────────────────────────────────────────────────────┘
```
#### 3.2.2 약국 상세 페이지 구독 탭 추가
- 기존: 기본정보, 네트워크정보, 연결된 머신
- **신규**: **구독 서비스** 탭 추가
```
┌─────────────────────────────────────────────────────────────────┐
│ [기본정보] [네트워크정보] [연결된 머신] [구독 서비스] ←← 신규 탭 │
├─────────────────────────────────────────────────────────────────┤
│ 📦 구독 중인 서비스 │
│ │
│ 🟢 클라우드 PC ₩60,000/월 [관리] │
│ ├─ 구독기간: 2024.01.15 ~ 무제한 │
│ ├─ 다음결제: 2025.10.15 │
│ └─ 상태: 정상 (ACTIVE) │
│ │
│ 🔵 AI CCTV ₩80,000/월 [관리] │
│ ├─ 구독기간: 2024.03.01 ~ 무제한 │
│ ├─ 다음결제: 2025.10.01 │
│ └─ 상태: 정상 (ACTIVE) │
│ │
│ 📦 구독 가능한 서비스 │
│ │
│ 🟡 CRM 시스템 ₩40,000/월 [가입] │
│ └─ 고객 관계 관리 및 매출 분석 도구 │
│ │
│ [+ 새 서비스 구독하기] │
└─────────────────────────────────────────────────────────────────┘
```
### 3.3 새로운 메뉴 추가
#### 3.3.1 사이드바 메뉴 구조 개선
```
PharmQ Super Admin (PSA)
├── 📊 대시보드
├── 🏥 약국 관리
├── 👥 PQON 사용자 관리
├── 💻 머신 관리
├── 🖥️ VM 관리 (VNC)
├── 📦 구독 서비스 관리 ←← 신규 메뉴
│ ├── 구독 현황 조회
│ ├── 서비스 상품 관리
│ ├── 결제 이력 조회
│ └── 사용량 통계
├── 📈 매출 대시보드 ←← 신규 메뉴
└── 🔗 Medivault
```
#### 3.3.2 구독 서비스 관리 페이지 (`/subscriptions`)
- **전체 구독 현황 테이블**
- **서비스별 필터링**
- **구독 상태별 필터링** (활성/일시정지/해지)
- **월별 매출 차트**
#### 3.3.3 매출 대시보드 (`/revenue`)
- **월별 매출 트렌드**
- **서비스별 매출 비중**
- **약국별 구독료 순위**
- **신규 구독/해지 통계**
## 4. API 설계
### 4.1 구독 관리 API
#### 4.1.1 구독 현황 조회
```
GET /api/subscriptions
GET /api/subscriptions/pharmacy/{pharmacy_id}
GET /api/subscriptions/product/{product_code}
```
#### 4.1.2 구독 생성/수정
```
POST /api/subscriptions # 새 구독 생성
PUT /api/subscriptions/{subscription_id} # 구독 정보 수정
DELETE /api/subscriptions/{subscription_id} # 구독 해지
```
#### 4.1.3 서비스 상품 관리
```
GET /api/products # 상품 목록
POST /api/products # 상품 등록
PUT /api/products/{product_id} # 상품 수정
```
### 4.2 결제 및 통계 API
#### 4.2.1 결제 관련
```
GET /api/billing/history/{subscription_id} # 결제 이력
POST /api/billing/invoice # 청구서 생성
PUT /api/billing/{billing_id}/status # 결제 상태 업데이트
```
#### 4.2.2 통계 및 리포트
```
GET /api/analytics/revenue/monthly # 월별 매출
GET /api/analytics/subscriptions/summary # 구독 요약
GET /api/analytics/usage/{subscription_id} # 서비스 사용량
```
## 5. 구현 단계별 로드맵
### Phase 1: 기본 구조 구축 (1-2주)
- [x] 데이터베이스 스키마 생성
- [ ] 기본 API 엔드포인트 구현
- [ ] 대시보드 구독 현황 카드 추가
### Phase 2: 약국별 구독 관리 (2-3주)
- [ ] 약국 상세 페이지 구독 탭 추가
- [ ] 구독 생성/수정/해지 기능
- [ ] 약국 목록 구독 상태 표시
### Phase 3: 서비스 관리 및 통계 (3-4주)
- [ ] 구독 서비스 관리 메뉴 구현
- [ ] 매출 대시보드 구현
- [ ] 사용량 로깅 시스템
### Phase 4: 과금 시스템 (4-6주)
- [ ] 자동 결제 시스템
- [ ] 청구서 생성
- [ ] 결제 연동 (포트원/토스페이먼츠 등)
## 6. 기술 스택
### 6.1 백엔드
- **Database**: SQLite (개발) → PostgreSQL (운영)
- **API**: Flask REST API
- **결제**: 포트원(PortOne) 또는 토스페이먼츠
### 6.2 프론트엔드
- **Framework**: Bootstrap 5 + Jinja2
- **Charts**: Chart.js 또는 D3.js
- **Icons**: Font Awesome
### 6.3 모니터링
- **사용량 추적**: Custom logging system
- **알림**: 결제 실패, 구독 만료 등
## 7. 보안 및 컴플라이언스
### 7.1 데이터 보안
- 결제 정보 암호화
- 개인정보 보호법 준수
- API 인증/인가 체계
### 7.2 백업 및 복구
- 데이터베이스 일일 백업
- 결제 데이터 별도 보관
- 장애 복구 프로세스
---
## 8. 예상 효과
### 8.1 비즈니스 효과
- **매출 가시화**: 실시간 구독 매출 현황 파악
- **고객 관리**: 약국별 서비스 이용 패턴 분석
- **확장성**: 새로운 서비스 추가 용이
### 8.2 운영 효율화
- **자동화**: 구독/해지/결제 프로세스 자동화
- **모니터링**: 서비스별 이용 현황 실시간 추적
- **리포팅**: 월별/분기별 매출 리포트 자동 생성
---
**작성일**: 2025년 9월 11일
**작성자**: PharmQ Development Team
**버전**: v1.0