# Laravel 题库管理功能说明

## 📁 已创建的文件

### 1. 服务类
- **`app/Services/QuestionServiceApi.php`**
  - 题库 API 客户端
  - 提供题目 CRUD、搜索、统计等功能
  - 支持缓存机制（5分钟 TTL）

### 2. Filament 资源
- **`app/Filament/Resources/QuestionResource.php`**
  - 题库管理资源
  - 包含题目列表、筛选、搜索、批量操作
  - 支持知识点、难度、来源等多维度筛选

### 3. 页面类
- **`app/Filament/Resources/QuestionResource/Pages/ListQuestions.php`**
  - 题库列表页
  - 包含 AI 生成题目、智能搜索、刷新统计等功能

- **`app/Filament/Resources/QuestionResource/Pages/ViewQuestion.php`**
  - 题目详情页
  - 显示题目完整信息
  - 支持查找相似题、删除等操作

- **`app/Filament/Resources/QuestionResource/Pages/CreateQuestion.php`**
  - 创建题目页面（预留）

### 4. 配置文件
- **`config/question_bank.php`**
  - 题库 API 配置
  - 超时、缓存、重试等设置

### 5. API 路由
- **`routes/api.php`**
  - 题库相关 API 端点
  - GET /questions - 获取题目列表
  - GET /questions/{id} - 获取题目详情
  - POST /questions/search - 语义搜索
  - POST /questions/generate - AI 生成题目
  - DELETE /questions/{id} - 删除题目

## 🎯 功能特性

### 题目列表管理
- ✅ 分页显示（支持 10/25/50/100 每页）
- ✅ 按知识点筛选
- ✅ 按难度筛选（基础/中等/拔高）
- ✅ 搜索功能（题干、答案、解析）
- ✅ 查看题目编号、知识点代码、题干摘要
- ✅ 难度标签（颜色区分）
- ✅ 来源标识（AI 生成/手工录入）
- ✅ 创建时间显示
- ✅ 自动刷新（每分钟）

### 题目详情查看
- ✅ 完整题干展示（支持 Markdown）
- ✅ 标准答案（可复制）
- ✅ 详细解析（支持 Markdown）
- ✅ 难度标签和颜色
- ✅ 技能标签
- ✅ 创建/更新时间

### AI 题目生成
- ✅ 选择知识点
- ✅ 设置关键词
- ✅ 设置题目数量（1-100）
- ✅ 选择生成策略（自动/DeepSeek/Kimi）
- ✅ 进度反馈和结果通知

### 智能搜索
- ✅ 语义搜索相似题目
- ✅ 设置返回数量
- ✅ 实时显示搜索结果

### 批量操作
- ✅ 批量删除题目
- ✅ 多选支持

### 相似题目推荐
- ✅ 查看相似题目（基于向量检索）
- ✅ 快速跳转到相似题

### 统计信息
- ✅ 题库总数显示（导航徽章）
- ✅ 实时刷新统计数据

## 🚀 使用方法

### 1. 配置 API 地址

编辑 `.env` 文件：
```bash
QUESTION_BANK_API_BASE=http://localhost:5015
```

### 2. 启动服务

```bash
# 启动知识图谱服务
cd /Volumes/T9/code/math/apis/KnowledgeServic
docker compose up -d

# 启动题库服务
cd /Volumes/T9/code/math/apis/QuestionBankService
docker compose up -d

# 启动 Laravel 后台
cd /Volumes/T9/code/math/apis/FilamentAdmin
herd serve
```

### 3. 访问后台

```
URL: http://filament-admin.test/admin
```

### 4. AI 生成题目示例

在题目列表页，点击 "AI 生成题目" 按钮：
- 选择知识点：因式分解 (KP1001)
- 关键词：因式分解
- 数量：50
- 策略：自动选择模型

### 5. 搜索相似题

在题目列表页，点击 "智能搜索"：
- 输入搜索内容：提取公因式的题目
- 返回数量：20

## 🔌 API 对接

### Laravel 调用题库 API

