clinic-agent

# 🏥 诊所智能预约挂号客服系统

用于诊所医生预约挂号场景。

## ✅ 功能特性

* 对话式预约挂号全流程交互

* 支持 5 位不同科室出诊医生的号源匹配

* 基于时间段的精细化号源选择

* 纯大模型智能路由（无正则匹配、无硬编码规则）

* 状态驱动的多轮对话设计

* Streamlit UI 可视化可点击选项交互

* SQLite 本地数据持久化存储

## 📁 项目结构

运行前先利用data/db.py创建表和保存数据

```
clinic-agent/

├── agents/

│   ├── booking_agent.py           # LangGraph 智能体及对话流程编排

│   └── save_langgraph_flow.py     # LangGraph 流程图导出工具

├── data/

│   └── db.py                      # SQLite 数据库操作封装，创建和保存数据表

├── services/

│   ├── booking_service.py         # 预约挂号业务逻辑实现

│   └── doctor_service.py          # 医生信息管理业务逻辑

├── ui/

│   └── chat_ui.py                 # Streamlit 前端UI组件

├── app.py                         # 项目主入口文件

├── requirements.txt               # Python 项目依赖

├── README.md                      # 项目说明文档

└── .env                           # 环境变量配置（存储DeepSeek API Key）
```

## 🚀 环境准备

### 1. 安装项目依赖

```
pip install -r requirements.txt
```

### 2. 配置环境变量

编辑项目根目录下的 `.env` 文件，填入 DeepSeek API 密钥：

```
DEEPSEEK_API=your_api_key_here
DEEPSEEK_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat
```

### 3. 启动应用

```
streamlit run app.py
```

## 🏗️ 系统架构设计

> 📌 这张图展示了从用户在浏览器点击，到数据落盘的整体数据流向。

> 📌 双实线交互：用户与系统之间的真实消息流转（Streamlit 和 LangGraph 之间通过 interrupt 和 Command(resume=...) 来回拉扯）。 

> 📌 虚线调用：LangGraph 节点内部对 DeepSeek 的异步/同步 API 调用，这是整个系统的“大脑”。 

> 📌 底层支撑：只有当流程走到 completed_node 时，才会穿透到 Service 层，真正去 SQLite 里执行 INSERT 操作生成订单号。前面的对话全都是在内存（State）中流转的。
     

```mermaid
graph LR
    subgraph 前端展示层
        UI["🏥 Streamlit Web UI界面 + 可点击按钮"]
    end

    subgraph 核心控制层
        PM["进程消息<br>process_message"]
        AG["LangGraph 状态机"]
        MEM["MemorySaver"]
    end

    subgraph 决策与阻断层
        INT["interrupt()并等待UI输入"]
        RT["llm_router()路由与跑题拦截"]
        EXT["call_llm()信息提取(科室/时间)"]
    end

    subgraph 外部大模型
        DS["🧠 DeepSeek APIdeepseek-chat)"]
    end

    subgraph 数据与业务层
        SVC["Services<br>doctor_service / booking_service"]
        DB[(" SQLite 数据库doctors / customers / bookings ")]
    end