# 酒店与景区模块联调说明

## 范围

本文档覆盖当前仓库内已经落地的两个业务模块：

- `business-hotel`
- `business-scenic`

适用场景：

- 数据库初始化
- 菜单权限导入
- 后台管理端联调
- 小程序接口联调
- 微信支付联调前置检查

当前结论：

- 两个模块都已经接入 `jeesharp-business` 聚合工程。
- 后台 controller、application、service、mapper、SQL 脚本都已落地。
- 小程序端接口已通过 `business-mobile-gateway` 挂出。
- 酒店与景区支付回调入口、统一回调适配层、业务确认支付适配器都已落地。
- “我的订单”聚合接口已纳入酒店与景区订单。

## 一、酒店模块

目录：

- `jeesharp-business/business-hotel`

推荐 SQL 顺序：

1. `01_schema.sql`
2. `02_seed.sql`
3. `03_menu_permission.sql`
4. `04_cleanup.sql` 可选回滚

### 1. 后台能力

当前后台已具备以下对象管理能力：

- 酒店管理
- 房型管理
- 预订单管理

菜单路径：

- `/business/hotel/stay`
- `/business/hotel/room-type`
- `/business/hotel/booking`

对应后台接口子路径：

- `GET /manager/business/hotel/stay/v1/info`
- `POST /manager/business/hotel/stay/v1/list`
- `POST /manager/business/hotel/stay/v1/save`
- `GET /manager/business/hotel/stay/v1/delete`
- `GET /manager/business/hotel/roomType/v1/info`
- `POST /manager/business/hotel/roomType/v1/list`
- `POST /manager/business/hotel/roomType/v1/save`
- `GET /manager/business/hotel/roomType/v1/delete`
- `GET /manager/business/hotel/booking/v1/info`
- `POST /manager/business/hotel/booking/v1/list`
- `POST /manager/business/hotel/booking/v1/save`
- `GET /manager/business/hotel/booking/v1/delete`

说明：

- 菜单路由仍然是 `/business/hotel/room-type`，但后台 controller 路径是 `roomType/v1`，这是当前代码中的实际实现。

### 2. 小程序能力

当前移动端接口挂载在：

- `${jeesharp.web.mobilePath}/hotel`

主要接口：

- `GET /mobile/hotel/stays`
- `GET /mobile/hotel/stay/{id}`
- `POST /mobile/hotel/booking/create`
- `POST /mobile/hotel/booking/pay/prepare`
- `GET /mobile/hotel/booking/pay/status/{orderId}`
- `POST /mobile/hotel/booking/pay/mock-success`
- `POST /mobile/hotel/booking/cancel`
- `GET /mobile/hotel/booking/result/{orderId}`

当前已经实现的业务行为：

- 酒店列表与详情查询
- 房型随酒店详情一起输出
- 创建酒店业务预约单
- 根据入住/离店日期、房型、间数计算支付金额
- 生成支付业务字段：`tradeOrderId / payOrderId / attach / amountFen`
- 查询支付状态
- 模拟支付成功
- 微信支付回调后确认支付
- 取消未完成预订
- 成功页按 `orderId` 回查结果

### 3. 当前支付接入状态

当前不是纯占位状态，已经具备以下能力：

- `HotelBookingOrderServiceImpl#preparePay(...)` 会生成完整业务支付参数
- `HotelMobileController#payPrepare(...)` 通过 `WechatJsapiPayOrderPrepayService` 创建财务支付单（`biz_finance_pay_order`）、调用 `WechatMiniPayService.createPrepay(...)` 并回填调起参数
- 如果会员已登录且存在 `memberId + appId + openid` 绑定，会把 `payer.openid` 一起带上
- 支付回调：`TravelWechatPayNotifyMobileController`（`/mobile/pay/notify/wechat`，attach 路由）
- 回调适配层已经接到 `WechatPayNotifyAdapterService`
- 酒店业务确认支付适配器已经落地在 `HotelWechatPayCallbackAdapter`

## 二、景区门票模块

目录：

- `jeesharp-business/business-scenic`

推荐 SQL 顺序：

1. `01_schema.sql`
2. `02_seed.sql`
3. `03_menu_permission.sql`
4. `04_cleanup.sql` 可选回滚

### 1. 后台能力

当前后台已具备以下对象管理能力：

- 景区场馆管理
- 景区预约单管理

菜单路径：

- `/business/scenic/venue`
- `/business/scenic/booking`

对应后台接口子路径：

