plan.md 6.1 KB
Implementation Plan: OMG（歐買尬/FunPoint）AIO 支付接入
Branch: （待创建，暂未建分支/未提交） | Date: 2026-07-29 | Spec: spec.md
Input: Feature specification from /specs/016-omg-payment/spec.md
Summary
接入台湾 OMG（歐買尬，金流引擎 FunPoint）AIO 幕前支付作为餐饮订单的在线支付，替代蓝新 NewebPay（不再启用）。OMG 用 CheckMacValue(SHA256) 单字段签名（无 AES、无解密），支持全部支付方式（信用卡/Apple Pay/ATM/超商/BarcodeATM/AFTEE，ChoosePayment=ALL），门店级凭证，本期含信用卡退款。OMG 全部代码独立新建，不复用任何蓝新金流代码/表；仅复用平台共享基础设施（订单状态机、推送、订单日志）。
技术决策与备选见 research.md，表结构见 data-model.md，接口契约见 contracts/api.md，验证场景见 quickstart.md。
Technical Context
Language/Version: Java 21（Spring Boot 3 / RuoYi-Vue-Plus，MyBatis-Plus，Lombok）
Primary Dependencies: Spring Boot、MyBatis-Plus（@TableName/@TableId，XML mapper）、Apache HttpClient 4（幕后 POST QueryTradeInfo/DoAction）、fastjson2、@Anonymous/PermitAllUrlProperties（回调白名单）
Storage: MySQL（新增 pos_store_omg / pos_order_omg_payment / pos_order_omg_refund 三表，DDL 写 updatesql/sql.md 不直接执行；pos_order 不改结构，仅扩展 pay_type="7"）
Testing: 工具类 main 自测（CheckMacValue 用官方示例值复算）+ 测试环境端到端（测试卡，见 quickstart.md）；项目无统一自动化测试框架约定
Target Platform: Linux server（后端服务），配合 uni-app 用户端 Form Post 跳转 OMG 收银台
Project Type: web-service（后端）
Performance Goals: 发起支付接口 < 1s；回调核销幂等无重复发货
Constraints: CheckMacValue 必须与 OMG 完全一致（含 .NET 风格 URL 编码与小写）；回调须回纯串 1|OK；门店级凭证；InvoiceMark=N（发票走 ezPay 解耦）；外部 HTTP 工具类须放 ruoyi-admin（模块依赖 admin→system 不可反向）
Scale/Scope: 全平台餐饮订单在线支付（旅游·机票 015 后续衔接，不在本期）
Constitution Check
GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.
.specify/memory/constitution.md 为未填写模板（占位符），无实际治理原则可校验。改为遵循项目 CLAUDE.md 与记忆中的硬约束：
| 约束 | 本期遵守 |
|---|---|
| 模块依赖 admin→system 不可反向 | ✅ OMG 外部 HTTP/签名工具类放 ruoyi-admin/.../app/utils/omg/，联网验证在 Controller 层；实体/Service/Mapper 放 ruoyi-system |
| 外部 HTTP 工具类（httpclient4+fastjson2）放 admin | ✅ OmgPay/OmgCheckMacValue 在 admin |
| 后端文件 CRLF | ✅ 新建 Java/md 文件保持 CRLF |
DB 变更写 updatesql/sql.md 不直接执行 |
✅ 三表 DDL 写入，不执行 |
| 前端新功能必须 i18n | 本期后端为主；若涉及前端支付跳转/结果页文字，按规范加 4 语言 |
| 范围控制 / 简单优先 | ✅ 不复用蓝新、不抽公共支付套件（仅一个使用点） |
| OMG 不复用蓝新代码（用户新增） | ✅ 零 newebpay import，独立凭证/流水/退款表 |
结论：无违规，Phase 0 可继续。Phase 1 设计后再次确认无蓝新耦合。
Project Structure
Documentation (this feature)
specs/016-omg-payment/
├── plan.md # 本文件
├── research.md # Phase 0：技术决策
├── data-model.md # Phase 1：表结构 + DDL
├── quickstart.md # Phase 1：端到端验证
├── contracts/
│ └── api.md # Phase 1：OMG 外部接口 + 平台内部接口
└── tasks.md # Phase 2 (/speckit-tasks 生成，本阶段不创建)
Source Code (repository root)
ruoyi-admin/src/main/java/com/ruoyi/app/
├── utils/omg/ # OMG 专属，零 newebpay 依赖
│ ├── OmgCheckMacValue.java # CheckMacValue(SHA256) 生成/校验 + main 自测
│ ├── OmgPayConfig.java # MerchantID / HashKey / HashIV
│ └── OmgPay.java # HTTP 客户端：createAioForm / queryTrade / doAction
├── pay/
│ └── OmgPayController.java # /pay/omg/{create,notify,return,paymentInfo}（US1/US2/US3）
└── mendian/
└── PosStoreOmgController.java # /system/storeOmg/* 凭证开通管理（US5）
ruoyi-system/src/main/java/com/ruoyi/system/
├── domain/
│ ├── PosStoreOmg.java # 门店 OMG 凭证（pos_store_omg）
│ ├── PosOrderOmgPayment.java # OMG 支付流水（pos_order_omg_payment）
│ ├── PosOrderOmgRefund.java # OMG 退款记录（pos_order_omg_refund）
│ ├── vo/PosStoreOmgVo.java
│ └── dto/StoreOmgCredentialDto.java
├── mapper/
│ ├── PosStoreOmgMapper.java (+xml)
│ ├── PosOrderOmgPaymentMapper.java (+xml)
│ └── PosOrderOmgRefundMapper.java (+xml)
└── service/
├── IPosStoreOmgService.java + impl
├── IPosOrderOmgPaymentService.java + impl
└── IPosOrderOmgRefundService.java + impl
updatesql/sql.md # 追加三表 DDL（2026-07-29）
application.yml (+application-dev.yml) # 新增 omg.* 配置段
Structure Decision：沿用项目既有分层（utils 在 ruoyi-admin/.../app/utils/omg/，domain/mapper/service 在 ruoyi-system，Controller 在 ruoyi-admin/.../app/{pay,mendian}），与 ezPay/newebpay 同构但独立包/独立类/独立表。退款入口（US4）并入 OmgPayController 或订单取消链路（PosOrderShOprate/UserOrderController 取消时触发），tasks 阶段定具体落点。
Complexity Tracking
Constitution Check 无违规，无需填表。
| Violation | Why Needed | Simpler Alternative Rejected Because |
|---|---|---|
| — | — | — |