# 员工端 H5 页面规划

## 产品定位

面向酒店/商户员工的移动端工作台，核心解决三件事：

- 员工通过手机号验证码登录。
- 员工查看订单，并对可使用订单进行核销。
- 员工发布和查看运营事件。

第一版优先保证业务闭环，不做复杂后台管理能力。

## 页面地图

```text
/login
  手机验证码登录

/
  /home
    工作台

  /orders
    订单列表

  /orders/:id
    订单详情
    └─ 进入核销确认

  /verify
    核销入口

  /verify/confirm
    核销确认

  /verify/result
    核销结果

  /events
    事件列表

  /events/create
    发布事件

  /mine
    我的
```

## 底部导航

| Tab | 路由 | 说明 |
|---|---|---|
| 工作台 | `/home` | 展示关键数据和快捷入口 |
| 订单 | `/orders` | 查询订单、进入详情 |
| 核销 | `/verify` | 手机摄像头扫码核销 |
| 事件 | `/events` | 查看事件列表 |
| 我的 | `/mine` | 当前账号、登录状态、退出登录 |

## 核心流程

### 登录流程

```text
输入手机号
-> 获取验证码
-> 输入验证码
-> 调用 OAuth2 手机号登录
-> 保存 access_token
-> 调用组织关系接口
-> 进入工作台
```

接口：

| 动作 | 接口 |
|---|---|
| 发送验证码 | `GET /admin/platformUser/sendMobileCode/{phone}` |
| 手机号登录 | `POST /auth/oauth2/token` |
| 登录后绑定并获取组织关系 | `POST /hotelStaff/organizationMember/bindUserInfoAndGetUserMemberInfoByPhone` |

登录参数要点：

- `grant_type=mobile`
- `mobile=手机号`
- `code=验证码`
- `scope=server`
- `clientConfigId` 需要和发送验证码时保持一致

### 订单核销流程

```text
订单列表
-> 订单详情
-> 点击立即核销
-> 核销确认
-> 调用核销接口
-> 核销结果
```

扫码入口支持：

```text
核销入口
-> 点击进行扫码
-> 解析二维码内容
-> 查询订单详情
-> 核销确认
-> 核销结果
```

接口：

| 页面/动作 | 接口 |
|---|---|
| 订单列表 | `POST /hotelStaff/order/commodityOrderList` |
| 订单详情 | `POST /hotelStaff/order/userOrderDetail` |
| 确认核销 | `POST /hotelStaff/order/writeOff` |

当前二维码内容规则是 `orderId&packageName`，其中 `packageName` 是套餐名称。前端也兼容只有 `orderId` 的二维码内容。

扫码内容带 `packageName` 时，核销确认页只能核销该套餐商品；扫码内容只有 `orderId` 时，核销确认页按订单详情展示可选套餐。

### 事件流程

```text
事件列表
-> 发布事件
-> 填写事件信息
-> 上传图片
-> 发布
-> 回到事件列表
```

接口：

| 页面/动作 | 接口 |
|---|---|
| 事件列表 | `POST /hotelStaff/event/eventList` |
| 创建事件 | `POST /hotelStaff/event/createEvent` |
| 图片上传 | `POST /hotelBiz/hotBizCommon/upload` |

## 页面明细

### `/login` 手机验证码登录

目标：让员工用手机号进入系统。

展示内容：

- 手机号输入框
- 验证码输入框
- 获取验证码按钮
- 登录按钮

状态：

- 手机号格式错误
- 验证码倒计时
- 登录中
- 登录失败

### `/home` 工作台

目标：提供员工进入高频操作的首页。

展示内容：

- 当前日期
- 当前账号
- 待使用订单数
- 待确认订单数
- 生效事件数
- 今日订单数
- 快捷入口：扫码核销、订单列表、发布事件、事件列表
- 近期订单
- 近期事件

主要操作：

- 去核销
- 查看订单
- 发布事件
- 查看事件

### `/orders` 订单列表

目标：让员工快速查找订单。

展示内容：

- 搜索框：手机号
- 状态筛选：全部、待使用、待确认、退款中、已完成
- 订单卡片：订单号、状态、商品名、联系人、手机号、金额、数量、时间

