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，后续真实支付/发放仍待继续。

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。