积分与支付

Nexus 内置「积分」计费模型与真实支付能力，适配按量计费的 AI 产品：用户充值获得积分，调用 AI 生成、下载资源等消耗积分，全程流水可审计。

积分体系

概念	说明
积分账户	每个用户一个积分余额
充值	通过微信 / 支付宝购买积分（生成充值订单）
消费	调用 AI 生成、下载等按规则扣减积分
流水审计	每笔增减记录到 credit_transactions，可追溯
奖励	注册奖励、签到奖励（欢迎礼包）

数据模型见 server/database/migrations：0007_credit_system、0008_credit_transactions_idx、0019_recharge_orders、0020_recharge_orders_expires、0025_welcome_bonus。

支付能力

渠道	方式	实现
微信支付	Native 扫码	server/utils/payments/wechat.ts（wxpay-node-v3）
支付宝	电脑网站支付	server/utils/payments/alipay.ts（alipay-sdk）
Mock	本地联调	server/utils/payments/mock.ts

商户密钥（微信 / 支付宝）在 .env 自持，不进数据库、不进 Admin 配置页。未配置时对应支付方式在充值页返回 502（优雅降级，不崩溃）；后台「支付配置」页仅展示各渠道「是否已配置」的布尔状态，不显示密钥本身。

支付支持

支付流程与边界

充值订单由前台创建，支付渠道完成付款后通过异步回调通知服务端。服务端验签并校验订单金额，幂等地更新订单和积分流水；已支付订单不会重复到账，超时未支付订单自动取消。

支持项	当前实现
模拟支付	server/utils/payments/mock.ts，本地确认后立即到账
微信支付	Native 扫码，使用 server/utils/payments/wechat.ts（wxpay-node-v3）
支付宝	电脑网站支付，使用 server/utils/payments/alipay.ts（alipay-sdk）
退款	当前不提供自动退款，需要在商户平台处理

订单金额以「分」存储与计算；微信按分传参、支付宝按元字符串传参，回调时自动换算比对。前端轮询订单状态，支付成功后刷新积分余额。

接入前置条件

1. 站点地址公网可达，且生产环境使用 HTTPS。
2. 反向代理或容器放行 /api/pay/notify/**，使微信和支付宝能够回调。
3. NUXT_APP_URL 使用浏览器实际访问的协议、域名和端口，系统据此生成回调地址。
4. 在微信/支付宝平台完成商户申请、产品开通和证书或 RSA2 密钥准备。

环境变量与密钥

支付密钥只写入服务器 .env，修改后重启或重建容器。微信需要 AppID、商户号、APIv3 密钥和商户证书；支付宝需要 APPID、应用私钥、公钥和密钥类型。变量完整清单见环境变量·支付商户密钥。

后台 /admin/payment 的「服务商密钥配置状态」只返回已配置/未配置，不返回密钥本身。状态显示已配置仅代表变量齐全且已生效，不代表商户侧收款功能一定可用。

回调与安全校验

• 微信和支付宝回调必须验签，验签失败不得更新订单或积分。
• 回调处理必须幂等，同一订单只能发放一次积分。
• 涉及积分发放或扣减的接口会校验请求 Origin 的 host 必须与 NUXT_APP_URL 一致，不一致返回 403「非法来源」。
• 关注服务端日志中的 [pay-wechat]、[pay-notify]；排查时可临时提高 LOG_LEVEL。

资产接口安全

涉及积分发放/扣减的接口（如签到、充值回调）会校验请求 Origin 的 host 必须与 NUXT_APP_URL 一致，不一致返回 403「非法来源」。因此 NUXT_APP_URL 必须与浏览器实际访问地址（协议+host+端口）完全一致。

相关接口

路由	说明
/api/pay/notify/*	支付异步回调（微信/支付宝验签）
/api/user/credits/*	用户积分查询/消费
/api/admin/credit-rules/*	积分规则配置
/api/admin/credit-transactions/*	积分流水审计
/api/admin/orders/*	充值订单管理
/api/admin/payment-config	支付渠道配置状态

后台管理

• 积分运营：/admin/credits
• 充值订单：/admin/orders
• 支付配置：/admin/payment

详见 授权售卖（与积分兑换联动）、Admin 运营后台；商户申请、密钥配置与后台开启真实支付见 配置支付与充值。