#	问题	修复	文件
1	前端构建失败（引号错误）	size="small type=" → size="small" type="	PosterHistoryPage.vue
2	migrate_014 ORM vs 缺失列	全部改为原始 SQL，不再引用 ORM 模型	migrate_014.py
3	cleanup 字段名错误	output_path → ppt_path	cleanup.py
4	文案生成 case 越权	添加 case.user_id != user_id 校验	poster/service.py
5	存储路径未接通持久化卷	全部改用 get_storage_root()（默认 /app/api/storage/insurance）	config.py, ppt/routes.py, poster/service.py, poster/tasks.py
高风险问题修复
#	问题	修复	文件
6	migrate_019 rollback 撤销成功字段	每个 ALTER 后立即 commit，失败只回滚当前语句	migrate_019.py
7	迁移锁 Windows 不兼容 + 句柄未持久化	全局变量保存锁句柄，支持 Windows msvcrt	api/insurance/db/__init__.py
8	PDF 校验异常时放行	异常返回 False（文件损坏）	security.py
9	健康检查始终返回成功	缺少关键资源时返回 503 + missing 列表	poster/routes.py
10	短密钥掩码泄露原值	≤4 字符返回 ****	ppt_admin_service.py
11	设置无键名白名单	添加 _ALLOWED_SETTING_KEYS 白名单	ppt_admin_service.py
12	容器重启任务永久 stuck	添加 recover_stale_tasks() 启动恢复函数	poster/tasks.py, ppt/parse_worker.py

2026-07-27 13:52:09 +08:00

7.8 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，独立项目）

核心原则

在 BaoDan 源码上开发，自研代码放 api/insurance/，与 BaoDan 代码隔离
只改 BaoDan 的 main.py（注册路由）和 web/.env.local（开启 iframe），其余 BaoDan 文件不动
复用 BaoDan 基础设施：认证、数据库、Redis、日志全部用 BaoDan 现有的，不重复造轮子
BaoDan 升级安全：你的代码在独立目录，升级时只合并 main.py 那几行改动
前端独立：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 用英文

运行方式

# 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 — 项目状态 + 未完成功能
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 升级流程

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

7.8 KiB Raw Blame History Unescape Escape