前端对接变更说明

变更日期：2026-06-30
关联需求：支付渠道切换与重复支付追溯、邀请链接直接下载、邀请文案调整

一、变更范围概览

本次后端改动涉及三大模块：

支付模块：支持订单详情页切换支付渠道，15 分钟内原渠道二维码仍有效；多渠道重复支付时以首笔成功渠道为准，其余渠道记录备查。
邀请模块：邀请链接 /api/invite/{code} 改为直接下载（302 重定向到安装包），删除独立下载接口 /api/invite/{code}/download。
数据库：新增 wechat_nickname、paid_channel 字段及 t_payment_order_extra_payment 重复支付记录表。

二、后端接口变更清单

2.1 邀请模块

接口	变更前	变更后
`GET /api/invite/{code}`	302 重定向到安装包 URL	服务端流式返回安装包二进制，浏览器自动下载
`GET /api/invite/{code}/download`	下载接口	已删除

响应行为：

服务端根据 User-Agent 自动判断系统类型（Windows x64 / macOS ARM64）。
返回 Content-Type: application/octet-stream 和 Content-Disposition: attachment; filename="..."。
从本地 invite.download-base-path 配置目录读取安装包文件写入响应流，不再暴露真实文件 URL。

2.2 支付模块

新增接口：切换支付渠道

POST /api/payment/order/{orderNo}/switch-channel
Content-Type: application/json

{
  "channel": "ALIPAY"   // 可选值：WECHAT / ALIPAY
}

说明：

用于订单详情页切换支付方式。
不关闭原渠道订单，原渠道二维码 15 分钟内仍有效。
返回新渠道的支付二维码 qrCodeBaseUrl / qrCodeBase64 / payUrl。

已有接口：查询订单

GET /api/payment/order/{orderNo}

变更说明：

待支付订单会返回当前渠道二维码字段，前端可直接展示扫码支付。
关键返回字段：
- qrCodeBase64：Base64 图片二维码
- payUrl：支付链接（支付宝等可用）
- channel：当前订单渠道
- expireHint：过期提示文案

回调逻辑变更

第一个支付成功渠道写入 paidChannel。
若同一订单在另一个渠道也支付成功，后端记录到 t_payment_order_extra_payment，但不重复激活会员。
前端正常展示"支付成功"即可，无需额外处理。

三、前端必须修改的内容

3.1 邀请链接直接下载（高优先级）

删除旧调用：

GET /api/invite/{code}/download

改为：

GET /api/invite/{code}

实现建议：

H5/小程序/Web：使用 <a href="/api/invite/{code}" download> 或 window.open('/api/invite/{code}')。
桌面端：直接访问该 URL，浏览器自动处理下载。
落地页中的"下载 APP / Windows 客户端"按钮，URL 使用后端返回的 appDownloadUrl（当前等于邀请链接本身）。
注意：inviteLink 和 downloadUrl 现在统一为 https://priceapi.kailin.com.cn/api/invite/{code}（含 /api 路径），之前生成的 /invite/{code} 已修复。

3.2 邀请分享文案（高优先级）

文案来源：

使用 /api/invite/code 接口返回的 copyText 字段，不要在前端硬编码。

文案格式示例：

我是Evan，在这里发现了一个药店采购神器——智价云！它聚合比价功能特别方便，能快速查到最低价，帮你节省采购成本。填我的邀请码 2XKADABS 完成注册，你也会获得会员权益！下载链接https://priceapi.kailin.com.cn/api/invite/C6GZJEU4

兜底展示名规则：

后端已处理，优先级为：微信昵称 > 用户昵称 > 手机尾号（如"手机尾号6688"）> "一位药店用户"。

3.3 支付订单详情页新增"切换支付渠道"（高优先级）

新增交互：

在订单详情页增加"切换为微信支付" / "切换为支付宝支付"按钮。

点击后调用：

POST /api/payment/order/{orderNo}/switch-channel

请求体：

{
  "channel": "WECHAT"
}

前端处理：

