# 酒店订单支付系统开发文档

> 开发时间：2026-08-17  
> 功能模块：酒店顾客端支付流程（Mock 模式）

---

## 一、功能概述

实现了酒店顾客端完整的支付流程，支持**先支付后接单**的业务模式。当前采用 Mock 支付模式，后续可无缝对接微信支付、支付宝小程序支付。

### 核心特性

- ✅ **支付前置**：订单创建后进入"待支付"状态，支付成功后才进入"待接单"
- ✅ **15 分钟超时**：未支付订单自动取消，定时任务扫描处理
- ✅ **并发安全**：订单号生成、菜品销量累加均解决并发问题
- ✅ **支付流水**：完整的支付日志记录，支持对账
- ✅ **多状态管理**：待支付(0) → 已支付/待接单(1) → 后续流程；超时取消(10)
- ✅ **H5 适配**：支持微信小程序、支付宝小程序、H5、Mock 四种支付环境

---

## 二、数据库变更

### 2.1 Flyway 迁移脚本

**文件**：`forge-server/db/migration/V1.0.105__add_hotel_order_payment_fields.sql`

> MySQL 8.0 兼容：使用 `information_schema` + `PREPARE/EXECUTE` 模式替代 MariaDB 专有的 `IF NOT EXISTS` 扩展语法。

#### hotel_order 表新增字段

```sql
pay_status       TINYINT        -- 支付状态：0=待支付, 1=已支付, 2=已退款, 3=支付超时已取消
pay_expire_time  DATETIME       -- 支付截止时间
pay_time         DATETIME       -- 实际支付时间
pay_trade_no     VARCHAR(128)   -- 第三方支付交易号
paid_amount      DECIMAL(10,2)  -- 实付金额
pay_source       VARCHAR(32)    -- 支付来源：WECHAT/ALIPAY/H5/MOCK
```

#### 清理遗留字段

- `pay_method`：V1.0.104 创建但实体已移除，迁移脚本自动 DROP COLUMN

#### 新增索引

- `idx_pay_expire`：加速支付超时订单扫描（`pay_status`, `pay_expire_time`）
- `uk_order_no`：已在 V1.0.104 中创建，不重复

#### hotel_pay_log 表

记录每笔支付的完整流水，包括：
- 订单关联（order_id, order_no）
- 支付渠道（pay_channel: WECHAT/ALIPAY/MOCK）
- 支付来源（pay_source: WECHAT/ALIPAY/H5/WECHAT_MP/ALIPAY_MP/MOCK）
- 交易流水号（out_trade_no: 商户生成，trade_no: 第三方返回）
- 支付金额、状态、时间等

#### 字典数据

新增字典类型：
- `hotel_pay_status`：支付状态（0=待支付, 1=已支付, 2=已退款, 3=支付超时已取消）
- `hotel_pay_source`：支付来源（WECHAT/ALIPAY/H5/MOCK 等）
- `hotel_order_status`：补充 0=待支付、10=超时取消

---

## 三、后端变更

### 3.1 常量定义

**文件**：`HotelOrderConstants.java`

```java
// 订单状态
STATUS_PENDING_PAY = 0      // 待支付（新增）
STATUS_PLACED = 1           // 待接单（已支付）
STATUS_PAY_TIMEOUT = 10     // 超时取消（新增）

// 支付状态
PAY_STATUS_PENDING = 0      // 待支付
PAY_STATUS_SUCCESS = 1      // 已支付
PAY_STATUS_TIMEOUT = 2      // 支付超时

// 支付来源
PAY_SOURCE_WECHAT = "WECHAT"
PAY_SOURCE_ALIPAY = "ALIPAY"
PAY_SOURCE_H5 = "H5"
PAY_SOURCE_MOCK = "MOCK"

// 超时配置
PAY_TIMEOUT_MINUTES = 15    // 支付超时时间（分钟）
```

### 3.2 实体类

#### HotelOrder.java

