# 店员核销功能 · 前后端协作协议

> 版本：v1.0（2026-08-03）｜项目：妆点一刻·饮品店小程序
> 状态：后端实现中，此文档供前端并行开发

## 一、功能概述

指定微信用户为**店员**（后端 role 字段标识），店员登录小程序后出现「核销」入口，可对顾客订单进行**扫码核销**或**手动输号核销**。

- 店员身份：后端 `wx_user.role = 1`（0 普通用户 / 1 店员），初期由店主在后端数据库直接设置
- 核销走**用户 token**（与顾客同一套登录体系），前端无需新增登录流程

## 二、店员身份识别

`GET /api/user/info` 与 `GET /api/user/detail` 响应新增 `role` 字段：

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 5,
    "nick": "枢铭测试5",
    "mobile": "15995518218",
    "role": 1,
    "...": "..."
  }
}
```

**前端逻辑**：登录后调 `/api/user/detail`（或 info）→ `data.role == 1` → 显示「核销」入口；`role == 0` 不显示。

## 三、核销接口（3 个，均需登录 + 店员身份）

### 3.1 扫码核销

```
POST /api/staff/order/hx
Content-Type: application/x-www-form-urlencoded 或 application/json
参数：hxNumber（必填，二维码内容，16 位核销码）
```

成功响应：
```json
{ "code": 0, "msg": "success", "data": null }
```

失败响应：
```json
{ "code": 700, "msg": "核销码不能为空" }
{ "code": 700, "msg": "未找到对应取餐码的订单" }
{ "code": 700, "msg": "只有制作中的订单才能核销" }
{ "code": 2001, "msg": "无权限" }   // 非店员
```

### 3.2 手动输号核销

```
POST /api/staff/order/pickup
Content-Type: application/x-www-form-urlencoded 或 application/json
参数：pickupNumber（必填，顾客报的 4 位取餐号）
```

说明：**仅核销当天**（pickup_date = 今日）的订单，避免跨天取餐号重复撞单。

成功/失败响应同 3.1，另有：
```json
{ "code": 700, "msg": "未找到今天的取餐号" }
```

### 3.3 核销前查单（店员核对，防扫错）

```
GET /api/staff/order/query?hxNumber=xxx
GET /api/staff/order/query?pickupNumber=0423
（二选一，传一个即可）
```

成功响应：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 123,
    "orderNo": "202608030000001",
    "pickupNumber": "0423",
    "hxNumber": "2026080301010123",
    "status": 1,
    "amountReal": 10.00,
    "dateAdd": "2026-08-03 09:15:30",
    "items": [
      { "goodsName": "珍珠奶茶", "number": 1, "property": "多冰,3分糖", "additions": "红豆" }
    ]
  }
}
```

失败：`{ "code": 700, "msg": "未找到对应订单" }`

**建议前端流程**：扫码/输号 → 调 query 展示订单信息确认 → 店员点头 → 调核销接口 → 成功提示 + 刷新。

## 四、状态码约定

| code | 含义 |
|---|---|
| 0 | 成功 |
| 700 | 业务失败（未找到/状态不符/参数错误） |
| 2000 | 未登录 / token 无效 |
| 2001 | 无权限（非店员调用核销接口） |

## 五、关键业务规则（前端提示文案参考）

1. **一单一核销**：核销后订单状态 1(制作中) → 2(已完成)，**不可重复核销**（再次核销提示「只有制作中的订单才能核销」）
2. **手动输号仅当天有效**：顾客的 4 位取餐号隔天作废（跨天提示「未找到今天的取餐号」）
3. **核销范围**：店员只能核销订单，**不能查看全部订单/修改商品**（那是商户后台能力）
4. **取餐页展示**：顾客端取餐页应展示**所有制作中订单**（每单含 pickupNumber + hxNumber），不是只显示最新一单——顾客取哪单展示哪单的码（orderList 已支持 statusBatch 过滤，前端取 status=1 的列表）

## 六、后端交付物（联调前就绪）

| 项 | 状态 |
|---|---|
| wx_user.role 字段 + 迁移 | 实现中 |
| role 在 user/info、user/detail 返回 | 实现中 |
| POST /api/staff/order/hx（扫码核销） | 实现中 |
| POST /api/staff/order/pickup（输号核销，当天） | 实现中 |
| GET /api/staff/order/query（核销前查单） | 实现中 |

## 七、联调建议

1. 前端用**店员账号**（role=1）登录 → 确认 user/detail 返回 role=1 → 核销入口出现
2. 顾客端下一单（isCanHx=true）→ 拿到 hxNumber/pickupNumber
3. 店员端 query 查单 → hx 核销（或 pickup 输号核销）→ 成功
4. 再核销同一单 → 应提示「只有制作中的订单才能核销」（幂等验证）

---

后端接口就绪后我会更新此文档状态；前端联调遇到字段/行为不符随时反馈。