시골약사 f367781031 docs: 프로젝트 분석 및 개선 방안 문서 추가

추가된 문서:
1. 프로젝트_전체_분석.md
   - 시스템 아키텍처 분석
   - 디렉토리 구조 정리
   - 데이터베이스 설계 상세
   - 주요 기능 및 비즈니스 로직

2. 보험코드_매핑_문제_분석.md
   - Excel 입고 시 보험코드 처리 문제 분석
   - 앞자리 0 누락 문제 원인과 해결방안
   - 영향 범위 및 수정 방법

3. 입고_프로세스_개선방안.md
   - 성분코드-보험코드 매핑 구조 설명
   - 개선된 입고 프로세스 설계
   - 성분코드 기준 재고 관리 방법
   - 구현 우선순위 및 기대 효과

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

Co-Authored-By: Claude <noreply@anthropic.com>

2026-02-16 14:38:52 +00:00

14 KiB

Raw Permalink Blame History

kdrug 프로젝트 전체 분석 보고서

프로젝트 개요

프로젝트명

kdrug - 한의원 약재 관리 시스템

목적

한의원 및 한약방을 위한 웹 기반 통합 관리 시스템으로, 약재 재고 관리, 처방 관리, 조제 관리, 환자 관리 등을 효율적으로 처리하는 것을 목표로 합니다.

주요 특징

건강보험 표준 약재 코드 기반 체계적 관리
Excel 입고장 자동 처리 (한의사랑, 한의정보 형식)
FIFO(선입선출) 기반 로트별 재고 관리
2단계 약재 체계 (마스터 약재 → 제품)
정확한 원가 계산 및 추적
모바일 친화적 환자 문진표 시스템

현재 상태 (2026-02-16 기준)

데이터베이스: 16MB
약재 마스터: 454개
표준 제품: 53,769개
실사용 제품: 40개
등록 처방: 2개
조제 내역: 3건
제조사: 128개

시스템 아키텍처

전체 구조

┌─────────────────────────────────────────┐
│   웹 브라우저 (클라이언트)                │
│   - Single Page Application (SPA)       │
│   - Bootstrap 5.1.3 + jQuery 3.6.0     │
│   - RESTful API 통신                    │
└──────────────────┬──────────────────────┘
                   │ HTTP/AJAX
                   │ Port 5001
┌──────────────────▼──────────────────────┐
│   Flask 웹 서버 (백엔드)                  │
│   - app.py: REST API 엔드포인트          │
│   - excel_processor.py: Excel 처리      │
│   - 트랜잭션 관리, 비즈니스 로직          │
└──────────────────┬──────────────────────┘
                   │ SQL
┌──────────────────▼──────────────────────┐
│   SQLite 데이터베이스                     │
│   - database/kdrug.db (16MB)            │
│   - 26개 테이블                          │
│   - 정규화된 관계형 설계                   │
└─────────────────────────────────────────┘

데이터 플로우

입고 → 로트 생성 → 재고 증가 → 조제 시 소비 → 재고 감소 → 원가 계산
  ↓        ↓           ↓            ↓            ↓          ↓
Excel   lot_id    inventory_lots  FIFO 차감   stock_ledger  원가추적

디렉토리 구조

주요 디렉토리

/root/kdrug/
├── 📄 Core Files
│   ├── app.py (1,916줄)              # Flask 애플리케이션
│   ├── excel_processor.py (285줄)     # Excel 처리 모듈
│   └── run_server.sh                  # 서버 실행 스크립트
│
├── 📁 templates/                      # HTML 템플릿
│   ├── index.html (1,233줄)          # 메인 관리 화면
│   └── survey.html (881줄)           # 환자 문진표
│
├── 📁 static/                         # 정적 파일
│   └── app.js (2,386줄)              # 프론트엔드 JavaScript
│
├── 📁 database/                       # 데이터베이스
│   ├── kdrug.db (16MB)               # 메인 DB ⭐
│   ├── schema.sql (229줄)            # 스키마 정의
│   └── [기타 SQL 파일들]
│
├── 📁 docs/                           # 프로젝트 문서
│   ├── api_documentation.md          # API 명세
│   ├── database_schema.md            # DB 스키마
│   ├── database_erd.md               # ER 다이어그램
│   └── [기타 문서들]
│
├── 📁 refactoring/                    # 리팩토링 스크립트
├── 📁 sample/                         # 샘플 데이터
├── 📁 uploads/                        # 업로드 파일
├── 📁 backups/                        # 백업 파일
└── 📁 .claude/                        # Claude AI 설정

데이터베이스 설계

테이블 구조 (26개 테이블)

1. 핵심 마스터 테이블

