# 保险智能客服系统

基于 BaoDan 源码的保险行业智能客服系统。**直接在 BaoDan 源码上开发**，自研代码放在 `api/insurance/` 目录下，与 BaoDan 代码物理隔离。

## 系统架构

```
用户浏览器 / 企微 H5
    │
    ▼
┌─ BaoDan 服务（BaoDan + 你的代码，同一进程）─────────────┐
│  BaoDan WebApp（对话界面，iframe 嵌入）                  │
│  BaoDan 管理后台（知识库/Prompt/模型/日志）               │
│  你的 Extensions（api/insurance/）：                   │
│    · 企微机器人 + OAuth                                │
│    · 产品推荐                                         │
│    · 角色权限                                         │
│    · 数据统计                                         │
└───────────────────────┬──────────────────────────────┘
                        │
        ┌───────────────▼───────────────┐
        │  你的前端（Vue 3，独立项目）     │
        │  对话页 / 推荐页 / 管理页       │
        └───────────────────────────────┘
```

## 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 基础平台 | BaoDan 1.14.2（源码） | Flask 后端 + Next.js 前端 |
| 自研后端 | Python + Flask Blueprint | 放在 `api/insurance/`，复用 BaoDan 基础设施 |
| 自研前端 | Vue 3 + TypeScript + Vite + Element Plus | 对话 iframe + 推荐页 + 管理页 |
| 数据库 | PostgreSQL 15 | 复用 BaoDan 的 DB，新增 3 张自研表 |
| 向量库 | BaoDan 内置 | 知识库检索 |
| 缓存 | Redis 6 | 复用 BaoDan 的 Redis |

## 项目结构

```
baodan-main/
├── api/
│   ├── insurance/              # ★ 你的代码（新建目录）
│   │   ├── wecom/              #   企微机器人 + OAuth
│   │   ├── recommend/          #   产品推荐
│   │   ├── permissions/        #   角色权限
│   │   ├── stats/              #   数据统计
│   │   └── db/                 #   自研数据表
│   ├── core/                   # BaoDan 核心（不动）
│   ├── controllers/            # BaoDan API（不动）
│   ├── models/                 # BaoDan 模型（不动）
│   └── main.py                 # ★ 只改这里：注册路由
│
├── web/
│   └── .env.local              # ★ 只改这里：开启 iframe
│
├── dev/                        # 开发脚本（BaoDan 自带）
└── docker/                     # Docker 部署（BaoDan 自带）

frontend/                       # 你的前端（Vue 3）
├── src/
├── package.json
└── 前端开发计划.md

deploy/
├── sql/init.sql                # 自研表建表脚本
└── nginx.conf                  # Nginx 反向代理
```

## 修改 BaoDan 文件清单

| 文件 | 改动 | 改动量 |
|------|------|:---:|
| `api/main.py` | 注册 insurance Blueprint | ~5 行 |
| `web/.env.local` | 开启 iframe 嵌入 | 1 行 |
| **合计** | **只改 2 个 BaoDan 文件** | **~6 行** |

## 快速开始

### 前置条件

- Python 3.12 + uv
- Node.js 22 + pnpm
- PostgreSQL 15 + Redis 6
- DeepSeek API Key

### 启动步骤

```bash
# 1. 克隆 BaoDan 源码
git clone https://github.com/langgenius/baodan.git
cd baodan

# 2. 安装依赖
./dev/setup

# 3. 配置环境变量
# 编辑 api/.env 和 web/.env.local（详见开发文档）

# 4. 启动服务（4 个终端）
./dev/start-api          # 终端1：后端（含你的 insurance 模块）
./dev/start-worker       # 终端2：Celery Worker
./dev/start-web          # 终端3：BaoDan 前端
./dev/start-beat         # 终端4：定时任务（可选）

# 5. 启动你的 Vue 前端
cd ../frontend && pnpm install && pnpm dev

# 6. 验证
curl http://localhost:5001/api/health
```

## BaoDan 功能 vs 自研功能

| 功能 | 来源 | 你做什么 |
|------|:---:|---------|
| 对话界面 | BaoDan WebApp | iframe 嵌入 |
| 知识库管理 | BaoDan 后台 | 不写代码 |
| Prompt 编辑 | BaoDan 后台 | 不写代码 |
| 模型配置 | BaoDan 后台 | 不写代码 |
| 对话日志 | BaoDan 后台 | 不写代码 |
| 产品推荐 | **自研** | `api/insurance/recommend/` |
| 企微机器人 | **自研** | `api/insurance/wecom/` |
| 企微 OAuth | **自研** | `api/insurance/wecom/` |
| 角色权限 | **自研** | `api/insurance/permissions/` |
| 数据统计 | **自研** | `api/insurance/stats/` |

## 开发文档

所有文档在 `docs/` 目录，完整索引见 [docs/README.md](docs/README.md)。

| 文档 | 说明 |
|------|------|
| [需求文档](docs/保险智能客服系统_需求文档.md) | 125 项功能 + 数据库设计 + 数据流转 |
| [API 接口文档](docs/保险智能客服系统_API接口文档.md) | 45 个接口完整设计 |
| [开发计划](docs/开发计划.md) | 8 阶段开发计划（排除 BaoDan 重复功能） |
| [开发任务清单](docs/开发任务清单.md) | 185 项可勾选任务 |
| [编码规范](docs/保险智能客服系统_编码规范.md) | 编码标准 + BaoDan 集成规范 |
| [测试用例](docs/保险智能客服系统_测试用例.md) | 功能/边界/异常测试 + 上线 Checklist |
| [前端开发计划](docs/前端开发计划.md) | Vue 3 前端完整组件代码 |
| [API curl 示例](docs/API_curl示例.md) | 接口调试 curl 示例 |
| [部署指南](docs/部署指南.md) | BaoDan 源码集成指南 |

## BaoDan 升级流程

```bash
cd baodan
git stash                    # 暂存你的改动
git pull origin main         # 拉取 BaoDan 新版本
git stash pop                # 恢复你的改动
# main.py 冲突 → 手动合并（只合并注册路由的 5 行）
# .env.local 冲突 → 重新加那一行
# api/insurance/ 目录永远不会冲突
```

## 许可证

BaoDan 部分：Apache 2.0
你的自研部分：MIT