# PRD 需求文档 — 问题排查模块双模式界面升级

> 版本：1.0 ｜ 日期：2026-07-29 ｜ 分支：troubleshoot-ai-assistant

---

## 1. 需求背景

当前问题排查模块已支持两种运行模式：
- **在线模式（有 AI 接入）**：调用 Claude API 进行 AI 智能分析
- **离线模式（离线部署方式）**：基于 TF-IDF 搜索返回知识库匹配结果

目前两种模式共用同一套界面（问题输入表单 + AI 分析结果展示），但用户反馈离线模式的界面风格需要差异化设计，以更好地区分两种模式的使用场景，并增强离线模式的产品资料查阅功能。

### 1.1 业务场景分析

| 模式 | 适用场景 | 用户需求 |
|------|----------|----------|
| 在线模式 | 有网络环境，需 AI 智能分析 | 当前界面风格已满足需求，保持不变 |
| 离线模式 | 内网隔离环境，无 AI 支持 | 需要产品资料下载 + 常见问题查阅功能 |

---

## 2. 需求概述

### 2.1 核心需求

**根据 `OFFLINE_MODE` 环境变量自动切换界面风格：**

| 模式 | 界面风格 | 布局结构 |
|------|----------|----------|
| 在线模式（OFFLINE_MODE=false） | 当前风格 | 表单输入 + AI 分析结果展示 |
| 离线模式（OFFLINE_MODE=true） | 全新风格 | 左侧产品树 + 右侧资料/问题列表 |

### 2.2 离线模式界面设计

```
┌─────────────────────────────────────────────────────────────────┐
│ 顶部导航栏：运行维护平台                                          │
├──────────────────────┬──────────────────────────────────────────┤
│ 左侧面板 (280px)     │ 右侧内容区                                │
│                      │                                          │
│ ┌──────────────────┐ │ ┌────────────────────────────────────────┐│
│ │ 搜索框           │ │ │ 标题：产品资料 / 常见问题              ││
│ └──────────────────┘ │ └────────────────────────────────────────┘│
│                      │                                          │
│ ┌──────────────────┐ │ ┌────────────────────────────────────────┐│
│ │ 产品列表         │ │ │ 列表区                                ││
│ │                  │ │ │                                        ││
│ │ ▼ 门口屏5.0      │ │ │ 【产品资料模式】                       ││
│ │   ├ 产品资料     │ │ │ ┌────────────────────────────────────┐││
│ │   └ 常见问题     │ │ │ │ 📄 门口屏5.0维护手册.docx  [下载] │││
│ │                  │ │ │ │ 📄 安装部署指南.pdf         [下载] │││
│ │ ▼ 桌牌系统       │ │ │ │ 📄 配置说明.pdf             [下载] │││
│ │   ├ 产品资料     │ │ │ └────────────────────────────────────┘││
│ │   └ 常见问题     │ │ │                                        ││
│ │                  │ │ │ 【常见问题模式】                       ││
│ │   预定系统       │ │ │ ┌────────────────────────────────────┐││
│ │   会管平台       │ │ │ │ ▶ 门口屏绑定失败怎么办？           │││
│ │   ...            │ │ │ │ ▶ 会议信息不显示怎么处理？         │││
│ │                  │ │ │ │ ▶ 人脸识别异常如何排查？           │││
│ └──────────────────┘ │ │ └────────────────────────────────────┘││
│                      │ │                                        ││
│                      │ │ ┌────────────────────────────────────────┐│
│                      │ │ │ 排查指引详情（点击问题后展开）        ││
│                      │ │ │                                        ││
│                      │ │ │ 问题：门口屏绑定失败怎么办？          ││
│                      │ │ │                                        ││
│                      │ │ │ 排查步骤：                            ││
│                      │ │ │ 1. 检查网络连接...                    ││
│                      │ │ │ 2. 确认 MQTT 配置...                  ││
│                      │ │ │ ...                                   ││
│                      │ │ └────────────────────────────────────────┘│
└──────────────────────┴──────────────────────────────────────────┘
```

---

## 3. 功能详细设计

### 3.1 模式判断机制

前端通过 `/api/health` 接口的 `offline_mode` 字段判断当前模式：

```json
{
  "offline_mode": true,  // true = 离线模式，false = 在线模式
  ...
}
```

**判断流程：**
1. 应用启动时调用 `/api/health` 获取模式配置
2. 根据 `offline_mode` 值渲染对应界面组件
3. 模式切换需重启服务（热更新本期不做）

### 3.2 在线模式界面（保持不变）

