Codex
105 lines
4.7 KiB
Markdown
105 lines
4.7 KiB
Markdown
# 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`，后续真实支付/发放仍待继续。
|