验证、发布与维护记录
在未来更新完成后验证业务、安排发布、处理失败，并区分公开更新说明与内部维护记录。
本篇用于已经完成目标评估与必要合并之后。暂时没有更新需求时，保留现有项目即可，不需要执行发布、打标签或数据库操作。
一、先明确验收范围
验证应围绕本次变化及其实际影响展开，不能只看首页，也不必在无关文案修改后机械测试所有第三方功能。
| 本次变化 | 需要验证的代表场景 |
|---|---|
| 登录、会话或邮箱验证 | 新旧账号、正常与失效会话、错误验证码、必要的二次验证 |
| 权限和产品规则 | 普通账号与已购买账号、历史授权、过期或撤销后的行为 |
| 支付和 Webhook | 测试购买、重复投递、延迟或乱序事件、旧套餐关联 |
| 数据结构 | 旧数据读取、写入、约束、空库初始化和已有库升级 |
| Queue 或 Reaction | 正常执行、可重试失败、重复消息、升级前保存的执行记录 |
| 内容与语言 | 导航、正文、搜索、已启用语言及缺失文案 |
| 资源与域名 | 绑定目标、Cookie、回调、Cron 与运行日志 |
开发模式下邮件是终端预览，不能把预览成功当作真实投递验证。使用 Stripe 测试模式时也要确认连接、Price 和 Webhook 属于同一测试环境。
二、完成本地检查
代码变更完成后运行：
npm run verify模板会依次执行 ESLint、TypeScript 类型检查、应用与脚本等测试，以及生产构建。检查过程中生成的内容或类型错误也需要处理，不能只留下最后一次构建成功的截图。
如需本地检查打包后的页面，可以使用：
npm run preview本地预览不能证明生产资源、邮件服务或第三方回调可用。需要线上集成验证时，先准备隔离资源与明确的测试配置，当前模板并没有自动提供一套完整的 staging 环境。
三、发布前核对实际运行目标
记录准备发布的提交、站点地址、Worker、资源 ID、迁移文件及配置变化。确认恢复所需的原始主密钥和其他凭据仍保存在安全位置，记录里只写保存位置或更新状态。
涉及生产数据变化时，确认备份或恢复点可用，并评估发布期间是否需要限制相关写操作。只创建 Git 标签不能保护数据库和外部服务状态。
正常更新使用：
npm run deploy:update该命令发布的是当前工作目录，不会下载或合并模板。执行顺序包括生产检查、生成类型、完整验证、远程迁移、发布 Worker、同步 KV 和页面健康检查。
由于它已包含 verify，发布前不需要为了凑流程立刻再重复一遍相同检查。但早先验证之后若又修改了代码，不能把旧验证结果当作当前版本的证明。
发布步骤详见首次部署与后续更新。
四、失败后先确认发生了什么
| 停止位置 | 当前状态可能是什么 | 恢复方向 |
|---|---|---|
配置检查或 verify | 尚未执行本次更新的远程迁移与发布 | 修复失败项，再继续更新 |
| 数据库迁移 | 部分前序迁移或另一个库已完成 | 核对迁移记录与结构，确定修复 SQL |
| Worker 发布 | 迁移可能已完成，旧代码可能仍在线 | 保证旧代码与当前结构兼容，修复发布 |
| KV 同步 | 新 Worker 已上线，但内容尚未完整同步 | 使用正确版本恢复同步 |
| 健康检查 | 前面的步骤可能全部已完成 | 检查实际页面和日志，定位业务或入口问题 |
不要看到命令失败就删除资源、清空数据库或重复首次部署。更详细的排查见部署、资源与域名。
代码回退不等于系统恢复
如果仅修改了应用代码，且没有改变数据格式、配置语义和外部状态，可以评估重新发布已验证的旧代码。如果迁移已经删除旧字段，或者新版本已经写入旧版本无法识别的数据，就不能直接套用这条办法。
数据库恢复可能撤销恢复点之后的合法数据。Stripe 已付款、邮件已发送、Queue 已处理的效果也不会随 Git 回退一起消失，需要单独对账。
项目没有自动回滚整个系统的命令。恢复方案应根据这次变更制定，写清恢复对象、依据、执行顺序与恢复后需要补处理的业务。
五、上线后验证真正受影响的功能
页面健康检查通过后，用发布前准备的代表案例验证。核对旧账号和历史数据，不要只创建一个新账号得到正常结果。
涉及后台工作时，继续检查 Event、Command 和消费者结果。涉及支付时，核对交易与权益是否一致。首次观察到正常结果后，还应结合真实业务周期留意延迟回调或定时任务，不把短时间没有报错理解为所有路径已经验证。
确认稳定后，清理本次确实不再需要的临时逻辑、测试配置和旧引用。没有用到的资源不要仅凭名称相似就删除，先确认没有读写者和恢复用途。
六、保留一份内部维护记录
内部记录解释如何实施和恢复，公开更新页解释用户得到了什么，两者用途不同。
下面是以后有实际更新时可以复制的记录模板，其中占位内容需要据实填写，不是本次已经发生的升级：
# 更新记录：<本次变更名称>
- 状态：评估中 / 待发布 / 已发布 / 已恢复
- 更新原因：
- 应用原提交与版本：
- 模板原来源与目标来源：
- 本次采用的修改：
- 保留或未采用的模板变化及原因：
- 数据库迁移文件与验证结果：
- 配置、变量和资源变化：
- 第三方平台人工操作：
- 自动检查与业务验收结果：
- 实际发布提交、时间和目标 Worker：
- 失败时的恢复条件、对象与步骤：
- 发布后的观察结果：
- 尚未解决的问题：不要在记录里保存 Secret、Cookie、令牌、完整生产数据或邮件验证码。数据库备份也应单独安全保存，不应随文档提交到仓库。
即使决定暂缓更新，也可以记录目标版本和暂缓原因。下次评估时就不必从头猜测。
七、维护公开的更新说明
当前模板的更新页读取 src/components/server/Changelog/entries.ts 中的静态数组，不会自动把 Git 提交或 package.json 版本转换成公告。
当前条目使用以下字段：
| 字段 | 用途 |
|---|---|
commit | 关联提交的文字标识 |
date、displayDate | 日期与展示日期 |
type、title、description | 更新分类、标题和说明 |
icon | 当前组件支持的图标名称 |
items | 由 kind 和 copy 组成的变化列表 |
条目正文当前直接使用数组中的英文字符串，页面框架文案才通过 pages.changelog 等语言键读取。只修改语言 JSON 不会自动翻译 entries.ts 的标题和条目。如果未来需要多语言更新正文，应按项目既有国际化机制接入对应资源。
初始化后的产品不应把模板历史记录自动当成自己的产品发布历史。有实际发布时，再记录自己已经提供给用户的变化。没有变化时，不需要为了填充页面虚构新版本。
文案应描述具体结果，例如“修复修改邮箱后旧地址仍收到后续通知的问题”，比“优化邮箱模块”更有意义。内部资源 ID、恢复点、敏感数据和具体安全控制细节保留在受控的维护记录中。
八、标签、源码包与部署各自独立
npm run release:tag 会创建并向 origin 推送标签，不是本地只读操作，也不会部署 Worker。release:archive 从指定 Git Tree 生成源码包，不会包含未提交的改动。
模板维护者的 commit script 在发布源码包中被移除，不能假定初始化项目提供相同的一键提交方式。
是否使用这些发布命令，应由自己的版本管理流程决定。现在没有发布需求时，不需要先创建标签或归档，只需保留能够追溯项目状态的记录。