baodan/docs/开发计划.md

# 保险智能客服系统 — 完整开发计划

> **基于**：需求文档 V1.0 + API 文档 V1.1 + 前端开发计划 + BaoDan 源码分析
> **当前状态**：后端空壳（49 行注释）+ 前端骨架（743 行）+ SQL 建表（112 行）
> **预计工期**：10 个工作日（一人全栈）
> **核心原则**：BaoDan 已有的绝不重复造轮子

---

## 零、已确认不需要自研的功能（用 BaoDan 原生）

| 功能 | BaoDan 提供的 | 对应需求编号 |
|------|-----------|:---:|
| LLM 模型配置 CRUD | `ModelProviderCredentialApi` 后台可视化配置 | 6.1 / A6.1.1-A6.1.2 |
| Prompt 编辑/版本/测试 | App 配置页 + Annotation 系统 | 6.2 / A6.1.3-A6.1.4 |
| 对话日志查看/筛选 | BaoDan 后台 /logs 页面 | 4.1.1-4.1.2 |
| 负反馈管理 | `MessageFeedbackExportApi` + Annotation | 4.1.4 |
| 点赞/点踩 | BaoDan WebApp 内置 | 1.4.1 |
| 推荐追问 | `MessageSuggestedQuestionApi` | 1.2.4 / A2.2.2 |
| 来源引用标注 | BaoDan RAG 自动返回 sources | 1.2.3 |
| 会话标题自动命名 | BaoDan 自动命名 | 1.1.5 |
| 知识库测试入口（hit testing） | `HitTestingApi` | 3.4.1 |
| FAQ 手动条目 | BaoDan Annotation Reply = FAQ | 3.4.3 |
| 文档上传/列表/删除/重试 | BaoDan `/datasets` 后台 | 3.1.1-3.1.2 / 3.1.5 / 3.2.x |
| Markdown 渲染 | BaoDan WebApp 内置 | 1.2.1 |
| 多轮对话上下文 | BaoDan conversation 机制 | 1.1.3 |
| 流式输出 | BaoDan WebApp iframe | 1.1.2 |

**以上功能不需要写后端接口，不需要写前端页面。**

---

## 一、后端自研接口清单（25 个，对齐 API 文档 V1.1）

### 1.1 认证鉴权（4 个）

| # | 方法 | URL | 说明 |
|:---:|:---:|-----|------|
| 1 | POST | /api/auth/wework-login | 企微 OAuth 登录 → JWT |
| 2 | POST | /api/auth/password-login | 账密登录 → JWT |
| 3 | POST | /api/auth/refresh-token | 刷新 Token |
| 4 | POST | /api/auth/logout | 退出（Token 黑名单） |

### 1.2 智能问答（5 个）

| # | 方法 | URL | 说明 |
|:---:|:---:|-----|------|
| 5 | POST | /api/chat/message | 发送消息（SSE 流式，调 BaoDan Chat API） |
| 6 | GET | /api/chat/sessions | 会话列表（封装 BaoDan API） |
| 7 | POST | /api/chat/sessions | 创建会话 |
| 8 | DELETE | /api/chat/sessions/{id} | 删除会话 |
| 9 | GET | /api/chat/sessions/{id}/messages | 消息记录（含来源引用） |

### 1.3 反馈 + 检索（2 个）

| # | 方法 | URL | 说明 |
|:---:|:---:|-----|------|
| 10 | POST | /api/chat/messages/{id}/feedback | 提交反馈（封装 BaoDan API） |
| 11 | POST | /api/retrieval/search | 向量检索（封装 BaoDan API） |

### 1.4 产品推荐（4 个）

| # | 方法 | URL | 说明 |
|:---:|:---:|-----|------|
| 12 | POST | /api/recommend/generate | 生成方案（调 BaoDan Workflow） |
| 13 | GET | /api/recommend/generate/{task_id} | 查询任务状态 |
| 14 | POST | /api/recommend/{id}/export | 导出 PDF/PPT/Word |
| 15 | POST | /api/recommend/{id}/share | 生成分享链接 |

### 1.5 知识库增强（6 个）

