meal_manager/jeesharp-business/HOTEL_SCENIC_DEPLOYMENT.md

酒店与景区模块联调说明

范围

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

• 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. 若进入运营阶段，再补退款、撤销、售后相关流程

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