# 🤖 SmartBot KR — 누구나 쓰는 AI 챗봇 플랫폼

> **코딩 몰라도 됩니다.** 설치부터 운영까지 한 번에.

카카오톡 채팅, 홈페이지 위젯으로 고객 질문에 AI가 자동으로 답변합니다.
지자체·음식점·쇼핑몰·병원·학원 등 **어떤 조직이든 바로 사용 가능**합니다.

---

## 이런 분께 딱 맞습니다

| 사용처 | 활용 예시 |
|--------|-----------|
| 🏛️ **지자체·공공기관** | 민원 안내, 서류 발급 방법, 담당부서 연결 |
| 🍽️ **음식점·카페** | 메뉴 문의, 영업시간, 예약, 주차 안내 |
| 🛍️ **쇼핑몰·온라인몰** | 배송 조회, 교환·환불 정책, 상품 문의 |
| 🏥 **병원·의원·약국** | 진료시간, 예약 방법, 보험 안내 |
| 🎓 **학원·교육기관** | 수업 일정, 수강료, 입학 상담 |
| 🏢 **일반 기업** | 고객 CS 자동화, 사내 FAQ 봇 |

---

## ✨ 주요 기능

| 기능 | 설명 |
|------|------|
| 💬 **카카오톡 연동** | 카카오 i 오픈빌더 스킬 서버로 바로 연결 |
| 🌐 **홈페이지 위젯** | 코드 한 줄로 어느 홈페이지에나 삽입 |
| ❓ **FAQ 자동 답변** | 등록한 FAQ를 AI가 유사도로 매칭해 즉시 답변 |
| 📄 **문서 학습** | PDF·Word 파일 업로드 → AI가 자동으로 학습 |
| 🤖 **LLM 연동** | Claude·GPT 연결 시 더 자연스러운 답변 (선택) |
| 📊 **관리 대시보드** | 통계·FAQ·문서·대화이력 한눈에 관리 |
| 🔒 **개인정보 보호** | 고객 발화 자동 마스킹, 원문 미저장 |
| 🏢 **멀티 조직 지원** | 하나의 서버로 여러 매장/지점 각각 운영 |

---

## 🚀 5분 설치

### Linux / macOS

```bash
git clone https://github.com/sinmb79/Gov-chat-bot.git
cd Gov-chat-bot
chmod +x install.sh
./install.sh
```

> **Windows 사용자** → [Windows 설치 가이드](docs/WSL2_가이드.md)

### 설치 후 접속

```
관리자 화면:  http://localhost:3000
API 문서:     http://localhost:8000/docs
```

---

## 📋 시스템 요구사항

| 항목 | 최소 |
|------|------|
| OS | Ubuntu 20.04+ / macOS 13+ / Windows 11 (WSL2) |
| RAM | 4GB |
| 디스크 | 20GB |
| Docker | 24.x 이상 |
| 인터넷 | 설치 시 필요 (이후 오프라인 운영 가능) |

---

## 📖 사용 방법

### 1단계 — 관리자 계정 만들기

```bash
docker compose exec backend python -m app.scripts.create_admin
```

조직 ID(영문), 이메일, 비밀번호를 입력하면 완료.

### 2단계 — FAQ 등록하기

1. http://localhost:3000 에서 로그인
2. **FAQ 관리** → **+ FAQ 추가**
3. 카테고리, 질문, 답변 입력 → 저장

> **팁**: 같은 뜻이지만 표현이 다른 질문을 여러 개 등록할수록 인식률이 높아집니다.
> - "영업시간이요?" / "몇시에 열어요?" / "오늘 언제까지 해요?" → 같은 답변으로 등록

### 3단계 — 문서 업로드하기 (선택)

자주 묻는 내용이 담긴 PDF, Word 파일을 올리면 AI가 자동으로 학습합니다.

1. **문서 관리** → **+ 문서 업로드**
2. 파일 선택 (PDF · Word · 텍스트)
3. 처리 완료 후 **승인** 클릭

### 4단계 — 테스트하기

**시뮬레이터** 메뉴에서 실제 질문을 입력해 답변을 미리 확인할 수 있습니다.

### 5단계 — 홈페이지에 위젯 달기

홈페이지 HTML에 아래 코드를 붙여넣기만 하면 됩니다.

```html
<script
  src="http://내서버주소/widget/govbot-widget.js"
  data-tenant="내조직ID"
  data-api="http://내서버주소"
  data-title="AI 도우미"
  data-color="#2563eb"
></script>
```

---

## ⚙️ 환경 설정