| # | 方法 | URL | 说明 |
|:---:|:---:|-----|------|
| 16 | POST | /api/kb/documents/upload | 上传文档（附标签，调 BaoDan API） |
| 17 | GET | /api/kb/documents | 文档列表（带自定义标签） |
| 18 | GET | /api/kb/documents/{id}/status | 文档处理状态 |
| 19 | PATCH | /api/kb/documents/{id} | 更新元数据（编号/标签） |
| 20 | DELETE | /api/kb/documents/{id} | 删除文档 |
| 21-24 | * | /api/kb/datasources/* | 保司数据源 CRUD + 同步 + 日志（4 个） |

### 1.6 用户权限（3 个）

| # | 方法 | URL | 说明 |
|:---:|:---:|-----|------|
| 25 | CRUD | /api/admin/users | 用户管理（含停用吊销 Token） |
| 26 | POST | /api/admin/users/batch-import | 批量导入 |
| 27 | CRUD | /api/admin/roles | 角色管理 |

### 1.7 系统日志 + 统计（4 个）

| # | 方法 | URL | 说明 |
|:---:|:---:|-----|------|
| 28 | GET | /api/admin/logs/system | 系统操作日志 |
| 29 | GET | /api/stats/overview | 使用概览 |
| 30 | GET | /api/stats/trend | 趋势数据 |
| 31 | GET | /api/stats/kb-health | 知识库健康度 |

### 1.8 企微回调（4 个）

| # | 方法 | URL | 说明 |
|:---:|:---:|-----|------|
| 32 | GET | /api/wecom/callback | 企微 URL 验证 |
| 33 | POST | /api/wecom/callback | 企微消息接收 |
| 34 | GET | /api/wecom/oauth | OAuth 入口 |
| 35 | GET | /api/wecom/oauth/callback | OAuth 回调 |

---

## 二、前端自研页面清单

### 2.1 用户端（5 个页面 + 5 个组件）

| 页面 | 路径 | 说明 | 对应需求 |
|------|------|------|---------|
| LoginPage.vue | /login | 企微 OAuth + 账密登录 | 无（全新） |
| ChatPage.vue | /chat | iframe 嵌入 BaoDan WebApp | M1 |
| ChatFilters.vue | — | 险种/保司筛选器组件 | 1.3.1-1.3.3 |
| ChatCopyButton.vue | — | 复制回答按钮组件 | 1.2.5 |
| RecommendPage.vue | /recommend | 推荐方案表单 + 结果 | M2.1-M2.2 |
| RecommendForm.vue | — | 客户信息表单组件 | 2.1.1-2.1.6 |
| RecommendResult.vue | — | 方案展示组件 | 2.2-2.3 |
| RecommendHistory.vue | /recommend/history | 历史方案列表 | 2.5.1-2.5.4 |
| RecommendDetail.vue | /recommend/detail/:id | 方案详情 + 导出 | 2.3-2.4 |

### 2.2 管理端（6 个页面）

| 页面 | 路径 | 说明 | 对应需求 |
|------|------|------|---------|
| DashboardPage.vue | /admin | 管理后台首页（跳转入口） | — |
| UsersPage.vue | /admin/users | 用户 CRUD + 批量导入 | 5.1-5.2 |
| PermissionsPage.vue | /admin/roles | 角色权限配置 | 5.2 |
| StatsPage.vue | /admin/stats | 数据统计仪表盘 | M7 |
| KBManagePage.vue | /admin/kb | 文档管理 + 标签 + 编号 | 3.1.3-3.1.4 |
| DataSourcePage.vue | /admin/datasource | 保司数据源配置 | 3.3 |

> 注：知识库主界面、对话日志、Prompt 管理、模型配置 → 跳转 BaoDan 后台，不自研。

---

## 三、数据库表（3 张自研表，已建好）

| 表名 | 用途 | 当前状态 |
|------|------|:---:|
| wecom_user_mapping | 企微用户 ↔ BaoDan 用户映射 | 已建 |
| recommendation_records | 推荐方案记录 | 已建 |
| system_operation_logs | 系统操作审计日志 | 已建 |

可能需要追加的表：

| 表名 | 用途 | 何时建 |
|------|------|--------|
| document_metadata | 文档编号/标签/险种/保司 | Phase 7 KB 增强时 |
| datasource_configs | 保司 API 数据源配置 | Phase 7 KB 增强时 |
| datasource_sync_logs | 同步日志 | Phase 7 KB 增强时 |
| share_tokens | 方案分享链接 Token | Phase 3 产品推荐时 |
| token_blacklist | JWT 黑名单（或用 Redis） | Phase 1 认证时 |

---

## 四、分阶段开发计划

---

### Phase 0：项目脚手架（0.5 天）

**目标**：BaoDan + 自研代码能跑起来，路由能通。

#### 后端任务

**0.1 创建 insurance/ 模块骨架**

```
api/insurance/
├── __init__.py              # 空
├── config.py                # 配置常量（JWT Secret、企微配置等）
├── utils/
│   ├── __init__.py
│   ├── response.py          # 统一响应封装：success_response() / error_response()
│   ├── auth.py              # JWT 签发/校验/装饰器
│   └── db.py                # 复用 BaoDan 的 db：from extensions.ext_database import db
├── wecom/
│   ├── __init__.py
│   ├── routes.py            # Blueprint: wecom_bp
│   ├── wecom_bot.py         # 消息回调处理
│   ├── wecom_oauth.py       # OAuth 登录
│   └── wecom_api.py         # 企微 API 封装（发消息/获取 Token）
├── recommend/
│   ├── __init__.py
│   ├── routes.py            # Blueprint: recommend_bp
│   └── workflow_helper.py   # BaoDan Workflow 调用封装
├── permissions/
│   ├── __init__.py
│   ├── routes.py            # Blueprint: permissions_bp
│   └── middleware.py        # 权限校验中间件
├── stats/
│   ├── __init__.py
│   └── routes.py            # Blueprint: stats_bp
└── db/
    ├── __init__.py
    ├── models.py            # SQLAlchemy 模型（3 张自研表）
    └── init.sql             # 建表脚本（已有）
```

每个 `routes.py` 先放一个 health check 占位接口。

**0.2 注册路由到 BaoDan**

修改 `baodan-main/api/app_factory.py`（或 `main.py`），在 app 创建后加：

```python
try:
    from insurance.utils.response import InsuranceResponse
    from insurance.wecom.routes import wecom_bp
    from insurance.recommend.routes import recommend_bp
    from insurance.permissions.routes import permissions_bp
    from insurance.stats.routes import stats_bp
    app.register_blueprint(wecom_bp, url_prefix='/api/wecom')
    app.register_blueprint(recommend_bp, url_prefix='/api/recommend')
    app.register_blueprint(permissions_bp, url_prefix='/api/admin')
    app.register_blueprint(stats_bp, url_prefix='/api/stats')
except ImportError:
    pass
```

**0.3 修改 BaoDan 前端 iframe 配置**

`web/.env.local` 添加：
```
NEXT_PUBLIC_ALLOW_EMBED=true
```

#### 前端任务

**0.4 确认前端项目能启动**

已有 `package.json`、`router`、`App.vue`。安装依赖后 `pnpm dev` 验证。

**0.5 统一响应拦截器**

确保 `src/utils/api.ts` 的 axios 拦截器处理 `code !== 0` 的情况。

#### 验证标准

```bash
# 后端
curl http://localhost:5001/api/health              # 返回 {"status":"ok"}
curl http://localhost:5001/api/auth/password-login  # 返回参数错误（不是 404）

# 前端
pnpm dev → 浏览器打开 localhost:3000 → 显示登录页
```

---

### Phase 1：认证系统（1 天）

**目标**：能登录、能鉴权、Token 能刷新。

#### 后端（0.5 天）

**1.1 config.py — 配置项**

```python
JWT_SECRET = os.getenv('JWT_SECRET', 'your-secret-key')
JWT_EXPIRE_HOURS = 2
REDIS_TOKEN_PREFIX = 'token:blacklist:'
WECOM_CORP_ID = os.getenv('WECOM_CORP_ID', '')
WECOM_AGENT_SECRET = os.getenv('WECOM_AGENT_SECRET', '')
WECOM_TOKEN = os.getenv('WECOM_TOKEN', '')
WECOM_AES_KEY = os.getenv('WECOM_AES_KEY', '')
```

**1.2 utils/auth.py — JWT 工具**

- `generate_token(user_id, username, role, department)` → 签发 JWT
- `decode_token(token)` → 解码 + 校验有效期
- `login_required` 装饰器 → 从 Header 提取 JWT → 解码 → 注入 current_user
- `admin_required` 装饰器 → 额外校验 role in [super_admin, admin]

**1.3 utils/response.py — 统一响应**

```python
def success(data=None, message="success"):
    return {"code": 0, "message": message, "data": data}

def error(code, message):
    return {"code": code, "message": message, "data": None}
```

**1.4 POST /api/auth/password-login**

```
输入：{ username, password }
处理：
  1. 参数校验（3-64字符，8-128字符）
  2. 查 wecom_user_mapping 表找用户
  3. bcrypt 校验密码（需在用户表加 password_hash 字段）
  4. 签发 JWT
  5. 记录 system_operation_logs（action=login）
输出：{ token, expires_in, user }
```

> 注意：wecom_user_mapping 表需要加 `password_hash` 字段（ALTER TABLE）。

**1.5 POST /api/auth/refresh-token**

```
处理：
  1. 校验旧 Token 有效性（未过期、未在黑名单）
  2. 签发新 Token
  3. 旧 Token 加入 Redis 黑名单（EX 7200）
输出：{ token, expires_in }
```

**1.6 POST /api/auth/logout**

```
处理：
  1. 当前 Token 加入 Redis 黑名单
  2. 记录操作日志
输出：{ code: 0 }
```

**1.7 POST /api/auth/wework-login**

```
输入：{ code, state }
处理：
  1. 用 code 调企微 gettoken API → 拿 access_token
  2. 用 access_token + code 调企微 auth/get_user_info → 拿 userid/name/department
  3. 查/建 wecom_user_mapping 记录
  4. 签发 JWT
输出：{ token, expires_in, user }
```

#### 前端（0.5 天）

**1.8 LoginPage.vue**

- 企微登录按钮 → `window.location.href = '/api/wecom/oauth'`
- 账密登录表单 → POST /api/auth/password-login → 存 token → 跳 /chat
- 表单校验：用户名必填，密码必填

**1.9 路由守卫**

- `router.beforeEach` 检查 `localStorage.token`
- 无 token → 跳 /login

**1.10 Token 自动刷新**

- api.ts 拦截器：响应 401 → 尝试 refresh-token → 成功则重试原请求 → 失败跳登录页

#### 验证标准

```bash
# 后端
curl -X POST http://localhost:5001/api/auth/password-login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"test1234"}'
# → 返回 JWT token

curl -H "Authorization: Bearer <token>" http://localhost:5001/api/auth/refresh-token
# → 返回新 token

curl -H "Authorization: Bearer <old_token>" http://localhost:5001/api/auth/refresh-token
# → 旧 token 已失效
```

---

### Phase 2：对话页面（1 天）

**目标**：用户能在 iframe 中跟 BaoDan 对话，筛选器可用。

#### 后端（0.5 天）

**2.1 POST /api/chat/message（SSE 流式）**

这是核心接口，封装 BaoDan Chat API：

```
输入：{ session_id, message, filters }
处理：
  1. JWT 鉴权
  2. 参数校验
  3. 根据 filters.险种 选择对应的 BaoDan App（不同险种不同知识库）
     - 无险种 → 全库 App
     - 重疾险 → 重疾险专用 App
     - 以此类推
  4. 调 BaoDan Chat API（blocking 模式）：
     POST http://localhost:5001/v1/chat-messages
     Headers: Authorization: Bearer app-xxxxxxxx
     Body: { query, user, conversation_id, response_mode: "blocking" }
  5. 解析 BaoDan 响应 → 提取 answer + retriever_resources
  6. 返回 SSE 流式数据
输出（SSE）：
  data: {"type":"source","data":{...}}
  data: {"type":"delta","data":"根据"}
  data: {"type":"done","data":{"message_id":"...","conversation_id":"..."}}
```

> 关键点：BaoDan 本身已有 SSE，我们可以直接用 blocking 模式拿到完整回答后转 SSE，或用 streaming 模式透传。先做 blocking 模式（简单），后续优化为 streaming。

**2.2 GET /api/chat/sessions**

```
处理：
  1. 调 BaoDan API: GET /v1/conversations?user={user_id}&page=1&limit=20
  2. 转换格式为 API 文档定义的结构
输出：{ total, items: [{ id, title, created_at, updated_at, message_count }] }
```

**2.3 POST /api/chat/sessions**

```
处理：调 BaoDan API 创建空会话（或前端直接新建）
```

**2.4 DELETE /api/chat/sessions/{id}**

```
处理：调 BaoDan API 删除会话
```

**2.5 GET /api/chat/sessions/{id}/messages**

```
处理：调 BaoDan API 获取消息列表 → 转换格式
```

#### 前端（0.5 天）

**2.6 ChatPage.vue**

```
结构：
  ┌─────────────────────────────┐
  │ ChatFilters（筛选器）          │
  ├─────────────────────────────┤
  │                             │
  │ iframe（BaoDan WebApp）         │
  │ src="/baodan/chat/{app_id}"   │
  │                             │
  ├─────────────────────────────┤
  │ ChatCopyButton + Suggestions │
  └─────────────────────────────┘
```

- ChatEmbed 组件：iframe 加载 BaoDan WebApp
- ChatFilters：险种下拉（7 种）+ 保司下拉（动态加载）
- 选择险种后切换 iframe src 到对应 BaoDan App

**2.7 App.vue 侧边栏**

```
左侧导航：
  智能问答 → /chat
  产品推荐 → /recommend
  历史方案 → /recommend/history
  ────────（管理员以下才显示）
  管理后台 → /admin
  ────────
```

- 根据用户 role 控制显示哪些菜单
- 顶部栏：页面标题 + 用户名 + 退出

#### 验证标准

```bash
# 浏览器
1. 登录 → 自动跳 /chat
2. iframe 加载出 BaoDan 对话界面
3. 筛选器下拉选择"重疾险"
4. 在 iframe 中提问 → BaoDan 回答
5. 侧边栏点击"产品推荐" → 跳转正常
```

---

### Phase 3：产品推荐（2 天）— 最大自研模块

**目标**：填写客户信息 → 生成方案 → 查看结果 → 导出。

#### 后端（1 天）

**3.1 数据模型扩展 — recommendation_records**

确认表结构满足需求，补充 `share_token` 和 `share_expire_at` 字段。

**3.2 POST /api/recommend/generate**

```
输入：{ customer, insurance_types, coverage_amount, coverage_period, existing_policies }
处理：
  1. JWT 鉴权
  2. 参数校验（年龄 1-150、性别 male/female、险种至少 1 项等，见需求文档 13.3 节）
  3. INSERT recommendation_records（status=pending）
  4. 异步调 BaoDan Workflow API：
     POST http://localhost:5001/v1/workflows/run
     Headers: Authorization: Bearer app-yyyyyyyyyyyy
     Body: { inputs: { age, gender, insurance_types, ... }, response_mode: "blocking", user }
  5. 解析 Workflow 输出 → JSON 格式化为 3 套方案（基础/均衡/全面）
  6. UPDATE recommendation_records（status=done, generated_plan=...）
  7. 记录操作日志
输出：{ task_id, status }
```

> 关键：Workflow 返回的是 Markdown 格式的方案文本，需要在 workflow_helper.py 中解析为结构化 JSON。

**3.3 workflow_helper.py — BaoDan Workflow 调用封装**

```python
def call_recommendation_workflow(customer_info, insurance_types, coverage_amount, coverage_period):
    """
    调 BaoDan Workflow API 生成推荐方案
    返回: { plans: [{ name, total_premium, items: [...], summary }] }
    """
    # 1. 构造 inputs
    # 2. POST /v1/workflows/run
    # 3. 解析 Markdown 输出 → 结构化 JSON
    # 4. 失败处理（超时 120s、Workflow 错误）
```

**3.4 GET /api/recommend/generate/{task_id}**

```
处理：查 recommendation_records 表，返回 status + proposal
```

**3.5 POST /api/recommend/{id}/export**

```
输入：{ format: "pdf" | "pptx" | "docx" }
处理：
  1. 查推荐记录
  2. 根据 format 调对应生成器：
     - docx: python-docx（先做，最简单）
     - pdf: reportlab 或 weasyprint
     - pptx: python-pptx
  3. 生成文件 → 保存到 /tmp/exports/ 或 OSS
  4. 返回下载链接（带临时 token，30 分钟有效）
输出：{ download_url, expire_at }
```

**3.6 POST /api/recommend/{id}/share**

```
处理：
  1. 生成随机 token
  2. 存 share_tokens 表（含过期时间）
输出：{ share_url, expire_at }
```

#### 前端（1 天）

**3.7 RecommendForm.vue — 表单组件**

```vue
结构：
  基础信息：姓名 / 年龄 / 性别（radio）/ 健康状况（select）/ 职业
  收入预算：年收入（万）/ 月预算（元）
  关注险种：checkbox group（寿险/重疾险/医疗险/意外险/年金险/储蓄险）
  保障需求：保额（slider + input）/ 保障期限（select）
  已有保单：可选折叠区域，动态添加
  [生成方案] 按钮

验证规则（见需求文档 13.3 节 + 14 节）：
  - 年龄：必填，整数 1-150
  - 性别：必选
  - 职业：必填，1-64 字符
  - 月预算：必填，>0
  - 险种：至少选 1 项
  - 保额：>=1 万
  - 保障期限：必选

草稿保存：
  - useDraft composable → 自动存 localStorage
  - 提交成功后清除草稿
```

**3.8 RecommendPage.vue — 主页面**

```
结构：
  RecommendForm（表单）
  ↓ 提交后
  loading 状态（轮询中...）
  ↓ 完成后
  RecommendResult（结果展示）
```

轮询逻辑：
```javascript
// 提交表单 → 拿到 task_id
// setInterval(2s) 轮询 GET /api/recommend/generate/{task_id}
// status=processing → 继续
// status=done → 展示方案
// status=failed → 显示错误
// 超过 60 次轮询 → 超时提示
```

**3.9 RecommendResult.vue — 结果展示**

```
结构：
  三套方案（Collapse 折叠面板）：
    基础方案 | 均衡方案 | 全面方案
    每套方案内：
      产品表格（产品名/保额/年保费/推荐理由）
      总保费
      方案总结
  操作栏：[浏览器打印] [重新生成] [导出 PDF] [分享]
  免责声明
```

**3.10 RecommendHistory.vue — 历史方案列表**

```
功能：
  分页表格：方案名称 / 客户姓名 / 险种 / 状态 / 创建时间 / 操作
  筛选：客户姓名 / 险种 / 时间范围
  操作：查看详情 / 导出 / 删除
```

**3.11 RecommendDetail.vue — 方案详情**

```
功能：
  展示完整方案内容
  导出按钮（PDF / Word / PPT）
  分享按钮 → 生成链接 → 复制
```

#### 验证标准

```bash
# 端到端
1. /recommend → 填写客户信息 → 点击"生成方案"
2. 页面显示 loading → 轮询中...
3. ~15 秒后显示 3 套方案
4. 点击"导出 PDF" → 浏览器下载 PDF
5. /recommend/history → 看到刚才生成的方案
```

---

### Phase 4：企微集成（1.5 天）

**目标**：企微私聊/群聊能问 BaoDan 问题。

#### 后端

**4.1 wecom_api.py — 企微 API 封装**

```python
class WeComAPI:
    def get_access_token(self):
        """获取企微 access_token，缓存到 Redis（提前 5 分钟刷新）"""

    def send_text_message(self, user_id, content):
        """单聊发消息"""

    def send_group_message(self, chat_id, content):
        """群聊发消息"""

    def send_long_message(self, user_id, content):
        """长消息自动分段发送（>2048字节时分段，间隔500ms）"""
```

**4.2 wecom_bot.py — 消息回调处理**

```
GET /api/wecom/callback（URL 验证）
  1. SHA1(sort([Token, timestamp, nonce, echostr]))
  2. 与 msg_signature 比对
  3. 验证通过 → 返回解密后的 echostr

POST /api/wecom/callback（消息接收）
  1. 立即返回 "success"（5 秒内）
  2. 异步处理：
     a. 验证签名 + 解密 XML
     b. 判断 MsgType：
        - text → 继续处理
        - image/voice/video/file → 回复"暂不支持该消息类型"
        - event → 忽略
     c. 群聊消息 → 去掉"@机器人"前缀
     d. 查 wecom_user_mapping 获取用户
     e. 调 BaoDan Chat API（blocking）
     f. 通过企微 API 回复
```

> 关键：5 秒内必须返回 success。所以用 Flask 的异步机制（threading/queue），先返回再处理。

**4.3 wecom_oauth.py — OAuth 登录**

```
GET /api/wecom/oauth
  构造企微授权 URL → 302 重定向

GET /api/wecom/oauth/callback
  1. 用 code 调企微 API → 获取用户信息
  2. 查/建 wecom_user_mapping
  3. 签发 JWT
  4. 302 重定向到前端（URL 带 token）
```

**4.4 XML 加解密**

```python
# 企微消息加解密（AES-CBC）
# 参考企微官方 SDK 或自行实现
# 核心：decrypt_msg(encrypted_msg) → 明文 XML
```

#### 验证标准

```bash
# 模拟企微回调
curl "http://localhost:5001/api/wecom/callback?msg_signature=xxx&timestamp=xxx&nonce=xxx&echostr=encrypted_echostr"
# → 返回解密后的 echostr

# 模拟消息推送（用企微调试工具）
# → 机器人回复 AI 回答
```

---

### Phase 5：用户权限管理（1 天）

**目标**：管理员能管用户、配角色、数据隔离。

#### 后端

**5.1 用户 CRUD — /api/admin/users**

```
GET    /api/admin/users         → 分页列表（支持 role/department/keyword 筛选）
POST   /api/admin/users         → 新增用户（插入 wecom_user_mapping）
PUT    /api/admin/users/{id}    → 编辑（改角色/部门/状态）
DELETE /api/admin/users/{id}    → 停用（status=disabled + 吊销所有 Token）
```

**5.2 批量导入 — /api/admin/users/batch-import**

```
POST（multipart/form-data） → 解析 Excel → 批量插入
```

**5.3 角色管理 — /api/admin/roles**

```
GET    /api/admin/roles         → 5 个内置角色 + 自定义角色
POST   /api/admin/roles         → 新建角色（name + permissions 数组）
PUT    /api/admin/roles/{id}    → 更新权限
DELETE /api/admin/roles/{id}    → 删除（内置角色不可删）
```

**5.4 权限校验中间件 — middleware.py**

```python
# 在需要权限的路由上加装饰器：
@require_permission('kb_manage')
def upload_document():
    ...

# 权限列表：
# chat, proposal, kb_manage, kb_view, log_view, user_manage,
# config_manage, team_stats, system_log
```

**5.5 数据权限（5.2.3）**

这是 BaoDan 不具备的核心能力：
```
- 销售(sales) → 只能看自己的数据（推荐记录、对话）
- 主管(manager) → 看本组数据（同 department）
- 管理员(admin) / 超级管理员(super_admin) → 看全部
```

实现方式：在查询接口中自动注入 `WHERE user_id = ?` 或 `WHERE department = ?` 条件。

#### 前端

**5.6 UsersPage.vue**

```
功能：
  用户表格（分页）：用户名/企微ID/角色/部门/状态/操作
  新增用户弹窗
  编辑用户弹窗
  停用确认弹窗
  批量导入按钮（上传 Excel）
```

**5.7 PermissionsPage.vue**

```
功能：
  左侧：角色列表（可选中）
  右侧：权限配置面板（checkbox 分组）
    对话：智能问答 / 产品推荐
    管理：知识库管理 / 对话日志 / 用户管理 / 数据统计 / 系统日志
  [保存权限] 按钮
```

#### 验证标准

```bash
# 管理员操作
1. 登录 admin → /admin/users → 看到用户列表
2. 新增一个 sales 角色用户
3. 用新用户登录 → 只能看到 /chat、/recommend
4. 访问 /admin/users → 返回 403
```

---

### Phase 6：数据统计（1 天）

**目标**：管理员能看到系统使用数据。

#### 后端

**6.1 GET /api/stats/overview**

```
处理：
  今日问答数 → 查 BaoDan 对话记录（或自建统计表）
  活跃用户数 → 查 wecom_user_mapping 中 last_active_at 在今天内的
  知识库命中率 → 查 BaoDan 日志中有 retriever_resources 的比例
  文档总数 → 查 BaoDan datasets/documents 数量
输出：{ today_chats, active_users, kb_hit_rate, total_documents }
```

**6.2 GET /api/stats/trend**

```
输入：?metric=chat_count&start_date=2026-05-01&end_date=2026-05-31&granularity=day
处理：按天聚合数据
输出：{ metric, granularity, data: [{ date, value }] }
```

**6.3 GET /api/stats/kb-health**

```
输入：?days=30
处理：
  热门问题 TOP20 → 按 query 文本分组计数
  未命中问题 → 检索结果 score < 0.5 的问题
  文档覆盖率 → 各险种文档数量统计
输出：{ hot_questions, missed_questions, coverage }
```

> 注：热门问题和未命中问题需要在问答接口中记录日志到自研表（或从 BaoDan 日志中聚合）。

#### 前端

**6.4 StatsPage.vue**

```
结构：
  顶栏：4 个指标卡片（今日问答/活跃用户/命中率/文档数）
  中间：趋势折线图（ECharts，7天/30天切换）
  底部左：险种分布饼图
  底部右：热门问题 TOP20 表格
```

#### 验证标准

```bash
浏览器打开 /admin/stats → 看到指标卡片 + 图表
（数据量少时可能为空，但页面不报错）
```

---

### Phase 7：知识库增强（1 天）

**目标**：BaoDan 后台不支持的 KB 功能（编号/标签/数据源）。

#### 后端

**7.1 数据库追加表**

```sql
-- 文档元数据（编号、标签、险种、保司）
CREATE TABLE document_metadata (
    id SERIAL PRIMARY KEY,
    baodan_document_id VARCHAR(64) NOT NULL,
    dataset_id VARCHAR(64) NOT NULL,
    doc_number VARCHAR(32),        -- 编号，如 CJ-XX-001
    insurance_type VARCHAR(32),     -- 险种
    company VARCHAR(64),            -- 保司
    tags JSONB DEFAULT '[]',        -- 自定义标签
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- 保司 API 数据源配置
CREATE TABLE datasource_configs (
    id SERIAL PRIMARY KEY,
    name VARCHAR(128) NOT NULL,
    api_url VARCHAR(512) NOT NULL,
    api_key_encrypted TEXT,         -- AES 加密存储
    sync_frequency VARCHAR(32),     -- CRON 表达式
   险种 VARCHAR(32),
    last_sync_at TIMESTAMP,
    last_sync_status VARCHAR(16),
    last_sync_count INTEGER,
    status VARCHAR(16) DEFAULT 'active',
    created_at TIMESTAMP DEFAULT NOW()
);

-- 同步日志
CREATE TABLE datasource_sync_logs (
    id SERIAL PRIMARY KEY,
    datasource_id INTEGER REFERENCES datasource_configs(id),
    status VARCHAR(16),             -- success/failed
    items_added INTEGER DEFAULT 0,
    items_updated INTEGER DEFAULT 0,
    items_deleted INTEGER DEFAULT 0,
    error_message TEXT,
    started_at TIMESTAMP DEFAULT NOW(),
    completed_at TIMESTAMP
);
```

**7.2 文档管理增强接口**

```
POST   /api/kb/documents/upload      → 上传文档（同时写 document_metadata）
GET    /api/kb/documents             → 文档列表（JOIN document_metadata 拿编号/标签）
PATCH  /api/kb/documents/{id}        → 更新编号/标签
GET    /api/kb/documents/{id}/status → 处理状态
DELETE /api/kb/documents/{id}        → 删除文档
POST   /api/kb/documents/{id}/retry  → 重试
```

**7.3 保司数据源接口**

```
GET    /api/kb/datasources            → 数据源列表
POST   /api/kb/datasources            → 新建数据源
POST   /api/kb/datasources/{id}/sync  → 手动同步（异步）
GET    /api/kb/datasources/{id}/logs  → 同步日志
```

**7.4 编号自动生成规则**

```python
def generate_doc_number(insurance_type, company):
    """
    规则：险种代码-保司代码-序号
    例：CJ-XX-001（重疾险-XX人寿-第1个文档）
    险种代码：CJ=重疾, RS=寿险, YL=医疗, YW=意外, CX=车险, NJ=年金, CX=储蓄
    """
```

#### 前端

**7.5 KBManagePage.vue**

```
功能：
  文档列表表格（分页）：编号/文件名/险种/保司/标签/状态/操作
  上传文档弹窗（多文件 + 选择险种 + 填写保司）
  编辑元数据弹窗（修改编号、标签）
  删除确认
```

**7.6 DataSourcePage.vue**

```
功能：
  数据源列表表格：名称/URL/同步频率/上次同步/状态/操作
  新建数据源弹窗
  [立即同步] 按钮 → 显示同步进度
  同步日志查看
```

#### 验证标准

```bash
1. /admin/kb → 上传一个 MD 文件 → 选择险种 → 看到文档在列表中
2. 点编辑 → 修改编号为 CJ-XX-001 → 保存成功
3. /admin/datasource → 新建一个数据源 → 点击"立即同步"
```

---

### Phase 8：导出 + 日志 + 收尾（0.5 天）

#### 导出功能

**8.1 PDF 导出**

```python
# 使用 reportlab 或 weasyprint
# 按模板渲染推荐方案 → 生成 PDF
# 需要客户提供 PDF 模板（或先用简单模板）
```

**8.2 Word 导出**

```python
# 使用 python-docx
# 最简单的导出方式，优先实现
```

**8.3 PPT 导出**

```python
# 使用 python-pptx
# 按模板生成 PPT（需要客户提供模板）
```

#### 系统日志

**8.4 system_operation_logs 记录**

在以下操作时自动写入：
- 登录/登出
- 文档上传/删除
- 角色权限变更
- 推荐方案生成

#### 通知告警（可选）

**8.5 企微 Webhook 通知**

```python
def send_alert(message):
    """通过企微机器人 Webhook 发送告警"""
    webhook_url = config.WECOM_WEBHOOK_URL
    requests.post(webhook_url, json={"msgtype": "text", "text": {"content": message}})
```

告警场景：
- 数据源同步失败
- Token 月消耗超预算

---

## 五、依赖安装清单

### 后端（Python）

```
PyJWT==2.*           # JWT 签发
bcrypt==4.*          # 密码哈希
python-docx==1.*     # Word 导出
reportlab==4.*       # PDF 导出（可选）
python-pptx==1.*     # PPT 导出（可选）
openpyxl==3.*        # Excel 批量导入
lxml==5.*            # XML 解析（企微消息）
cryptography==43.*   # AES 加解密（企微消息 + API Key）
celery==5.*          # 异步任务（企微消息处理、文档同步）
```

> 大部分依赖 BaoDan 已有（Flask、SQLAlchemy、Redis），不需要重复安装。

### 前端（Node）

```
vue@3
vue-router@4
element-plus
axios
marked              # Markdown 渲染
echarts             # 统计图表
```

---

## 六、风险与应对

| 风险 | 影响 | 应对 |
|------|------|------|
| BaoDan Workflow 输出格式不稳定 | 推荐方案解析失败 | 在 workflow_helper.py 中加容错解析 + fallback |
| 企微消息加解密实现复杂 | 回调不通 | 参考企微官方 Python SDK（wxwork-sdk） |
| 9GB 知识库上传慢 | 首次导入耗时长 | 分批上传 + 异步处理 + 进度反馈 |
| BaoDan 版本升级破坏接口 | 自研代码不可用 | 只改 main.py + app_factory.py，insurance/ 独立 |
| 一人开发工期紧 | 10 天可能不够 | Phase 7-8 可推后，Phase 0-5 是 MVP |

---

## 七、MVP 交付标准

Phase 0-5 完成后即可进入测试：

```
✅ 能登录（企微 + 账密）
✅ 能在 iframe 中跟 BaoDan 对话
✅ 能筛选险种
✅ 能填写客户信息生成推荐方案
✅ 能查看历史方案
✅ 企微私聊能问答
✅ 管理员能管用户和角色
```

Phase 6-8 为增强功能，可并行测试：

```
⏳ 数据统计仪表盘
⏳ 知识库编号/标签管理
⏳ 保司数据源同步
⏳ PDF/Word 导出
⏳ 系统操作日志
```