【寻迹校园 HarmonyOS NEXT 实战 30】双方确认后才能结案如何联动 Claim 与两条 Report 状态这是“寻迹校园 HarmonyOS NEXT 实战”系列第 30 篇。本文结合HandoffService.confirmCompletion()、ClaimService.complete()、HandoffParty与本地回归测试说明为什么一方确认只能记录进度第二方确认后才能完成 Handoff、Claim并联动拾得与来源丢失两条 Report。上图为原创生成的双确认结案插画不是应用截图。CLAIMANT与KEEPER两个完成信号汇合后业务才进入COMPLETED并继续更新 Claim 和关联 Report。一、为什么一方点击“完成”不能直接结案线下交接存在两个不同事实拾得者确认已经交出物品申请者确认已经收到物品。如果任意一方单击后就把记录永久关闭可能出现“拾得者到了但没有见到对方”“申请者拿到的不是目标物品”“一方误点完成”等争议。双方确认不是形式上的两个按钮而是结案条件的两个独立证据。二、先区分“安排确认”和“完成确认”交接流程有两层确认claimantConfirmed / keeperConfirmed双方同意地点和时间claimantCompleted / keeperCompleted双方确认实际交接已经发生。安排确认只让 Handoff 进入CONFIRMED。只有完成确认同时为真才进入COMPLETED。把这两层混在一个布尔值里会让“同意去图书馆见面”被误解为“已经收到物品”。三、HandoffParty 让调用意图显式化项目用枚举表达确认方exportenumHandoffParty{CLAIMANTCLAIMANT,KEEPERKEEPER}confirmCompletion(claimId, party)根据角色只更新一方标记。相比传入两个任意布尔值枚举更容易审查也能避免调用方一次篡改双方结果。四、只有 CONFIRMED 才允许确认完成Service 首先读取 Handoff 并检查if(!record||record.status!HandoffStatus.CONFIRMED){returnnewOperationResultHandoffRecord(false,双方确认安排后才能确认已交接);}PROPOSED、RESCHEDULED、CANCELLED、EXPIRED和COMPLETED都不能进入这条写入路径。这防止用户绕过地点确认也避免已结束流程被旧页面重新修改。五、第一次完成确认为什么仍保持 CONFIRMED如果只有claimantCompleted或keeperCompleted为真Service 保存记录但不改变 Handoff 状态。返回文案是已记录一方确认等待另一方确认。页面继续展示两行独立进度已确认一方按钮禁用另一方仍可操作。用户能看到流程在前进但不会误以为已经结案。六、第二次确认如何触发 COMPLETEDService 每次更新角色标记后检查if(record.claimantCompletedrecord.keeperCompleted){record.statusHandoffStatus.COMPLETED;}只有两个条件同时成立保存后的 Handoff 才是COMPLETED。随后 Service 调用claimService.complete(claimId)把结果扩散到认领和报告聚合。上图展示第二方确认后的级联路径Handoff 完成只是第一步Claim 和两条关联 Report 全部更新后用户才应看到完整结案结果。七、Claim 完成为什么要求原状态为 ACCEPTEDClaimService.complete()只接受ACCEPTEDClaim。若申请已取消、拒绝、过期或完成调用会失败。这条前置条件保证 Handoff 不能把一个已经失效的认领重新结案。Handoff 和 Claim 的状态必须相互兼容而不是谁最后写入谁覆盖。八、为什么要更新两条 Report认领目标是FOUND拾得记录可选的sourceReportId指向申请者自己的LOST丢失记录。交接完成后拾得报告已经找到失主应为RESOLVED来源丢失报告已经找回物品也应为RESOLVEDClaim 为COMPLETEDHandoff 为COMPLETED。如果只关闭拾得记录失主自己的丢失记录仍会出现在候选列表继续制造无效匹配。九、没有 sourceReportId 时怎样处理用户也可能从拾得详情直接发起认领没有关联自己的丢失记录。此时sourceReportId为空。Service 始终结案目标拾得报告只在来源 ID 非空时更新第二条报告awaitreportService.markResolved(current.reportId);if(current.sourceReportId.length0){awaitreportService.markResolved(current.sourceReportId);}可选关联不能阻止主流程完成也不能用空字符串查询 Repository。十、结案后为什么禁止取消HandoffService.cancel()明确拒绝COMPLETED、CANCELLED和EXPIRED状态。完成代表双方已经确认实际交接并且关联记录可能已经从候选列表移除。普通取消按钮不应反向打开这些实体。如果正式产品需要争议申诉应新增独立申诉流程和审计记录而不是复用“取消安排”把历史状态倒退。十一、ArkUI 页面如何表达单机角色模拟HandoffPage提供两个按钮“模拟拾得者确认已交出”“模拟失主确认已收到”。页面顶部明确说明这是单机比赛演示正式版本需要两个已验证身份分别完成。这段文案非常重要。两个按钮出现在同一台设备上只能证明状态机和 UI 链路不能证明真实双账号签名、远程通知或防抵赖能力。十二、本地测试验证了完整级联回归测试按真实顺序执行创建并接受 Claim使用固定地点发起 Handoff确认交接安排CLAIMANT首次确认完成断言 Handoff 仍为CONFIRMED断言 Claim 仍为ACCEPTEDKEEPER第二次确认完成断言 Handoff 与 Claim 均为COMPLETED断言目标和来源 Report 均为RESOLVED断言完成后取消失败。powershell-ExecutionPolicy Bypass-File.\scripts\test-local-state-machines.ps1这组断言把“按钮点击成功”升级为跨实体结果验证。十三、当前写入顺序存在重要的部分失败窗口现有实现先把 Handoff 保存为COMPLETED再调用ClaimService.complete()。如果后续 Claim 或 Report 更新失败方法会返回失败但 Handoff 可能已经是COMPLETED。用户再次调用confirmCompletion()时又会因为状态不再是CONFIRMED而被拒绝。这是一个真实的一致性风险错误提示存在不代表自动补偿已经完成。十四、为什么不能把 try/catch 写成“事务”try/catch能捕获异常并映射用户文案却不会自动回滚已经成功的 Repository 写入。当前跨实体顺序大致为顺序写入1Handoff →COMPLETED2Claim →COMPLETED3FOUND Report →RESOLVED4可选 LOST Report →RESOLVED任何后一步失败都可能留下前面已提交的数据。准确表述应是“顺序协调并返回部分失败”而不是“事务性结案”。十五、正式版怎样实现原子或可补偿结案服务端可以选择在同一事务中更新 Handoff、Claim 和两条 Report为每条记录增加版本号阻止并发旧写使用结案命令 ID 保证重复请求幂等写入 outbox 事件再由可靠消费者补齐派生状态对部分失败记录建立补偿任务管理端显示不一致告警保留双方确认时间和身份审计申诉流程不直接回滚历史完成状态。客户端只应展示服务端确认后的权威结果。十六、结案后的页面刷新应来自权威数据完成后onDataChanged()增加共享dataRevision首页、消息和“我的发布”重新读取 Service 数据。页面不应该手工把多个卡片改成“已完成”。从 Repository 重新聚合能避免某一页面漏改来源 Report也便于进程重启后恢复一致视图。十七、消息文案要区分三个阶段用户至少会看到三种不同结果一方已确认等待另一方双方已确认所有实体结案成功Handoff 已完成但后续联动失败需要重新进入检查。把它们全部写成“操作成功”会掩盖最关键的一致性问题。十八、真机与多用户验收仍缺什么当前本地测试和单机页面可以证明主要业务规则但正式验收还需要两个真实账号分别确认服务端拒绝同一账号代替双方并发双击与重试保持幂等一方离线后恢复推送和消息状态一致进程重启后确认标记不丢失部分失败可以自动补偿审计日志不泄露私密核验答案申诉与争议不会静默篡改历史记录。这些均不能由当前同设备角色模拟外推。工程复盘多实体结案先列出最小一致性清单一次完整结案至少要回答五个问题Handoff 是否已经由双方确认完成Claim 是否从允许的状态进入COMPLETED目标拾得 Report 是否进入RESOLVED存在来源丢失 Report 时它是否同步结束重复调用是否仍返回同一个业务结果。把这五项写成清单比在页面成功回调里零散修改对象更容易审查。顺序写入实现还要为每一步指定失败后的动作。第一方确认只改变 Handoff 进度不触发其余实体第二方确认触发级联时任何部分失败都应保留操作 ID 和已完成步骤下一次重试从权威状态继续而不是从头把终态记录倒退。当前单机 Repository 没有跨表事务所以文章只报告本地顺序写入和测试覆盖并把原子性明确列为未实现边界。读取侧也需要一致性保护。列表、详情和消息页应在结案后统一刷新 Service 快照如果发现 Handoff 已完成但 Report 仍可认领应显示可恢复错误并触发受控补偿不能让两个页面长期展示相反结论。日志只记录实体 ID、状态迁移和补偿结果私密核验答案不进入结案审计。最终验收应覆盖顺序和重复拾得者先确认、失主后确认反向顺序两方重复点击第一方确认后重启应用第二方确认时其中一条关联报告缺失。每个案例都要同时断言四类实体的权威状态和用户可见文案才能证明“双方确认”不是一个局部按钮效果。十九、本文小结双方确认结案的核心是把“安排已同意”“拾得者已交出”“失主已收到”拆成独立事实。第一方完成确认只记录进度第二方确认后才触发 Handoff、Claim 和关联 Report 的联动结案。“寻迹校园”当前已经用生产 Service 和本地回退测试证明主要级联与取消限制但跨 Repository 原子事务、真实双账号身份、服务端审计和部分失败补偿仍是正式版本必须解决的工程问题。系列导航第 30 篇 / 共 50 篇。上一篇《一次改期与 24 小时过期》下一篇《举报去重与治理状态机》。