Feature Specification: OMG AIO 支付重建——创建支付与付款结果回调

Feature Branch: 020-omg-payment-rebuild

Created: 2026-08-13

Status: 创建支付已实现；付款结果回调设计已批准并进入实现

Input: 以 OMG 全方位金流 AIO 官方技术文件 V1.5.3（2026-07）为唯一外部事实来源，从零重建创建支付订单和 ReturnURL 付款结果回调；现有 OMG 支付代码、旧支付流水和 specs/016-omg-payment 均不作为需求或设计依据。查询、补单、退款与推送后续逐项重建。

1. Scope and Trust Boundary

1.1 In scope

从订单所属门店读取其独立的 MerchantID / HashKey / HashIV。
为合法、未支付的 OMG 订单创建一条全新的支付尝试。
根据 OMG 官方 AIO 规则生成完整表单和 CheckMacValue。
由客户端在当前页面以表单 POST 进入 OMG 测试收银台。
防止同一业务订单同时产生多个未结束 OMG 支付尝试。
在 POST /pay/omg/notify 接收 OMG 最终付款结果，按创建尝试的凭证快照验签并幂等更新支付事实。
在 POST /pay/omg/query 只查询订单当前有效支付尝试；可信已付款结果复用回调状态机补偿丢失回调。
提供 POST /pay/omg/refund 的测试阶段拒绝契约：明确提示测试环境不支持退款，且不调用正式网关、不改本地状态。
每次回调独立写入现有 ipn_log，并保存完整、可重放的 form-urlencoded 回传内容。
成功回调只把订单 payStatus 更新为已付款，不推进订单、配送或推送流程。
停用旧 OMG Controller 及其补单、退款、定时任务和订单取消调用入口。

1.2 Explicitly out of scope

ATM、CVS、BarcodeATM 取号结果通知及缴费信息展示。
PaymentInfoURL、ClientRedirectURL、ClientBackURL。
定时/批量自动补单、独立人工补单入口；用户触发的当前支付查询补偿属于本阶段范围。
正式环境退款动作、取消交易、信用卡关账；本阶段只实现测试环境安全拒绝入口。
分期、定期定额、记忆卡号、银联专用流程。
正式环境开放。
旧 OMG 支付流水的数据迁移、兼容或清理。
客户端页面代码；本阶段只定义客户端必须遵守的表单 POST 契约。

1.3 Trust decisions

OMG 官方 AIO 技术文件 V1.5.3 是支付协议的唯一事实来源。
旧 OmgPayController、旧 OMG 工具类、旧支付流水表和 specs/016-omg-payment 均不可信，不得复制其行为或用其解释官方文档。
唯一获准复用的旧 OMG 能力是 pos_store_omg 及其现有门店凭证存储、录入、启停和查询实现。该表只保存每个门店独立的 MerchantID / HashKey / HashIV 等凭证信息。
订单现有字段继续使用 PosOrder.payType = "2" 表示选择 OMG 支付。
旧支付表及其数据不读取、不迁移；开发者会自行删除旧表。

2. Confirmed Business Decisions

