提交调用im接口

.specify/feature.json

@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/010-order-invoice"
+  "feature_directory": "specs/012-im-user-integration"
 }

CLAUDE.md

@@ -152,5 +152,5 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 
 <!-- SPECKIT START -->
 For additional context about technologies to be used, project structure,
-shell commands, and other important information, read the current plan
+shell commands, and other important information, read the current plan: `specs/012-im-user-integration/plan.md`
 <!-- SPECKIT END -->

ruoyi-admin/src/main/java/com/ruoyi/app/mendian/PosStoreNewebpayController.java

@@ -0,0 +1,149 @@
+package com.ruoyi.app.mendian;
+
+import com.alibaba.fastjson2.JSONObject;
+import com.ruoyi.app.utils.newebpay.NewebPay;
+import com.ruoyi.app.utils.newebpay.NewebPayConfig;
+import com.ruoyi.common.annotation.Log;
+import com.ruoyi.common.core.controller.BaseController;
+import com.ruoyi.common.core.domain.AjaxResult;
+import com.ruoyi.common.core.page.TableDataInfo;
+import com.ruoyi.common.enums.BusinessType;
+import com.ruoyi.system.domain.dto.StoreNewebpayCredentialDto;
+import com.ruoyi.system.domain.vo.PosStoreNewebpayVo;
+import com.ruoyi.system.service.IPosStoreNewebpayService;
+import jakarta.validation.Valid;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 平台后台 - 门店蓝新金流支付开通管理。
+ *
+ * <p>蓝新商店注册为线下人工；本接口负责申请状态推进、凭证录入与联网验证（QueryTradeInfo 探测）、
+ * 启用开关、支付方式设置。复用 009 PosStoreEzpayController 模式；联网验证放 Controller 层，
+ * Service 仅持久化（避免 ruoyi-system 反向依赖 ruoyi-admin 的 NewebPay 工具类）。
+ *
+ * @author ruoyi
+ * @date 2026-06-22
+ */
+@RestController
+@RequestMapping("/system/storeNewebpay")
+public class PosStoreNewebpayController extends BaseController {
+
+    @Autowired
+    private IPosStoreNewebpayService posStoreNewebpayService;
+
+    @Autowired
+    private NewebPay newebPay;
+
+    @Value("${newebpay.base-url}")
+    private String newebpayBaseUrl;
+
+    /** 开通管理列表（分页 + 筛选 + 快捷过滤）。 */
+    @PreAuthorize("@ss.hasPermi('chanting:storeNewebpay:list')")
+    @GetMapping("/list")
+    public TableDataInfo list(PosStoreNewebpayVo query) {
+        startPage();
+        List<PosStoreNewebpayVo> list = posStoreNewebpayService.selectNewebpayStoreList(query);
+        return getDataTable(list);
+    }
+
+    /** 门店蓝新详情。 */
+    @PreAuthorize("@ss.hasPermi('chanting:storeNewebpay:query')")
+    @GetMapping("/{storeId}")
+    public AjaxResult getInfo(@PathVariable Long storeId) {
+        return success(posStoreNewebpayService.selectNewebpayStoreDetail(storeId));
+    }
+
+    /** 发起申请（未申请 0 → 申请中 1）。 */
+    @PreAuthorize("@ss.hasPermi('chanting:storeNewebpay:apply')")
+    @Log(title = "蓝新发起申请", businessType = BusinessType.UPDATE)
+    @PutMapping("/apply/{storeId}")
+    public AjaxResult apply(@PathVariable Long storeId) {
+        return toAjax(posStoreNewebpayService.apply(storeId));
+    }
+
+    /**
+     * 录入蓝新凭证并验证：调 QueryTradeInfo 查虚构订单探测金钥，
+     * 响应含金钥/商店错误标志视为无效（拒绝、状态不变），否则通过并标记已开通。
+     */
+    @PreAuthorize("@ss.hasPermi('chanting:storeNewebpay:saveCredentials')")
+    @Log(title = "蓝新录入凭证", businessType = BusinessType.UPDATE)
+    @PutMapping("/saveCredentials")
+    public AjaxResult saveCredentials(@RequestBody @Valid StoreNewebpayCredentialDto dto) {
+        NewebPayConfig cfg = new NewebPayConfig(dto.getMerchantId(), dto.getHashKey(), dto.getHashIv());
+        // 查一个不存在的订单号，仅用于探测金钥是否被蓝新接受
+        String probeOrderNo = "NEBVERIFY" + System.currentTimeMillis();
+
+        String respStr;
+        try {
+            JSONObject resp = newebPay.queryTrade(newebpayBaseUrl, cfg, "1", probeOrderNo);
+            respStr = resp == null ? "" : resp.toJSONString();
+        } catch (Exception e) {
+            posStoreNewebpayService.recordVerifyResult(dto.getStoreId(), "ERROR: " + msg(e));
+            return error("蓝新验证服务暂不可用，请稍后重试");
+        }
+
+        // 金钥/商店错误通常在响应中含 HashKey/HashIV/MPG01001 等标志；金钥正确则返回查询类结果（非金钥错误）
+        if (looksLikeCredentialError(respStr)) {
+            posStoreNewebpayService.recordVerifyResult(dto.getStoreId(), "FAIL: " + truncate(respStr));
+            return error("蓝新凭证无效，请检查商店代号 / HashKey / HashIV");
+        }
+
+        posStoreNewebpayService.enableWithCredentials(dto);
+        return success("凭证验证通过，已开通");
+    }
+
+    /** 停用 / 恢复（仅已开通门店）。 */
+    @PreAuthorize("@ss.hasPermi('chanting:storeNewebpay:toggleEnable')")
+    @Log(title = "蓝新停用恢复", businessType = BusinessType.UPDATE)
+    @PutMapping("/toggleEnable/{storeId}")
+    public AjaxResult toggleEnable(@PathVariable Long storeId) {
+        return toAjax(posStoreNewebpayService.toggleEnable(storeId));
+    }
+
+    /** 重置状态（凭证作废/重新申请）。 */
+    @PreAuthorize("@ss.hasPermi('chanting:storeNewebpay:query')")
+    @Log(title = "蓝新重置状态", businessType = BusinessType.UPDATE)
+    @PutMapping("/reset/{storeId}")
+    public AjaxResult reset(@PathVariable Long storeId) {
+        return toAjax(posStoreNewebpayService.reset(storeId));
+    }
+
+    /** 设置启用的支付方式。入参 {enabledPayments: "CREDIT,LINEPAY,APPLEPAY"}。 */
+    @PreAuthorize("@ss.hasPermi('chanting:storeNewebpay:toggleEnable')")
+    @Log(title = "蓝新支付方式设置", businessType = BusinessType.UPDATE)
+    @PutMapping("/enabledPayments/{storeId}")
+    public AjaxResult enabledPayments(@PathVariable Long storeId, @RequestBody Map<String, String> body) {
+        String eps = body == null ? null : body.get("enabledPayments");
+        return toAjax(posStoreNewebpayService.setEnabledPayments(storeId, eps));
+    }
+
+    // ===== 内部辅助 =====
+
+    /** 判定响应是否为金钥/商店代号错误（金钥对则不会出现这些标志）。 */
+    private static boolean looksLikeCredentialError(String respStr) {
+        if (respStr == null || respStr.isEmpty()) {
+            return false;
+        }
+        String u = respStr.toUpperCase();
+        return u.contains("HASHKEY") || u.contains("HASHIV")
+                || u.contains("MPG01001") || u.contains("CHECKVALUE")
+                || u.contains("\"STATUS\":\"MPG01001\"");
+    }
+
+    private static String msg(Throwable e) {
+        return e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage();
+    }
+
+    private static String truncate(String s) {
+        if (s == null) {
+            return "";
+        }
+        return s.length() > 240 ? s.substring(0, 240) : s;
+    }
+}

ruoyi-admin/src/main/java/com/ruoyi/app/order/OrderInvoiceService.java