调用成功后，重新展示新渠道的二维码。
提示用户："已切换支付方式，请使用新二维码完成支付。原二维码 15 分钟内仍有效。"
不要在前端主动关闭或禁用原二维码的展示（如果已展示）。

3.4 查询订单二维码展示（中优先级）

待支付订单详情需要展示二维码：

{
  "qrCodeBase64": "data:image/png;base64,iVBORw0KGgo...",
  "payUrl": "https://qr.alipay.com/...",
  "channel": "ALIPAY",
  "expireHint": "请在15分钟内完成支付"
}

微信支付：展示 qrCodeBase64 图片。
支付宝支付：可展示 qrCodeBase64，或提供"打开支付宝"按钮使用 payUrl。

3.5 落地页字段调整（中优先级）

appDownloadUrl 现在就是 /api/invite/{code}。
落地页点击下载按钮直接访问该 URL 即可，无需拼接 /download。
downloadUrl 字段与 inviteLink 一致。

四、前端无需改动但需知悉

项	说明
会员激活	仍以第一个支付成功渠道为准
重复支付	第二个渠道支付只记录，不重复激活会员，前端正常展示成功即可
订单过期	15 分钟未支付自动过期，过期后切换渠道会失败
支付宝支付	当前仅保留扫码模式（`alipay.trade.precreate`）
微信支付	Native API v3，返回 Base64 二维码

五、本地测试指引

启动网关服务。
访问测试页面：http://localhost:{port}/invite-test.html
在"支付模块"中找到：
- 创建支付订单
- 查询订单
- 切换支付渠道
在"邀请模块"中找到：
- 邀请链接入口（直接下载）
- 获取邀请码

六、数据库上线注意

已有环境需要执行 zhijiayun-gateway/src/main/resources/db/migration-v5.sql，主要变更：

-- t_user 新增微信昵称字段
ALTER TABLE `t_user` ADD COLUMN `wechat_nickname` VARCHAR(128) DEFAULT NULL COMMENT '微信昵称';

-- t_payment_order 新增实际支付渠道字段
ALTER TABLE `t_payment_order` ADD COLUMN `paid_channel` VARCHAR(20) DEFAULT NULL COMMENT '实际支付渠道';

-- 新增重复支付记录表
CREATE TABLE `t_payment_order_extra_payment` (...);

七、安装包部署路径

流式下载会从 invite.download-base-path 配置目录直接读取安装包文件。

生产环境默认：

/app/zhijiayun/downloads/desktop-updates/

需要放入：

智价云-x64.exe
智价云-arm64.dmg

中文文件名已通过 Content-Disposition: filename*=UTF-8''... 编码，兼容主流浏览器。

八、变更文件列表

文件	变更类型	说明
`zhijiayun-invite/.../InviteController.java`	修改	`/api/invite/{code}` 改为服务端流式下载，删除 `/download` 接口
`zhijiayun-invite/.../InviteService.java`	修改	邀请文案、下载链接（含 `/api` 路径修正）、展示名优先级调整、流式下载文件读取
`zhijiayun-payment/.../PaymentOrder.java`	修改	新增 `paidChannel` 字段
`zhijiayun-payment/.../PaymentOrderExtraPayment.java`	新增	重复支付记录实体
`zhijiayun-payment/.../PaymentOrderExtraPaymentMapper.java`	新增	重复支付记录 Mapper
`zhijiayun-payment/.../PaymentOrderService.java`	修改	渠道切换、重复支付处理
`zhijiayun-payment/.../PaymentCallbackController.java`	修改	回调传递 `paidChannel`
`zhijiayun-gateway/.../db/schema.sql`	修改	新增字段和表
`zhijiayun-gateway/.../db/migration-v5.sql`	新增	已有环境幂等升级脚本
`zhijiayun-test/.../invite-test.html`	修改	测试页面同步新增/调整接口说明
`zhijiayun-gateway/.../application-dev.yml`	修改	新增 invite 下载文件路径配置
`zhijiayun-gateway/.../application-prod.yml`	修改	新增 invite 下载文件路径配置

前端对接变更说明-2026-06-30.md 8.0 KB Historia Raaka