diff --git a/docs/PAAI-SYSTEM.md b/docs/PAAI-SYSTEM.md new file mode 100644 index 0000000..04578ba --- /dev/null +++ b/docs/PAAI-SYSTEM.md @@ -0,0 +1,359 @@ +# PAAI (Pharmacist Assistant AI) 시스템 + +> 약사를 위한 AI 기반 처방 분석 및 복약지도 보조 시스템 + +## 📋 목차 +1. [시스템 개요](#시스템-개요) +2. [구현 현황](#구현-현황) +3. [아키텍처](#아키텍처) +4. [데이터베이스](#데이터베이스) +5. [API 엔드포인트](#api-엔드포인트) +6. [어드민 페이지](#어드민-페이지) +7. [향후 계획](#향후-계획) + +--- + +## 시스템 개요 + +### 목적 +- 처방전 분석 시 KIMS 약물 상호작용 자동 확인 +- AI 기반 복약지도 포인트 추천 +- OTC 구매 이력 기반 맞춤 상담 제안 +- 처방 변화 감지 및 분석 + +### 핵심 기능 +1. **KIMS 상호작용 조회** - 처방 약품 간 상호작용 자동 체크 +2. **AI 분석** - Clawdbot(Claude) 기반 처방 인사이트 생성 +3. **처방 비교** - 이전 처방과 현재 처방 변화 분석 +4. **OTC 연계** - 환자 OTC 구매 이력 기반 추천 + +--- + +## 구현 현황 + +### ✅ 완료된 기능 + +#### PMR (조제관리) 페이지 +- [x] 환자 목록 / 처방 상세 조회 +- [x] 이전 처방 비교 모드 (추가/변경/중단/동일 표시) +- [x] OTC 구매 이력 모달 +- [x] PAAI 분석 버튼 + +#### PAAI 분석 기능 +- [x] KIMS API 연동 (약물 상호작용 조회) +- [x] Clawdbot Gateway 연동 (AI 분석) +- [x] 비동기 토스트 알림 (다른 환자 보면서도 알림 수신) +- [x] 분석 결과 캐싱 (환자별) +- [x] 피드백 수집 (유용/비유용) + +#### 토스트 알림 시스템 +- [x] 우상단 오버레이 토스트 +- [x] A환자 분석 중 → B환자 조회 가능 +- [x] 토스트 클릭 시 해당 환자 결과 모달 + +### 🚧 진행 중 + +#### 어드민 페이지 +- [ ] 피드백 통계 대시보드 +- [ ] 분석 이력 검색 +- [ ] KIMS 호출 로그 +- [ ] AI 요청/응답 로그 + +--- + +## 아키텍처 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ PMR 페이지 (pmr.html) │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ +│ │ 환자 목록 │ │ 처방 상세 │ │ PAAI 토스트/모달 │ │ +│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ Flask API (pmr_api.py) │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ +│ │ /pmr/api/ │ │ /pmr/api/ │ │ /pmr/api/paai/ │ │ +│ │ prescriptions│ │ patient/ │ │ analyze, feedback │ │ +│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ + │ + ┌───────────────┼───────────────┐ + ▼ ▼ ▼ +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ PIT3000 DB │ │ KIMS API │ │ Clawdbot Gateway│ +│ (MSSQL) │ │ (상호작용) │ │ (Claude AI) │ +│ │ │ │ │ │ +│ - PM_PRES │ │ - 약품 검색 │ │ - WebSocket │ +│ - PM_DRUG │ │ - 상호작용 조회 │ │ - 세션 관리 │ +│ - PM_CUS │ │ │ │ │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ + │ + ▼ + ┌─────────────────┐ + │ SQLite DB │ + │ (paai_logs) │ + │ │ + │ - 분석 로그 │ + │ - 피드백 │ + │ - KIMS 로그 │ + └─────────────────┘ +``` + +--- + +## 데이터베이스 + +### paai_logs 테이블 (SQLite) + +```sql +CREATE TABLE IF NOT EXISTS paai_logs ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + + -- 환자/처방 정보 + pre_serial TEXT, -- 처방전 번호 + cus_code TEXT, -- 환자 코드 + patient_name TEXT, -- 환자명 + + -- 질병 정보 + disease_codes TEXT, -- JSON: ["M750", "K299"] + disease_names TEXT, -- JSON: ["어깨 유착성 관절낭염", "위십이지장염"] + + -- 처방 정보 + medication_count INTEGER, -- 약품 수 + medications_json TEXT, -- JSON: 전체 약품 리스트 + + -- KIMS 결과 + kims_called BOOLEAN, -- KIMS 호출 여부 + kims_request_json TEXT, -- KIMS 요청 데이터 + kims_response_json TEXT, -- KIMS 응답 원본 + kims_interaction_count INTEGER, -- 상호작용 건수 + kims_has_severe BOOLEAN, -- 중증 상호작용 여부 + kims_duration_ms INTEGER, -- KIMS 응답 시간 + + -- AI 분석 결과 + ai_called BOOLEAN, -- AI 호출 여부 + ai_prompt_json TEXT, -- AI에게 전달한 프롬프트 + ai_response_json TEXT, -- AI 응답 원본 + ai_parsed_json TEXT, -- 파싱된 분석 결과 + ai_duration_ms INTEGER, -- AI 응답 시간 + ai_model TEXT, -- 사용 모델 (claude-opus-4-5 등) + + -- 피드백 + feedback_useful BOOLEAN, -- 유용했는지 + feedback_at TIMESTAMP, -- 피드백 시간 + feedback_comment TEXT, -- 추가 코멘트 (향후) + + -- 메타 + total_duration_ms INTEGER, -- 전체 처리 시간 + error_message TEXT, -- 에러 발생 시 + client_ip TEXT -- 요청 IP +); + +-- 인덱스 +CREATE INDEX idx_paai_created ON paai_logs(created_at); +CREATE INDEX idx_paai_patient ON paai_logs(cus_code); +CREATE INDEX idx_paai_feedback ON paai_logs(feedback_useful); +``` + +--- + +## API 엔드포인트 + +### PAAI 분석 + +#### POST `/pmr/api/paai/analyze` + +**요청:** +```json +{ + "pre_serial": "20260305001", + "cus_code": "C00123", + "patient_name": "김미성", + "disease_info": { + "code_1": "M750", + "name_1": "어깨의 유착성 관절낭염", + "code_2": "K299", + "name_2": "상세불명의 위십이지장염" + }, + "current_medications": [ + {"code": "641500020", "name": "아세탑정", "dosage": "1", "frequency": "2", "days": "5"} + ], + "previous_medications": [], + "otc_history": { + "visit_count": 5, + "frequent_items": [{"name": "신신파스", "count": 3}] + } +} +``` + +**응답:** +```json +{ + "success": true, + "log_id": 42, + "kims_summary": { + "interaction_count": 2, + "has_severe": false, + "interactions": [...] + }, + "analysis": { + "prescription_insight": "소염진통제와 위장약 병용 처방...", + "kims_analysis": "아세클로페낙과 레바미피드 병용은...", + "cautions": ["식후 30분 복용", "위장장애 주의"], + "otc_recommendations": [ + {"product": "신신파스", "reason": "근골격계 통증 보조"} + ], + "counseling_points": ["충분한 수분 섭취", "알코올 자제"] + }, + "timing": { + "kims_ms": 234, + "ai_ms": 2891, + "total_ms": 3125 + } +} +``` + +### 피드백 + +#### POST `/pmr/api/paai/feedback` + +**요청:** +```json +{ + "log_id": 42, + "useful": true +} +``` + +--- + +## 어드민 페이지 + +### 📊 대시보드 (`/pmr/admin`) + +#### 1. 개요 통계 +``` +┌─────────────────────────────────────────────────────────────┐ +│ 📊 PAAI 어드민 대시보드 [날짜 선택] │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ 127 │ │ 89% │ │ 15건 │ │ 2.3초 │ │ +│ │ 총 분석 │ │ 유용 평가│ │KIMS 경고 │ │ 평균응답 │ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +#### 2. 피드백 통계 +- 일별/주별/월별 유용/비유용 비율 차트 +- 비유용 피드백 많은 케이스 분석 + +#### 3. 분석 이력 검색 +``` +┌─────────────────────────────────────────────────────────────┐ +│ 🔍 분석 이력 │ +├─────────────────────────────────────────────────────────────┤ +│ 환자명: [_________] 기간: [____] ~ [____] [검색] │ +├─────────────────────────────────────────────────────────────┤ +│ # │ 일시 │ 환자 │ 약품수│ KIMS │ 피드백│ 상세 │ +│ ───┼────────────┼─────────┼───────┼──────┼───────┼─────── │ +│ 1 │ 03-05 14:32│ 김미성 │ 4 │ 2건 │ 👍 │ [보기] │ +│ 2 │ 03-05 14:28│ 박철수 │ 6 │ 0건 │ 👎 │ [보기] │ +│ 3 │ 03-05 14:15│ 이영희 │ 3 │ 1건 │ - │ [보기] │ +└─────────────────────────────────────────────────────────────┘ +``` + +#### 4. 상세 로그 보기 (모달) +``` +┌─────────────────────────────────────────────────────────────┐ +│ 📋 분석 상세 - 김미성님 (2026-03-05 14:32) [닫기] │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ▼ 환자/처방 정보 │ +│ 처방번호: 20260305001 │ +│ 질병: [M750] 어깨 유착성 관절낭염, [K299] 위십이지장염 │ +│ 약품: 아세탑정, 에페솔정, 레바미피드정, 브로나제정 │ +│ │ +│ ▼ KIMS 호출 (234ms) │ +│ 요청: {"medications": ["641500020", "645678901", ...]} │ +│ 응답: {"interactions": [...], "count": 2} │ +│ │ +│ ▼ AI 프롬프트 │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ 당신은 약사를 보조하는 AI입니다... │ │ +│ │ ## 환자 질병 │ │ +│ │ [M750] 어깨의 유착성 관절낭염... │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ │ +│ ▼ AI 응답 (2891ms) │ +│ 모델: claude-opus-4-5 │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ { │ │ +│ │ "prescription_insight": "소염진통제와...", │ │ +│ │ "kims_analysis": "아세클로페낙과...", │ │ +│ │ "cautions": ["식후 30분 복용", ...], │ │ +│ │ ... │ │ +│ │ } │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ │ +│ ▼ 피드백 │ +│ 평가: 👍 유용해요 │ +│ 시간: 2026-03-05 14:35:21 │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +#### 5. KIMS 호출 로그 +- 일별 KIMS API 호출 횟수 +- 상호작용 감지율 +- 중증 경고 발생 케이스 + +#### 6. AI 성능 모니터링 +- 평균 응답 시간 추이 +- 에러율 +- 모델별 사용량 + +--- + +## 향후 계획 + +### Phase 1 (현재) +- [x] 기본 PAAI 분석 기능 +- [x] 비동기 토스트 알림 +- [ ] 어드민 페이지 기본 + +### Phase 2 +- [ ] 피드백 기반 프롬프트 개선 +- [ ] 자주 나오는 상담 포인트 학습 +- [ ] 약국별 맞춤 설정 + +### Phase 3 +- [ ] 다중 약국 지원 +- [ ] 분석 결과 PDF 출력 +- [ ] 환자용 복약지도 문자 발송 연동 + +--- + +## 파일 구조 + +``` +backend/ +├── pmr_api.py # Flask API 서버 +├── services/ +│ ├── kims_service.py # KIMS API 연동 +│ └── clawdbot_client.py # Clawdbot Gateway 연동 +├── templates/ +│ ├── pmr.html # 조제관리 페이지 +│ └── pmr_admin.html # 어드민 페이지 (예정) +└── db/ + └── paai_logs.db # PAAI 로그 SQLite +``` + +--- + +*최종 업데이트: 2026-03-05*