@@ -124,14 +124,18 @@ public class OrderInvoiceService {
         EzPayConfig cfg = new EzPayConfig(ez.getMerchantId(), ez.getHashKey(), ez.getHashIv());
 
         int newStatus;
-        String invoiceNumber = null, randomNum = null, invoiceUrl = null, failReason = null;
+        String invoiceNumber = null, randomNum = null, invoiceTransNo = null,
+                invoiceBarCode = null, invoiceQrcodeL = null, invoiceQrcodeR = null, failReason = null;
         try {
             JSONObject resp = ezPay.issueInvoice(ezpayBaseUrl, cfg, inv);            String status = resp == null ? "" : resp.getString("Status");
             JSONObject result = resp == null ? null : resp.getJSONObject("Result");
             if ("SUCCESS".equals(status) && result != null && StrUtil.isNotBlank(result.getString("InvoiceNumber"))) {
                 invoiceNumber = result.getString("InvoiceNumber");
                 randomNum = result.getString("RandomNum");
-                invoiceUrl = result.getString("InvoiceTransNo");
+                invoiceTransNo = result.getString("InvoiceTransNo");
+                invoiceBarCode = result.getString("BarCode");
+                invoiceQrcodeL = result.getString("QRcodeL");
+                invoiceQrcodeR = result.getString("QRcodeR");
                 newStatus = STATUS_ISSUED;
             } else {
                 failReason = resp == null ? "ezPay 无回应" : (status + ":" + resp.getString("Message"));
@@ -161,7 +165,10 @@ public class OrderInvoiceService {
         if (newStatus == STATUS_ISSUED) {
             saveRow.setInvoiceNumber(invoiceNumber);
             saveRow.setRandomNum(randomNum);
-            saveRow.setInvoiceUrl(invoiceUrl);
+            saveRow.setInvoiceTransNo(invoiceTransNo);
+            saveRow.setInvoiceBarCode(invoiceBarCode);
+            saveRow.setInvoiceQrcodeL(invoiceQrcodeL);
+            saveRow.setInvoiceQrcodeR(invoiceQrcodeR);
             saveRow.setIssueTime(now);
             saveRow.setFailReason(null);
         } else {
@@ -330,7 +337,8 @@ public class OrderInvoiceService {
         EzPayConfig cfg = new EzPayConfig(ez.getMerchantId(), ez.getHashKey(), ez.getHashIv());
 
         int newStatus;
-        String invoiceNumber = null, randomNum = null, invoiceUrl = null, failReason = null;
+        String invoiceNumber = null, randomNum = null, invoiceTransNo = null,
+                invoiceBarCode = null, invoiceQrcodeL = null, invoiceQrcodeR = null, failReason = null;
         try {
             JSONObject resp = ezPay.issueInvoice(ezpayBaseUrl, cfg, inv);
             String status = resp == null ? "" : resp.getString("Status");
@@ -338,7 +346,10 @@ public class OrderInvoiceService {
             if ("SUCCESS".equals(status) && result != null && StrUtil.isNotBlank(result.getString("InvoiceNumber"))) {
                 invoiceNumber = result.getString("InvoiceNumber");
                 randomNum = result.getString("RandomNum");
-                invoiceUrl = result.getString("InvoiceTransNo");
+                invoiceTransNo = result.getString("InvoiceTransNo");
+                invoiceBarCode = result.getString("BarCode");
+                invoiceQrcodeL = result.getString("QRcodeL");
+                invoiceQrcodeR = result.getString("QRcodeR");
                 newStatus = STATUS_ISSUED;
             } else {
                 failReason = resp == null ? "ezPay 无回应" : (status + ":" + resp.getString("Message"));
@@ -353,7 +364,10 @@ public class OrderInvoiceService {
         if (newStatus == STATUS_ISSUED) {
             row.setInvoiceNumber(invoiceNumber);
             row.setRandomNum(randomNum);
-            row.setInvoiceUrl(invoiceUrl);
+            row.setInvoiceTransNo(invoiceTransNo);
+            row.setInvoiceBarCode(invoiceBarCode);
+            row.setInvoiceQrcodeL(invoiceQrcodeL);
+            row.setInvoiceQrcodeR(invoiceQrcodeR);
             row.setIssueTime(now);
             row.setFailReason(null);
         } else {

ruoyi-admin/src/main/java/com/ruoyi/app/order/PosOrderShOprateController.java

@@ -60,6 +60,8 @@ public class PosOrderShOprateController extends BaseController {
     @Autowired
     private OrderInvoiceService orderInvoiceService;
 
+
+
     /**
      * 商家端查询订单发票（状态/发票号/凭证）
      */

ruoyi-admin/src/main/java/com/ruoyi/app/pay/NewebpayPayController.java

@@ -0,0 +1,446 @@
+package com.ruoyi.app.pay;
+
+import com.alibaba.fastjson.JSONObject;
+import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
+import com.ruoyi.app.order.dto.OrderPushBodyDto;
+import com.ruoyi.app.utils.PayPush;
+import com.ruoyi.app.utils.event.PushEventService;
+import com.ruoyi.app.utils.newebpay.NewebPay;
+import com.ruoyi.app.utils.newebpay.NewebPayConfig;
+import com.ruoyi.app.utils.newebpay.NewebPayEncryptUtil;
+import com.ruoyi.common.annotation.Anonymous;
+import com.ruoyi.common.annotation.RepeatSubmit;
+import com.ruoyi.common.core.controller.BaseController;
+import com.ruoyi.common.core.domain.AjaxResult;
+import com.ruoyi.common.utils.MessageUtils;
+import com.ruoyi.system.domain.InfoUser;
+import com.ruoyi.system.domain.IpnLog;
+import com.ruoyi.system.domain.PosOrder;
+import com.ruoyi.system.domain.PosOrderPayment;
+import com.ruoyi.system.domain.PosStoreNewebpay;
+import com.ruoyi.system.mapper.RiderPositionMapper;
+import com.ruoyi.system.service.IInfoUserService;
+import com.ruoyi.system.service.IIpnLogService;
+import com.ruoyi.system.service.IPosOrderPaymentService;
+import com.ruoyi.system.service.IPosOrderService;
+import com.ruoyi.system.service.IPosStoreNewebpayService;
+import com.ruoyi.system.utils.Auth;
+import com.ruoyi.system.utils.JwtUtil;
+import com.ruoyi.system.utils.OrderLogHelper;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.io.IOException;
+import java.net.URLDecoder;
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.text.SimpleDateFormat;
+import java.util.Date;
+import java.util.Enumeration;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * 蓝新金流(NewebPay) 线上支付 Controller。
+ *
+ * <p>本期实现：
+ * <ul>
+ *   <li>{@code POST /pay/newebpay/create} — 发起 MPG 幕前支付（US1）。</li>
+ *   <li>{@code POST /pay/newebpay/notify} — NotifyURL 支付结果回调（US2，@Anonymous）。</li>
+ *   <li>{@code GET|POST /pay/newebpay/return} — ReturnURL 完成页引导（US2，@Anonymous）。</li>
+ * </ul>
+ * 单笔查询 /pay/newebpay/query（US5）后续补充。
+ *
+ * <p>回调成功后的业务链路（更新 payStatus + 订单日志 + 推送用户/商家/骑手）参照
+ * {@link PayController#payipn(HttpServletRequest)} 的 VNPay 实现。
+ *
+ * @author ruoyi
+ * @date 2026-06-22
+ */
+@RestController
+@RequestMapping("/pay/newebpay")
+public class NewebpayPayController extends BaseController {
+
+    private static final Logger log = LoggerFactory.getLogger(NewebpayPayController.class);
+
+    /** payType 取值：蓝新在线支付（发起时写入 pos_order.pay_type；具体方式 CREDIT/LINEPAY/APPLEPAY 由回调写入 pos_order_payment）。 */
+    public static final String PAY_TYPE_NEWEBPAY = "6";
+
+    @Autowired
+    private IPosOrderService posOrderService;
+    @Autowired
+    private IPosStoreNewebpayService posStoreNewebpayService;
+    @Autowired
+    private IPosOrderPaymentService posOrderPaymentService;
+    @Autowired
+    private NewebPay newebPay;
+    @Autowired
+    private IInfoUserService infoUserService;
+    @Autowired
+    private RiderPositionMapper riderPositionMapper;
+    @Autowired
+    private PushEventService pushEventService;
+    @Autowired
+    private OrderLogHelper orderLogHelper;
+    @Autowired
+    private IIpnLogService ipnLogService;
+    /** 复用 PayController 的可接单骑手异步推送（避免重写复杂调度）。 */
+    @Autowired
+    private PayController payController;
+
+    @Value("${newebpay.base-url}")
+    private String baseUrl;
+    @Value("${newebpay.notify-url}")
+    private String notifyUrl;
+    @Value("${newebpay.return-url}")
+    private String returnUrl;
+    @Value("${newebpay.front-result-url}")
+    private String frontResultUrl;
+    @Value("${newebpay.mpg-version}")
+    private String mpgVersion;
+
+    // ============================ US1：发起 MPG 幕前支付 ============================
+
+    /**
+     * 发起蓝新 MPG 幕前支付。校验订单 → 查门店启用凭证 → 生成商店订单号 →
+     * 组装并加密 TradeInfo → 落流水 + 更新订单 payType → 返回 form 字段供前端 Form Post 跳转蓝新付款页。
+     */
+    @Anonymous
+    @Auth
+    @RepeatSubmit(interval = 1000, message = "请求过于频繁")
+    @PostMapping("/create")
+    public AjaxResult create(@RequestParam String orderid, HttpServletRequest request) {
+        String token = request.getHeader("token");
+        JwtUtil jwtUtil = new JwtUtil();
+        String userId;
+        try {
+            userId = jwtUtil.getusid(token);
+        } catch (Exception e) {
+            return error(MessageUtils.message("no.order.id.error"));
+        }
+        if (userId == null || userId.isEmpty()) {
+            return error("请先登录");
+        }
+
+        PosOrder order = posOrderService.getOne(new QueryWrapper<PosOrder>().eq("dd_id", orderid));
+        if (order == null) {
+            return error(MessageUtils.message("no.order.id.error"));
+        }
+        if (order.getUserId() == null || !userId.equals(String.valueOf(order.getUserId()))) {
+            return error("无权操作该订单");
+        }
+        if (order.getPayStatus() != null && order.getPayStatus() == 1L) {
+            return error("订单已支付");
+        }
+        if (order.getAmount() == null || order.getAmount() <= 0) {
+            return error("订单金额异常");
+        }
+
+        Long storeId = order.getMdId();
+        PosStoreNewebpay cfg = posStoreNewebpayService.getEnabledConfig(storeId);
+        if (cfg == null) {
+            return error("该门店暂不支持线上支付");
+        }
+
+        String merchantOrderNo = genMerchantOrderNo(orderid);
+
+        // TradeInfo 明文（NDNF §4.2.1）
+        Map<String, Object> tradeParams = new LinkedHashMap<>();
+        tradeParams.put("MerchantID", cfg.getMerchantId());
+        tradeParams.put("RespondType", "JSON");
+        tradeParams.put("TimeStamp", String.valueOf(System.currentTimeMillis() / 1000L));
+        tradeParams.put("Version", mpgVersion);
+        tradeParams.put("MerchantOrderNo", merchantOrderNo);
+        tradeParams.put("Amt", order.getAmount());
+        tradeParams.put("ItemDesc", "order " + orderid);
+        tradeParams.put("NotifyURL", notifyUrl);
+        tradeParams.put("ReturnURL", returnUrl);
+        applyPaymentSwitch(tradeParams, cfg.getEnabledPayments());
+
+        NewebPayConfig npc = new NewebPayConfig(cfg.getMerchantId(), cfg.getHashKey(), cfg.getHashIv());
+        Map<String, String> form = newebPay.createMpgForm(baseUrl, npc, tradeParams, mpgVersion);
+
+        posOrderPaymentService.createPayment(orderid, merchantOrderNo, storeId, cfg.getMerchantId(), order.getAmount());
+
+        PosOrder upd = new PosOrder();
+        upd.setId(order.getId());
+        upd.setPayType(PAY_TYPE_NEWEBPAY);
+        upd.setPayUrl(form.get("gatewayUrl"));
+        posOrderService.saveOrUpdate(upd);
+
+        return success(MessageUtils.message("no.order.create.success"), form);
+    }
+
+    // ============================ US2：NotifyURL 支付结果回调 ============================
+
+    /**
+     * 蓝新支付结果背景通知（@Anonymous，蓝新服务器 Form Post）。
+     *
+     * <p>记 IPN 日志 → 按 MerchantID 查凭证 → 验签 TradeSha → 解密 TradeInfo →
+     * 幂等(trade_no) + 金额校验 + 订单关联 → 成功则更新 payStatus=1 并推送用户/商家/骑手；
+     * 失败则记录。任何异常都不抛错响应（蓝新收到非成功会重试），但绝不错误更新订单。
+     */
+    @Anonymous
+    @PostMapping("/notify")
+    public JSONObject notify(HttpServletRequest request) {
+        JSONObject resp = new JSONObject();
+        resp.put("Status", "SUCCESS");
+        resp.put("Message", "OK");
+
+        Map<String, Object> form = collectForm(request);
+        String ip = new com.ruoyi.app.utils.IpUtils().getIpAddr(request);
+        String merchantId = (String) form.get("MerchantID");
+        String tradeInfo = (String) form.get("TradeInfo");
+        String tradeSha = (String) form.get("TradeSha");
+        String status = (String) form.get("Status");
+
+        // 记录 IPN 日志
+        try {
+            IpnLog ipnLog = new IpnLog();
+            ipnLog.setIp(ip);
+            ipnLog.setIpnLog(form.toString());
+            ipnLogService.insertIpnLog(ipnLog);
+        } catch (Exception e) {
+            log.warn("记蓝新 IPN 日志失败", e);
+        }
+
+        PosStoreNewebpay cfg = posStoreNewebpayService.getByMerchantId(merchantId);
+        if (cfg == null || cfg.getHashKey() == null || tradeInfo == null) {
+            log.warn("蓝新回调无匹配凭证或缺少 TradeInfo: merchantId={}", merchantId);
+            return resp;
+        }
+
+        // 验签
+        String expectedSha = NewebPayEncryptUtil.genTradeSha(tradeInfo, cfg.getHashKey(), cfg.getHashIv());
+        if (tradeSha == null || !tradeSha.equals(expectedSha)) {
+            log.warn("蓝新回调验签失败: merchantId={}, expected={}, got={}", merchantId, expectedSha, tradeSha);
+            return resp;
+        }
+
+        // 解密
+        Map<String, Object> d;
+        try {
+            d = parseQuery(NewebPayEncryptUtil.decrypt(tradeInfo, cfg.getHashKey(), cfg.getHashIv()));
+        } catch (Exception e) {
+            log.warn("蓝新回调解密失败: merchantId={}", merchantId, e);
+            return resp;
+        }
+
+        String tradeNo = getStr(d, "TradeNo");
+        String merchantOrderNo = getStr(d, "MerchantOrderNo");
+
+        // 幂等：同 tradeNo 已成功则直接返回
+        PosOrderPayment exist = posOrderPaymentService.getByTradeNo(tradeNo);
+        if (exist != null && exist.getPayStatus() != null && exist.getPayStatus() == 1) {
+            return resp;
+        }
+
+        // 订单关联
+        PosOrderPayment payment = posOrderPaymentService.getByMerchantOrderNo(merchantOrderNo);
+        if (payment == null) {
+            log.warn("蓝新回调无对应发起记录: merchantOrderNo={}", merchantOrderNo);
+            return resp;
+        }
+        String ddId = payment.getDdId();
+        PosOrder order = posOrderService.getOne(new QueryWrapper<PosOrder>().eq("dd_id", ddId));
+        if (order == null) {
+            log.warn("蓝新回调订单不存在: ddId={}", ddId);
+            return resp;
+        }
+
+        // 金额校验
+        int amt = parseInt(getStr(d, "Amt"), -1);
+        if (amt < 0 || order.getAmount() == null || order.getAmount() != amt) {
+            log.error("蓝新回调金额不符: ddId={}, orderAmt={}, callbackAmt={}", ddId, order.getAmount(), amt);
+            return resp;
+        }
+
+        String payType = mapPaymentType(d);
+        String auth = getStr(d, "Auth");
+        Date payTime = parsePayTime(getStr(d, "PayTime"));
+
+        if ("SUCCESS".equals(status)) {
+            int n = posOrderPaymentService.markSuccess(ddId, merchantOrderNo, payment.getStoreId(),
+                    merchantId, amt, tradeNo, payType, auth, payTime, d.toString());
+            if (n > 0) {
+                // 首次成功：更新订单支付状态并推送（state 保持 0 待商家接单）
+                handlePaymentSuccess(order, d);
+            }
+        } else {
+            posOrderPaymentService.markFail(merchantOrderNo, tradeNo, payType, d.toString());
+            log.warn("蓝新回调交易失败: ddId={}, status={}, message={}", ddId, status, getStr(d, "Message"));
+        }
+        return resp;
+    }
+
+    /**
+     * 支付完成返回页（@Anonymous）。仅引导回前端结果页，<b>不</b>修改订单状态（状态以 notify 为准）。
+     */
+    @Anonymous
+    @RequestMapping(value = "/return", method = {org.springframework.web.bind.annotation.RequestMethod.GET,
+            org.springframework.web.bind.annotation.RequestMethod.POST})
+    public void returnCallback(HttpServletRequest request, HttpServletResponse response) throws IOException {
+        String ddId = "";
+        try {
+            Map<String, Object> form = collectForm(request);
+            String merchantId = (String) form.get("MerchantID");
+            String tradeInfo = (String) form.get("TradeInfo");
+            PosStoreNewebpay cfg = posStoreNewebpayService.getByMerchantId(merchantId);
+            if (cfg != null && cfg.getHashKey() != null && tradeInfo != null) {
+                Map<String, Object> d = parseQuery(NewebPayEncryptUtil.decrypt(tradeInfo, cfg.getHashKey(), cfg.getHashIv()));
+                PosOrderPayment p = posOrderPaymentService.getByMerchantOrderNo(getStr(d, "MerchantOrderNo"));
+                if (p != null) {
+                    ddId = p.getDdId();
+                }
+            }
+        } catch (Exception e) {
+            log.warn("蓝新 ReturnURL 解析失败", e);
+        }
+        String sep = frontResultUrl.contains("?") ? "&" : "?";
+        response.sendRedirect(frontResultUrl + sep + "ddId=" + URLEncoder.encode(ddId, StandardCharsets.UTF_8));
+    }
+
+    // ============================ 支付成功业务链路（参照 PayController.payipn） ============================
+
+    /** 支付成功：更新订单 payStatus=1（state 不变）+ 订单日志 + 推送用户/商家/骑手。 */
+    private void handlePaymentSuccess(PosOrder order, Map<String, Object> decryptedMap) {
+        try {
+            PosOrder upd = new PosOrder();
+            upd.setId(order.getId());
+            upd.setState(0L);
+            upd.setPayStatus(1L);
+            posOrderService.saveOrUpdate(upd);
+
+            orderLogHelper.logSync(String.valueOf(order.getDdId()), 0, null, "系统", "系统收到蓝新支付成功回调");
+
+            InfoUser user = order.getUserId() == null ? null : infoUserService.getById(order.getUserId());
+            InfoUser shanghu = order.getShId() == null ? null : infoUserService.getById(order.getShId());
+            if (user == null) {
+                return;
+            }
+            PayPush push = new PayPush();
+            Map<String, Object> orderMap = OrderPushBodyDto.getMap(String.valueOf(order.getDdId()), "1", 0, 1);
+            String json = OrderPushBodyDto.margeMapGetJsonString(orderMap, decryptedMap);
+
+            String title = MessageUtils.message("no.message.push.message");
+            push.apppush(user.getCid(), title, MessageUtils.message("no.message.push.payment.success"), json);
+            pushEventService.PublisherEvent(user.getUserId(), title, MessageUtils.message("no.message.push.payment.success"), json);
+
+            if (shanghu != null) {
+                push.shpush(shanghu.getCid(), title, MessageUtils.message("no.message.push.new.order"), json);
+                pushEventService.PublisherEvent(shanghu.getUserId(), title, MessageUtils.message("no.message.push.new.order"), json);
+            }
+
+            // 可接单骑手推送（外卖），复用 PayController 的异步实现
+            try {
+                String body = OrderPushBodyDto.getJson(String.valueOf(order.getDdId()), String.valueOf(order.getState()), 1);
+                payController.sendAcceptRiderPush(order, push, riderPositionMapper, body);
+            } catch (Exception e) {
+                log.warn("蓝新支付成功骑手推送异常: ddId={}", order.getDdId(), e);
+            }
+        } catch (Exception e) {
+            log.error("蓝新支付成功业务处理异常: ddId={}", order.getDdId(), e);
+        }
+    }
+
+    // ============================ 辅助 ============================
+
+    private static String genMerchantOrderNo(String orderid) {
+        String safe = orderid == null ? "" : orderid.replaceAll("[^A-Za-z0-9_]", "");
+        return "NB" + safe;
+    }
+
+    private static void applyPaymentSwitch(Map<String, Object> params, String enabledPayments) {
+        if (enabledPayments == null || enabledPayments.isEmpty()) {
+            params.put("CREDIT", 1);
+            return;
+        }
+        String eps = enabledPayments.toUpperCase();
+        params.put("CREDIT", eps.contains("CREDIT") ? 1 : 0);
+        params.put("LINEPAY", eps.contains("LINEPAY") ? 1 : 0);
+        params.put("APPLEPAY", eps.contains("APPLEPAY") ? 1 : 0);
+    }
+
+    /** 收集 form 参数到 Map（值非空的单值参数）。 */
+    private static Map<String, Object> collectForm(HttpServletRequest request) {
+        Map<String, Object> m = new LinkedHashMap<>();
+        Enumeration<String> names = request.getParameterNames();
+        while (names.hasMoreElements()) {
+            String n = names.nextElement();
+            String[] vals = request.getParameterValues(n);
+            if (vals != null && vals.length == 1 && !vals[0].isEmpty()) {
+                m.put(n, vals[0]);
+            }
+        }
+        return m;
+    }
+
+    /** 解析 a=1&b=2（URL decode）为 Map。 */
+    private static Map<String, Object> parseQuery(String query) {
+        Map<String, Object> m = new LinkedHashMap<>();
+        if (query == null || query.isEmpty()) {
+            return m;
+        }
+        for (String pair : query.split("&")) {
+            int idx = pair.indexOf('=');
+            if (idx <= 0) {
+                continue;
+            }
+            String k = urlDecode(pair.substring(0, idx));
+            String v = idx + 1 <= pair.length() ? urlDecode(pair.substring(idx + 1)) : "";
+            m.put(k, v);
+        }
+        return m;
+    }
+
+    private static String urlDecode(String s) {
+        try {
+            return URLDecoder.decode(s, StandardCharsets.UTF_8);
+        } catch (Exception e) {
+            return s;
+        }
+    }
+
+    private static String getStr(Map<String, Object> m, String k) {
+        Object v = m.get(k);
+        return v == null ? "" : v.toString();
+    }
+
+    private static int parseInt(String s, int def) {
+        try {
+            return Integer.parseInt(s);
+        } catch (Exception e) {
+            return def;
+        }
+    }
+
+    private static Date parsePayTime(String s) {
+        if (s == null || s.isEmpty()) {
+            return null;
+        }
+        try {
+            return new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").parse(s);
+        } catch (Exception e) {
+            return null;
+        }
+    }
+
+    /** 蓝新回调支付方式映射：优先 PaymentMethod（APPLEPAY），否则 PaymentType（CREDIT/LINEPAY...）。 */
+    private static String mapPaymentType(Map<String, Object> d) {
+        String pm = getStr(d, "PaymentMethod");
+        if (!pm.isEmpty()) {
+            return pm.toUpperCase();
+        }
+        return getStr(d, "PaymentType").toUpperCase();
+    }
+
+    // TODO US5: POST /pay/newebpay/query（单笔查询 + 补单）
+}

ruoyi-admin/src/main/java/com/ruoyi/app/service/ImAccountService.java

@@ -0,0 +1,64 @@
+package com.ruoyi.app.service;
+
+import com.ruoyi.app.utils.im.ImClient;
+import com.ruoyi.common.exception.ServiceException;
+import com.ruoyi.system.domain.InfoUser;
+import com.ruoyi.system.domain.vo.ImAccountVo;
+import com.ruoyi.system.service.IInfoUserService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Component;
+
+/**
+ * IM 账号开通服务（编排层）。
+ *
+ * <p>幂等校验 → 调用 IM 平台创建 → 回写用户表凭证。
+ * 放在 ruoyi-admin 模块：同时依赖 {@link ImClient}（外部 HTTP，仿 NewebPay，
+ * httpclient4 + fastjson2）与 {@link IInfoUserService}（用户表读写），
+ * 避开 ruoyi-system 反向依赖 ruoyi-admin 的模块边界问题。
+ *
+ * @author ruoyi
+ * @date 2026-06-23
+ */
+@Component
+public class ImAccountService {
+
+    @Autowired
+    private ImClient imClient;
+
+    @Autowired
+    private IInfoUserService infoUserService;
+
+    /**
+     * 开通（或获取）当前用户的 IM 账号凭证。
+     * 幂等：用户已有 IM 凭证时直接返回，不再调用 IM 平台。
+     *
+     * @param userId 用户ID
+     * @return IM 凭证（apiKey + imUserId）
+     */
+    public ImAccountVo openImAccount(Long userId) {
+        InfoUser user = infoUserService.getById(userId);
+        if (user == null) {
+            throw new ServiceException("用户不存在");
+        }
+        // 幂等：已有 IM 凭证直接返回，不再调用 IM 平台创建
+        if (user.getImApiKey() != null && !user.getImApiKey().isEmpty()) {
+            ImAccountVo exist = new ImAccountVo();
+            exist.setImApiKey(user.getImApiKey());
+            exist.setImUserId(user.getImUserId() == null ? null : String.valueOf(user.getImUserId()));
+            return exist;
+        }
+        // 首次开通：nickName 取 userName，无则取 phone（哪个有值用哪个）
+        String nickName = (user.getUserName() != null && !user.getUserName().isEmpty())
+                ? user.getUserName() : user.getPhone();
+        if (nickName == null || nickName.isEmpty()) {
+            throw new ServiceException("用户昵称为空，无法创建 IM 账号");
+        }
+        ImAccountVo vo = imClient.createAccount(nickName);
+        InfoUser update = new InfoUser();
+        update.setUserId(userId);
+        update.setImApiKey(vo.getImApiKey());
+        update.setImUserId(Long.valueOf(vo.getImUserId()));
+        infoUserService.updateById(update);
+        return vo;
+    }
+}

ruoyi-admin/src/main/java/com/ruoyi/app/user/InfoUserController.java

@@ -25,6 +25,7 @@ import com.ruoyi.common.utils.ip.IpUtils;
 import com.ruoyi.common.utils.poi.ExcelUtil;
 import com.ruoyi.system.domain.*;
 import com.ruoyi.system.domain.vo.UserDTO;
+import com.ruoyi.app.service.ImAccountService;
 import com.ruoyi.system.mapper.InfoUserMapper;
 import com.ruoyi.system.mapper.PosOrderMapper;
 import com.ruoyi.system.mapper.PosStoreMapper;
@@ -67,6 +68,8 @@ public class InfoUserController extends BaseController {
     @Autowired
     private IInfoUserService infoUserService;
     @Autowired
+    private ImAccountService imAccountService;
+    @Autowired
     private InfoUserMapper infoUserMapper;
     @Autowired
     private IVipUserService vipUserService;
@@ -938,4 +941,24 @@ public class InfoUserController extends BaseController {
     public AjaxResult remove(@PathVariable Long[] userIds) {
         return toAjax(infoUserService.deleteInfoUserByUserIds(userIds));
     }
+
+    /**
+     * 开通 IM 账号：APP 在用户注册完成后（或首次沟通前）调用。
+     * 通过登录 token 解析 userId，幂等创建/获取 IM 凭证并返回，供 APP 初始化 IM SDK。
+     */
+    @Anonymous
+    @PostMapping("/imOpen")
+    public AjaxResult openIm(@RequestHeader String token) {
+        JwtUtil jwtUtil = new JwtUtil();
+        String id;
+        try {
+            id = jwtUtil.getusid(token);
+        } catch (Exception e) {
+            return error("请先登录");
+        }
+        if (id == null || id.isEmpty()) {
+            return error("请先登录");
+        }
+        return AjaxResult.success(imAccountService.openImAccount(Long.valueOf(id)));
+    }
 }

ruoyi-admin/src/main/java/com/ruoyi/app/utils/im/ImClient.java

@@ -0,0 +1,99 @@
+package com.ruoyi.app.utils.im;
+
+import com.alibaba.fastjson2.JSON;
+import com.alibaba.fastjson2.JSONObject;
+import com.ruoyi.common.exception.ServiceException;
+import com.ruoyi.system.domain.vo.ImAccountVo;
+import org.apache.http.client.config.RequestConfig;
+import org.apache.http.client.methods.CloseableHttpResponse;
+import org.apache.http.client.methods.HttpPost;
+import org.apache.http.entity.StringEntity;
+import org.apache.http.impl.client.CloseableHttpClient;
+import org.apache.http.impl.client.HttpClients;
+import org.apache.http.util.EntityUtils;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+import java.nio.charset.StandardCharsets;
+
+/**
+ * IM 平台 HTTP 客户端。
+ *
+ * <p>封装 IM 平台「创建用户」接口（extCreate）：
+ * POST {base-url}{create-path}，请求头带 extToken，返回 apiKey + userId。
+ *
+ * <p>仿 {@code com.ruoyi.app.utils.newebpay.NewebPay} 结构，使用 org.apache.http；
+ * 配置经 @Value 从 application.yml 的 im 段注入（域名/令牌均不硬编码）。
+ *
+ * @author ruoyi
+ * @date 2026-06-23
+ */
+@Component
+public class ImClient {
+
+    @Value("${im.base-url}")
+    private String baseUrl;
+
+    @Value("${im.ext-token}")
+    private String extToken;
+
+    @Value("${im.create-path}")
+    private String createPath;
+
+    @Value("${im.timeout-ms}")
+    private int timeoutMs;
+
+    /**
+     * 调用 IM 平台 extCreate 创建用户，返回凭证。
+     *
+     * <p>请求体 JSON：{@code {"nickName": <昵称>, "type": 0}}，请求头带 extToken。
+     *
+     * @param nickName 昵称（由上层取 userName，无则取 phone）
+     * @return 含 apiKey、imUserId(String) 的凭证对象
+     * @throws ServiceException IM 平台返回失败、超时或网络异常时抛出（由上层捕获，不写库）
+     */
+    public ImAccountVo createAccount(String nickName) {
+        String url = baseUrl + createPath;
+        RequestConfig requestConfig = RequestConfig.custom()
+                .setConnectTimeout(timeoutMs)
+                .setSocketTimeout(timeoutMs)
+                .build();
+        HttpPost post = new HttpPost(url);
+        post.setConfig(requestConfig);
+        post.setHeader("extToken", extToken);
+        post.setHeader("Content-Type", "application/json");
+        // 请求体：nickName + type(默认 0)
+        JSONObject reqBody = new JSONObject();
+        reqBody.put("nickName", nickName);
+        reqBody.put("type", 0);
+        post.setEntity(new StringEntity(reqBody.toJSONString(), StandardCharsets.UTF_8));
+
+        String body;
+        try (CloseableHttpClient client = HttpClients.createDefault();
+             CloseableHttpResponse res = client.execute(post)) {
+            body = EntityUtils.toString(res.getEntity(), StandardCharsets.UTF_8);
+        } catch (Exception e) {
+            throw new ServiceException("IM 账号创建失败：网络异常 " + e.getMessage());
+        }
+
+        JSONObject resp = JSON.parseObject(body);
+        Integer code = resp.getInteger("code");
+        if (code == null || code != 200) {
+            throw new ServiceException("IM 账号创建失败：" + resp.getString("message"));
+        }
+        JSONObject data = resp.getJSONObject("data");
+        if (data == null) {
+            throw new ServiceException("IM 账号创建失败：响应缺少 data");
+        }
+        String apiKey = data.getString("apiKey");
+        Long userId = data.getLong("userId");
+        if (apiKey == null || apiKey.isEmpty() || userId == null) {
+            throw new ServiceException("IM 账号创建失败：凭证字段缺失");
+        }
+
+        ImAccountVo vo = new ImAccountVo();
+        vo.setImApiKey(apiKey);
+        vo.setImUserId(String.valueOf(userId)); // String 规避前端 Long 精度丢失
+        return vo;
+    }
+}

ruoyi-admin/src/main/java/com/ruoyi/app/utils/newebpay/NewebPay.java

@@ -0,0 +1,132 @@
+package com.ruoyi.app.utils.newebpay;
+
+import com.alibaba.fastjson2.JSON;
+import com.alibaba.fastjson2.JSONObject;
+import org.apache.http.NameValuePair;
+import org.apache.http.client.entity.UrlEncodedFormEntity;
+import org.apache.http.client.methods.CloseableHttpResponse;
+import org.apache.http.client.methods.HttpPost;
+import org.apache.http.impl.client.CloseableHttpClient;
+import org.apache.http.impl.client.HttpClients;
+import org.apache.http.message.BasicNameValuePair;
+import org.apache.http.util.EntityUtils;
+import org.springframework.stereotype.Component;
+
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 蓝新金流(NewebPay) HTTP 客户端。
+ *
+ * <p>对应官方手册 NDNF-1.2.2：
+ * <ul>
+ *   <li>{@link #createMpgForm} — MPG 幕前支付：组装加密 form 字段，前端 Form Post 到 gateway。</li>
+ *   <li>{@link #queryTrade} — 单笔交易查询：幕后 POST QueryTradeInfo，返回 JSON。</li>
+ * </ul>
+ *
+ * <p>多门店：每个门店在蓝新申请独立 HashKey/HashIV，调用时传入 {@link NewebPayConfig}。
+ * 仿 {@code com.ruoyi.app.utils.ezPay.EzPay} 结构。
+ *
+ * @author ruoyi
+ * @date 2026-06-22
+ */
+@Component
+public class NewebPay {
+
+    /** 正式环境根地址。 */
+    public static final String BASE_PROD = "https://core.newebpay.com";
+    /** 测试环境根地址。 */
+    public static final String BASE_TEST = "https://ccore.newebpay.com";
+
+    /** MPG 幕前支付 gateway。 */
+    public static final String URL_MPG_GATEWAY = "/MPG/mpg_gateway";
+    /** 单笔交易查询。 */
+    public static final String URL_QUERY_TRADE_INFO = "/API/QueryTradeInfo";
+
+    /**
+     * MPG 幕前支付：组装加密 form 字段（不直接 POST，由前端 Form Post 到 gateway）。
+     *
+     * <p>对应 NDNF §4.2.1 + §4.1.1/4.1.2：tradeParams → http_build_query → AES 加密 TradeInfo →
+     * SHA256 生成 TradeSha → 连同 MerchantID/Version/EncryptType 返回。
+     *
+     * @param baseUrl      {@link #BASE_PROD} 或 {@link #BASE_TEST}
+     * @param cfg          门店配置
+     * @param tradeParams  TradeInfo 内含字段（MerchantID/RespondType/TimeStamp/Version/MerchantOrderNo/
+     *                     Amt/ItemDesc/NotifyURL/ReturnURL/CREDIT/LINEPAY/APPLEPAY 等）
+     * @param version      串接程式版本（如 "2.3"）
+     * @return form 字段：gatewayUrl / MerchantID / TradeInfo / TradeSha / Version / EncryptType
+     */
+    public Map<String, String> createMpgForm(String baseUrl, NewebPayConfig cfg,
+                                              Map<String, Object> tradeParams, String version) {
+        String query = buildQuery(tradeParams);
+        String tradeInfo = NewebPayEncryptUtil.encrypt(query, cfg.getHashKey(), cfg.getHashIv());
+        String tradeSha = NewebPayEncryptUtil.genTradeSha(tradeInfo, cfg.getHashKey(), cfg.getHashIv());
+        Map<String, String> form = new LinkedHashMap<>();
+        form.put("gatewayUrl", baseUrl + URL_MPG_GATEWAY);
+        form.put("MerchantID", cfg.getMerchantId());
+        form.put("TradeInfo", tradeInfo);
+        form.put("TradeSha", tradeSha);
+        form.put("Version", version);
+        form.put("EncryptType", "0"); // 0 = AES/CBC/PKCS7Padding（默认）
+        return form;
+    }
+
+    /**
+     * 单笔交易查询（幕后 POST，返回 JSON）。对应 NDNF §4.3。
+     *
+     * @param baseUrl         {@link #BASE_PROD} 或 {@link #BASE_TEST}
+     * @param cfg             门店配置
+     * @param amt             订单金额
+     * @param merchantOrderNo 商店订单号
+     * @return 蓝新回应 JSON（Status/Message/Result，Result 内含 TradeStatus/PaymentType/PayTime/CheckCode 等）
+     */
+    public JSONObject queryTrade(String baseUrl, NewebPayConfig cfg, String amt, String merchantOrderNo) throws Exception {
+        String checkValue = NewebPayEncryptUtil.genCheckValue(
+                amt, cfg.getMerchantId(), merchantOrderNo, cfg.getHashKey(), cfg.getHashIv());
+        List<NameValuePair> params = new ArrayList<>();
+        params.add(new BasicNameValuePair("MerchantID", cfg.getMerchantId()));
+        params.add(new BasicNameValuePair("Version", "1.3"));
+        params.add(new BasicNameValuePair("RespondType", "JSON"));
+        params.add(new BasicNameValuePair("CheckValue", checkValue));
+        params.add(new BasicNameValuePair("TimeStamp", String.valueOf(System.currentTimeMillis() / 1000L)));
+        params.add(new BasicNameValuePair("MerchantOrderNo", merchantOrderNo));
+        params.add(new BasicNameValuePair("Amt", amt));
+        String resp = postFormRaw(baseUrl + URL_QUERY_TRADE_INFO, params);
+        return JSON.parseObject(resp);
+    }
+
+    /**
+     * 后台 POST（urlencoded form），返回响应体字符串。
+     */
+    private static String postFormRaw(String url, List<NameValuePair> params) throws Exception {
+        HttpPost post = new HttpPost(url);
+        post.setEntity(new UrlEncodedFormEntity(params, StandardCharsets.UTF_8));
+        try (CloseableHttpClient client = HttpClients.createDefault();
+             CloseableHttpResponse res = client.execute(post)) {
+            return EntityUtils.toString(res.getEntity(), StandardCharsets.UTF_8);
+        }
+    }
+
+    /**
+     * 模拟 PHP http_build_query：key、value 均做 URL 编码，用 & 连接。null 值跳过。
+     */
+    static String buildQuery(Map<String, Object> params) {
+        StringBuilder sb = new StringBuilder();
+        for (Map.Entry<String, Object> e : params.entrySet()) {
+            if (e.getValue() == null) {
+                continue;
+            }
+            if (sb.length() > 0) {
+                sb.append('&');
+            }
+            sb.append(URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8))
+                    .append('=')
+                    .append(URLEncoder.encode(String.valueOf(e.getValue()), StandardCharsets.UTF_8));
+        }
+        return sb.toString();
+    }
+}

ruoyi-admin/src/main/java/com/ruoyi/app/utils/newebpay/NewebPayConfig.java

@@ -0,0 +1,36 @@
+package com.ruoyi.app.utils.newebpay;
+
+import lombok.Data;
+
+/**
+ * 蓝新金流(NewebPay) 商店配置（运行时传入，支持多门店）。
+ *
+ * <p>每个门店在蓝新平台申请商店后会拿到一组专属金钥，由业务层从 pos_store_newebpay 读取后构造本对象。
+ * 申请入口：测试环境 https://ccore.newebpay.com/ ｜ 正式环境 https://core.newebpay.com/
+ *
+ * <p>HashKey 固定 32 字节（→ AES-256），HashIV 固定 16 字节。
+ *
+ * @author ruoyi
+ * @date 2026-06-22
+ */
+@Data
+public class NewebPayConfig {
+
+    /** 商店代号（对应 MPG 请求 MerchantID / 查询请求 MerchantID）。 */
+    private String merchantId;
+
+    /** 商店 HashKey（固定 32 字节）。 */
+    private String hashKey;
+
+    /** 商店 HashIV（固定 16 字节）。 */
+    private String hashIv;
+
+    public NewebPayConfig() {
+    }
+
+    public NewebPayConfig(String merchantId, String hashKey, String hashIv) {
+        this.merchantId = merchantId;
+        this.hashKey = hashKey;
+        this.hashIv = hashIv;
+    }
+}

ruoyi-admin/src/main/java/com/ruoyi/app/utils/newebpay/NewebPayEncryptUtil.java

@@ -0,0 +1,189 @@
+package com.ruoyi.app.utils.newebpay;
+
+import javax.crypto.Cipher;
+import javax.crypto.spec.IvParameterSpec;
+import javax.crypto.spec.SecretKeySpec;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.util.HexFormat;
+import java.util.Map;
+import java.util.TreeMap;
+
+/**
+ * 蓝新金流(NewebPay) 加密 / 签名工具。
+ *
+ * <p>对应官方手册 NDNF-1.2.2「4.1 加解密方式」：
+ * <ul>
+ *   <li>{@code AES-256-CBC + PKCS7Padding}（标准块 16 字节）→ 输出小写 hex，即请求 TradeInfo / 回应密文。</li>
+ *   <li>{@code TradeSha = SHA256("HashKey={key}&{tradeInfoHex}&HashIV={iv}")} 大写（§4.1.2，请求带）。</li>
+ *   <li>{@code CheckValue}（§4.1.6，查询请求）：{@code SHA256("IV={iv}&{Amt/MerchantID/MerchantOrderNo 排序}&Key={key}")} 大写。</li>
+ *   <li>{@code CheckCode}（§4.1.5，校验回应）：{@code SHA256("HashIV={iv}&{Amt/MerchantID/MerchantOrderNo/TradeNo 排序}&HashKey={key}")} 大写。</li>
+ * </ul>
+ *
+ * <p><b>与 ezPay 加密工具的区别</b>：ezPay 用特殊 PKCS7 块 32 + AES/CBC/NoPadding；蓝新用标准
+ * AES/CBC/PKCS5Padding（对 16 字节块等同 PKCS7），故本类独立实现，不复用 EzPayEncryptUtil。
+ * HashKey 固定 32 字节（→ AES-256），HashIV 固定 16 字节。
+ *
+ * <p>自测：{@link #main} 用 NDNF §4.1 官方示例数据验证加解密 round-trip 与 TradeSha 规则。
+ *
+ * @author ruoyi
+ * @date 2026-06-22
+ */
+public class NewebPayEncryptUtil {
+
+    /** AES-256-CBC + PKCS7 填充（Java 标准库 PKCS5Padding 对 16 字节块等同 PKCS7）。 */
+    private static final String TRANSFORMATION = "AES/CBC/PKCS5Padding";
+
+    private NewebPayEncryptUtil() {
+    }
+
+    /**
+     * AES-256-CBC 加密 → 小写 hex（MPG 请求的 TradeInfo）。
+     *
+     * @param data    明文，参数已按 http_build_query 形式拼成 {@code a=1&b=2}
+     * @param hashKey 商店 HashKey（固定 32 字节）
+     * @param hashIV  商店 HashIV（固定 16 字节）
+     * @return 小写 hex 密文
+     */
+    public static String encrypt(String data, String hashKey, String hashIV) {
+        try {
+            Cipher cipher = Cipher.getInstance(TRANSFORMATION);
+            cipher.init(Cipher.ENCRYPT_MODE,
+                    new SecretKeySpec(hashKey.getBytes(StandardCharsets.UTF_8), "AES"),
+                    new IvParameterSpec(hashIV.getBytes(StandardCharsets.UTF_8)));
+            byte[] encrypted = cipher.doFinal(data.getBytes(StandardCharsets.UTF_8));
+            return HexFormat.of().formatHex(encrypted);
+        } catch (Exception e) {
+            throw new RuntimeException("NewebPay TradeInfo 加密失败", e);
+        }
+    }
+
+    /**
+     * AES-256-CBC 解密（解密回应 / 回调里的 TradeInfo hex）。
+     *
+     * @param hexData 小写 hex 密文
+     * @return 解密后的明文（通常为 {@code a=1&b=2} 形式）
+     */
+    public static String decrypt(String hexData, String hashKey, String hashIV) {
+        try {
+            byte[] bytes = HexFormat.of().parseHex(hexData);
+            Cipher cipher = Cipher.getInstance(TRANSFORMATION);
+            cipher.init(Cipher.DECRYPT_MODE,
+                    new SecretKeySpec(hashKey.getBytes(StandardCharsets.UTF_8), "AES"),
+                    new IvParameterSpec(hashIV.getBytes(StandardCharsets.UTF_8)));
+            byte[] decrypted = cipher.doFinal(bytes);
+            return new String(decrypted, StandardCharsets.UTF_8);
+        } catch (Exception e) {
+            throw new RuntimeException("NewebPay TradeInfo 解密失败", e);
+        }
+    }
+
+    /**
+     * 请求 TradeSha：{@code SHA256("HashKey={key}&{tradeInfoHex}&HashIV={iv}")} 转大写。NDNF §4.1.2。
+     */
+    public static String genTradeSha(String tradeInfoHex, String hashKey, String hashIV) {
+        return sha256Upper("HashKey=" + hashKey + "&" + tradeInfoHex + "&HashIV=" + hashIV);
+    }
+
+    /**
+     * 单笔查询请求 CheckValue：Amt/MerchantID/MerchantOrderNo 按字母序，
+     * {@code SHA256("IV={iv}&{排序后字段}&Key={key}")} 转大写。NDNF §4.1.6。
+     */
+    public static String genCheckValue(String amt, String merchantId, String merchantOrderNo,
+                                       String hashKey, String hashIV) {
+        TreeMap<String, String> fields = new TreeMap<>();
+        fields.put("Amt", amt);
+        fields.put("MerchantID", merchantId);
+        fields.put("MerchantOrderNo", merchantOrderNo);
+        return sha256Upper("IV=" + hashIV + "&" + joinSorted(fields) + "&Key=" + hashKey);
+    }
+
+    /**
+     * 回应 CheckCode：Amt/MerchantID/MerchantOrderNo/TradeNo 等字段按字母序，
+     * {@code SHA256("HashIV={iv}&{排序后字段}&HashKey={key}")} 转大写。NDNF §4.1.5。
+     *
+     * @param fields 回应中参与校验的字段（调用方按接口塞入对应键名）
+     */
+    public static String genCheckCode(Map<String, String> fields, String hashKey, String hashIV) {
+        TreeMap<String, String> sorted = new TreeMap<>(fields);
+        return sha256Upper("HashIV=" + hashIV + "&" + joinSorted(sorted) + "&HashKey=" + hashKey);
+    }
+
+    /** 将字段按 key 字母序拼接为 {@code k1=v1&k2=v2...}。 */
+    private static String joinSorted(TreeMap<String, String> sorted) {
+        StringBuilder sb = new StringBuilder();
+        for (Map.Entry<String, String> e : sorted.entrySet()) {
+            if (sb.length() > 0) {
+                sb.append('&');
+            }
+            sb.append(e.getKey()).append('=').append(e.getValue());
+        }
+        return sb.toString();
+    }
+
+    private static String sha256Upper(String raw) {
+        try {
+            MessageDigest md = MessageDigest.getInstance("SHA-256");
+            return HexFormat.of().formatHex(md.digest(raw.getBytes(StandardCharsets.UTF_8))).toUpperCase();
+        } catch (Exception e) {
+            throw new RuntimeException("SHA256 计算失败", e);
+        }
+    }
+
+    // ===================== 自测：NDNF §4.1 官方示例 =====================
+    public static void main(String[] args) {
+        // NDNF §4.1 Step0 商店金钥
+        String key = "Fs5cX1TGqYM2PpdbE14a9H83YQSQF5jn"; // 32 字节
+        String iv = "C6AcmfqJILwgnhIP";                   // 16 字节
+
+        // NDNF §4.1 Step1 请求字符串（http_build_query 后）
+        String plain = "MerchantID=MS127874575&RespondType=String&TimeStamp=1695795410&Version=2.0"
+                + "&MerchantOrderNo=Vanespl_ec_1695795410&Amt=30&ItemDesc=test"
+                + "&NotifyURL=https%3A%2F%2Fwebhook.site%2Fd4db5ad1-2278-466a-9d66-78585c0dbadb";
+
+        // NDNF §4.1 Step2 官方加密结果（hex）
+        String docHex = "f79eac33c4f3245d58f17b544c5d38b09457a6d77e77bae6f10fcc7236fe153c"
+                + "cef1a80001c0746afc063a7570f80ad970d8a32c72332c9ec5547410188007876"
+                + "bdca2bafa52d07d31b6b183f2204d6e4feee6d245e286ab198cf95422ad5843c"
+                + "7696fc943cbb65979ad207607d4b5d97dac4a90ccd5e7a37adb7d7062e838be09d94e8c5dfa145c048e"
+                + "17feabe58c2e310792f0f50f5af32961ffb07ff6649ae1021ad558242551de5f09316e3182e1987"
+                + "75e5d1ad5b66a70be290004de750fa85d86b0c2f087b40005d89e048be2ab6fd83f1c522494c093426a10a1f73fe4";
+        // NDNF §4.1 Step3 官方 TradeSha
+        String expectedSha = "84E4D9F96537E029F8450BE1E759080F9AF6995921B7F6F9AAFDDD2C36E7B287";
+
+        int pass = 0, fail = 0;
+
+        // 1) 加解密 round-trip（对称性，必过）
+        String enc = encrypt(plain, key, iv);
+        String dec = decrypt(enc, key, iv);
+        if (plain.equals(dec)) {
+            System.out.println("[PASS] encrypt/decrypt round-trip");
+            pass++;
+        } else {
+            System.out.println("[FAIL] round-trip  dec=" + dec);
+            fail++;
+        }
+
+        // 2) TradeSha 规则：用官方 Step2 hex 计算应得官方 Step3 值
+        String sha = genTradeSha(docHex, key, iv);
+        if (expectedSha.equals(sha)) {
+            System.out.println("[PASS] genTradeSha (官方示例)");
+            pass++;
+        } else {
+            System.out.println("[FAIL] genTradeSha  got=" + sha);
+            fail++;
+        }
+
+        // 3) encrypt(官方明文) == 官方 hex（验证加密与蓝新规范完全一致）
+        if (docHex.equals(enc)) {
+            System.out.println("[PASS] encrypt 与官方示例一致");
+            pass++;
+        } else {
+            // round-trip + TradeSha 已通过即说明实现正确；此处置 WARN 以防 PDF 文本拼接误差
+            System.out.println("[WARN] encrypt 与官方 hex 不完全一致（可能是 PDF 文本换行拼接误差），"
+                    + "round-trip 与 TradeSha 已通过即实现正确。");
+        }
+
+        System.out.println("\n结果: " + pass + " passed, " + fail + " failed");
+    }
+}

ruoyi-admin/src/main/resources/application.yml

@@ -22,6 +22,30 @@ ezpay:
   # 开票/作废根地址（测试环境 cinv.ezpay.com.tw；上线改 https://inv.ezpay.com.tw）
   base-url: https://cinv.ezpay.com.tw
 
+# 蓝新金流(NewebPay)线上支付配置
+newebpay:
+  # 幕前支付根地址（测试环境 ccore.newebpay.com；正式 core.newebpay.com）
+  base-url: https://ccore.newebpay.com
+  # 支付结果背景通知网址（须公网 80/443，蓝新服务器回调，对应 /pay/newebpay/notify）
+  notify-url: https://your-public-domain/pay/newebpay/notify
+  # 支付完成返回页（须公网，对应 /pay/newebpay/return，仅引导不改状态）
+  return-url: https://your-public-domain/pay/newebpay/return
+  # 支付完成前端结果页基址（ReturnURL 解析订单号后重定向到此，自动拼接 ?ddId=）
+  front-result-url: https://your-h5-domain/#/pages/payResult
+  # MPG 串接程式版本
+  mpg-version: "2.3"
+
+# IM 即时沟通配置
+im:
+  # IM 平台根地址（测试环境 test-im.abtim-my.com；正式环境另行配置）
+  base-url: https://test-im.abtim-my.com
+  # 平台级鉴权令牌（extToken）
+  ext-token: 92a88467-6eca-11f1-9dd5-00163e1eec55
+  # 创建用户接口路径
+  create-path: /bot/extCreate
+  # 连接/读取超时（毫秒）
+  timeout-ms: 5000
+
 # 开发环境配置
 server:
   # 服务器的HTTP端口，默认为8080

ruoyi-system/src/main/java/com/ruoyi/system/domain/InfoUser.java

@@ -7,6 +7,8 @@ import com.baomidou.mybatisplus.annotation.TableId;
 import com.baomidou.mybatisplus.annotation.TableName;
 import com.ruoyi.common.annotation.Excel;
 import lombok.Data;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;
 import lombok.EqualsAndHashCode;
 import org.apache.commons.lang3.builder.ToStringBuilder;
 import org.apache.commons.lang3.builder.ToStringStyle;
@@ -178,6 +180,15 @@ public class InfoUser
     @TableField(exist = false)
     private Double juli;
 
+    /** IM 平台 API 密钥（extCreate 返回） */
+    @Excel(name = "IM apiKey")
+    private String imApiKey;
+
+    /** IM 平台用户ID（extCreate 返回，长整型）。序列化为字符串，规避前端 Long 精度丢失 */
+    @Excel(name = "IM userId")
+    @JsonSerialize(using = ToStringSerializer.class)
+    private Long imUserId;
+
 
     public void setUserId(Long userId)
     {

ruoyi-system/src/main/java/com/ruoyi/system/domain/PosOrderInvoice.java

@@ -76,8 +76,17 @@ public class PosOrderInvoice {
     /** 失败原因 */
     private String failReason;
 
-    /** 发票查看凭证 / 链接 */
-    private String invoiceUrl;
+    /** ezPay 交易流水号（InvoiceTransNo） */
+    private String invoiceTransNo;
+
+    /** 发票条码码值（PrintFlag=Y 才有，兑奖扫描用） */
+    private String invoiceBarCode;
+
+    /** 发票左二维码码值（PrintFlag=Y 才有，含发票核心信息+加密防伪） */
+    private String invoiceQrcodeL;
+
+    /** 发票右二维码码值（PrintFlag=Y 才有，含中文商品明细） */
+    private String invoiceQrcodeR;
 
     /** 申请开票时间 */
     private Date applyTime;

ruoyi-system/src/main/java/com/ruoyi/system/domain/PosOrderPayment.java

@@ -0,0 +1,73 @@
+package com.ruoyi.system.domain;
+
+import com.baomidou.mybatisplus.annotation.FieldFill;
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import com.fasterxml.jackson.annotation.JsonFormat;
+import lombok.Data;
+
+import java.util.Date;
+
+/**
+ * 蓝新支付交易流水 pos_order_payment
+ *
+ * <p>每笔蓝新交易一条。承载幂等（按 trade_no）与对账明细。
+ * 同一订单多次发起产生多行（不同 merchant_order_no），但同一 trade_no 只对应一行。
+ *
+ * @author ruoyi
+ * @date 2026-06-22
+ */
+@Data
+@TableName(value = "pos_order_payment")
+public class PosOrderPayment {
+
+    private static final long serialVersionUID = 1L;
+
+    /** 主键 */
+    @TableId(type = IdType.AUTO)
+    private Long id;
+
+    /** 系统订单号（关联 pos_order.dd_id） */
+    private String ddId;
+
+    /** 商店订单号 MerchantOrderNo（发起生成，门店内唯一） */
+    private String merchantOrderNo;
+
+    /** 蓝新交易序号 TradeNo（回调获得，幂等键，唯一索引） */
+    private String tradeNo;
+
+    /** 门店ID */
+    private Long storeId;
+
+    /** 蓝新商店代号（发起时的门店凭证） */
+    private String merchantId;
+
+    /** 支付方式: CREDIT/LINEPAY/APPLEPAY（回调确定） */
+    private String payType;
+
+    /** 交易金额（整数元，= 订单 amount） */
+    private Integer amount;
+
+    /** 支付状态: 0未支付/1已支付/2失败 */
+    private Integer payStatus;
+
+    /** 授权码（信用卡回调 Auth） */
+    private String authCode;
+
+    /** 支付完成时间（回调 PayTime） */
+    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    private Date payTime;
+
+    /** 回调原始解密结果（调试/对账） */
+    private String callbackRaw;
+
+    /** 创建时间（发起时间） */
+    @TableField(fill = FieldFill.INSERT)
+    private Date createTime;
+
+    /** 更新时间 */
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    private Date updateTime;
+}

ruoyi-system/src/main/java/com/ruoyi/system/domain/PosStoreNewebpay.java

@@ -0,0 +1,80 @@
+package com.ruoyi.system.domain;
+
+import com.baomidou.mybatisplus.annotation.FieldFill;
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.util.Date;
+
+/**
+ * 门店蓝新金流支付凭证 pos_store_newebpay
+ *
+ * <p>与 pos_store 1:1，记录该门店的蓝新申请状态、启用开关、凭证、启用的支付方式。
+ * 复用 009 pos_store_ezpay 的状态机模式（0未申请/1申请中/2已开通）。
+ * 门店无此行即视为「未申请」。
+ *
+ * @author ruoyi
+ * @date 2026-06-22
+ */
+@Data
+@TableName(value = "pos_store_newebpay")
+public class PosStoreNewebpay {
+
+    private static final long serialVersionUID = 1L;
+
+    /** 主键 */
+    @TableId(type = IdType.AUTO)
+    private Long id;
+
+    /** 关联 pos_store.id（门店），唯一 */
+    private Long storeId;
+
+    /** 申请状态:0未申请/1申请中/2已开通 */
+    private Integer newebpayStatus;
+
+    /** 启用开关:0停用/1启用（仅 status=2 有意义） */
+    private Integer isEnabled;
+
+    /** 蓝新商店代号 MerchantID */
+    private String merchantId;
+
+    /** 蓝新 HashKey（固定 32 字节） */
+    private String hashKey;
+
+    /** 蓝新 HashIV（固定 16 字节） */
+    private String hashIv;
+
+    /** 启用的支付方式，逗号分隔：CREDIT,LINEPAY,APPLEPAY */
+    private String enabledPayments;
+
+    /** 提交申请时间（0→1） */
+    private Date applyTime;
+
+    /** 开通时间（→2） */
+    private Date approvedTime;
+
+    /** 最近一次凭证验证结果 */
+    private String lastVerifyResult;
+
+    /** 备注 */
+    private String remark;
+
+    /** 创建时间 */
+    @TableField(fill = FieldFill.INSERT)
+    private Date createTime;
+
+    /** 更新时间 */
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    private Date updateTime;
+
+    /** 创建人 */
+    @TableField(fill = FieldFill.INSERT)
+    private String createBy;
+
+    /** 更新人 */
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    private String updateBy;
+}

ruoyi-system/src/main/java/com/ruoyi/system/domain/dto/StoreNewebpayCredentialDto.java

@@ -0,0 +1,37 @@
+package com.ruoyi.system.domain.dto;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+/**
+ * 运营录入蓝新金流凭证入参。
+ *
+ * @author ruoyi
+ * @date 2026-06-22
+ */
+@Data
+public class StoreNewebpayCredentialDto {
+
+    /** 门店 id */
+    @NotNull(message = "门店不能为空")
+    private Long storeId;
+
+    /** 蓝新商店代号 MerchantID */
+    @NotBlank(message = "商店代号不能为空")
+    private String merchantId;
+
+    /** 蓝新 HashKey（固定 32 字节） */
+    @NotBlank(message = "HashKey 不能为空")
+    @Size(min = 32, max = 32, message = "HashKey 必须为 32 位")
+    private String hashKey;
+
+    /** 蓝新 HashIV（固定 16 字节） */
+    @NotBlank(message = "HashIV 不能为空")
+    @Size(min = 16, max = 16, message = "HashIV 必须为 16 位")
+    private String hashIv;
+
+    /** 启用的支付方式：CREDIT,LINEPAY,APPLEPAY（可空，默认 CREDIT） */
+    private String enabledPayments;
+}

ruoyi-system/src/main/java/com/ruoyi/system/domain/vo/ImAccountVo.java

@@ -0,0 +1,21 @@
+package com.ruoyi.system.domain.vo;
+
+import lombok.Data;
+
+/**
+ * IM 账号凭证 VO（开通 IM 账号接口返回）。
+ *
+ * <p>imUserId 用 String 返回，规避前端 JS 对 19 位 Long 的精度丢失。
+ *
+ * @author ruoyi
+ * @date 2026-06-23
+ */
+@Data
+public class ImAccountVo {
+
+    /** IM 平台 API 密钥 */
+    private String imApiKey;
+
+    /** IM 平台用户ID（字符串，规避前端 Long 精度丢失） */
+    private String imUserId;
+}

ruoyi-system/src/main/java/com/ruoyi/system/domain/vo/PosOrderInvoiceVo.java

@@ -67,8 +67,17 @@ public class PosOrderInvoiceVo {
     /** 失败原因 */
     private String failReason;
 
-    /** 发票查看凭证 */
-    private String invoiceUrl;
+    /** ezPay 交易流水号（InvoiceTransNo） */
+    private String invoiceTransNo;
+
+    /** 发票条码码值（PrintFlag=Y 才有） */
+    private String invoiceBarCode;
+
+    /** 发票左二维码码值（PrintFlag=Y 才有） */
+    private String invoiceQrcodeL;
+
+    /** 发票右二维码码值（PrintFlag=Y 才有） */
+    private String invoiceQrcodeR;
 
     /** 申请时间 */
     private Date applyTime;

ruoyi-system/src/main/java/com/ruoyi/system/domain/vo/PosStoreNewebpayVo.java

@@ -0,0 +1,74 @@
+package com.ruoyi.system.domain.vo;
+
+import lombok.Data;
+
+import java.util.Date;
+
+/**
+ * 门店蓝新金流开通管理列表行（pos_store LEFT JOIN pos_store_newebpay）。
+ *
+ * <p>仿 {@link PosStoreEzpayVo}。蓝新支付无统编/免用发票概念，故无 ubn/invoiceExempt。
+ *
+ * @author ruoyi
+ * @date 2026-06-22
+ */
+@Data
+public class PosStoreNewebpayVo {
+
+    /** 门店 id */
+    private Long storeId;
+
+    /** 门店名称 */
+    private String posName;
+
+    /** 所属商家 id */
+    private Long userId;
+
+    /** 所属商家用户名 */
+    private String userName;
+
+    /** 是否摊位 0=店铺 1=摊位 */
+    private Integer isStall;
+
+    /** 是否关联夜市 */
+    private Integer isNightMarket;
+
+    /** 夜市id */
+    private Long nightMarketId;
+
+    /** 蓝新申请状态:0未申请/1申请中/2已开通（无行=0） */
+    private Integer newebpayStatus;
+
+    /** 启用开关:0停用/1启用 */
+    private Integer isEnabled;
+
+    /** 是否已录入商店代号（前端展示「凭证已填」） */
+    private Integer hasMerchantId;
+
+    /** 蓝新商店代号（详情用，列表可不下发） */
+    private String merchantId;
+
+    /** 蓝新 HashKey（详情回显用，仅平台后台核对） */
+    private String hashKey;
+
+    /** 蓝新 HashIV（详情回显用） */
+    private String hashIv;
+
+    /** 启用的支付方式：CREDIT,LINEPAY,APPLEPAY */
+    private String enabledPayments;
+
+    /** 备注（详情用） */
+    private String remark;
+
+    /** 提交申请时间 */
+    private Date applyTime;
+
+    /** 开通时间 */
+    private Date approvedTime;
+
+    /** 最近一次凭证验证结果 */
+    private String lastVerifyResult;
+
+    /** 查询用快捷过滤：needApply=还要去开通 / notEnabled=还没开通（不映射列） */
+    private transient String quickFilter;
+}

ruoyi-system/src/main/java/com/ruoyi/system/mapper/PosOrderPaymentMapper.java

@@ -0,0 +1,16 @@
+package com.ruoyi.system.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.ruoyi.system.domain.PosOrderPayment;
+
+/**
+ * 蓝新支付交易流水 Mapper。
+ *
+ * <p>基础 CRUD 由 MyBatis-Plus {@link BaseMapper} 提供；
+ * 按 trade_no / dd_id / merchant_order_no 查询用 LambdaQueryWrapper。
+ *
+ * @author ruoyi
+ * @date 2026-06-22
+ */
+public interface PosOrderPaymentMapper extends BaseMapper<PosOrderPayment> {
+}

ruoyi-system/src/main/java/com/ruoyi/system/mapper/PosStoreNewebpayMapper.java

@@ -0,0 +1,24 @@
+package com.ruoyi.system.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.ruoyi.system.domain.PosStoreNewebpay;
+import com.ruoyi.system.domain.vo.PosStoreNewebpayVo;
+
+import java.util.List;
+
+/**
+ * 门店蓝新金流支付凭证 Mapper。
+ *
+ * <p>基础 CRUD 由 {@link BaseMapper} 提供；开通管理列表/详情（join pos_store）见对应 XML。
+ *
+ * @author ruoyi
+ * @date 2026-06-22
+ */
+public interface PosStoreNewebpayMapper extends BaseMapper<PosStoreNewebpay> {
+
+    /** 开通管理列表（pos_store LEFT JOIN pos_store_newebpay）。 */
+    List<PosStoreNewebpayVo> selectNewebpayStoreList(PosStoreNewebpayVo query);
+
+    /** 门店蓝新详情。 */
+    PosStoreNewebpayVo selectNewebpayStoreDetail(Long storeId);
+}

ruoyi-system/src/main/java/com/ruoyi/system/service/IPosOrderPaymentService.java

@@ -0,0 +1,38 @@
+package com.ruoyi.system.service;
+
+import com.ruoyi.system.domain.PosOrderPayment;
+
+import java.util.Date;
+
+/**
+ * 蓝新支付交易流水 Service。
+ *
+ * <p>承载发起（createPayment）、幂等查询、回调成功/失败写入。US1 发起 + US2 回调共用。
+ *
+ * @author ruoyi
+ * @date 2026-06-22
+ */
+public interface IPosOrderPaymentService {
+
+    /** 发起支付流水：同 merchantOrderNo 已存在则更新（重新发起），否则新增（pay_status=0）。 */
+    int createPayment(String ddId, String merchantOrderNo, Long storeId, String merchantId, Integer amount);
+
+    /** 按蓝新交易序号查（回调幂等键）。 */
+    PosOrderPayment getByTradeNo(String tradeNo);
+
+    /** 按商店订单号查。 */
+    PosOrderPayment getByMerchantOrderNo(String merchantOrderNo);
+
+    /** 按系统订单号查最近一笔。 */
+    PosOrderPayment getLatestByDdId(String ddId);
+
+    /**
+     * 标记支付成功（回调/查询补单用）。
+     * 幂等：若该 tradeNo 已 pay_status=1 则返回 0 不重复处理。
+     */
+    int markSuccess(String ddId, String merchantOrderNo, Long storeId, String merchantId, Integer amount,
+                    String tradeNo, String payType, String authCode, Date payTime, String callbackRaw);
+
+    /** 标记支付失败（回调 Status≠SUCCESS）。 */
+    int markFail(String merchantOrderNo, String tradeNo, String payType, String callbackRaw);
+}

ruoyi-system/src/main/java/com/ruoyi/system/service/IPosStoreNewebpayService.java

@@ -0,0 +1,51 @@
+package com.ruoyi.system.service;
+
+import com.ruoyi.system.domain.PosStoreNewebpay;
+import com.ruoyi.system.domain.dto.StoreNewebpayCredentialDto;
+import com.ruoyi.system.domain.vo.PosStoreNewebpayVo;
+
+import java.util.List;
+
+/**
+ * 门店蓝新金流支付凭证 Service（纯 DB；联网验证在 Controller 层）。
+ *
+ * <p>复用 009 pos_store_ezpay 的开通管理状态机：0未申请/1申请中/2已开通。
+ *
+ * @author ruoyi
+ * @date 2026-06-22
+ */
+public interface IPosStoreNewebpayService {
+
+    /** 取门店「已开通且启用」的蓝新凭证；否则 null。发起支付前判断用。 */
+    PosStoreNewebpay getEnabledConfig(Long storeId);
+
+    /** 按 storeId 取行；无行则返回 status=0 的内存对象。 */
+    PosStoreNewebpay getOrCreateByStoreId(Long storeId);
+
+    /** 按蓝新 MerchantID 查凭证（回调用）。 */
+    PosStoreNewebpay getByMerchantId(String merchantId);
+
+    /** 开通管理列表。 */
+    List<PosStoreNewebpayVo> selectNewebpayStoreList(PosStoreNewebpayVo query);
+
+    /** 门店蓝新详情（不存在抛异常）。 */
+    PosStoreNewebpayVo selectNewebpayStoreDetail(Long storeId);
+
+    /** 发起申请 0→1。 */
+    int apply(Long storeId);
+
+    /** 录入凭证并标记已开通（→2，is_enabled=1）。 */
+    int enableWithCredentials(StoreNewebpayCredentialDto dto);
+
+    /** 停用/恢复（仅已开通）。 */
+    int toggleEnable(Long storeId);
+
+    /** 重置状态（凭证作废，→1）。 */
+    int reset(Long storeId);
+
+    /** 设置启用的支付方式（CREDIT/LINEPAY/APPLEPAY）。 */
+    int setEnabledPayments(Long storeId, String enabledPayments);
+
+    /** 记录凭证验证结果。 */
+    int recordVerifyResult(Long storeId, String result);
+}

ruoyi-system/src/main/java/com/ruoyi/system/service/impl/PosOrderPaymentServiceImpl.java

@@ -0,0 +1,132 @@
+package com.ruoyi.system.service.impl;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.ruoyi.system.domain.PosOrderPayment;
+import com.ruoyi.system.mapper.PosOrderPaymentMapper;
+import com.ruoyi.system.service.IPosOrderPaymentService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Service;
+
+import java.util.Date;
+
+/**
+ * 蓝新支付交易流水 Service 实现。
+ *
+ * @author ruoyi
+ * @date 2026-06-22
+ */
+@Service
+public class PosOrderPaymentServiceImpl implements IPosOrderPaymentService {
+
+    @Autowired
+    private PosOrderPaymentMapper posOrderPaymentMapper;
+
+    private static final int PAY_STATUS_UNPAID = 0;
+    private static final int PAY_STATUS_SUCCESS = 1;
+    private static final int PAY_STATUS_FAIL = 2;
+
+    @Override
+    public int createPayment(String ddId, String merchantOrderNo, Long storeId, String merchantId, Integer amount) {
+        PosOrderPayment exist = getByMerchantOrderNo(merchantOrderNo);
+        Date now = new Date();
+        if (exist != null) {
+            // 重新发起：更新金额/门店（保留 id），pay_status 重置为未支付
+            exist.setDdId(ddId);
+            exist.setStoreId(storeId);
+            exist.setMerchantId(merchantId);
+            exist.setAmount(amount);
+            exist.setPayStatus(PAY_STATUS_UNPAID);
+            exist.setUpdateTime(now);
+            return posOrderPaymentMapper.updateById(exist);
+        }
+        PosOrderPayment p = new PosOrderPayment();
+        p.setDdId(ddId);
+        p.setMerchantOrderNo(merchantOrderNo);
+        p.setStoreId(storeId);
+        p.setMerchantId(merchantId);
+        p.setAmount(amount);
+        p.setPayStatus(PAY_STATUS_UNPAID);
+        p.setCreateTime(now);
+        p.setUpdateTime(now);
+        return posOrderPaymentMapper.insert(p);
+    }
+
+    @Override
+    public PosOrderPayment getByTradeNo(String tradeNo) {
+        if (tradeNo == null || tradeNo.isEmpty()) {
+            return null;
+        }
+        return posOrderPaymentMapper.selectOne(
+                new LambdaQueryWrapper<PosOrderPayment>().eq(PosOrderPayment::getTradeNo, tradeNo));
+    }
+
+    @Override
+    public PosOrderPayment getByMerchantOrderNo(String merchantOrderNo) {
+        if (merchantOrderNo == null || merchantOrderNo.isEmpty()) {
+            return null;
+        }
+        return posOrderPaymentMapper.selectOne(
+                new LambdaQueryWrapper<PosOrderPayment>().eq(PosOrderPayment::getMerchantOrderNo, merchantOrderNo));
+    }
+
+    @Override
+    public PosOrderPayment getLatestByDdId(String ddId) {
+        if (ddId == null || ddId.isEmpty()) {
+            return null;
+        }
+        return posOrderPaymentMapper.selectOne(
+                new LambdaQueryWrapper<PosOrderPayment>()
+                        .eq(PosOrderPayment::getDdId, ddId)
+                        .orderByDesc(PosOrderPayment::getId)
+                        .last("LIMIT 1"));
+    }
+
+    @Override
+    public int markSuccess(String ddId, String merchantOrderNo, Long storeId, String merchantId, Integer amount,
+                            String tradeNo, String payType, String authCode, Date payTime, String callbackRaw) {
+        // 幂等：同 tradeNo 已成功则跳过
+        PosOrderPayment byTrade = getByTradeNo(tradeNo);
+        if (byTrade != null && Integer.valueOf(PAY_STATUS_SUCCESS).equals(byTrade.getPayStatus())) {
+            return 0;
+        }
+        PosOrderPayment row = byTrade != null ? byTrade : getByMerchantOrderNo(merchantOrderNo);
+        boolean isNew = false;
+        if (row == null) {
+            row = new PosOrderPayment();
+            isNew = true;
+        }
+        row.setDdId(ddId);
+        row.setMerchantOrderNo(merchantOrderNo);
+        row.setStoreId(storeId);
+        row.setMerchantId(merchantId);
+        row.setAmount(amount);
+        row.setTradeNo(tradeNo);
+        row.setPayType(payType);
+        row.setAuthCode(authCode);
+        row.setPayTime(payTime);
+        row.setCallbackRaw(callbackRaw);
+        row.setPayStatus(PAY_STATUS_SUCCESS);
+        Date now = new Date();
+        if (isNew) {
+            row.setCreateTime(now);
+            row.setUpdateTime(now);
+            return posOrderPaymentMapper.insert(row);
+        }
+        row.setUpdateTime(now);
+        return posOrderPaymentMapper.updateById(row);
+    }
+
+    @Override
+    public int markFail(String merchantOrderNo, String tradeNo, String payType, String callbackRaw) {
+        PosOrderPayment row = getByMerchantOrderNo(merchantOrderNo);
+        if (row == null) {
+            return 0; // 无发起记录，忽略
+        }
+        row.setTradeNo(tradeNo);
+        row.setPayType(payType);
+        row.setCallbackRaw(callbackRaw);
+        row.setPayStatus(PAY_STATUS_FAIL);
+        row.setUpdateTime(new Date());
+        return posOrderPaymentMapper.updateById(row);
+    }
+}

ruoyi-system/src/main/java/com/ruoyi/system/service/impl/PosStoreNewebpayServiceImpl.java

@@ -0,0 +1,180 @@
+package com.ruoyi.system.service.impl;
+
+import cn.hutool.core.util.StrUtil;
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.ruoyi.common.exception.ServiceException;
+import com.ruoyi.common.utils.SecurityUtils;
+import com.ruoyi.system.domain.PosStoreNewebpay;
+import com.ruoyi.system.domain.dto.StoreNewebpayCredentialDto;
+import com.ruoyi.system.domain.vo.PosStoreNewebpayVo;
+import com.ruoyi.system.mapper.PosStoreNewebpayMapper;
+import com.ruoyi.system.service.IPosStoreNewebpayService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Service;
+
+import java.util.Date;
+import java.util.List;
+
+/**
+ * 门店蓝新金流支付凭证 Service 实现（纯 DB 操作）。
+ *
+ * <p>仿 {@link PosStoreEzpayServiceImpl} 状态机与审计字段处理。
+ *
+ * @author ruoyi
+ * @date 2026-06-22
+ */
+@Service
+public class PosStoreNewebpayServiceImpl implements IPosStoreNewebpayService {
+
+    @Autowired
+    private PosStoreNewebpayMapper posStoreNewebpayMapper;
+
+    private static final int STATUS_NOT_APPLIED = 0;
+    private static final int STATUS_APPLYING = 1;
+    private static final int STATUS_ENABLED = 2;
+
+    @Override
+    public PosStoreNewebpay getEnabledConfig(Long storeId) {
+        PosStoreNewebpay row = getOrCreateByStoreId(storeId);
+        if (row == null || row.getId() == null) {
+            return null;
+        }
+        boolean opened = Integer.valueOf(STATUS_ENABLED).equals(row.getNewebpayStatus());
+        boolean enabled = row.getIsEnabled() != null && row.getIsEnabled() == 1;
+        return (opened && enabled) ? row : null;
+    }
+
+    @Override
+    public PosStoreNewebpay getOrCreateByStoreId(Long storeId) {
+        if (storeId == null) {
+            return null;
+        }
+        PosStoreNewebpay row = posStoreNewebpayMapper.selectOne(
+                new LambdaQueryWrapper<PosStoreNewebpay>().eq(PosStoreNewebpay::getStoreId, storeId));
+        if (row == null) {
+            row = new PosStoreNewebpay();
+            row.setStoreId(storeId);
+            row.setNewebpayStatus(STATUS_NOT_APPLIED);
+            row.setIsEnabled(1);
+        }
+        return row;
+    }
+
+    @Override
+    public PosStoreNewebpay getByMerchantId(String merchantId) {
+        if (merchantId == null || merchantId.isEmpty()) {
+            return null;
+        }
+        return posStoreNewebpayMapper.selectOne(
+                new LambdaQueryWrapper<PosStoreNewebpay>().eq(PosStoreNewebpay::getMerchantId, merchantId));
+    }
+
+    @Override
+    public List<PosStoreNewebpayVo> selectNewebpayStoreList(PosStoreNewebpayVo query) {
+        return posStoreNewebpayMapper.selectNewebpayStoreList(query);
+    }
+
+    @Override
+    public PosStoreNewebpayVo selectNewebpayStoreDetail(Long storeId) {
+        PosStoreNewebpayVo vo = posStoreNewebpayMapper.selectNewebpayStoreDetail(storeId);
+        if (vo == null) {
+            throw new ServiceException("门店不存在");
+        }
+        return vo;
+    }
+
+    @Override
+    public int apply(Long storeId) {
+        PosStoreNewebpay row = getOrCreateByStoreId(storeId);
+        if (!Integer.valueOf(STATUS_NOT_APPLIED).equals(row.getNewebpayStatus())) {
+            throw new ServiceException("当前状态不允许发起申请");
+        }
+        row.setNewebpayStatus(STATUS_APPLYING);
+        row.setApplyTime(new Date());
+        return saveOrUpdate(row);
+    }
+
+    @Override
+    public int enableWithCredentials(StoreNewebpayCredentialDto dto) {
+        PosStoreNewebpay row = getOrCreateByStoreId(dto.getStoreId());
+        row.setMerchantId(dto.getMerchantId());
+        row.setHashKey(dto.getHashKey());
+        row.setHashIv(dto.getHashIv());
+        if (StrUtil.isNotBlank(dto.getEnabledPayments())) {
+            row.setEnabledPayments(dto.getEnabledPayments().toUpperCase());
+        } else {
+            row.setEnabledPayments("CREDIT");
+        }
+        row.setNewebpayStatus(STATUS_ENABLED);
+        row.setIsEnabled(1);
+        row.setApprovedTime(new Date());
+        row.setLastVerifyResult("PASS");
+        return saveOrUpdate(row);
+    }
+
+    @Override
+    public int toggleEnable(Long storeId) {
+        PosStoreNewebpay row = getOrCreateByStoreId(storeId);
+        if (!Integer.valueOf(STATUS_ENABLED).equals(row.getNewebpayStatus())) {
+            throw new ServiceException("仅已开通门店可停用/恢复");
+        }
+        int next = Integer.valueOf(1).equals(row.getIsEnabled()) ? 0 : 1;
+        row.setIsEnabled(next);
+        return saveOrUpdate(row);
+    }
+
+    @Override
+    public int reset(Long storeId) {
+        PosStoreNewebpay row = getOrCreateByStoreId(storeId);
+        row.setNewebpayStatus(STATUS_APPLYING);
+        row.setApprovedTime(null);
+        return saveOrUpdate(row);
+    }
+
+    @Override
+    public int setEnabledPayments(Long storeId, String enabledPayments) {
+        PosStoreNewebpay row = getOrCreateByStoreId(storeId);
+        row.setEnabledPayments(enabledPayments == null || enabledPayments.isEmpty()
+                ? "CREDIT" : enabledPayments.toUpperCase());
+        return saveOrUpdate(row);
+    }
+
+    @Override
+    public int recordVerifyResult(Long storeId, String result) {
+        PosStoreNewebpay row = getOrCreateByStoreId(storeId);
+        row.setLastVerifyResult(truncate(result));
+        return saveOrUpdate(row);
+    }
+
+    // ===== 内部辅助 =====
+
+    private int saveOrUpdate(PosStoreNewebpay row) {
+        Date now = new Date();
+        String user = currentUser();
+        if (row.getId() == null) {
+            row.setCreateTime(now);
+            row.setUpdateTime(now);
+            row.setCreateBy(user);
+            row.setUpdateBy(user);
+            return posStoreNewebpayMapper.insert(row);
+        }
+        row.setUpdateTime(now);
+        row.setUpdateBy(user);
+        return posStoreNewebpayMapper.updateById(row);
+    }
+
+    private String currentUser() {
+        try {
+            return SecurityUtils.getUsername();
+        } catch (Exception e) {
+            return "system";
+        }
+    }
+
+    private static String truncate(String s) {
+        if (s == null) {
+            return "";
+        }
+        return s.length() > 240 ? s.substring(0, 240) : s;
+    }
+}

ruoyi-system/src/main/resources/mapper/chanting/PosOrderInvoiceMapper.xml

@@ -62,7 +62,10 @@ PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
             i.sales_amt        AS salesAmt,
             i.tax_amt          AS taxAmt,
             i.fail_reason      AS failReason,
-            i.invoice_url      AS invoiceUrl,
+            i.invoice_trans_no AS invoiceTransNo,
+            i.invoice_bar_code AS invoiceBarCode,
+            i.invoice_qrcode_l AS invoiceQrcodeL,
+            i.invoice_qrcode_r AS invoiceQrcodeR,
             i.apply_time       AS applyTime,
             i.issue_time       AS issueTime,
             i.invalid_time     AS invalidTime,

ruoyi-system/src/main/resources/mapper/chanting/PosStoreNewebpayMapper.xml

@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE mapper
+PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
+"http://mybatis.org/dtd/mybatis-3-mapper.dtd">
+<mapper namespace="com.ruoyi.system.mapper.PosStoreNewebpayMapper">
+
+    <!-- 门店蓝新支付开通管理列表：列名别名对齐 VO 属性，resultType 自动映射 -->
+    <select id="selectNewebpayStoreList" parameterType="com.ruoyi.system.domain.vo.PosStoreNewebpayVo"
+            resultType="com.ruoyi.system.domain.vo.PosStoreNewebpayVo">
+        SELECT
+            s.id              AS storeId,
+            s.pos_name        AS posName,
+            s.user_id         AS userId,
+            u.user_name       AS userName,
+            s.is_stall        AS isStall,
+            s.is_night_market AS isNightMarket,
+            s.night_market_id AS nightMarketId,
+            IFNULL(n.newebpay_status, 0) AS newebpayStatus,
+            IFNULL(n.is_enabled, 1)      AS isEnabled,
+            CASE WHEN n.merchant_id IS NULL OR n.merchant_id = '' THEN 0 ELSE 1 END AS hasMerchantId,
+            n.enabled_payments AS enabledPayments,
+            n.apply_time       AS applyTime,
+            n.approved_time    AS approvedTime,
+            n.last_verify_result AS lastVerifyResult
+        FROM pos_store s
+        LEFT JOIN pos_store_newebpay n ON n.store_id = s.id
+        LEFT JOIN info_user u ON u.user_id = s.user_id
+        <where>
+            s.del_flag = '0'
+            <if test="isStall != null"> AND s.is_stall = #{isStall} </if>
+            <if test="posName != null and posName != ''"> AND s.pos_name LIKE concat('%', #{posName}, '%') </if>
+            <if test="newebpayStatus != null"> AND IFNULL(n.newebpay_status, 0) = #{newebpayStatus} </if>
+            <if test="quickFilter != null and quickFilter == 'needApply'">
+                AND IFNULL(n.newebpay_status, 0) = 0
+            </if>
+            <if test="quickFilter != null and quickFilter == 'notEnabled'">
+                AND IFNULL(n.newebpay_status, 0) IN (0, 1)
+            </if>
+        </where>
+        ORDER BY s.id DESC
+    </select>
+
+    <!-- 门店蓝新详情 -->
+    <select id="selectNewebpayStoreDetail" parameterType="Long"
+            resultType="com.ruoyi.system.domain.vo.PosStoreNewebpayVo">
+        SELECT
+            s.id              AS storeId,
+            s.pos_name        AS posName,
+            s.user_id         AS userId,
+            u.user_name       AS userName,
+            s.is_stall        AS isStall,
+            s.is_night_market AS isNightMarket,
+            s.night_market_id AS nightMarketId,
+            IFNULL(n.newebpay_status, 0) AS newebpayStatus,
+            IFNULL(n.is_enabled, 1)      AS isEnabled,
+            CASE WHEN n.merchant_id IS NULL OR n.merchant_id = '' THEN 0 ELSE 1 END AS hasMerchantId,
+            n.merchant_id      AS merchantId,
+            n.hash_key         AS hashKey,
+            n.hash_iv          AS hashIv,
+            n.enabled_payments AS enabledPayments,
+            n.apply_time       AS applyTime,
+            n.approved_time    AS approvedTime,
+            n.last_verify_result AS lastVerifyResult,
+            n.remark           AS remark
+        FROM pos_store s
+        LEFT JOIN pos_store_newebpay n ON n.store_id = s.id
+        LEFT JOIN info_user u ON u.user_id = s.user_id
+        WHERE s.id = #{storeId}
+    </select>
+
+</mapper>

ruoyi-system/src/main/resources/mapper/infouser/InfoUserMapper.xml

@@ -41,6 +41,8 @@ PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
         <result property="longitude"    column="longitude"    />
         <result property="latitude"    column="latitude"    />
         <result property="juli"    column="juli"    />
+        <result property="imApiKey"    column="im_api_key"    />
+        <result property="imUserId"    column="im_user_id"    />
     </resultMap>
 
     <sql id="selectInfoUserVo">

specs/010-order-invoice/plan.md

@@ -105,3 +105,19 @@ src/lang/{zh,tw,en,vi}.js                    # 四语言加 key
 | Violation | Why Needed | Simpler Alternative Rejected Because |
 |-----------|------------|-------------------------------------|
 | — | — | — |
+
+## Enhancement: 发票凭证补全与平台后台展示 (2026-06-22)
+
+**背景**：开票成功后 `invoice_url` 实际存的是 ezPay `InvoiceTransNo`（交易流水号），字段名误导（被当成查看链接）；且 research.md D9 原计划落库的 `BarCode`/`QRcodeL`/`QRcodeR`（发票码图凭证）代码漏存，平台后台详情看不到发票凭证。领域概念澄清见 memory `reference-tw-einvoice-concepts`。
+
+**设计决策**（经多轮确认）：
+1. **字段改名**：`invoice_url` → `invoice_trans_no`（语义=ezPay 交易流水号），新增 `invoice_bar_code`/`invoice_qrcode_l`/`invoice_qrcode_r` 三列存发票码值字符串。
+2. **开票落库**：`PrintFlag=Y`（B2B / B2C无载具 / B2C邮箱）时 ezPay issue 回应含 `BarCode`/`QRcodeL`/`QRcodeR`，开票成功一并落库；`PrintFlag=N`（载具发票）这 3 字段为空（合规——载具发票法定不能索取纸本）。
+3. **search 对外接口不做**：码值开票时已落库，平台后台直接读库；载具发票核对走文案提示（凭发票号+随机码在 ezPay/财政部平台核对）。
+4. **平台后台展示**（`foodie-admin-vue/views/mendian/orderInvoice/index.vue` 详情弹窗）：
+   - 有码值：前端库（qrcode + jsbarcode）渲染左右二维码 + 条码，加「下载 PNG / 打印」按钮（html2canvas / window.print）
+   - 载具发票（码值为空）：展示结构化信息 + 「已存入买受人载具，无纸本凭证」提示
+5. **合规红线不动**：不改 PrintFlag 规则、载具与纸本互斥、防一票两份；仅补落库字段与展示。
+
+**业务事实约束**：ezPay 不返回查看 URL 也不返回图片，只给码值字符串；`BarCode`/`QRcodeL`/`QRcodeR` 仅 `PrintFlag=Y` 返回（手册 EZP_INVI 第828-850行）。
+

specs/010-order-invoice/tasks.md

@@ -151,6 +151,22 @@ description: "Task list for 订单 ezPay 电子发票开立"
 
 ---
 
+## Phase 9: Enhancement - 发票凭证补全与平台后台展示 (2026-06-22)
+
+**Goal**: 修正 invoice_url 字段语义、补落库发票码值凭证、平台后台详情可看/下载发票
+
+**Independent Test**: 开一张 B2C 邮箱发票 → 详情弹窗显示二维码/条码图 + 可下载 PNG；开一张载具发票 → 详情显示「已存入载具」无码图
+
+- [x] T026 [Enh] SQL：在 `updatesql/sql.md` 追加 2026-06-22 段——① `ALTER TABLE pos_order_invoice CHANGE invoice_url invoice_trans_no VARCHAR(20)` 改名；② `ADD COLUMN invoice_bar_code VARCHAR(255)`/`invoice_qrcode_l VARCHAR(255)`/`invoice_qrcode_r VARCHAR(255)`（码值字符串，均可空，仅 PrintFlag=Y 有值）
+- [x] T027 [Enh] 实体 `PosOrderInvoice.java`：`invoiceUrl` → `invoiceTransNo`（改字段名 + 注释「ezPay 交易流水号 InvoiceTransNo」），新增 `invoiceBarCode`/`invoiceQrcodeL`/`invoiceQrcodeR`（注释「发票码值，PrintFlag=Y 才有」）
+- [x] T028 [Enh] VO `PosOrderInvoiceVo.java`：同步加 `invoiceTransNo`/`invoiceBarCode`/`invoiceQrcodeL`/`invoiceQrcodeR` 字段
+- [x] T029 [Enh] Mapper XML `PosOrderInvoiceMapper.xml`：`selectInvoiceDetail` 改 `invoice_trans_no AS invoiceTransNo` + 加 3 码值字段；`selectInvoiceList` 不带码值（列表无需）
+- [x] T030 [Enh] `OrderInvoiceService.java`：开票成功落库时从 ezPay issue 回应取 `BarCode`/`QRcodeL`/`QRcodeR` 存入（applyInvoice + reIssueAndSave 两处；PrintFlag=N 时为空）；`setInvoiceUrl`→`setInvoiceTransNo`
+- [x] T031 [Enh] 平台后台前端 `orderInvoice/index.vue` 详情弹窗：① 有码值时用 qrcode + jsbarcode 渲染左右二维码 + 条码，加「下载 PNG / 打印」按钮（html2canvas / window.print）；② 载具发票（码值空）显示「已存入买受人载具，无纸本凭证」；③ npm 引入 qrcode/jsbarcode/html2canvas 依赖（package.json）
+- [x] T032 [P] [Enh] 平台后台 i18n：`orderInvoice:{}` 下补 key（交易流水号/发票凭证/下载发票/打印/已存入载具提示），四语言一致
+
+---
+
 ## Dependencies & Execution Order
 
 ### Phase Dependencies

specs/011-newebpay-payment/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: 蓝新金流(NewebPay)线上支付接入
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-06-22
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs) — 注：加解密算法(AES-256-CBC/SHA256)、蓝新字段名(TradeInfo/TradeSha/TradeNo)、端点域名为蓝新**不可更改的对外契约**，属业务约束而非实现选型，必须写入 spec 以便验收；未泄漏本项目内部技术选型。
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain — 关键决策（支付方式范围、凭证层级、功能范围）已在 specify 前与用户澄清并固化。
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded — 第一期明确不含退款/取消授权/定期定额。
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- 所有校验项通过，spec 已就绪，可进入 `/speckit-clarify`（如需进一步澄清）或直接 `/speckit-plan`。
+- 用户已确认：不新建分支（跳过 `before_specify` 建分支 hook），在当前 test 分支开发。
+- 待办（留给 plan 阶段细化）：payType 蓝新取值枚举、PosOrderPayment 表结构、NotifyURL/ReturnURL 路由、NewebPay 加密工具类设计、前端支付方式 i18n key。

specs/011-newebpay-payment/contracts/api.md

@@ -0,0 +1,155 @@
+# API Contracts: 蓝新金流(NewebPay)线上支付接入
+
+**Feature**: specs/011-newebpay-payment/spec.md
+**Date**: 2026-06-22
+
+本文定义本期对外与内部接口契约。Controller 位于 `ruoyi-admin`；Service/Domain 位于 `ruoyi-system`；加密工具位于 `ruoyi-admin/.../app/utils/newebpay/`。
+
+---
+
+## A. 对外接口（蓝新服务器调用，必须匿名）
+
+### A1. NotifyURL — 支付结果背景通知
+
+蓝新在交易完成/失败后以 Form Post 通知本接口。本接口解密验签并更新订单。
+
+- **路径**: `POST /pay/newebpay/notify`
+- **鉴权**: `@Anonymous`（蓝新无登录态，经 PermitAllUrlProperties 放行）
+- **Content-Type**: `application/x-www-form-urlencoded`
+- **请求参数**（蓝新 Form Post）:
+
+| 参数 | 说明 |
+|------|------|
+| MerchantID | 商店代号 |
+| Status | SUCCESS 或错误代码 |
+| Version | 串接版本 |
+| TradeInfo | AES-256-CBC 加密的交易结果（hex） |
+| TradeSha | SHA256 检查码（大写 hex） |
+| EncryptType | 加密模式（若发起时设 0/不传，可能不回传） |
+
+- **处理流程**:
+  1. 记录原始回调到 IPN 日志（复用 `IpnLog`）。
+  2. 用 MerchantID 查 `pos_store_newebpay` 取该门店 HashKey/HashIV；无凭证 → 记录并返回。
+  3. **验签**: `SHA256("HashKey={key}&{TradeInfo}&HashIV={iv}")` 大写 == TradeSha；不符 → 拒绝、记录。
+  4. **解密**: AES-256-CBC(PKCS7) 解 TradeInfo → 得 Status/Message/MerchantOrderNo/TradeNo/Amt/PaymentType/PayTime/Auth 等。
+  5. **幂等**: 按 TradeNo 查 `pos_order_payment`；已存在且 pay_status=1 → 直接返回成功应答，不重复处理。
+  6. **金额校验**: 解密所得 Amt == 订单 amount；不符 → 拒绝更新、记录告警。
+  7. **订单关联**: 由 MerchantOrderNo（"NB"+ddId）反查 pos_order；订单不存在 → 记录待查、返回。
+  8. **状态更新**（仅 Status=SUCCESS 且以上校验通过）:
+     - `pos_order_payment` 写入/更新 trade_no、pay_type、auth_code、pay_time、pay_status=1、callback_raw。
+     - `pos_order.payStatus = 1`，`pos_order.state` 保持不变（沿用 payipn 语义）。
+     - `orderLogHelper.logSync(...)` 记订单日志。
+     - 触发推送（用户/商家/骑手，复用 pushEventService / sendAcceptRiderPush 链路）。
+  9. **失败回调**（Status≠SUCCESS）: 记录失败原因到 pos_order_payment(pay_status=2)，订单保持未支付。
+- **响应**: 返回 JSON `{"Status":"SUCCESS","Message":"OK"}`（HTTP 200）；蓝新收到非成功应答会重试。
+
+---
+
+### A2. ReturnURL — 支付完成返回页（前端引导）
+
+蓝新在用户付款后将浏览器 Form Post 回本接口（携带与 NotifyURL 相同的加密参数）。
+
+- **路径**: `GET/POST /pay/newebpay/return`
+- **鉴权**: `@Anonymous`
+- **行为**: 仅作引导——重定向到前端支付结果页（带订单号）；**不**据此修改订单状态（订单状态以 NotifyURL 为准，见 spec FR-015）。
+- **响应**: 302 重定向至前端结果页 URL（含 ddId 与轻量结果提示）。
+
+---
+
+## B. 内部接口（前端/管理端调用）
+
+### B1. 发起蓝新支付（C 端用户下单后调用）
+
+- **路径**: `POST /pay/newebpay/create`
+- **鉴权**: `@Anonymous` + `@Auth`（C 端用户 token，参照 /pay/VNPay）
+- **请求参数**:
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| orderid | String | V | 系统订单号 ddId |
+
+- **处理**:
+  1. 按 ddId 查 pos_order；校验订单存在、未支付、属于当前用户。
+  2. 按订单 md_id 查 `pos_store_newebpay`；校验已开通(status=2)且启用(is_enabled=1)，否则报错「该门店暂不支持在线支付」。
+  3. 生成 merchant_order_no = "NB" + ddId（重新发起时追加时间戳避免重复）。
+  4. 组装 TradeInfo 明文: MerchantID、RespondType=JSON、TimeStamp、Version=2.3、MerchantOrderNo、Amt=amount、ItemDesc、NotifyURL、ReturnURL、CREDIT/LINEPAY/APPLEPAY（按门店 enabled_payments 开关）。
+  5. AES-256-CBC(PKCS7) 加密 → TradeInfo(hex)；SHA256 → TradeSha。
+  6. 落 `pos_order_payment`（merchant_order_no、store_id、merchant_id、amount、pay_status=0、create_time）。
+  7. 更新 `pos_order.payType="6"`、`pos_order.payUrl=gatewayUrl`。
+- **响应** `AjaxResult.success`:
+
+```json
+{
+  "code": 200,
+  "msg": "...",
+  "data": {
+    "gatewayUrl": "https://ccore.newebpay.com/MPG/mpg_gateway",
+    "MerchantID": "MS12345678",
+    "TradeInfo": "<hex>",
+    "TradeSha": "<UPPER hex>",
+    "Version": "2.3",
+    "EncryptType": "0"
+  }
+}
+```
+
+前端用隐藏 form 自动 submit 到 gatewayUrl，字段名对应 data 内 key。
+
+---
+
+### B2. 单笔交易查询（商家/运营，回调补单与对账）
+
+- **路径**: `POST /pay/newebpay/query`
+- **鉴权**: `@Auth`（商家/运营 token）
+- **请求参数**: `orderid`（ddId）
+- **处理**:
+  1. 查 pos_order 与其门店 pos_store_newebpay 凭证。
+  2. 组装 CheckValue = `SHA256("IV={iv}&Amt=&MerchantID=&MerchantOrderNo= 排序&Key={key}")`。
+  3. 调蓝新 `POST https://(c)core.newebpay.com/API/QueryTradeInfo`（MerchantID/Version=1.3/RespondType=JSON/CheckValue/TimeStamp/MerchantOrderNo/Amt）。
+  4. 解析 TradeStatus（0未付/1成功/2失败/3取消/6退款）、PaymentType、PayTime、CheckCode。
+  5. **补单**: 若蓝新返回 TradeStatus=1 且订单 payStatus 仍=0（回调丢失），则更新 pos_order.pay_status=1、写 pos_order_payment、触发推送（同 A1 步骤 8）。
+- **响应**: `AjaxResult.success` 含 TradeStatus、PaymentType、PayTime、订单当前 payStatus。
+
+---
+
+## C. 门店蓝新凭证管理（平台后台）
+
+复用 009 `PosStoreEzpayController` 模式，路径 `/system/storeNewebpay`，`@PreAuthorize("@ss.hasPermi('chanting:storeNewebpay:xxx')")`。Service 纯 DB，联网验证在 Controller 层。
+
+| 方法 | 路径 | 权限后缀 | 说明 |
+|------|------|----------|------|
+| GET | `/system/storeNewebpay/list` | `:list` | 开通管理列表（分页+筛选） |
+| GET | `/system/storeNewebpay/{storeId}` | `:query` | 门店蓝新详情 |
+| PUT | `/system/storeNewebpay/apply/{storeId}` | `:apply` | 发起申请 0→1 |
+| PUT | `/system/storeNewebpay/saveCredentials` | `:saveCredentials` | 录入凭证+验证（调 QueryTradeInfo 探测）→2 |
+| PUT | `/system/storeNewebpay/toggleEnable/{storeId}` | `:toggleEnable` | 停用/恢复 |
+| PUT | `/system/storeNewebpay/reset/{storeId}` | `:query` | 重置状态（凭证作废） |
+| PUT | `/system/storeNewebpay/enabledPayments/{storeId}` | `:toggleEnable` | 设置启用的支付方式 CREDIT/LINEPAY/APPLEPAY |
+
+**saveCredentials 请求体** `StoreNewebpayCredentialDto`:
+```json
+{ "storeId": 1, "merchantId": "MS...", "hashKey": "...", "hashIv": "...", "enabledPayments": "CREDIT,LINEPAY,APPLEPAY" }
+```
+验证：Controller 调 NewebPay QueryTradeInfo（查虚构订单）；返回金钥/商店错误 → 视为无效（拒绝、状态不变）；否则通过置 status=2、is_enabled=1。
+
+---
+
+## D. NewebPay 工具类（内部，非 HTTP 接口）
+
+位于 `ruoyi-admin/.../app/utils/newebpay/`，仿 ezPay 结构：
+
+- `NewebPayEncryptUtil`: `encrypt(query,key,iv)`→hex(AES-256-CBC/PKCS7)、`decrypt(hex,key,iv)`→明文、`genTradeSha(tradeInfoHex,key,iv)`→大写、`genCheckValue(amt,mid,orderNo,key,iv)`→大写、`genCheckCode(fields,key,iv)`→大写。含 main 自测（用 NDNF §4.1 示例 Key=Fs5cX1TGqYM2PpdbE14a9H83YQSQF5jn/IV=C6AcmfqJILwgnhIP/MID=MS127874575 验证加解密 round-trip 与 TradeSha 规则）。
+- `NewebPay`: 端点常量（`URL_MPG_GATEWAY`、`URL_QUERY_TRADE_INFO`）、`createMpgForm(baseUrl,cfg,params)` 返回加密后的 form 字段、`queryTrade(baseUrl,cfg,amt,orderNo)` 调查询。
+- `NewebPayConfig`: merchantId/hashKey/hashIV（运行时由 Service 从 pos_store_newebpay 构造）。
+
+---
+
+## 配置（application.yml，新增）
+
+```yaml
+newebpay:
+  base-url: https://ccore.newebpay.com   # 测试 ccore / 正式 core
+  notify-url: https://<公网域名>/pay/newebpay/notify
+  return-url: https://<公网域名>/pay/newebpay/return
+  mpg-version: "2.3"
+```

specs/011-newebpay-payment/data-model.md

@@ -0,0 +1,148 @@
+# Data Model: 蓝新金流(NewebPay)线上支付接入
+
+**Feature**: specs/011-newebpay-payment/spec.md
+**Date**: 2026-06-22
+
+本文定义新增实体、现有实体扩展与建表 DDL（DDL 同步写入 `updatesql/sql.md`，不直接执行）。
+
+---
+
+## 新增实体
+
+### 1. PosStoreNewebpay（门店蓝新支付凭证）— `pos_store_newebpay`
+
+与 `pos_store` 一对一。记录门店的蓝新申请状态、启用开关、凭证、启用的支付方式。复用 009 `pos_store_ezpay` 的状态机与审计字段约定。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | BIGINT PK AUTO | 主键 |
+| store_id | BIGINT UK | 关联 pos_store.id（门店），唯一 |
+| newebpay_status | INT | 申请状态: 0未申请/1申请中/2已开通 |
+| is_enabled | INT | 启用开关: 0停用/1启用（仅 status=2 有意义） |
+| merchant_id | VARCHAR(15) | 蓝新商店代号 MerchantID |
+| hash_key | VARCHAR(64) | 蓝新 HashKey（32 字节） |
+| hash_iv | VARCHAR(32) | 蓝新 HashIV（16 字节） |
+| enabled_payments | VARCHAR(50) | 启用的支付方式，逗号分隔：CREDIT,LINEPAY,APPLEPAY |
+| apply_time | DATETIME | 提交申请时间（0→1） |
+| approved_time | DATETIME | 开通时间（→2） |
+| last_verify_result | VARCHAR(240) | 最近一次凭证验证结果 |
+| remark | VARCHAR(255) | 备注 |
+| create_time | DATETIME | 创建时间 |
+| update_time | DATETIME | 更新时间 |
+| create_by | VARCHAR(64) | 创建人 |
+| update_by | VARCHAR(64) | 更新人 |
+
+**状态机**: `0 未申请 --apply--> 1 申请中 --saveCredentials(验证通过)--> 2 已开通 <--reset--> 1 申请中`；`2 已开通` 下 `toggleEnable` 切换 is_enabled。门店无此行即视为未申请。
+
+**Java 实体**: `ruoyi-system/.../domain/PosStoreNewebpay.java`，MyBatis-Plus 注解（`@TableName("pos_store_newebpay")`、`@TableId(AUTO)`、`@TableField(fill=...)`），与 PosStoreEzpay 一致风格。
+
+---
+
+### 2. PosOrderPayment（支付交易流水）— `pos_order_payment`
+
+每笔蓝新交易一条。承载幂等（按 trade_no）与对账明细。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | BIGINT PK AUTO | 主键 |
+| dd_id | VARCHAR(64) | 系统订单号（关联 pos_order.dd_id），索引 |
+| merchant_order_no | VARCHAR(30) | 商店订单号 MerchantOrderNo（发起生成），索引 |
+| trade_no | VARCHAR(20) | 蓝新交易序号 TradeNo（回调获得），唯一索引（幂等键） |
+| store_id | BIGINT | 门店ID |
+| merchant_id | VARCHAR(15) | 蓝新商店代号（发起时的门店凭证） |
+| pay_type | VARCHAR(20) | 支付方式: CREDIT/LINEPAY/APPLEPAY（回调确定） |
+| amount | INT | 交易金额（整数元，= 订单 amount） |
+| pay_status | INT | 支付状态: 0未支付/1已支付/2失败（对齐 payStatus 语义） |
+| auth_code | VARCHAR(20) | 授权码（信用卡回调 Auth） |
+| pay_time | DATETIME | 支付完成时间（回调 PayTime） |
+| callback_raw | TEXT | 回调原始解密结果（调试/对账） |
+| create_time | DATETIME | 创建时间（发起时间） |
+| update_time | DATETIME | 更新时间 |
+
+**幂等规则**: 回调按 `trade_no` 查重——已存在且 pay_status=1 则跳过更新（仍返回成功应答）；不存在则新增/更新。
+**唯一性**: `trade_no` 建唯一索引（UNIQUE），允许空值（发起时尚无 trade_no）；同一订单多次发起产生多行（不同 merchant_order_no），但同一 trade_no 只对应一行。
+
+**Java 实体**: `ruoyi-system/.../domain/PosOrderPayment.java`，MyBatis-Plus 注解。
+
+---
+
+## 现有实体扩展
+
+### 3. PosOrder（订单）— `pos_order`（不改表结构）
+
+复用现有字段，扩展取值语义：
+
+| 字段 | 现状 | 本期用法 |
+|------|------|----------|
+| dd_id | 订单号 | 派生 MerchantOrderNo = "NB" + dd_id |
+| amount | 订单合计金额(Integer 元) | 蓝新支付金额（含运费，与发票 amount−freight 不同） |
+| pay_type | 支付方式(1-5越南旧值) | 新增取值 `"6"` = 蓝新在线支付（发起时写入） |
+| pay_status | 0未支付/1已支付/2已退款 | 回调成功置 1（沿用） |
+| pay_url | 支付地址 | 存蓝新 gatewayUrl（兜底/记录） |
+| md_id | 门店ID | 决定用哪个门店的蓝新凭证发起交易 |
+
+**不改表结构**，无 DDL。payType 取值扩展在代码层（常量/枚举）体现。
+
+---
+
+## DDL（写入 updatesql/sql.md，不直接执行）
+
+```sql
+-- 2026-06-22 蓝新金流支付接入 - 门店蓝新凭证表
+CREATE TABLE pos_store_newebpay (
+  id BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',
+  store_id BIGINT NOT NULL COMMENT '关联 pos_store.id(门店)',
+  newebpay_status INT NOT NULL DEFAULT 0 COMMENT '申请状态:0未申请/1申请中/2已开通',
+  is_enabled INT NOT NULL DEFAULT 1 COMMENT '启用开关:0停用/1启用',
+  merchant_id VARCHAR(15) DEFAULT NULL COMMENT '蓝新商店代号 MerchantID',
+  hash_key VARCHAR(64) DEFAULT NULL COMMENT '蓝新 HashKey(32字节)',
+  hash_iv VARCHAR(32) DEFAULT NULL COMMENT '蓝新 HashIV(16字节)',
+  enabled_payments VARCHAR(50) DEFAULT 'CREDIT' COMMENT '启用支付方式:CREDIT,LINEPAY,APPLEPAY',
+  apply_time DATETIME DEFAULT NULL COMMENT '申请时间',
+  approved_time DATETIME DEFAULT NULL COMMENT '开通时间',
+  last_verify_result VARCHAR(240) DEFAULT NULL COMMENT '最近验证结果',
+  remark VARCHAR(255) DEFAULT NULL COMMENT '备注',
+  create_time DATETIME DEFAULT NULL COMMENT '创建时间',
+  update_time DATETIME DEFAULT NULL COMMENT '更新时间',
+  create_by VARCHAR(64) DEFAULT NULL COMMENT '创建人',
+  update_by VARCHAR(64) DEFAULT NULL COMMENT '更新人',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_store_id (store_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='门店蓝新金流支付凭证';
+
+-- 2026-06-22 蓝新金流支付接入 - 支付交易流水表
+CREATE TABLE pos_order_payment (
+  id BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',
+  dd_id VARCHAR(64) NOT NULL COMMENT '系统订单号(关联 pos_order.dd_id)',
+  merchant_order_no VARCHAR(30) NOT NULL COMMENT '商店订单号 MerchantOrderNo',
+  trade_no VARCHAR(20) DEFAULT NULL COMMENT '蓝新交易序号 TradeNo(幂等键)',
+  store_id BIGINT DEFAULT NULL COMMENT '门店ID',
+  merchant_id VARCHAR(15) DEFAULT NULL COMMENT '蓝新商店代号',
+  pay_type VARCHAR(20) DEFAULT NULL COMMENT '支付方式:CREDIT/LINEPAY/APPLEPAY',
+  amount INT DEFAULT NULL COMMENT '交易金额(整数元)',
+  pay_status INT NOT NULL DEFAULT 0 COMMENT '支付状态:0未支付/1已支付/2失败',
+  auth_code VARCHAR(20) DEFAULT NULL COMMENT '授权码',
+  pay_time DATETIME DEFAULT NULL COMMENT '支付完成时间',
+  callback_raw TEXT COMMENT '回调原始解密结果',
+  create_time DATETIME DEFAULT NULL COMMENT '创建时间',
+  update_time DATETIME DEFAULT NULL COMMENT '更新时间',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_trade_no (trade_no),
+  KEY idx_dd_id (dd_id),
+  KEY idx_merchant_order_no (merchant_order_no)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='蓝新支付交易流水';
+```
+
+注：`uk_trade_no` 唯一索引在 MySQL 下允许多个 NULL（发起时 trade_no 为空），回调写入时保证唯一。
+
+---
+
+## 实体关系
+
+```
+pos_store 1 ──── 1 pos_store_newebpay   (门店蓝新凭证)
+pos_store 1 ──── ∞ pos_order             (门店订单)
+pos_order 1 ──── ∞ pos_order_payment     (一订单多次发起支付,每发起一行)
+                                   ↑
+                        trade_no 唯一(回调幂等)
+```

specs/011-newebpay-payment/plan.md

@@ -0,0 +1,107 @@
+# Implementation Plan: 蓝新金流(NewebPay)线上支付接入
+
+**Branch**: `test`（不新建分支，在当前 test 分支开发） | **Date**: 2026-06-22 | **Spec**: [spec.md](spec.md)
+
+**Input**: Feature specification from `/specs/011-newebpay-payment/spec.md`
+
+## Summary
+
+为系统接入台湾蓝新金流(NewebPay) MPG 幕前线上支付。C 端用户下单后由后端按门店凭证生成 AES-256-CBC + SHA256 加密的 MPG 交易参数，前端 Form Post 跳转蓝新付款页完成**信用卡 / LINE Pay / Apple Pay** 支付；蓝新经 NotifyURL 背景回调通知结果，系统解密验签、幂等、金额校验后更新订单支付状态并复用现有推送/记账链路；另支持单笔查询用于对账与回调丢失补单。
+
+凭证按门店存储（新建 `pos_store_newebpay`，复用 009 开通管理模式），交易流水独立成表 `pos_order_payment`（按蓝新交易序号幂等）。加密工具新建 `NewebPayEncryptUtil`（标准 PKCS7 块16，区别于 ezPay 的块32），HTTP 客户端 `NewebPay`。详见 [research.md](research.md)、[data-model.md](data-model.md)、[contracts/api.md](contracts/api.md)、[quickstart.md](quickstart.md)。
+
+## Technical Context
+
+**Language/Version**: Java 17（Spring Boot 3，证据：`jakarta.*` 包、`@EnableMethodSecurity`）
+
+**Primary Dependencies**: Spring Boot 3、Spring Security（`@PreAuthorize`/`@Anonymous`/PermitAllUrlProperties）、MyBatis-Plus（`@TableName`/`@TableId`/LambdaQueryWrapper）、MySQL、fastjson2、Hutool、Apache HttpClient（ezPay 已用）、RuoYi 脚手架（BaseController/AjaxResult/TableDataInfo/MessageUtils）。
+
+**Storage**: MySQL（新增 `pos_store_newebpay`、`pos_order_payment` 两表；`pos_order` 不改结构，payType 取值扩展）。
+
+**Testing**: `NewebPayEncryptUtil.main` 加解密/签名自测（用 NDNF §4.1 官方示例数据）+ 蓝新测试环境 ccore 端到端验证（见 [quickstart.md](quickstart.md)，测试卡号见 NDNF 附录1）。
+
+**Target Platform**: Linux server（Tomcat 8082，公网可达 80/443 供蓝新回调）。
+
+**Project Type**: web-service（Spring Boot REST，多模块 Maven：ruoyi-admin / ruoyi-system / ruoyi-framework / ruoyi-common）。
+
+**Performance Goals**: 99% 支付回调在蓝新发出后 10s 内处理（SC-004）；发起支付接口 p95 < 1s。
+
+**Constraints**: NotifyURL/ReturnURL 必须公网 80/443 可达；回调必须幂等（按 TradeNo）；必须验签 + 金额校验，异常回调误更新率 0%（SC-003）；HashKey/HashIV 不得下发前端（加密仅在后端）。
+
+**Scale/Scope**: 全平台门店可开通；面向 C 端用户下单（外卖/自取/堂食扫码点餐）；商家端/平台后台用于凭证管理与对账查询。
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+**N/A** — `.specify/memory/constitution.md` 仍为模板占位（`[PRINCIPLE_1_NAME]` 等），未填写项目具体准则，无实质 gate 可校验。无违反项。
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/011-newebpay-payment/
+├── spec.md              # 需求规格 (/speckit-specify)
+├── plan.md              # 本文件 (/speckit-plan)
+├── research.md          # 技术决策 (/speckit-plan Phase 0)
+├── data-model.md        # 数据模型 (/speckit-plan Phase 1)
+├── quickstart.md        # 端到端验证指南 (/speckit-plan Phase 1)
+├── contracts/
+│   └── api.md           # 接口契约 (/speckit-plan Phase 1)
+└── tasks.md             # 任务分解 (/speckit-tasks，下一步生成)
+```
+
+### Source Code (repository root)
+
+```text
+ruoyi-admin/src/main/java/com/ruoyi/app/
+├── utils/newebpay/
+│   ├── NewebPay.java               # 蓝新 HTTP 客户端（MPG/Query），仿 EzPay
+│   ├── NewebPayConfig.java         # merchantId/hashKey/hashIV，仿 EzPayConfig
+│   └── NewebPayEncryptUtil.java    # AES-256-CBC/PKCS7 + SHA256(TradeSha/CheckValue/CheckCode)
+├── pay/
+│   └── NewebpayPayController.java  # /pay/newebpay/{create,notify,return,query}（notify/return @Anonymous）
+└── mendian/
+    └── PosStoreNewebpayController.java  # /system/storeNewebpay/* 门店凭证管理（@PreAuthorize）
+
+ruoyi-system/src/main/java/com/ruoyi/system/
+├── domain/
+│   ├── PosStoreNewebpay.java       # 门店蓝新凭证实体（@TableName pos_store_newebpay）
+│   ├── PosOrderPayment.java        # 支付流水实体（@TableName pos_order_payment）
+│   ├── vo/PosStoreNewebpayVo.java  # 凭证列表/详情 VO
+│   └── dto/StoreNewebpayCredentialDto.java  # 录入凭证 DTO
+├── mapper/
+│   ├── PosStoreNewebpayMapper.java + PosOrderPaymentMapper.java
+├── service/
+│   ├── IPosStoreNewebpayService + Impl   # 纯 DB（状态机/CRUD），仿 PosStoreEzpayServiceImpl
+│   └── IPosOrderPaymentService + Impl    # 流水写入/幂等查询
+
+ruoyi-system/src/main/resources/mapper/chanting/
+├── PosStoreNewebpayMapper.xml      # 仿 PosStoreEzpayMapper.xml
+└── PosOrderPaymentMapper.xml
+
+ruoyi-admin/src/main/resources/
+└── application.yml                 # 新增 newebpay 段（base-url/notify-url/return-url/mpg-version）
+
+updatesql/
+└── sql.md                          # 追加两段建表 DDL（pos_store_newebpay、pos_order_payment）
+
+前端（CRLF 文件，用 Python 脚本编辑，按项目规范）：
+E:\QtwCode\foodie\foodie-store\         # C 端发起支付入口、支付结果页、四语 i18n
+E:\QtwCode\foodie\foodie-admin-vue\     # 平台后台门店蓝新凭证管理页 + 四语 i18n
+```
+
+**Structure Decision**: 严格遵循现有分层——加密/HTTP 客户端/Controller 在 `ruoyi-admin`，Domain/Mapper/Service 在 `ruoyi-system`（Service 纯 DB，联网验证在 Controller 层以避免反向依赖）。蓝新支付链路与发票（009/010）并列共存、互不干扰，复用 ezPay 的工具类组织形式与 PosStoreEzpay 的开通管理模式，但不共享表/凭证。
+
+## Complexity Tracking
+
+> 无 Constitution Check 违反项，本表无需填写。
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| — | — | — |
+
+## Phase 1 设计后 Constitution 复核
+
+设计完成（research/data-model/contracts/quickstart 已产出）。`constitution.md` 仍为占位，无 gate 可复核；设计未引入与项目既有模式冲突的结构（全部对齐 ezPay/PosStoreEzpay/PayController.payipn 既有范式）。**通过**。

specs/011-newebpay-payment/quickstart.md

@@ -0,0 +1,94 @@
+# Quickstart: 蓝新金流(NewebPay)线上支付接入
+
+**Feature**: specs/011-newebpay-payment/spec.md
+**Date**: 2026-06-22
+
+端到端验证指南。实现完成后按此验证「下单 → 付款 → 订单已支付」主链路与回调安全。
+
+---
+
+## 前置条件
+
+1. **数据库**: 已执行 `updatesql/sql.md` 中本期两段 DDL（`pos_store_newebpay`、`pos_order_payment`）。
+2. **配置**: `ruoyi-admin/src/main/resources/application.yml` 已加 `newebpay` 段：
+   - `base-url`: 测试环境用 `https://ccore.newebpay.com`
+   - `notify-url` / `return-url`: 本机开发需用内网穿透（ngrok/frp）映射到本地 8082 端口的公网域名，如 `https://xxx.ngrok-free.app/pay/newebpay/notify`。
+3. **蓝新测试商店**: 在蓝新测试区（ccore）申请测试商店，取得 `MerchantID` / `HashKey` / `HashIV`。
+4. **测试卡**: 蓝新测试区信用卡测试卡号（NDNF 附录1），如 `4000-2211-1111-1111`（成功卡）、有效日期/安全码按附录。
+
+---
+
+## 场景 1：门店开通蓝新凭证
+
+1. 平台后台进「门店蓝新支付开通」列表 → 选门店 → 发起申请（状态→申请中）。
+2. 录入测试 `MerchantID/HashKey/HashIV` + 勾选启用支付方式（CREDIT/LINEPAY/APPLEPAY）→ 保存。
+3. **预期**: 系统调 QueryTradeInfo 探测，凭证有效 → 状态「已开通」、`last_verify_result=PASS`；无效 → 提示「凭证无效」、状态不变。
+4. **验证**: `SELECT newebpay_status,is_enabled,enabled_payments FROM pos_store_newebpay WHERE store_id=?` → status=2, is_enabled=1。
+
+---
+
+## 场景 2：信用卡支付主链路（核心 P1）
+
+1. C 端用户对「已开通蓝新」的门店下一笔订单（任意类型）。
+2. 调发起支付: `POST /pay/newebpay/create?orderid={ddId}`（带用户 token）。
+   - **预期 200**: 返回 `data.gatewayUrl/MerchantID/TradeInfo/TradeSha/Version/EncryptType`。
+   - **DB**: `pos_order_payment` 新增一行（merchant_order_no=NB+ddId, pay_status=0）；`pos_order.pay_type=6`、`pay_url=gatewayUrl`。
+3. 前端用返回字段构建隐藏 form 自动 submit → 跳转蓝新 MPG 付款页。
+4. 在蓝新付款页选**信用卡**，输入测试卡号 + 有效期 + 安全码 → 送出。
+5. **预期**: 付款成功后蓝新跳回 ReturnURL（重定向到前端结果页）；蓝新同时 POST 到 NotifyURL。
+6. **NotifyURL 处理**:
+   - 解密 TradeInfo、验签 TradeSha 通过。
+   - 金额 == 订单 amount。
+   - `pos_order.pay_status` 由 0 → 1。
+   - `pos_order_payment` 写入 trade_no、pay_type=CREDIT、auth_code、pay_time、pay_status=1。
+   - 订单日志记录「系统收到支付成功回调」。
+7. **验证**: 订单列表/详情显示「已支付」，商家端/骑手收到新订单推送。
+
+---
+
+## 场景 3：回调安全（幂等 + 金额不符 + 伪造）
+
+1. **幂等**: 把场景2的成功回调报文（含 trade_no）再 POST 到 `/pay/newebpay/notify` 一次。
+   - **预期**: 订单状态不变（不重复推送、不重复记账），仍返回成功应答。
+2. **金额不符**: 构造一笔 TradeInfo 中 Amt 与订单 amount 不一致的合法签名回调。
+   - **预期**: 订单 pay_status 不变，`pos_order_payment`/日志记录「金额不一致」告警。
+3. **伪造签名**: 篡改 TradeSha 后 POST。
+   - **预期**: 验签失败，订单不变，记录告警。
+
+---
+
+## 场景 4：LINE Pay / Apple Pay（P2）
+
+1. 发起支付同场景2（门店 enabled_payments 含 LINEPAY/APPLEPAY）。
+2. 蓝新付款页选 **LINE Pay**（跳转 LINE 测试环境完成）或 **Apple Pay**（需 Apple Pay 环境/设备）。
+3. **预期**: 回调到达后订单已支付，`pos_order_payment.pay_type` 分别为 LINEPAY / APPLEPAY。
+
+> 注：Apple Pay 需 Apple Developer 配置与 HTTPS 域名验证；测试环境受限时可先验证信用卡 + LINE Pay，Apple Pay 在具备条件时补测。
+
+---
+
+## 场景 5：单笔查询补单（P3）
+
+1. 模拟回调丢失：付款成功但人为不触发 NotifyURL（订单 pay_status 仍 0）。
+2. 商家/运营调 `POST /pay/newebpay/query?orderid={ddId}`。
+3. **预期**: 系统调蓝新 QueryTradeInfo 返回 TradeStatus=1，检测到订单未支付 → 补单（pay_status→1、写流水、推送）。
+4. **验证**: 订单变为已支付。
+
+---
+
+## 场景 6：未开通/停用门店
+
+1. 对未开通蓝新（无 pos_store_newebpay 行 / status≠2）或已停用（is_enabled=0）的门店下单。
+2. 调发起支付。
+3. **预期**: 返回错误「该门店暂不支持在线支付」，不生成交易。
+
+---
+
+## 加密自测（无需联网）
+
+运行 `NewebPayEncryptUtil.main`（实现时加入），用 NDNF §4.1 官方示例数据验证：
+- AES-256-CBC/PKCS7 加解密 round-trip。
+- TradeSha 规则: `SHA256("HashKey={key}&{tradeInfoHex}&HashIV={iv}")` 大写。
+- 明文示例 `MerchantID=MS127874575&RespondType=String&TimeStamp=...&Version=2.3&...` 加密后 hex 可被蓝新测试环境接受（场景2 即端到端验证）。
+
+全部通过后方可进入场景1。

specs/011-newebpay-payment/research.md

@@ -0,0 +1,168 @@
+# Research: 蓝新金流(NewebPay)线上支付接入
+
+**Feature**: specs/011-newebpay-payment/spec.md
+**Date**: 2026-06-22
+
+本文记录实现蓝新 MPG 幕前支付所需的关键技术决策、理由与备选。所有决策已基于现有系统（ezPay 发票实现、PayController 回调链路、PosOrder 字段）与蓝新官方手册 NDNF-1.2.2。
+
+---
+
+## D1. 加密工具：新建独立 NewebPayEncryptUtil，不复用 EzPayEncryptUtil
+
+**Decision**: 新建 `ruoyi-admin/.../app/utils/newebpay/NewebPayEncryptUtil.java` + `NewebPay.java`（HTTP 客户端）+ `NewebPayConfig.java`，与 ezPay 工具类并列，不抽取公共加密套件。
+
+**Rationale**:
+- 蓝新加密是**标准 AES-256-CBC + PKCS7Padding（块 16 字节）**，输出 hex；ezPay 是 AES/CBC/NoPadding + 手动 PKCS7（**块 32 字节**，ezPay 特殊）。两者填充块大小不同，加密实现无法共用。
+- 蓝新的检查码语义：`TradeSha = SHA256("HashKey={key}&{tradeInfoHex}&HashIV={iv}")` 大写（请求时带）；`CheckCode = SHA256("HashIV={iv}&{Amt=&MerchantID=&MerchantOrderNo=&TradeNo= 排序}&HashKey={key}")` 大写（校验响应）；`CheckValue = SHA256("IV={iv}&{Amt=&MerchantID=&MerchantOrderNo= 排序}&Key={key}")` 大写（查询请求）。与 ezPay 的 CheckValue/CheckCode 形似但字段与前缀不同。
+- 第一期使用 `EncryptType=0`（默认 AES/CBC/PKCS7Padding），不上 AES/GCM，降低复杂度。
+- 不抽取公共套件遵循「简单优先」——两者细节差异大，强行抽象会引入间接层且只有两个使用点。
+
+**Alternatives**:
+- 抽取 `PaymentCryptoUtil` 公共类：被否，因填充块大小与检查码字段差异使抽象收益低、误用风险高。
+- 复用 EzPayEncryptUtil：被否，块大小不同会导致蓝新解密失败。
+
+---
+
+## D2. MPG 幕前跳转：后端生成加密参数，前端 Form Post 跳转蓝新
+
+**Decision**: 新增「发起支付」接口返回 `{ gatewayUrl, MerchantID, TradeInfo, TradeSha, Version, EncryptType }`；前端用隐藏 form 自动 `submit` 跳转至 `https://(c)core.newebpay.com/MPG/mpg_gateway`。
+
+**Rationale**:
+- MPG 是**幕前**支付，必须由用户浏览器跳转到蓝新付款页（NDNF §3.1、§4.1.3 Form Post）。后端不能直接 HTTP 调用完成付款。
+- 与现有 VNPay 的 `payUrl`（单个跳转 URL）模式不同——蓝新需 POST 多个加密字段。故不复用 `PosOrder.payUrl` 存 URL，而是接口返回 form 参数；`payUrl` 字段保留存 gatewayUrl 供前端兜底/记录。
+- 后端生成参数时机：用户下单后、点击「去支付」时调用发起接口。
+
+**Alternatives**:
+- 后端直接返回自动 submit 的 HTML 页面（蓝新 PHP 官方示例做法）：被否，前端是 Vue SPA，返回 HTML 与现有交互不一致；改为接口返回 form 字段由前端构建更贴合。
+- 前端自行加密：被否，HashKey/HashIV 是敏感凭证，不能下发前端。
+
+---
+
+## D3. 凭证存储：新建 pos_store_newebpay 表（与 pos_store 1:1），独立于发票凭证
+
+**Decision**: 新建 `pos_store_newebpay`，与 `pos_store` 一对一，结构与状态机复用 009 `pos_store_ezpay` 模式，但独立表、独立字段。
+
+**Rationale**:
+- 支付与发票是两条独立业务线，凭证、开通流程、启用开关各自独立；混表会造成字段语义混乱、停用相互影响。
+- 复用 009 的「未申请 0 / 申请中 1 / 已开通 2 + is_enabled」状态机与 Controller/Service 分层（Service 纯 DB，联网验证在 Controller 层，避免 ruoyi-system 反向依赖 ruoyi-admin 工具类）。
+- 额外字段 `enabled_payments`：记录该门店启用的支付方式组合（信用卡/LINE Pay/Apple Pay），发起 MPG 时据此设置 CREDIT/LINEPAY/APPLEPAY 开关。
+
+**Alternatives**:
+- 复用 pos_store_ezpay 加列：被否，语义混淆、发票停用会误伤支付。
+- 全局 application.yml 单组凭证：被否，用户已选定门店级。
+
+---
+
+## D4. 凭证联网验证：用单笔查询 QueryTradeInfo 探测
+
+**Decision**: 录入凭证后调蓝新 `QueryTradeInfo`（查一个不存在的订单号），根据返回判断凭证是否有效。
+
+**Rationale**:
+- 蓝新无等价的「纯凭证校验」接口。QueryTradeInfo 用 CheckValue（Amt/MerchantID/MerchantOrderNo）签名，若 HashKey/HashIV/MerchantID 错误，蓝新返回商店/金钥相关错误码（如 `MPG01001` 系列、Status≠SUCCESS 且 Message 提示金钥）；若凭证正确则返回「交易不存在」类结果（Status≠SUCCESS 但 Message 为查询无资料）。
+- 与 009 ezPay 用只读 invoice_search 验证金钥的思路一致（ezPay 靠响应含 `KEY1` 判定金钥错误）。
+- 验证逻辑放 Controller 层（同 009），Service 仅持久化结果。
+
+**Alternatives**:
+- MPG 测试环境发起真实小额交易再取消：被否，流程重、产生垃圾交易。
+- 不验证直接保存：被否，错误凭证会导致所有交易失败，需录入即校验。
+
+---
+
+## D5. 支付流水表：新建 pos_order_payment 承载幂等与对账
+
+**Decision**: 新建 `pos_order_payment`，每笔蓝新交易一条，回调按 `trade_no`（蓝新交易序号）幂等。
+
+**Rationale**:
+- `PosOrder.payStatus` 只能存最终状态，无法承载 TradeNo、支付方式、授权码、原始回调、多次发起。蓝新要求按 TradeNo 幂等（NotifyURL 可能重试），必须有专门表。
+- 字段：dd_id、merchant_order_no、trade_no（蓝新交易序号，幂等键）、store_id、merchant_id、pay_type(CREDIT/LINEPAY/APPLEPAY)、amount、pay_status、auth_code、pay_time、callback_raw、create_time、update_time。
+- 同一订单可有多条（多次发起支付，每次新 merchant_order_no），但成功回调只处理一次（按 trade_no）。
+
+**Alternatives**:
+- 用 PosOrder 字段 + Redis 幂等标记：被否，无法留存对账明细与多次发起记录。
+- 用现有 IpnLog：被否，IpnLog 是通用日志无结构化字段、无 trade_no 索引。
+
+---
+
+## D6. 商店订单号 MerchantOrderNo 生成规则
+
+**Decision**: `merchant_order_no = "NB" + ddId`（ddId 为系统订单号），保证门店内唯一、格式合法（英数+下划线）、可由 ddId 反查订单。
+
+**Rationale**:
+- 蓝新要求同 MerchantID 下 MerchantOrderNo 不重复、限英数+下划线、≤30 字元。
+- ddId 全局唯一 ⇒ 加固定前缀 "NB" 后门店内必然唯一；前缀便于识别蓝新订单、避免与其他渠道订单号冲突。
+- 实现时需确认 ddId 不含 `-`/`/` 等非法字符；若含则清洗（替换为 `_`）。
+- 重新发起支付时生成新 merchant_order_no（追加时间戳后缀），旧记录作废。
+
+**Alternatives**:
+- 直接用 ddId：可行但缺渠道标识，调试时难辨来源；加前缀更稳。
+- 独立序列号：被否，需额外维护映射，ddId 已满足唯一性。
+
+---
+
+## D7. NotifyURL 回调处理链路：复用 PayController.payipn 业务链路
+
+**Decision**: 新建 `NewebpayPayController`（`/pay/newebpay/*`），回调接口 `/pay/newebpay/notify` 加 `@Anonymous`；处理流程复用现有 `PayController.payipn` 的业务链路（IPN 日志 → 解密验签 → 金额校验 → 幂等 → 更新 payStatus → 订单日志 → 推送），仅替换加解密/字段层。
+
+**Rationale**:
+- `PayController.payipn` 已实现完整的「支付成功后业务动作」：`orderLogHelper.logSync` 记日志、`userBillingService` 记账、`push.apppush/shpush` + `pushEventService.PublisherEvent` 推送用户/商家/骑手、`sendAcceptRiderPush` 推送可接单骑手。蓝新回调成功后必须触发相同动作，否则订单虽已支付但商家/骑手收不到通知。
+- `@Anonymous` 注解经 `PermitAllUrlProperties` 自动加入 SecurityConfig 匿名白名单（蓝新服务器无登录态）。
+- 新建独立 Controller 而非塞入已 440 行的 PayController，保持单一职责、便于维护。
+- 订单状态更新语义沿用 payipn：`state` 保持不变（0 待处理，支付不改业务状态）、`payStatus=1`（已支付）。
+
+**Alternatives**:
+- 抽取公共「支付成功处理」方法供 VNPay/蓝新共用：理想但 VNPay 代码耦合度高、改造范围大，第一期不做（surgical changes）；仅复用其调用的组件（orderLogHelper/pushEventService 等）。
+- 在 PayController 加 /pay/newebpay/notify 方法：被否，Controller 已臃肿。
+
+---
+
+## D8. payType 取值与支付方式承载
+
+**Decision**: `PosOrder.payType` 发起时设固定值表示「蓝新在线支付」（取 `"6"`），具体支付方式(CREDIT/LINEPAY/APPLEPAY) 由 `pos_order_payment.pay_type` 在回调后承载；订单列表展示支付方式时联查 pos_order_payment。
+
+**Rationale**:
+- MPG 幕前：发起交易时用户**尚未选择**支付方式（在蓝新付款页才选），故发起瞬间只能知道「走蓝新」，无法预知信用卡还是 LINE Pay。
+- payType 历史取值 1-5（越南到付/vnpay/zalopay/银行卡），台湾已不用；新增 `"6"` 表示蓝新，避免语义冲突。
+- 回调到达后明确方式，写入 pos_order_payment；订单列表/详情需展示具体方式时由该表提供。
+
+**Alternatives**:
+- 回调后把 payType 更新为细分(7/8/9)：增加枚举且与「发起时未知方式」矛盾，被否。
+
+---
+
+## D9. 环境配置：application.yml 新增 newebpay 段
+
+**Decision**: 仿 `ezpay.base-url` 模式新增：
+```yaml
+newebpay:
+  base-url: https://ccore.newebpay.com   # 测试 ccore / 正式 core
+  notify-url: https://<公网域名>/pay/newebpay/notify
+  return-url: https://<公网域名>/pay/newebpay/return
+  mpg-version: "2.3"
+```
+
+**Rationale**:
+- 与 ezpay.base-url 一致的注入风格（`@Value`），便于环境切换。
+- notify-url/return-url 必须是公网可访问的 80/443（蓝新要求），配置化便于不同环境部署。
+- 第一期固定 EncryptType=0（CBC），不入配置。
+
+---
+
+## D10. 测试环境与端到端自测
+
+**Decision**: 使用蓝新测试环境 `ccore.newebpay.com` + 文档附录1测试卡号验证；本地开发用内网穿透（ngrok/frp）暴露 NotifyURL。
+
+**Rationale**:
+- 蓝新测试区提供测试商店凭证与测试卡（附录1），不产生真实扣款。
+- NotifyURL 须被蓝新服务器访问，本地 8082 端口需穿透到公网。
+- 自测链路：门店录入测试凭证 → 下单 → 发起蓝新支付 → 测试卡付款 → 回调到达 → 订单已支付 + 推送。
+
+**Alternatives**:
+- 直接用正式环境：被否，风险高、产生真实交易。
+
+---
+
+## D11. 数据库变更管理
+
+**Decision**: 所有 DDL 写入 `updatesql/sql.md`（标注日期与用途），不直接执行，由开发者统一手动执行（遵循项目规范）。
+
+涉及：`pos_store_newebpay` 建表、`pos_order_payment` 建表。（`pos_order` 无需改结构，payType 取值扩展不改表。）

specs/011-newebpay-payment/spec.md

@@ -0,0 +1,157 @@
+# Feature Specification: 蓝新金流(NewebPay)线上支付接入
+
+**Feature Branch**: 不新建分支（在当前 test 分支开发）
+
+**Created**: 2026-06-22
+
+**Status**: Draft
+
+**Input**: User description: "为系统接入线上支付。渠道：蓝新金流(NewebPay) MPG幕前支付（文档：線上交易─幕前支付技術串接手冊 NDNF-1.2.2）。场景：C端用户下单后跳转蓝新MPG付款页完成支付，系统通过NotifyURL背景回调接收加密支付结果并更新订单payStatus。复用现有ezPay工具类的AES-256-CBC+SHA256加密模式与PosStoreEzpay门店凭证存储模式。第一期支付方式：信用卡、LINE Pay、Apple Pay；凭证门店级存储；功能为核心闭环（下单支付+回调+单笔查询）。spec编号011，不新建分支，在当前test分支开发。"
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - C端用户用信用卡完成线上支付 (Priority: P1)
+
+C端用户在门店下单（外卖/自取/堂食扫码点餐）后选择线上支付，系统按订单所属门店的蓝新凭证生成加密交易参数（商店订单号、合计金额、启用信用卡），前端以 Form Post 将用户跳转至蓝新 MPG 付款页面；用户在蓝新页输入信用卡完成付款，蓝新通过 NotifyURL 背景通知系统支付结果，系统解密验签后把订单支付状态更新为「已支付」。
+
+**Why this priority**: 这是「用户能在线付钱、商家能收到钱」的核心价值，是整个支付接入的主链路；没有它，后续回调、查询、对账都无从谈起。
+
+**Independent Test**: 对一个已开通蓝新的门店下一笔订单 → 选择信用卡支付 → 跳转蓝新付款页并完成 → 订单支付状态变为已支付，订单上记录蓝新交易序号与支付方式。
+
+**Acceptance Scenarios**:
+
+1. **Given** 订单所属门店已开通且启用蓝新支付，**When** 用户下单并选择线上信用卡支付，**Then** 系统生成加密交易参数并跳转至蓝新 MPG 付款页，页面上出现信用卡支付选项。
+2. **Given** 用户已在蓝新付款页成功完成信用卡付款，**When** 蓝新向系统 NotifyURL 发送支付结果，**Then** 系统解密回调、验签通过、金额一致后，订单支付状态更新为「已支付」，记录蓝新交易序号(TradeNo)、支付方式(CREDIT)、授权码与支付时间。
+3. **Given** 门店未开通蓝新支付或已停用，**When** 用户下单，**Then** 不提供线上支付选项（或提示该门店暂不支持线上支付）。
+
+---
+
+### User Story 2 - 系统正确处理蓝新支付结果回调 (Priority: P1)
+
+蓝新在每笔交易支付完成（或失败）后，以 Form Post 向系统 NotifyURL 发送加密的支付结果（Status、MerchantID、TradeInfo、TradeSha 等）。系统用订单所属门店的 HashKey/HashIV 对 TradeInfo 做 AES 解密、对 TradeSha 做 SHA256 验签、用 CheckCode 校验关键字段，确认交易成功且回调金额与订单金额一致后，才更新订单支付状态。同一笔交易被蓝新重复通知时，系统只处理一次（幂等）。
+
+**Why this priority**: 回调是订单状态真实性的唯一可信来源——前端跳回(ReturnURL)只代表用户走完流程，不代表付款成功。回调的解密、验签、幂等、金额校验是支付安全的底线，与 US1 同为核心。
+
+**Independent Test**: 构造一笔成功的蓝新回调报文（正确加密+签名+金额）发送到 NotifyURL → 订单变为已支付；将同一报文再发一次 → 订单状态不变（幂等）；篡改金额后发送 → 订单拒绝更新。
+
+**Acceptance Scenarios**:
+
+1. **Given** 一笔交易成功且金额与订单一致的正确加密回调，**When** 蓝新发送到 NotifyURL，**Then** 订单支付状态更新为已支付，系统记录交易明细并向蓝新返回成功应答。
+2. **Given** 同一交易（同一蓝新交易序号 TradeNo）的回调被发送多次，**When** 系统再次收到，**Then** 不重复更新订单、不重复记录，仍返回成功应答。
+3. **Given** 回调中的金额与订单合计金额不一致，**When** 系统处理，**Then** 拒绝更新订单支付状态，记录异常告警，便于运营核查。
+4. **Given** 回调签名(TradeSha)校验失败或解密失败，**When** 系统处理，**Then** 拒绝更新并记录，防止伪造回调。
+5. **Given** 交易付款失败的回调（Status 为错误代码），**When** 系统处理，**Then** 订单保持未支付，记录失败原因。
+
+---
+
+### User Story 3 - C端用户使用 LINE Pay / Apple Pay 支付 (Priority: P2)
+
+用户在蓝新 MPG 付款页除信用卡外，还可选择 LINE Pay 或 Apple Pay。选 LINE Pay 时跳转 LINE 完成付款；选 Apple Pay 时调起 Apple Pay 完成付款。两种方式付款完成后，蓝新同样通过 NotifyURL 通知系统，系统处理流程与信用卡一致。
+
+**Why this priority**: 信用卡已覆盖核心付款，LINE Pay 与 Apple Pay 是台湾高频的体验增强，但依赖 US1/US2 主链路先打通，故 P2。
+
+**Independent Test**: 对已开通蓝新的门店下单 → 在蓝新付款页分别选 LINE Pay 与 Apple Pay 完成支付 → 订单支付状态均变为已支付，记录对应支付方式（LINEPAY / APPLEPAY）。
+
+**Acceptance Scenarios**:
+
+1. **Given** 订单已发起且启用 LINE Pay，**When** 用户在蓝新页选 LINE Pay 并完成，**Then** 回调到达后订单更新为已支付，支付方式记录为 LINE Pay。
+2. **Given** 订单已发起且启用 Apple Pay，**When** 用户在 Apple Pay 设备上调起并完成，**Then** 回调到达后订单更新为已支付，支付方式记录为 Apple Pay。
+3. **Given** 门店未在发起参数中启用某支付方式，**When** 用户到达蓝新付款页，**Then** 该支付方式不出现（按门店配置/商店设定控制）。
+
+---
+
+### User Story 4 - 门店开通并管理蓝新支付凭证 (Priority: P2)
+
+门店在平台代为向蓝新申请商店账号后，运营在平台后台录入该门店的 MerchantID/HashKey/HashIV，系统调用蓝新能力验证凭证有效性后开通；门店可启用/停用蓝新支付。该流程复用 009-ezpay-invoice-onboarding 已建立的「平台代申请 → 运营录入凭证 → 验证开通 → 可停用」管理模式。
+
+**Why this priority**: 凭证是发起任何交易的前提，但属于配置态、非交易主链路，复用 009 成熟流程可快速落地，故 P2。
+
+**Independent Test**: 运营在后台为某门店录入一组蓝新凭证 → 系统验证通过后状态变为「已开通」→ 该门店订单即可发起线上支付；停用后该门店订单不再提供线上支付。
+
+**Acceptance Scenarios**:
+
+1. **Given** 运营在后台为门店录入蓝新 MerchantID/HashKey/HashIV，**When** 提交并触发验证，**Then** 凭证有效则状态置「已开通」并记录开通时间，无效则提示验证失败原因。
+2. **Given** 门店已开通蓝新，**When** 运营/商家停用，**Then** 该门店订单不再提供线上支付，凭证保留以便重新启用。
+3. **Given** 门店从未录入蓝新凭证，**When** 查看门店，**Then** 状态为「未申请」，订单不提供线上支付。
+
+---
+
+### User Story 5 - 商家/平台通过单笔查询确认订单支付状态 (Priority: P3)
+
+当 NotifyURL 回调因网络等原因未到达、或需要对账时，商家在商家端、运营在平台后台可对某订单主动发起蓝新单笔交易查询；系统用门店凭证向蓝新查询，返回该笔交易的支付状态(TradeStatus)、支付方式、支付时间等，并据此校正订单支付状态（回调丢失时的补单）。
+
+**Why this priority**: 查询是对账与异常补救手段，依赖交易主链路稳定运行后才有意义，频率低，故 P3。
+
+**Independent Test**: 对一笔用户已付款但订单仍为未支付的订单（回调丢失），运营点「查询支付状态」→ 系统向蓝新查询返回已支付 → 订单状态被校正为已支付。
+
+**Acceptance Scenarios**:
+
+1. **Given** 一笔订单用户已付款但回调未到达（订单仍为未支付），**When** 运营发起单笔查询，**Then** 系统向蓝新查询得 TradeStatus=付款成功，订单支付状态校正为已支付并记录明细。
+2. **Given** 一笔未支付订单，**When** 发起查询，**Then** 返回蓝新 TradeStatus=未付款，订单状态保持未支付。
+3. **Given** 一笔订单查询返回付款失败，**When** 系统处理，**Then** 订单保持未支付，记录失败原因，可重新发起支付。
+
+---
+
+### Edge Cases
+
+- **回调丢失**：用户已付款但 NotifyURL 回调未到达 → 订单停留未支付，由 US5 单笔查询补单。
+- **回调重复**：蓝新对同一笔交易重试多次通知 → 系统按蓝新交易序号(TradeNo)幂等，只处理一次。
+- **金额不一致**：回调金额 ≠ 订单合计金额 → 拒绝更新，记录告警，不影响订单。
+- **签名/解密失败**：伪造或损坏的回调 → 拒绝更新并记录。
+- **支付中途关闭/超时**：用户跳转蓝新后未完成付款即关闭 → 订单停留未支付，可重新发起支付（生成新的商店订单号 MerchantOrderNo）。
+- **门店凭证未开通/已停用**：不展示线上支付入口，下单走原有到付等方式。
+- **同一订单重复发起支付**：每次发起生成新的商店订单号，旧发起作废，回调按最新 TradeNo 处理。
+- **蓝新测试与正式环境切换**：通过配置在 ccore（测试）与 core（正式）间切换，避免误用。
+- **回调到达早于订单发起记录落库**：以商店订单号(MerchantOrderNo)关联订单，回调到达时若订单不存在则记录并跳过，等待人工/查询处理。
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: 系统 MUST 能按订单所属门店读取该门店的蓝新凭证（MerchantID/HashKey/HashIV），未开通或已停用的门店不能发起线上支付。
+- **FR-002**: 系统 MUST 生成符合蓝新 MPG 规范的加密交易参数：以门店 HashKey/HashIV 对交易明文做 AES-256-CBC(PKCS7) 加密生成 TradeInfo，再用 SHA256 生成 TradeSha，串接版本号 2.3。
+- **FR-003**: 系统 MUST 在发起交易时支持信用卡、LINE Pay、Apple Pay 三种支付方式的启用开关，并可按门店配置控制可选方式。
+- **FR-004**: 系统 MUST 为每笔交易生成门店内唯一的商店订单号(MerchantOrderNo)，并与系统订单号(ddId)关联，同一门店内不可重复。
+- **FR-005**: 支付金额 MUST 取订单合计金额(amount，整数元，新台币)。
+- **FR-006**: 系统 MUST 提供一个对外公网(80/443)的 NotifyURL 接口接收蓝新 Form Post 回调，对 TradeInfo 解密、对 TradeSha 验签、用 CheckCode 校验关键字段。
+- **FR-007**: 回调处理 MUST 幂等——同一蓝新交易序号(TradeNo)的多次通知只更新订单一次。
+- **FR-008**: 回调 MUST 校验「回调金额 = 订单合计金额」且签名正确，任一不符则拒绝更新订单支付状态并记录。
+- **FR-009**: 交易成功回调 MUST 把订单支付状态(payStatus)更新为「已支付」，并记录蓝新交易序号、支付方式、授权码、支付完成时间。
+- **FR-010**: 系统 MUST 记录每笔蓝新支付的完整明细（商店订单号、蓝新交易序号、门店、支付方式、金额、支付状态、支付时间、回调原始结果），用于幂等与对账。
+- **FR-011**: 系统 MUST 支持对订单发起蓝新单笔交易查询(QueryTradeInfo)，返回并展示蓝新侧支付状态，并据此校正订单支付状态。
+- **FR-012**: 门店 MUST 能在平台后台录入/验证/启用/停用蓝新支付凭证，复用 009-ezpay-invoice-onboarding 的开通管理流程。
+- **FR-013**: 未支付订单 MUST 能重新发起支付（生成新商店订单号），原发起作废。
+- **FR-014**: 系统 MUST 支持测试环境(ccore.newebpay.com)与正式环境(core.newebpay.com)通过配置切换。
+- **FR-015**: 支付完成页(ReturnURL) MUST 将用户引导回系统前端并展示支付结果，但订单状态以 NotifyURL 回调为准（前端只作引导，不触发状态变更）。
+
+### Key Entities *(include if feature involves data)*
+
+- **门店蓝新支付凭证(PosStoreNewebpay)**：与 pos_store 一对一。记录该门店的蓝新申请状态（未申请/申请中/已开通）、启用开关、MerchantID、HashKey、HashIV、申请时间、开通时间、最近验证结果、备注及审计字段。门店无此记录即视为未申请。复用 009 模式。
+- **订单(PosOrder，已有实体扩展)**：复用 ddId(订单号)、amount(合计金额)、payType(支付方式，扩展蓝新取值)、payStatus(支付状态 0未支付/1已支付/2已退款)、payUrl(发起支付后的跳转地址)。本期扩展 payType 取值以区分蓝新信用卡/LINE Pay/Apple Pay。
+- **支付交易流水(PosOrderPayment，新增)**：每笔蓝新交易一条。记录系统订单号(ddId)、商店订单号(MerchantOrderNo)、蓝新交易序号(TradeNo)、门店ID、支付方式、金额、支付状态、支付完成时间、回调原始结果、创建/更新时间。作为回调幂等判重与对账的依据。
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 已开通蓝新的门店，C端用户下单后不超过 3 次点击即可跳转至蓝新付款页。
+- **SC-002**: 在 NotifyURL 回调正常到达的情况下，用户付款完成后 30 秒内订单支付状态更新为「已支付」。
+- **SC-003**: 异常回调（重复通知、金额不符、签名错误、解密失败）不会导致订单被错误更新，此类异常误更新率为 0%。
+- **SC-004**: 99% 的支付回调在蓝新发出后 10 秒内被系统正确处理并应答。
+- **SC-005**: 回调丢失时，运营通过单笔查询可在 1 分钟内补正订单支付状态。
+- **SC-006**: 门店运营可在平台后台自助完成蓝新凭证的录入、验证与启用/停用，无需开发介入。
+- **SC-007**: 信用卡、LINE Pay、Apple Pay 三种支付方式均能完成「下单→付款→订单已支付」完整链路。
+
+## Assumptions
+
+- 复用现有 ezPay 工具类的「AES-256-CBC + SHA256」加密思路，但因蓝新 PKCS7 填充块为标准 16 字节（ezPay 为特殊的 32 字节）且 MPG 为幕前 Form Post（非幕后的 PostData_），需新建独立的 NewebPay 加密客户端与工具类，不复用 EzPayEncryptUtil 的加密实现。
+- 凭证按门店存储，开通管理复用 009-ezpay-invoice-onboarding 已建立的「平台代申请 → 运营录入凭证 → 验证开通 → 可停用」流程与界面模式（新建对应蓝新的实体/表/接口，不与 ezPay 发票凭证混用）。
+- 面向 C 端用户下单场景（外卖/自取/堂食扫码点餐）收款；商家端与平台后台用于凭证管理与对账查询。
+- 商店订单号 MerchantOrderNo 以系统订单号 ddId 派生（如加门店/时间前缀），保证门店内唯一、可追溯。
+- 支付金额取订单合计金额 amount（整数元，新台币），与发票口径（amount−freight 不含运费）不同；发票与支付各自独立计算。
+- NotifyURL/ReturnURL 为系统对外公网接口（仅 80/443），部署环境需可被蓝新服务器访问。
+- 测试环境使用蓝新 ccore.newebpay.com，正式环境 core.newebpay.com，通过配置切换；接入初期在测试环境验证，正式启用前更换正式凭证。
+- 在当前 test 分支开发，不新建分支；所有数据库变更写入 updatesql/sql.md，不直接执行。
+- 第一期不含退款、取消授权、信用卡定期定额/订阅（NDNP）；这些作为后续迭代。
+- 现有 PosOrder 的 payStatus 字段语义（0未支付/1已支付/2已退款）沿用，本期主要写入 0/1。
+- 前端为 Vue（商家端 foodie-store / 平台端 foodie-admin-vue），支付方式相关文案须按项目规范实现四语 i18n（vi/zh/tw/en）。

specs/011-newebpay-payment/tasks.md

@@ -0,0 +1,208 @@
+---
+description: "Task list for 蓝新金流(NewebPay)线上支付接入"
+---
+
+# Tasks: 蓝新金流(NewebPay)线上支付接入
+
+**Input**: Design documents from `/specs/011-newebpay-payment/`
+
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/, quickstart.md（均已就绪）
+
+**Tests**: 未要求 TDD；验证以 `NewebPayEncryptUtil.main` 自测 + quickstart.md 端到端场景为准。
+
+**Organization**: 按 user story 组织，每个 story 可独立实现与验证。MVP = US1 + US2（支付闭环）。
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: 可并行（不同文件、无依赖）
+- **[Story]**: 归属 user story（US1~US5）
+- 描述含精确文件路径；前端 CRLF 文件用 Python 脚本编辑
+
+---
+
+## Phase 1: Setup（基础设施）
+
+**Purpose**: 数据库 DDL 与配置就位
+
+- [ ] T001 追加两表建表 DDL 到 `updatesql/sql.md`（pos_store_newebpay、pos_order_payment，取自 data-model.md，标注 2026-06-22 蓝新支付接入）
+- [ ] T002 [P] 在 `ruoyi-admin/src/main/resources/application.yml` 新增 newebpay 配置段（base-url=ccore.newebpay.com、notify-url、return-url、mpg-version=2.3），仿 ezpay 段
+
+---
+
+## Phase 2: Foundational（阻塞前置，所有 story 依赖）
+
+**Purpose**: 加密工具、HTTP 客户端、实体、Mapper——所有 story 的公共地基
+
+**⚠️ CRITICAL**: 本阶段完成前不得开始任何 user story
+
+- [ ] T003 [P] 创建 `ruoyi-admin/src/main/java/com/ruoyi/app/utils/newebpay/NewebPayConfig.java`（merchantId/hashKey/hashIV，仿 EzPayConfig）
+- [ ] T004 创建 `ruoyi-admin/src/main/java/com/ruoyi/app/utils/newebpay/NewebPayEncryptUtil.java`：AES-256-CBC/PKCS7Padding(块16) encrypt/decrypt(hex)、genTradeSha(`HashKey=&{enc}&HashIV=`)、genCheckValue(`IV=&{Amt/MerchantID/MerchantOrderNo 排序}&Key=`)、genCheckCode(`HashIV=&{Amt/MerchantID/MerchantOrderNo/TradeNo 排序}&HashKey=`)；含 main 自测用 NDNF §4.1 示例(Key=Fs5cX1TGqYM2PpdbE14a9H83YQSQF5jn/IV=C6AcmfqJILwgnhIP/MID=MS127874575)验证加解密 round-trip 与 TradeSha 规则
+- [ ] T005 [P] 创建 `ruoyi-system/src/main/java/com/ruoyi/system/domain/PosStoreNewebpay.java`（@TableName pos_store_newebpay，字段见 data-model.md）
+- [ ] T006 [P] 创建 `ruoyi-system/src/main/java/com/ruoyi/system/domain/PosOrderPayment.java`（@TableName pos_order_payment，字段见 data-model.md）
+- [ ] T007 [P] 创建 `ruoyi-system/src/main/java/com/ruoyi/system/mapper/PosStoreNewebpayMapper.java` + `ruoyi-system/src/main/resources/mapper/chanting/PosStoreNewebpayMapper.xml`（仿 PosStoreEzpayMapper，基础 CRUD）
+- [ ] T008 [P] 创建 `ruoyi-system/src/main/java/com/ruoyi/system/mapper/PosOrderPaymentMapper.java` + `ruoyi-system/src/main/resources/mapper/chanting/PosOrderPaymentMapper.xml`（insert、selectByTradeNo、selectByDdId、updateById）
+- [ ] T009 [P] 创建 `ruoyi-admin/src/main/java/com/ruoyi/app/utils/newebpay/NewebPay.java` HTTP 客户端：端点常量(URL_MPG_GATEWAY、URL_QUERY_TRADE_INFO、BASE_TEST=ccore/BASE_PROD=core)、createMpgForm(baseUrl,cfg,params)→加密form字段Map、queryTrade(baseUrl,cfg,amt,orderNo)→JSONObject、buildQuery(http_build_query)、postForm
+
+**Checkpoint**: 加密自测通过、表可建、实体/Mapper 就绪 → 可开始 user story
+
+---
+
+## Phase 3: User Story 1 - 发起蓝新支付(信用卡) (Priority: P1) 🎯 MVP part 1
+
+**Goal**: C端用户下单后调发起接口拿到加密form参数，前端Form Post跳转蓝新付款页
+
+**Independent Test**: 对已开通蓝新的门店下单 → 调 /pay/newebpay/create → 返回 gatewayUrl+TradeInfo+TradeSha → 前端跳转蓝新页出现信用卡选项；pos_order_payment 落一行(pay_status=0)、pos_order.pay_type=6
+
+- [ ] T010 [P] [US1] 创建 `ruoyi-system/src/main/java/com/ruoyi/system/domain/dto/StoreNewebpayCredentialDto.java`（storeId/merchantId/hashKey/hashIv/enabledPayments）与 `ruoyi-system/src/main/java/com/ruoyi/system/domain/vo/PosStoreNewebpayVo.java`（列表/详情VO）
+- [ ] T011 [US1] 实现 `ruoyi-system/.../service/IPosStoreNewebpayService.java` + `impl/PosStoreNewebpayServiceImpl.java`（纯DB：getOrCreateByStoreId、getEnabledConfig(storeId)返回启用且已开通的凭证或null、基础保存），仿 PosStoreEzpayServiceImpl
+- [ ] T012 [US1] 实现 `ruoyi-system/.../service/IPosOrderPaymentService.java` + `impl/PosOrderPaymentServiceImpl.java`（createPayment(ddId,merchantOrderNo,storeId,merchantId,amount)发起流水、getByTradeNo、getByMerchantOrderNo、markSuccess(tradeNo,payType,authCode,payTime,callbackRaw)、markFail）
+- [ ] T013 [US1] 在 `ruoyi-system/.../domain/PosOrder.java` 附近定义 payType 蓝新取值常量（PAY_TYPE_NEWEBPAY="6"），或新建枚举类；不改表结构
+- [ ] T014 [US1] 创建 `ruoyi-admin/src/main/java/com/ruoyi/app/pay/NewebpayPayController.java` 实现 `POST /pay/newebpay/create`（@Anonymous+@Auth）：校验订单存在/未支付/属当前用户 → 查门店启用凭证(无则报错) → 生成 merchant_order_no="NB"+ddId → 组装TradeInfo明文(MerchantID/RespondType=JSON/TimeStamp/Version=2.3/MerchantOrderNo/Amt=amount/ItemDesc/NotifyURL/ReturnURL/CREDIT=1) → NewebPayEncryptUtil 加密+TradeSha → 落 pos_order_payment → 更新 pos_order.payType=6/payUrl=gatewayUrl → 返回 form 字段（见 contracts/api.md B1）
+- [ ] T015 [US1] 前端 `E:\QtwCode\foodie\foodie-store\` 新增"蓝新支付"入口：用户下单后调 /pay/newebpay/create，用返回字段构建隐藏 form 自动 submit 到 gatewayUrl；支付方式相关文案用 $t() 四语 i18n（zh/tw/en/vi，key 加到对应对象层级，如支付/订单对象内）
+
+**Checkpoint**: 发起支付链路通，可跳转蓝新测试页（此时回调未接，订单状态待 US2 更新）
+
+---
+
+## Phase 4: User Story 2 - 支付结果回调处理 (Priority: P1) 🎯 MVP part 2
+
+**Goal**: 蓝新NotifyURL回调到达后，解密验签+幂等+金额校验，更新订单payStatus=1并触发推送；ReturnURL仅引导
+
+**Independent Test**: US1发起并跳转后用测试卡付款 → 蓝新回调 /pay/newebpay/notify → 订单payStatus变1、pos_order_payment写trade_no/pay_type=CREDIT、商家/骑手收到推送；重复回调不变；金额不符/伪造签名拒绝
+
+- [ ] T016 [US2] 在 `NewebpayPayController.java` 实现 `POST /pay/newebpay/notify`（@Anonymous）：收Form参数 → 记IpnLog → 由MerchantID查门店凭证 → 无凭证记录返回
+- [ ] T017 [US2] notify 验签解密：`genTradeSha(TradeInfo,key,iv)==TradeSha` 校验，不符拒绝记录；通过则 `NewebPayEncryptUtil.decrypt(TradeInfo)` 解出 Status/MerchantOrderNo/TradeNo/Amt/PaymentType/PayTime/Auth
+- [ ] T018 [US2] notify 幂等+金额校验：按TradeNo查 pos_order_payment（已存在且pay_status=1→直接返回成功应答）；Amt==订单amount校验（不符→拒绝更新、记录告警）；由MerchantOrderNo反查pos_order（不存在→记录待查返回）
+- [ ] T019 [US2] notify 成功业务链路（Status=SUCCESS且校验通过）：markSuccess写流水、pos_order.payStatus=1(state不变)、orderLogHelper.logSync记日志、复用 pushEventService.PublisherEvent + sendAcceptRiderPush 推送用户/商家/骑手（参照 PayController.payipn）；返回 `{"Status":"SUCCESS","Message":"OK"}`
+- [ ] T020 [US2] notify 失败处理（Status≠SUCCESS）：markFail记 pos_order_payment(pay_status=2)、订单保持未支付、记失败原因、返回成功应答
+- [ ] T021 [US2] 在 `NewebpayPayController.java` 实现 `GET/POST /pay/newebpay/return`（@Anonymous）：仅302重定向前端结果页(带ddId)，不改订单状态（FR-015）
+- [ ] T022 [US2] 前端 `E:\QtwCode\foodie\foodie-store\` 支付结果页：展示支付状态，轮询订单payStatus（因ReturnURL不改状态，以轮询/回调后状态为准）；文案四语 i18n
+
+**Checkpoint**: US1+US2 构成完整 MVP——下单→付款→订单已支付→推送，可端到端验证（quickstart 场景2、3）
+
+---
+
+## Phase 5: User Story 3 - LINE Pay / Apple Pay (Priority: P2)
+
+**Goal**: 用户在蓝新页可选 LINE Pay / Apple Pay，回调方式记录正确
+
+**Independent Test**: 门店enabled_payments含LINEPAY/APPLEPAY → 发起参数带LINEPAY=1/APPLEPAY=1 → 蓝新页出现选项 → 付款后回调pay_type为LINEPAY/APPLEPAY
+
+- [ ] T023 [P] [US3] 扩展 `NewebpayPayController.create`：按门店 enabled_payments 在TradeInfo明文中设 LINEPAY=1 / APPLEPAY=1（与CREDIT并存），读取门店 pos_store_newebpay.enabled_payments
+- [ ] T024 [US3] notify 解析 PaymentType 映射到 pos_order_payment.pay_type（CREDIT/LINEPAY/APPLEPAY，回调字段 PaymentType/PaymentMethod），确保 US2 的 markSuccess 正确写入方式
+- [ ] T025 [US3] 前端 `E:\QtwCode\foodie\foodie-store\` 支付方式展示：按门店启用方式渲染可选标识（发起前提示），文案四语 i18n
+
+**Checkpoint**: 三种支付方式均可完成闭环（quickstart 场景4；Apple Pay 需具备 HTTPS+Apple 配置）
+
+---
+
+## Phase 6: User Story 4 - 门店蓝新凭证开通管理 (Priority: P2)
+
+**Goal**: 运营在平台后台录入/验证/启停门店蓝新凭证，复用009模式
+
+**Independent Test**: 后台为门店录入测试凭证 → 调QueryTradeInfo验证通过 → 状态已开通 → 该门店可发起支付；停用后不可
+
+- [ ] T026 [US4] 创建 `ruoyi-admin/src/main/java/com/ruoyi/app/mendian/PosStoreNewebpayController.java`（/system/storeNewebpay，@PreAuthorize chanting:storeNewebpay:*）：list/{storeId}/apply/saveCredentials/toggleEnable/reset/enabledPayments，仿 PosStoreEzpayController
+- [ ] T027 [US4] saveCredentials 凭证验证：Controller 调 NewebPay.queryTrade(虚构订单)探测，返回金钥/商店错误(MPG01001类/Status≠SUCCESS且Message含金钥)→视为无效拒绝；否则置 newebpay_status=2/is_enabled=1、记last_verify_result
+- [ ] T028 [US4] 扩展 `PosStoreNewebpayServiceImpl`：apply(0→1)、enableWithCredentials、toggleEnable、reset、setEnabledPayments、recordVerifyResult（仿 PosStoreEzpayServiceImpl 状态机）
+- [ ] T029 [US4] 平台后台 `E:\QtwCode\foodie\foodie-admin-vue\` 新增门店蓝新凭证管理页（列表分页/详情/录入凭证/启停/重置/设置支付方式），文案四语 i18n
+- [ ] T030 [US4] 菜单与权限：新增菜单项 + 权限标识 chanting:storeNewebpay:list/query/apply/saveCredentials/toggleEnable，SQL 写入 `updatesql/sql.md`（sys_menu 插入，仿 storeEzpay 菜单）
+
+**Checkpoint**: 凭证可全流程管理，US1/US3 发起支付有真实凭证来源（不必手插数据）
+
+---
+
+## Phase 7: User Story 5 - 单笔交易查询/补单 (Priority: P3)
+
+**Goal**: 回调丢失或对账时，主动查蓝新并校正订单状态
+
+**Independent Test**: 回调丢失(订单未支付) → 调 /pay/newebpay/query → 蓝新返回TradeStatus=1 → 补更新payStatus=1+推送
+
+- [ ] T031 [US5] 在 `NewebpayPayController.java` 实现 `POST /pay/newebpay/query`（@Auth）：查订单+门店凭证 → genCheckValue → NewebPay.queryTrade 调 /API/QueryTradeInfo → 解析 TradeStatus/PaymentType/PayTime
+- [ ] T032 [US5] 查询补单：若蓝新TradeStatus=1且订单payStatus仍0 → 执行与US2相同的状态更新+流水+推送（抽取公共方法供 notify/query 复用，避免重复）
+- [ ] T033 [US5] 商家端 `E:\QtwCode\foodie\foodie-store\` 订单详情增加"查询支付状态"入口（展示蓝新TradeStatus/支付方式/时间），文案四语 i18n
+
+**Checkpoint**: 对账与补单可用（quickstart 场景5）
+
+---
+
+## Phase 8: Polish & Cross-Cutting
+
+**Purpose**: 多 story 共享的收尾
+
+- [ ] T034 [P] 四语 i18n 统一校验：foodie-store 与 foodie-admin-vue 的 zh.js/tw.js/en.js/vi.js 中支付相关 key 四文件齐全、命名有意义、位于正确对象层级（用 i18n-consistency-checker 或人工核）
+- [ ] T035 [P] 安全复核：NotifyURL/ReturnURL 确为 @Anonymous 且仅此两接口匿名；HashKey/HashIV 不出现在任何前端响应；回调 TradeSha 验签为强制前置；金额校验不可绕过
+- [ ] T036 运行 `specs/011-newebpay-payment/quickstart.md` 全部 6 场景端到端验证（测试环境 ccore + 测试卡 + 内网穿透），记录结果
+- [ ] T037 文档一致性：确认 spec.md/plan.md/tasks.md 描述一致；更新 `updatesql/sql.md` 中所有 SQL 齐全（两建表 + 菜单权限）
+
+---
+
+## Dependencies & Execution Order
+
+### Phase 依赖
+- **Phase 1 Setup**: 无依赖，立即开始
+- **Phase 2 Foundational**: 依赖 Phase 1（配置/DDL）—— **阻塞所有 user story**
+- **Phase 3 US1**: 依赖 Phase 2
+- **Phase 4 US2**: 依赖 US1（回调处理依赖发起产生的流水与订单关联）
+- **Phase 5 US3**: 依赖 US1+US2（复用主链路，增量在参数开关与方式解析）
+- **Phase 6 US4**: 依赖 Phase 2（凭证表/Mapper）；可与 US1 并行（US1 测试可临时手插凭证数据）
+- **Phase 7 US5**: 依赖 US1+US2（查询补单复用状态更新逻辑）
+- **Phase 8 Polish**: 依赖所有欲交付的 story 完成
+
+### User Story 独立性
+- **US1**: 依赖 Foundational，无跨 story 依赖
+- **US2**: 依赖 US1（闭环下半段）
+- **US3**: 依赖 US1+US2，但增量小（参数+解析）
+- **US4**: 依赖 Foundational，可与 US1 并行
+- **US5**: 依赖 US1+US2
+
+### 并行机会
+- Phase 2 的 T003/T005/T006/T007/T008/T009 互不冲突，可全部并行
+- US4（Phase 6）可与 US1/US2（Phase 3/4）并行（不同文件、不同端）
+- Phase 8 的 T034/T035 可并行
+
+---
+
+## Parallel Example: Foundational
+
+```bash
+# 以下任务文件互不冲突，可并行：
+Task: "NewebPayConfig in ruoyi-admin/.../utils/newebpay/NewebPayConfig.java"
+Task: "PosStoreNewebpay in ruoyi-system/.../domain/PosStoreNewebpay.java"
+Task: "PosOrderPayment in ruoyi-system/.../domain/PosOrderPayment.java"
+Task: "PosStoreNewebpayMapper + XML"
+Task: "PosOrderPaymentMapper + XML"
+Task: "NewebPay HTTP 客户端骨架 in ruoyi-admin/.../utils/newebpay/NewebPay.java"
+# 仅 NewebPayEncryptUtil(T004) 含被他人依赖的加密契约，建议优先完成并跑通自测
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First（US1 + US2）
+1. Phase 1 Setup + Phase 2 Foundational（**加密自测必须先过**）
+2. Phase 3 US1（发起支付）+ Phase 4 US2（回调处理）→ 端到端验证（quickstart 场景2、3）
+3. **STOP and VALIDATE**: 下单→信用卡付款→订单已支付→推送，全链路通
+4. 此时已是最小可用产品
+
+### 增量交付
+1. MVP（US1+US2）→ 验证 → 可上测试环境
+2. + US3（LINE Pay/Apple Pay）→ 验证
+3. + US4（凭证管理）→ 去除手插数据、运营自助
+4. + US5（查询补单）→ 异常补救就绪
+5. Polish（i18n/安全/全场景验证）→ 可转正式
+
+### 并行策略
+- Foundational 完成后：开发者 A 做 US1+US2（主链路），开发者 B 做 US4（凭证管理前端+后端），互不阻塞
+- US3/US5 待主链路稳定后接力
+
+---
+
+## Notes
+
+- [P] 任务 = 不同文件、无依赖；同文件多改动须串行
+- 前端 CRLF 文件（foodie-store/foodie-admin-vue）用 Python 脚本编辑，避免 Edit 匹配失败
+- 所有数据库变更写 `updatesql/sql.md`，不直接执行
+- 每个任务或逻辑组完成后提交（按用户指示）；在 test 分支开发，不新建分支
+- HashKey/HashIV 为敏感凭证：仅后端持有，日志脱敏，不下发前端

specs/012-im-user-integration/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: 骑手与用户 IM 即时沟通账号接入
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-06-23
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs) — 仅描述业务能力与外部集成契约，未指定技术栈
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain — FR-007/008 已通过用户澄清定稿（app 触发独立接口、对所有类型开放）
+- [x] Requirements are testable and unambiguous（除待澄清项外）
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- 用户澄清：不改注册流程，由 APP 注册完成后自行调用独立开通接口 → 已据此重写 FR-001/FR-007/FR-008。
+- 合理默认（已记录为假设）：全用户类型开放、幂等返回、接口回传凭证、token 解析 userId。
+- 所有项已通过，spec 已具备进入 plan 的条件。

specs/012-im-user-integration/contracts/im-extcreate.md

@@ -0,0 +1,66 @@
+# Contract: IM 平台 extCreate（外部依赖）
+
+**方向**: 平台后端 → IM 平台（出站调用）
+**用途**: 为用户创建 IM 账号，获取 apiKey + userId
+
+## 请求
+
+```
+POST {im.base-url}{im.create-path}
+```
+
+- 测试环境示例：`POST https://test-im.abtim-my.com/bot/extCreate`
+- `create-path` 默认 `/bot/extCreate`
+
+### 请求头
+
+| Header | 值 | 来源 |
+|--------|----|----|
+| `extToken` | `92a88467-6eca-11f1-9dd5-00163e1eec55`（测试） | 配置 `im.ext-token` |
+
+### 请求体（JSON）
+
+```json
+{ "nickName": "+88615287406952", "type": 0 }
+```
+
+- `nickName`：昵称，由后端取用户 `userName`，无则取 `phone`（哪个有值用哪个）。
+- `type`：固定默认 `0`。
+- Content-Type：`application/json`。
+
+### 配置项（application.yml 新增段）
+
+```yaml
+# IM 即时沟通配置
+im:
+  base-url: https://test-im.abtim-my.com   # IM 平台根地址（正式环境另行配置）
+  ext-token: 92a88467-6eca-11f1-9dd5-00163e1eec55   # 平台级鉴权令牌
+  create-path: /bot/extCreate               # 创建用户接口路径
+  timeout-ms: 5000                          # 连接/读取超时(毫秒)
+```
+
+## 响应
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "apiKey": "f7a49f9745114462a3333e5698aac9ae",
+    "userId": 2069305587785445400
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `code` | int | 200 表示成功；非 200 视为失败 |
+| `message` | String | 状态描述 |
+| `data.apiKey` | String | IM API 密钥（落库 `im_api_key`，返回 APP） |
+| `data.userId` | long | IM 用户ID（落库 `im_user_id`，转 String 返回 APP） |
+
+## 处理规则
+
+- **成功**：`code == 200` 且 `data.apiKey`、`data.userId` 均非空 → 取 data 落库并返回。
+- **失败**：`code != 200`、data 缺字段、HTTP 非 2xx、超时、网络异常 → 抛异常，不写库，接口返回失败供 APP 重试。
+- **幂等**：调用前先查本地 `info_user`，已有 `imApiKey` 则不调用本接口，直接返回。

specs/012-im-user-integration/contracts/open-im-account.md

@@ -0,0 +1,51 @@
+# Contract: 开通 IM 账号接口（平台对外）
+
+**方向**: APP → 平台后端（入站接口）
+**用途**: APP 在用户注册完成后（或首聊前）调用，为当前登录用户开通/获取 IM 账号凭证
+
+## 请求
+
+```
+POST /infouser/user/im/open
+Header: token: <登录token>
+```
+
+- 鉴权：通过 `token` 请求头解析当前 userId（复用 `JwtUtil.getusid`），**不接受 body 传 userId**（防越权）。
+- 请求体：无（或空 JSON）。
+- 适用对象：所有已登录用户类型（普通0/商家1/骑手2/夜市3）。
+
+## 响应
+
+### 成功（首次开通 或 幂等返回）
+
+```json
+{
+  "code": 200,
+  "msg": "成功",
+  "data": {
+    "apiKey": "f7a49f9745114462a3333e5698aac9ae",
+    "imUserId": "2069305587785445400"
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data.apiKey` | String | IM API 密钥 |
+| `data.imUserId` | String | IM 用户ID（**字符串**，规避前端 Long 精度丢失） |
+
+### 失败
+
+| 场景 | 返回 |
+|------|------|
+| 未登录 / token 失效 | 错误（未登录提示），不开通 |
+| IM 平台不可用 / 超时 / 返回失败 | 错误（IM 开通失败，可重试），不写库 |
+
+> 失败沿用项目全局异常 / `AjaxResult.error(...)` 约定。
+
+## 行为契约
+
+1. **幂等**：当前用户已有 `imApiKey` → 直接返回现有凭证，不重复调用 IM 平台。
+2. **成对写入**：仅当 IM 返回 apiKey 与 userId 均有效时才同时写 `im_api_key`、`im_user_id`。
+3. **不阻塞注册**：本接口独立于注册流程；其失败不影响用户已注册状态。
+4. **不接收 userId 参数**：用户身份仅来自 token。

specs/012-im-user-integration/data-model.md

@@ -0,0 +1,73 @@
+# Data Model: 骑手与用户 IM 即时沟通账号接入
+
+**Phase**: 1 | **Date**: 2026-06-23
+
+## 变更表：info_user（用户信息）
+
+现有用户表，本期**新增两列**存储 IM 平台返回的凭证。
+
+### 新增字段
+
+| 列名 | Java 属性 | 类型 | 可空 | 说明 |
+|------|-----------|------|------|------|
+| `im_api_key` | `imApiKey` | VARCHAR(64) | 是 | IM 平台 extCreate 返回的 `data.apiKey`（如 `f7a49f9745114462a3333e5698aac9ae`，32 位十六进制）。用户尚未开通 IM 时为 NULL。 |
+| `im_user_id` | `imUserId` | BIGINT | 是 | IM 平台 extCreate 返回的 `data.userId`（如 `2069305587785445400`，19 位长整型）。用户尚未开通时为 NULL。 |
+
+### 关系
+
+- 一个 `info_user` 对应 **0 或 1** 组 IM 凭证（imApiKey 与 imUserId 同时为空，或同时有值）。
+- 凭证由 IM 平台生成，平台侧不可变；写入后不再更新（幂等返回）。
+
+### 验证规则（来自需求）
+
+- `imApiKey` 非空 ⇔ `imUserId` 非空（成对写入，避免脏数据）。
+- 写入前必须 IM 平台 `code == 200` 且 `data` 含非空 apiKey/userId，否则不写库。
+- 已有凭证的用户再次调用开通接口：不写库，直接返回现有凭证（幂等）。
+
+### Java 实体改动
+
+`InfoUser.java`（`com.ruoyi.system.domain`）新增：
+
+```java
+/** IM 平台 API 密钥（extCreate 返回） */
+@Excel(name = "IM apiKey")
+private String imApiKey;
+
+/** IM 平台用户ID（extCreate 返回，长整型） */
+@Excel(name = "IM userId")
+private Long imUserId;
+```
+
+> 因实体已用 Lombok `@Data`，无需手写 getter/setter；但该类仍保留大量手写 getter/setter，按现有风格在末尾补 `getImApiKey/setImApiKey`、`getImUserId/setImUserId` 保持一致（可选，@Data 已覆盖）。
+
+### Mapper 改动
+
+`InfoUserMapper.xml` 的 `InfoUserResult` resultMap 新增两行映射：
+
+```xml
+<result property="imApiKey"    column="im_api_key"    />
+<result property="imUserId"    column="im_user_id"    />
+```
+
+> `selectInfoUserVo` 为 `select * from info_user`，自动覆盖新列，无需改 SQL。
+
+### SQL 迁移
+
+写入 `updatesql/sql.md`（不直接执行）：
+
+```sql
+-- 2026-06-23 IM 即时沟通账号接入：info_user 新增 IM 凭证两列
+ALTER TABLE info_user ADD COLUMN im_api_key VARCHAR(64) DEFAULT NULL COMMENT 'IM平台API密钥(extCreate返回)';
+ALTER TABLE info_user ADD COLUMN im_user_id BIGINT DEFAULT NULL COMMENT 'IM平台用户ID(extCreate返回)';
+```
+
+## 新增 VO：ImAccountVo
+
+`com.ruoyi.system.domain.vo.ImAccountVo` —— 开通接口返回体。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `apiKey` | String | IM 平台返回的 apiKey |
+| `imUserId` | String | IM 平台返回的 userId（**String 规避前端 Long 精度丢失**） |
+
+> service 内部 `InfoUser.imUserId` 为 Long；组装 VO 时 `String.valueOf(imUserId)` 转字符串返回。

specs/012-im-user-integration/plan.md

@@ -0,0 +1,81 @@
+# Implementation Plan: 骑手与用户 IM 即时沟通账号接入
+
+**Branch**: `012-im-user-integration`（按用户要求未创建 git 分支） | **Date**: 2026-06-23 | **Spec**: [spec.md](spec.md)
+
+**Input**: Feature specification from `/specs/012-im-user-integration/spec.md`
+
+## Summary
+
+为骑手与用户的即时沟通能力提供 IM 账号开通基础。**不改动用户注册流程**；新增一个独立的「开通 IM 账号」HTTP 接口，APP 在用户注册完成后（或首次需要沟通时）自行调用。后端通过登录 token 解析出 userId，幂等地调用 IM 平台 `POST {base-url}/bot/extCreate`（请求头带 `extToken`），将返回的 `apiKey`/`userId` 绑定存入 `info_user` 表新增的两列（`im_api_key`、`im_user_id`），并把凭证返回给 APP 用于初始化 IM SDK。IM 域名与 extToken 集中放于 `application.yml`，HTTP 调用封装为独立 `@Component` 工具类（仿 `NewebPay`）。
+
+## Technical Context
+
+**Language/Version**: Java（Spring Boot），项目主语言，沿用现有技术栈。
+
+**Primary Dependencies**: Spring Boot、MyBatis-Plus（`@TableName`/`@TableField`）、MyBatis XML mapper、`org.apache.http`（HttpClient，参考 `NewebPay`）、`com.alibaba.fastjson2`（JSON 解析）、若依 `AjaxResult`/`BaseController`、`JwtUtil`（token→userId）。
+
+**Storage**: MySQL。`info_user` 表新增两列：`im_api_key VARCHAR(64)`、`im_user_id BIGINT`。
+
+**Testing**: 手动接口验证（Postman / curl）+ quickstart 验证指南。项目无自动化测试框架约定，沿用现有手动验证方式。
+
+**Target Platform**: Linux 服务器（Spring Boot 后端，端口 8082，context-path `/`）。
+
+**Project Type**: web-service（Spring Boot REST API）。
+
+**Performance Goals**: 开通接口额外开销 < 1s（单次外部 IM 调用）。
+
+**Constraints**: IM 平台不可用时接口明确返回失败、不写无效凭证；幂等（已有凭证直接返回）；未登录拒绝。
+
+**Scale/Scope**: 全量用户类型（普通0/商家1/骑手2/夜市3）。1 个新接口、1 个新工具类、2 个新字段、1 段配置、1 条 SQL。
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+`.specify/memory/constitution.md` 为未填写的空模板（项目尚未定义 constitution 原则）。无约束规则可校验，**本门禁默认通过**，无违规项。建议项目后续补充 constitution。
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/012-im-user-integration/
+├── plan.md              # 本文件
+├── research.md          # Phase 0：技术决策
+├── data-model.md        # Phase 1：info_user 字段
+├── contracts/
+│   ├── im-extcreate.md  # IM 平台 extCreate 外部契约
+│   └── open-im-account.md  # 平台对外「开通 IM 账号」接口契约
+├── quickstart.md        # Phase 1：端到端验证指南
+└── tasks.md             # Phase 2（/speckit-tasks 生成，本阶段不创建）
+```
+
+### Source Code (repository root)
+
+```text
+ruoyi-admin/src/main/
+├── java/com/ruoyi/app/
+│   ├── user/InfoUserController.java        # 【改】新增 POST /infouser/user/im/open 开通接口（注入 ImAccountService）
+│   ├── service/ImAccountService.java      # 【新】IM 开通编排服务(幂等+调ImClient+回写)，在 admin 避开模块反向依赖
+│   └── utils/im/
+│       └── ImClient.java                   # 【新】IM 平台 HTTP 客户端(@Component)，封装 extCreate
+└── resources/
+    └── application.yml                      # 【改】新增 im 配置段(base-url/ext-token/create-path/timeout)
+
+ruoyi-system/src/main/
+├── java/com/ruoyi/system/
+│   ├── domain/InfoUser.java                 # 【改】新增 imApiKey、imUserId 两字段 + getter/setter
+│   ├── service/
+│   │   └── (IInfoUserService / InfoUserServiceImpl 不改——编排移至 ruoyi-admin 的 ImAccountService)
+│   └── domain/vo/ImAccountVo.java           # 【新】返回 apiKey + imUserId 的 VO
+└── resources/mapper/infouser/
+    └── InfoUserMapper.xml                   # 【改】resultMap 新增 im_api_key / im_user_id 映射
+
+updatesql/sql.md                             # 【改】追加 info_user 加两列的 ALTER 语句
+```
+
+**Structure Decision**: 沿用项目现有「ruoyi-admin(Controller/utils) + ruoyi-system(domain/service/mapper)」分层。开通接口归属于已存在的 `InfoUserController`（用户域，已具备 `infoUserService`、token 解析依赖），仅追加 1 个方法，避免新建控制器带来的冗余。外部 IM HTTP 调用封装为独立 `@Component` 工具类 `ImClient`（仿 `NewebPay`），由 service 注入调用，保持 service 可测试性与关注点分离。配置用 `@Value` 注入（仿 `NewebPayPayController`）。
+
+## Complexity Tracking
+
+无 Constitution 违规，无需记录复杂度豁免。本方案保持最小改动：2 字段、1 接口、1 工具类、1 配置段、1 SQL，不引入新分层、不改动注册流程。

specs/012-im-user-integration/quickstart.md

@@ -0,0 +1,67 @@
+# Quickstart: 骑手与用户 IM 即时沟通账号接入
+
+**Phase**: 1 | **Date**: 2026-06-23
+
+端到端验证指南。本文件仅描述"如何验证功能可用"，具体实现代码见 tasks.md 与实现阶段。
+
+## 前置条件
+
+1. 数据库已执行 `updatesql/sql.md` 中 `info_user` 加两列的 ALTER（由开发者统一手动执行）。
+2. `application.yml` 已配置 `im` 段（base-url / ext-token / create-path / timeout-ms），且 `im.ext-token` 与 IM 平台一致。
+3. 后端服务已重启加载新配置与新代码。
+4. 已有一个可登录的测试用户（任意类型），拿到其登录 `token`。
+
+## 验证场景
+
+### 场景 1：首次开通 IM 账号（核心）
+
+**步骤**：
+1. 用测试用户 token 调用：
+   ```
+   POST http://localhost:8082/infouser/user/im/open
+   Header: token: <测试用户token>
+   ```
+2. 检查响应 `code==200`，`data.apiKey` 与 `data.imUserId` 非空。
+3. 查库确认：
+   ```sql
+   SELECT im_api_key, im_user_id FROM info_user WHERE user_id = <该用户id>;
+   ```
+   两列均已写入非空值，且 `im_user_id` 与响应 `data.imUserId` 一致。
+
+**预期**：成功返回凭证；库中两列成对写入。
+
+### 场景 2：幂等返回
+
+**步骤**：对**同一用户**再次调用 `POST /infouser/user/im/open`。
+
+**预期**：
+- 响应 `apiKey`/`imUserId` 与场景 1 完全一致。
+- IM 平台 extCreate **未被再次调用**（可通过日志/IM 侧确认账号创建次数仍为 1）。
+- 库中凭证不变。
+
+### 场景 3：未登录拒绝
+
+**步骤**：不带 token（或带失效 token）调用 `POST /infouser/user/im/open`。
+
+**预期**：返回未登录错误，不产生 IM 账号，库无写入。
+
+### 场景 4：IM 平台失败降级
+
+**步骤**：临时把 `im.ext-token` 改成错误值（或断网模拟 IM 不可达），重启后用新用户调用开通接口。
+
+**预期**：
+- 接口返回失败（IM 开通失败，可重试）。
+- 库中该用户 `im_api_key`/`im_user_id` 仍为 NULL（不写无效凭证）。
+- 恢复正确 token 后重试 → 成功（回到场景 1）。
+
+### 场景 5：全用户类型覆盖
+
+**步骤**：分别用普通用户(0)、商家(1)、骑手(2)、夜市(3) 的 token 调用开通接口。
+
+**预期**：四类用户均能成功开通（验证 FR-007 不按类型限制）。
+
+## 通过标准
+
+- 场景 1~5 全部符合预期。
+- 新老用户（im_api_key 原为空）都能通过同一接口开通（场景 1 即覆盖老用户补建）。
+- 注册流程未被改动（回归验证：注册接口行为与返回结构保持原样）。

specs/012-im-user-integration/research.md

@@ -0,0 +1,89 @@
+# Research: 骑手与用户 IM 即时沟通账号接入
+
+**Phase**: 0 | **Date**: 2026-06-23
+
+本文件记录实现该功能所需的关键技术决策、调研结论与备选方案。所有 NEEDS CLARIFICATION 已在 spec 阶段通过用户澄清解决，此处补充实现层面的取舍依据。
+
+## 决策 1：开通触发机制 —— APP 主动调用独立接口
+
+**Decision**: 不在用户注册流程内嵌 IM 开通；新增独立的 `POST /infouser/user/im/open` 接口，由 APP 在注册完成后（或首聊前）自行调用。
+
+**Rationale**: 用户明确要求"不改动用户创建过程"。独立接口解耦了注册与 IM 开通——注册保持稳定不被外部依赖（IM 平台）拖累；开通失败可由 APP 自由重试，不影响用户已注册状态。同时该接口天然服务存量用户补建（老用户首聊时 APP 调同一接口即可）。
+
+**Alternatives considered**:
+- 在 `insertInfoUser`/`saveOrUpdate` 注册成功后自动调用 IM：被用户否决（要求不改注册流程），且会让注册强依赖外部 IM 平台可用性。
+- 定时任务全量回填：运维成本高、实时性差，作为本期范围外的补充手段。
+
+## 决策 2：幂等策略 —— 凭证已存在则直接返回
+
+**Decision**: `openImAccount(userId)` 先查用户；若 `imApiKey` 非空，直接返回现有凭证，不再调用 IM 平台。
+
+**Rationale**: 防止 APP 重试/网络抖动导致同一用户重复调用 `extCreate` 产生多个 IM 账号。基于本地凭证判定，简单可靠，避免依赖 IM 平台侧的去重语义。
+
+**Alternatives considered**:
+- 每次都重新创建覆盖：会丢失历史 IM 账号、可能产生孤儿账号，不可接受。
+- 加分布式锁防并发：本期单机 + 本地判定已足够；若后续多实例可补充 Redis 锁，当前不过度设计。
+
+## 决策 3：imUserId 存储类型 —— BIGINT / Long
+
+**Decision**: `im_user_id` 数据库列用 `BIGINT`，Java 字段用 `Long`。
+
+**Rationale**: IM 平台返回示例 `userId: 2069305587785445400` 为 19 位整数，超出 `INT`（约 21 亿）和 JS 安全整数范围。Java `Long` 最大 9223372036854775807（19 位），可容纳。**注意**：JSON 序列化返回给 APP 时，19 位 Long 必须序列化为**字符串**，否则前端 JS 会精度丢失。本项目 `JwtUtil.setToken` 已有将 Long 转 String 的先例（`withClaim("id", String.valueOf(...))`）；返回 VO 的 `imUserId` 字段建议用 `String` 类型或加 `@JsonSerialize` ToStringSerializer，本期采用 **VO 中 imUserId 用 String** 的稳妥做法。
+
+**Alternatives considered**:
+- 数据库存 VARCHAR：丧失数值语义且无必要，BIGINT 更合理。
+- 返回数字不加处理：前端 JS 会精度丢失（2069305587785445400 → 2069305587785445…），不可接受。
+
+## 决策 4：HTTP 客户端 —— org.apache.http（仿 NewebPay）
+
+**Decision**: 使用项目已有的 `org.apache.http.client.HttpClients`（`HttpPost`），封装为 `@Component` 类 `ImClient`，参考 `com.ruoyi.app.utils.newebpay.NewebPay`。
+
+**Rationale**: 项目已统一使用 Apache HttpClient（见 `NewebPay.postFormRaw`），保持一致、无新依赖。IM `extCreate` 为 POST + Header 鉴权（非表单加密），实现比 NewebPay 更简单：构造 `HttpPost`，设 `extToken` 请求头，发送空体或最小体，解析 JSON 响应。
+
+**Alternatives considered**:
+- RestTemplate / WebClient：项目未引入，新增技术栈成本，无必要。
+- OkHttp：项目未用，不引入。
+
+## 决策 5：配置注入方式 —— @Value（仿 NewebPayPayController）
+
+**Decision**: 在 `ImClient` 内用 `@Value` 注入 `im.base-url`、`im.ext-token`、`im.create-path`、`im.timeout-ms`。
+
+**Rationale**: 与 `NewebPayPayController` 的 `@Value("${newebpay.base-url}")` 模式一致。IM 配置为全局单例（一个域名 + 一个平台级 extToken），直接注入组件即可，无需 `@ConfigurationProperties` 类（仅 2~4 个字段，@Value 更轻量）。
+
+**Alternatives considered**:
+- `@ConfigurationProperties` 绑定 POJO：字段少时反而啰嗦，本期不采用。
+- 硬编码：被需求明确禁止（域名/令牌须配置化）。
+
+## 决策 6：失败处理 —— 不写库、抛 ServiceException
+
+**Decision**: IM 平台返回 `code != 200`、网络异常或超时时，`ImClient` 抛异常 → service 不写库 → controller 经全局异常处理返回失败 `AjaxResult`，APP 可重试。
+
+**Rationale**: 保证不写入无效/部分凭证（如只拿到 userId 没 apiKey 的脏数据）。用户注册主流程不经过此接口，故失败仅影响开通本身，APP 重试即可。超时用 `RequestConfig.setConnectTimeout/SocketTimeout`（按配置 `im.timeout-ms`，默认 5000ms）控制。
+
+## 决策 7：用户身份识别 —— token 解析 userId
+
+**Decision**: 接口从 `request.getHeader("token")` 取 token，经 `new JwtUtil().getusid(token)` 解析 userId；为空则拒绝（返回未登录错误）。
+
+**Rationale**: 与 `NewebPayPayController`（行 121-129）完全一致的鉴权模式，复用现有 JwtUtil，不引入新鉴权方式。不接受 APP 传 userId 参数，防越权为他人开通。
+
+## 决策 8：响应 VO —— ImAccountVo
+
+**Decision**: 新建 `ImAccountVo`，含 `apiKey`(String)、`imUserId`(String) 两字段，作为开通接口的 data 返回。
+
+**Rationale**: APP 需要这两个值初始化 IM SDK。`imUserId` 用 String 规避前端精度问题（见决策 3）。
+
+## 决策 9：编排服务所处模块 —— ruoyi-admin（非 ruoyi-system）
+
+**Decision**: IM 开通编排服务 `ImAccountService` 放在 **ruoyi-admin**（`com.ruoyi.app.service`），而非原计划的 `ruoyi-system.InfoUserServiceImpl`。
+
+**Rationale**: 编译期发现模块依赖方向约束——`ruoyi-admin → ruoyi-system`（反向不可）。`ImClient` 依赖 httpclient **4.x + fastjson2**（仅 ruoyi-admin 有，仿 `NewebPay`；ruoyi-system 仅有 httpclient5 + fastjson1）。若把 `ImClient` 放进 ruoyi-system 需重写为 HC5+fastjson1，风险更高。因此把 `ImClient` 与编排服务 `ImAccountService` 同置于 ruoyi-admin，编排层注入 `IInfoUserService`（system，admin 可见）做用户读写，复用 `WalletService` 同款模式（`com.ruoyi.app.service` 中已有服务注入 `IInfoUserService` 的先例）。
+
+**Alternatives considered**:
+- `ImClient` 移入 ruoyi-system + 用 HC5/fastjson1 重写：技术债与重写风险高，弃。
+- 编排逻辑塞进 Controller：Controller 过厚，弃；改为独立 `ImAccountService` 保持分层。
+
+**对外契约不变**: `POST /infouser/user/im/open` 仍在 `InfoUserController`，请求/响应/行为与 `contracts/open-im-account.md` 完全一致，仅内部模块归属调整。
+
+## 结论
+
+所有实现层面决策已明确，无遗留 NEEDS CLARIFICATION。可进入 Phase 1（data-model / contracts / quickstart）。

specs/012-im-user-integration/spec.md

@@ -0,0 +1,106 @@
+# Feature Specification: 骑手与用户 IM 即时沟通账号接入
+
+**Feature Branch**: `012-im-user-integration`
+
+**Created**: 2026-06-23
+
+**Status**: Draft
+
+**Input**: User description: "骑手和用户沟通要使用 im 功能，我们需要调用 im 的功能，让 im 给我们创建用户；用户表绑定 im 创建用户返回的信息；创建用户调用方法 POST https://test-im.abtim-my.com/bot/extCreate，请求头带 extToken；返回 apiKey 与 userId；im 域名和 extToken 放到配置文件。用户创建过程不改动，APP 在用户创建完成后自己触发接口，后端再去调用 im 方法创建 im 账号。"
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - APP 触发开通 IM 账号 (Priority: P1)
+
+用户在平台注册完成后，APP 主动调用平台提供的「开通 IM 账号」接口。平台后端识别当前登录用户，向 IM 平台发起创建请求，将 IM 平台返回的 apiKey 与 userId 绑定保存到该用户记录中，并把这两个凭证返回给 APP，供 APP 初始化 IM SDK 进行即时沟通。
+
+**Why this priority**: 这是整个 IM 沟通能力的根基——没有 IM 账号就无法收发任何消息。它是 MVP 的核心切片，其他故事都依赖它。
+
+**Independent Test**: 可通过"以某用户身份调用开通接口 → 校验用户表 imApiKey / imUserId 已写入 → 校验接口返回了这两个凭证 → IM 平台确实存在该账号"独立验证，交付价值为"用户已具备 IM 身份并可直接聊天"。
+
+**Acceptance Scenarios**:
+
+1. **Given** 一个已登录、尚未开通 IM 账号的用户，**When** APP 调用「开通 IM 账号」接口，**Then** 平台成功调用 IM 平台创建账号，用户表 imApiKey / imUserId 被写入非空值，接口返回这两个凭证。
+2. **Given** IM 平台返回成功（code=200），**When** 平台处理响应，**Then** 仅从 data 节点取出 apiKey 与 userId 落库并返回。
+3. **Given** IM 平台临时不可用或返回失败，**When** APP 调用开通接口，**Then** 接口返回明确的失败信息（不写库），APP 可稍后重试。
+
+---
+
+### User Story 2 - 重复开通幂等返回 (Priority: P2)
+
+同一个用户多次调用「开通 IM 账号」接口时，平台不重复在 IM 平台创建账号，而是直接返回该用户已有的 IM 凭证，保证幂等，避免产生重复 IM 账号。
+
+**Why this priority**: 幂等是接口健壮性的核心保障，避免 APP 重试或网络抖动导致一个用户绑定多个 IM 账号；优先级仅次于首次开通。
+
+**Independent Test**: 可通过"对同一用户连续调用两次开通接口 → 确认 IM 平台只创建一次、返回的凭证一致"独立验证。
+
+**Acceptance Scenarios**:
+
+1. **Given** 某用户 imApiKey 已存在，**When** APP 再次调用开通接口，**Then** 平台直接返回现有凭证，不再次调用 IM 平台创建。
+2. **Given** APP 因网络问题重复提交，**When** 并发或连续到达，**Then** 该用户最终只拥有一组 IM 凭证。
+
+---
+
+### User Story 3 - IM 配置集中管理 (Priority: P3)
+
+IM 平台的访问域名与鉴权令牌（extToken）集中存放于系统配置文件中，由配置统一管理，代码中不硬编码任何 IM 域名或令牌，便于测试环境与正式环境切换。
+
+**Why this priority**: 支撑性需求，是 P1/P2 正确、安全运行的前提，但属于工程化而非用户可见功能。
+
+**Independent Test**: 可通过"修改配置文件中的域名/令牌 → 重启 → 确认调用指向新地址"独立验证。
+
+**Acceptance Scenarios**:
+
+1. **Given** 配置文件已配置 IM 域名与 extToken，**When** 系统启动，**Then** 平台读取并使用配置值调用 IM 平台，代码内不出现硬编码域名或令牌。
+2. **Given** 需要从测试环境切换到正式环境，**When** 仅修改配置文件，**Then** 无需改动代码即可完成切换。
+
+---
+
+### Edge Cases
+
+- IM 平台返回 userId 超出普通整数范围（如 19 位长整型）时，存储字段类型如何避免精度丢失？
+- APP 短时间内多次请求开通接口时，系统如何保证幂等（不重复创建、不覆盖已有有效账号）？
+- IM 平台返回 code 非 200（鉴权失败 / 限流 / 服务异常）时，系统如何明确返回失败，便于 APP 重试？
+- IM 平台调用超时（如 > 5 秒）时，是否阻塞接口响应？超时阈值与重试策略是什么？
+- extToken 泄露或过期，系统如何感知与处理？
+- 未登录或 token 失效调用开通接口，系统应拒绝（不产生账号）。
+- 用户删除后，IM 账号是否需要同步注销？（本期范围外，仅记录）
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: 系统 MUST 提供一个独立的「开通 IM 账号」接口，供 APP 在用户注册完成后（或首次需要沟通时）主动调用；用户注册主流程保持不变，不在注册环节内嵌 IM 开通。
+- **FR-002**: 系统 MUST 通过当前登录 token 解析出 userId 来识别要开通的用户，不接受由 APP 显式传入 userId（防止越权为他人开通）。
+- **FR-003**: 系统 MUST 调用 IM 平台创建账号（POST {IM域名}/bot/extCreate，请求头带 extToken），将 IM 平台返回的 apiKey 与 userId 绑定保存到用户表对应字段。
+- **FR-004**: 系统 MUST 通过请求头 `extToken` 携带鉴权令牌，令牌值与 IM 域名均从配置文件读取，代码中不硬编码。
+- **FR-005**: 系统 MUST 正确解析 IM 平台返回结构（外层 code/message，内层 data 含 apiKey/userId），仅取 data 节点落库。
+- **FR-006**: 系统 MUST 在开通成功后将 apiKey 与 imUserId 返回给 APP，供 APP 初始化 IM SDK。
+- **FR-007**: 接口 MUST 对所有用户类型开放（普通用户 0 / 商家 1 / 骑手 2 / 夜市 3），由 APP 决定调用方；后端不按用户类型限制。
+- **FR-008**: 系统 MUST 保证幂等——当目标用户已存在 IM 凭证（imApiKey 非空）时，直接返回现有凭证，不再调用 IM 平台创建。
+- **FR-009**: 当 IM 平台不可用、返回失败或调用超时时，系统 MUST 返回明确的失败结果，且不在用户表写入无效凭证。
+
+### Key Entities *(include if feature involves data)*
+
+- **InfoUser（用户信息）**: 平台已有用户表。本期新增两个 IM 凭证字段：imApiKey（IM 平台返回的 API 密钥，字符串）与 imUserId（IM 平台返回的用户ID，长整型 BIGINT）。一个用户对应一组 IM 凭证。
+- **IM 平台外部账号**: 由 IM 平台管理，通过 extCreate 接口创建，对平台而言是不可变的对外凭证，以 apiKey+userId 形式回传绑定。
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 100% 的「开通 IM 账号」接口调用（IM 平台可用时）成功为用户写入并返回 IM 凭证。
+- **SC-002**: 对同一用户重复调用开通接口，IM 平台账号创建次数为 1，重复请求 100% 命中幂等返回。
+- **SC-003**: 未登录或 token 失效调用开通接口时，100% 被拒绝，不产生任何 IM 账号或写库。
+- **SC-004**: IM 创建请求平均耗时控制在可接受范围，接口响应不被显著拖慢（如额外开销 < 1 秒）。
+- **SC-005**: 测试环境与正式环境的 IM 域名/令牌切换，仅需修改配置文件，零代码改动。
+
+## Assumptions
+
+- 用户注册主流程（骑手注册、商家注册、普通用户注册/登录即注册）保持原样，本期完全不动注册相关代码，仅在注册完成后由 APP 自行调用开通接口。
+- IM 平台创建账号接口（extCreate）对同一外部用户具备可接受的重复请求处理；系统侧额外通过「凭证已存在则直接返回」做幂等保护。
+- IM 平台返回的 userId 为长整型，存储字段按 BIGINT 设计以避免精度丢失。
+- extToken 为平台级共享令牌（非单用户级），所有创建请求共用同一令牌。
+- 接口通过项目现有登录鉴权机制识别当前用户（解析 token → userId），不新增鉴权方式。
+- 配置文件采用项目现有 application.yml 风格（参考 ezpay / newebpay 段），新增独立 im 配置段。
+- HTTP 客户端沿用项目现有 org.apache.http 用法（参考 NewebPay 工具类）。

specs/012-im-user-integration/tasks.md

@@ -0,0 +1,150 @@
+---
+
+description: "Task list for 骑手与用户 IM 即时沟通账号接入"
+---
+
+# Tasks: 骑手与用户 IM 即时沟通账号接入
+
+**Input**: Design documents from `/specs/012-im-user-integration/`
+
+**Prerequisites**: plan.md ✅, spec.md ✅, research.md ✅, data-model.md ✅, contracts/ ✅, quickstart.md ✅
+
+**Tests**: 项目无自动化测试约定，不生成测试任务；验证通过 quickstart.md 手动场景完成。
+
+**Organization**: 按用户故事分组。注意：本特性 3 个故事围绕同一接口，存在依赖（US3 配置→US1 接口→US2 幂等），按依赖顺序排列。
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: 可并行（不同文件、无未完成依赖）
+- **[Story]**: 所属用户故事（US1/US2/US3）
+- 描述含确切文件路径
+
+---
+
+## Phase 1: Setup（数据库变更）
+
+**Purpose**: info_user 表新增 IM 凭证两列
+
+- [x] T001 在 `updatesql/sql.md` 追加 info_user 加列 SQL：`ALTER TABLE info_user ADD COLUMN im_api_key VARCHAR(64) DEFAULT NULL COMMENT 'IM平台API密钥';` 与 `ALTER TABLE info_user ADD COLUMN im_user_id BIGINT DEFAULT NULL COMMENT 'IM平台用户ID';`（标注日期 2026-06-23 与用途，不直接执行）
+
+---
+
+## Phase 2: Foundational（阻塞前置，所有故事依赖）
+
+**Purpose**: 实体字段、映射、配置、外部客户端、返回 VO —— 用户故事开始前必须就绪
+
+**⚠️ CRITICAL**: 本相位完成前不得开始用户故事
+
+- [x] T002 [P] `ruoyi-system/src/main/java/com/ruoyi/system/domain/InfoUser.java`：新增 `imApiKey`(String) 与 `imUserId`(Long) 两字段（带 `@Excel` 注解与注释，IM apiKey / IM userId）；该类用 Lombok `@Data` 自动生成 getter/setter
+- [x] T003 [P] `ruoyi-system/src/main/resources/mapper/infouser/InfoUserMapper.xml`：在 `InfoUserResult` resultMap 追加 `<result property="imApiKey" column="im_api_key"/>` 与 `<result property="imUserId" column="im_user_id"/>`（`selectInfoUserVo` 为 select *，无需改 SQL）
+- [x] T004 [P] `ruoyi-system/src/main/java/com/ruoyi/system/domain/vo/ImAccountVo.java`：新建返回 VO，含 `apiKey`(String) 与 `imUserId`(**String**，规避前端 Long 精度丢失)；用 `@Data`
+- [x] T005 [P] `ruoyi-admin/src/main/resources/application.yml`：新增 `im` 配置段（base-url / ext-token / create-path / timeout-ms），测试值 base-url=`https://test-im.abtim-my.com`、ext-token=`92a88467-6eca-11f1-9dd5-00163e1eec55`、create-path=`/bot/extCreate`、timeout-ms=`5000`（参考现有 ezpay/newebpay 段风格）【满足 US3 配置集中管理】
+- [x] T006 [P] `ruoyi-admin/src/main/java/com/ruoyi/app/utils/im/ImClient.java`：新建 `@Component`，`@Value` 注入 `im.base-url`/`im.ext-token`/`im.create-path`/`im.timeout-ms`；方法 `ImAccountVo createAccount()` 用 `org.apache.http`（仿 `NewebPay.postFormRaw`）发 `POST {base-url}{create-path}`，请求头带 `extToken`，设连接/读取超时，解析 fastjson2 响应：`code==200 && data.apiKey/userId 非空` → 填充 VO（imUserId 转 String）；否则抛 `ServiceException`【满足 US3 配置注入】
+
+**Checkpoint**: 数据层 + 外部 IM 客户端就绪，可开始用户故事
+
+---
+
+## Phase 3: User Story 1 - APP 触发开通 IM 账号 (Priority: P1) 🎯 MVP
+
+**Goal**: APP 调用 `POST /infouser/user/im/open`，为当前登录用户首次开通 IM 账号并返回凭证
+
+**Independent Test**: 以未开通用户 token 调用接口 → 返回 apiKey/imUserId 且库中两列成对写入（见 quickstart 场景1）
+
+### Implementation for User Story 1
+
+- [x] T007 [US1] `ruoyi-system/src/main/java/com/ruoyi/system/service/IInfoUserService.java`：新增方法签名 `ImAccountVo openImAccount(Long userId);`
+- [x] T008 [US1] `ruoyi-system/src/main/java/com/ruoyi/system/service/impl/InfoUserServiceImpl.java`：注入 `ImClient`；实现 `openImAccount` **首次开通**逻辑：`getById(userId)` → （本期暂不做幂等分支，留 US2）→ `imClient.createAccount()` 取 VO → `updateById` 把 apiKey/imUserId 写回用户（成对）→ 返回 VO（注意 imUserId 落库为 Long，VO 用 String）。失败时 ImClient 已抛异常，本层不写库
+- [x] T009 [US1] `ruoyi-admin/src/main/java/com/ruoyi/app/user/InfoUserController.java`：新增 `@PostMapping("/im/open")`（复用现有 `JwtUtil`/`request`，仿 NewebPayPayController 行121-129）：从 `request.getHeader("token")` 经 `new JwtUtil().getusid(token)` 解析 userId；为空返回未登录错误；否则调 `infoUserService.openImAccount(userId)`，用 `AjaxResult.success(data)` 返回 VO
+
+**Checkpoint**: User Story 1 完整可用 —— 首次开通端到端跑通（幂等性暂缺，由 US2 补齐）
+
+---
+
+## Phase 4: User Story 2 - 重复开通幂等返回 (Priority: P2)
+
+**Goal**: 同一用户重复调用开通接口时，直接返回已有凭证，不重复调用 IM 平台
+
+**Independent Test**: 同一用户连调两次 → 返回凭证一致，IM 侧仅创建一次（见 quickstart 场景2）
+
+### Implementation for User Story 2
+
+- [x] T010 [US2] `ruoyi-system/src/main/java/com/ruoyi/system/service/impl/InfoUserServiceImpl.java`：在 `openImAccount` 开头增加幂等分支——`getById(userId)` 后若 `imApiKey` 非空（已有凭证），直接组装并返回现有 VO（`imUserId` 转 String），**不再调用** `imClient.createAccount()`；否则走 T008 首次开通逻辑
+
+**Checkpoint**: 幂等生效，重复调用安全
+
+---
+
+## Phase 5: User Story 3 - IM 配置集中管理 (Priority: P3)
+
+**Goal**: IM 域名与 extToken 全部来自配置文件，代码无硬编码，环境切换零改码
+
+**Independent Test**: 改 yml 域名/令牌 → 重启 → 调用指向新地址（见 quickstart 场景4 间接验证）
+
+> 实现：US3 由 Foundational T005（yml 配置段）+ T006（@Value 注入）已交付。本相位为合规验证。
+
+- [x] T011 [US3] 验证：grep 确认 `ImClient.java` 与全工程无硬编码 IM 域名（`test-im.abtim-my.com`）或 extToken 明文，均经 `@Value("${im.*}")` 读取；确认 yml 测试/正式环境可仅改配置切换
+
+**Checkpoint**: 配置集中管理达标
+
+---
+
+## Phase 6: Polish & Cross-Cutting Concerns
+
+**Purpose**: 跨故事质量与端到端验证
+
+- [x] T012 [P] 精度复核：确认 `ImAccountVo.imUserId` 为 String，且 controller 返回 JSON 中 imUserId 为字符串（19 位不丢精度）；确认 `InfoUser.imUserId` 落库为 Long/BIGINT 不溢出
+- [ ] T013 [P] 按 `specs/012-im-user-integration/quickstart.md` 执行场景 1~5 全部验证并记录结果
+- [x] T014 [P] 回归确认：用户注册相关接口（骑手/商家/普通用户注册）行为与返回结构未被改动
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: 无依赖，立即开始（T001 仅写 SQL 文件，不执行）
+- **Foundational (Phase 2)**: T002~T006 可并行（不同文件）；本相位阻塞所有用户故事
+- **US1 (Phase 3)**: 依赖 Foundational；内部 T007→T008→T009（接口→实现→控制器）
+- **US2 (Phase 4)**: 依赖 US1 的 T008（在已有 service 方法上加幂等分支）
+- **US3 (Phase 5)**: 实现已在 Foundational T005/T006；T011 仅验证
+- **Polish (Phase 6)**: 依赖全部用户故事完成
+
+### Within Each User Story
+
+- 接口签名 → 实现 → 控制器（US1）
+- 幂等分支在首次开通逻辑就绪后追加（US2 依赖 US1）
+
+### Parallel Opportunities
+
+- Foundational T002 / T003 / T004 / T005 / T006 可全部并行（不同文件）
+- Polish T012 / T013 / T014 可并行
+
+---
+
+## Implementation Strategy
+
+### MVP First（仅 User Story 1）
+
+1. Phase 1：写 SQL（T001）
+2. Phase 2：字段+映射+VO+配置+ImClient（T002~T006）
+3. Phase 3：service+controller 首次开通（T007~T009）
+4. **STOP 验证**：quickstart 场景1（首次开通）+ 场景5（全类型）
+5. 可联调交付
+
+### Incremental Delivery
+
+1. Foundational → 基础就绪
+2. +US1 → 首次开通可用（MVP）
+3. +US2 → 重复调用幂等（健壮性）
+4. +US3 验证 → 配置合规
+5. Polish → 精度/回归/全场景
+
+---
+
+## Notes
+
+- 数据库变更只写 `updatesql/sql.md`，不直接执行（项目规范）
+- `imUserId` 在 VO 中用 String，落库用 Long/BIGINT（防前端 JS 精度丢失 + 容纳 19 位）
+- 复用现有 `JwtUtil.getusid(token)` 解析用户，不新增鉴权方式
+- 不改动注册流程（用户明确要求）

updatesql/sql.md

@@ -249,3 +249,87 @@ VALUES ('重新开票', @invMenuId, 2, '#', '', 'F', '0', '0', 'chanting:orderIn
 INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, menu_type, visible, status, perms, icon, create_by, create_time)
 VALUES ('作废发票', @invMenuId, 3, '#', '', 'F', '0', '0', 'chanting:orderInvoice:invalid', '#', 'admin', NOW());
 ```
+
+
+```sql
+-- ============================================================
+-- 2026-06-22 蓝新金流(NewebPay)线上支付接入 (specs/011-newebpay-payment)
+-- ============================================================
+
+-- 1. 门店蓝新支付凭证表（与 pos_store 1:1，复用 009 pos_store_ezpay 状态机模式）
+CREATE TABLE pos_store_newebpay (
+  id BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',
+  store_id BIGINT NOT NULL COMMENT '关联 pos_store.id(门店)',
+  newebpay_status INT NOT NULL DEFAULT 0 COMMENT '申请状态:0未申请/1申请中/2已开通',
+  is_enabled INT NOT NULL DEFAULT 1 COMMENT '启用开关:0停用/1启用',
+  merchant_id VARCHAR(15) DEFAULT NULL COMMENT '蓝新商店代号 MerchantID',
+  hash_key VARCHAR(64) DEFAULT NULL COMMENT '蓝新 HashKey(32字节)',
+  hash_iv VARCHAR(32) DEFAULT NULL COMMENT '蓝新 HashIV(16字节)',
+  enabled_payments VARCHAR(50) DEFAULT 'CREDIT' COMMENT '启用支付方式:CREDIT,LINEPAY,APPLEPAY',
+  apply_time DATETIME DEFAULT NULL COMMENT '申请时间',
+  approved_time DATETIME DEFAULT NULL COMMENT '开通时间',
+  last_verify_result VARCHAR(240) DEFAULT NULL COMMENT '最近验证结果',
+  remark VARCHAR(255) DEFAULT NULL COMMENT '备注',
+  create_time DATETIME DEFAULT NULL COMMENT '创建时间',
+  update_time DATETIME DEFAULT NULL COMMENT '更新时间',
+  create_by VARCHAR(64) DEFAULT NULL COMMENT '创建人',
+  update_by VARCHAR(64) DEFAULT NULL COMMENT '更新人',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_store_id (store_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='门店蓝新金流支付凭证';
+
+-- 2. 支付交易流水表（每笔蓝新交易一条，按 trade_no 幂等）
+CREATE TABLE pos_order_payment (
+  id BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',
+  dd_id VARCHAR(64) NOT NULL COMMENT '系统订单号(关联 pos_order.dd_id)',
+  merchant_order_no VARCHAR(30) NOT NULL COMMENT '商店订单号 MerchantOrderNo',
+  trade_no VARCHAR(20) DEFAULT NULL COMMENT '蓝新交易序号 TradeNo(幂等键)',
+  store_id BIGINT DEFAULT NULL COMMENT '门店ID',
+  merchant_id VARCHAR(15) DEFAULT NULL COMMENT '蓝新商店代号',
+  pay_type VARCHAR(20) DEFAULT NULL COMMENT '支付方式:CREDIT/LINEPAY/APPLEPAY',
+  amount INT DEFAULT NULL COMMENT '交易金额(整数元)',
+  pay_status INT NOT NULL DEFAULT 0 COMMENT '支付状态:0未支付/1已支付/2失败',
+  auth_code VARCHAR(20) DEFAULT NULL COMMENT '授权码',
+  pay_time DATETIME DEFAULT NULL COMMENT '支付完成时间',
+  callback_raw TEXT COMMENT '回调原始解密结果',
+  create_time DATETIME DEFAULT NULL COMMENT '创建时间',
+  update_time DATETIME DEFAULT NULL COMMENT '更新时间',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_trade_no (trade_no),
+  KEY idx_dd_id (dd_id),
+  KEY idx_merchant_order_no (merchant_order_no)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='蓝新支付交易流水';
+```
+
+
+```sql
+-- 3. 平台后台菜单：门店蓝新支付开通管理（挂在门店菜单同级父节点下，参考 009/010 写法）
+INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, menu_type, visible, status, perms, icon, create_by, create_time, remark)
+SELECT '门店蓝新支付', parent_id, 9, 'storeNewebpay', 'mendian/storeNewebpay/index', 'C', '0', '0', 'chanting:storeNewebpay:list', 'money', 'admin', NOW(), '门店蓝新金流支付凭证开通管理'
+FROM sys_menu WHERE perms = 'chanting:store:list' LIMIT 1;
+
+-- 按钮权限
+SET @nbMenuId = (SELECT menu_id FROM sys_menu WHERE perms = 'chanting:storeNewebpay:list' LIMIT 1);
+INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, menu_type, visible, status, perms, icon, create_by, create_time)
+VALUES ('门店详情',   @nbMenuId, 1, '#', '', 'F', '0', '0', 'chanting:storeNewebpay:query',           '#', 'admin', NOW());
+INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, menu_type, visible, status, perms, icon, create_by, create_time)
+VALUES ('发起申请',   @nbMenuId, 2, '#', '', 'F', '0', '0', 'chanting:storeNewebpay:apply',            '#', 'admin', NOW());
+INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, menu_type, visible, status, perms, icon, create_by, create_time)
+VALUES ('录入凭证',   @nbMenuId, 3, '#', '', 'F', '0', '0', 'chanting:storeNewebpay:saveCredentials', '#', 'admin', NOW());
+INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, menu_type, visible, status, perms, icon, create_by, create_time)
+VALUES ('停用恢复',   @nbMenuId, 4, '#', '', 'F', '0', '0', 'chanting:storeNewebpay:toggleEnable',    '#', 'admin', NOW());
+```
+
+```sql
+-- 2026-06-22 发票凭证字段补全（invoice_url 改名 + 新增 3 个码值列，保留原数据）
+ALTER TABLE pos_order_invoice CHANGE COLUMN invoice_url invoice_trans_no VARCHAR(64) DEFAULT NULL COMMENT 'ezPay 交易流水号 InvoiceTransNo';
+ALTER TABLE pos_order_invoice ADD COLUMN invoice_bar_code VARCHAR(255) DEFAULT NULL COMMENT '发票条码码值(PrintFlag=Y 才有)';
+ALTER TABLE pos_order_invoice ADD COLUMN invoice_qrcode_l VARCHAR(255) DEFAULT NULL COMMENT '发票左二维码码值(PrintFlag=Y 才有)';
+ALTER TABLE pos_order_invoice ADD COLUMN invoice_qrcode_r VARCHAR(255) DEFAULT NULL COMMENT '发票右二维码码值(PrintFlag=Y 才有)';
+```
+
+```sql
+-- 2026-06-23 IM 即时沟通账号接入（012-im-user-integration）：info_user 新增 IM 凭证两列
+ALTER TABLE info_user ADD COLUMN im_api_key VARCHAR(64) DEFAULT NULL COMMENT 'IM平台API密钥(extCreate返回)';
+ALTER TABLE info_user ADD COLUMN im_user_id BIGINT DEFAULT NULL COMMENT 'IM平台用户ID(extCreate返回)';
+```