taiyi/baodan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
bc4c339e0c
baodan/AGENTS.md

7.6 KiB
Raw Blame History

保险智能客服系统

项目概述

基于 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 用英文

运行方式

# 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/保险智能客服系统_需求文档.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 升级流程

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/ 下