qipai/docs/api-changelog/2026-06-25-M08-B-cleaning.md

2026-06-25 M08-B 保洁端 API

App API

• GET /app-api/cleaning/tasks/hall

  • 登录：必需。
  • 权限：cleaning.task.read、tenant.manage 或 PLATFORM_ADMIN。
  • 查询：page、pageSize、status；默认查询 WAITING。
  • 说明：按保洁员门店范围返回任务大厅。

• GET /app-api/cleaning/tasks/mine

  • 登录：必需。
  • 权限：cleaning.task.read、tenant.manage 或 PLATFORM_ADMIN。
  • 查询：page、pageSize、status。
  • 说明：返回当前保洁员已领取任务。

• POST /app-api/cleaning/tasks/:taskId/claim

  • 登录：必需。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN。
  • 说明：仅 WAITING 且未被领取的任务可接单。

• POST /app-api/cleaning/tasks/:taskId/start

  • 登录：必需。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN。
  • 说明：当前保洁员已领取的 CLAIMED 任务可开始。

• POST /app-api/cleaning/tasks/:taskId/photos

  • 登录：必需。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN。
  • Content-Type：application/octet-stream。
  • Headers：x-file-name、x-image-content-type。
  • 说明：当前保洁员本人 STARTED 或 REJECTED 任务可上传验收照片；服务端压缩存储后返回 publicUrl。

• POST /app-api/cleaning/tasks/:taskId/submit

  • 登录：必需。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN。
  • Body：photoUrls: string[]，note?: string。
  • 说明：当前保洁员本人 STARTED 或 REJECTED 任务可提交验收；photoUrls 至少 1 张，最多 9 张。

• POST /app-api/cleaning/tasks/:taskId/rework

  • 登录：必需。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN。
  • 说明：当前保洁员本人 REJECTED 任务可重新进入 STARTED 补做状态。

• GET /app-api/cleaning/stats

  • 登录：必需。
  • 权限：cleaning.task.read、tenant.manage 或 PLATFORM_ADMIN。
  • 说明：返回当前保洁员任务状态计数和待结算金额。

Admin API

• GET /admin-api/cleaning/tasks

  • 登录：必需。
  • 权限：cleaning.task.read、tenant.manage 或 PLATFORM_ADMIN。
  • 查询：page、pageSize、status。
  • 说明：按管理员门店范围查询保洁任务。

• POST /admin-api/cleaning/tasks/:taskId/assign

  • 登录：必需。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN。
  • Body：cleanerUserId: string，note?: string。
  • 说明：仅可将任务指派给具备 CLEANER 角色且拥有该门店范围的有效用户。

• POST /admin-api/cleaning/tasks/:taskId/complete

  • 登录：必需。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN。
  • Body：note?: string。
  • 说明：将 SUBMITTED 任务验收为 COMPLETED，并进入待结算候选。

• POST /admin-api/cleaning/tasks/:taskId/reject

  • 登录：必需。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN。
  • Body：reason: string。
  • 说明：将 SUBMITTED 任务驳回为 REJECTED，保洁端可查看原因并补做。

• GET /admin-api/cleaning/settlement-candidates

  • 登录：必需。
  • 权限：cleaning.task.read、tenant.manage 或 PLATFORM_ADMIN。
  • 查询：page、pageSize。
  • 说明：返回 COMPLETED 且 settled_at IS NULL 的待结算保洁任务。

• POST /admin-api/cleaning/reclaim-timeouts

  • 登录：必需。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN。
  • Body：olderThanMinutes?: number，limit?: number。
  • 说明：将超时停留在 CLAIMED 或 STARTED 的任务回收到 WAITING，并清空保洁员领取状态。

• GET /admin-api/cleaning/settlements

  • 登录：必需。
  • 权限：cleaning.task.read、tenant.manage 或 PLATFORM_ADMIN。
  • 查询：page、pageSize、status。
  • 说明：查询保洁结算单，状态支持 DRAFT、CONFIRMED、PAID、CANCELLED。

