魔方财务商品与付款机器人

← 运维与备份 · 所有分区

VexBot 使用 Python 和 OneBot 11，在私聊中接入传统智简魔方财务。可以配置多家服务商；每位用户分别验证自己的服务商账号，再浏览一级、二级商品分组和商品详情，获取报价、确认订单与付款二维码或链接。

安装与启用

需要 Python 3.11+，并完成 OneBot 11 连接。项目根目录执行：

python -m pip install -r requirements.lock.txt
python -m starbridge init
python -m starbridge run

初始化只执行一次。NapCat 等实现端填写通用反向 WebSocket ws://127.0.0.1:5800/onebot/ws，Access Token 使用 config.toml 的 onebot.token。

在 config.toml 同目录创建 billing.toml：

enabled = true
timeout = 15

[providers.demo]
name = "示例服务商"
base_url = "https://billing.example.com"
# 可选：HTML 支付表单的账单页入口，按服务商主题配置。
# invoice_path = "/viewbilling?id={invoiceid}"

# 可继续添加 [providers.other]，最多 20 家。

把示例域名换成服务商实际 HTTPS 根地址，允许安装在子目录；修改后重启 VexBot。服务商标识 demo 用于机器人指令。服务商由部署者配置，用户选择并绑定自己的账号。功能默认关闭，地址不包含接口路径 /v1 或查询参数。

仅使用财务功能时，不需要 Minecraft 游戏端。在 config.toml 所有表之前写 servers = []，并删除示例的 [[servers]] 及 [servers.commands] 表。财务私聊处理不依赖任何游戏服务器或关联群。

绑定与浏览

用户先在服务商会员中心的安全中心 / API 管理创建 API 密钥，按服务商要求授权机器人运行服务器的出口 IP。私聊机器人发送：

/财务服务商
/财务绑定 demo user@example.com 在服务商创建的API密钥
/财务账号 demo
/财务分组 demo
/财务分组 demo 1
/财务商品 demo 2
/财务详情 demo 100
/财务支付方式 demo

账号为服务商注册手机号或邮箱，第二个凭据为 API 密钥。机器人调用 API 登录后读取会员资料验证身份，验证成功才保存绑定。查询分组、商品、支付方式和订单都要求先绑定；业务请求会重新验证服务商身份。已绑定的服务商根地址变化时，原凭据不会发往新地址，用户需要核对后重新绑定。

/财务分组 demo 查看一级分组，/财务分组 demo 1 查看一级分组 1 下的二级分组；/财务商品 demo 2 查看二级分组 2 下的商品。列表每页 12 项，在命令末尾添加页码，例如 /财务商品 demo 2 2。分组分页格式为 /财务分组 demo 一级分组ID 页码。

下单与付款

/财务下单 demo 100 monthly WxPay 1

周期和支付方式使用服务商返回的标识，不能使用自行翻译的名称。数量默认为 1；最多 100，实际还受服务商商品库存和购买数量规则限制。机器人返回服务商计算的应付金额和 5 分钟有效的确认码，此时尚未创建订单。

/财务确认 demo 机器人返回的确认码

确认时重新报价；价格或币种变化会使当前确认失效，需要重新下单报价。确认后只结算本次加入的购物车位置，保存本地订单号和服务商账单号，再发起所选支付方式。二维码内容由本机生成 PNG 并通过 OneBot 私聊图片发送；支付插件返回跳转链接或二维码图片地址时直接返回对应链接。

支付插件只返回 HTML 表单时，机器人返回服务商的账单网页，用户登录服务商网站后完成支付。默认模板为 /viewbilling?id={invoiceid}；该前台地址由服务商主题决定，可用 invoice_path 改成实际路径。占位符固定为 {invoiceid}，只能跳转到所配置服务商站点。

/财务订单 demo
/财务订单 demo 本地订单号
/财务付款 demo 本地订单号 WxPay

订单状态实时查询服务商账单。机器人创建付款入口；支付到账与商品交付由服务商处理。付款入口生成失败不会丢弃已创建订单，可使用 /财务付款 再获取入口。返回二维码不代表已付款。

配置型商品可在数量后添加 JSON：

/财务下单 demo 100 monthly WxPay 1 {"configoption":{"12":34},"customfield":{"5":"example"},"host":"my-server"}

支持 configoption、customfield、host、password、os 字段。os 使用系统 ID 到名称的对象，例如 "os":{"8":"Ubuntu 22.04"}。配置项与子选项 ID 按商品详情和服务商文档填写；不同模块的附加必填参数、联动规则、实名认证或销售限制仍以服务商校验为准。服务商定制模块需要扩展适配时，修改 starbridge/billing_client.py 的产品参数转换。

数据与异常处理

/财务解绑 demo 删除本人凭据并作废待确认请求。解绑重绑会更新账号代次，旧订单不能通过新绑定访问。群里收到财务指令时只提示私聊，消息不会继续转发到游戏，也不会在群内执行绑定、下单或返回付款信息。

财务数据独立保存在与 config.toml 同目录的 data/billing.sqlite3，API 凭据和待确认商品参数使用 Fernet 加密，密钥保存在 data/billing.key。密钥缺失时拒绝读取原绑定，不会生成新密钥覆盖它。billing.toml 和 data/ 不进入源码提交和发布附件。

现有面板便携备份覆盖原有主数据库与社区设置，不包含此模块的独立数据库和密钥。迁移或备份财务功能时，停止机器人后一起保存 billing.toml、data/billing.sqlite3 和 data/billing.key；丢失密钥时需要恢复原密钥备份。升级包保留这些本地文件。

确认码持久化并原子领取；重复消息、重复确认、并发确认及进程重启不会重新提交同一确认。请求超时或返回结果不确定时，不自动重试创建订单，请先到服务商会员中心核对。不同确认码代表不同购买意图，重新发送下单命令会生成新的确认码。

API 适配依据与测试边界

接口依据智简魔方官方的 财务系统 API 文档，采用传统前台接口契约，服务商地址保持可配置。该模块不使用智简魔方 V10 的签名接口。

本仓库使用模拟服务商测试账号校验、分组结构、报价、指定购物车结算、订单归属、重复确认及支付回复。真实服务商域名和测试账号尚需部署者配置；未配置真实凭据时，不能完成真实下单、付款到账或商品开通验收。