baodan/docs/baodanppt集成计划.md

# baodanppt 集成计划

> **目标**：在现有保险智能客服系统中集成 baodanppt（PPT 生成）功能
> **日期**：2026-07-23

---

## 一、现状分析

### 1.1 三个系统的技术栈

| 系统 | 技术栈 | 端口 | 入口 |
|------|--------|------|------|
| **Flask API** | Python Flask + SQLAlchemy | 5001 | `api/insurance/app.py` |
| **Vue 前端** | Vue 3 + TypeScript + Element Plus + Vite | 9080 | `frontend/src/App.vue` |
| **baodanppt** | Bun + TypeScript + 原生 HTML/JS | 3000 | `baodanppt/src/api/server.ts` |

### 1.2 baodanppt 前端特点

- **独立 SPA**：纯 HTML/JS，无框架依赖，运行在 `http://localhost:3000`
- **4 步流程**：上传 → 解析 → 生成 → 结果
- **API 调用**：所有接口以 `/api/` 开头，调用自己的 Bun 后端
- **静态文件**：前端代码在 `baodanppt/public/` 目录

### 1.3 现有前端结构

```
frontend/src/
├── App.vue                    # 布局 + 侧边栏导航
├── router/index.ts            # Vue Router 路由定义
├── pages/                     # 页面组件
├── components/                # 公共组件
├── composables/               # 组合式函数
└── utils/api.ts               # Axios 实例 (baseURL: /insurance)
```

侧边栏导航在 `App.vue` 中，分两个区域：
- **功能菜单**：智能问答（/chat）、产品推荐（已注释）
- **系统管理**：管理首页、用户管理、权限管理等（需 admin 权限）

---

## 二、集成方案

### 推荐方案：iframe 嵌入 + API 代理

**理由**：
1. baodanppt 前端是独立的原生 JS SPA，**不适合重写为 Vue 组件**（工作量巨大且无收益）
2. iframe 嵌入是**最小改动方案**：只需创建一个 Vue 包装页面 + 代理 API 请求
3. 两个系统的 UI 风格差异大（Element Plus vs 原生 Tailwind），iframe 天然隔离样式冲突

### 架构图

```
用户浏览器
    │
    ▼
┌─ Vue 前端 (port 9080) ─────────────────────────┐
│  App.vue 侧边栏                                  │
│    ├── /chat        → ChatPage.vue              │
│    ├── /ppt         → PptPage.vue (iframe)      │
│    └── /admin/*     → 管理页面                   │
│                                                   │
│  Vite 代理:                                      │
│    /insurance/*  → Flask API (5001)              │
│    /ppt-api/*    → baodanppt Bun (3000)          │
└───────────────────────────────────────────────────┘
```

---

## 三、详细实施步骤

### 步骤 1：启动 baodanppt 后端服务

baodanppt 的 Bun 后端需要作为常驻服务运行。

**文件**：`baodanppt/src/api/server.ts`（已有，不需修改）

**启动命令**：
```bash
cd baodanppt && bun run src/api/server.ts
# 监听 port 3000
```

**修改**：将 baodanppt 端口改为非冲突端口（如 3001），或通过环境变量控制：
```bash
PORT=3001 bun run src/api/server.ts
```

### 步骤 2：配置 Vite 代理

**文件**：`frontend/vite.config.ts`

新增一条代理规则，将 `/ppt-api/` 请求转发到 baodanppt 后端：

```typescript
// 在现有 proxy 配置中新增
'/ppt-api': {
  target: 'http://localhost:3001',
  changeOrigin: true,
  rewrite: (path) => path.replace(/^\/ppt-api/, ''),
}
```

这样前端访问 `/ppt-api/upload` 会被代理到 `http://localhost:3001/upload`。

### 步骤 3：创建 PptPage.vue 包装组件

**文件**：`frontend/src/pages/PptPage.vue`（新建）

```vue
<template>
  <div class="ppt-page">
    <iframe
      ref="iframeRef"
      :src="pptUrl"
      class="ppt-iframe"
      frameborder="0"
      allow="clipboard-write"
    />
  </div>
</template>

<script setup lang="ts">
import { ref, computed } from 'vue'

const iframeRef = ref<HTMLIFrameElement>()

// iframe 地址：指向 baodanppt 前端
// 开发环境：http://localhost:3001
// 生产环境：需要配置实际地址
const pptUrl = computed(() => {
  // 从环境变量或配置中读取 baodanppt 地址
  return import.meta.env.VITE_PPT_BASE_URL || 'http://localhost:3001'
})
</script>

<style scoped>
.ppt-page {
  width: 100%;
  height: calc(100vh - 60px);  /* 减去顶部 header 高度 */
  overflow: hidden;
}
.ppt-iframe {
  width: 100%;
  height: 100%;
  border: none;
}
</style>
```

### 步骤 4：添加路由

