X-Financial/document/development/receipt-folder/CONCEPT.md

票据夹功能概念文档

更新时间：2026-05-29

功能一句话

票据夹用于归集用户已上传并经过 OCR 识别的原始票据文件，避免票据已识别但忘记关联报销单后无法找回。

背景与问题

当前系统有两条票据路径：

• 报销明细附件路径：票据上传到某个草稿费用明细后，会存入 expense_claims 附件目录，并写入附件元数据。
• 独立 OCR 识别路径：报销对话里先上传票据识别时，/ocr/recognize 只返回识别结果，源文件使用临时目录，识别结束后会清理。

这会导致一个业务缺口：用户可能已经上传票据并完成 OCR，但还没有把票据关联到报销草稿。只要用户关闭会话、切走页面或忘记继续操作，原始票据就没有一个稳定入口可追溯。

票据夹要补齐这个缺口：凡是系统对用户上传文件做过 OCR 并持久化源文件，就应进入票据夹列表；后续用户可以查看、修正票据信息、删除无效票据，或一键把未关联票据带入报销对话。

目标与非目标

目标：

• 在左侧侧边栏的“单据中心”下面新增“票据夹”入口。
• 建立票据源文件持久化能力，OCR 后保留原始文件、预览文件和识别元数据。
• 提供票据夹列表，复用单据中心的紧凑列表视觉语言。
• 支持“未关联票据 / 已关联票据”两个状态切换。
• 支持票据详情：基本票据信息可编辑、原始文件可预览、底部返回列表和删除票据。
• 支持“一键关联票据”：选择未关联票据，选择未提交草稿或新建报销单，再跳转到报销对话继续填写和关联。

非目标：

• 本轮不引入 document_assets 等数据库结构变更；先用文件资产和元数据 JSON 完成产品闭环。
• 本轮不替换现有报销明细附件接口。
• 本轮不把票据夹做成财务共享的全公司档案库；默认只展示当前登录用户自己的票据。
• 本轮不在列表页直接完成报销单提交，提交仍回到现有对话核对流程。

用户与场景

涉及角色：

• 普通员工：上传票据后稍后再归集到草稿。
• 经理或财务用户：在自己名下上传票据时同样需要留存和追溯。

典型场景：

1. 用户在个人工作台上传 3 张票据，OCR 成功后暂时没有保存草稿。
2. 用户第二天打开票据夹，看到这 3 张票据仍在“未关联票据”。
3. 用户进入详情，修正票据类型、金额或日期。
4. 用户点击“一键关联票据”，多选未关联票据。
5. 用户选择已有草稿，或选择新建报销单。
6. 系统打开报销对话，把票据源文件和 OCR 信息带入现有核对流程。

功能能力

票据持久化

• OCR 入口接收文件后，在识别完成阶段保存源文件。
• 保存位置建议为 storage/receipt_folder/<owner_key>/<receipt_id>/。
• 每个票据目录包含：
  • 原始文件：source.<ext>
  • 预览文件：preview.<ext>，可为空
  • 元数据：meta.json
• 元数据记录：
  • id
  • owner_key
  • file_name
  • media_type
  • size_bytes
  • uploaded_at
  • status: unlinked / linked
  • linked_claim_id
  • linked_claim_no
  • linked_item_id
  • linked_at
  • OCR 引擎、模型、文本、摘要、置信度、票据类型、场景、结构化字段、提示信息

列表

• 页签：
  • 未关联票据
  • 已关联票据
• 表格字段建议：
  • 票据文件
  • 识别类型
  • 费用场景
  • 金额
  • 票据日期
  • OCR 置信度
  • 关联状态
  • 上传时间
• 交互：
  • 搜索文件名、摘要、字段值、关联单号
  • 按状态切换
  • 点击行进入详情
  • 未关联页显示“一键关联票据”

详情

• 基本票据信息：
  • 文件名只读
  • 票据类型可编辑
  • 费用场景可编辑
  • 票据日期可编辑
  • 金额可编辑
  • 商户 / 出发地 / 到达地 / 票据号码等 OCR 字段可编辑
• 原始文件展示：
  • 图片直接预览
  • PDF 用浏览器内嵌预览
  • 不可预览类型提供下载入口
• 底部动作：
  • 返回列表
  • 删除票据

一键关联票据

流程：

1. 打开关联弹窗，展示未关联票据多选列表。
2. 下一步展示当前用户未提交草稿报销单，也提供“新建报销单”选项。
3. 确认后打开现有报销对话。
4. 如果选择已有草稿：
   • 对话以 link_to_existing_draft 语义继续。
   • 携带 draft_claim_id 和票据文件。
5. 如果选择新建报销单：
   • 对话以 create_new_claim_from_documents 语义继续。
   • 携带票据文件和 OCR 元数据。

方案设计

后端

新增模块：

• schemas/receipt_folder.py
• services/receipt_folder.py
• api/v1/endpoints/receipt_folder.py

接口建议：

