179 lines
7.6 KiB
Markdown
179 lines
7.6 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
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
baodan-main/
|
||
├── api/
|
||
│ ├── core/ # BaoDan 核心（不动）
|
||
│ ├── controllers/ # BaoDan API 路由（不动）
|
||
│ ├── models/ # BaoDan 数据模型（不动）
|
||
│ ├── services/ # BaoDan 业务逻辑（不动）
|
||
│ ├── extensions/ # BaoDan 扩展（不动）
|
||
│ │
|
||
│ ├── insurance/ # ★ 你的代码（新建目录）
|
||
│ │ ├── __init__.py
|
||
│ │ ├── wecom/ # 企微机器人 + OAuth
|
||
│ │ │ ├── wecom_bot.py # 消息回调处理
|
||
│ │ │ ├── wecom_oauth.py # OAuth 登录
|
||
│ │ │ └── routes.py # Blueprint 路由
|
||
│ │ ├── recommend/ # 产品推荐
|
||
│ │ │ ├── recommend_api.py # 推荐接口
|
||
│ │ │ └── workflow_helper.py# Workflow 调用封装
|
||
│ │ ├── permissions/ # 角色权限
|
||
│ │ │ ├── models.py # 角色/权限模型
|
||
│ │ │ ├── middleware.py # 权限校验
|
||
│ │ │ └── routes.py # 角色管理接口
|
||
│ │ ├── stats/ # 数据统计
|
||
│ │ │ └── stats_api.py # 统计接口
|
||
│ │ └── db/ # 自研数据表
|
||
│ │ ├── wecom_user.py # 企微用户映射
|
||
│ │ └── recommend_record.py# 推荐记录
|
||
│ │
|
||
│ └── main.py # ★ BaoDan 入口（只改这里：注册 insurance 路由）
|
||
│
|
||
├── web/
|
||
│ └── .env.local # ★ BaoDan 前端配置（只改这里：开启 iframe）
|
||
│
|
||
├── docker/ # Docker 部署配置
|
||
└── dev/ # 开发脚本
|
||
|
||
frontend/ # 你的前端（独立 Vue 3 项目）
|
||
├── src/
|
||
│ ├── pages/ # 登录/对话/推荐/管理页面
|
||
│ ├── components/ # 通用组件
|
||
│ ├── composables/ # 组合函数
|
||
│ └── utils/ # 工具函数
|
||
├── package.json
|
||
└── vite.config.ts
|
||
|
||
deploy/
|
||
├── sql/init.sql # 自研表建表脚本
|
||
└── nginx.conf # Nginx 反向代理
|
||
|
||
docs/ # 所有项目文档
|
||
├── README.md # 文档索引（入口）
|
||
├── 保险智能客服系统_需求文档.md
|
||
├── 保险智能客服系统_API接口文档.md
|
||
├── 保险智能客服系统_编码规范.md
|
||
├── 保险智能客服系统_测试用例.md
|
||
├── 保险智能客服系统_文档规范.md
|
||
├── 前端开发计划.md
|
||
├── 开发计划.md
|
||
├── 开发任务清单.md
|
||
├── API_curl示例.md
|
||
└── 部署指南.md
|
||
```
|
||
|
||
## 修改 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` — 8 阶段开发计划
|
||
- `docs/开发任务清单.md` — 185 项可勾选任务
|
||
- `docs/API_curl示例.md` — 接口调试 curl 示例
|
||
- `docs/部署指南.md` — BaoDan 源码集成指南
|
||
- `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/` 下
|