Codex
4.0 KiB
4.0 KiB
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、门店、房间、设备、命令类型和可选订单；设备离线、未绑定或跨店仍由服务端拒绝。