- `GET /manager/business/scenic/venue/v1/info`
- `POST /manager/business/scenic/venue/v1/list`
- `POST /manager/business/scenic/venue/v1/save`
- `GET /manager/business/scenic/venue/v1/delete`
- `GET /manager/business/scenic/booking/v1/info`
- `POST /manager/business/scenic/booking/v1/list`
- `POST /manager/business/scenic/booking/v1/save`
- `GET /manager/business/scenic/booking/v1/delete`

### 2. 小程序能力

当前移动端接口挂载在：

- `${jeesharp.web.mobilePath}/ticket/booking`

主要接口：

- `GET /mobile/ticket/booking/venues`
- `GET /mobile/ticket/booking/venue/{id}`
- `POST /mobile/ticket/booking/create`
- `POST /mobile/ticket/booking/pay/prepare`
- `GET /mobile/ticket/booking/pay/status/{orderId}`
- `POST /mobile/ticket/booking/pay/mock-success`
- `POST /mobile/ticket/booking/cancel`
- `GET /mobile/ticket/booking/result/{orderId}`

当前已经实现的业务行为：

- 场馆列表与详情查询
- 免费预约：创建后进入 `pending_use`
- 付费预约：创建后进入 `pending_pay`
- 保存票档人数、出行人、金额明细
- 生成支付业务字段：`tradeOrderId / payOrderId / attach / amountFen`
- 查询支付状态
- 模拟支付成功
- 微信支付回调后确认支付
- 取消未完成预约
- 成功页按 `orderId` 回查结果

### 3. 当前支付接入状态

当前景区支付链路也已经超出“仅占位”阶段：

- `ScenicBookingOrderServiceImpl#preparePay(...)` 已生成支付业务参数
- `ScenicMobileController#preparePay(...)` 通过 `WechatJsapiPayOrderPrepayService` 创建财务支付单、调用 `WechatMiniPayService.createPrepay(...)` 并回填调起参数
- 支付回调：`TravelWechatPayNotifyMobileController`（`/mobile/pay/notify/wechat`，attach 路由）
- 统一回调适配层已经接入 `WechatPayNotifyAdapterService`
- 景区业务确认支付适配器已经落地在 `ScenicWechatPayCallbackAdapter`

## 三、后端挂载点

两个模块当前已经挂入以下工程：

- `jeesharp-business/pom.xml`
- `jeesharp-business/business-mobile-gateway/pom.xml`
- `web-starter/pom.xml`

因此正常启动 `web-starter` 后，会同时暴露：

- 后台管理接口
- 小程序业务接口
- 微信支付回调接口

支付相关公共组件当前在 `business-mobile-gateway` 内统一维护：

- `WechatJsapiPayOrderPrepayService`（支付单 + 统一下单 + 回填 VO）
- `WechatPayNotifyAdapterService`
- `HotelWechatPayCallbackAdapter`
- `ScenicWechatPayCallbackAdapter`
- `MallWechatPayCallbackAdapter`
- `WECHAT_PAY_NOTIFY_SAMPLE.yml`

财务侧支付单与支付流水在 `business-finance`：`PayOrderApplicationService`、`PayRecordApplicationService`（回调先更新支付单再落支付记录）。

## 四、订单聚合现状

当前“我的订单”聚合已经不是待办，已接入移动端订单接口：

- `GET /mobile/order/list`
- `GET /mobile/order/{id}`

当前会聚合三类订单：

- 商城订单
- 酒店预订单
- 景区预约单

说明：

- 这里是接口聚合，未接统一订单中心。
- 酒店、景区、**商城订单**预支付均走 `WechatJsapiPayOrderPrepayService`（财务支付单 + 微信统一下单）；酒店与景区仍各自维护业务单状态；商城订单支付状态见 `mall_order.status`。

## 五、联调前检查

### 1. 菜单父级

两个模块的菜单 SQL 默认依赖：

- `sys_menu.parent_id = biz_root`

如果现网父菜单不是 `biz_root`，执行前需要先修改：

- `03_menu_permission.sql`
- 对应总菜单脚本

### 2. 角色授权

当前菜单 SQL 只负责：

- 菜单
- 按钮权限

不会自动给真实角色写入授权。

仍需：

- 手动执行 `sys_role_menu` 授权
- 或在后台角色管理中勾选

### 3. 静态资源

演示数据默认引用部分静态图片，如：

- `/static/images/home-hero-default.png`（原 `home-hero-banner.png` / `home-hero-ref.png` 已合并）