```php
use App\Services\QuestionServiceApi;

$service = app(QuestionServiceApi::class);

// 获取题目列表
$questions = $service->listQuestions(1, 25, ['kp_code' => 'KP1001']);

// 搜索题目
$results = $service->searchQuestions('因式分解计算', 20);

// 生成题目
$result = $service->generateQuestions([
    'kp_code' => 'KP1001',
    'keyword' => '因式分解',
    'count' => 10,
    'strategy' => 'auto',
]);
```

### API 响应格式

```json
{
  "data": [
    {
      "id": 1,
      "question_code": "KP1001-AI-ABC123",
      "kp_code": "KP1001",
      "stem": "因式分解题目内容",
      "answer": "标准答案",
      "solution": "详细解析",
      "difficulty": 0.6,
      "source": "ai::deepseek",
      "tags": "整数因数分解,提公因式策略",
      "created_at": "2025-11-15T10:00:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 100,
    "total_pages": 4
  }
}
```

## 📊 数据流

```
Laravel 后台 (Herd)
    ↓ HTTP API 调用
题库服务 (localhost:5015)
    ↓ 数据查询
PostgreSQL + pgvector (localhost:5442)
    ↓ AI 调用
DeepSeek/Kimi API
```

## 🔐 安全措施

- ✅ API 超时保护（10秒）
- ✅ 失败重试机制（2次）
- ✅ 缓存机制（5分钟）
- ✅ 错误日志记录
- ✅ XSS 防护（Filament 自动处理）

## 🐛 故障排查

### 问题 1: API 调用失败

**症状**：页面显示空白或错误信息

**解决方案**：
```bash
# 检查题库服务状态
curl http://localhost:5015/health

# 检查 Laravel 日志
tail -f storage/logs/laravel.log

# 检查 API 配置
cat .env | grep QUESTION_BANK_API_BASE
```

### 问题 2: 缓存问题

**症状**：数据不更新

**解决方案**：
```bash
# 清理 Laravel 缓存
php artisan cache:clear
php artisan config:clear
php artisan route:clear

# 手动刷新缓存（API 层）
# 修改 QuestionServiceApi 中的 cacheTtl 设置
```

### 问题 3: 题目生成失败

**症状**：AI 生成功能报错

**解决方案**：
```bash
# 检查 AI API Key 配置
docker compose exec question_bank_api env | grep API_KEY

# 使用 dry_run 模式测试
python scripts/seed_ai_questions.py --keyword "因式分解" --count 5 --dry-run
```

## 🎨 UI 界面

### 导航结构
```
题库系统
├── 题库管理
└── 知识点管理
```

### 颜色编码
- **主色**：#4163ff (蓝色)
- **难度**：
  - 基础：绿色
  - 中等：黄色
  - 拔高：红色
- **来源**：
  - AI 生成：蓝色标签
  - 手工录入：灰色标签

## 📈 性能优化

### 1. 缓存策略
- 题目列表缓存：5分钟
- 统计信息缓存：5分钟
- 搜索结果缓存：5分钟

### 2. 分页优化
- 默认每页 25 条
- 最大 100 条每页
- 自动刷新：60 秒

### 3. API 优化
- 超时设置：10 秒
- 重试机制：2 次
- 重试延迟：200ms

## 🔮 后续规划

1. **增加题目编辑功能**：支持在线编辑题目
2. **添加题目审核流程**：三级审核机制
3. **优化相似题算法**：基于学习路径的推荐
4. **增加题目导出**：支持导出 Word/PDF
5. **添加题目统计**：使用情况、错误率等
6. **支持题目复用**：复制和模板功能

## 📝 注意事项

1. **API 地址**：确保使用正确的端口（5015）
2. **缓存清理**：数据更新后记得清理缓存
3. **并发限制**：注意 API 调用频率限制
4. **错误处理**：所有 API 调用都有异常捕获
5. **日志记录**：所有错误都有详细日志

---

**更新日期**：2025-11-15
**版本**：v1.0
**维护者**：Claude Code