档案软件按次付费功能从零搭建到上线全流程实操技术指南

前置准备

1. 环境依赖准备

需提前安装Node.js 16.20.0版本，下载地址：https://nodejs.org/zh-cn/download/releases/，确保npm可用。所需依赖可直接执行以下命令安装：

```bash 后端依赖安装（Koa2框架） npm install koa@2.14.2 koa-router@12.0.0 koa-bodyparser@4.4.1 wechatpay-node-v3@2.1.3 alipay-sdk@3.1.1 前端依赖安装（Vue3框架通用） npm install axios@1.4.0 qrcode@1.5.3 ```

支付渠道测试可直接用官方沙箱环境，微信支付沙箱地址：https://pay.weixin.qq.com/wiki/doc/apiv3/open/pay/chapter1_1_1.shtml，支付宝沙箱地址：https://open.alipay.com/develop/sandbox/app

2. 核心资源提前配置

• 支付渠道参数：微信支付V3商户ID、APIv3密钥、证书序列号、私钥；支付宝APPID、应用私钥、公钥
• 按次付费场景定义：提前给每个档案操作分配唯一scene_id，比如上传（upload_001）、解密（decrypt_002）、批量导出（export_003）
• 前端预留DOM：在档案操作按钮对应的页面，提前预留支付弹窗的挂载节点

第一步：后端按次计费逻辑开发

1. 支付配置文件编写

新建config/pay.js文件，完整配置如下，直接替换自己的参数即可使用：

```javascript module.exports = { wxPay: { mchid: '你的微信商户号', appid: '你的公众号/小程序APPID', apiV3Key: '你的APIv3密钥', certSerialNo: '你的证书序列号', privateKey: `--BEGIN PRIVATE KEY-- 你的微信支付私钥完整内容 --END PRIVATE KEY--`, notifyUrl: 'https://你的域名/api/pay/wx/notify' }, aliPay: { appId: '你的支付宝应用ID', privateKey: '你的支付宝应用私钥', publicKey: '你的支付宝公钥', notifyUrl: 'https://你的域名/api/pay/ali/notify' }, // 按次付费场景定价，单位为分，避免浮点数精度问题 scenePrice: { upload_001: 100, // 1元/次上传 decrypt_002: 200, // 2元/次解密 export_003: 500 // 5元/次导出 } } ```

2. 下单接口开发

新建路由router.post('/api/pay/create-order')，核心逻辑如下：

• 校验用户登录态，获取用户ID
• 校验请求参数中的scene_id是否在scenePrice配置中，非法则直接返回错误
• 生成全局唯一订单号，规则推荐：时间戳+6位随机数+用户ID后4位，避免重复
• 订单数据存入数据库，状态设为0（待支付），字段包含订单号、用户ID、场景ID、金额、支付类型、创建时间
• 调用对应支付渠道的下单接口，返回支付参数给前端

注意：订单表需给order_no字段添加唯一索引，避免重复订单生成

3. 支付回调接口开发

• 先校验支付渠道的签名，未通过校验直接返回错误，禁止未校验直接修改订单状态
• 解析回调参数获取订单号，查询数据库中对应订单的状态
• 如果订单状态为待支付，将状态改为1（已支付），同时给用户的付费次数表新增对应场景的1次使用权限
• 返回支付渠道要求的成功应答，避免重复回调

第二步：前端按次付费交互开发

1. 操作前校验逻辑

用户点击档案操作按钮时，先调用后端接口/api/pay/check-count，参数携带scene_id，查询用户当前场景的剩余次数：

• 剩余次数>0：直接放行执行操作，调用后端扣减接口次数减1
• 剩余次数=0：触发支付弹窗，展示对应场景的价格和支付选项

2. 支付弹窗核心代码

Vue3环境下可直接复制以下代码使用：

```vue ```

注意：所有金额展示都要除以100，避免把分作为元展示给用户

第三步：测试与上线验证

1. 本地测试流程

• 本地测试回调需要公网地址，可使用ngrok内网穿透，下载地址：https://ngrok.com/，执行命令ngrok http 3000（3000为后端端口），将生成的https域名替换配置中的notifyUrl域名即可
• 使用沙箱环境模拟支付，验证订单状态是否更新、次数是否到账、操作是否正常放行
• 测试异常场景：取消支付、支付超时、重复回调，验证后端不会出现重复加次数、订单状态错误的问题

2. 上线注意事项

• 回调地址必须为HTTPS，免费SSL证书可从https://letsencrypt.org/ 申请
• 支付私钥、密钥不要硬编码到代码中，上线时用服务器环境变量注入，避免泄露
• 服务器防火墙需放开支付渠道的IP段，微信IP段：https://pay.weixin.qq.com/wiki/doc/apiv3/wechatpay/wechatpay4_1.shtml，支付宝IP段：https://opendocs.alipay.com/open/01faw0

常见问题排查

• 支付回调无响应：先检查回调地址是否公网可访问，再检查防火墙是否拦截了支付渠道的IP
• 支付成功后不触发操作：检查轮询接口是否跨域，或者订单状态更新是否有延迟
• 金额显示错误：确认全链路所有金额计算都以分为单位，禁止使用浮点数存储金额