# PRD_需求文档_问题排查助手性能与功能优化

## 基本信息

| 项目 | 内容 |
|------|------|
| 文档类型 | 需求文档 |
| 创建日期 | 2026-07-12 |
| 负责人 | 研发组 |
| 优先级 | 高 |
| 状态 | 规划中 |
| 关联文档 | [PRD_需求文档_问题知识库智能排查助手](./PRD_需求文档_问题知识库智能排查助手.md) |

---

## 一、背景与目标

### 1.1 当前问题

| 问题 | 说明 |
|------|------|
| **重复请求浪费** | 相同问题多次请求，每次都调用 API，费用高 |
| **无法选择模型** | 固定使用一个模型，无法平衡速度和质量 |
| **缺少健康检查** | 服务状态无法监控，运维不便 |
| **敏感信息泄露风险** | 输出可能包含 IP、密码等敏感信息 |

### 1.2 目标

1. **缓存机制**：相同问题返回缓存结果，减少 API 调用
2. **模型切换**：前端可选择模型，平衡速度和质量
3. **健康检查接口**：方便监控服务状态
4. **敏感信息过滤**：自动过滤输出中的敏感信息

---

## 二、功能需求

### 2.1 缓存机制

#### 功能描述
- 用户提交的问题在 24 小时内缓存结果
- 缓存命中时直接返回，不调用 API
- 缓存支持手动清除

#### 缓存策略

| 场景 | 策略 |
|------|------|
| 完全相同的问题 | 直接返回缓存 |
| 项目名称不同但问题相同 | 不使用缓存（上下文不同） |
| 缓存过期 | 重新调用 API |
| 用户刷新页面 | 可选择重新请求 |

#### 技术方案

```
用户请求 → 检查缓存（key: 问题hash）→ 命中？
    ├─ 是 → 返回缓存结果 + 标记"来自缓存"
    └─ 否 → 调用 API → 存入缓存 → 返回结果
```

#### 验收标准

- [x] 相同问题 24 小时内返回缓存结果
- [x] 缓存命中时响应时间 < 500ms
- [x] 前端显示"来自缓存"标识
- [x] 提供清除缓存的按钮

---

### 2.2 模型切换

#### 功能描述
- 前端提供模型选择下拉框
- 不同模型有不同的速度和质量特点
- 用户可根据需求选择

#### 模型选项

| 模型 | 速度 | 质量 | 适用场景 |
|------|------|------|----------|
| glm-4-flash | 快（5-10s） | 中 | 快速排查 |
| glm-5.1 | 中（20-50s） | 高 | 默认推荐 |
| glm-4-plus | 慢（30-60s） | 最高 | 复杂问题 |

#### 前端设计

```
┌─────────────────────────────────────────┐
│  模型选择：[ glm-5.1（推荐）    ▼ ]      │
│            ○ 快速模式（glm-4-flash）     │
│            ○ 标准模式（glm-5.1）         │
│            ○ 深度模式（glm-4-plus）      │
└─────────────────────────────────────────┘
```

#### 验收标准

- [x] 前端显示模型选择下拉框
- [x] 不同模型响应时间符合预期
- [x] 模型选择保存在 localStorage，下次访问记住

---

### 2.3 健康检查接口

#### 功能描述
- 提供 `/api/health` 接口，返回服务状态
- 可用于监控系统、负载均衡器健康检查

#### 接口设计

**请求**：
```
GET /api/health
```

**响应**：
```json
{
  "status": "ok",
  "timestamp": "2026-07-12T12:00:00",
  "version": "1.2.0",
  "knowledge_base": {
    "total_records": 357,
    "last_update": "2026-07-11 14:38:04"
  },
  "components": {
    "search_engine": "ok",
    "safety_filter": "ok"
  }
}
```

#### 验收标准

- [x] 接口返回 200 状态码
- [x] 返回服务状态和版本信息
- [x] 响应时间 < 100ms

---

### 2.4 敏感信息过滤

#### 功能描述
- 自动识别并过滤输出中的敏感信息
- 支持多种敏感信息类型

#### 过滤规则

| 类型 | 匹配规则 | 替换为 |
|------|----------|--------|
| IP 地址 | `\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}` | `***.***.***.***` |
| 密码 | `password[:=]\s*\S+` | `password: ***` |
| 数据库连接串 | `mysql://.*@` | `mysql://***@` |
| 手机号 | `1[3-9]\d{9}` | `1**********` |
| 邮箱 | `[\w.]+@[\w.]+` | `***@***.***` |

#### 验收标准

- [x] IP 地址被过滤
- [x] 密码被过滤
- [x] 数据库连接串被过滤
- [x] 过滤后的内容仍可读

---

## 三、非功能需求

| 需求 | 说明 |
|------|------|
| 缓存存储 | 使用文件缓存，无需额外数据库 |
| 缓存清理 | 缓存文件超过 100MB 时自动清理最旧的 |
| 兼容性 | 保留原有接口，新增参数可选 |

---

## 四、影响范围

### 4.1 涉及现有文件

| 文件 | 变更类型 | 说明 |
|------|----------|------|
| `code/web/server.py` | 更新 | 新增缓存逻辑、健康检查接口 |
| `code/web/safety_filter.py` | 更新 | 新增敏感信息过滤 |
| `code/web/templates/index.html` | 更新 | 新增模型选择下拉框 |
| `code/web/config.json` | 更新 | 新增模型配置 |

### 4.2 新增文件

| 文件 | 说明 |
|------|------|
| `code/web/cache_manager.py` | 缓存管理模块 |

---

## 五、验收标准

### 功能验收

- [x] 缓存机制正常工作
- [x] 模型切换功能正常
- [x] 健康检查接口返回正确
- [x] 敏感信息被正确过滤

### 性能验收

- [x] 缓存命中时响应 < 500ms
- [x] 健康检查响应 < 100ms
- [x] 不增加 API 调用费用

---

## 六、优化功能回填

| 优化项 | 状态 | 备注 |
|--------|------|------|
| 缓存机制 | [x] 已完成 | cache_manager.py 已实现 |
| 模型切换 | [x] 已完成 | 前端下拉框 + 后端参数支持 |
| 健康检查接口 | [x] 已完成 | /api/health 接口已新增 |
| 敏感信息过滤 | [x] 已完成 | safety_filter.py 已增强 |

---

## 变更记录

| 日期 | 版本 | 变更内容 | 变更人 |
|------|------|----------|--------|
| 2026-07-12 | v1.0 | 初始版本 | Claude |
| 2026-07-12 | v1.1 | 完成所有优化功能开发 | Claude |