• POST /admin-api/cleaning/settlements

  • 登录：必需。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN。
  • Body：cleanerUserId: string，storeId?: string，note?: string。
  • 说明：将指定保洁员已完成未结算任务生成 DRAFT 结算单，任务同步转为 SETTLED 并写入结算明细。

• POST /admin-api/cleaning/settlements/:settlementId/confirm

  • 登录：必需。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN。
  • Body：note?: string。
  • 说明：将 DRAFT 结算单确认成 CONFIRMED，进入发放待处理状态。

• POST /admin-api/cleaning/settlements/:settlementId/paid

  • 登录：必需。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN。
  • Body：payoutChannel: string，payoutReference: string，note?: string。
  • 说明：将 CONFIRMED 结算单标记为 PAID，记录发放人、发放时间、渠道和外部流水号，清空旧失败原因。

• POST /admin-api/cleaning/settlements/:settlementId/payout-failure

  • 登录：必需。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN。
  • Body：error: string，payoutChannel?: string，payoutReference?: string，note?: string。
  • 说明：记录 CONFIRMED 结算单发放失败原因，保留可重试状态。

2026-06-26 多保洁员协作增量

• GET /admin-api/cleaning/tasks/:taskId/members
  • 登录：必须。
  • 权限：cleaning.task.read、tenant.manage 或 PLATFORM_ADMIN。
  • 说明：返回任务有效保洁成员，包含 LEAD 负责人和 ASSIST 协作者、成员分账金额与结算时间。
• POST /admin-api/cleaning/tasks/:taskId/members
  • 登录：必须。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN。
  • Body：cleanerUserId: string，rewardCents: number，note?: string。
  • 说明：添加或更新协作者分账金额；协作者必须为有效 CLEANER 且拥有任务门店范围；协作者金额总和不能超过任务奖励。
• POST /admin-api/cleaning/tasks/:taskId/members/:cleanerUserId/remove
  • 登录：必须。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN。
  • Body：note?: string。
  • 说明：移除未结算协作者并把剩余奖励回算到负责人；负责人不可通过该接口移除。
• POST /admin-api/cleaning/settlements
  • 追加说明：多人协作任务按 qipai_cleaning_task_members.reward_cents 分别为每个保洁员生成结算明细；所有有效成员均完成结算后任务才整体转为 SETTLED。

2026-06-27 微信转账适配增量

• POST /admin-api/cleaning/settlements/:settlementId/wechat-transfer
  • 登录：必须。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN；服务层继续校验 cleaning.settlement.write。
  • Body：mode?: "API" | "MOCK"，note?: string。
  • 说明：对 CONFIRMED 保洁结算单发起微信商家转账。API 模式会校验门店/全局微信收款账户、商户凭据、保洁员微信 openid 和转账场景配置；MOCK 仅非生产环境可用。
  • 返回：成功转账直接返回 PAID 结算单；微信返回 FAIL 时记录失败原因；微信返回待确认或处理中状态时保留 CONFIRMED，并返回 payoutState、payoutReference 和 payoutPackageInfo。

2026-06-29 微信转账回调与轮询增量

• POST /admin-api/cleaning/settlements/:settlementId/wechat-transfer/sync

  • 登录：必须。
  • 权限：cleaning.task.write、tenant.manage 或 PLATFORM_ADMIN；服务层继续校验 cleaning.settlement.write。
  • Body：note?: string。
  • 说明：按结算单商户转账单号主动查询微信商家转账状态；SUCCESS 自动标记 PAID，FAIL 记录失败原因，其它中间态保留 CONFIRMED 并更新 payout_state。

