YG-Soft/X-Financial
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0d6327a990f811a63e37ad7bd5fd095509ce57d6
X-Financial/document/development/receipt-folder/TODO.md
caoxiaozhu 4c59941ec6 feat: 新增票据夹模块并优化 OCR 与员工画像服务 
后端新增票据夹端点、数据模型和服务模块，优化 OCR 端点
Schema 和附件操作逻辑，完善员工行为画像服务和辅助函数，
前端新增票据夹视图和服务层，优化文档中心样式和侧边栏导
航，完善员工画像详情弹窗和权限控制，补充单元测试。
2026-05-29 14:51:18 +08:00

6.3 KiB
Raw Blame History

票据夹功能 TODO

更新时间：2026-05-29

阶段一：调研与契约

  • 梳理现有单据中心导航、列表样式和详情入口。[CONCEPT: 方案设计] 证据：已确认 DocumentsCenterView.vue、useNavigation.js、AppShellRouteView.vue 是前端入口。

  • 梳理现有 OCR 和报销附件存储链路。[CONCEPT: 背景与问题] 证据：已确认 /ocr/recognize 只临时识别；报销明细附件由 expense_claim_attachment_* 写入 expense_claims 存储。

  • 确定本轮不做数据库结构变更，先用票据文件资产和元数据 JSON 完成闭环。[CONCEPT: 目标与非目标] 证据：避免新增迁移，降低本轮开发风险。

阶段二：文档

  • 创建 document/development/receipt-folder/CONCEPT.md。[CONCEPT: 全文] 证据：本文档已落地。

  • 创建 document/development/receipt-folder/TODO.md。[CONCEPT: 测试方案] 证据：本文档已落地。

阶段三：后端票据资产层

  • 新增 schemas/receipt_folder.py，定义列表项、详情、字段更新和删除响应。[CONCEPT: 后端] 证据：已新增 ReceiptFolderItemRead、ReceiptFolderDetailRead、ReceiptFolderUpdate、ReceiptFolderDeleteResponse。

  • 新增 services/receipt_folder.py，负责源文件保存、元数据读写、预览解析、列表过滤和安全路径校验。[CONCEPT: 票据持久化] 证据：ReceiptFolderService 已覆盖 OCR 批量持久化、已关联附件同步、详情更新、预览/源文件解析与目录安全校验。

  • 新增 api/v1/endpoints/receipt_folder.py，暴露列表、详情、更新、删除、预览和源文件接口。[CONCEPT: 后端] 证据：已提供 GET/PATCH/DELETE /receipt-folder/{receipt_id} 及 preview/source 文件接口。

  • 在 api/v1/router.py 注册票据夹接口。[CONCEPT: 后端] 证据：已 include receipt_folder_router。

  • 改造 /ocr/recognize，OCR 后保存源文件并把 receipt_id 等可选字段带回前端。[CONCEPT: OCR 改造] 证据：OcrRecognizeDocumentRead 已补充 receipt_id、receipt_status、receipt_preview_url、receipt_source_url；来源于票据夹的 receipt_ids 会复用原票据，避免重复入库。

阶段四：前端票据夹页面

  • 新增 services/receiptFolder.js，封装票据夹接口和 Blob 文件读取。[CONCEPT: 前端] 证据：已封装列表、详情、更新、删除、文件读取和 buildReceiptFile。

  • 新增 ReceiptFolderView.vue，实现列表、状态页签、搜索、一键关联入口和详情切换。[CONCEPT: 列表] 证据：页面已包含未关联/已关联页签、搜索、表格、详情、编辑、预览和删除动作。

  • 新增 receipt-folder-view.css，复用单据中心紧凑企业级视觉，避免继续拉大现有 DocumentsCenterView.vue。[CONCEPT: 列表] 证据：票据夹样式独立落在 assets/styles/views/receipt-folder-view.css，核心文件均未超过 800 行。

  • 在 useNavigation.js 增加 receiptFolder，并放在 documents 后面。[CONCEPT: 前端] 证据：appViews 与 navItems 中 receiptFolder 均紧跟 documents。

  • 在 accessControl.js 增加默认可见权限和默认路由顺序。[CONCEPT: 前端] 证据：已加入 DEFAULT_APP_VIEW_ORDER 与 ALWAYS_VISIBLE_VIEWS。

  • 在 AppShellRouteView.vue 渲染票据夹页面，并让页面可打开报销对话。[CONCEPT: 一键关联票据] 证据：已接入 ReceiptFolderView 并转发 open-assistant 到 openSmartEntry。

阶段五：一键关联流程

  • 实现未关联票据多选弹窗第一步。[CONCEPT: 一键关联票据] 证据：ElDialog 第一阶段使用 ElCheckboxGroup 多选未关联票据。

  • 实现未提交草稿选择和“新建报销单”选择第二步。[CONCEPT: 一键关联票据] 证据：第二阶段读取草稿报销单，并保留 新建报销单 选项。

  • 从票据源文件接口取回 Blob 并构造 File 对象传给报销对话。[CONCEPT: 对话衔接] 证据：buildReceiptFile 从 source_url 读取 Blob 并生成带 receiptId 的 File。

  • 选择已有草稿时，打开对话并带入草稿单号和关联提示。[CONCEPT: 一键关联票据] 证据：选择草稿后以 source: 'detail'、request 和关联 prompt 打开报销对话；附件上传会携带 receipt_id 并回写原票据为已关联。

  • 选择新建报销单时，打开对话并带入基于票据新建的提示。[CONCEPT: 一键关联票据] 证据：新建路径以 source: 'receipt-folder' 携带票据文件和新建 prompt。

阶段六：测试与验证

  • 补充后端票据夹服务和接口测试，超时时间控制在 60s 内。[CONCEPT: 测试方案] 证据：docker exec x-financial-main ... pytest server/tests/test_ocr_endpoints.py server/tests/test_reimbursement_endpoints.py -q 通过，8 passed，耗时 11.41s。

  • 补充前端导航和票据夹视图模型测试。[CONCEPT: 测试方案] 证据：navigation-route-resolution.test.mjs 已覆盖路由顺序，新增 receipt-folder-view.test.mjs 覆盖视图关键能力。

  • 运行前端构建或定向测试。[CONCEPT: 指标与验收] 证据：node web/tests/navigation-route-resolution.test.mjs、node web/tests/receipt-folder-view.test.mjs、npm.cmd run build 均通过。

  • 在 Docker x-financial-main 的 /app 内运行后端定向测试。[CONCEPT: 测试方案] 证据：pytest server/tests/test_ocr_endpoints.py server/tests/test_reimbursement_endpoints.py -q 在容器内通过，8 passed。

  • 手动核对侧边栏位置、列表密度、详情预览和关联弹窗。[CONCEPT: 指标与验收] 证据：内置浏览器打开 http://localhost:5173/app/receiptFolder，侧边栏中“票据夹”位于“单据中心”下方，未关联/已关联页签与空态渲染正常，控制台无相关错误。

阶段七：收口

  • 回看 CONCEPT.md 验收标准，确认已实现项均有证据。[CONCEPT: 指标与验收] 证据：OCR 持久化、列表/详情/预览、侧边栏位置、一键关联入口和文件行数约束均已覆盖。

  • 更新本 TODO 的完成状态和验证记录。[CONCEPT: 测试方案] 证据：本文件已补充完成勾选和验证命令记录。

Reference in New Issue View Git Blame Copy Permalink