# FairScan

> 此文档为项目需求文档

## 文件原有的离线扫描功能

- 相机实时预览、文档边缘检测、自动裁切
- 页面编辑（裁切/旋转/滤镜/顺序调整）
- PDF/JPEG 导出
- 多页扫描管理

## 手机网络图传功能

### 变成一个局域网内进行一定压缩广播的实时网络摄像头

- 手机端通过 WebSocket 将 JPEG 帧发送到 PC
- PC 端浏览器实时显示画面
- 支持帧率控制（无限制 / 15fps / 10fps / 5fps）
- 丢帧策略：上一帧未发送完毕则丢弃当前帧，保证实时性
- 连接状态显示（已连接/未连接/出错）

#### 压缩力度可选

- **低质量**：最长边 640px，JPEG 质量 45，目标 8~12fps
- **均衡**：最长边 960px，JPEG 质量 60，目标 6~10fps（默认）
- **高质量**：最长边 1280px，JPEG 质量 75，目标 5~8fps

## 支持将离线扫描出来的pdf，通过局域网wifi网络协议发送给pc主机

### 已实现的核心功能

#### 1. PDF 上传
- 手机端在导出页可选择"仅传输到电脑"
- 通过 HTTP multipart/form-data 上传到 PC 服务器 `POST /upload/pdf`
- 上传进度与状态实时显示
- 上传成功后返回 `fileId`，PC 端保存原始 PDF 到 `./uploads/` 目录

#### 2. 上传+处理
- 上传后自动创建处理任务：`POST /tasks/process`
- 支持两种处理类型：
  - **OCR PDF** (`processType=ocrpdf`) — 复制原始 PDF 作为"处理结果"
  - **Markdown** (`processType=markdown`) — 生成模拟 `.md` 文件
- 任务状态轮询：queued → processing (10% → 50% → 90%) → completed
- 处理完成后可下载产物

#### 3. PC 端管理面板
- 浏览器访问 `/dashboard` 查看管理界面
- 统计卡片：已上传文件数、处理任务数、排队中/处理中/已完成
- 文件列表：显示已上传的 PDF，支持下载原始文件
- 任务列表：显示所有处理任务，支持下载处理产物
- 自动刷新（每 2 秒）
- 导航栏：可在图传预览页和管理面板间切换

### 所连接的wifi可自定义，可以显示出自己的IP和端口

- 设置页可配置 PC 主机地址和端口
- 支持手动输入 IP 和端口
- 显示当前手机 IP 地址
- 通过 `GET /health` 测试连接
- 局域网发现（mDNS/NSD）的占位代码已准备，待完整实现

### MinerU转成markdowm便于数字化存储 ✅ 已实现

- `processType=markdown` 处理类型
- 使用 MinerU `aio_do_parse()` 异步接口，pipeline 后端
- `HF_HUB_OFFLINE=1` 使用本地缓存模型（绕过 huggingface.co 不可达）
- 输出产物：`.md` + `images/` + `{name}_result.zip`（ZIP 含 .md + images/）
- 手机端可通过任务管理面板查看状态并下载到指定目录

### 进行OCRmyPDF 转成双层pdf 📌 下一步

- `processType=ocrpdf` 处理类型
- **当前**：使用 MinerU 生成 layout PDF（画布局框，非真正 OCR）
- **目标**：接入 `ocrmypdf` 库，生成可搜索双层 PDF
- 接口已预留，详见 `requirements/NEXT_STEPS.md`

## PC 端服务器

基于 Python FastAPI，提供以下端点：

| 端点 | 方法 | 功能 |
|------|------|------|
| `/health` | GET | 健康检查 |
| `/` | GET | 图传预览页面 |
| `/stream` | WS | 接收 JPEG 帧 |
| `/dashboard` | GET | 管理面板页面 |
| `/api/dashboard` | GET | 管理面板 JSON 数据 |
| `/upload/pdf` | POST | 上传 PDF（纯上传，不处理） |
| `/tasks/process` | POST | 创建处理任务 |
| `/tasks/{taskId}` | GET | 查询任务状态 |
| `/tasks/{taskId}/artifacts` | GET | 查询任务产物列表 |
| `/artifacts/{artifactId}/download` | GET | 下载处理产物 |
| `/files/{fileId}/download` | GET | 下载已上传的原始文件 |

### 手机端任务管理面板 ✅ 已实现

- 导出页底部 `TaskPanelSection`：显示所有上传处理任务
- 任务状态：排队中 / 处理中（进度条） / 已完成 / 失败
- 2 秒间隔后台轮询，完成后自动停止
- 已完成任务：选择下载目录（SAF）→ 下载产物 → 打开文件
- Markdown 任务默认下载 ZIP（.md + images/），OCR PDF 任务下载 PDF

## 后续待实现

- **P0 OCRmyPDF 真实接入**：用 `ocrmypdf` 库替换 MinerU layout PDF，产出可搜索双层 PDF
- **P0 局域网自动发现**：mDNS/NSD 自动发现 PC 服务
- **处理结果自动下载**：配置开启后自动下载处理结果
- **图传延迟/帧率实时显示**