math_cms/Laravel 题库管理说明.md

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 文件：

QUESTION_BANK_API_BASE=http://localhost:5015

2. 启动服务

# 启动知识图谱服务
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

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 响应格式

{
  "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 调用失败

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

解决方案：

# 检查题库服务状态
curl http://localhost:5015/health

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

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

问题 2: 缓存问题

症状：数据不更新

解决方案：

# 清理 Laravel 缓存
php artisan cache:clear
php artisan config:clear
php artisan route:clear

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

问题 3: 题目生成失败

症状：AI 生成功能报错

解决方案：

# 检查 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