kdrug-inventory-system/docs/판매관리_기획문서.md

# 한약 판매 관리 시스템 기획 문서

## 1. 개요

### 1.1 배경
- 한약사가 조제한 한약은 재고 차감과 별개로 판매 프로세스를 거쳐야 함
- 조제 완료 후 판매 상태 관리 및 가격 책정이 필요
- 환자 관리 및 마케팅을 위한 카카오 채널 연동 계획

### 1.2 목적
- 조제된 한약의 판매 상태 관리
- 유연한 가격 정책 적용
- 판매 이력 추적 및 매출 관리
- 환자 정보 연계 강화

## 2. 현재 시스템 분석

### 2.1 기존 구조
```
compounds 테이블:
- compound_id: 조제 고유번호
- status: 현재 'PREPARED'로 고정
- sell_price_total: 판매가격 필드 존재하나 미활용
- cost_total: 원가 필드 존재
```

### 2.2 현재 문제점
- 조제 후 판매 상태 추적 불가
- 가격 정책 유연성 부족
- 판매 완료/취소/반품 등 프로세스 미비
- 매출 통계 기능 없음

## 3. 기능 요구사항

### 3.1 판매 상태 관리

#### 3.1.1 상태 유형
```
PREPARED (조제완료) → 현재 기본값
PENDING_PAYMENT (결제대기)
PAID (결제완료)
PENDING_DELIVERY (배송대기)
DELIVERED (배송완료)
COMPLETED (판매완료)
OTC_CONVERTED (OTC전환)
CANCELLED (취소)
REFUNDED (환불)
```

#### 3.1.2 상태 전이 규칙
```
조제완료 → 결제대기 → 결제완료 → 배송대기 → 배송완료 → 판매완료
                ↓                    ↓
              OTC전환              취소/환불
```

### 3.2 가격 관리

#### 3.2.1 가격 정책
1. **기본가격 산정**
   - 표준처방: 처방별 기본가격 테이블 참조
   - 직접조제: 약재별 단가 × 용량 × 첩수 자동 계산

2. **가격 조정**
   - 가감방 적용시 자동 재계산
   - 수동 가격 조정 가능
   - 할인율 적용 기능

3. **가격 구성**
   ```
   약재원가 + 조제료 + 배송비 = 기본가격
   기본가격 × (1 - 할인율) = 최종판매가
   ```

### 3.3 판매 처리 기능

#### 3.3.1 판매 정보 입력
- 결제 방법 (현금/카드/계좌이체/카카오페이)
- 결제 일시
- 실제 판매가격
- 할인 사유 및 금액
- 배송 정보 (택배/직접수령/퀵서비스)
- 영수증 발행 여부

#### 3.3.2 OTC 전환
- 처방전 없이 판매 가능한 경우
- 환자 정보 없이도 판매 처리
- 별도 재고 관리 필요

## 4. 데이터베이스 설계

### 4.1 기존 테이블 수정

#### compounds 테이블 수정사항
```sql
ALTER TABLE compounds ADD COLUMN payment_method TEXT;
ALTER TABLE compounds ADD COLUMN payment_date DATETIME;
ALTER TABLE compounds ADD COLUMN discount_rate REAL DEFAULT 0;
ALTER TABLE compounds ADD COLUMN discount_reason TEXT;
ALTER TABLE compounds ADD COLUMN delivery_method TEXT;
ALTER TABLE compounds ADD COLUMN delivery_date DATETIME;
ALTER TABLE compounds ADD COLUMN invoice_number TEXT;
```

### 4.2 신규 테이블

