qipai/docs/api-changelog/2026-08-11-M09-C-cleaning-settlement-integrity.md

2026-08-11 M09-C 保洁统计与结算 API

新增管理接口

• GET /admin-api/cleaning/settlements/export
  • 与结算分页列表共用状态、转账状态、门店、保洁员筛选和稳定排序。
  • 最多返回 5000 条，并返回 total、exported、truncated，由客户端明确提示截断。
• POST /admin-api/cleaning/settlements/:settlementId/cancel
  • 请求体必填 reason。
  • 只允许取消 DRAFT / CONFIRMED 且转账未进入 PROCESSING、WAIT_USER_CONFIRM、SUCCESS 的结算单。
  • 原单不删除；返回 CANCELLED 结算单并保留冲正与事件审计。

既有接口收口

• GET /admin-api/cleaning/settlements/:settlementId 新增：
  • 结算单 cancelledBy、cancelledAt、payoutRequestNo。
  • 明细 reversedAt。
  • reversals[] 负向冲正和 events[] 状态历史，事件包含 actorType、actorId、traceId。
• POST /admin-api/cleaning/settlements/:settlementId/paid 明确为人工付款入口：金额始终读取结算单，客户端只传 payoutChannel、必填 payoutReference 和可选 note；仅允许未发起或已明确失败的 CONFIRMED 结算。
• 微信转账在调用供应商前固化请求号并进入处理中；网络异常不再写成失败，成功通知重放返回幂等成功。
• 结算列表与导出只返回调用人租户/门店范围内数据；微信通知使用已验签商户号关联收款账户后再匹配请求号或外部流水。
• 保洁员与管理端统计中的待结算金额覆盖所有尚未 PAID 的有效成员份额，已结算金额只累计已付款份额。

领域口径

多人协作任务按收款成员分别付款，因此唯一键定义为“任务 × 收款成员份额”，而不是把多个收款人强行并入一张单收款人记录。同一份额不能同时进入两张有效结算单；任务只有在全部有效奖励份额付款后才进入 SETTLED。