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` 且未结算任务；保洁员口径覆盖负责人和未移除、未结算的协作者。