保持当前界面风格：
- 表单输入：项目名称、系统类型、APK 产品、问题描述、模型选择
- SSE 流式分析结果展示
- 匹配案例列表 + 查看详情
- AI 分析结果渲染（Markdown）
- 导出 Word、提交入库功能

### 3.3 离线模式界面（全新设计）

#### 3.3.1 左侧面板：产品树

**组件结构：**

```
搜索框（实时过滤产品）
└── 产品列表（el-tree 或自定义树）
    ├── 产品A
    │   ├── 📁 产品资料
    │   └── ❓ 常见问题
    ├── 产品B
    │   ├── 📁 产品资料
    │   └── ❓ 常见问题
    └── ...
```

**产品数据来源：**
- 后端新增 API：`GET /api/troubleshoot/products`
- 返回产品列表，每个产品包含：
  - `id`: 产品唯一标识
  - `name`: 产品名称（如"门口屏5.0"、"桌牌系统"）
  - `system_type`: 系统类型（用于关联知识库记录）
  - `documents`: 产品资料文件列表（可选，预加载）
  - `faq_count`: 常见问题数量（可选）

**交互行为：**
- 搜索框输入时实时过滤产品列表（前端过滤）
- 点击"产品资料"节点 → 右侧展示该产品的资料文件列表
- 点击"常见问题"节点 → 右侧展示该产品的常见问题列表

#### 3.3.2 右侧面板：内容展示区

**两种展示模式：**

##### 模式一：产品资料

展示该产品的文档资料列表，支持下载到本地：

| 字段 | 说明 |
|------|------|
| 文件名称 | 文档标题（可点击下载） |
| 文件类型 | PDF / DOCX / MD 等 |
| 文件大小 | 可选显示 |
| 操作 | 下载按钮 |

**API 设计：**
- `GET /api/troubleshoot/products/{product_id}/documents` — 获取产品资料列表
- `GET /api/troubleshoot/documents/{doc_id}/download` — 下载文档

**文件存储方案：**
- 产品资料文件存放在 `Docs/维护手册/` 目录
- 后端配置文件定义产品与文档的映射关系（`config.json` 或独立配置）

##### 模式二：常见问题

展示该产品的常见问题列表，点击问题展开排查指引：

**问题列表：**
- 从知识库（357 条记录）中按产品筛选
- 显示问题标题、问题描述摘要
- 点击问题展开详细排查指引

**排查指引展示：**
- 问题标题
- 问题现象（phenomenon）
- 排查步骤（solution / troubleshoot_steps）
- 相关记录详情链接

**API 设计：**
- `GET /api/troubleshoot/products/{product_id}/faqs` — 获取常见问题列表
- 复用现有 `GET /api/troubleshoot/record/{id}` — 获取问题详情

#### 3.3.3 搜索功能

左侧顶部搜索框支持：
- **产品名搜索**：过滤左侧产品列表
- **全局问题搜索**：可选功能，搜索所有产品的问题（调用现有搜索 API）

---

## 4. 数据结构设计

### 4.1 产品配置结构

新增配置文件：`skill/code/web/products.json`

```json
{
  "products": [
    {
      "id": "door-screen-5.0",
      "name": "门口屏5.0",
      "system_type": "标准版预定2.0",
      "apk_product": "门口屏5.0",
      "documents": [
        {
          "id": "doc-001",
          "title": "门口屏5.0维护手册",
          "filename": "01-门口屏5.0维护手册.docx",
          "type": "docx",
          "size": "2.5MB"
        }
      ],
      "tags": ["门口屏", "会议显示"]
    },
    {
      "id": "desk-sign",
      "name": "桌牌系统",
      "system_type": "标准版预定2.0",
      "apk_product": "桌牌",
      "documents": [
        {
          "id": "doc-002",
          "title": "桌牌系统维护手册",
          "filename": "02-桌牌系统维护手册.docx",
          "type": "docx",
          "size": "1.8MB"
        }
      ],
      "tags": ["桌牌", "电子桌牌"]
    }
  ]
}
```

### 4.2 前端类型定义

```typescript
// 产品信息
interface Product {
  id: string
  name: string
  system_type?: string
  apk_product?: string
  documents?: Document[]
  faq_count?: number
  tags?: string[]
}

// 文档信息
interface Document {
  id: string
  title: string
  filename: string
  type: string
  size?: string
}

// 常见问题（复用现有 MatchedCase 结构）
interface FAQ {
  record_id: string
  title: string
  phenomenon: string
  solution: string
  score?: number  // 相关度
}
```

