92 lines
9.7 KiB
Markdown
92 lines
9.7 KiB
Markdown
# 酒店结账全部结算接入
|
||
|
||
## 启用和发布
|
||
|
||
全部结算直接启用，预检、受理及后台执行由业务流程和权限控制。完成迁移、第三方及钱包全部实例部署、前端和角色授权后即可使用。
|
||
|
||
酒店结账结果默认回传 `pjcloud-wallet-biz`，thirdparty 已内置 `hotel-checkout` 对应的钱包接收目标。下面的配置用于覆盖部署中的服务名。当前支付宝付款应用使用 `ali-pay-config` 的证书配置。
|
||
|
||
```yaml
|
||
app-plus:
|
||
transfer:
|
||
notify-targets:
|
||
hotel-checkout:
|
||
service-id: pjcloud-wallet-biz
|
||
```
|
||
|
||
覆盖服务名时按实际注册名核对，显式空值或非法地址会阻止付款预检。更新内置目标解析代码后须重新部署并启动 thirdparty，钱包及前端使用已更新的结账版本。预检通过后显示确认选项及确认转账按钮，操作员确认后才异步受理真实付款。转账场景固定为“业务结算”，背景类型为“结算款项名称”，内容包含原酒店结账单号。先在支付宝完成转账产品签约、场景申报和 `alipay.fund.trans.order.changed` 应用网关订阅。
|
||
|
||
发布前先核实历史登记清单。停止钱包旧实例和受理任务、隔离回调写入后，完成外部一致性备份及迁移，再发布钱包与前端、核对权限并恢复任务。第三方通知增加付款 AppID 快照，可先发布 thirdparty，钱包兼容旧通知时通过受保护查询核实应用。钱包转账扫描统一由 sys_job 触发，初始每5秒最多100条，保留4个Worker和120秒数据库租约。第三方提交、查单、通知任务同样通过任务管理页维护。
|
||
|
||
首次接入需要 `db/20261110_add_mch_checkout_bill_transfer.sql` 创建批次与付款尝试表。本轮新增 `db/20261110_mch_checkout_alipay_only.sql`，按独立阶段核实历史数据、恢复明确误登记、保留审计依据并删除商户表7个登记字段及其约束/索引。脚本编写和数据库执行分别安排。
|
||
|
||
## 历史数据迁移与发布
|
||
|
||
1. 在同一钱包库连接执行新脚本的默认 `PREFLIGHT`，导出历史清单。`HCO2120097438306938882` 是首批待核实账单，脚本未预置任何未实付结论。
|
||
2. 停止全部旧钱包实例及受理任务，隔离第三方回调写入，完成外部一致性备份。写入阶段还会保留账单、商户、订单、占用、事件、批次、付款尝试七张首次只读副本。
|
||
3. 财务确认未通过其他渠道实付后，在脚本的 `tmp_checkout_verified_unpaid` 中逐明细填写租户、明细ID、当前版本、原请求号、应付分金额、核实人及依据。同一连接设置阶段为 `REPAIR`，并将脚本列明的停机及备份确认变量置1后执行。
|
||
4. 核对恢复的待付款状态、递增版本、订单复核调度和 `MANUAL_PAYMENT_RESTORED` 审计。成功、在途、资金异常、版本或请求号不匹配均拒绝恢复。同阶段重跑保持幂等。
|
||
5. 所有历史已付款均已核实后执行 `MIGRATE`。已实付或未核实的手工登记仍会阻止删列，需单独完成资金对账。原依据保存在事件与备份中，7列和依赖在一个原子ALTER中移除。
|
||
6. 发布新钱包与前端，手动退役 `wallet_mchCheckoutBill_pay`，授权 `wallet_mchCheckoutBill_transfer`。完成核对后恢复任务，操作员重新预览并确认真实转账。
|
||
|
||
迁移后重复执行直接返回已完成。旧钱包代码依赖已删除列，恢复旧版本需先在停机窗口按备份制定对应数据回退方案。
|
||
|
||
## 默认收款配置
|
||
|
||
使用商户当前支付宝支付配置的唯一默认关系。默认关系中的接收方类型、完整标识及可选实名作为转账依据。关闭分账时仍可维护收款字段，实际转账前统一校验。
|
||
|
||
| 关系接收方类型 | 转账身份 | 必要条件 |
|
||
| --- | --- | --- |
|
||
| `userId` | `ALIPAY_USER_ID` | 有效接收方标识 |
|
||
| `openId` | `ALIPAY_OPEN_ID` | 有效标识，关系所属应用与付款应用一致 |
|
||
| `loginName` | `ALIPAY_LOGON_ID` | 有效标识及收款实名 |
|
||
| `cardAliasNo` | 预检异常 | 改配当前产品支持的身份 |
|
||
|
||
原始账号仅通过受保护的Feign获取，在钱包和第三方各自使用项目统一加密器保存固定指令。管理端展示脱敏账号及实名。分账开关、绑定结果和分佣比例不参与转账资格判断。
|
||
|
||
## 付款及恢复规则
|
||
|
||
- “全部结算”读取整张账单所有待付款明细，商户行“支付宝转账”仅选择该商户。两个入口都校验整张账单的历史数据权限。预检令牌属于当前用户，有效十分钟，提交前重新读取酒店订单及收款配置。
|
||
- 已付款、已作废及无订单明细自动跳过。有订单且应付为零的商户记录确认结清事件。
|
||
- 正金额须在10～10000000000分之间。低于最低金额及超过单笔上限时阻止本次付款范围提交。0.01～0.09元保留待付款，可经确认作废原明细、调整抽成配置后重新结账。
|
||
- 同一账单批次的请求号和预检令牌在超时重试时保持原值。已受理结果优先从数据库恢复，预检缓存到期后也可恢复原批次。
|
||
- 全量参与名单通过后原子保存付款授权。真实渠道执行允许部分成功。转账中明细使用 `PAYING`，待付款汇总包含这一状态。
|
||
- 仅支付宝SUCCESS且金额、业务归属、原指令和付款AppID核对一致才回写已付。实付金额只读汇总成功付款指令，重复查询和一对多展示不会增加实付。付款时间采用渠道事实，未回传时显示“待渠道核实”，后台安排原单复核补齐。
|
||
- 明确失败释放当前付款尝试。再次付款先同步核对原单，再重新预检并由操作员确认。原单被明确拒绝且渠道确认无单时允许重新授权，其他未知结果继续保留转账中。
|
||
- 资金终态与订单差异分别记录。迟到成功按原付款尝试落账，存在后续付款尝试或终态冲突时冻结新付款并记录审计。
|
||
- 原任务失败退避最长5分钟，累计100次领取后暂停任务，保留原资金状态。在详情中“核对并恢复原单”后继续同号执行。
|
||
- 详情每5秒更新进度，跨批次尚有未收敛付款也持续刷新。详情提供历史批次分页查询、逐商户最近尝试和第三方转账记录入口。等待第三方受理时显示“待受理”，不提前显示已付款。
|
||
|
||
## 历史误登记重新转账
|
||
|
||
商户付款明细在“历史手工PAY审计完整、请求号与原应付相符、没有任何平台付款尝试”时显示“核对并重新转账”。原账单及订单占用持续保留，确认后在同一事务中追加纠正事件、创建首笔付款指令并将商户改为PAYING，只有渠道成功才重新记为PAID。
|
||
|
||
预检、确认和提交均绑定指定商户、账单/商户版本及原PAY事件。直接API提交也必须明确提供 `legacyPaymentConfirmedUnpaid=true`。这一确认只适用于旧登记，普通结算默认false并沿用原请求摘要。
|
||
|
||
没有平台指令时无法按转账号向支付宝查单，界面明确显示该事实，并要求操作员确认没有其他渠道实付。已有失败指令继续通过原单Feign同步查询，成功、在途、未知结果或查询异常都会阻止生成新的付款。重复点击及超时重试沿用原请求，原账本锁和版本检查防止并发纠正。
|
||
|
||
本功能沿用 `wallet_mchCheckoutBill_transfer` 权限与完整历史账单数据权限，部署钱包代码并刷新前端后使用。数据库结构沿用现有账单与转账表。
|
||
|
||
## 手工配置权限
|
||
|
||
| 名称 | 类型 | 父级菜单及真实ID | 权限标识 | 页面路由 | 组件路径 |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| 支付宝转账（整单及单商户） | 按钮 | 商户结账记录，ID待确认 | `wallet_mchCheckoutBill_transfer` | 沿用商户结账记录菜单 | `mch/checkout/record/index` |
|
||
|
||
已有 `wallet_mchCheckoutBill_view` 负责查看历史转账进度。新的转账权限控制预检、真实付款受理和业务侧原单恢复。每个入口均校验整张账单完整历史归属权限。
|
||
|
||
## 验证边界
|
||
|
||
开发阶段使用源码语法、接口及状态路径核对。已补充单商户范围、付款应用与指令核对、成功资金合计、跨批次轮询、历史迟到成功冻结、迁移白名单及重复删列的针对性回归源码。测试执行、隔离数据库并发验证和受控支付宝联调留在集中验证阶段。
|
||
|
||
集中验证时执行钱包与第三方测试及编译、前端检查及构建，使用隔离MySQL验证请求唯一约束、事务回滚、租约恢复及单商户/整单转账与作废竞争。真实支付宝联调与数据库迁移执行单独安排。
|
||
|
||
隔离数据库用例读取 `CHECKOUT_BILL_TEST_JDBC_URL`、`CHECKOUT_BILL_TEST_JDBC_USER`、`CHECKOUT_BILL_TEST_JDBC_PASSWORD`，数据库名必须以 `_checkout_bill_test` 结尾，只创建和清理随机后缀测试表。
|
||
|
||
|
||
## 统一任务管理
|
||
|
||
钱包结账转账受理扫描与订单复核统一由 `sys_job` 触发，页面入口为 `/tools/job-manage/index`。初始任务分别为“酒店结账转账受理扫描”和“酒店结账订单复核”，执行 Bean 为 `mchCheckoutTask`，无参方法分别为 `dispatchTransfers`、`recheckOrders`。前者初始每5秒，后者初始每分钟，周期和启停由页面维护。
|
||
|
||
先停止旧钱包与 Quartz 实例，执行任务库脚本 `db/20261110_migrate_business_jobs_to_sys_job.sql`，再部署钱包和 Quartz。脚本仅包含这两项钱包结账任务及三项支付宝转账任务。钱包任务内部沿用跨租户扫描，只保留一份调度。重启钱包仅恢复执行入口，Quartz 需加载对应 `sys_job` 行后才会周期扫描。单轮调度成功表示业务服务接受执行，资金结果继续查看逐商户付款尝试及第三方转账流水。
|