테이블명	레코드수	설명
herb_masters	454	주성분코드 기반 약재 마스터
herb_items	40	제조사별 실제 제품
herb_products	53,769	건강보험 표준 제품 목록
product_companies	128	제조/유통 업체
formulas	2	처방 마스터
patients	-	환자 정보

2. 재고 관리 테이블

테이블명	설명
inventory_lots	로트별 재고 (FIFO 관리)
stock_ledger	모든 재고 변동 이력
stock_adjustments	재고 조정 헤더
stock_adjustment_details	재고 조정 상세

3. 조제 관리 테이블

테이블명	설명
compounds	조제 내역
compound_ingredients	조제별 약재 구성
compound_consumptions	로트별 실제 소비 내역

4. 처방 관리 테이블

테이블명	설명
formula_ingredients	처방 구성 (ingredient_code 기반)

5. 입고 관리 테이블

테이블명	설명
suppliers	도매상 정보
purchase_receipts	입고장 헤더
purchase_receipt_lines	입고장 상세

6. 기타 테이블

테이블명	설명
herb_efficacy_tags	효능 태그 (18개)
herb_item_tags	약재-태그 연결
survey_templates	문진표 템플릿
patient_surveys	환자별 문진표
survey_responses	문진표 응답
survey_progress	문진표 진행 상태

주요 관계

약재 계층: herb_masters → herb_items → inventory_lots
처방-조제: formulas → formula_ingredients → compounds → compound_ingredients
재고 추적: purchase_receipts → inventory_lots → compound_consumptions
원가 관리: lot별 unit_price_per_g → FIFO 기반 원가 계산

백엔드 구조

Flask 애플리케이션 (app.py)

API 엔드포인트 (7개 카테고리)

1. 약재 관리 API

GET /api/herbs - 약재 제품 목록
GET /api/herbs/masters - 마스터 약재 목록
GET /api/herbs/by-ingredient/{code} - 성분코드별 제품
GET /api/herbs/{id}/available-lots - 가용 로트 조회

2. 처방 관리 API

GET /api/formulas - 처방 목록
POST /api/formulas - 처방 등록
GET /api/formulas/{id}/ingredients - 처방 구성 조회

3. 조제 관리 API

POST /api/compounds - 조제 실행
GET /api/compounds/recent - 최근 조제 내역
GET /api/compounds/{id} - 조제 상세

4. 재고 관리 API

GET /api/inventory/summary - 재고 현황 요약
GET /api/inventory/low-stock - 재고 부족 약재
GET /api/stock-ledger - 재고 원장

5. 환자 관리 API

GET /api/patients - 환자 목록
POST /api/patients - 환자 등록
GET /api/patients/{id}/prescriptions - 환자 처방 이력

6. 구매/입고 API

POST /api/purchases/upload - Excel 업로드
POST /api/purchases/receipts - 입고장 등록
GET /api/purchases/receipts - 입고장 조회

7. 재고 조정 API

POST /api/stock-adjustments - 재고 보정
GET /api/stock-adjustments - 보정 내역 조회

Excel 처리 모듈 (excel_processor.py)

주요 기능

형식 자동 감지: 한의사랑, 한의정보 형식 자동 인식
컬럼 매핑: 다양한 컬럼명 유연한 처리
데이터 변환: 숫자, 날짜, 텍스트 자동 변환
검증 및 요약: 데이터 검증 및 처리 결과 리포트

프론트엔드 구조

메인 관리 화면 (index.html)

7개 주요 섹션

대시보드: 통계 요약, 최근 조제 내역
환자 관리: 환자 등록, 조회, 처방 내역
입고 관리: Excel 업로드, 입고장 관리
처방 관리: 처방 등록, 구성 관리
조제 관리: 조제 실행, 내역 조회
재고 현황: 재고 조회, 보정, 원장
약재 관리: 마스터 약재 관리

JavaScript 애플리케이션 (app.js)

주요 기능 모듈

페이지 네비게이션: SPA 방식 클라이언트 라우팅
API 통신: jQuery 기반 RESTful API 호출
동적 UI 생성: 테이블, 폼, 모달 동적 생성
데이터 로딩: 20+ 데이터 로딩 함수
이벤트 처리: 30+ 이벤트 핸들러
유틸리티: 포맷팅, 계산, 검증

환자 문진표 (survey.html)

모바일 최적화 설계

반응형 레이아웃: 모바일 친화적 UI
진행률 추적: 실시간 진행 상태 표시
카테고리 네비게이션: 9개 건강 카테고리
자동 저장: 로컬스토리지 + 서버 동기화
오프라인 지원: 로컬 백업 및 복원

주요 기능 분석

1. 재고 관리 시스템

2단계 약재 체계

