2026-07-02 23:13:23 +08:00

6.3 KiB

Raw Blame History

保险智能客服系统 — 开发指南

文档版本：V1.0 更新日期：2026-06-25 项目状态：完成 64%，产品推荐功能待实现

一、文档索引

文档	说明	链接
后续开发计划	完整的开发计划和时间表	后续开发计划.md
前端开发文档	前端开发规范和待开发功能	前端开发文档.md
后端开发文档	后端开发规范和待开发功能	后端开发文档.md
需求文档	完整的需求规格说明	保险智能客服系统_需求文档.md
API 接口文档	所有 API 接口定义	保险智能客服系统_API接口文档.md
编码规范	编码标准和规范	保险智能客服系统_编码规范.md
测试用例	功能测试用例	保险智能客服系统_测试用例.md

二、当前状态

2.1 已完成功能（64%）

✅ 认证系统（企微 OAuth + 账密登录）
✅ 对话功能（iframe 嵌入 BaoDan）
✅ 用户管理（CRUD + 角色权限）
✅ 知识库管理（文档上传/列表/删除）
✅ 数据统计（概览/趋势/知识库健康度）
✅ 系统管理（模板/通知/分组/Prompt/日志）
✅ 导出功能（PDF/Word）

2.2 未完成功能（36%）

❌ 产品推荐（Workflow 配置 + API 联调）
❌ 批量导入用户
❌ 数据权限过滤
❌ 文档编号自动生成
❌ 功能测试

三、快速开始

3.1 环境要求

Docker Desktop
Node.js 18+ (前端开发)
Python 3.12 (后端开发)

3.2 启动服务

# 1. 进入项目目录
cd D:\work\code\python\coding\baodanagent

# 2. 启动后端服务
docker compose -f docker-compose.dify.yml up -d

# 3. 启动前端服务（开发模式）
cd frontend
pnpm install
pnpm dev

# 4. 访问系统
# 前端：http://localhost:9080
# 后端：http://localhost:5001
# Dify：http://localhost:3000

3.3 默认账户

账户	密码	角色
admin	admin123456	超级管理员

四、开发流程

4.1 后端开发

修改代码：编辑 api/insurance/ 下的文件

重新构建：

docker compose -f docker-compose.dify.yml build baodan-api
docker compose -f docker-compose.dify.yml up -d baodan-api

测试 API：使用 curl 或 Postman 测试

4.2 前端开发

修改代码：编辑 frontend/src/ 下的文件
开发模式：
```
cd frontend
pnpm dev
```

构建部署：

pnpm build
docker compose -f docker-compose.frontend.yml build
docker compose -f docker-compose.frontend.yml up -d

4.3 数据库变更

编写 SQL：在 deploy/sql/ 下创建迁移文件

执行迁移：

docker exec -i baodanagent-db-1 psql -U postgres -d baodan < deploy/sql/migration.sql

五、核心任务

5.1 产品推荐功能（优先级最高）

目标：实现客户信息 → 生成 3 套推荐方案

步骤：

配置 Workflow（0.5 天）
- 在 Dify 后台创建 Workflow 应用
- 配置 6 个节点
- 获取 API Key
实现后端 API（0.5 天）
- 完善 generate/status/export/share API
- 封装 Workflow 调用
前端联调（0.5 天）
- 适配后端返回格式
- 测试完整流程

详细内容：见后续开发计划.md Phase 2.5 和 Phase 3

5.2 批量导入用户（优先级中等）

目标：支持 Excel 批量导入用户

步骤：

后端 API（0.2 天）
- 实现 POST /admin/users/batch-import
- 解析 Excel 文件
前端页面（0.1 天）
- UsersPage 添加导入按钮
- 上传组件

详细内容：见后端开发文档.md 2.3 节

5.3 数据权限过滤（优先级中等）

目标：销售只看自己的数据，主管看本组数据

步骤：

实现过滤逻辑（0.3 天）
- 在查询接口中注入权限条件
- 使用 get_data_scope()
测试验证（0.2 天）
- 测试不同角色的数据范围

详细内容：见后端开发文档.md 2.4 节

六、常见问题

Q1: 如何配置 Workflow？

A: 在 Dify 后台（http://localhost:3000）创建 Workflow 应用，参考后续开发计划.md Phase 2.5 的节点设计。

Q2: 如何更新 Workflow API Key？

A: 修改 docker-compose.dify.yml 中的 BAODAN_WORKFLOW_API_KEY，然后重启服务：

docker compose -f docker-compose.dify.yml up -d baodan-api

Q3: 如何添加新的 API 接口？

A: 在对应的 routes.py 中添加路由，参考后端开发文档.md 的 API 接口清单。

Q4: 如何添加新的前端页面？

A: 在 frontend/src/pages/ 下创建页面组件，在 router/index.ts 中添加路由，参考前端开发文档.md 的组件开发规范。

Q5: 如何执行数据库迁移？

A: 在 deploy/sql/ 下创建迁移文件，执行：

docker exec -i baodanagent-db-1 psql -U postgres -d baodan < deploy/sql/migration.sql

七、技术栈

后端

技术	版本	用途
Python	3.12	编程语言
Flask	3.x	Web 框架
SQLAlchemy	2.x	ORM
PostgreSQL	15	数据库
Redis	7.x	缓存
JWT	-	认证
bcrypt	4.x	密码哈希

前端

技术	版本	用途
Vue	3.x	前端框架
TypeScript	5.x	类型系统
Vite	5.x	构建工具
Element Plus	2.x	UI 组件库
Axios	1.x	HTTP 客户端
Vue Router	4.x	路由管理

基础设施

技术	版本	用途
Docker	-	容器化
Docker Compose	-	服务编排
Nginx	-	反向代理
Dify/BaoDan	1.14.2	AI 平台

八、联系方式

如有问题，请联系项目负责人或查阅项目文档。

最后更新：2026-06-25 文档维护：开发团队

6.3 KiB Raw Blame History Unescape Escape