docs/UPGRADE_v0.9.4.md

Rama main · réplica de lectura del repositorio original.

# Core v0.9.4 补丁升级指南

[English](UPGRADE_v0.9.4.en.md)

从公开 Core 0.9.3 升级到 0.9.4，移除 DOCX 未使用的 CLI 依赖链，并为新任务终态与审批提示提供持久通知及自带控制台管理。本指南仅涉及 Core；SDK/DSH 仍为 0.7.0，ACC、客户端及独立 Host 按各自流程发行和部署。

## 1. 保存一致备份并暂停写入

保留当前代码或镜像摘要、配置和凭据、附件、状态与配置数据库、JSONL、迁移账本及旧制品。数据库可能分开：任务终态属于状态库，审批与审批提示属于配置库；分别确认实际数据库身份并备份。通知快照含业务正文和目的地址，按原任务数据等级保护，不能复制到公开报告。

停止新工作并协调所有共用库的写入方，排空旧实例。核对在途通知、原任务/请求/审批和外部回执。保留原 ID、死信重投标记及队列；旧实例关闭完成不证明从未持久保存的通知意图已经送达，升级不会批量补发历史已完成任务和旧审批。

## 2. 核对制品并显式迁移

使用正式 `v0.9.4` 源码、`bailinghub@0.9.4` 或镜像，核对 Tag/提交、版本和制品摘要。安装器及预构建 Compose 默认版本为 0.9.4，已有 `.env` 保留。DOCX 依赖改为仓内固定库归档；不要仅更新版本字段或保留旧锁树，也不需要自行修改上游包源码。

| 相对 0.9.3 新增迁移 | 作用 |
| --- | --- |
| `068_notification_outbox.sql` | 建立 `bz_notification_outbox`，保存事件、快照、状态、重试与租约；给 `bz_delivery_dlq` 增加可空 `event_id` 及唯一索引 |

067 及以前的迁移保持原样。使用新制品自带的官方显式迁移器执行全部待执行 SQL，核对完整 `BAILINGHUB_CORE_ARTIFACT_V1` manifest；不手工修改旧 SQL 或迁移账本，Kernel 启动不自动迁移。

```bash
npm run db:init
```

**该 CLI 只迁移当前配置中的 `state.mysql`。** 如果审批使用独立 MySQL 配置库，必须额外对该库调用官方 `migrateBailingHubCoreSchema({ mysql: configurationDatabase })`，由部署方提供已确认的目标连接配置。状态/配置共库时只执行一次；不要并行迁移同一库。JSONL 状态存储不需要 SQL 迁移，但其 MySQL 配置库仍需 068。配置库入口和权限见 [Kernel Host API](KERNEL_HOST_API.md)。更早版本须补齐前序迁移，参见 [0.9.3 升级指南](UPGRADE_v0.9.3.md)。

迁移完成不创建历史通知。JSONL 使用同步复合日志记录且只支持一个 writer；不要让新旧实例同时写同一日志。未完成尾行可按仓储规则恢复，完整记录损坏应停止处理，不能删除中间历史来强行启动。

## 3. 配套仓储和接收方

官方状态/配置仓储、DLQ ledger 与 Core 一起更新。自定义仓储需实现可选持久端口及事务、租约 token、原事件重试语义；未实现时保留旧尽力发送兼容路径，管理接口显示能力不可用，不能据此宣称可靠补投。

Webhook 接收端按 `X-Bailing-Event-Id` 或签名正文 `notification_event_id` 保存去重记录。网络中断、429、5xx 可有限退避重试；普通 4xx 停止，自动周期最多六次发送尝试，耗尽后保留失败记录。接收方处理成功而本地确认丢失会再次发送同一事件；租约不保证跨系统恰好一次。

原生部分/未知送达或过期在途领取为 `uncertain`。控制台「任务 → 通知送达」只允许有 `runs:write` 权限者重新处理，并要求核对重复风险；状态改变返回冲突，不覆盖新状态。关联原生事件的死信统一通过 outbox 重试；067 执行器死信仍只重排原通知子任务。补通知不重跑业务父任务，不将通知 `completed` 当作收件人已阅读。

嵌入式继续公平调用既有 `tick()` 和 `close(drainMs)`；正常关闭停止扫描并等待已接受的工作，剩余持久记录由后续实例恢复。普通告警和任意外部扩展不纳入本次完整持久化保证。

## 4. 升级验收

1. 核对新制品身份、两类目标库的迁移账本/068 表和索引、`/health`、readiness、控制台与既有 smoke。可显式运行只读 `npm run --silent doctor -- --deployment --url http://127.0.0.1:18900 --readiness --json`；它不执行迁移，也不独立确认所有数据库身份或镜像摘要。
2. 在隔离数据和本地接收端上验证：新任务终态/审批创建与意图一起保存；中断重启后同事件补通知，原业务派发次数不增加。验证接收端处理后确认丢失的重复可被事件 ID 去重。
3. 验证旧 worker 不能确认新租约；原生未知态停止自动重发；控制台只读角色不能重试、并发旧状态返回 409。保留旧 067 原通知重投的入队去重保证。
4. 验证控制台和实际 npm 消费的 DOCX 既有解析路径。`npm run docx:vendor:verify-upstream`、`npm run docx:test`、构建后的 `npm run docx:browser:test` 及 `npm run audit:deps` 提供公开验证入口。原始审计零发现不等于任意文档安全。
5. 如启用受保护 `/metrics`，核对固定 `jobs` / `approvals` 的可用性、持久状态数、待处理年龄及过期租约。指标读取不触发发送，未实现端口不伪造零积压。当前没有 outbox 自动清理策略，应监测数据增长。

完整回归入口见[通知持久化](NOTIFICATION_DURABILITY.md)和[依赖校验](DOCX_DEPENDENCY.md)。条件跳过不能算通过；发行合成测试不代替目标环境真实渠道验收。

## 5. 回退边界

先停止新接单、通知 worker 和共用写入方，保存 outbox、死信、原任务、队列、回执与迁移账本，核对已经送出和仍未知的通知。**旧代码不会处理新 outbox，旧 schema manifest 也可能拒绝未知的 068 账本。** 增量表不代表可以无验证直接降级，不得删迁移记录、通知事件或重投标记来绕过检查。

在隔离副本验证拟恢复的代码/配置/数据库组合。需要恢复备份时按一致集合恢复，另外核对备份以后发生的业务和消息；恢复数据库不能撤销外部退款或已发通知。回退到 0.9.3 同时恢复旧 DOCX 依赖链与其原限时风险，并失去新通知持久化能力，不能继续宣称依赖修复或崩溃补投已生效。

[版本说明](RELEASE_NOTES_v0.9.4.md) · [通知契约](NOTIFICATION_DURABILITY.md) · [兼容策略](兼容性与升级.md)