goodbuddy/docs/features/document-processing/user-stories.md

HTTP OCR 用户场景

本文件覆盖 HTTP 扩展 FR-H1 至 FR-H12 及 图片路由 FR-I1 至 FR-I5。当前实现及证据见 生产实现和进度，未执行的场景不视为通过。

ID	Given / When / Then
US-H1	给定设备没有本地 OCR 模型，用户保存可用 HTTP 服务并测试扫描 PDF，应返回逐页文字和图片；切回本地来源时再检查本地模型。对应 FR-H1、FR-H7。
US-H2	给定包含文本页和扫描页的 PDF，用户以自动聊天或完整索引方式导入，仅需要 OCR 的页进入所选 Provider，结果保留原始页码；快速模式不上传，高保真按全页处理。对应 FR-H2。
US-H3	给定两页有相同图片键的文档，解析完成并重开聊天或知识库时，两页图片均可查看且来源正确；删除一份文档不损坏另一份的图片。对应 FR-H3。
US-H4	给定页眉包含合同编号，用户选择保留页眉页脚后再次测试，能看到原先被默认过滤的内容；恢复服务默认或设置空排除列表的含义不同且可辨认。对应 FR-H4。
US-H5	给定两页连续表格，用户启用重组后可检查表格结果及来源页集合；合并错误、无变化或无法关联页码时，测试信息如实显示。对应 FR-H5、FR-H7。
US-H6	给定 HTTP 返回 401、429、5xx 或超时，导入提示对应错误；用户修正设置后可重试。解析期间取消则停止后续请求并清理本次未提交图片，已有草稿与索引保留。对应 FR-H6。
US-H7	给定服务只返回图片 URL，客户端不访问该 URL，明确报告图片未保存；自动聊天可按逻辑规则保留文字及警告，知识库完整索引和高保真不可将其当作完整结果。对应 FR-H3、FR-H6。
US-H8	给定现有本地设置和图片型 PPTX，升级后默认仍走本地；主动选择 HTTP 后识别直接内嵌图片并标注“幻灯片 N · 图片 M”，不把图片响应顺序当作幻灯片号。对应 FR-H1、FR-H2。
US-H9	给定高级开关在 OpenAPI 中存在但对应模型未安装，启用测试时报告服务错误和选项名称，不以连接成功代替能力验证，也不静默忽略用户设置。对应 FR-H4、FR-H7。
US-H10	给定文档附件已发送或被发送队列接受，用户关闭应用并删除外部原文件，再启动后可打开保存的原文件、正文及图片，队列可恢复附件内容；取消生成不会删除附件。对应 FR-H8、FR-H9。
US-H11	给定草稿、已发送会话和知识库分别持有文档，移除草稿或取消导入只清理本次暂存；删除会话只清理无其他引用的资源，知识库图片仍可查看。对应 FR-H9、FR-H10。
US-H12	给定本地与远程均有配置，切换来源后配置仍在；修改高级选项时须保存后才能测试，结果可切换正文、图片和详情视图。再改配置并打开历史附件时，旧结果及其所用选项不变。保存失败保留草稿，关闭或切分类遵循未保存保护。对应 FR-H11、FR-H12。
US-H13	给定已有聊天草稿解析结果或 managed/reference 知识库文档，重解析失败或取消后旧正文和图片仍可查看，知识库旧 chunks 仍可检索；成功后才替换。历史消息及已入队内容不会被替换，再解析产生新草稿。删除知识库来源清理无引用派生资源，不误删外部原文件。对应 FR-H10、FR-H11。
US-H14	给定测试、聊天、知识库中同一类解析结果，用户查看正文、图片和详情，页码及图片可互相定位，HTML 表格可读，缺失置信度显示未提供；打开原件遵循各自归属。测试不提供选图入会话，关闭预览后清理测试资源，reference 原件缺失仍可看保存的正文和图片。对应 FR-H3、FR-H7、FR-H12。
US-H15	给定导入或保存中断、磁盘写入失败、无文字或部分 OCR 失败，界面区分失败、中断、仅图片及部分结果；重启可从保存的原件重试，未保存则提示重选。自动聊天可靠文本可带警告发送，完整索引和高保真不替换旧结果；失败批次回滚且原草稿保留。对应 FR-H6、FR-H9、FR-H12。
US-H16	给定从聊天或知识库预览进入“前往文档解析设置”，应直达同一全局分类，关闭后保留原选择、目标和草稿；保存不自动重解析或发送。关闭本机推理监控应用不禁用解析，HTTP 来源无需加载本地模型。知识库“用于当前对话”继续选择检索范围，“添加所选图片”只复制图片；新建目标后回到预览，明确点击添加才改变附件。历史附件不可就地改写，队列修改须先恢复到草稿。对应 FR-H1、FR-H11、FR-H12、FR-I2、FR-I5。