新增字段：
- `payStatus`（Integer）：支付状态
- `payExpireTime`（LocalDateTime）：支付截止时间
- `payTime`（LocalDateTime）：实际支付时间
- `payTradeNo`（String）：支付交易号
- `paidAmount`（BigDecimal）：实付金额
- `paySource`（String）：支付来源

移除字段：
- `payMethod`（已废弃，改用 paySource）

#### HotelPayLog.java（新建）

支付流水实体，包含完整的支付记录字段。

### 3.3 Mapper 层

#### HotelOrderMapper.java

新增方法：
```java
List<Long> selectExpiredUnpaidOrderIds()
```
查询所有超时未支付的订单 ID。

#### HotelOrderMapper.xml

- `resultMap` 和 `OrderColumns`：添加支付相关字段映射
- `selectDashboard`、`countTodayOrders`、`sumTodayRevenue`：改为只统计已支付订单（`pay_status = 1`）
- `selectOrderPage`：筛选条件从 `payMethod` 改为 `payStatus`、`paySource`
- 新增 `selectExpiredUnpaidOrderIds`：查询超时订单

#### HotelDishMapper.java

新增方法：
```java
int incrementSales(@Param("dishId") Long dishId, @Param("quantity") Integer quantity)
```
原子更新菜品销量。

#### HotelDishMapper.xml

新增 SQL：
```xml
<update id="incrementSales">
    UPDATE hotel_dish
    SET sales = IFNULL(sales, 0) + #{quantity},
        update_time = NOW()
    WHERE id = #{dishId} AND del_flag = 0
</update>
```

#### HotelPayLogMapper.java（新建）

```java
HotelPayLog selectByOutTradeNo(@Param("outTradeNo") String outTradeNo)
```
根据商户订单号查询支付流水。

### 3.4 Service 层

#### HotelOrderServiceImpl.java

**orderCreate() 方法重构**：
- 订单创建后状态设为 `STATUS_PENDING_PAY`（待支付）
- 设置 `payStatus = PAY_STATUS_PENDING`
- 设置 `payExpireTime = now + 15 分钟`
- 移除 `payMethod` 字段赋值

**generateOrderNo() 并发修复**：
- 添加 3 次重试机制
- 每次重试前检查唯一性（`selectCount`）
- 防御性唯一性检查：插入前再次验证订单号是否已存在

**incrementDishSales() 并发修复**：
- 从"先查后写"改为原子 SQL 更新
- 调用 `dishMapper.incrementSales()` 直接执行 `SET sales = IFNULL(sales, 0) + #{quantity}`

**customerRefund() 新增逻辑**：
- 待支付订单（status=0）：直接取消，状态改为 `STATUS_PAY_TIMEOUT`
- 已支付订单（status=1）：进入退单流程

#### HotelPayService.java（新建）

支付服务接口，定义核心方法：
```java
Map<String, Object> createPay(Long orderId, String paySource)
PayResultVO mockPaySuccess(Long orderId)
void handlePayCallback(String outTradeNo, String tradeNo, boolean success, String rawContent)
PayResultVO queryPayStatus(Long orderId)
void cancelTimeoutOrder(Long orderId)
```

#### HotelPayServiceImpl.java（新建）

**createPay()**：
- 校验订单状态（必须为待支付）
- 检查是否已过期
- 生成商户订单号（`PAY + 时间戳 + 订单ID后6位`）
- 创建支付流水（`hotel_pay_log`）
- 返回支付参数（Mock 模式返回简化参数）

**mockPaySuccess()**：
- 模拟支付成功流程
- 创建 Mock 支付流水（如果不存在）
- 触发支付回调处理

**handlePayCallback()**：
- 幂等校验：已处理的订单直接返回
- 支付成功：更新流水状态、更新订单状态（0→1）、记录支付时间和交易号
- 支付失败：更新流水状态为失败

**cancelTimeoutOrder()**：
- 更新订单状态为 `STATUS_PAY_TIMEOUT`
- 更新支付状态为 `PAY_STATUS_TIMEOUT`

**queryPayStatus()**：
- 返回订单支付状态、金额、时间等信息

### 3.5 Controller 层

#### HotelPayController.java（新建）

