云枢支付聚合支付系统 · 模板开发文档
版本：V1.0.1 | 系统内置三套页面模板体系：首页模板 / 支付页模板 / 聚合收款页模板，支持模板市场分发、后台一键切换、卸载自动回退。
一、模板体系概览
| 模板类型 | 标识 | 生效位置 | 后台位置 |
|---|
| 首页模板 | home | 站点前台首页 / | 模板配置 / 模板市场（分类：首页模板） |
| 支付页模板 | pay | 收银台 /cashier/{订单号} | 模板配置（支付页模板） |
| 聚合收款页模板 | qrpay | 聚合收款/付款码收款页 | 模板配置 / 模板市场（分类：聚合收款页模板） |
模板配置存储（后台「模板配置」页切换）：
| 配置键 | 说明 | 默认值 |
|---|
tpl_home | 当前首页模板标识 | default |
tpl_pay | 当前支付页模板标识 | 内置 |
tpl_qrpay | 当前聚合收款页模板标识 | 内置 |
cashier_tpl | 收银台渲染变体（联动 tpl_pay） | xjupay |
二、模板包结构（通用）
模板以 zip 包形式分发，上传到模板市场或手动放置到 extend/plugins/{标识}/ 目录。核心清单文件：
plugin.json（模板专用字段）
{
"name": "my_home_tpl",
"display_name": "我的首页模板",
"version": "1.0",
"author": "开发者",
"description": "模板简介",
"template": "home",
"tpl_name": "my_home"
}
| 字段 | 必填 | 说明 |
|---|
| name | 是 | 目录标识，[a-zA-Z0-9_-]{2,40} |
| template | 是 | 模板类型：home / pay / qrpay |
| tpl_name | 是 | 模板标识（用于配置项与文件名），[a-z0-9_-]{1,30} |
| display_name / version / author / description | 否 | 展示信息 |
| preview.png | 推荐 | 市场预览图 |
模板包不需要 class、types、config_fields 等通道插件字段，且 template 非空时系统按模板包处理，不会当作通道插件加载。
打包方式
my_home_tpl.zip
└── (任意一层或两级目录)/plugin.json + index.html + preview.png + 其他静态文件
系统安装时自动在包内搜索 plugin.json（支持根目录或一到两层子目录），无需固定层级。
三、首页模板开发（home）
1. 运行机制
- 首页模板就是 ThinkPHP 视图文件：
app/index/view/index/{tpl_name}.html；
- 安装模板包时，系统把包内
index.html 复制为该视图文件并清空视图编译缓存，切换即刻生效；
- 前台路由
/ → Index/index 控制器按 tpl_home 配置渲染对应视图；
- 模板标识白名单校验
^[a-z0-9_-]{1,30}$，不存在时自动回退 default；
- 卸载模板时自动删除视图文件，若正在启用则回退默认模板。
2. 模板内可用变量（控制器注入）
| 变量 | 说明 |
|---|
{$siteName} | 站点名称 |
{$siteUrl} | 站点地址 |
{$err} | 演示支付返回的错误提示 |
{$notices} | 平台公告列表（前 5 条，status=1，sort 排序） |
{$payTypes} | 启用的支付方式列表（演示支付表单下拉用） |
{$stats} | 数组：today_amount 今日交易额 / total_orders 累计订单 / merchant_count 商户数 / type_count 支付方式数 |
{$registerOpen} | 是否开放注册（1/0） |
3. 注意事项
- 模板内不能调用对象方法（ThinkPHP 8 模板限制），需要的数据必须由控制器注入；
- 静态资源请使用
{:request()->root()}/static/... 或绝对路径 /static/...；
- 建议整页样式内嵌或引用
/static/ 下资源，保证模板包独立可分发；
- 演示支付表单 POST 到
/demo/pay（参数：type/money/name，见内置 default 模板）。
四、支付页模板开发（pay）
1. 运行机制
- 收银台为轻量 SPA：
public/static/cashier-spa/（index.html + css/app.css + js/app.js）；
- 收银台数据接口
/cashier/info/{订单号} 返回 tpl 字段（值来自 cashier_tpl 配置：xjupay / paypro）；
- 模板切换：后台「模板配置 → 支付页模板」写入
tpl_pay，同时联动写入 cashier_tpl。
2. 开发新支付页模板
- 在
cashier-spa 中新增渲染分支（按 tpl 值切换布局/配色/交互），或直接开发新的独立收银台页面；
- 订单数据接口：
GET /cashier/info/{trade_no}、轮询 GET /cashier/poll/{trade_no}、模拟支付 POST /cashier/mockpay/{trade_no}；
- 若以模板包分发：包内
plugin.json 填 "template": "pay" + tpl_name，附 index.html 等静态文件；
- 通过模板市场安装后，在「模板配置」中启用。
3. 收银台核心约定
- 页面需支持：订单信息展示（金额/商品/订单号）、支付方式选择、二维码或跳转支付、3 秒轮询支付状态、支付成功/失败结果页；
- 公众号/小程序支付走 JSAPI 调起参数（
/cashier/info 返回 jsapi 字段）；
- 码支付订单（codepay_ 类型）收银台需额外支持「我已完成支付」按钮（POST
/codepay/buyer_confirm）。
五、聚合收款页模板开发（qrpay）
1. 运行机制
- 模板目录：
extend/plugins/{标识}/，plugin.json 中 "template": "qrpay"；
- 纯静态文件模板：
index.html（收款页）+ css/、js/、images/ + success.html（收款成功页）+ info.json（模板元信息，name/title/author/version/desc）；
- 后台「模板配置 → 聚合收款页模板」按
tpl_qrpay 配置渲染。
2. 内置参考
extend/plugins/qrpay_default/ 为官方默认模板，可直接参考其目录结构与页面写法：
qrpay_default/
├── plugin.json # {"template":"qrpay", ...}
├── info.json # 元信息
├── index.html # 收款页
├── success.html # 成功页
├── preview.png # 市场预览图
├── css/ js/ images/
3. 收款页数据接口
| 接口 | 说明 |
|---|
POST /onecode/info | 收款码信息（code 参数，返回 title/money_type/money/pay_types） |
POST /onecode/create | 创建收款订单（返回 trade_no，跳转 /cashier/{trade_no}） |
六、模板的安装 / 切换 / 卸载
| 操作 | 途径 |
|---|
| 安装 | 模板市场点「安装」（云端下载 → 校验 → 落盘）；或手动上传 zip 到后台「本地插件」上传；或手动放置 extend/plugins/ 目录 |
| 切换 | 后台 → 应用管理 → 模板配置，选择对应模板类型启用 |
| 卸载 | 模板市场「卸载」/ 本地插件「删除」——首页模板会删除视图文件并自动回退默认，其余模板删除目录 |
| 调试 | 首页模板切换后若未生效，清空 runtime/index/temp/ 视图缓存 |
七、开发规范与踩坑提示
- 命名：模板标识一律
[a-z0-9_-]，避免中文/大写/特殊字符（会被白名单校验拦截）；
- 首页模板不要调用对象方法：
{$obj.method()} 会直接 500，改用控制器注入字段 + {if}；
- 路径：模板内资源路径用绝对路径
/static/...，避免多应用模式下相对路径解析错误；
- 安全：模板内输出的用户可控内容（商品名、备注）注意转义；
- 兼容性：支付页/收款页模板建议移动端优先（手机扫码场景为主）；
- 版本管理：
version 字段用于模板市场更新检测，请随迭代递增。