如果现网不提供这些资源，需要改成真实 URL。

### 4. 微信小程序支付前置

要跑通真实 `createPrepay(...)`，至少要满足：

- `wx.pay.jsapi.enabled=true`
- `notify-base-url` 配置正确
- 商户私钥、平台公钥、`api-v3-key` 配置完整
- 当前会员存在微信小程序登录态
- `app_member_oauth` 中可查到 `memberId + appId + openid`

配置样例：

- `jeesharp-business/business-mobile-gateway/WECHAT_PAY_NOTIFY_SAMPLE.yml`

### 5. 本地联调说明

本地联调时，如果没有完整微信支付配置，可使用：

- `pay/mock-success`
- `wx.pay.jsapi.mock-fallback=true`
- `wx.pay.notify.skip-signature-verify=true`

但测试/生产环境不能依赖这些开发态设置。

## 六、联调顺序建议

### 酒店

1. 执行酒店 SQL
2. 在后台维护酒店与房型
3. 调 `GET /mobile/hotel/stays` 与 `GET /mobile/hotel/stay/{id}` 校验数据
4. 调 `POST /mobile/hotel/booking/create` 创建业务单
5. 调 `POST /mobile/hotel/booking/pay/prepare` 验证预支付参数
6. 本地先用 `POST /mobile/hotel/booking/pay/mock-success` 验证支付成功流转
7. 核对 `biz_finance_pay_order.notify_url` 为 `.../mobile/pay/notify/wechat` 并完成真实支付回调联调
8. 最后用 `GET /mobile/hotel/booking/result/{orderId}` 与 `GET /mobile/order/{id}` 校验结果

### 景区门票

1. 执行景区 SQL
2. 在后台维护场馆与票档 JSON
3. 调 `GET /mobile/ticket/booking/venues` 与 `GET /mobile/ticket/booking/venue/{id}` 校验数据
4. 免费票验证创建后直接进入 `pending_use`
5. 付费票验证创建后进入 `pending_pay`
6. 调 `POST /mobile/ticket/booking/pay/prepare` 验证预支付参数
7. 本地先用 `POST /mobile/ticket/booking/pay/mock-success` 验证支付成功流转
8. 核对 `biz_finance_pay_order.notify_url` 为 `.../mobile/pay/notify/wechat` 并完成真实支付回调联调
9. 最后用 `GET /mobile/ticket/booking/result/{orderId}` 与 `GET /mobile/order/{id}` 校验结果

## 七、当前限制

### 酒店

已完成：

- 业务单创建
- 金额计算
- 预支付参数生成
- JSAPI 下单调用接入点
- 支付状态查询
- 模拟支付成功
- 微信支付回调入口
- 回调统一适配
- 成功页回查

未完成或仍需加强：

- 真实环境下的完整支付联调验证
- 支付回调幂等保护的严格校验
- 超时关单任务
- 退款/售后流程
- 与统一订单中心的正式打通

### 景区门票

已完成：

- 免费预约闭环
- 付费预约业务单创建
- 预支付参数生成
- JSAPI 下单调用接入点
- 支付状态查询
- 模拟支付成功
- 微信支付回调入口
- 回调统一适配
- 成功页回查

未完成或仍需加强：

- 真实环境下的完整支付联调验证
- 支付回调幂等保护的严格校验
- 超时关单任务
- 退款/撤销能力
- 与统一订单中心的正式打通

## 八、前端联调说明

当前仓库内已经明确了后端接口契约，但没有在本仓库直接检索到 `pages/hotel/*` 或 `pages/ticket/*` 页面源码。

因此这里把以下路径视为小程序端联调约定，而不是当前仓库内现成资源：

- `pages/hotel/index`
- `pages/hotel/detail`
- `pages/hotel/book`
- `pages/hotel/success`
- `pages/ticket/index`
- `pages/ticket/book`
- `pages/ticket/success`

如果联调使用的是外部小程序仓库，请以该仓库中的页面与 API 封装为准。

## 九、推荐下一步

按当前进度，优先建议：

1. 用测试商户参数把酒店、景区两条真实微信支付链路各跑通一次
2. 给酒店、景区回调补更严格的幂等与异常补偿
3. 增加未支付超时关闭任务
4. 明确是否要接统一订单中心，而不是继续双轨维护业务单
5. 若进入运营阶段，再补退款、撤销、售后相关流程

如果只是做业务演示或后台联调，当前版本已经可以支撑酒店与景区的主流程联调。