主要操作：

- 搜索订单
- 筛选状态
- 进入订单详情

### `/orders/:id` 订单详情

目标：核对订单完整信息，并从详情发起核销。

展示内容：

- 订单号
- 订单状态
- 商品图
- 商品名称
- 商品类型
- 购买数量
- 联系人信息
- 支付信息
- 使用/预约信息
- 套餐内容
- 核销记录

主要操作：

- 待使用订单显示“立即核销”
- 点击后进入 `/verify/confirm`

核销按钮显示条件：

- `orderStatus === '2'`，即待使用

### `/verify` 核销入口

目标：提供独立核销入口。

展示内容：

- 点击进行扫码

主要操作：

- 调起手机摄像头扫码
- 解析 `orderId&packageName` 或 `orderId`
- 进入核销确认

备注：

- 当前不提供手动输入订单号兜底。
- 摄像头扫码要求浏览器支持摄像头能力，生产环境建议使用 HTTPS。

### `/verify/confirm` 核销确认

目标：防止员工误核销。

展示内容：

- 订单号
- 订单状态
- 商品名称
- 联系人
- 核销套餐
- 可核销商品数
- 已核销商品数
- 总数量
- 预约时间
- 实付金额

主要操作：

- 确认核销
- 取消返回

规则：

- 从扫码入口进入且二维码带套餐名称时，只展示当前扫码套餐，不允许切换其他套餐。
- 核销确认页优先使用后端套餐配置里的 `count`、`writeOffCount`、`packageStatus` 计算数量。
- 当可核销商品数为 `0` 时，确认核销按钮不可点击，并提示当前套餐商品已核销完。
- 调用核销接口后，必须检查 `/hotelStaff/order/writeOff` 返回的 `Boolean`；返回 `false` 时按核销失败处理。

状态：

- 可核销
- 套餐已核销完
- 当前订单不可核销
- 核销提交中
- 核销失败

### `/verify/result` 核销结果

目标：给员工明确反馈。

展示内容：

- 成功/失败状态
- 订单号
- 核销内容
- 操作时间
- 失败原因

主要操作：

- 继续核销
- 查看订单

### `/events` 事件列表

目标：查看已发布事件。

展示内容：

- 搜索框：事件标题
- 事件卡片：事件标题、事件描述、显示状态、生效时间、发布人、是否弹窗提醒

主要操作：

- 搜索事件
- 进入发布事件页

### `/events/create` 发布事件

目标：创建新的运营事件。

展示内容：

- 事件标题
- 事件描述
- 图片上传
- 发布时间
- 生效开始时间
- 生效结束时间
- 弹窗提醒开关

主要操作：

- 上传图片
- 发布事件

校验：

- 事件标题必填
- 事件描述必填
- 生效时间必填

### `/mine` 我的

目标：查看当前登录状态。

展示内容：

- 当前账号
- 登录状态
- 手机号绑定状态
- 租户

主要操作：

- 退出登录

## 订单状态

| 值 | 文案 |
|---|---|
| `0` | 待支付 |
| `1` | 待确认 |
| `2` | 待使用 |
| `3` | 已取消 |
| `4` | 退款中 |
| `5` | 已关闭 |
| `6` | 已完成 |

## 商品类型

| 值 | 文案 |
|---|---|
| `0` | 酒店 |
| `1` | 门票 |
| `2` | 餐饮 |

## 事件状态

| 值 | 文案 |
|---|---|
| `0` | 开启 |
| `1` | 关闭 |

事件列表还会展示后端计算的 `showStatusDesc`：

- 待生效
- 生效中
- 已过期

## 第一阶段 MVP

必须包含：

- 手机验证码登录
- 工作台
- 订单列表
- 订单详情
- 订单详情发起核销
- 独立核销入口
- 核销确认
- 核销结果
- 事件列表
- 发布事件
- 我的/退出登录

暂缓内容：

- 独立核销码查询
- 订单复杂高级筛选
- 事件编辑/关闭/删除
- 员工权限细分
- 数据统计图表