# 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集成
- 🔧 文件上传管理
- 🔧 错误处理与日志记录

---

**开发完成！** 🎉

系统现已准备就绪，可以投入生产使用。如有问题，请查阅故障排除章节或联系开发团队。