**文件**：`frontend/src/router/index.ts`

在路由数组中新增：

```typescript
{
  path: '/ppt',
  name: 'PptGenerator',
  component: () => import('@/pages/PptPage.vue'),
  meta: {
    requiresAuth: true,
    title: 'PPT生成',
  },
},
```

### 步骤 5：添加侧边栏导航项

**文件**：`frontend/src/App.vue`

在"功能菜单"区域（`智能问答` 下方）添加：

```vue
<!-- 桌面端侧边栏（约 line 122-192） -->
<el-menu-item index="/ppt">
  <el-icon><Document /></el-icon>
  <span>PPT生成</span>
</el-menu-item>

<!-- 移动端抽屉菜单（约 line 31-101） -->
<el-menu-item index="/ppt">
  <el-icon><Document /></el-icon>
  <span>PPT生成</span>
</el-menu-item>
```

### 步骤 6：配置环境变量

**文件**：`frontend/.env.development`（新建）

```bash
VITE_PPT_BASE_URL=http://localhost:3001
```

**文件**：`frontend/.env.production`

```bash
VITE_PPT_BASE_URL=/ppt  # 生产环境同源部署
```

---

## 四、生产环境部署方案

### 方案 A：同源部署（推荐）

在生产环境中，baodanppt 的静态文件由 Nginx 直接托管，API 请求反向代理到 Bun 后端：

```nginx
# Nginx 配置片段
location /ppt/ {
    alias /path/to/baodanppt/public/;
    try_files $uri $uri/ /ppt/index.html;
}

location /ppt-api/ {
    proxy_pass http://127.0.0.1:3001/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}
```

此时 `VITE_PPT_BASE_URL=/ppt`，iframe 加载 `/ppt/index.html`。

### 方案 B：独立端口

baodanppt 运行在独立端口（3001），前端直接指向 `http://domain:3001`。

**缺点**：跨域、端口暴露、用户体验不统一。

---

## 五、需要修改的文件清单

| 文件 | 操作 | 改动量 |
|------|------|--------|
| `frontend/vite.config.ts` | 新增 `/ppt-api` 代理规则 | ~5 行 |
| `frontend/src/pages/PptPage.vue` | **新建** iframe 包装页面 | ~30 行 |
| `frontend/src/router/index.ts` | 新增 `/ppt` 路由 | ~8 行 |
| `frontend/src/App.vue` | 侧边栏新增"PPT生成"菜单项（2 处） | ~4 行 |
| `frontend/.env.development` | **新建** 环境变量 | 1 行 |
| `baodanppt/src/api/server.ts` | 端口改为环境变量控制（已有 `PORT`） | 0 行（已支持） |
| **合计** | | **~48 行** |

---

## 六、风险与注意事项

### 6.1 iframe 通信

当前方案不需要 iframe 通信。如果未来需要从 Vue 主应用向 baodanppt 传递用户信息（如 JWT token），可通过：
- URL 参数：`?token=xxx`
- `postMessage` API

### 6.2 样式隔离

iframe 天然隔离样式，不会影响 Element Plus 主题。

### 6.3 认证统一

baodanppt 当前使用 `X-API-Key` 认证。如果需要与主系统 JWT 统一：
- **短期方案**：baodanppt 的 `APP_API_KEY` 设为空（开放模式）
- **长期方案**：在 baodanppt 的 Bun 后端添加 JWT 验证中间件

### 6.4 文件路径

baodanppt 的 `KNOWLEDGE_ROOT` 硬编码了 macOS 路径（`/Users/soldier/Desktop/公司介绍`）。部署到服务器时需要修改为环境变量或配置文件。

### 6.5 Python 依赖

baodanppt 需要 Python 3.11 + PyMuPDF + pdfplumber + python-pptx。部署时需要确保服务器安装了这些依赖。

---

## 七、验证标准

1. ✅ 访问 `http://localhost:9080/ppt` 能看到 baodanppt 的上传页面
2. ✅ 上传 PDF 文件能正常调用 `/ppt-api/upload`
3. ✅ AI 解析流程正常完成
4. ✅ PPT 生成并返回下载链接
5. ✅ 侧边栏"PPT生成"菜单项高亮正确
6. ✅ 移动端抽屉菜单中也有"PPT生成"入口
7. ✅ 页面刷新后保持在 PPT 生成页面

---

## 八、后续优化（可选）

| 优化项 | 说明 | 优先级 |
|--------|------|--------|
| JWT 统一认证 | 让 baodanppt 复用主系统的 JWT | 中 |
| 会话关联 | 将 PPT 生成会话与主系统用户绑定 | 中 |
| 风格统一 | 将 baodanppt 前端渐进式迁移到 Vue + Element Plus | 低 |
| 数据库集成 | 将生成记录存入主系统数据库 | 低 |
| Nginx 生产配置 | 配置反向代理和静态文件托管 | 高 |