docs: add hospital CS center PRD

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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` — 환경변수 템플릿