thug0bin/pharmacy-pos-qr-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: PAAI 시스템 아키텍처 문서

Browse Source 
- 시스템 개요 및 데이터 흐름
- API 엔드포인트 정리
- Clawdbot 연동 방법
- 트러블슈팅 가이드
This commit is contained in:
thug0bin 2026-03-05 09:30:39 +09:00
parent 16c3881661
commit f3b6496c91
1 changed files with 359 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

359
docs/PAAI-SYSTEM.md Normal file
View File

@ -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*