### 4.3 后端 API 设计

| API | 方法 | 说明 |
|-----|------|------|
| `/api/health` | GET | 已有，返回 `offline_mode` 字段 |
| `/api/troubleshoot/products` | GET | 获取产品列表 |
| `/api/troubleshoot/products/{product_id}` | GET | 获取产品详情 |
| `/api/troubleshoot/products/{product_id}/documents` | GET | 获取产品资料列表 |
| `/api/troubleshoot/documents/{doc_id}/download` | GET | 下载文档文件 |
| `/api/troubleshoot/products/{product_id}/faqs` | GET | 获取产品常见问题 |
| `/api/troubleshoot/record/{id}` | GET | 已有，获取问题详情 |

---

## 5. 界面风格对比

| 特性 | 在线模式 | 离线模式 |
|------|----------|----------|
| 布局 | 单栏卡片式 | 左右分栏式 |
| 主色调 | 紫色渐变 | 蓝色/中性色 |
| 核心操作 | 问题输入 → AI 分析 | 产品导航 → 资料查阅 |
| 交互方式 | 表单提交、流式输出 | 树形导航、列表点击 |
| 结果展示 | AI 分析报告 | 文档列表、问题答案 |

---

## 6. 非功能需求

| 项目 | 要求 |
|------|------|
| 模式切换 | 通过环境变量 `OFFLINE_MODE` 控制，前端无需修改代码 |
| 响应速度 | 产品列表加载 < 500ms，文档下载支持断点续传 |
| 文件下载 | 支持常见格式（PDF、DOCX、MD），文件名保持原中文名 |
| 移动端适配 | 离线模式支持移动端响应式，左侧面板可折叠 |
| 搜索性能 | 产品搜索前端实时过滤，问题搜索调用后端 TF-IDF |

---

## 7. 约束与依赖

### 7.1 技术约束

- 遵循项目 P1-3 三层架构：routes/services/utils
- 不修改 `search_engine.py` / `safety_filter.py` / `cache_manager.py` 公开接口
- 离线模式不影响在线模式行为（代码分支隔离）

### 7.2 数据依赖

- 产品资料文件需提前放置到 `Docs/维护手册/` 目录
- 产品配置需手动维护 `products.json`
- 常见问题依赖现有知识库（357 条记录）

### 7.3 用户提供项

用户需提供以下内容以丰富离线模式：
1. **产品维护手册清单**：产品名称、系统类型、文件名
2. **产品与知识库的映射关系**：哪些知识库记录属于哪个产品
3. **排查指引内容**：常见问题的详细排查步骤（可逐步补充）

---

## 8. 实施阶段

### 阶段一：基础架构（P0）

- 前端双模式路由判断
- 离线模式基础布局组件
- 产品列表 API + 前端展示
- 产品配置文件结构

### 阶段二：产品资料功能（P0）

- 产品资料列表展示
- 文档下载 API 实现
- 文件存储与配置管理

### 阶段三：常见问题功能（P0）

- 产品常见问题列表展示
- 问题详情展开/折叠
- 排查指引渲染

### 阶段四：搜索与优化（P1）

- 产品搜索过滤
- 全局问题搜索（可选）
- 移动端响应式适配

### 阶段五：内容丰富（P2）

- 产品资料持续补充
- 排查指引内容完善
- 产品与知识库映射优化

---

## 9. 验收标准

### 9.1 在线模式验收

- [ ] 界面风格与当前保持一致
- [ ] 所有功能正常（AI 分析、导出、入库等）
- [ ] `OFFLINE_MODE=false` 时正确显示在线界面

### 9.2 离线模式验收

- [ ] `OFFLINE_MODE=true` 时显示离线界面
- [ ] 左侧产品树正确展示
- [ ] 点击产品资料，右侧展示资料列表
- [ ] 点击资料名称可下载文件到本地
- [ ] 点击常见问题，右侧展示问题列表
- [ ] 点击问题展开排查指引
- [ ] 搜索框可过滤产品列表

### 9.3 兼容性验收

- [ ] 模式切换无需前端代码修改
- [ ] 两种模式共享公共组件（导航栏等）
- [ ] 单元测试通过（新增 API 测试用例）

---

## 10. 后续扩展（本期不做）

- 产品资料在线预览（PDF/Word 预览）
- 排查指引富文本编辑器
- 产品配置管理界面（管理员维护产品信息）
- 知识库记录自动归类到产品（AI 自动打标签）
- 离线包导出（U 盘分发场景）