• GET /api/v1/receipt-folder?status=unlinked|linked|all
• GET /api/v1/receipt-folder/{receipt_id}
• PATCH /api/v1/receipt-folder/{receipt_id}
• DELETE /api/v1/receipt-folder/{receipt_id}
• GET /api/v1/receipt-folder/{receipt_id}/preview
• GET /api/v1/receipt-folder/{receipt_id}/source

OCR 改造：

• /api/v1/ocr/recognize 保持现有响应结构兼容。
• 在识别后调用票据夹服务保存源文件和识别结果。
• 给每个返回的 OCR 文档补充可选 receipt_id、receipt_preview_url、receipt_source_url 字段。

前端

新增模块：

• services/receiptFolder.js
• views/ReceiptFolderView.vue
• assets/styles/views/receipt-folder-view.css

导航改造：

• useNavigation.js 新增 receiptFolder，放在 documents 后面。
• accessControl.js 将 receiptFolder 作为默认可见视图。
• router/index.js 自动生成 /app/receiptFolder 路由。
• AppShellRouteView.vue 渲染新页面，并允许页面触发 openSmartEntry。

对话衔接：

• 票据夹确认关联时，前端从 source 接口取回 Blob，构造 File 对象传给 openSmartEntry。
• 同时把已编辑 OCR 元数据转为 initialReceiptDocuments 或直接通过 prompt / extraContext 进入对话。
• 本轮优先用现有 initial-files 和 initial-prompt 打开对话，确保用户可以继续核对和保存。

算法与公式

当前功能不涉及显式数学公式。

列表排序使用上传时间倒序：

sortKey(receipt) = uploadedAt(receipt)

状态归类：

status(receipt) =
\begin{cases}
linked, & linkedClaimId \neq \emptyset \\
unlinked, & linkedClaimId = \emptyset
\end{cases}

测试方案

后端：

• OCR 识别后会保存源文件和 meta.json。
• 列表只返回当前用户票据。
• status=unlinked 只返回未关联票据。
• 详情可读取 OCR 字段。
• PATCH 后字段持久化。
• 预览接口能返回图片或 PDF。
• DELETE 只删除票据夹根目录下的目标票据。

前端：

• 导航中“票据夹”位于“单据中心”下面。
• 列表空态、加载态、错误态可用。
• 未关联和已关联两个页签计数正确。
• 点击行进入详情。
• 详情可保存字段、返回列表、删除票据。
• 一键关联弹窗能完成票据选择和草稿选择。

集成：

• 上传票据触发 OCR 后，票据出现在票据夹。
• 从票据夹选择未关联票据，可打开报销对话。
• 选择已有草稿时，对话带入草稿单号。
• 选择新建报销单时，对话提示基于票据新建。

指标与验收

• OCR 成功返回后，票据夹列表能查到对应源文件。
• 票据源文件和预览文件在重启后仍可访问。
• 未关联票据和已关联票据状态切换正确。
• 票据详情字段修改后刷新仍保留。
• 删除票据后列表不再显示，预览接口返回 404。
• 侧边栏位置符合要求：票据夹在单据中心下面。
• 单个新增核心前端和后端模块不超过 800 行。

风险与开放问题

• 当前报销草稿流主要持久化 OCR 文本和文件名，真实文件复制到报销明细附件目录仍需要进一步打通。
• 本轮采用文件元数据而非数据库，适合先完成闭环；后续若需要审计、权限、跨用户协作和全文检索，应升级到资产表。
• 已关联状态如何自动回写，需要在后续把票据夹 ID 与报销明细 invoice_id 建立更强绑定。
• 多票据关联时，如果用户中途取消对话，本轮仍保留为未关联，避免误标。

2026-06-03 详情页与上传治理补充

本轮根据新的验收要求收敛为三块核心内容：

• 左侧为票据预览，使用共享详情页主区域承载，图片和 PDF 都以完整票据可见为优先目标，不再提供“打开源文件”按钮。
• 右侧为识别票据详情，展示当前票据所有 OCR 字段和基础字段；用户点击“编辑”后可直接修改识别内容，保存后写回票据夹元数据。
• 底部为关联信息；左侧预览卡底部同时展示用户编辑操作记录，用于后续财务判断人工修改痕迹。

编辑记录治理：

• PATCH /receipt-folder/{receipt_id} 在保存前后对可编辑票据信息做字段级 diff。
• 每条编辑日志记录操作者、操作时间、字段名称、修改前值、修改后值。
• 前端详情页只展示真实 edit_logs，不再用模拟操作日志替代。

重复上传治理：

• OCR 持久化票据时计算源文件 sha256。
• 同一用户再次上传相同源文件时，不新建票据目录，返回已有 receipt_id，并在 OCR 文档 warnings 中提示“已上传过同样的单据，请不要重复上传。”

报销助手联动：

• 用户在报销助手上传新附件前，如果票据夹中存在未关联票据，先提示用户是否进入票据夹关联。
• 用户可以选择“去票据夹关联”，也可以选择“继续上传新附件”；继续上传时只跳过本次未关联提醒，不影响后续重复附件校验。

删除级联：

• 已关联票据对应的报销单被删除时，票据夹中关联该报销单的票据源文件、预览文件和元数据一并删除。