yunhaifinance/frontend/.codebuddy/PROGRESS.md

表单数据保护方案 - 进度跟踪

最后更新: 2026-04-20

当前状态: 试点改造完成，等待用户确认效果

已完成

• 项目代码扫描
• 技术栈分析 (React 18 + Ant Design 5 + Zustand + react-router-dom 6)
• 表单组件清单整理 (13个Modal表单 + 1个页面级表单)
• 输出详细改造方案
• 用户确认方案（所有决策点已确认）
• 创建 useFormDraft Hook (src/hooks/useFormDraft.ts)
• 创建 useFormGuard Hook (src/hooks/useFormGuard.ts)
• 试点改造: ReimbursementsPage (Modal表单，含detailItems外部状态)
• 试点改造: BudgetProjectCreate (页面级表单，含路由离开拦截)

待完成

• 用户确认试点效果
• 推广至全项目 (11个剩余组件)

已确认的决策

决策项	决定	理由
第三方库 vs 自定义Hook	自定义Hook	项目表单模式统一(Ant Design Form)，第三方库兼容性不确定
sessionStorage vs localStorage	sessionStorage	关闭标签自动清理，避免脏数据残留
草稿恢复时机	弹确认框让用户选择	给用户选择权
草稿过期策略	savedAt超过24小时自动忽略	避免过期脏数据
Modal关闭拦截	是，但只拦截有改动的情况	防止误关，但不干扰正常操作
试点组件	ReimbursementsPage + BudgetProjectCreate	最复杂Modal表单 + 唯一页面级表单

新增文件

• src/hooks/useFormDraft.ts - 表单草稿自动保存/恢复/清理
• src/hooks/useFormGuard.ts - 离开拦截(浏览器刷新/关闭 + 路由跳转 + 移动端切后台)

改造要点

ReimbursementsPage (Modal表单)

• Modal关闭时保存草稿而非丢弃
• 重新打开时检测草稿，弹确认框让用户选择恢复或重新填写
• detailItems外部状态通过extraData同步保存
• 表单提交成功后清理草稿
• maskClosable=false 防止误点遮罩关闭
• onValuesChanged 监听表单变化自动保存

BudgetProjectCreate (页面级表单)

• 页面加载时检测草稿，弹确认框让用户选择恢复
• useBlocker 拦截路由跳转，弹确认框
• beforeunload 拦截浏览器刷新/关闭
• visibilitychange + pagehide 处理移动端切后台
• 附件变化时同步保存草稿
• 取消按钮有改动时弹确认

剩余待改造组件 (11个)

1. AdvancesPage.tsx - 预支申请(Modal, 附件)
2. PaymentRequestsPage.tsx - 付款申请(Modal, 收款单位联动, 附件)
3. SuppliersPage.tsx - 供应商(Modal, 联系人/收款信息)
4. SubcontractorsPage.tsx - 分包商(Modal, 联系人/收款信息)
5. CustomersPage.tsx - 客户(Modal, 联系人/收款信息)
6. LogisticsCompaniesPage.tsx - 物流公司(Modal)
7. ProcurementPage.tsx - 采购(Modal)
8. PurchaseRequestsPage.tsx - 采购申请(Modal)
9. PurchaseOrdersPage.tsx - 采购订单(Modal, 商品明细)
10. ContractCreateModal.tsx - 快速签约(Modal)
11. QuotationCreateModal.tsx - 新增报价版本(Modal)
12. ProfilePage.tsx - 个人资料(页面表单+密码修改Modal)