시골약사
f367781031
추가된 문서: 1. 프로젝트_전체_분석.md - 시스템 아키텍처 분석 - 디렉토리 구조 정리 - 데이터베이스 설계 상세 - 주요 기능 및 비즈니스 로직 2. 보험코드_매핑_문제_분석.md - Excel 입고 시 보험코드 처리 문제 분석 - 앞자리 0 누락 문제 원인과 해결방안 - 영향 범위 및 수정 방법 3. 입고_프로세스_개선방안.md - 성분코드-보험코드 매핑 구조 설명 - 개선된 입고 프로세스 설계 - 성분코드 기준 재고 관리 방법 - 구현 우선순위 및 기대 효과 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
460 lines
14 KiB
Markdown
460 lines
14 KiB
Markdown
# kdrug 프로젝트 전체 분석 보고서
|
|
|
|
## 목차
|
|
1. [프로젝트 개요](#프로젝트-개요)
|
|
2. [시스템 아키텍처](#시스템-아키텍처)
|
|
3. [디렉토리 구조](#디렉토리-구조)
|
|
4. [데이터베이스 설계](#데이터베이스-설계)
|
|
5. [백엔드 구조](#백엔드-구조)
|
|
6. [프론트엔드 구조](#프론트엔드-구조)
|
|
7. [주요 기능 분석](#주요-기능-분석)
|
|
8. [비즈니스 로직](#비즈니스-로직)
|
|
9. [기술 스택](#기술-스택)
|
|
10. [개선 권장사항](#개선-권장사항)
|
|
|
|
---
|
|
|
|
## 프로젝트 개요
|
|
|
|
### 프로젝트명
|
|
**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 | 문진표 진행 상태 |
|
|
|
|
### 주요 관계
|
|
1. **약재 계층**: herb_masters → herb_items → inventory_lots
|
|
2. **처방-조제**: formulas → formula_ingredients → compounds → compound_ingredients
|
|
3. **재고 추적**: purchase_receipts → inventory_lots → compound_consumptions
|
|
4. **원가 관리**: 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)
|
|
|
|
#### 주요 기능
|
|
1. **형식 자동 감지**: 한의사랑, 한의정보 형식 자동 인식
|
|
2. **컬럼 매핑**: 다양한 컬럼명 유연한 처리
|
|
3. **데이터 변환**: 숫자, 날짜, 텍스트 자동 변환
|
|
4. **검증 및 요약**: 데이터 검증 및 처리 결과 리포트
|
|
|
|
---
|
|
|
|
## 프론트엔드 구조
|
|
|
|
### 메인 관리 화면 (index.html)
|
|
|
|
#### 7개 주요 섹션
|
|
1. **대시보드**: 통계 요약, 최근 조제 내역
|
|
2. **환자 관리**: 환자 등록, 조회, 처방 내역
|
|
3. **입고 관리**: Excel 업로드, 입고장 관리
|
|
4. **처방 관리**: 처방 등록, 구성 관리
|
|
5. **조제 관리**: 조제 실행, 내역 조회
|
|
6. **재고 현황**: 재고 조회, 보정, 원장
|
|
7. **약재 관리**: 마스터 약재 관리
|
|
|
|
### JavaScript 애플리케이션 (app.js)
|
|
|
|
#### 주요 기능 모듈
|
|
1. **페이지 네비게이션**: SPA 방식 클라이언트 라우팅
|
|
2. **API 통신**: jQuery 기반 RESTful API 호출
|
|
3. **동적 UI 생성**: 테이블, 폼, 모달 동적 생성
|
|
4. **데이터 로딩**: 20+ 데이터 로딩 함수
|
|
5. **이벤트 처리**: 30+ 이벤트 핸들러
|
|
6. **유틸리티**: 포맷팅, 계산, 검증
|
|
|
|
### 환자 문진표 (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. 재고 차감 로직
|
|
```python
|
|
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. 원가 계산
|
|
```python
|
|
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 프로젝트는 한의원의 실무 요구사항을 충실히 반영한 **실용적이고 체계적인 관리 시스템**입니다.
|
|
|
|
### 강점
|
|
1. **표준화**: 건강보험 표준 코드 기반
|
|
2. **자동화**: Excel 입고 자동 처리
|
|
3. **정확성**: FIFO 기반 정확한 원가 추적
|
|
4. **사용성**: 직관적인 UI/UX
|
|
5. **확장성**: 모듈화된 구조
|
|
|
|
### 핵심 가치
|
|
- 업무 효율성 향상
|
|
- 정확한 재고 관리
|
|
- 체계적인 원가 관리
|
|
- 환자 서비스 품질 향상
|
|
|
|
프로젝트는 지속적인 개선과 확장을 통해 한의원 통합 관리 솔루션으로 발전할 수 있는 견고한 기반을 갖추고 있습니다.
|
|
|
|
---
|
|
|
|
**작성일**: 2026-02-16
|
|
**작성자**: Claude AI Assistant
|
|
**버전**: 1.0 |