# 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. 安装步骤 ```bash # 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` 文件中添加以下配置： ```bash # 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. 数据库表结构 系统会自动创建以下数据表： ```sql -- 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. 上传卷子照片 1. 点击 **"OCR识别记录"** 进入列表页 2. 点击 **"上传卷子照片"** 按钮 3. 选择老师（从下拉列表中选择） 4. 选择学生（根据老师动态加载） 5. 上传图片文件（支持拖拽） 6. 点击 **"上传并开始OCR识别"** 7. 等待上传完成 ### 3. 查看识别结果 1. 在OCR记录列表中查看所有记录 2. 使用过滤器按状态/年级/班级筛选 3. 点击记录行的 **"查看详情"** 按钮 4. 查看详细信息： - 基本信息（学生、图片信息） - 原图预览 - 识别统计 - 题目详情列表 ### 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" } ``` 响应示例： ```json { "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` 中配置： ```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% | 低置信度 | 红色 | ## 故障排除 ### 常见问题 1. **上传失败** - 检查文件大小（<10MB） - 检查文件类型（JPG/PNG/WEBP） - 检查网络连接 - 查看日志：`storage/logs/laravel.log` 2. **OCR处理失败** - 检查LearningAnalytics服务是否运行 - 验证图片是否清晰 - 尝试重新处理 3. **图片不显示** - 运行 `php artisan storage:link` - 检查文件权限：`chmod -R 755 storage/app/public` - 验证磁盘空间充足 4. **学生列表为空** - 检查teachers和students表是否有数据 - 验证外键关联关系 ### 日志查看 ```bash # 查看Laravel日志 tail -f storage/logs/laravel.log # 查看OCR相关日志 grep "OCR" storage/logs/laravel.log # 查看文件上传日志 grep "upload" storage/logs/laravel.log ``` ### 性能监控 ```bash # 检查数据库连接 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集成 - 🔧 文件上传管理 - 🔧 错误处理与日志记录 --- **开发完成！** 🎉 系统现已准备就绪，可以投入生产使用。如有问题，请查阅故障排除章节或联系开发团队。