图片与草稿验收

ID	Given / When / Then
US-I1	给定本次模型和 Runtime 支持图片输入，用户添加普通图片并发送，模型收到图片输入，不调用 OCR；如为请求生成缩放或转码副本，历史附件仍可打开原图。对应 FR-I1、FR-I3。
US-I2	给定实际模型或 Runtime 不支持图片输入，用户发送图片时收到明确提示，可选择提取文字或切换视觉模型；未作选择前不自动 OCR，也不声称模型已看到原图。切换后按实际能力重新判断。对应 FR-I1。
US-I3	给定聊天模型支持视觉，用户仍明确选择“提取图片文字”，系统调用已保存 OCR；成功后附件显示“原文件名 · 提取文字”和“仅发送提取文字，原图保留”，请求只有提取文字。失败时原图、草稿及原发送方式保留，允许重试。对应 FR-I2。
US-I4	给定纯图片消息已发送或入队，关闭应用并移除外部原文件后重开，原图仍可查看，队列可恢复；没有执行 OCR 的图片不要求存在解析正文或清单。对应 FR-I3。
US-I5	给定可恢复草稿引用暂存附件，应用退出再启动时不因临时目录清理丢失附件；移除该引用后仅清理无其他引用的资源。对应 FR-H9、FR-I3。
US-I6	给定同一知识库工作流，切换聊天模型是否支持视觉不会改变图片文字提取和索引策略；PDF、Office 仍遵循文档解析规则。该场景需在相应导入格式实现后验收。对应 FR-I4。
US-I7	给定文档已保存多张提取图片，打开预览为零选择，不发模型请求。勾选图片后点击添加，目标会话草稿出现带文档名、页码、图片序号的视觉附件；关闭前未添加的勾选不算附件，重新打开按草稿显示已附加状态。重复点击只添加一次，不自动全量发送。对应 FR-I5。
US-I8	给定草稿含父文档及从中选出的图片，发送时父文档全文只加入一次，图片分别作为图片输入；移除父文档后图片仍在，移除图片不影响文档。重解析父文档不会替换已复制图片，已发送图片及来源信息重启可用。同一图片移除后可再加，发送后可加到新草稿。对应 FR-I5、FR-H9。
US-I9	给定知识库预览有选择，存在可编辑活动会话时显示其名称并添加到该草稿；无会话或当前通道不可编辑时，可选择或新建会话，取消保持选择。添加中切换会话不改变目标，目标被删除则失败且不留下新副本。添加不启用知识检索、不带整篇文档、不自动发消息；源文档重解析或删除后会话图片仍可用。对应 FR-I5、FR-H10。
US-I10	给定草稿已有附件，选图批次超过共享数量或容量上限时整批拒绝且保留选择和草稿；重复项不重复占位。添加后切换到不支持图片的模型或 Runtime，发送明确阻止并允许切换、提取文字或移除。队列重启后实际能力不匹配同样保留资源并提供恢复到草稿修正，不静默丢图。对应 FR-I1、FR-I5。
US-I11	给定普通图片或文档插图正在 OCR，取消、失败或空文字不会改变发送方式；成功后可打开保留的原图并“改为发送原图”，按新能力重新校验。改显示名不改原始文件名，插图仍保留文档和页码来源；重试按当前保存配置且不破坏旧结果。对应 FR-I2、FR-I3、FR-I5。
US-I12	给定窄输入区、知识库单面板或嵌套预览，用户仅用键盘可切页签、勾选、放大、添加、取消和关闭；Escape 只处理顶层，关闭后焦点恢复。浅深主题、200% 缩放、工作栏展开及原生浏览器同时显示时，目标、状态和主操作仍可见可用。对应 FR-H12、FR-I5。

首次配置、成功解析、失败重试和取消均须从产品入口验收；独立脚本结果只证明指定部署的 接口行为。图片保留不等于后续文本模型会自动接收图片字节，也不等于知识库支持图片检索。