每个门店使用独立的 MerchantID / HashKey / HashIV，不使用平台统一凭证。
不传 PlatformID。
ChoosePayment 固定为 ALL，并发送 IgnorePayment=ATM#CVS#BarcodeATM；优先让 OMG 官方收银台只展示信用卡与 Apple Pay。官方公开参数不能隐藏 AFTEE，因此商户同时开通 AFTEE 时不承诺严格只剩两个渠道，必须以 stage 实测结果为准。
客户端在当前页面提交表单，不使用 iframe，不打开新窗口。
当前仅接 OMG 测试环境。
新可信公开路径继续使用 /pay/omg/*；创建入口为 POST /pay/omg/create，可信回调为 POST /pay/omg/notify。
旧 Controller 完全作废，不保留 /legacy/* 或任何其他旧 OMG 接口。
所有新实现代码放在新的 omgpay 包目录；新代码不得引用旧支付 Controller、旧签名器、旧表单工具或旧支付流水服务。
新支付尝试使用全新表 pos_order_omg_attempt。
创建时把该次尝试实际使用的 HashKey / HashIV 保存为凭证快照；回调不读取可能已被覆盖的新凭证。
ipn_log 是可信的通用 IPN 流水表，但旧 OMG 写入逻辑不可信；新回调只复用其现有表结构和通用插入 Service。

User Scenarios & Testing

User Story 1 - 首次创建并进入 OMG 收银台 (Priority: P1)

已登录用户为自己的单门店餐饮订单选择 OMG 后，调用创建接口并取得由服务端签名的表单。客户端在当前页面 POST 该表单，进入对应门店的 OMG 测试收银台；服务端通过 ALL + IgnorePayment 隐藏 ATM、CVS 和 BarcodeATM，优先保留信用卡与 Apple Pay。

Why this priority: 这是进入 OMG 收银台的基础，也是本期最终付款回调及后续查询、退款的前置能力。

Independent Test: 为测试门店配置有效测试凭证，创建一笔合法未支付订单，调用接口并提交响应表单，确认浏览器进入官方测试端点且收银台显示正确订单金额及可用渠道。

Acceptance Scenarios:

Given 用户拥有一笔 payType="2"、未取消、未付款、金额为正的单门店订单，且门店 OMG 凭证已启用，When 用户首次调用创建接口，Then 系统创建唯一支付尝试并返回可提交的 OMG 表单。
Given 创建接口返回成功，When 客户端在当前页面向 gatewayUrl POST 全部 formFields，Then 浏览器进入 OMG 测试收银台，不通过 iframe 或新窗口加载。
Given 门店已开通信用卡、Apple Pay、ATM、CVS 和 BarcodeATM，When 收银台接收 ChoosePayment=ALL 与 IgnorePayment=ATM#CVS#BarcodeATM，Then OMG 页面隐藏 ATM、CVS 和 BarcodeATM，并保留已开通的信用卡与 Apple Pay。
Given 门店还开通 AFTEE 或 OMG 未来新增且不支持 IgnorePayment 的渠道，When 进入收银台，Then 手动验收如实记录额外渠道；本方案不通过非官方参数或自有页面强行隐藏。

User Story 2 - 阻止重复创建有效付款入口 (Priority: P1)

客户创建表单后没有立即付款，再次点击支付时，系统既不重复提交旧 MerchantTradeNo，也不贸然生成新的 MerchantTradeNo。

Why this priority: ATM、CVS、BarcodeATM 可能在较长期限内仍可付款；多个有效入口可能造成重复付款。

Independent Test: 对同一订单顺序或并发调用创建接口，数据库始终只有一条未结束尝试，后续请求得到 PAYMENT_ATTEMPT_EXISTS，且不会返回第二份可提交表单。

Acceptance Scenarios:

Given 某订单已有 CREATED 尝试，When 用户再次创建，Then 返回 PAYMENT_ATTEMPT_EXISTS，不生成新 MerchantTradeNo，也不重放旧表单。
Given 同一订单同时发起多个创建请求，When 请求并发执行，Then 数据库约束和事务保证最多一条未结束尝试，其余请求得到一致的业务结果。
Given 旧尝试状态尚不明确，When 系统尚未实现可信查询，Then 不以本地时间、新鲜窗口或用户重复点击为理由释放旧尝试。

User Story 3 - 拒绝不合法或不安全的创建请求 (Priority: P1)

系统只为订单本人、合法业务状态、合法金额且门店凭证可用的测试订单创建支付尝试，并确保门店密钥不出现在响应或日志中。

Why this priority: 创建错误门店、错误金额或泄露密钥会形成直接资金风险。

Independent Test: 分别使用无效 token、他人订单、终态订单、异常金额、错误支付类型、无凭证门店和非测试网关配置调用接口，均被拒绝且不写入尝试表。

Acceptance Scenarios:

Given 请求用户不是订单所有者，When 调用创建接口，Then 系统拒绝且不透露订单或门店支付详情。
Given 订单已取消、已付款、金额不大于零、不是单门店订单或 payType 不是 "2"，When 调用创建接口，Then 系统返回国际化业务错误且不创建尝试。
Given 门店没有已启用 OMG 凭证，When 调用创建接口，Then 系统拒绝且不创建尝试。
Given 服务配置不是允许的 OMG 测试端点，When 调用创建接口，Then 系统拒绝生成表单。
Given 创建成功或失败，When 检查 API 响应和应用日志，Then 所有响应和日志均不存在 HashKey、HashIV；完整 CheckMacValue 与签名表单只存在于订单本人获准取得的创建成功响应，不出现在错误响应或日志中。

User Story 4 - 可信接收最终付款结果 (Priority: P1)

OMG 向 ReturnURL 发送最终付款结果时，系统保存本次 HTTP 回传原文，使用创建支付时的门店凭证快照验证全部实际字段，并幂等同步支付尝试与订单付款状态。

Why this priority: 创建支付后必须依靠可信 Server POST 确认资金事实；客户端跳转、旧回调和本地推测都不能证明付款结果。

Independent Test: 对同一 MerchantTradeNo 分别提交合法成功、模拟成功、合法失败、重复、失败后成功、成功后失败、金额不符、商户不符和验签失败的 form-urlencoded 请求，确认支付尝试状态、订单 payStatus、ipn_log 流水和纯文本响应符合契约。

Acceptance Scenarios:

Given 回调字段完整且签名、MerchantID、MerchantTradeNo、TradeAmt 均匹配创建快照，When RtnCode=1，Then 支付尝试标记 PAID，订单只把 payStatus 改为 1，并返回精确的 1|OK。
Given 合法成功回调的 SimulatePaid=1，When 当前系统仍处于测试阶段，Then 仍按已付款处理，同时在尝试记录和日志中保留模拟付款标记。
Given 回调验签通过但 RtnCode!=1，When 处理最终失败结果，Then 尝试标记 FAILED 并保存原始 RtnCode/RtnMsg，订单保持未付款，活动尝试被释放，返回 1|OK。
Given 同一尝试先失败后成功，When 后续成功通知到达，Then 状态从 FAILED 升级为 PAID；已 PAID 的尝试不得被后续失败通知降级。
Given 订单已取消但收到合法成功通知，When 处理真实资金事实，Then 尝试仍标记 PAID、订单仍更新为已付款，并记录严重异常日志；本阶段不自动退款。
Given 同一成功或失败通知重复到达，When 系统已处理相同事实，Then 不重复修改订单或推进业务状态，并返回 1|OK。
Given 回调无法验证或持久化，When 交易号不存在、商户/金额不符、验签失败、字段非法或业务事务失败，Then 不修改订单或支付尝试，并返回 0|ERROR 以允许 OMG 重试。
Given 任意回调请求到达，When 后续验签或业务事务失败，Then 本次完整回传内容仍以独立事务新增到 ipn_log；日志表故障不得阻断真实支付处理。

Edge Cases

支付成功回调丢失时，用户查询当前有效尝试；完整验签及商户号、交易号、金额核对后必须原子补偿为已付款。
查询返回未付款时不得修改本地状态；返回 10200095 时同步失败信息；任何查询不得把已付款降级。
查询响应新增字段或空值字段仍必须参与检查码计算，客户端不得指定要查询的 MerchantTradeNo。
测试环境调用退款时必须在任何支付/订单读取、网关 HTTP 或状态写入前失败关闭，返回稳定的环境不支持状态。
业务订单号含有不适合 OMG MerchantTradeNo 的字符时，系统使用独立生成的英数字编号，不直接拼接或截断业务订单号。
随机生成的 MerchantTradeNo 发生唯一索引冲突时，系统可在同一创建事务中重新生成；达到受控次数仍失败时整笔创建回滚。
客户端取得表单但未提交、网络中断或关闭页面时，本地只能保持 CREATED，不得宣称 OMG 已建立或未付款。
表单生成成功但尝试落库失败，或尝试落库事务最终回滚时，不得向客户端返回可提交表单。
订单或凭证在并发过程中发生变化时，最终写入必须仍满足订单合法状态、凭证归属门店和单活跃尝试约束。
TradeDesc、ItemName 不接受客户端文本，必须由服务端生成，无 HTML 标签或未经允许的特殊符号，并满足官方长度限制。
ReturnURL 必须是服务端受控的 HTTPS URL，路径固定指向新的 /pay/omg/notify；客户端不得覆盖。
表单中出现重复参数名、无法解码的 percent encoding 或超出受控大小时，按非法请求处理，避免参数污染或资源滥用。
OMG 新增未列明的回传字段时，只要请求合法，字段也必须被 DTO 边界完整捕获并参加验签；不能依赖固定字段白名单计算检查码。
同一订单存在另一笔活动尝试时，一笔成功将关闭其他活动尝试；以后若另一历史交易也收到合法成功通知，仍记录其支付事实并输出严重异常日志，不吞掉第二笔资金事实。

Requirements

Functional Requirements

FR-037: 查询接口 MUST 仅接受业务订单号并验证 token 用户归属；服务端 MUST 选择唯一当前 CREATED 尝试，已付款订单选择其首条 PAID 尝试。
FR-038: 查询 MUST 使用尝试保存的 MerchantID / HashKey / HashIV 快照向 OMG stage QueryTradeInfo/V5 发送表单请求。
FR-039: 查询响应 MUST 将全部实际回传参数（含额外与空值）纳入检查码计算，仅排除 CheckMacValue，并核对商户号、交易号与金额。
FR-040: TradeStatus=1 MUST 复用回调的锁与幂等状态机更新尝试和订单为已付款；0 MUST 不修改；10200095 MUST 同步失败；已付款 MUST 不可逆。
FR-041: 查询只返回白名单字段且不写 ipn_log；HashKey、HashIV、CheckMacValue 和完整网关响应 MUST NOT 返回客户端或写入应用日志。
FR-042: POST /pay/omg/refund MUST 需要 token，并以显式 JSON DTO 只接收 orderId；不得接收客户端提供的金额、交易号、Action、凭证或地址。
FR-043: 当前测试阶段退款 MUST 返回 PAYMENT_REFUND_UNAVAILABLE_IN_TEST_ENVIRONMENT，MUST NOT 调用 OMG 正式 CreditDetail/DoAction、查询或写入任何订单/支付/退款状态。
FR-044: 测试环境退款拒绝 MUST 提供五套 i18n 提示和必要的脱敏日志；日志不得记录 token、凭证或完整支付签名。
FR-045: 系统 MUST 提供 POST /pay/omg/retry，使用 token 和只含 orderId 的显式 JSON DTO；客户端不得提交旧 MerchantTradeNo、支付方式、金额、凭证、网关地址或旧表单。
FR-046: retry MUST 先复用可信 query 查询 OMG 实际状态；查询失败、响应不可信或状态为 UNKNOWN 时不得修改尝试或创建新表单。
FR-047: query 确认 PAID 时 retry MUST 返回 ORDER_ALREADY_PAID；确认 FAILED 时 MAY 创建新尝试；确认 UNPAID 时仅当 paymentType 为空才 MAY 替换旧尝试。
FR-048: 替换未付款尝试 MUST 在同一事务内锁定订单，精确比较 query 已验证的 MerchantTradeNo 与当前活动尝试，把该行原子更新为 SUPERSEDED 后再生成新交易号和新表单；任一条件变化 MUST 返回 PAYMENT_RETRY_NOT_AVAILABLE。
FR-049: 同一旧尝试的顺序或并发 retry MUST 最多生成一条新 CREATED 尝试；迟到的旧尝试可信成功回调仍 MUST 能升级为 PAID 并关闭更新的活动尝试。
FR-050: retry 不保存、恢复或复用 App WebView，不返回旧表单或所谓继续付款 URL；成功响应 MUST 与 create 相同并包含新 MerchantTradeNo 的新表单。
FR-001: 系统 MUST 新建 com.ruoyi.app.omgpay 下的 Controller、请求/响应 DTO、创建服务、表单生成器、签名器和配置类型；这些新类 MUST NOT 引用旧 OmgPayController、旧 OmgPay、旧 OmgCheckMacValue 或旧 OMG 支付流水服务。
FR-002: 系统 MUST 新建 com.ruoyi.system.omgpay 下的支付尝试 Entity、Mapper 和 Service；新支付尝试 MUST 使用 pos_order_omg_attempt，不得读取或写入旧 OMG 支付流水表。
FR-003: 系统 MAY 复用现有 pos_store_omg 门店凭证查询实现，且这是唯一允许复用的旧 OMG 实现；新创建流程 MUST 按订单门店读取该门店已启用的 MerchantID / HashKey / HashIV。
FR-004: 系统 MUST 保持公开创建入口为 POST /pay/omg/create，使用 @RequestHeader String token 和显式 @RequestBody DTO；Controller 入参不得使用 Map，DTO 不使用 Bean Validation 注解。
FR-005: 创建请求 DTO MUST 只接收 orderId；金额、门店、用户、支付类型、说明文字、网关地址、回调地址和支付渠道均必须由服务端决定。
FR-006: 系统 MUST 校验登录用户为订单所有者，订单为单门店订单、未取消、未付款、未完成、金额为正且 PosOrder.payType="2"；任何校验失败 MUST NOT 创建支付尝试。
FR-007: 系统 MUST 使用订单的整数新台币金额作为 TotalAmount，不得接受或信任客户端金额。
FR-008: 系统 MUST 仅允许创建表单到 https://payment-stage.funpoint.com.tw/Cashier/AioCheckOut/V5；第一阶段不得配置或回退到正式环境。
FR-009: 系统 MUST 为每次新尝试生成全局唯一、不可复用、长度不超过 20 且只含 ASCII 英数字的 MerchantTradeNo；不得从业务订单号直接派生可冲突或超长的编号。
FR-010: 同一业务订单在任一时刻 MUST 最多存在一条未结束 OMG 尝试；顺序重复或并发创建 MUST 返回业务状态 PAYMENT_ATTEMPT_EXISTS，不得返回旧表单、重复提交旧编号或创建新编号。
FR-011: 在可信查询尚未实现前，系统 MUST NOT 基于固定分钟窗口、本地创建时间或用户再次点击自动结束 CREATED 尝试。
FR-012: 创建表单 MUST 发送以下字段和值：MerchantID、MerchantTradeNo、MerchantTradeDate、PaymentType=aio、TotalAmount、TradeDesc、ItemName、ReturnURL、OrderResultURL、ChoosePayment=ALL、IgnorePayment=ATM#CVS#BarcodeATM、EncryptType=1、InvoiceMark=N、NeedExtraPaidInfo=Y 和 CheckMacValue。
FR-013: 创建表单 MUST NOT 发送 PlatformID、PaymentInfoURL、ClientRedirectURL、ClientBackURL、Language、UnionPay、ATM/CVS/BarcodeATM 期限字段、分期、定期定额或记忆卡号参数。
FR-014: MerchantTradeDate MUST 以 Asia/Taipei 时区格式化为 yyyy/MM/dd HH:mm:ss。
FR-015: TradeDesc 和 ItemName MUST 由服务端生成，禁止 HTML，符合 OMG 字符及长度限制；ItemName 不得超过中文 60 字或英数字 120 字的官方显示限制，字段总长度不得超过官方 String(200) 限制。
FR-016: ReturnURL MUST 是受控 HTTPS 地址并固定以 /pay/omg/notify 结尾；该路径 MUST 由新的 omgpay Controller 处理，不得被旧 Controller 接收。
FR-017: CheckMacValue MUST 严格按 OMG 官方规则生成：排除 CheckMacValue 本身，将其余全部实际发送字段按官方字母顺序排序，以 & 串接，前置 HashKey=...&、后置 &HashIV=...，执行符合官方 .NET 表的 URL 编码并转小写，使用 SHA-256，最后输出大写十六进制。
FR-018: 除 CheckMacValue 自身外，创建请求实际发送的全部字段 MUST 参加签名，包括 OrderResultURL、ChoosePayment=ALL、IgnorePayment=ATM#CVS#BarcodeATM 和 NeedExtraPaidInfo=Y；不得挑选所谓核心字段计算。
FR-019: 回调 MUST 遵守同一完整字段原则：除 CheckMacValue 外，OMG 实际返回的全部字段均参加验签；启用 NeedExtraPaidInfo=Y 后，全部额外回传字段、未知字段及空值字段也必须进入验签集合。重复参数名必须作为非法请求拒绝，不得静默选取其中一个值。
FR-020: 创建成功响应 MUST 使用明确对象 {status, gatewayUrl, formFields}；status 固定为 CREATED，gatewayUrl 为测试 AioCheckOut 端点，formFields 含实际需要 POST 的全部字段但不含 gatewayUrl。
FR-021: 客户端 MUST 在当前页面以 application/x-www-form-urlencoded 表单 POST 全部 formFields 到 gatewayUrl；不得使用 iframe，不得另开新窗口，不得把响应转换为 GET 查询链接。
FR-022: 支付尝试 MUST 保存创建时实际使用的 HashKey / HashIV 快照，确保门店凭证被覆盖或停用后仍可验证在途交易；不得保存完整创建表单。完整回调内容保存到现有 ipn_log，不新增该表字段。
FR-023: 创建接口和创建日志 MUST NOT 输出登录 token、HashKey、HashIV。回调入口按已批准的排障策略 MUST 在应用日志和 ipn_log.ipn_log 直接记录完整回传内容，包括完整 MerchantTradeNo、TradeNo、额外参数、空值和 CheckMacValue；任何日志均不得输出数据库中的 HashKey / HashIV。
FR-024: 业务校验错误 MUST 使用项目国际化机制，不得硬编码单一语言错误；新增错误 key 必须同步 vi/zh/tw/en 支持来源。
FR-025: 旧 OmgPayController MUST 取消 Spring Controller 身份且所有旧接口不可访问；不得保留 legacy 路径。
FR-026: 旧 OMG 定时补单任务、订单取消链路中的旧 OMG 退款调用、旧管理端 OMG 补单/退款接口和其他对旧 Controller 的运行时调用 MUST 一并停用或移除；不得影响非 OMG 订单取消及其他支付通道。
FR-027: 旧 OMG 支付及退款表 pos_order_omg_payment、pos_order_omg_refund MUST 通过 updatesql/sql.md 登记删除，任何可达运行链路和源码 MUST NOT 再查询或写入这些旧表。pos_store_omg 凭证表不属于该禁用范围。
FR-028: 所有新建表、索引或约束 SQL MUST 只追加到 updatesql/sql.md，实现过程不得执行数据库变更。
FR-029: 创建与回调 MUST 保持测试环境边界，验收不得把旧回调或旧查询结果当成新流程成功证据。
FR-030: 新 omgpay 代码 MUST 包含标准且必要的注释：公开类型说明职责和安全边界；协议字段、检查码编码、事务与数据库唯一约束等非显然逻辑说明“为什么”；不为显然的赋值、访问器或框架样板添加重复注释。注释不得包含真实凭证、完整签名原文或可用测试秘密。
FR-031: 新创建流程 MUST 使用项目日志框架输出足够的结构化排障上下文。创建开始记录业务订单号和请求用户标识；校验通过后记录门店 ID；落库成功记录支付尝试 ID、业务订单号、门店 ID、金额、状态和脱敏 MerchantTradeNo；业务拒绝记录稳定业务错误码及已有的安全上下文；非预期异常记录相同安全上下文并保留服务端异常堆栈。不得以拼接整份 DTO、凭证对象或表单对象的方式记录日志。
FR-032: POST /pay/omg/notify MUST 是无需登录 token 的第三方 form-urlencoded 接口，Controller MUST 使用明确 DTO 作为唯一业务入参，不得使用 Map 或 HttpServletRequest 作为 Controller 入参。DTO 边界 MUST 保留全部实际参数、空值、原始可重放表单内容和请求 IP。
FR-033: 每次回调 MUST 先以独立事务向现有 ipn_log 新增一行：type="omg"、ip 为请求来源、cretim 为接收时间、ipn_log 为完整可重放 form-urlencoded 内容。该写入失败只记录应用错误日志，不得阻断后续验签与付款处理。
FR-034: 回调 MUST 先按 MerchantTradeNo 读取并锁定新支付尝试，再使用该尝试的 HashKey / HashIV 快照验签；不得只凭请求 MerchantID 选择密钥，也不得使用门店当前可能已变更的凭证。
FR-035: 验签成功后 MUST 同时校验请求 MerchantID、MerchantTradeNo、TradeAmt 与尝试快照完全一致。交易号不存在、字段缺失/格式非法、商户或金额不符、验签失败及业务事务异常 MUST NOT 修改订单或尝试，并返回纯文本 0|ERROR。
FR-036: 当 RtnCode=1 时，无论 SimulatePaid 为 0 或 1，系统 MUST 把尝试标记 PAID 并保存网关交易事实；订单仅把 pay_status 从未付款改为已付款，不得修改 state、delivery_status 或触发接单、出餐、完成、推送、退款。
FR-037: 当验签通过且 RtnCode!=1 时，系统 MUST 把非 PAID 尝试标记 FAILED，原样保存 RtnCode/RtnMsg 并释放活动尝试；订单保持未付款，下一次创建支付生成新的 MerchantTradeNo。
FR-038: 回调状态 MUST 成功优先且不可逆：CREATED/FAILED -> PAID，CREATED -> FAILED，PAID 不得降级。重复通知不得重复改变订单；正确处理或已处理的通知均返回精确 1|OK。
FR-039: 合法成功通知到达时，即使订单已取消也 MUST 记录付款事实并把订单 pay_status 更新为 1；系统 MUST 输出异常日志，但本阶段不得自动退款。
FR-040: 一笔尝试成功后 MUST 关闭同订单其他仍活动的尝试。若历史尝试后来也收到合法成功通知，仍 MUST 记录第二笔付款事实并输出严重异常日志，不得因本地单活跃约束丢弃真实资金通知。
FR-041: 支付尝试 MUST 保存 trade_no、rtn_code、rtn_msg、payment_type、payment_date、trade_date、payment_type_charge_fee、simulate_paid 和 last_notify_time；完整逐次回调原文只保存于 ipn_log。trade_no 非空时全局唯一，防止同一 OMG 交易被绑定到多个本地尝试。
FR-042: 旧 com.ruoyi.app.utils.omg 工具包及其测试 MUST 删除。可信门店凭证录入保留原表与管理流程，但联网验证 MUST 迁入新的 com.ruoyi.app.omgpay，并复用 rebuild 的签名、严格响应解析和 stage 查询边界。
FR-043: specs/016-omg-payment 和历史建表 SQL MUST 作为变更记录保留，但不得再作为运行实现依据；旧表删除只能追加新迁移记录，不改写或移除历史 SQL。

API Contract

Request

POST /pay/omg/create
Content-Type: application/json
token: <login-token>

{
  "orderId": "991786433092835"
}

Success data

{
  "status": "CREATED",
  "gatewayUrl": "https://payment-stage.funpoint.com.tw/Cashier/AioCheckOut/V5",
  "formFields": {
    "MerchantID": "1000031",
    "MerchantTradeNo": "OMGR8K3P7W2M9C4X6A1B",
    "MerchantTradeDate": "2026/08/13 15:30:23",
    "PaymentType": "aio",
    "TotalAmount": "100",
    "TradeDesc": "Food order 991786433092835",
    "ItemName": "Order 991786433092835",
    "ReturnURL": "https://example.test/pay/omg/notify",
    "OrderResultURL": "https://example.test/pay/omg/result",
    "ChoosePayment": "ALL",
    "IgnorePayment": "ATM#CVS#BarcodeATM",
    "EncryptType": "1",
    "InvoiceMark": "N",
    "NeedExtraPaidInfo": "Y",
    "CheckMacValue": "<64 uppercase hexadecimal characters>"
  }
}

HashKey 和 HashIV 永远不属于响应。外层继续使用项目现有 AjaxResult 成功/失败封装；上例只定义 data 契约。

Existing-attempt failure

外层返回项目业务失败响应。
机器可识别业务状态为 PAYMENT_ATTEMPT_EXISTS。
不返回旧 formFields 或新的 MerchantTradeNo。

Key Entities

`OmgPaymentAttempt` / `pos_order_omg_attempt`

表示本次重建产生的一次不可覆盖的 OMG 支付尝试。创建和最终付款回调字段如下：

Field	Meaning	Constraint
`id`	本地支付尝试主键	自增主键
`dd_id`	`pos_order.dd_id` 业务订单号	非空
`merchant_trade_no`	本次 OMG 特店交易编号	非空、全局唯一、≤20 位英数字
`store_id`	创建时订单门店	非空
`merchant_id`	创建时门店 MerchantID 快照	非空、≤10 位
`amount`	创建时订单整数 TWD 金额快照	非空、>0
`hash_key_snapshot`	创建时 HashKey 快照	非空，不得输出到日志或 API
`hash_iv_snapshot`	创建时 HashIV 快照	非空，不得输出到日志或 API
`attempt_status`	本地事实状态	`0=CREATED, 1=PAID, 2=FAILED, 3=SUPERSEDED`
`active_dd_id`	单活跃约束生成列	`attempt_status=0` 时为 `dd_id`，否则为 `NULL`
`trade_no`	OMG 金流交易编号	可空；非空时全局唯一
`rtn_code` / `rtn_msg`	OMG 原始结果码及说明	可空，不维护固定错误码枚举
`payment_type`	OMG 回覆付款方式	可空
`payment_date` / `trade_date`	OMG 付款及建单时间	可空，Asia/Taipei 语义
`payment_type_charge_fee`	OMG 回传手续费	可空
`simulate_paid`	模拟付款标记	可空；`1` 仍按已付款处理
`last_notify_time`	最近一次合法通知处理时间	可空
`create_time`	本地创建时间	非空
`update_time`	本地更新时间	非空

约束：

UNIQUE (merchant_trade_no)；
UNIQUE (active_dd_id)，利用 MySQL 唯一索引允许多个 NULL 的语义，为后续终态释放活跃键；
CREATED 只表示本地已生成并持久化表单所需事实，不能解释为 OMG 已接收或已建立订单；
PAID 是不可逆资金事实；FAILED 可被后续合法成功通知升级为 PAID；SUPERSEDED 表示同订单已有其他尝试成功，并非 OMG 返回的支付失败；
回调保存归一化最终事实，逐次完整请求历史由 ipn_log 承载。

Existing `PosStoreOmg` / `pos_store_omg`

可信门店凭证来源。不修改其表结构、录入流程或启停流程。创建服务读取与订单 storeId 对应、已启用的 MerchantID / HashKey / HashIV，并把密钥写入本次尝试快照；回调不再依赖门店当前行。

Existing `IpnLog` / `ipn_log`

每个回调 HTTP 请求新增一行，不新增字段：ip 保存来源地址，cretim 保存接收时间，type 固定为 omg，ipn_log 保存完整原始 form-urlencoded 请求体。该流水使用独立事务，后续业务回滚不删除已经接收的通知记录。

3. Error Handling and Security

创建流程必须在返回表单前完成所有订单、凭证、环境和并发校验。
尝试记录与订单合法性必须处于可证明的一致事务边界；事务失败不得泄出可提交表单。
数据库唯一约束是并发安全的最终防线；应用锁只能作为降低冲突的辅助机制，不能取代唯一约束。
PAYMENT_ATTEMPT_EXISTS 是安全终止，不是系统异常，也不能自动删除或覆盖已有行。
外部网关地址和 ReturnURL 必须由服务端配置并严格校验，不接受客户端 URL，防止开放重定向或向非 OMG 主机泄露签名表单。
HashKey / HashIV 只在服务端签名过程中短暂使用；不得复制到新支付尝试表。
API 错误不返回堆栈、SQL、密钥、签名原文或内部类名。
旧 Controller 下线后，/pay/omg/create 只能由新 omgpay Controller 映射；/pay/omg/notify 在下一阶段前必须没有旧处理器。
日志级别必须有一致语义：正常阶段事件使用 INFO，可预期的业务拒绝使用 WARN，非预期且需要调查的异常使用 ERROR 并携带异常对象；单元测试可依赖稳定业务错误码，不依赖自然语言日志文本。
日志中的 MerchantTradeNo 只显示足以关联记录的首尾片段；如果应用已有 trace/request ID，则沿用现有上下文，不自行生成新的支付追踪体系。

4. Verification Requirements

4.1 Automated tests

使用 OMG 官方 AioCheckOut 示例参数和官方期望 CheckMacValue 验证完整 SHA-256 签名链路；不得用旧实现测试或其他金流向量代替官方依据。
验证字段排序、HashKey/HashIV 包夹、.NET URL 编码替换、转小写、SHA-256 和大写十六进制各步骤。
验证实际发送字段集合与签名输入集合完全一致；删除、增加或修改任一非 CheckMacValue 字段都会改变签名。
验证回调所有实际字段、未知额外字段和空值字段均进入签名集合，只有 CheckMacValue 被排除。
验证 ipn_log 在验签失败和业务事务回滚时仍独立保留，且日志写入失败不阻断付款处理。
验证成功、模拟成功、失败、失败后成功、成功后失败、重复通知、取消后成功和同订单迟到第二笔成功的状态机。
验证 MerchantTradeNo 仅含英数字、长度不超过 20、重复冲突不会覆盖旧行。
验证台北时区与 yyyy/MM/dd HH:mm:ss 格式。
验证固定字段和值、禁止字段不出现在表单、金额只取订单、文字字段安全和长度限制。
验证 token、订单归属、单门店、业务状态、payType="2"、金额和门店凭证校验。
验证非测试网关和不合法 ReturnURL 被拒绝。
验证顺序重复和真实并发创建最多产生一条 CREATED 尝试。
验证所有响应和日志均不包含登录 token、HashKey 或 HashIV；完整 CheckMacValue 与签名表单只出现在创建成功响应，不出现在错误响应或日志中。
验证创建开始、校验拒绝、创建成功、重复尝试和非预期异常路径均输出规定的排障上下文与正确日志级别，同时不记录 token、凭证对象、DTO 或表单对象。
通过定向代码审查验证新公开类型、签名编码、事务和唯一约束处理具有必要注释，且没有对显然代码的噪声注释。
验证旧 Controller 不再注册，旧定时任务不再调度，旧补单/退款接口和取消链路调用不可达。
验证删除旧 OMG 支付/退款表后，当前有效运行链路不包含对这些旧表的 Mapper/Service 调用；门店凭证 pos_store_omg 查询保持可用。

所有新增生产方法必须遵循测试先行：先运行定向测试并观察其因缺少新行为而失败，再写最小实现使其通过。

4.2 Module verification

临时使用 C:\Users\qmj\.jdks\graalvm-jdk-21.0.7 设置当前命令的 JAVA_HOME 和 PATH。
运行新 omgpay 测试及受旧链路下线影响的订单回归测试。
运行 ruoyi-admin 及其依赖模块的 JDK 21 Maven 构建。
检查 git diff，确认未改动旧凭证能力、未重写无关文件、未引入编码或换行噪音。

4.3 OMG stage acceptance

使用门店测试凭证调用 POST /pay/omg/create。
在当前页面将全部 formFields POST 到返回的测试 gatewayUrl。
确认进入 OMG 测试收银台，金额、商品说明和 ALL 可用渠道显示正确。
确认不使用 iframe 或新窗口。
创建和付款结果回调按本规格完成；查询、补单、取号、退款与推送不作为本阶段完成标准。

Success Criteria

Measurable Outcomes

SC-001: 合法首次创建请求 100% 返回固定测试端点和完整签名表单，并可进入 OMG 测试收银台。
SC-002: 官方 AioCheckOut 签名向量自动化测试与官方 CheckMacValue 完全一致。
SC-003: 实际发送的每一个非 CheckMacValue 字段均由测试证明参与签名，额外字段与空值字段不会被签名器丢弃。
SC-004: 对同一订单进行顺序或并发重复创建时，数据库未结束尝试数始终不超过 1，第二个 MerchantTradeNo 产生率为 0。
SC-005: 未授权、非法状态、非法金额、错误支付类型、无凭证和非测试环境请求的尝试写入数为 0。
SC-006: 新 OMG 创建链路中对旧支付 Controller、旧工具类和旧支付流水服务的引用数为 0；对旧支付表的 SQL 访问数为 0。
SC-007: 旧 OMG Controller、旧补单/退款入口和旧定时任务的可达运行入口数为 0；/pay/omg/create 只映射到新 Controller。
SC-008: API 响应及应用日志中的登录 token、HashKey、HashIV 泄露数为 0；错误响应和应用日志中的完整 CheckMacValue 或完整签名表单泄露数为 0。
SC-009: 受影响的自动化测试和 JDK 21 模块构建均以退出码 0 完成。
SC-010: 创建开始、创建成功、业务拒绝和非预期异常均可通过业务订单号及安全的支付尝试上下文定位；敏感信息日志泄露数为 0，非预期异常堆栈保留率为 100%。
SC-011: 新 omgpay 的公开类型、签名编码、事务和数据库并发边界均有必要注释，显然样板代码上的重复注释数为 0。
SC-012: 生产源码中旧 com.ruoyi.app.utils.omg 类定义、导入和调用数为 0；旧支付/退款表没有运行 SQL，测试源码只允许用类名或表名做退役断言。
SC-013: 已验证的 UNPAID + paymentType 为空 重试 100% 使用新 MerchantTradeNo；同一旧尝试并发重试时新活动尝试数不超过 1，旧表单重放次数为 0。

Assumptions

pos_order.dd_id 是客户端使用的业务订单号，PosOrder.mdId 能唯一定位单门店订单的门店。
PosOrder.amount 是当前订单应支付的整数新台币金额。
pos_store_omg 的既有启用凭证查询能按 storeId 返回正确门店凭证。
测试环境使用 OMG 官方公开的 AIO stage 端点；正式环境切换将在可信回调及后续流程完成后单独设计和批准。
新表 SQL 由开发者手动执行；代码实现不会连接数据库执行 DDL。
App 退出原支付页面后会销毁 WebView；重新支付必须调用 retry 获取新表单，不要求保存或恢复原 WebView。

spec.md 39 KB

History Raw

Feature Specification: OMG AIO 支付重建——创建支付与付款结果回调

1. Scope and Trust Boundary

1.1 In scope

1.2 Explicitly out of scope

1.3 Trust decisions

2. Confirmed Business Decisions

User Scenarios & Testing

User Story 1 - 首次创建并进入 OMG 收银台 (Priority: P1)

User Story 2 - 阻止重复创建有效付款入口 (Priority: P1)

User Story 3 - 拒绝不合法或不安全的创建请求 (Priority: P1)

User Story 4 - 可信接收最终付款结果 (Priority: P1)

Edge Cases

Requirements

Functional Requirements

API Contract

Request

Success data

Existing-attempt failure

Key Entities

`OmgPaymentAttempt` / `pos_order_omg_attempt`

Existing `PosStoreOmg` / `pos_store_omg`

Existing `IpnLog` / `ipn_log`

3. Error Handling and Security

4. Verification Requirements

4.1 Automated tests

4.2 Module verification

4.3 OMG stage acceptance

Success Criteria

Measurable Outcomes

Assumptions

Official Sources

spec.md 39 KB History Raw

Feature Specification: OMG AIO 支付重建——创建支付与付款结果回调

1. Scope and Trust Boundary

1.1 In scope

1.2 Explicitly out of scope

1.3 Trust decisions

2. Confirmed Business Decisions

User Scenarios & Testing

User Story 1 - 首次创建并进入 OMG 收银台 (Priority: P1)

User Story 2 - 阻止重复创建有效付款入口 (Priority: P1)

User Story 3 - 拒绝不合法或不安全的创建请求 (Priority: P1)

User Story 4 - 可信接收最终付款结果 (Priority: P1)

Edge Cases

Requirements

Functional Requirements

API Contract

Request

Success data

Existing-attempt failure

Key Entities

OmgPaymentAttempt / pos_order_omg_attempt

Existing PosStoreOmg / pos_store_omg

Existing IpnLog / ipn_log

3. Error Handling and Security

4. Verification Requirements

4.1 Automated tests

4.2 Module verification

4.3 OMG stage acceptance

Success Criteria

Measurable Outcomes

Assumptions

Official Sources

spec.md 39 KB

History Raw

`OmgPaymentAttempt` / `pos_order_omg_attempt`

Existing `PosStoreOmg` / `pos_store_omg`

Existing `IpnLog` / `ipn_log`