# DMTrialSupplyChain-Kor (디엠트라이얼서플라이체인코어)

> ⚠️ **디스클레이머**: 본 도구는 연구·운영 보조용 참고 도구이며 실제 임상시험 규제 의사결정을 대체하지 않는다. 모든 데이터는 합성/사용자입력이며 외부 네트워크·API를 사용하지 않는다(오프라인 우선).

당뇨 cold-chain 주사제 IMP(인슐린·GLP-1RA·tirzepatide) 임상시험의 **약물 공급망 시뮬레이터 & drug accountability 추적기** (standalone Streamlit 앱).

- **도메인**: DM (당뇨)
- **카테고리**: 인체실험 도구 (임상시험 운영 물류)
- **기술스택**: Python + Streamlit + pandas + simpy(이산사건 시뮬레이션, 선택) + plotly(선택) + scipy

## 목적

당뇨 임상시험의 IMP는 대부분 2–8°C cold-chain 주사제(인슐린 펜, GLP-1RA 펜, tirzepatide 바이알)다. 무작위배정 속도, arm별 dose, titration 스케줄, lot 만료, 온도일탈, site별 accountability가 얽혀 **약물 부족·과다 폐기·온도일탈 폐기·GCP accountability 불일치** 위험이 상존한다. 본 도구는 이 다섯 가지를 한 화면에서 시뮬레이션·추적하는 운영 보조 MVP다.

## 5개 핵심 기능

1. **무작위배정 연동 resupply forecasting** — 등록 로그·arm별 dose/주·titration 가중 → site별·arm별·주차별 누적 약물 소요량(kit) 예측, par level 도달 시 자동 보급 trigger, 부족 위험 주차(stockout) 산출 및 제안 발주량 제시.
2. **FEFO 만료관리 엔진** — lot별 만료일·재고를 만료일 오름차순(First-Expiry-First-Out)으로 수요에 배분, 예상 폐기량·폐기 비용(원) 산출.
3. **온도일탈(excursion) 영향 추적** — temperature 로그 CSV에서 일탈 구간(>상한 또는 <하한) 검출, lot/shipment별 누적 일탈 시간 집계, IMP 안정성 budget 기반 격리(QUARANTINE)/사용가능(USABLE) 자동 판정. budget 미상 IMP는 보수적으로 격리.
4. **drug accountability 원장** — ICH GCP E6(R3) 요건 기반 shipped/dispensed/returned/destroyed 균형 대장, site별 불일치(MISMATCH) alert.
5. **depot→site 배분 시나리오 (what-if)** — 등록 가속·site 추가·공급 지연 what-if 시뮬레이션. simpy 설치 시 이산사건 시뮬레이션, 미설치 시 결정론적 모델로 자동 fallback. 주차별 수요 vs 보급 vs backorder·stockout 주차 산출.

## 실행법

```bash
# (권장) 가상환경에서 설치 — 전역 설치 금지
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 데모 데이터 재생성(선택; data/에 이미 생성돼 있음)
python3 data/generate_demo_data.py

# 앱 실행 — CSV 업로드 없이 합성 데모 데이터로 즉시 동작
streamlit run app.py
```

> simpy·plotly가 없어도 앱은 동작한다(결정론적 모델 + streamlit 기본 차트). 전체 기능은 `requirements.txt` 설치 시 사용 가능.

## 데이터 소스

- **사용자 입력 CSV** (사이드바 업로드): lot 재고, 온도 로그, 등록 로그, accountability, site 마스터.
- **합성 데모 데이터셋** (`data/*.csv`, 시드 고정 재현 가능): `data/generate_demo_data.py`로 생성.
- **내장 reference 템플릿**: IMP별 dose/주·kit당 dose·안정성 budget(`engine.py`의 `IMP_MASTER`).

### 입력 CSV 스키마

| 파일 | 주요 컬럼 |
|---|---|
| `lots.csv` | lot_id, imp, expiry_date, qty_kits, kit_doses, received_date, storage, status |
| `temperature_log.csv` | lot_id, imp, shipment_id, site_id, timestamp, temp_c |
| `enrollment_log.csv` | site_id, week_start, week_index, subject_id, arm |
| `accountability.csv` | txn_id, site_id, imp, lot_id, txn_type(shipped_to_site/dispensed/returned/destroyed), qty_kits, date |
| `sites.csv` | site_id, site_name, region, imp, on_hand_kits, par_level_kits, lead_time_days |

## 검수 체크리스트

- [x] `python3 -c "import ast; ast.parse(open('app.py').read())"` — 구문 OK
- [x] `python3 data/generate_demo_data.py` — CSV 5종 생성
- [x] 합성 CSV pandas 로드 (shape 확인)
- [x] requirements 핵심 import(streamlit/pandas/scipy) 가능, simpy/plotly는 명시(graceful fallback 검증)
- [x] engine 5개 함수 단위 테스트 통과
- [x] QUARANTINE/USABLE 분기 및 MISMATCH 검출 동작 확인
- [x] 디스클레이머 UI 상단·README 포함

자세한 검수 로그는 `QA.md` 참조.

## 출처 / 근거

- **ICH GCP E6(R3)** §8 — IMP accountability(수령·불출·반납·폐기 기록 및 reconciliation).
- **GMP cold-chain** — 2–8°C 보관·콜드체인 유지 원칙.
- **IATA PCR**(Perishable Cargo Regulations) — cold-chain 항공 운송 온도관리 원칙.
- **주사제 안정성 budget** — IMP 라벨/안정성 데이터 기반 누적 실온 허용 시간(본 MVP는 데모 템플릿 값 사용; 실제 값은 제품 안정성 데이터로 대체 필요).

> 모든 reference 값은 데모/템플릿이며, 실제 규제 의사결정 시 해당 제품의 안정성 데이터·기관 SOP·규제 문서를 따른다.