baodan/README.md

保险智能客服系统

基于 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

启动步骤

# 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。

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

BaoDan 升级流程

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

许可证

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