X-Financial/document/development/附件上传风险前置复核/CONCEPT.md

附件上传风险前置复核

功能一句话

报销附件上传并完成 OCR 识别后立即执行完整风险复核，提交审批时只做轻量最终校验、预算占用和流程流转。

背景与问题

当前报销单提交阶段会同步执行较重的风险检查，包括附件风险汇总、差旅规则、场景规则、规则中心风险、历史行为统计和风险观测写入。用户在点击提交后会等待较长时间，容易误认为页面卡住。

风险的主要依据来自已上传票据、OCR 识别结果、费用明细、关联申请单和员工历史行为。这些数据在附件上传完成后已经基本具备，因此完整风险复核应前移到上传完成阶段。

目标与非目标

目标：

• 附件上传成功后自动刷新费用明细、附件风险、差旅/场景/规则中心风险和 AI 预审标识。
• 风险复核结果写回 claim.risk_flags_json，并持久化规则中心风险观测。
• 提交阶段不再重复跑完整 _run_ai_submission_review()。
• 提交阶段只保留草稿完整性校验、预算占用、未处理阻断风险判断、状态流转、审计日志和助手会话清理。

非目标：

• 不新增业务字段。
• 不改变现有风险规则语义。
• 不把提交改成真正的后端异步任务队列。

用户与场景

• 报销申请人：上传票据后立即看到风险建议和需补充说明，不必等到提交时才发现问题。
• 直属领导和财务人员：收到单据时可看到提交前已生成的风险提示和用户处理结果。
• 系统管理员：风险观测仍可进入后台统计。

功能能力

上传完成后：

• 根据 OCR 结果回填费用明细类型、日期、金额、事由等已有字段。
• 刷新附件级 attachment_analysis 风险。
• 执行报销级风险复核，并生成 ai_pre_review 状态。
• 对规则中心命中的风险写入 risk_observations。

提交审批时：

• 如果存在高风险且用户未处理，继续阻止提交或要求说明/按职级测算。
• 如果风险已处理，只做预算和流程流转。
• 不再重复生成一套提交阶段风险。

方案设计

后端：

• 在 ExpenseClaimService.upload_claim_item_attachment() 中，OCR、附件分析和 _sync_claim_from_items() 完成后，调用上传后风险复核 helper。
• 新增 helper 复用现有 _run_ai_submission_review() 与 _replace_ai_pre_review_flag()，但保持单据状态为草稿。
• 提交阶段读取既有风险结果，只做最终阻断风险判断，不重复调用 _run_ai_submission_review()。

前端：

• 继续使用当前附件识别中的状态条。
• 上传完成后通过接口返回的 claim_risk_flags 更新 AI 建议区和风险标识。
• 提交时只显示轻量后台提交流程提示。

算法与公式

当前功能不涉及新的显式数学公式。风险评分和风险等级沿用现有规则中心、附件分析、差旅政策和风险观测逻辑。

测试方案

• 后端单元测试：附件上传后写入 ai_pre_review 和 submission_review 风险。
• 后端单元测试：提交阶段不再调用完整 _run_ai_submission_review()。
• 后端单元测试：上传后规则中心风险可写入 risk_observations。
• 前端静态回归：提交确认仍为后台提交，不恢复阻塞弹窗。
• 构建验证：npm.cmd --prefix web run build。

指标与验收

• 上传附件后，接口响应的 claim_risk_flags 包含最新复核结果。
• 提交接口耗时不再包含完整风险复核耗时。
• 提交后审批人仍能看到已前置生成的风险提示。
• 后端和前端相关回归测试通过。

风险与开放问题

• 如果用户上传后又修改费用明细，现有 update_claim_item() 需要继续刷新附件风险和报销级风险。
• 如果用户没有上传附件直接提交，提交阶段仍需要保留兜底风险复核或阻断提示。
• 未来可进一步把上传后复核做成真正后台任务，但本次先保持同步接口返回最新风险结果。