1단계: herb_masters (성분코드 기준)
   ↓
2단계: herb_items (제조사별 제품)
   ↓
로트: inventory_lots (입고 단위)

FIFO 재고 관리

선입선출 원칙으로 자동 차감
로트별 추적 가능
정확한 원가 계산

2. Excel 입고 자동화

지원 형식

한의사랑 거래명세표
한의정보 거래명세표
자동 형식 감지 및 처리

처리 프로세스

Excel 업로드 → 형식 감지 → 데이터 추출 → 검증 → DB 저장 → 로트 생성

3. 처방-조제 시스템

처방 구성

ingredient_code 기반 (유연한 제품 선택)
기본 첩수/파우치 설정
1첩당 용량 관리

조제 프로세스

처방 선택 → 제품 선택 → 원산지/로트 선택 → 조제 실행 → 재고 차감

4. 원가 관리

원가 계산 방식

로트별 단가 기준
FIFO 차감 시 실제 원가 추적
조제별 정확한 원가 집계

5. 환자 문진표 시스템

특징

모바일 최적화
9개 건강 카테고리
진행률 추적
자동 저장/복원

비즈니스 로직

1. 단위 환산 체계

1제 = 20첩 (기본값, 조정 가능)
1제 = 30파우치 (기본값, 조정 가능)

2. 재고 차감 로직

def consume_inventory(herb_item_id, quantity_needed):
    # 1. 가용 로트 조회 (FIFO 순서)
    lots = get_available_lots(herb_item_id, order='received_date')

    # 2. 순차적 차감
    consumptions = []
    for lot in lots:
        if quantity_needed <= 0:
            break
        consumed = min(lot.quantity_onhand, quantity_needed)
        lot.quantity_onhand -= consumed
        quantity_needed -= consumed
        consumptions.append({
            'lot_id': lot.id,
            'quantity': consumed,
            'unit_price': lot.unit_price_per_g
        })

    # 3. stock_ledger 기록
    # 4. compound_consumptions 기록
    return consumptions

3. 원가 계산

def calculate_cost(consumptions):
    total_cost = 0
    for consumption in consumptions:
        cost = consumption['quantity'] * consumption['unit_price']
        total_cost += cost
    return total_cost

4. 재고 보정 유형

감모: 자연 감소, 손실
발견: 추가 발견된 재고
재고조사: 실사 보정
반품: 반품 처리
기타: 기타 사유

기술 스택

백엔드

언어: Python 3.12
프레임워크: Flask
데이터베이스: SQLite 3
Excel 처리: pandas, openpyxl
CORS: flask-cors

프론트엔드

HTML5/CSS3: 시맨틱 마크업
JavaScript: ES6+
라이브러리:
- jQuery 3.6.0 (DOM, AJAX)
- Bootstrap 5.1.3 (UI Framework)
- Bootstrap Icons 1.8.1

개발/운영 환경

OS: Linux (6.8.4-3-pve)
가상환경: Python venv
포트: 5001
프로세스 관리: bash script

개선 권장사항

1. 성능 최적화

데이터베이스 인덱스 최적화
API 페이지네이션 구현
캐싱 전략 도입
대용량 데이터 처리 개선

2. 보안 강화

사용자 인증/인가 시스템
API 접근 제어
SQL Injection 방어 강화
XSS 방어 강화

3. 코드 품질

코드 모듈화 (app.py 분리)
에러 핸들링 개선
단위 테스트 추가
API 문서 자동화 (Swagger)

4. 사용자 경험

실시간 알림 시스템
대시보드 커스터마이징
고급 검색 기능
다크 모드 지원

5. 기능 확장

바코드/QR 코드 지원
보고서 생성 기능
다중 사업장 지원
모바일 앱 개발

6. 데이터 관리

자동 백업 시스템
데이터 마이그레이션 도구
감사 로그 시스템
데이터 분석 대시보드

결론

kdrug 프로젝트는 한의원의 실무 요구사항을 충실히 반영한 실용적이고 체계적인 관리 시스템입니다.

강점

표준화: 건강보험 표준 코드 기반
자동화: Excel 입고 자동 처리
정확성: FIFO 기반 정확한 원가 추적
사용성: 직관적인 UI/UX
확장성: 모듈화된 구조

핵심 가치

업무 효율성 향상
정확한 재고 관리
체계적인 원가 관리
환자 서비스 품질 향상

프로젝트는 지속적인 개선과 확장을 통해 한의원 통합 관리 솔루션으로 발전할 수 있는 견고한 기반을 갖추고 있습니다.

작성일: 2026-02-16 작성자: Claude AI Assistant 버전: 1.0

14 KiB Raw Permalink Blame History