From 7d8a9e08a93aab16f1a1994dd2e04687d4645a46 Mon Sep 17 00:00:00 2001 From: airkjw Date: Thu, 26 Mar 2026 12:55:00 +0900 Subject: [PATCH] docs: add hospital CS center PRD Co-Authored-By: Claude Sonnet 4.6 --- docs/PRD.md | 282 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 282 insertions(+) create mode 100644 docs/PRD.md diff --git a/docs/PRD.md b/docs/PRD.md new file mode 100644 index 0000000..e438d4a --- /dev/null +++ b/docs/PRD.md @@ -0,0 +1,282 @@ +# PRD: 병원 CS 센터 AI 챗봇 (Gov-chat-bot 기반) + +> 작성일: 2026-03-26 +> 기반 코드: sinmb79/Gov-chat-bot (SmartBot KR v0.2.0) + +--- + +## 1. 개요 (Overview) + +### 1.1 목적 + +전화·방문 위주의 병원 고객센터(CS) 업무를 AI 챗봇으로 1차 응대함으로써 **반복 문의를 자동화하고 상담사 부하를 줄인다.** 환자·보호자가 24시간 언제든지 진료 예약, 서류 발급, 위치 안내 등 기본 문의를 해결할 수 있도록 한다. + +### 1.2 배경 + +Gov-chat-bot은 공공기관용 멀티테넌트 AI 챗봇 플랫폼으로, 다음 기능을 이미 갖추고 있다. + +- **Tier A–D 응답 라우팅**: FAQ → RAG 문서 검색 → LLM 생성 → 폴백 순서로 자동 선택 +- **개인정보 마스킹**: 주민등록번호, 전화번호, 이메일 자동 처리 (의료 현장에서 필수) +- **멀티채널**: 웹 위젯 + 카카오톡 채널 동시 지원 +- **관리자 대시보드**: FAQ·문서·민원·지표 관리 +- **감사 로그 / 모더레이션**: 운영 투명성 확보 + +병원 CS 특성상 **환자 개인정보 보호**, **정확한 의료 정보 제공(할루시네이션 방지)**, **24시간 응대** 요구사항이 있으며, 현 코드베이스는 이 방향에 잘 맞는다. + +--- + +## 2. 현재 코드 분석 요약 + +### 2.1 아키텍처 + +``` +[환자/보호자] + │ 웹 위젯 / 카카오톡 + ▼ +[Frontend: React Admin Dashboard + JS Widget] + │ + ▼ +[Backend: FastAPI] + ├─ /skill/{tenant} ← 카카오톡 스킬 서버 + ├─ /engine/query ← 웹 위젯 엔진 + └─ /api/admin/* ← 관리자 API (JWT) + │ + ├─ [PostgreSQL] ← 테넌트, FAQ, 문서, 민원 로그 + ├─ [Redis] ← 멱등성 캐시 (중복 요청 방지) + └─ [ChromaDB] ← 벡터 검색 (FAQ/문서 임베딩) +``` + +### 2.2 응답 라우팅 (Tier) + +| Tier | 방식 | 조건 | 병원 활용 예 | +|------|------|------|-------------| +| **A** | FAQ 벡터 유사도 | 유사도 ≥ 0.85 | "외래 접수 시간은?" → 등록된 답변 즉시 반환 | +| **B** | RAG 문서 검색 | 유사도 ≥ 0.70 | "MRI 촬영 전 주의사항" → 업로드된 안내문 기반 | +| **C** | LLM + RAG | LLM 활성화 + 문서 존재 | RAG 결과를 Claude/GPT로 자연스럽게 재작성 | +| **D** | 폴백 | 매칭 없음 | "담당 상담사에게 연결해 드리겠습니다" | + +### 2.3 강점 (병원 CS 맥락) + +- **개인정보 마스킹**: 환자 발화에서 주민번호·전화번호 자동 제거 → HIPAA/개인정보보호법 대응 가능 +- **할루시네이션 제어**: LLM은 RAG 청크가 있을 때만 호출, 시스템 프롬프트에서 추측 금지 +- **4.5초 타임아웃**: 카카오톡 5초 제한에 맞춘 설계 +- **감사 로그**: 관리자 행동 전체 기록 (의료기관 컴플라이언스 필요) +- **멱등성 캐시**: 동일 요청 중복 처리 방지 (환자 버튼 연타 등) + +### 2.4 현재 한계 / 개선 필요 사항 + +| 구분 | 현재 상태 | 병원 적용 시 필요한 개선 | +|------|-----------|--------------------------| +| **대화 맥락** | 이전 턴 저장 없음 (무상태) | 예약 확인 등 멀티턴 흐름 필요 | +| **예약 시스템 연동** | 없음 | HIS(병원정보시스템) API 연동 필요 | +| **상담사 이관** | Tier D 폴백 텍스트만 | 실시간 상담사 연결 흐름 필요 | +| **카카오 채널 인증** | 스킬 서버 → 백엔드 서명 없음 | HMAC 검증 추가 권장 | +| **속도 제한** | 유저키 기반 모더레이션만 | 병원 규모에 따라 IP/분당 제한 추가 고려 | +| **문서 버전 UI** | DB 컬럼은 있으나 UI 미노출 | 진료 안내문 개정 이력 관리 필요 | +| **임베딩 모델** | ko-sroberta (단일 고정) | 의료 도메인 파인튜닝 모델 교체 고려 | + +--- + +## 3. 제품 목표 (Goals) + +### 3.1 핵심 목표 + +1. **반복 문의 자동화율 70%** — 진료 시간·예약 방법·위치·서류 발급 등 상위 문의 유형 70% 이상을 챗봇이 자체 해결 +2. **24시간 응대** — 야간·주말에도 기본 문의 처리 +3. **개인정보 0 노출** — 발화 원문 비저장, PII 자동 마스킹으로 의료 개인정보보호 준수 +4. **상담사 업무 경감** — CS 인입 콜 20% 이상 감소 + +### 3.2 비목표 (Out of Scope) + +- 의학적 진단·처방 안내 (챗봇은 의료 행위 불가) +- 실시간 진료 예약 처리 (1차 목표; HIS 연동은 2단계) +- 보험청구 업무 처리 + +--- + +## 4. 사용자 및 시나리오 + +### 4.1 사용자 유형 + +| 유형 | 설명 | 주요 문의 | +|------|------|-----------| +| **외래 환자** | 진료 예약, 접수, 검사 안내 | "내과 예약은 어떻게 해요?" "오늘 대기 얼마나 걸려요?" | +| **입원 환자/보호자** | 병동 규정, 면회, 식사 안내 | "면회 시간이 언제예요?" "보호자 주차 어떻게 해요?" | +| **서류 발급 문의** | 진단서, 소견서 등 | "진단서 발급 비용이 얼마예요?" "어디서 받나요?" | +| **응급 상황 문의** | 응급실 위치·이용 방법 | "응급실은 24시간인가요?" | +| **병원 관리자** | FAQ·문서 관리, 지표 확인 | 대시보드 사용 | + +### 4.2 핵심 시나리오 + +#### 시나리오 1 — 진료 예약 안내 (Tier A) +``` +환자: "내과 예약하려면 어떻게 해요?" +봇: "내과 예약은 아래 방법으로 가능합니다. + ① 전화 예약: 02-0000-0000 (평일 08:30–17:30) + ② 온라인 예약: 병원 홈페이지 > 예약/조회 + ③ 원무과 방문 접수 + 초진이신 경우 신분증을 지참해 주세요." +``` + +#### 시나리오 2 — 문서 기반 검사 안내 (Tier B/C) +``` +환자: "위내시경 전날 뭐 먹으면 안 되나요?" +봇: "[위내시경 검사 안내문 기반] + 검사 전날 저녁 9시 이후 금식이 필요합니다. + 물, 약 복용은 담당 의사 지시에 따라 주세요. + 자세한 내용은 검사 안내문을 참고하세요." +``` + +#### 시나리오 3 — 상담사 이관 (Tier D) +``` +환자: "제 검사 결과가 이상한 것 같아요." +봇: "검사 결과에 대한 자세한 안내는 + 담당 진료과 간호사 또는 상담사를 통해 확인하시기 바랍니다. + ☎ 상담 전화: 02-0000-1234 (평일 09:00–18:00)" +``` + +--- + +## 5. 기능 요구사항 + +### 5.1 MVP (1단계) + +| ID | 기능 | 구현 방법 | 우선순위 | +|----|------|-----------|---------| +| F-01 | 병원 FAQ 챗봇 (진료시간·위치·예약방법) | 기존 Tier A/B 그대로 활용 | **P0** | +| F-02 | 카카오톡 채널 연동 | 기존 `/skill/{tenant}` 활용 | **P0** | +| F-03 | 웹사이트 위젯 삽입 | 기존 `govbot-widget.js` 활용 | **P0** | +| F-04 | 관리자 FAQ 등록/수정 | 기존 Admin Dashboard 활용 | **P0** | +| F-05 | 의료 안내 문서 업로드 (PDF/Word) | 기존 문서 업로드 파이프라인 활용 | **P0** | +| F-06 | PII 마스킹 (환자 발화 보호) | 기존 masking 서비스 활용 | **P0** | +| F-07 | 병원 전용 폴백 메시지 설정 | `tenant_configs`에서 관리 | **P0** | +| F-08 | LLM 연동 (Claude Haiku) | `.env`에서 `LLM_PROVIDER=anthropic` 설정 | **P1** | +| F-09 | 민원/문의 로그 열람 (마스킹 상태) | 기존 Complaints 페이지 활용 | **P1** | +| F-10 | 응답 지표 대시보드 | 기존 Metrics 페이지 활용 | **P1** | + +### 5.2 2단계 (개선 과제) + +| ID | 기능 | 비고 | +|----|------|------| +| F-11 | 멀티턴 대화 컨텍스트 유지 | Redis에 세션 저장, 예약 흐름 지원 | +| F-12 | HIS 예약 시스템 API 연동 | 실시간 예약 가능 여부 조회 | +| F-13 | 상담사 이관 (LiveChat 연동) | Tier D 시 Slack/Zendesk 알림 | +| F-14 | 진료과별 FAQ 분류 | category 필드 활용, 탭 UI 추가 | +| F-15 | 음성 입력 (STT) 지원 | 고령 환자 접근성 향상 | +| F-16 | 문서 개정 이력 UI | `supersedes_id` 컬럼 활용 | +| F-17 | 의료 도메인 임베딩 모델 교체 | ko-sroberta → 의료 파인튜닝 모델 | + +--- + +## 6. 비기능 요구사항 + +| 구분 | 요구사항 | +|------|---------| +| **응답 속도** | 95 퍼센타일 3초 이내 (카카오 5초 제한 준수) | +| **가용성** | 99.5% 이상 (월 3.6시간 이하 다운타임) | +| **개인정보** | 환자 발화 원문 미저장, PII 자동 마스킹 의무화 | +| **보안** | JWT 24시간 만료, bcrypt 비밀번호 해시, CORS 화이트리스트 | +| **컴플라이언스** | 개인정보보호법, 의료법 제21조 (정보 누설 금지) 준수 | +| **감사** | 관리자 모든 행동 audit_logs 기록 | +| **확장성** | 멀티테넌트 구조 — 분원·부속병원 추가 용이 | + +--- + +## 7. 기술 스택 및 인프라 + +### 현재 스택 (변경 없이 활용 가능) + +``` +Backend: FastAPI (Python) + SQLAlchemy + asyncpg +Frontend: React 18 + Vite +Vector: ChromaDB + jhgan/ko-sroberta-multitask (한국어 임베딩) +DB: PostgreSQL 16 +Cache: Redis 7 +LLM: Anthropic Claude Haiku (권장) 또는 OpenAI GPT-4o-mini +Deploy: Docker Compose (NAS 자체 운영) +``` + +### 배포 환경 (CLAUDE.md 기준) + +| 항목 | 값 | +|------|-----| +| 서버 | NAS (nas.gru.farm) | +| 내부 IP | 192.168.0.17 | +| Docker | `sudo /usr/local/bin/docker` | +| Gitea | http://nas.gru.farm:3001/airkjw/Gov-chat-bot | + +--- + +## 8. 데이터 모델 (병원 맥락 주요 테이블) + +```sql +-- 병원 테넌트 설정 예시 +INSERT INTO tenants (name, slug) VALUES ('○○병원', 'hospital-oo'); + +-- 병원 전용 설정 +INSERT INTO tenant_configs (tenant_id, key, value) VALUES + (1, 'fallback_message', '"담당 상담사 연결: 02-0000-1234"'), + (1, 'llm_system_prompt', '"당신은 ○○병원 안내 챗봇입니다. 의학적 진단은 하지 않습니다."'), + (1, 'tier_a_threshold', '0.85'), + (1, 'tier_b_threshold', '0.70'); + +-- 주요 FAQ 카테고리 +-- category: 진료안내 / 예약접수 / 검사안내 / 서류발급 / 시설안내 / 응급안내 +``` + +--- + +## 9. 구현 로드맵 + +### Phase 1 — MVP (4주) + +| 주차 | 작업 | +|------|------| +| 1주 | NAS Docker 배포, 병원 테넌트 생성, `.env` 설정 (Claude API 키 등) | +| 2주 | 주요 FAQ 100건 이상 등록 (진료과별 운영시간, 예약, 위치, 서류 발급) | +| 3주 | 의료 안내 문서 업로드 (검사 전 주의사항 PDF 등), 웹 위젯 홈페이지 삽입 | +| 4주 | 카카오톡 채널 연동, QA 테스트, 오픈 | + +### Phase 2 — 고도화 (8주) + +| 주차 | 작업 | +|------|------| +| 5–6주 | 멀티턴 컨텍스트, 진료과별 FAQ 분류 UI | +| 7–8주 | 상담사 이관 흐름 (Tier D → 알림 발송) | +| 9–10주 | HIS 예약 API 파일럿 연동 | +| 11–12주 | 성과 분석, 임베딩 모델 튜닝 검토 | + +--- + +## 10. 성공 지표 (KPI) + +| 지표 | 목표 | 측정 방법 | +|------|------|-----------| +| 자동 해결율 | ≥ 70% | Tier A+B+C 응답 비율 (`admin_metrics`) | +| 평균 응답 시간 | ≤ 2초 | `complaint_logs.response_ms` 중앙값 | +| 폴백(Tier D) 비율 | ≤ 30% | Tier D 응답 비율 | +| 카카오 타임아웃 | ≤ 1% | `complaint_logs.is_timeout` 비율 | +| 상담 콜 감소율 | ≥ 20% | 월별 CS 인입 콜 수 비교 (오픈 3개월 후) | +| 관리자 FAQ 갱신 주기 | ≤ 2주 | `faqs.updated_at` 기준 | + +--- + +## 11. 리스크 및 대응 + +| 리스크 | 가능성 | 영향 | 대응 | +|--------|--------|------|------| +| 챗봇이 잘못된 의료 정보 제공 | 중 | 높음 | LLM 시스템 프롬프트에 의학적 판단 금지 명시, RAG 기반만 사용, 민감 키워드 Tier D 강제 라우팅 | +| 환자 개인정보 유출 | 낮 | 매우 높음 | PII 마스킹 (기존 구현), 발화 원문 미저장, HTTPS 필수 | +| 카카오톡 API 변경 | 낮 | 중 | 웹 위젯 병행 운영 | +| 임베딩 유사도 오매칭 | 중 | 중 | Tier A 임계값(0.85) 유지, 주기적 FAQ 품질 검토 | +| NAS 단일 장애점 | 중 | 높음 | 백업 스케줄, 향후 클라우드 이전 검토 | + +--- + +## 12. 참고 문서 + +- `docs/운영가이드.md` — 시스템 운영 절차 +- `docs/WSL2_가이드.md` — Windows 개발 환경 설정 +- `backend/app/core/config.py` — 환경변수 전체 목록 +- `docker-compose.yml` — 서비스 구성 +- `.env.example` — 환경변수 템플릿