OCR_README.md 11 KB
Filament后台OCR结果查看器
项目概述
Filament后台OCR结果查看器是一个基于Filament框架开发的现代化管理后台，用于管理OCR识别记录和卷子照片分析。系统提供了完整的OCR识别流程管理，从上传到分析结果的完整闭环。
功能特性
1. 核心功能
✅ OCR记录管理
- 查看所有OCR识别记录
- 实时状态更新（待处理/处理中/已完成/失败）
- 处理进度条显示
- 平均置信度统计
✅ 智能筛选
- 按处理状态筛选
- 按年级/班级筛选
- 按创建日期筛选
- 实时搜索
✅ 卷子照片上传
- 分步选择：老师 → 学生 → 图片
- 拖拽上传支持
- 实时进度显示
- 图片预览功能
- 文件验证（类型、大小）
✅ 识别结果查看
- 详细基本信息展示
- 原图查看
- 识别统计
- 题目结果列表
- 批改标记展示
2. 技术栈
- 后端框架: Laravel 10
- 管理后台: Filament 3.x
- 前端交互: Livewire 3
- 数据库: MySQL/PostgreSQL
- 文件存储: Laravel Storage
- HTTP客户端: GuzzleHttp
3. 架构设计
┌─────────────────────────────────────────┐
│ Filament管理后台 │
│ ┌─────────────────────────────────┐ │
│ │ OCR记录列表页 │ │
│ └─────────────────────────────────┘ │
│ │ │
│ ┌───────────▼───────────┐ │
│ │ 实时轮询(10秒) │ │
│ └───────────┬───────────┘ │
│ │ │
│ ┌───────────▼───────────┐ │
│ │ ViewOCRRecord │ │
│ │ (详情页) │ │
│ └───────────┬───────────┘ │
│ │ │
│ ┌───────────▼───────────┐ │
│ │ UploadExamPaper │ │
│ │ (上传组件) │ │
│ └───────────────────────┘ │
│ │ │
└──────────────┼───────────────────────────┘
│
┌──────────▼──────────┐
│ LearningAnalytics │
│ (OCR服务) │
└──────────────────────┘
安装配置
1. 环境要求
- PHP >= 8.1
- Laravel >= 10.0
- MySQL >= 8.0 / PostgreSQL >= 13
- Composer
- Node.js >= 18 (用于前端资源)
2. 安装步骤
# 1. 进入项目目录
cd /Volumes/T9/code/math/apis/FilamentAdmin
# 2. 安装依赖
composer install
npm install
# 3. 复制环境配置文件
cp .env.example .env
# 4. 生成应用密钥
php artisan key:generate
# 5. 配置数据库
# 编辑 .env 文件，设置数据库连接信息
# 6. 运行数据库迁移
php artisan migrate
# 7. 创建软链接
php artisan storage:link
# 8. 构建前端资源
npm run build
# 9. 运行队列处理器（推荐）
php artisan queue:work
3. 环境变量配置
在 .env 文件中添加以下配置：
# LearningAnalytics服务地址
LEARNING_ANALYTICS_URL=http://localhost:5010
# 文件上传配置
FILESYSTEM_DISK=public
# 队列配置
QUEUE_CONNECTION=database
# 缓存配置
CACHE_DRIVER=redis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
4. 数据库表结构
系统会自动创建以下数据表：
-- OCR记录表
CREATE TABLE ocr_records (
id VARCHAR(255) PRIMARY KEY, -- 记录ID
exam_id VARCHAR(255), -- 考试ID
student_id VARCHAR(255), -- 学生ID
image_path VARCHAR(500), -- 图片路径
image_filename VARCHAR(255), -- 图片文件名
image_size INTEGER, -- 文件大小
image_width INTEGER, -- 图片宽度
image_height INTEGER, -- 图片高度
status VARCHAR(50), -- 处理状态
total_questions INTEGER, -- 题目总数
processed_questions INTEGER, -- 已处理题目数
confidence_avg DECIMAL(5,4), -- 平均置信度
created_at TIMESTAMP, -- 创建时间
updated_at TIMESTAMP, -- 更新时间
processed_at TIMESTAMP -- 处理完成时间
);
-- OCR题目结果表
CREATE TABLE ocr_question_results (
id INTEGER PRIMARY KEY AUTO_INCREMENT,
ocr_record_id VARCHAR(255), -- 关联OCR记录ID
question_number INTEGER, -- 题目编号
kp_code VARCHAR(50), -- 知识点代码
score_value INTEGER, -- 分数
student_answer TEXT, -- 学生答案
mark_detected VARCHAR(10), -- 批改标记
score_confidence DECIMAL(5,4), -- 置信度
created_at TIMESTAMP
);
使用指南
1. 访问后台
在浏览器中访问：http://fa.test/admin
使用管理员账号登录后，在侧边栏中找到 "OCR识别记录" 菜单。
2. 上传卷子照片
- 点击 "OCR识别记录" 进入列表页
- 点击 "上传卷子照片" 按钮
- 选择老师（从下拉列表中选择）
- 选择学生（根据老师动态加载）
- 上传图片文件（支持拖拽）
- 点击 "上传并开始OCR识别"
- 等待上传完成
3. 查看识别结果
- 在OCR记录列表中查看所有记录
- 使用过滤器按状态/年级/班级筛选
- 点击记录行的 "查看详情" 按钮
- 查看详细信息：
- 基本信息（学生、图片信息）
- 原图预览
- 识别统计
- 题目详情列表
4. 管理记录
- 查看详情: 点击记录行的查看按钮
- 实时更新: 列表页每10秒自动刷新
- 重新处理: 失败的任务可以点击"重新处理"按钮
- 筛选搜索: 使用顶部过滤器快速查找
API文档
OCR服务接口
系统通过HTTP调用LearningAnalytics服务进行OCR处理：
POST /api/ocr/process
Content-Type: application/json
{
"record_id": "ocr_xxx",
"image_path": "uploads/ocr/xxx.jpg",
"student_id": "student_xxx"
}
响应示例：
{
"success": true,
"record_id": "ocr_xxx",
"status": "processing",
"message": "OCR处理已开始"
}
文件结构
FilamentAdmin/
├── app/
│ ├── Models/
│ │ ├── OCRRecord.php # OCR记录模型
│ │ └── OCRQuestionResult.php # OCR题目结果模型
│ ├── Services/
│ │ └── OCRService.php # OCR业务逻辑服务
│ ├── Livewire/
│ │ └── UploadExamPaper.php # 上传组件
│ └── Filament/Resources/OCRRecordResource/
│ ├── Pages/
│ │ ├── ListOCRRecords.php
│ │ ├── ViewOCRRecord.php
│ │ └── UploadExamPaper.php
│ └── OCRRecordResource.php
├── database/migrations/
│ ├── 2025_11_23_000001_create_ocr_records_table.php
│ └── 2025_11_23_000002_create_ocr_question_results_table.php
├── config/
│ └── ocr.php # OCR配置
└── resources/
├── views/
│ ├── filament/pages/
│ │ └── upload-exam-paper.blade.php
│ └── livewire/
│ └── upload-exam-paper.blade.php
配置选项
1. OCR配置
在 config/ocr.php 中配置：
return [
'learning_analytics' => [
'url' => env('LEARNING_ANALYTICS_URL'),
'timeout' => 30,
],
'upload' => [
'max_size' => 10 * 1024 * 1024, // 10MB
'allowed_types' => ['jpg', 'jpeg', 'png', 'webp'],
'disk' => 'public',
'path' => 'uploads/ocr',
],
'processing' => [
'batch_size' => 10,
'poll_interval' => 10, // 秒
'max_retries' => 3,
],
];
2. 文件上传限制
- 最大文件大小: 10MB
- 允许的文件类型: JPG, PNG, WEBP
- 最大图片尺寸: 4096x4096px
- 存储位置:
storage/app/public/uploads/ocr/
3. 性能优化
- 分页: 默认25条/页，最大100条/页
- 索引: 关键字段已添加索引（student_id, status, created_at）
- 轮询: 列表页10秒自动刷新
- 缓存: 学生列表数据可缓存
状态说明
OCR记录状态
| 状态 | 描述 | 颜色 |
|---|---|---|
| pending | 等待处理 | 灰色 |
| processing | 正在处理 | 蓝色 |
| completed | 处理完成 | 绿色 |
| failed | 处理失败 | 红色 |
置信度评级
| 范围 | 描述 | 颜色 |
|---|---|---|
| >= 80% | 高置信度 | 绿色 |
| 60% - 80% | 中等置信度 | 黄色 |
| < 60% | 低置信度 | 红色 |
故障排除
常见问题
上传失败
- 检查文件大小（<10MB）
- 检查文件类型（JPG/PNG/WEBP）
- 检查网络连接
- 查看日志：
storage/logs/laravel.log
OCR处理失败
- 检查LearningAnalytics服务是否运行
- 验证图片是否清晰
- 尝试重新处理
图片不显示
- 运行
php artisan storage:link - 检查文件权限：
chmod -R 755 storage/app/public - 验证磁盘空间充足
- 运行
学生列表为空
- 检查teachers和students表是否有数据
- 验证外键关联关系
日志查看
# 查看Laravel日志
tail -f storage/logs/laravel.log
# 查看OCR相关日志
grep "OCR" storage/logs/laravel.log
# 查看文件上传日志
grep "upload" storage/logs/laravel.log
性能监控
# 检查数据库连接
php artisan tinker
> DB::connection()->getPdo();
# 检查队列状态
php artisan queue:monitor
# 清理过期缓存
php artisan cache:prune-stale-tags
开发团队
- 开发: Claude Code
- 完成时间: 2025-11-23
- 版本: v1.0.0
许可证
本项目为内部使用，禁止外传。
更新日志
v1.0.0 (2025-11-23)
新增功能:
- ✅ OCR记录列表查看
- ✅ 实时状态更新
- ✅ 智能筛选（状态/年级/班级/日期）
- ✅ 卷子照片上传
- ✅ 识别结果详情查看
- ✅ 图片预览功能
- ✅ 处理进度显示
- ✅ 重新处理功能
技术特性:
- 🔧 基于Filament 3.x
- 🔧 Livewire 3响应式组件
- 🔧 Laravel 10 ORM模型
- 🔧 RESTful API集成
- 🔧 文件上传管理
- 🔧 错误处理与日志记录
开发完成！ 🎉
系统现已准备就绪，可以投入生产使用。如有问题，请查阅故障排除章节或联系开发团队。