客户端小程序 — 淋浴服务

上级文档：客户端小程序

---

概述

对应主文档 §8.7

淋浴服务允许用户在店内启动淋浴设备。淋浴权益通过服务端下发，支持按用户级别/会员等级配置不同时长，运营可在管理后台灵活调整默认规则。淋浴控制可通过个人中心或线下扫码触发。

页面路由

路由	页面	说明
/pages/shower/index	淋浴控制	权益展示 + 启动 + 倒计时

功能入口

入口	触发方式	说明
个人中心	菜单列表「淋浴控制」	始终可见
首页快捷入口	仅在门店内时显示	基于最近进店记录判断
线下扫码	淋浴间张贴二维码	登录后直接跳转淋浴页

淋浴权益体系

架构设计原则：权益时长由服务端下发，前端不做任何时长计算。用户无个人权益配置时，按门店默认配置执行。

权益来源优先级

服务端 GET /api/v1/shower/allowance 返回当前用户在指定门店的可用淋浴权益：

优先级从高到低：
1. 用户级权益配置（如 VIP 用户 30min/次，续费老用户 25min/次）
2. 门店级默认配置（如普通用户 20min/次）
3. 全局默认配置（兜底值）

权益方案

用户类型	每次时长	获取方式	说明
普通用户	20 分钟	每次刷脸进店自动赠送 1 次	门店默认配置，运营可调
VIP 用户	30 分钟	会员等级权益	服务端按等级下发
续费老用户	25 分钟	连续续费奖励	服务端配置

运营可配置项（管理后台）

配置项	说明	默认值
门店默认时长	无个人权益时的每次淋浴时长	20 分钟
每日最大次数	每人每天可使用的淋浴次数	1 次
进店自动赠送	刷脸进店是否自动发放淋浴次数	开启
赠送次数	每次进店赠送的淋浴次数	1 次
VIP 时长加成	VIP 等级对应的额外时长	按等级配置
超时是否自动关闭	倒计时归零后是否自动关闭水阀	开启

淋浴主页面要素

• 返回按钮 + 「淋浴控制」标题
• 当前门店名称
• 淋浴间状态（空闲/使用中/离线）
• 可用淋浴次数 + 每次可用时长（从服务端获取）
• 「启动淋浴」按钮

淋浴状态展示

展示文案	条件	按钮状态
「启动淋浴」	有可用次数 + 设备在线	可用
「今日已用完」	每日次数已用完	置灰
「请先进入健身房」	未进入过门店	置灰 + 引导
「设备不可用」	淋浴间离线或故障	置灰
「暂无会员权益」	无有效会员套餐	置灰 + 购买引导

倒计时页面要素

• 返回按钮 + 「淋浴中」标题
• 大字号倒计时显示（MM:SS）
• 进度条（剩余时长占比）
• 「提前结束」按钮
• 底部显示门店名称 + 淋浴间编号

淋浴操作流程

进入淋浴页
    │
    ├─ GET /api/v1/shower/allowance?storeId=xxx
    │   返回：{ duration, remainingToday, showerRoomStatus }
    │
    ├─ 无可用次数 → 展示对应提示
    │
    ├─ 设备离线 → 展示不可用提示
    │
    └─ 可启动 → 点击「启动淋浴」
         │
         ├─ POST /api/v1/shower/start
         │
         ├─ 成功 → 倒计时页面
         │         │
         │         ├─ 倒计时结束 → 自动发送 POST /api/v1/shower/stop
         │         ├─ 用户点击「提前结束」 → POST /api/v1/shower/stop
         │         └─ 页面切后台 → 服务端倒计时继续执行
         │
         └─ 失败 → 展示错误原因

异常处理

异常	处理
设备离线	「淋浴设备暂时不可用，请联系工作人员」
无权益	「暂无可用淋浴次数」+ 引导进入健身房
指令成功但设备未响应	「淋浴启动异常，请联系客服」
网络中断	重新拉取状态，服务端倒计时继续执行
倒计时页面被关闭	服务端倒计时继续，水阀按时自动关闭
重复启动	服务端校验，返回「当前已有进行中的淋浴」

接口

GET /api/v1/shower/allowance?storeId=xxx
  Auth: JWT
  Response: {
    duration: number,          // 本次可用时长（秒）
    remainingToday: number,    // 今日剩余可用次数
    maxPerDay: number,         // 每日最大次数
    showerRoomStatus: 'idle' | 'in_use' | 'offline'
  }

POST /api/v1/shower/start
  Auth: JWT
  Body: { storeId: string }
  Response: {
    success: boolean,
    endTime: string,           // ISO 时间，用于倒计时
    duration: number           // 实际分配时长（秒）
  }

POST /api/v1/shower/stop
  Auth: JWT
  Body: { storeId: string }
  Response: { success: boolean }

GET /api/v1/shower/status?storeId=xxx
  Auth: JWT
  Response: {
    active: boolean,
    remainingSeconds: number,
    endTime: string,
    showerRoomStatus: string
  }

扩展预留

• 按时长计费：未来可支持按实际使用时长扣费（非赠送权益模式）
• 购买额外时长：用户可付费购买额外淋浴时长
• 预约淋浴：高峰期可预约淋浴间时段
• 多人同时使用：门店可配置淋浴间数量，支持排队