```bash
# 설정 파일 복사
cp .env.example .env

# 텍스트 에디터로 열어서 수정
nano .env   # 또는 메모장으로 열기
```

**반드시 바꿔야 할 항목:**

| 항목 | 설명 |
|------|------|
| `SECRET_KEY` | 보안 키 (아무 긴 문자열, 32자 이상) |

**선택 항목 (LLM 연결):**

| 항목 | 설명 |
|------|------|
| `LLM_PROVIDER=anthropic` | Claude AI 사용 |
| `ANTHROPIC_API_KEY=...` | Claude API 키 |
| `LLM_PROVIDER=openai` | ChatGPT 사용 |
| `OPENAI_API_KEY=...` | OpenAI API 키 |

> LLM 없이도 FAQ + 문서 기반 답변이 충분히 잘 동작합니다. 처음에는 LLM 없이 시작하세요.

---

## 🏗️ 동작 원리

고객이 질문하면 아래 순서로 가장 적합한 답변을 찾습니다.

```
고객 질문
    │
    ▼
① FAQ 검색 (등록된 FAQ와 유사도 비교)
    │ 비슷한 FAQ 있음 → 즉시 답변
    │ 없음 ↓
    ▼
② 문서 검색 (업로드한 파일에서 관련 내용 추출)
    │ 관련 내용 있음 + LLM 연결됨 → AI가 자연스럽게 재서술
    │ 관련 내용 있음 + LLM 없음   → 문서 내용 그대로 안내
    │ 없음 ↓
    ▼
③ 담당자 안내 (설정한 연락처로 안내)
```

---

## 📁 파일 구조

```
Gov-chat-bot/
├── backend/          # AI 서버 (자동 관리, 직접 수정 불필요)
├── frontend/         # 관리자 화면 (자동 관리)
│   └── widget/       # 홈페이지 위젯 파일
├── docs/
│   ├── 운영가이드.md  # 상세 운영 설명서
│   └── WSL2_가이드.md # Windows 설치 방법
├── docker-compose.yml # 서비스 실행 설정
├── install.sh        # 자동 설치 스크립트
└── .env.example      # 환경 설정 예시
```

---

## 🔧 자주 묻는 질문 (설치·운영)

**Q. 클라우드 서버가 있어야 하나요?**
A. 아니요. 사무실 컴퓨터(윈도우·맥·리눅스)에서 바로 실행됩니다. 외부에서 접속하려면 공인 IP나 클라우드 서버가 필요합니다.

**Q. 카카오톡 계정이 있어야 하나요?**
A. 카카오톡 연동은 선택 사항입니다. 홈페이지 위젯만으로도 운영할 수 있습니다.

**Q. LLM(Claude·ChatGPT) API 비용이 걱정돼요.**
A. LLM 연결 없이도 FAQ + 문서 기반 답변이 잘 작동합니다. LLM은 나중에 필요할 때 추가하면 됩니다.

**Q. 고객 대화 내용이 외부로 나가나요?**
A. LLM을 사용하지 않으면 외부 API 호출이 전혀 없습니다. 모든 데이터가 내 서버 안에만 있습니다.

**Q. 여러 매장을 동시에 운영할 수 있나요?**
A. 네. 매장마다 별도의 조직 ID를 만들면 데이터가 완전히 분리되어 관리됩니다.

**Q. 문제가 생기면 어떻게 하나요?**
A. 로그 확인: `docker compose logs backend`
   [Issues](https://github.com/sinmb79/Gov-chat-bot/issues)에 남겨주시면 도움드립니다.

---

## 🔒 개인정보 보호

- 고객 발화에서 **주민번호·전화번호·이메일·카드번호** 자동 감지 후 마스킹
- 원문은 서버에 **절대 저장되지 않음**
- 사용자 ID는 **복원 불가능한 해시값**으로만 저장
- 관리자도 원문 열람 불가 (마스킹 상태로만 표시)

---

## 🧪 개발자 정보

```bash
cd backend
pip install -r requirements.txt
pytest tests/ -v
# 127 tests passing
```

**기술 스택**: Python · FastAPI · PostgreSQL · Redis · ChromaDB · React · Docker

---

## 🤝 기여 방법

버그 제보, 기능 제안, 코드 기여 모두 환영합니다!

1. 저장소 Fork
2. 브랜치 생성: `git checkout -b feature/기능명`
3. 커밋: `git commit -m "feat: 설명"`
4. Pull Request 생성

---

## 📄 라이선스

[MIT License](LICENSE) — **무료**, 상업적 이용 가능, 수정·재배포 자유