路径：`/hotel/open/pay/**`（免登录，已在 SaToken 白名单中）

接口列表：
```
POST /create        发起支付（创建支付流水）
POST /mockSuccess   模拟支付成功（开发阶段）
GET  /status        查询支付状态（前端轮询）
POST /notify        支付回调通知（微信/支付宝异步通知入口，Mock 占位）
```

所有接口都需要传入 `tenantId` 参数，通过 `TenantContextHolder.executeWithTenant()` 在指定租户上下文中执行。

### 3.6 定时任务

#### PayTimeoutTask.java（新建）

```java
@Scheduled(fixedDelay = 120000, initialDelay = 30000)
public void cancelExpiredOrders()
```

- 每 2 分钟执行一次（启动后 30 秒开始）
- 使用 `TenantContextHolder.executeIgnore()` 跨租户扫描
- 查询所有超时未支付的订单 ID
- 逐条调用 `payService.cancelTimeoutOrder()` 取消

---

## 四、前端变更（H5）

### 4.1 API 层

**文件**：`forge-h5-ui/src/api/index.js`

新增支付相关 API：
```javascript
hotelPayCreate: (data) => request.post('/hotel/open/pay/create', data)
hotelPayMockSuccess: (data) => request.post('/hotel/open/pay/mockSuccess', data)
hotelPayStatus: (params) => request.get('/hotel/open/pay/status', { params })
```

### 4.2 支付页面

**文件**：`forge-h5-ui/src/pages/hotel/customer/pay.vue`

**核心功能**：
- **15 分钟倒计时**：显示剩余时间（分:秒），超时自动跳转
- **环境自动识别**：
  - 微信小程序：`wx.miniProgram.getPhoneNumber()`
  - 支付宝小程序：`my.tradePay()`
  - H5：跳转第三方支付页面
  - Mock：直接调用模拟支付接口
- **支付流程**：
  1. 调用 `hotelPayCreate` 创建支付流水
  2. 根据环境调用对应支付方法（Mock 直接调用 `hotelPayMockSuccess`）
  3. 支付成功后跳转到订单状态页

**UI 元素**：
- 订单信息展示（订单号、金额、房间号）
- 倒计时显示（红色高亮）
- 支付方式选择（当前仅 Mock）
- 支付按钮（根据环境显示不同文案）

### 4.3 订单状态页

**文件**：`forge-h5-ui/src/pages/hotel/customer/order-status.vue`

新增状态处理：
- **状态 0（待支付）**：
  - 图标：💳
  - 文案："等待支付"
  - 提示："请在 15 分钟内完成支付"
  - 按钮："去支付"（跳转到支付页）
- **状态 10（超时取消）**：
  - 图标：⏰
  - 文案："支付超时，订单已取消"
  - 提示："您可以重新下单"
  - `isFinished()` 返回 true（订单结束）

### 4.4 订单列表页

**文件**：`forge-h5-ui/src/pages/hotel/customer/orders.vue`

**状态标签更新**：
```javascript
statusLabel(status) {
  const map = {
    0: '待支付', 1: '待接单', 2: '已接单', 3: '备餐中',
    4: '已出餐', 5: '配送中', 6: '已完成',
    7: '已拒单', 8: '退单审核中', 9: '已退单',
    10: '超时取消',
  }
  return map[status] || '未知'
}
```

**状态颜色**：
- `.o-st--0`：黄色背景（待支付）
- `.o-st--10`：灰色背景（超时取消）

**待支付订单特殊处理**：
- 显示"去支付"按钮
- 点击卡片跳转到支付页（而非订单状态页）

### 4.5 订单确认页

**文件**：`forge-h5-ui/src/pages/hotel/customer/order-confirm.vue`

更新跳转逻辑：
- 下单成功后跳转到支付页（而非订单状态页）
- 传递参数：`orderId`、`tenantId`、`amount`

---

## 五、并发问题修复

### 5.1 订单号并发

**问题**：多个订单同时生成可能产生重复订单号

**解决方案**：
1. 数据库层面：`order_no` 添加唯一索引
2. 代码层面：`generateOrderNo()` 添加 3 次重试
3. 防御性检查：插入前 `selectCount` 验证唯一性

