166 lines
7.8 KiB
Markdown
166 lines
7.8 KiB
Markdown
# 保险智能客服系统
|
||
|
||
## 项目概述
|
||
|
||
基于 BaoDan 源码的保险行业智能客服系统。**直接在 BaoDan 源码上开发**，自研代码放在 `api/insurance/` 目录下，与 BaoDan 代码物理隔离，只改 BaoDan 的 `main.py` 注册路由。
|
||
|
||
## 架构
|
||
|
||
```
|
||
用户浏览器 / 企微 H5
|
||
│
|
||
▼
|
||
┌─ BaoDan 服务（你的代码 + BaoDan 代码，同一进程）────────┐
|
||
│ BaoDan WebApp（对话界面） │
|
||
│ BaoDan 管理后台（知识库/Prompt/模型/日志） │
|
||
│ 你的 Extensions： │
|
||
│ · api/insurance/wecom/ 企微机器人 + OAuth │
|
||
│ · api/insurance/recommend/ 产品推荐 │
|
||
│ · api/insurance/permissions/角色权限 │
|
||
│ └── api/insurance/stats/ 数据统计 │
|
||
└────────────────────────────────────────────────────────┘
|
||
│
|
||
└── 你的前端（Vue 3，独立项目）
|
||
```
|
||
|
||
## 核心原则
|
||
|
||
1. **在 BaoDan 源码上开发**，自研代码放 `api/insurance/`，与 BaoDan 代码隔离
|
||
2. **只改 BaoDan 的 `main.py`**（注册路由）和 `web/.env.local`（开启 iframe），其余 BaoDan 文件不动
|
||
3. **复用 BaoDan 基础设施**：认证、数据库、Redis、日志全部用 BaoDan 现有的，不重复造轮子
|
||
4. **BaoDan 升级安全**：你的代码在独立目录，升级时只合并 `main.py` 那几行改动
|
||
5. **前端独立**：Vue 3 项目，对话页面 iframe 嵌入 BaoDan WebApp
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
baodanagent/
|
||
├── api/
|
||
│ └── insurance/ # ★ 你的全部自研代码
|
||
│ ├── app.py # Flask 应用入口
|
||
│ ├── config.py # 公共配置
|
||
│ ├── routes.py # Blueprint 路由注册
|
||
│ ├── admin/ # 管理后台（用户/部门/模板/通知）
|
||
│ ├── auth/ # 认证（企微 OAuth + 账密登录）
|
||
│ ├── chat/ # 对话功能（iframe 嵌入 BaoDan）
|
||
│ ├── db/ # 数据库 + 自定义迁移（migrate_001~013）
|
||
│ ├── kb/ # 知识库管理
|
||
│ ├── middleware/ # 认证中间件
|
||
│ ├── models/ # SQLAlchemy 数据模型（12 个）
|
||
│ ├── recommend/ # 产品推荐（Workflow 调用）
|
||
│ ├── stats/ # 数据统计
|
||
│ ├── utils/ # 工具函数（审计/邮件/错误处理）
|
||
│ └── wecom/ # 企微机器人 + OAuth
|
||
│
|
||
├── frontend/ # 你的前端（独立 Vue 3 项目）
|
||
│ ├── src/
|
||
│ │ ├── pages/ # 页面视图（用户端 + 管理端）
|
||
│ │ ├── components/ # 公共组件
|
||
│ │ ├── composables/ # 组合式函数
|
||
│ │ └── utils/ # 工具函数（api.ts）
|
||
│ └── dist/ # 构建产物
|
||
│
|
||
├── deploy/ # 部署配置（SQL/init.sql, nginx.conf, logo）
|
||
├── scripts/ # 脚本目录（按用途分类）
|
||
│ ├── deploy/ # 部署脚本（deploy-baodanagent.sh 等）
|
||
│ ├── build/ # 构建脚本（build-and-push.sh, package.sh）
|
||
│ ├── tools/ # 工具脚本（check-env.sh, docker-cleanup.sh）
|
||
│ ├── setup/ # 初始化脚本（create_admin.py 等）
|
||
│ └── README.md # 脚本索引说明
|
||
├── tests/ # 测试文件
|
||
├── docs/ # 项目文档（19 篇）
|
||
├── patches/ # Dify 源码补丁
|
||
├── plugin_files/ # Dify 插件定义
|
||
│
|
||
├── docker-compose.dify.yml # Docker Compose（数据库 + Redis）
|
||
├── docker-compose.frontend.yml # Docker Compose（前端容器）
|
||
├── Dockerfile.dify-custom # API 镜像（添加 insurance 模块）
|
||
├── Dockerfile.web-custom # Web 镜像（替换品牌）
|
||
├── Dockerfile.frontend # 前端镜像（静态服务 + 反向代理）
|
||
├── serve.py # 前端静态服务 + API 反向代理
|
||
│
|
||
├── dify-main/ # Dify 开源基座（参考，不直接修改）
|
||
└── deploy-package/ # 预构建部署包（Docker 镜像 tarballs）
|
||
```
|
||
|
||
## 修改 BaoDan 源码清单
|
||
|
||
| 文件 | 改动 | 改动量 |
|
||
|------|------|:---:|
|
||
| `api/main.py` | 注册 insurance Blueprint | ~5 行 |
|
||
| `web/.env.local` | 开启 iframe 嵌入 | 1 行 |
|
||
| **合计** | **只改 2 个 BaoDan 文件** | **~6 行** |
|
||
|
||
## 开发规范
|
||
|
||
详见 `docs/保险智能客服系统_编码规范.md`，关键点：
|
||
|
||
- 自研代码全部放在 `api/insurance/` 下，不往 BaoDan 其他目录写代码
|
||
- 后端文件名/变量名：snake_case
|
||
- 前端组件名/变量名：camelCase / PascalCase
|
||
- 复用 BaoDan 的数据库连接、Redis、日志系统
|
||
- 统一响应格式：`{"code": 0, "message": "success", "data": {...}}`
|
||
- 注释用中文，commit message 用英文
|
||
|
||
## 运行方式
|
||
|
||
```bash
|
||
# 1. 启动 BaoDan（源码模式）
|
||
cd baodan-main
|
||
./dev/setup # 安装依赖
|
||
./dev/start-api # 后端（含你的 insurance 模块）
|
||
./dev/start-worker # Celery Worker
|
||
./dev/start-web # 前端
|
||
|
||
# 2. 启动你的 Vue 前端
|
||
cd frontend
|
||
pnpm install && pnpm dev
|
||
|
||
# 3. 验证
|
||
curl http://localhost:5001/api/health
|
||
curl http://localhost:5001/api/wecom/callback # 企微回调
|
||
```
|
||
|
||
## 开发文档
|
||
|
||
所有文档已整理到 `docs/` 目录，完整索引见 [docs/README.md](docs/README.md)：
|
||
|
||
- `docs/保险智能客服系统_需求文档.md` — 完整需求
|
||
- `docs/保险智能客服系统_API接口文档.md` — 45 个 API 接口
|
||
- `docs/保险智能客服系统_编码规范.md` — 编码标准
|
||
- `docs/保险智能客服系统_测试用例.md` — 测试用例
|
||
- `docs/前端开发计划.md` — 前端开发详细计划
|
||
- `docs/后续开发计划.md` — 项目状态 + 未完成功能
|
||
- `docs/开发任务清单.md` — 412 项可勾选任务
|
||
- `docs/API_curl示例.md` — 接口调试 curl 示例
|
||
- `docs/部署文档_完整版.md` — 完整部署文档
|
||
- `docs/保险智能客服系统_文档规范.md` — 文档编写标准
|
||
|
||
## BaoDan 对接要点
|
||
|
||
- 复用 BaoDan 的数据库连接（SQLAlchemy），自研表直接用 BaoDan 的 DB
|
||
- 复用 BaoDan 的认证系统，在上面叠加你的角色权限
|
||
- 调 BaoDan 的 RAG 引擎：**直接 import Python 函数**，不走 HTTP
|
||
- 调 BaoDan 的 Workflow：通过 Python API 调用，不走 HTTP
|
||
- 按险种筛选：创建多个 BaoDan 应用，你的路由代码按用户选择分发
|
||
|
||
## BaoDan 升级流程
|
||
|
||
```bash
|
||
cd baodan-main
|
||
git stash # 暂存你的 insurance/ 目录改动
|
||
git pull origin main # 拉取 BaoDan 新版本
|
||
git stash pop # 恢复你的改动
|
||
# 如果 main.py 有冲突 → 手动合并（只合并注册路由的 5 行）
|
||
# 如果 .env.local 有冲突 → 重新加那一行
|
||
# insurance/ 目录永远不会冲突（新增的目录）
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- `.env` 文件不要提交到 Git
|
||
- BaoDan 的 `NEXT_PUBLIC_ALLOW_EMBED` 必须开启才能 iframe 嵌入
|
||
- 企微回调必须在 5 秒内返回 `success`，异步处理消息
|
||
- BaoDan WebApp 和你的前端必须**同源部署**
|
||
- 自研表的数据库迁移用 Alembic，放在 `api/insurance/db/` 下
|