docs(personal): document scanned PDF OCR

docs/个人AI助理阶段二专项TechSpec.md

@@ -385,6 +385,15 @@ Message 保存：
 - item 状态由 `QUEUED → PARSING → READY/FAILED` 单向推进；重试将状态恢复为 QUEUED、增加 `attempt_count`，并覆盖 `error_code/error_message`。
 - 文本块默认 800 字、重叠 120 字；参数由 `PersonalKnowledgeProperties` 管理。
 
+#### 8.1.1 扫描 PDF OCR
+
+- 普通 PDF 先走文本解析；仅在解析器返回 `EMPTY` 时转入视觉 OCR，不重复处理已有文本层的 PDF。
+- 每批最多识别 20 页，单文件硬上限 200 页；页面渲染限制最长边 2200px、单页图片 4MB，避免大图耗尽内存。
+- `aihr_personal_ocr_job` 保存文件级进度，`aihr_personal_ocr_page` 保存页级状态、识别正文、尝试次数和公开错误码；两表都必须带 `tenant_id + owner_user_id + item_id`。
+- 失败页最多自动尝试 3 次；已有成功页不重复调用模型。用户可在资料详情只重试失败页。
+- 至少一页成功时允许 item 进入 `READY`，同时展示失败页码；全部页面失败时 item 进入 `FAILED`，不得生成空片段或伪造正文。
+- OCR 复用 `category=vision` 的 OpenAI-compatible 模型配置；没有 vision 时不把普通 chat 模型的失败伪装成“文件为空”。
+
 ### 8.2 提示词模板
 
 新增模板代码：
@@ -447,6 +456,7 @@ src/services/personal-assistant.ts        API 客户端
 ### 10.2 关键交互
 
 - 上传后立即返回列表并显示解析状态，不阻塞页面等待解析。
+- 扫描 PDF 详情显示 `已处理页数/总页数`、进度条和失败页码；处理期间每 2 秒轮询，终态停止轮询。
 - 每条答案引用显示域徽标：我的资料、企业 SOP、外部网页。
 - 混合问答默认关闭，用户主动选择后才同时检索两域。
 - 删除前明确提示会删除附件、解析正文和搜索索引。
@@ -461,6 +471,10 @@ src/services/personal-assistant.ts        API 客户端
 | `PERSONAL_ITEM_NOT_FOUND` | 不存在或无权访问 | 统一显示不存在，不泄露归属 |
 | `PERSONAL_ITEM_NOT_READY` | 仍在解析 | 展示状态并允许刷新 |
 | `PERSONAL_PARSE_FAILED` | 解析失败 | 展示可公开原因和重试 |
+| `PERSONAL_OCR_MODEL_UNAVAILABLE` | 未配置可识图模型 | 提示配置视觉模型后重试失败页 |
+| `PERSONAL_OCR_PROVIDER_FAILED` | 视觉模型调用失败 | 保留失败页，允许稍后仅重试失败页 |
+| `PERSONAL_OCR_EMPTY` | 页面可访问但没有识别到文字 | 展示失败页和文件检查提示 |
+| `PERSONAL_PDF_PAGE_LIMIT` | PDF 超过 200 页 | 拒绝进入 OCR，提示拆分文件 |
 | `PERSONAL_URL_BLOCKED` | URL 被安全策略拦截 | 明确不能访问该地址 |
 | `PERSONAL_NO_CITATION` | 无足够资料支撑 | 不生成业务结论 |
 | `ENTERPRISE_SCOPE_FORBIDDEN` | 无企业知识范围权限 | 保留个人结果，提示企业范围不可用 |

docs/个人AI助理阶段二开发推进计划.md

@@ -1423,12 +1423,15 @@ Expected: PASS；无权限、空工单、空原因均拒绝；日志不含正文
 - [ ] 所有 API owner 来自服务端登录态。
 - [ ] 两个用户的列表、详情、全文、向量、会话、删除均无交叉可见。
 - [ ] 文字、文件、图片、网页链接可异步解析并可重试。
+- [x] 扫描 PDF 无文本层时进入页级 OCR：20 页/批、200 页上限、部分成功和失败页重试已实现。
 - [ ] URL 私网、元数据地址和恶意重定向全部被拒绝。
 - [ ] PERSONAL / ENTERPRISE / mixed 问答返回正确引用域。
 - [ ] 无授权引用时不调用 LLM 生成业务结论。
 - [ ] 删除立即隐藏，24 小时内清理片段、Qdrant 和 OSS。
 - [ ] mobile-uni 真实浏览器闭环通过。
 
+2026-07-12 扫描 PDF 增量验收记录：使用 8 页《关于修订证书管理办法的通知》真实扫描件完成 multipart 上传、OCR 作业/分页、关键词检索、个人域引用及删除后的 OCR/OSS/Qdrant 清理；本地 `vision` 运行时使用 `Qwen/Qwen3-VL-8B-Instruct`。移动端资料详情已增加进度、失败页码和失败页重试；浏览器自动化已确认文件收藏入口，但原生文件选择器仍需人工选取本地文件。
+
 ### P1 工程完成
 
 - [ ] 分享/企业入库必须审核并生成脱敏企业副本。