### 5.2 菜品销量并发

**问题**：先查后写导致并发时销量丢失

**解决方案**：
- 使用原子 SQL 更新：`SET sales = IFNULL(sales, 0) + #{quantity}`
- 避免"读取-计算-写入"的竞态条件

---

## 六、支付流程时序图

```
顾客                H5前端              后端API              数据库
 |                  |                   |                    |
 |--下单----------->|                   |                    |
 |                  |--创建订单-------->|                    |
 |                  |                   |--插入订单(status=0)|
 |                  |                   |<-------------------|
 |                  |<--返回orderId-----|                    |
 |                  |                   |                    |
 |--跳转支付页----->|                   |                    |
 |                  |--创建支付-------->|                    |
 |                  |                   |--插入pay_log       |
 |                  |                   |<-------------------|
 |                  |<--返回支付参数----|                    |
 |                  |                   |                    |
 |--点击支付------->|                   |                    |
 |                  |--模拟支付成功---->|                    |
 |                  |                   |--更新pay_log       |
 |                  |                   |--更新订单(status=1)|
 |                  |                   |<-------------------|
 |                  |<--返回支付结果----|                    |
 |                  |                   |                    |
 |--跳转订单状态--->|                   |                    |
 |                  |--轮询支付状态---->|                    |
 |                  |                   |--查询订单          |
 |                  |                   |<-------------------|
 |                  |<--返回已支付------|                    |
 |                  |                   |                    |
```

---

## 七、后续对接真实支付

### 7.1 微信支付（小程序）

1. 在 `HotelPayServiceImpl.createPay()` 中调用微信统一下单接口
2. 返回微信支付所需参数（prepay_id、sign 等）
3. 前端 `pay.vue` 中调用 `wx.requestPayment()`
4. 微信异步通知 `/hotel/open/pay/notify`
5. 验签、解密、更新订单状态

### 7.2 支付宝支付（小程序）

1. 在 `HotelPayServiceImpl.createPay()` 中调用支付宝订单创建接口
2. 返回支付宝所需参数（trade_no 等）
3. 前端 `pay.vue` 中调用 `my.tradePay()`
4. 支付宝异步通知 `/hotel/open/pay/notify`
5. 验签、更新订单状态

### 7.3 配置项

需要在 `application.yml` 中添加：
```yaml
forge:
  pay:
    wechat:
      appId: xxx
      mchId: xxx
      apiKey: xxx
    alipay:
      appId: xxx
      privateKey: xxx
      alipayPublicKey: xxx
```

---

## 八、文件清单

### 后端新增文件

1. `forge-server/forge-business/forge-hotel/src/main/java/com/mdframe/forge/business/core/hotel/pay/domain/HotelPayLog.java`
2. `forge-server/forge-business/forge-hotel/src/main/java/com/mdframe/forge/business/core/hotel/pay/mapper/HotelPayLogMapper.java`
3. `forge-server/forge-business/forge-hotel/src/main/resources/mapper/business/hotel/pay/HotelPayLogMapper.xml`
4. `forge-server/forge-business/forge-hotel/src/main/java/com/mdframe/forge/business/core/hotel/pay/service/HotelPayService.java`
5. `forge-server/forge-business/forge-hotel/src/main/java/com/mdframe/forge/business/core/hotel/pay/service/impl/HotelPayServiceImpl.java`
6. `forge-server/forge-business/forge-hotel/src/main/java/com/mdframe/forge/business/core/hotel/pay/vo/PayResultVO.java`
7. `forge-server/forge-business/forge-hotel/src/main/java/com/mdframe/forge/business/core/hotel/controller/open/HotelPayController.java`
8. `forge-server/forge-business/forge-hotel/src/main/java/com/mdframe/forge/business/core/hotel/pay/task/PayTimeoutTask.java`

### 后端修改文件

