foodie-server/specs/019-line-pay/rider-flash-online-spec.md

闪送用户向接单骑手支付 LINE Pay：增量规格

日期：2026-10-10。状态：实现中（本地已验证，未提交）。分支：当前 test-202609v2，不创建或切换分支。

目标与边界

平台配置骑手自己的 LINE Pay Online 凭证；闪送用户在骑手接单后直接向该骑手付款。平台不代收，不引入钱包结算。普通外卖继续由用户付款给商家、商家取餐时给骑手配送费，本增量不调整该流程。

骑手以个人身份开通 Online API 是业务方确认的接入前提；测试凭证与生产商户开通分别验收。App 不在修改范围，只交付接入文档。

用户场景与验收

US-R1 平台维护骑手支付配置（P1）

平台选择真实骑手，维护 channelId、channelSecret、环境及启用状态。沿用现有门店配置的权限与校验模式，但保存到独立骑手凭证记录，不混入门店配置。

1. 非骑手账号不能建立骑手收款配置；无权限的平台用户不能读取或修改配置。
2. 新凭证校验失败保留原有效配置；轮换不覆盖历史版本。
3. 列表不返回 channelSecret；密钥不能进入普通日志、网关原文审计、测试样例或接入文档。详情的授权回显策略沿用现有门店配置，不额外改变全项目的密钥保存策略。保存凭证绕过通用 sessionStorage 重复提交缓存，页面保留防重复点击。
4. 禁用配置阻止新的支付请求；已有交易仍能使用原凭证查询和处理退款，不切换到新密钥。
5. 服务端环境必须与实际网关地址严格匹配，错配时骑手凭证探测及闪送资金调用均拒绝，不把生产凭证错误标为 Sandbox。

US-R2 接单后发起支付（P1）

用户选择 payType="3" 创建闪送订单，订单仍先处于待接单；接单成功后用户发起支付。

1. 未接单、他人订单或已取消订单在网关调用前拒绝支付。
2. 用户仅传订单标识及必要支付操作参数；骑手、金额、TWD 币种和凭证版本取自后端事实。
3. 只有已启用有效骑手凭证且接受该支付方式的骑手才能接 LINE Pay 订单；待抢列表与接单接口保持一致，接口重新校验。用户下单尚未确定骑手时，不要求用户指定骑手凭证。
4. 同一订单最多一条阻断性活跃支付尝试。重复请求返回已有尝试；超时或结果未知时只读核实，不盲目创建第二次扣款请求。
5. 接单后不新增改价或追加支付能力，保留现有仅待接单可改址、加小费的约束。

US-R3 服务端确认支付后取件（P1）

1. 浏览器回跳或 App 上报成功不构成支付事实。后端经 LINE Pay 确认或查询，核对交易、订单、金额及币种后，才能写入已支付。
2. 未支付、认证中、结果未知或异常待核对时，单点取件及任意站点取件都拒绝；多站点订单即使主状态仍为 ACCEPTED，也不得绕过检查。
3. 骑手手工确认收款不能将 LINE Pay 订单标记为支付成功；现金及线下转账原确认入口保持原行为。
4. 重复回跳、重复查询及恢复任务只落一次资金事实；不在支付确认时重复写订单完成收入账单。

US-R4 取消与资金闭环（P1，2026-10-10 用户确认）

现状：用户仅可在任意站点实际取件前取消；平台原先支持取件后异常取消。此次收紧平台权限，不再允许用户或平台取消任意站点已经取件的订单；当前闪送取消没有线上支付退款，需要在本增量补齐。

已确认规则：

• 任意站点取件前取消：已经支付的 LINE Pay 订单自动全额退款；尚未完成支付但网关结果未知的订单先核实，若查到真实扣款则补偿退款，不把未知状态当作未扣款。
• 任意站点取件后：用户和平台取消接口均拒绝。以实际站点已取件事实判定，不等待主状态进入 PICKED_UP；已送达及已完成同样禁止取消。
• 此取消限制适用于全部闪送支付方式，不仅 LINE Pay。现金和线下转账的收款流程不变。
• 损坏、丢失或无法送达由客服人工处理，不通过取消接口关闭订单，不自动退款；本期不新增客服工单、部分退款、取件后异常关闭或取消费用功能。
• 支付与退款分别记录事实；退款失败或未知时保留可追踪状态并恢复核实，不把订单 CANCELLED 等同于已退款。
• 用户及平台取消、各站点取件、支付成功落库共用订单级并发保护；先锁订单再检查最新站点事实。取件先成功则取消失败，取消先成功则取件失败；取消后的迟到付款只能进入退款补偿，不能恢复履约。

验收：单站已取、多站仅已取 1/N 站、旧订单主状态为 PICKED_UP 或 DELIVERED 均拒绝用户和平台取消；全部未取的合法非终态订单可取消。平台按钮根据服务端取消资格展示，不能仅根据主状态判断；直接调用接口同样拒绝。取消与取件并发最终只能有一个成功，不产生“已取件又取消”的订单。

数据与组件边界

• 骑手凭证：骑手 ID、环境、凭证版本、启用和校验状态；支付引用不可变版本，轮换不破坏历史交易。
• 闪送支付尝试：闪送订单 ID、收款骑手、凭证版本、服务端金额和币种、LINE 订单号/交易号、活跃键、支付事实及时间。不使用外卖订单 ID 关联闪送交易。
• 退款意图及事实：取件前取消创建唯一全额退款意图，关联原支付和原凭证，不覆盖历史已付款事实；不得以退款结果未知为由重复提交资金副作用。
• SDK 的签名、客户端及只读凭证校验能力复用；外卖支付编排不直接套用于闪送，不为本增量重构 OMG 或废弃支付代码。
• 保持 ruoyi-admin 到 ruoyi-system 的依赖方向。Controller 显式 DTO/参数与 token 注解；业务错误及平台页面提供项目四语。
• 数据库变更只登记到 updatesql/sql.md，由开发者手动执行；本次不连接数据库执行迁移。

注释与交付要求

注释说明“为什么”：为何锁定收款骑手及凭证版本、为何未知结果不能重扣、为何回跳不能作为付款凭据、为何每个取件入口都要校验、为何取消仍需核实资金、为何多站点只取一站就禁止平台取消。涉及支付副作用的竞态、条件更新及补偿边界必须有注释，不仅复述方法名。

前端接入文档应包含下单 payType、接单后的支付入口、支付查询与回跳、未支付取件错误、支付/退款状态含义及重试限制；不提供真实密钥，不要求 App 上传密钥。

验证与完成条件

• 定向测试覆盖权限、收款方防伪、凭证轮换、重复支付、未知结果、可信支付确认、多站点取件及现金/转账兼容。
• 取消退款测试纳入同一交付，覆盖单站、多站部分取件、历史状态、取消/取件竞态、取消后的迟到支付与退款未知结果，不以数据库改状态替代真实退款。
• 执行 JDK 21 受影响模块构建、平台页面定向检查及四语核对；真实 Sandbox/生产验证不可用时明确列为未执行。
• 交付前检查 diff、编码、换行和文件范围，不混入工作区原有修改。未运行验证不得宣称已验证，未提交不得宣称已提交。

后续流程

按 spec-kit 的 specify → plan → tasks → implement 推进：用户已确认本会话原地执行计划，顺延任务 T061 至 T065。本地 1140 项后端测试、16 项平台行为测试与两端构建通过，独立审查 5 项重要问题已回归修复；详情见 tasks.md。未执行数据库迁移、真实 MySQL 并发或真实资金联调，未修改 App，未提交/推送。