Codex
43 lines
4.0 KiB
Markdown
43 lines
4.0 KiB
Markdown
# 2026-08-10 M08-C 管理员/员工小程序 API
|
|
|
|
| 方法 | 路径 | 权限 | 结果 |
|
|
|---|---|---|---|
|
|
| GET | `/app-api/management/stores` | `store.operation.read/write`、`tenant.manage` 或平台管理员 | 返回当前账号授权范围内门店。 |
|
|
| GET | `/app-api/management/stores/:storeId/rooms` | 读权限且门店在授权范围 | 返回包含停用房间在内的完整配置/运营房态。 |
|
|
| PATCH | `/app-api/management/rooms/:id/status` | 写权限且门店在授权范围 | 调整配置状态或运营状态并写审计；STAFF 只读账号返回 403。 |
|
|
|
|
房态请求体必须包含 `storeId`、非空 `reason`，并至少包含 `configurationStatus` 或 `operationalStatus` 之一。接口继续使用统一 Bearer 会话与服务端门店范围，不信任前端隐藏按钮。
|
|
|
|
## 订单处置与代下单增量
|
|
|
|
| 方法 | 路径 | 权限 | 结果 |
|
|
|---|---|---|---|
|
|
| GET | `/app-api/orders?storeId=:storeId&status=:status` | 本人订单或 `store.operation.read` 授权门店 | `storeId` 与状态均为可选服务端筛选，继续叠加租户和订单可见范围。 |
|
|
| POST | `/app-api/management/orders/:orderId/actions` | `store.operation.write`、`tenant.manage` 或平台管理员，且订单门店在范围内 | 复用订单状态机执行受控业务动作并写历史/审计。 |
|
|
| POST | `/app-api/management/orders/:orderId/renew`、`change-room`、`adjust-time`、`note` | 同上 | 复用既有管理员调整仓储，拒绝客户端金额。 |
|
|
| POST | `/app-api/management/orders/reserve-on-behalf` | 同上 | 为同租户有效会员预占授权门店房间，服务端计算价格，状态历史与审计记录真实管理员。 |
|
|
|
|
代下单请求体包含 `userId`、`roomId`、`startAt`、`endAt`、`pricingMode`；跨租户或失效用户返回 404，越权门店返回 403，只读 STAFF 返回 403。
|
|
|
|
## 会员检索与员工概况增量
|
|
|
|
| 方法 | 路径 | 权限 | 结果 |
|
|
|---|---|---|---|
|
|
| GET | `/app-api/management/members` | `user.read`，并叠加租户与授权门店范围 | 按昵称/手机号搜索会员；门店范围以该门店钱包账户或历史 OWNER 订单为准，返回脱敏手机号和聚合概况。 |
|
|
| GET | `/app-api/management/members/:id` | 同上 | 返回会员钱包、订单、优惠券、套餐和最近钱包流水；越权会员不可见。 |
|
|
| GET | `/app-api/management/staff` | `user.read`，并叠加租户与授权门店范围 | 强制仅查询 `userType=STAFF`，返回角色、门店范围、状态、备注及脱敏手机号/最近登录 IP。 |
|
|
|
|
管理员代下单页改为调用会员检索接口选择目标会员，不再要求手工输入全局用户 ID。列表分页参数继续由服务端夹取为安全整数；MySQL 查询不再绑定 `LIMIT/OFFSET` 占位符，以兼容当前 MySQL 8.4 驱动组合。
|
|
|
|
## 保洁与设备运营增量
|
|
|
|
| 方法 | 路径 | 权限 | 结果 |
|
|
|---|---|---|---|
|
|
| GET | `/app-api/management/cleaning/tasks` | `cleaning.task.read`，并叠加租户与授权门店范围 | 按门店、状态和保洁员查询任务。 |
|
|
| GET | `/app-api/management/cleaning/statistics` | 同上 | 返回任务汇总、状态、门店、结算、人员和趋势统计。 |
|
|
| POST | `/app-api/management/cleaning/tasks/:taskId/complete`、`reject`、`exempt` | `cleaning.task.write`，任务门店在授权范围 | 复用既有验收、驳回补做和免清洁状态机/事件记录。 |
|
|
| GET | `/app-api/management/devices`、`device-topology` | `device.read`，并叠加租户与授权门店范围 | 返回设备在线状态、信号、固件、能力、最近心跳、告警、维护和绑定拓扑。 |
|
|
| POST | `/app-api/management/device-control/*` | `device.write`，设备门店在授权范围 | 复用既有控制箱、Sub-1G 和智能插座命令服务；小程序当前接入临时开门、全屋电控和插座开关。 |
|
|
|
|
管理端设备写操作在命令创建前写入 `DEVICE_COMMAND_REQUESTED` 审计，记录实际账号类型/ID、traceId、门店、房间、设备、命令类型和可选订单；设备离线、未绑定或跨店仍由服务端拒绝。
|