kdrug-inventory-system/claude.md

한약 재고관리 시스템 (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. 효능 태그 시스템 리팩토링 ✅

-- 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으로 태그 조회

설치 및 실행

# 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 생성

효능 태그 추가

# 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: 분석 강화

• 소비 패턴 분석
• 재고 예측 모델
• 비용 최적화

문제 해결

약재 드롭다운이 안 나올 때

# /api/herbs 엔드포인트 확인
# herb_products 매핑 확인
# ingredient_code 연결 확인

효능 태그가 안 보일 때

# herb_item_tags 테이블 확인
# ingredient_code 매핑 확인
# JOIN 경로 확인

가감방이 감지 안 될 때

# originalFormulaIngredients 전역 변수 확인
# ingredient_code 비교 로직 확인
# 약재 추가/삭제 이벤트 확인

기여 가이드

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

라이선스

Private Project - All rights reserved

문의

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

---

Last updated: 2026-02-17 Version: 1.0.0