#### sales_transactions (판매 거래)
```sql
CREATE TABLE sales_transactions (
    transaction_id INTEGER PRIMARY KEY AUTOINCREMENT,
    compound_id INTEGER REFERENCES compounds(compound_id),
    transaction_date DATETIME NOT NULL,
    transaction_type TEXT NOT NULL, -- SALE, REFUND, CANCEL
    amount REAL NOT NULL,
    payment_method TEXT,
    payment_status TEXT, -- PENDING, COMPLETED, FAILED
    notes TEXT,
    created_by TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

#### price_policies (가격 정책)
```sql
CREATE TABLE price_policies (
    policy_id INTEGER PRIMARY KEY AUTOINCREMENT,
    formula_id INTEGER REFERENCES formulas(formula_id),
    base_price REAL NOT NULL,
    dispensing_fee REAL DEFAULT 0,
    is_active BOOLEAN DEFAULT 1,
    effective_date DATE,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

#### sales_status_history (판매 상태 이력)
```sql
CREATE TABLE sales_status_history (
    history_id INTEGER PRIMARY KEY AUTOINCREMENT,
    compound_id INTEGER REFERENCES compounds(compound_id),
    old_status TEXT,
    new_status TEXT NOT NULL,
    changed_by TEXT,
    change_reason TEXT,
    changed_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

## 5. 사용자 인터페이스

### 5.1 판매 관리 화면

#### 5.1.1 조제 목록 화면 개선
```
[조제 목록]
┌────┬──────┬──────┬────────┬────────┬────────┬──────────┐
│번호│환자명│처방명│조제일자│  상태  │판매가격│   작업   │
├────┼──────┼──────┼────────┼────────┼────────┼──────────┤
│ 1  │홍길동│갈근탕│02-18   │조제완료│ 80,000 │[판매처리]│
│ 2  │김철수│쌍화탕│02-18   │결제대기│ 60,000 │[결제확인]│
│ 3  │이영희│십전대│02-17   │배송대기│120,000 │[배송처리]│
└────┴──────┴──────┴────────┴────────┴────────┴──────────┘
```

#### 5.1.2 판매 처리 모달
```
┌─────────────── 판매 처리 ──────────────┐
│                                         │
│ 처방명: 갈근탕                          │
│ 환자명: 홍길동                          │
│ 조제일: 2026-02-18                      │
│                                         │
│ ─────── 가격 정보 ─────────             │
│ 약재원가: 45,000원                      │
│ 조제료: 20,000원                        │
│ 기본가격: 65,000원                      │
│                                         │
│ 할인율: [10%▼]                          │
│ 할인사유: [_______________]             │
│ 최종가격: 58,500원                      │
│                                         │
│ ─────── 결제 정보 ─────────             │
│ 결제방법: [카드▼]                       │
│ 결제일시: [2026-02-18 14:30]            │
│                                         │
│ ─────── 배송 정보 ─────────             │
│ 배송방법: [택배▼]                       │
│ 배송예정: [2026-02-19]                  │
│                                         │
│ [취소]                      [판매확정]  │
└─────────────────────────────────────────┘
```

### 5.2 매출 통계 화면

```
[매출 현황]
기간: [2026-02-01] ~ [2026-02-29]

┌─────────────────────────────────┐
│ 총 매출: 3,540,000원            │
│ 총 건수: 42건                   │
│ 평균 단가: 84,286원             │
└─────────────────────────────────┘

[일별 매출 추이 그래프]
[처방별 매출 비중 차트]
[결제 방법별 통계]
```

## 6. API 설계

### 6.1 판매 관련 API

```python
# 판매 상태 업데이트
POST /api/compounds/{compound_id}/status
{
    "status": "PAID",
    "payment_method": "CARD",
    "payment_date": "2026-02-18T14:30:00",
    "amount": 58500
}

# 가격 조정
PUT /api/compounds/{compound_id}/price
{
    "sell_price_total": 58500,
    "discount_rate": 10,
    "discount_reason": "단골 할인"
}

# 판매 통계 조회
GET /api/sales/statistics?start_date=2026-02-01&end_date=2026-02-29

# OTC 전환
POST /api/compounds/{compound_id}/convert-to-otc
{
    "reason": "처방전 미제출",
    "notes": "환자 요청"
}
```

## 7. 구현 우선순위

### Phase 1 (1주차)
1. compounds 테이블 칼럼 추가
2. 판매 상태 변경 기능
3. 기본 가격 입력/수정 기능
4. 판매 처리 UI 구현

### Phase 2 (2주차)
1. sales_transactions 테이블 생성
2. 판매 이력 관리 기능
3. 매출 통계 API
4. 통계 화면 구현

### Phase 3 (3주차)
1. 가격 정책 테이블 구현
2. 자동 가격 계산 로직
3. OTC 전환 기능
4. 영수증 발행 기능

## 8. 추후 확장 계획

### 8.1 카카오 채널 연동
- QR 코드 생성 및 출력
- 카카오 회원가입 유도
- 알림톡 발송 (조제완료, 배송안내)

### 8.2 고객 관리
- 구매 이력 관리
- 재구매 주기 분석
- 맞춤 처방 추천

### 8.3 재고 연계
- OTC 전환시 별도 재고 관리
- 유통기한 관리
- 재고 부족 알림

## 9. 기대 효과

1. **업무 효율성 향상**
   - 조제부터 판매까지 일원화된 관리
   - 자동 가격 계산으로 실수 방지

2. **매출 관리 개선**
   - 실시간 매출 현황 파악
   - 처방별/기간별 분석 가능

3. **고객 서비스 향상**
   - 체계적인 배송 관리
   - 투명한 가격 정책

4. **의사결정 지원**
   - 데이터 기반 가격 정책 수립
   - 인기 처방 파악 및 재고 관리 최적화