FEATURE_DIAGNOSIS.md

# 功能诊断指南

## 🔍 问题：新增功能无法使用

如果您发现Graph View和摘要高亮功能无法使用，请按照以下步骤诊断：

## ✅ 第一步：检查代码是否已更新

### 1. 确认文件已更新

检查 `static/index.html` 是否包含新功能：

```bash
# 检查Graph View相关的代码
grep -n "Graph View\|tab-graph\|graph-view" static/index.html

# 检查摘要高亮相关的代码
grep -n "highlighted_snippet" static/index.html
```

**应该看到**：
- Tab导航按钮
- Graph View容器
- 摘要高亮处理代码

### 2. 检查后端API

```bash
# 检查Graph API
grep -n "/api/search/graph" web_server.py

# 检查摘要高亮
grep -n "generate_highlighted_snippet\|highlighted_snippet" search_engine.py
```

## 🚀 第二步：重启服务器

**重要**：代码更改后必须重启服务器！

### 停止旧服务器

```bash
# 查找运行中的服务器进程
ps aux | grep "web_server.py\|uvicorn"

# 停止服务器（替换PID）
kill <PID>
```

### 启动新服务器

```bash
cd /Users/papersiii/tum-search
python3 web_server.py --mode user --port 8000
```

## 🌐 第三步：清除浏览器缓存

### 方法1：硬刷新

- **Windows/Linux**: `Ctrl + Shift + R`
- **Mac**: `Cmd + Shift + R`

### 方法2：清除缓存

1. 打开浏览器开发者工具（F12）
2. 右键点击刷新按钮
3. 选择"清空缓存并硬性重新加载"

### 方法3：使用无痕模式

在新无痕窗口中打开：
```
http://localhost:8000/
```

## 🔎 第四步：检查功能是否出现

### 测试Graph View

1. **搜索任意关键词**（如 "TUM"）
2. **查看搜索结果区域上方** - 应该看到两个Tab：
   - ✅ "List View" (列表视图)
   - ✅ "Graph View" (网络图视图)
3. **点击 "Graph View" Tab** - 应该显示网络图

### 测试摘要高亮

1. **搜索任意关键词**（如 "TUM"）
2. **查看搜索结果卡片中的摘要文本**
3. **关键词应该以青色加粗显示**

## 🐛 常见问题排查

### 问题1：看不到Graph View Tab

**可能原因**：
- 浏览器缓存了旧页面
- 服务器没有重启
- 访问了错误的URL

**解决方案**：
1. 确认访问 `http://localhost:8000/`（根路径）
2. 硬刷新页面（Ctrl+Shift+R）
3. 检查浏览器控制台是否有错误

### 问题2：摘要高亮不显示

**可能原因**：
- 搜索结果中没有 `highlighted_snippet` 字段
- 关键词在文本中不存在
- HTML渲染问题

**检查方法**：
1. 打开浏览器开发者工具（F12）
2. 切换到 **Network** 标签
3. 执行搜索
4. 点击 `/api/search?q=...` 请求
5. 查看响应中的 `results` 数组
6. 检查第一个结果是否有 `highlighted_snippet` 字段

### 问题3：Graph View为空或报错

**可能原因**：
- ECharts库未加载
- 网络图数据为空
- JavaScript错误

**检查方法**：
1. 打开浏览器控制台（F12）
2. 查看是否有JavaScript错误
3. 检查是否加载了ECharts：
   ```javascript
   typeof echarts !== 'undefined'
   ```
4. 检查API响应：
   ```javascript
   fetch('/api/search/graph?q=TUM').then(r => r.json()).then(console.log)
   ```

## 🔧 手动测试步骤

### 测试1：检查后端API

```bash
# 启动服务器后，测试搜索API
curl "http://localhost:8000/api/search?q=TUM" | python3 -m json.tool | head -50

# 检查是否包含highlighted_snippet字段
curl "http://localhost:8000/api/search?q=TUM" | grep -o "highlighted_snippet" | head -1
```

### 测试2：检查Graph API

```bash
# 测试Graph API
curl "http://localhost:8000/api/search/graph?q=TUM&max_nodes=10" | python3 -m json.tool
```

应该返回包含 `nodes` 和 `edges` 的JSON数据。

### 测试3：浏览器控制台测试

在浏览器控制台中输入：

```javascript
// 检查Tab元素是否存在
document.getElementById('tab-graph')

// 检查Graph容器是否存在
document.getElementById('graph-container')

// 检查ECharts是否加载
typeof echarts

// 测试Graph API
fetch('/api/search/graph?q=TUM').then(r => r.json()).then(data => {
    console.log('节点数量:', data.nodes?.length);
    console.log('边数量:', data.edges?.length);
})
```

## 📝 功能确认清单

### Graph View功能

- [ ] 搜索后能看到两个Tab（List View和Graph View）
- [ ] 点击Graph View Tab后能显示网络图
- [ ] 网络图中有节点和连线
- [ ] 中心节点是青色，相关节点是紫色
- [ ] 点击节点可以跳转到详情页

### 摘要高亮功能

- [ ] 搜索结果中的关键词被加粗显示
- [ ] 关键词是青色（cyan-400）
- [ ] 关键词有半透明背景
- [ ] 多个关键词都会被高亮

## 🆘 如果仍然无法使用

### 检查清单

1. ✅ **服务器已重启**
   ```bash
   ps aux | grep web_server
   ```

2. ✅ **访问正确的URL**
   - `http://localhost:8000/` ✅
   - `http://localhost:8000/static/index.html` ✅

3. ✅ **浏览器缓存已清除**
   - 使用无痕模式测试

4. ✅ **检查服务器日志**
   - 查看终端输出是否有错误

5. ✅ **检查浏览器控制台**
   - 按F12打开开发者工具
   - 查看Console标签的错误信息

### 获取帮助信息

如果仍然无法解决，请提供以下信息：

1. **服务器日志**（终端输出）
2. **浏览器控制台错误**（F12 → Console）
3. **网络请求响应**（F12 → Network → 查看 `/api/search` 响应）
4. **访问的URL**

## 🔄 快速修复步骤

```bash
# 1. 停止服务器
pkill -f "web_server.py"

# 2. 确认代码已更新
git status
git log --oneline -3

# 3. 清除浏览器缓存（在浏览器中操作）

# 4. 重启服务器
cd /Users/papersiii/tum-search
python3 web_server.py --mode user --port 8000

# 5. 在无痕窗口中访问
# http://localhost:8000/
```

## 📚 相关文件位置

- **前端代码**：`static/index.html`
  - Graph View: 第193-222行
  - 摘要高亮: 第938-999行
  
- **后端API**：
  - Graph API: `web_server.py` 第223-370行
  - 搜索API: `web_server.py` 第218-221行
  - 摘要高亮: `search_engine.py` 第226-241行