• POST /app-api/cleaning/wechat-transfer/notify

  • 登录：不需要，依赖微信支付通知签名验证。
  • Headers：wechatpay-timestamp、wechatpay-nonce、wechatpay-serial、wechatpay-signature。
  • Body：微信支付 v3 加密通知原文。
  • 说明：服务端用原始 body 验签解密，校验商户号后按 out_bill_no 或 transfer_bill_no 定位保洁结算单，并写回成功、失败或中间态。

2026-06-30 后台协作与结算详情增量

• GET /admin-api/cleaning/settlements/:settlementId
  • 登录：必须。
  • 权限：cleaning.settlement.read、tenant.manage 或 PLATFORM_ADMIN。
  • 说明：按租户和门店数据范围读取结算单详情，返回结算单主信息与固化结算明细。
  • 返回：settlement 与 items；明细包含任务号、订单号、门店、房间、保洁员、成员分账金额和完成时间。

2026-06-30 统计明细增量

• GET /admin-api/cleaning/statistics
  • 登录：必须。
  • 权限：cleaning.task.read 与 cleaning.settlement.read，或 tenant.manage / PLATFORM_ADMIN。
  • Query：from?: string，to?: string，storeId?: string。
  • 说明：按登录管理员租户与门店范围统计保洁运营状态，支持日期和门店筛选。
  • 返回：summary、byStatus、byStore、settlements、members、trend，覆盖任务状态、门店明细、结算口径、成员分账待结算金额和每日趋势。

2026-06-30 保洁员资料管理增量

• GET /admin-api/users
  • 追加 Query：role?: "CLEANER" | "STAFF" | "STORE_ADMIN" | "TENANT_ADMIN"。
  • 说明：用于后台保洁员资料管理筛选 CLEANER 角色；权限、租户和门店范围继续沿用员工管理接口。
• POST /admin-api/staff
  • 复用说明：后台创建保洁员时传入 roles: ["CLEANER"] 和门店范围。
• PATCH /admin-api/users/:id
  • 复用说明：后台编辑保洁员姓名、备注、门店范围和启停状态。
• POST /admin-api/users/:id/reset-sessions
  • 复用说明：后台重置保洁员会话，使旧登录态立即失效。

2026-06-30 统计趋势增量

• GET /admin-api/cleaning/statistics
  • 追加返回：trend[]。
  • 说明：在既有日期、门店和管理员门店范围过滤基础上，按任务创建日期返回每日任务数、待验收数、完成数、驳回数、奖励金额和已发放金额，供后台运营趋势展示使用。

2026-06-30 保洁员资料细节增量

• GET /admin-api/users
  • 追加返回：avatarUrl、wechatMiniappBound。
  • 说明：后台保洁员资料列表可展示头像资料来源和微信小程序 openid 绑定状态，用于判断微信转账前置资料是否齐全。
• PATCH /admin-api/users/:id
  • 追加说明：后台保洁员编辑弹窗已接入手机号更新，继续沿用原有员工管理权限、租户隔离、门店范围和角色分配校验。

2026-06-30 统计按保洁员筛选增量

• GET /admin-api/cleaning/statistics
  • 追加 Query：cleanerUserId?: string。
  • 说明：管理统计支持按保洁员筛选；任务口径覆盖负责人和有效协作者，结算口径按结算单保洁员过滤，每日趋势中的已发放金额同步应用该筛选。

2026-06-30 待结算候选预览增量

• GET /admin-api/cleaning/settlement-candidates
  • 追加 Query：storeId?: string，cleanerUserId?: string。
  • 说明：后台可按门店和保洁员预览待生成结算单的 COMPLETED 且未结算任务；保洁员口径覆盖负责人和未移除、未结算的协作者。

2026-06-30 任务事件流水增量

• GET /admin-api/cleaning/tasks/:taskId/events
  • 登录：必须。
  • 权限：cleaning.task.read、tenant.manage 或 PLATFORM_ADMIN。
  • 说明：按租户和管理员门店范围返回保洁任务最近 50 条事件流水，包含动作、from/to 状态、操作人、traceId、备注和创建时间。