baodan/docs/开发指南.md

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

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

---

## 一、文档索引

| 文档 | 说明 | 链接 |
|------|------|------|
| 后续开发计划 | 完整的开发计划和时间表 | [后续开发计划.md](后续开发计划.md) |
| 前端开发文档 | 前端开发规范和待开发功能 | [前端开发文档.md](前端开发文档.md) |
| 后端开发文档 | 后端开发规范和待开发功能 | [后端开发文档.md](后端开发文档.md) |
| 需求文档 | 完整的需求规格说明 | [保险智能客服系统_需求文档.md](保险智能客服系统_需求文档.md) |
| API 接口文档 | 所有 API 接口定义 | [保险智能客服系统_API接口文档.md](保险智能客服系统_API接口文档.md) |
| 编码规范 | 编码标准和规范 | [保险智能客服系统_编码规范.md](保险智能客服系统_编码规范.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 启动服务

```bash
# 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 后端开发

1. **修改代码**：编辑 `api/insurance/` 下的文件
2. **重新构建**：
   ```bash
   docker compose -f docker-compose.dify.yml build baodan-api
   docker compose -f docker-compose.dify.yml up -d baodan-api
   ```
3. **测试 API**：使用 curl 或 Postman 测试

### 4.2 前端开发

1. **修改代码**：编辑 `frontend/src/` 下的文件
2. **开发模式**：
   ```bash
   cd frontend
   pnpm dev
   ```
3. **构建部署**：
   ```bash
   pnpm build
   docker compose -f docker-compose.frontend.yml build
   docker compose -f docker-compose.frontend.yml up -d
   ```

### 4.3 数据库变更

1. **编写 SQL**：在 `deploy/sql/` 下创建迁移文件
2. **执行迁移**：
   ```bash
   docker exec -i baodanagent-db-1 psql -U postgres -d baodan < deploy/sql/migration.sql
   ```

---

## 五、核心任务

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

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

**步骤**：

1. **配置 Workflow**（0.5 天）
   - 在 Dify 后台创建 Workflow 应用
   - 配置 6 个节点
   - 获取 API Key

2. **实现后端 API**（0.5 天）
   - 完善 generate/status/export/share API
   - 封装 Workflow 调用

3. **前端联调**（0.5 天）
   - 适配后端返回格式
   - 测试完整流程

**详细内容**：见 [后续开发计划.md](后续开发计划.md) Phase 2.5 和 Phase 3

---

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

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

**步骤**：

1. **后端 API**（0.2 天）
   - 实现 POST /admin/users/batch-import
   - 解析 Excel 文件

2. **前端页面**（0.1 天）
   - UsersPage 添加导入按钮
   - 上传组件

**详细内容**：见 [后端开发文档.md](后端开发文档.md) 2.3 节

---

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

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

**步骤**：

1. **实现过滤逻辑**（0.3 天）
   - 在查询接口中注入权限条件
   - 使用 get_data_scope()

2. **测试验证**（0.2 天）
   - 测试不同角色的数据范围

**详细内容**：见 [后端开发文档.md](后端开发文档.md) 2.4 节

---

## 六、常见问题

### Q1: 如何配置 Workflow？

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

### Q2: 如何更新 Workflow API Key？

A: 修改 `docker-compose.dify.yml` 中的 `BAODAN_WORKFLOW_API_KEY`，然后重启服务：
```bash
docker compose -f docker-compose.dify.yml up -d baodan-api
```

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

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

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

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

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

A: 在 `deploy/sql/` 下创建迁移文件，执行：
```bash
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
**文档维护**：开发团队