PerPay v0.3.0

本版相对 0.2.2，主要更新管理后台、公开收银台、首次配置和密钥维护，并完善查询、人工核账及异常操作的恢复流程。已使用 0.3.0-alpha.1 的实例同样需要升级数据库，请先阅读兼容性与升级说明。

更新内容

管理后台与公开收银台

• 管理后台统一使用 shadcn/ui 组件，整理侧栏、设置分类、表格和弹窗，支持浅色、深色及跟随系统；改善手机工具栏、列显示、触摸尺寸、键盘操作和焦点回归。
• 收款概览支持面积图、柱状图与折线图，使用中性灰阶展示收款趋势；每日数据直接展示并分页，金额完整显示，不缩写关键数值。
• 订单详情集中展示付款依据、关联流水、异常和通知结果。管理员可打开订单原收银台，不新建订单或延长付款期限。
• 公开收银台采用桌面双栏、手机单栏，保留二维码放大、保存及付款状态查询。可在实例设置关闭商品名称展示；该设置不修改订单或通知内容，也不是数据保密开关。
• 付款组件未启动时不显示二维码或静止倒计时，包括禁用 JavaScript、脚本加载失败或尚未初始化的情况；提供不依赖脚本的刷新链接。延迟启动、页面恢复或达到付款期限时，付款入口仍受时钟和生命周期守卫限制。

五步配置与密钥维护

• 首次配置精简为五步：应用公钥、支付宝接入、经营码、通知与备份、收款检查。管理员初始化与收款配置分离，支持步骤切换、未保存草稿保护和明确保存。
• 业务 API 凭证统一放在 实例设置 → 密钥与安全，不再作为向导必选步骤。向导完成不代表业务 API 已开通：调用方仍须在网站后端配置客户端 ID 和密钥，并通过签名鉴权。
• 尚未生成 API 密钥时，收款就绪的管理员可以创建真实测试订单；系统只保留禁用的客户端身份，不会自动生成或启用 API 凭证。测试收款不是模拟付款，也不是完成向导的必要步骤。
• 支持支付宝应用公钥安全变更：已接入实例先生成加密保存的待启用密钥，上传新应用公钥后，必须重新填入同一应用的支付宝公钥；只读查账并验签通过后才切换，不直接覆盖正在使用的私钥。
• 支持通知签名密钥轮换，保留通知开关、接收来源及重试配置。轮换后需同步更新业务系统验签配置；结果不确定时不得反复轮换。
• 设置参数直接展示，去除重复分组标题；将“终态观察期”明确为 收银台结束后查询期：仅控制公开链接在结束后继续查询状态的时长，不延长付款期限，不控制后台迟到账单处理，修改仅影响新订单。

查询、人工核账与安全边界

• 订单、业务通知、支付关联、账本冲突、账务异常和待处理事项支持服务端搜索、排序、游标分页及列显示，并保留筛选条件与返回位置。
• 人工关联采用“推荐候选＋搜索选择”，支持从订单选流水、从流水选订单，或逐步选择双方记录。确认前重新读取证据，理由改为可选；其他管理员财务操作原有的理由要求不变。
• 待处理事项可按筛选范围跨页忽略提醒，并支持查看、恢复与中断后继续操作；忽略后同步刷新提示，但不会消除真实冲突或停止通知重试。
• 区分运行故障与业务待处理；保留暂停收款、数据库异常和状态无法确认等阻断提示。修复离线改密反馈、迟到请求结果和密钥轮换超时恢复。
• 即使账户尚无流水，只要已有结束订单，切换支付宝账户仍须完成收尾检查，不能以零流水绕过旧账户的采集与确认要求。
• 管理员测试建单在读取请求体后再次复核会话，拒绝读取期间已注销、撤销或过期的会话；原有同源、CSRF、幂等和收款就绪检查继续生效。

更新通道与默认配置

• 支持 SemVer 预发布版本比较；正式版只检查正式版，预发布版同时检查正式版与预发布版。更新检查只提示，不自动安装；失败不会显示为“已是最新”。
• 新实例默认常规采集 60 秒、活跃采集 8 秒、采集有效时限 120 秒。已有配置不被默认值覆盖，金额复用冷却不延长历史付款窗口。

兼容性与数据库迁移

• 本版最新数据库 schema 为 29，运行兼容范围为 24—29。应用启动会自动迁移旧结构：从 0.2.2 的 schema 23 升级执行迁移 24—29；从已发布 0.3.0-alpha.1 的 schema 26 升级执行迁移 27—29。兼容范围不是阻止应用迁移旧数据库的最低起点，维护工具不会代替应用执行迁移。
• 迁移 24 增加显示设置，25—26 增加后台查询索引；27 允许人工关联理由缺省；28 增加支付宝应用密钥变更历史；29 分离 API 客户端身份与凭证。
• 迁移保留已有订单、客户端、密钥版本、外键关联、流水证据和历史审计记录，不自动轮换业务密钥、不重置管理员或已保存的收款配置。
• 业务订单与通知接入方式保持不变；公开收银台查询期仍使用 checkout_terminal_observation_seconds 字段。新增或改进的管理员功能继续遵守会话、CSRF、事务校验和幂等保护。
• 推荐候选不等于付款确认，金额推断不等于支付宝按商户订单号确认。管理员退款标记不会执行转账或通知业务系统；历史 REFUND_UPDATED 通知仍需兼容。

升级与回滚

1. 升级前先备份数据库，并另存 perpay-secrets 主密钥卷，保留原数据卷与旧构建信息。使用当前兼容的维护工具完成备份，建议先在隔离实例演练恢复，不要让测试实例向真实支付宝或业务通知地址发送请求。

2. 确认 0.3.0 的 Release 和镜像已实际发布。固定版本或从 Alpha 升级时，将 app、backup、maintenance 的镜像统一改为 ghcr.io/mashiro0619/perpay:0.3.0；使用稳定版 latest 的实例保持三个服务一致，不混用旧维护镜像。

3. 在原部署目录执行以下命令，停掉旧应用和自动备份后启动新构建；不要删除数据卷：

   docker compose pull
   docker compose stop app backup
   docker compose up -d

4. 核对数据库迁移、健康状态、首次查账、自动确认和备份任务。收款就绪后，在授权环境完成小额付款、查账确认、通知签名与 ACK 闭环验证，再恢复正式业务流量。保存备份配置不等于已经证明可恢复。

不能将 schema 29 数据库直接交给只支持到 schema 26 的已发布 Alpha 或更旧程序打开，也不要手动改数据库版本号伪装降级。 回退旧版需要该版本兼容的升级前备份及原主密钥。若升级后已经产生订单、流水或操作记录，先限制新下单并保留当前完整数据；不要用旧备份直接覆盖而丢失新增记录，优先使用兼容当前结构的修正版处理。

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

镜像与附件

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

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

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

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