1. `forge-server/forge-business/forge-hotel/src/main/java/com/mdframe/forge/business/core/hotel/order/constant/HotelOrderConstants.java`
2. `forge-server/forge-business/forge-hotel/src/main/java/com/mdframe/forge/business/core/hotel/order/domain/HotelOrder.java`
3. `forge-server/forge-business/forge-hotel/src/main/java/com/mdframe/forge/business/core/hotel/order/mapper/HotelOrderMapper.java`
4. `forge-server/forge-business/forge-hotel/src/main/resources/mapper/business/hotel/order/HotelOrderMapper.xml`
5. `forge-server/forge-business/forge-hotel/src/main/java/com/mdframe/forge/business/core/hotel/mapper/HotelDishMapper.java`
6. `forge-server/forge-business/forge-hotel/src/main/resources/mapper/business/hotel/HotelDishMapper.xml`
7. `forge-server/forge-business/forge-hotel/src/main/java/com/mdframe/forge/business/core/hotel/order/service/impl/HotelOrderServiceImpl.java`
8. `forge-server/forge-business/forge-hotel/src/main/java/com/mdframe/forge/business/core/hotel/order/vo/HotelOrderVO.java`

### 数据库脚本

1. `forge-server/db/migration/V1.0.105__add_hotel_order_payment_fields.sql`

### 前端新增文件

无

### 前端修改文件

1. `forge-h5-ui/src/api/index.js`
2. `forge-h5-ui/src/pages/hotel/customer/pay.vue`
3. `forge-h5-ui/src/pages/hotel/customer/order-status.vue`
4. `forge-h5-ui/src/pages/hotel/customer/orders.vue`
5. `forge-h5-ui/src/pages/hotel/customer/order-confirm.vue`

---

## 九、测试建议

### 9.1 功能测试

1. **正常支付流程**：
   - 下单 → 跳转支付页 → 点击支付 → 支付成功 → 订单状态变为"待接单"
   
2. **超时取消**：
   - 下单 → 等待 15 分钟 → 订单自动取消 → 状态变为"超时取消"
   
3. **主动取消**：
   - 下单 → 在支付页点击"取消订单" → 订单状态变为"超时取消"
   
4. **重复支付防护**：
   - 已支付订单再次调用支付接口 → 返回"订单已支付"错误

### 9.2 并发测试

1. **订单号唯一性**：
   - 同时创建 100 个订单 → 验证订单号无重复
   
2. **菜品销量准确性**：
   - 同时完成 10 个包含同一菜品的订单 → 验证销量累加正确

### 9.3 边界测试

1. **支付超时边界**：
   - 在第 14 分 59 秒支付 → 应该成功
   - 在第 15 分 01 秒支付 → 应该返回"订单已超时"

2. **库存不足**：
   - 下单时菜品库存不足 → 应该返回错误

---

## 十、已知问题与优化建议

### 10.1 已知问题

1. **Mock 模式安全性**：
   - 当前 Mock 支付接口无需鉴权，生产环境需要移除或限制访问
   
2. **定时任务精度**：
   - 数据库轮询方案最大延迟 2 分钟，对业务影响可接受

### 10.2 优化建议

1. **支付回调重试**：
   - 添加重试机制，防止网络问题导致回调失败
   
2. **支付对账**：
   - 添加每日对账任务，比对本地流水与第三方支付平台数据
   
3. **支付统计**：
   - 添加支付成功率、支付金额等统计报表
   
4. **退款流程**：
   - 完善已支付订单的退款流程（当前只支持未支付取消）

---

## 十一、总结

本次开发完成了酒店订单支付系统的核心功能，包括：

- ✅ 数据库结构设计（支付字段、流水表、索引）
- ✅ 后端支付服务（Mock 模式、回调处理、超时取消）
- ✅ 前端支付页面（倒计时、环境识别、支付调用）
- ✅ 并发问题修复（订单号、菜品销量）
- ✅ 订单状态管理（待支付、已支付、超时取消）

当前系统已支持完整的 Mock 支付流程，后续可无缝对接微信支付、支付宝小程序支付。所有代码已通过编译验证，无语法错误。

---

**文档版本**：v1.0  
**最后更新**：2026-08-17  
**维护人员**：AI Assistant