PerPay v0.3.1

PerPay 0.3.1

相对正式 0.3.0，本版新增订单创建日期筛选、CSV 导出和可选商家帮助链接，并统一后台布局、弹窗和操作反馈。

主要变化

• 支持自定义支付系统名称；可选商家帮助链接在收银台显示为右对齐的小字入口，未配置时不显示。
• 收银台精简重复说明，明确付款状态；合法返回地址用于收款确认后的“返回商家”，以及关闭、过期、争议或保留订单信息的暂不可用状态下的“返回商家处理”。不自动跳转，不追加成功参数。
• notify_url 用于服务端签名通知，return_url 用于浏览器导航，两者独立保存和使用。浏览器返回不代表付款成功，业务网站必须查单或验签通知。
• 订单和通知按北京时间的创建日期筛选；自定义日期默认今天，已有范围保留。订单列表显示付款确认时间，不把它称为支付宝实际交易时间。
• CSV 导出当前关键词、状态、创建日期和排序下的全部订单，单次最多 10,000 条、日期跨度最多 366 天；使用一致读取快照、UTF-8 BOM、转义和公式注入防护，不导出密钥、备注、通知正文或收银台能力链接。
• 首页固定今日指标、待处理与最近订单；图表和每日数据同区切换。通知及对账列表优先展示可读订单摘要。
• 后台统一“收缩／全屏”布局，默认最大 1280px 居中，选择保存在本浏览器；切换不改变侧栏、草稿或筛选。
• 统一确认／表单／技术详情弹窗、危险操作、顶栏刷新、图标提示、成功反馈及空状态；保留幂等编号和未知结果恢复。
• 配置表单使用易读时间单位且不舍入旧值，推荐值只修改草稿；完善备份状态、向导就绪说明和通知失败处理。

数据库与兼容性

• 最新数据库 schema 为 31，运行兼容范围为 24—31。正式 v0.3.0 最新 schema 为 29，升级依次应用迁移 30（系统名称，默认 PerPay）、31（商家帮助链接，默认空）。不改写历史迁移。
• 从 0.2.2 的 schema 23 升级执行迁移 24—31；从 Alpha 的 schema 26 升级执行迁移 27—31。兼容范围不是应用迁移旧库的最低起点。
• 保留现有订单、流水、管理员、密钥和已保存的采集配置；不自动轮换业务密钥。显示设置不改变付款配置版本。
• 旧请求省略帮助链接字段时保留原配置，传 null 清除；无创建日期参数的列表继续支持旧调用。付款确认及通知签名内容不变。
• 静态经营码仍按金额和时间推断归属，不是支付平台逐单确认接口。收款确认与通知送达必须分别判断。

升级与回滚

1. 使用当前版本的维护工具备份数据库，另行保存原主密钥；保留旧构建信息。不要在生产库上执行测试。

2. 待 v0.3.1 Release 和镜像实际发布后，将 app、backup、maintenance 三个服务统一切换到同一版本或镜像摘要，例如 ghcr.io/mashiro0619/perpay:0.3.1。源码版本号不代表镜像已经存在。

3. 在原部署目录执行，不删除数据卷：

   docker compose pull
   docker compose stop app backup
   docker compose up -d
   docker compose logs --tail=100 app backup

4. 核对迁移、健康状态、后台配置、收银台和备份任务；正式流量恢复前，在授权环境验证实际收款及通知签名／ACK 闭环。

不能将 schema 31 数据库直接交给正式 0.3.0（最大 schema 29）或 Alpha（最大 schema 26）打开。 回退需要目标版本兼容的升级前备份和原主密钥；不能手动改 schema 版本号。升级后已有新交易时，不要直接用旧备份覆盖，优先保留完整数据并采用兼容新结构的修正版。

部署说明 · 使用说明 · 维护与恢复

镜像与附件

• 固定版本镜像： ghcr.io/mashiro0619/perpay:0.3.1@sha256:92a7a37947d64128b53f6bb0328bd8c30613594debe83c800216ddb2a8430760
• 部署附件使用镜像： ghcr.io/mashiro0619/perpay:latest
• 支持平台： linux/amd64, linux/arm64
• 数据库结构范围： 24..31
• 部署配置校验值（SHA-256）：2745179ce747172ff177cfe0de8092269e327eeb29f892772f5cf1baefd832eb
• 调用示例校验值（SHA-256）：7c6f2c34f637e2cd33470e11bdb26f27152676f2619cd2191085172cf8f5eac9

这是正式版本，附件跟随稳定版 latest 更新通道。

首次部署下载附件 docker-compose.yml，按中文注释填写域名和代理配置，再执行 docker compose up -d。调用端示例见附件 demo.zip。

Linux 校验附件：echo "2745179ce747172ff177cfe0de8092269e327eeb29f892772f5cf1baefd832eb docker-compose.yml" | sha256sum -c -。