# 한약 재고관리 시스템 (kdrug)

## 프로젝트 개요

한의원에서 한약재 재고를 관리하고 처방 조제를 추적하는 통합 시스템입니다.

### 주요 기능
- 📦 **재고 관리**: 한약재 입고/출고/재고 추적
- 💊 **처방 조제**: 표준 처방 및 가감방 조제
- 🏥 **보험 청구**: 건강보험 급여 약재 코드 관리
- 🔍 **효능 검색**: 약재 효능별 검색 및 분류
- 📊 **통계 분석**: 재고 현황 및 소비 패턴 분석

## 기술 스택

- **Backend**: Python Flask
- **Database**: SQLite
- **Frontend**: Bootstrap 5 + jQuery
- **Excel**: pandas, openpyxl

## 핵심 개념

### 코드 체계
```
성분코드 (ingredient_code)    보험코드 (insurance_code)
━━━━━━━━━━━━━━━━━━━━━━━━    ━━━━━━━━━━━━━━━━━━━━━━━━
"3400H1AHM" (인삼)          "062400740" (휴먼감초)
- 454개 표준 약재            - 실제 청구/재고 단위
- 한의학적 속성 기준         - 9자리 제품 코드
```

### 테이블 관계
```
herb_items (재고)
    ↓ insurance_code
herb_products (제품)
    ↓ ingredient_code
herb_masters (마스터)
    ↓ ingredient_code
herb_item_tags (효능)
```

## 프로젝트 구조

```
kdrug/
├── app.py                    # Flask 메인 애플리케이션
├── database/
│   ├── kdrug.db             # SQLite 데이터베이스
│   └── schema.sql           # 스키마 정의
├── static/
│   ├── app.js              # 프론트엔드 로직
│   └── style.css           # 스타일시트
├── templates/
│   └── index.html          # SPA 템플릿
├── docs/
│   ├── 데이터_구조_및_흐름.md
│   ├── 조제_프로세스_및_커스텀_처방.md
│   └── 한약재_정보_관리_시스템_설계.md
└── migrations/
    └── add_herb_extended_info_tables.py
```

## 주요 API 엔드포인트

### 약재 관리
- `GET /api/herbs` - 약재 목록 (효능 태그 포함)
- `GET /api/herbs/masters` - 전체 약재 마스터 (454개)
- `GET /api/herbs/{id}/extended` - 약재 상세 정보
- `GET /api/herbs/{id}/tags` - 효능 태그 조회
- `POST /api/herbs/{id}/tags` - 효능 태그 추가

### 재고 관리
- `GET /api/inventory/summary` - 재고 현황 요약
- `POST /api/purchase-receipts` - 입고 처리
- `GET /api/herbs/{id}/available-lots` - 사용 가능한 로트

### 처방 조제
- `GET /api/formulas` - 처방 목록
- `GET /api/formulas/{id}/ingredients` - 처방 구성
- `POST /api/compounds` - 조제 실행
- `GET /api/patients/{id}/compounds` - 환자별 조제 이력

### 효능 검색
- `GET /api/efficacy-tags` - 모든 효능 태그
- `GET /api/herbs/search-by-efficacy` - 효능별 약재 검색
- `POST /api/prescription-check` - 처방 안전성 검증

## 최근 개선사항 (2026-02-17)

### 1. 효능 태그 시스템 리팩토링 ✅
```sql
-- Before: 복잡한 5단계 JOIN
herb_items → products → masters → extended → tags

-- After: 간단한 3단계 JOIN
herb_items → products → tags (ingredient_code 직접 사용)
```

### 2. 가감방 실시간 감지 ✅
- 처방 수정 시 자동으로 "가감방" 배지 표시
- `ingredient_code` 기준 비교로 정확도 향상

### 3. 복합 로트 지원 ✅
- 한 약재에 여러 로트 사용 가능
- 수동 로트 배분 UI 제공
- FIFO 자동 배분 옵션

## 데이터베이스 설계 특징

### 정규화된 구조
- 성분코드와 보험코드 분리
- 재고는 로트 단위 관리
- 처방 구성은 성분코드 기준

### 확장 가능한 설계
- 효능 태그 시스템 (18개 기본 태그)
- 안전성 정보 테이블
- 연구 문헌 관리
- AI/API 업데이트 로그

### 성능 최적화
- `ingredient_code` 인덱싱
- 집계 쿼리용 서브쿼리 활용
- GROUP_CONCAT으로 태그 조회

## 설치 및 실행

```bash
# 1. 의존성 설치
pip install -r requirements.txt

# 2. 데이터베이스 초기화
python init_db.py

# 3. 서버 실행
python app.py

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

## 개발 가이드

### 새 약재 추가
1. `herb_masters`에 성분코드 확인
2. `herb_products`에 보험코드 매핑
3. `herb_items`에 재고 단위 생성
4. 입고 처리로 `inventory_lots` 생성

### 효능 태그 추가
```python
# ingredient_code로 직접 추가 (개선됨!)
INSERT INTO herb_item_tags (ingredient_code, tag_id, strength)
VALUES ('3400H1AHM', 1, 5)  # 인삼에 보기(5) 추가
```

### API 개발 원칙
- `ingredient_code` 중심 JOIN
- `herb_products` 테이블 활용
- COALESCE로 안전한 처리
- 효능 태그는 선택적 로드

## 주의사항

### ID 체계
- ⚠️ `herb_item_id` ≠ `herb_id`
- `herb_item_id`: 재고 관리 (1~31)
- `herb_id`: 단순 인덱스 (1~454)
- 실제 KEY: `ingredient_code`

### 코드 매핑
- 입력: 보험코드 (9자리)
- 중간: `herb_products` 매핑
- 최종: `ingredient_code` 연결

### 재고 처리
- FIFO 원칙
- 로트별 추적
- 복합 로트 지원

## 향후 계획

### Phase 2: AI 통합
- 한의학연구원 API 연동
- PubMed 문헌 자동 수집
- ChatGPT 기반 정보 추출

### Phase 3: 임상 지원
- DUR 시스템 구현
- 처방 최적화 제안
- 부작용 모니터링

### Phase 4: 분석 강화
- 소비 패턴 분석
- 재고 예측 모델
- 비용 최적화

## 문제 해결

### 약재 드롭다운이 안 나올 때
```python
# /api/herbs 엔드포인트 확인
# herb_products 매핑 확인
# ingredient_code 연결 확인
```

### 효능 태그가 안 보일 때
```python
# herb_item_tags 테이블 확인
# ingredient_code 매핑 확인
# JOIN 경로 확인
```

### 가감방이 감지 안 될 때
```python
# originalFormulaIngredients 전역 변수 확인
# ingredient_code 비교 로직 확인
# 약재 추가/삭제 이벤트 확인
```

## 기여 가이드

1. 기존 시스템 이해
2. 영향도 분석
3. 테스트 작성
4. 문서 업데이트
5. PR 제출

## 라이선스

Private Project - All rights reserved

## 문의

개발팀 연락처: [이메일/슬랙]

---

*Last updated: 2026-02-17*
*Version: 1.0.0*