kdrug-inventory-system/README.md

# 한약 재고관리 시스템

한의원/한약방을 위한 웹 기반 재고관리 및 조제관리 시스템입니다.

## 주요 기능

### 1. 환자 관리
- 환자 등록 (이름, 전화번호, 주민번호, 성별, 생년월일)
- 환자 검색 및 조회
- 환자별 조제 이력 관리

### 2. 입고 관리
- Excel 파일을 통한 대량 입고 처리
- 도매상별 입고 관리
- 로트별 재고 추적 (원산지, 입고일, 단가 등)

### 3. 처방 관리 (약속 처방)
- 자주 사용하는 처방 템플릿 등록
- 처방별 구성 약재 및 용량 설정
- 처방 재사용 및 가감 기능

### 4. 조제 관리
- 처방 선택 후 즉시 조제
- 약재 가감 기능
- FIFO 방식 재고 차감
- 조제 원가 자동 계산

### 5. 재고 현황
- 실시간 재고 조회
- 약재별 재고 수량 및 금액
- 로트별 상세 재고 현황

## 시스템 아키텍처

```
┌─────────────────────────────────────────┐
│         웹 브라우저 (클라이언트)          │
│     HTML + Bootstrap + jQuery           │
└──────────────────┬──────────────────────┘
                   │ HTTP/AJAX
                   │
┌──────────────────▼──────────────────────┐
│        Flask 웹 서버 (Backend)          │
│         REST API + 템플릿 렌더링         │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│       SQLite Database                  │
│  (재고, 환자, 처방, 조제 데이터)        │
└─────────────────────────────────────────┘
```

## 데이터베이스 구조

### 핵심 테이블
- `herb_masters` - 약재 마스터 (성분코드 기준, 454개 표준 약재)
- `herb_items` - 약재 제품 (제조사별 개별 제품)
- `patients` - 환자 정보
- `suppliers` - 도매상 정보
- `purchase_receipts` - 입고장 헤더
- `purchase_receipt_lines` - 입고장 상세
- `inventory_lots` - 로트별 재고
- `formulas` - 처방 마스터
- `formula_ingredients` - 처방 구성 약재 (ingredient_code 기반)
- `compounds` - 조제 작업
- `compound_consumptions` - 로트별 차감 내역
- `stock_ledger` - 재고 원장 (모든 변동 기록)

### 핵심 개념
- **성분코드 (ingredient_code)**: 표준 약재 식별자
- **2단계 약재 체계**: 마스터(성분) → 제품(제조사별)
- **1제 = 20첩 = 30파우치** (기본값, 조정 가능)
- **로트 관리**: 입고 시점별로 재고를 구분 관리
- **FIFO 차감**: 오래된 재고부터 우선 사용
- **원가 추적**: 로트별 단가 기준 정확한 원가 계산

## 📚 문서

- [데이터베이스 스키마](docs/database_schema.md) - 전체 테이블 구조 상세 설명
- [ER 다이어그램](docs/database_erd.md) - 엔티티 관계도 및 데이터 플로우
- [API 문서](docs/api_documentation.md) - REST API 엔드포인트 상세 명세

## 설치 방법

### 1. 필수 요구사항
- Python 3.8 이상
- pip (Python 패키지 관리자)

### 2. 설치 과정

```bash
# 1. 프로젝트 클론 또는 다운로드
cd kdrug

# 2. 가상환경 생성 및 활성화
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 3. 필요 패키지 설치
pip install flask flask-cors pandas openpyxl

# 4. 서버 실행
python app.py
```

### 3. 웹 브라우저에서 접속
```
http://localhost:5001
```

## 사용 방법

### 1. 초기 설정
1. 시스템 실행 후 웹 브라우저로 접속
2. 약재 마스터 데이터 준비 (Excel 업로드로 자동 생성 가능)

### 2. Excel 입고장 업로드
Excel 파일 형식 (필수 컬럼):
- 제품코드 (보험코드 9자리)
- 업체명
- 약재명
- 구입일자 (YYYYMMDD)
- 구입량 (그램 단위)
- 구입액 (원)
- 원산지

### 3. 환자 등록
1. 좌측 메뉴에서 "환자 관리" 클릭
2. "새 환자 등록" 버튼 클릭
3. 필수 정보 입력 (이름, 전화번호)
4. 선택 정보 입력 (주민번호, 성별, 생년월일 등)

### 4. 처방 등록 (약속 처방)
1. 좌측 메뉴에서 "처방 관리" 클릭
2. "새 처방 등록" 버튼 클릭
3. 처방명 입력 (예: 쌍화탕, 보중익기탕 등)
4. 구성 약재 추가
   - 약재 선택
   - 1첩당 용량(g) 입력
5. 저장

### 5. 조제 실행
1. 좌측 메뉴에서 "조제 관리" 클릭
2. "새 조제" 버튼 클릭
3. 환자 선택
4. 처방 선택 (등록된 처방 템플릿)
5. 제수 입력 (기본 1제)
6. 약재 가감 (필요시)
   - 용량 조정
   - 약재 추가/삭제
7. "조제 실행" 클릭
8. 자동으로 재고 차감 및 원가 계산

### 6. 재고 확인
1. 좌측 메뉴에서 "재고 현황" 클릭
2. 약재명으로 검색 가능
3. 현재 재고량, 로트 수, 평균 단가, 재고 금액 확인

## 시스템 특징

### 장점
- **간편한 Excel 업로드**: 기존 Excel 입고장을 그대로 활용
- **약속 처방 기능**: 자주 사용하는 처방을 템플릿으로 저장
- **가감 기능**: 처방 기본 구성에서 유연한 조정 가능
- **정확한 원가 계산**: 로트별 단가 추적으로 정확한 원가 산출
- **FIFO 재고 관리**: 선입선출 원칙 자동 적용
- **웹 기반**: 별도 설치 없이 브라우저에서 사용

### 보안 고려사항
- 주민번호 등 민감 정보는 암호화 필요 (프로덕션 환경)
- 사용자 인증/권한 관리 기능 추가 필요
- HTTPS 적용 권장

## 향후 개발 계획

1. **보험 청구 연동**
   - 건강보험 첩약 코드 완벽 지원
   - 청구 자료 자동 생성

2. **고급 리포트**
   - 월별/분기별 매출 분석
   - 약재별 사용량 통계
   - 환자별 처방 이력

3. **모바일 지원**
   - 반응형 웹 디자인
   - 모바일 앱 개발

4. **재고 알림**
   - 최소 재고 수준 설정
   - 재고 부족 알림
   - 유효기간 임박 알림

5. **다중 사용자**
   - 사용자 계정 관리
   - 권한별 접근 제어
   - 작업 이력 추적

## 기술 스택

- **Backend**: Flask 3.1.2 (Python Web Framework)
- **Database**: SQLite (경량 관계형 데이터베이스)
- **Frontend**: Bootstrap 5.1.3 + jQuery 3.6.0
- **Excel 처리**: pandas + openpyxl
- **API**: RESTful JSON API

## 라이선스

이 프로젝트는 교육 및 테스트 목적으로 제작되었습니다.
상업적 사용 시 별도 협의가 필요합니다.

## 문의

기술 지원 및 문의사항은 이슈 트래커를 통해 등록해주세요.