# MQ 独立修复契约（2026-10-23，本地候选）

主链已经部署并由用户验收。本补丁只处理 MQ，不改变 UserBase 身份模型、HTTP 收据主链、FL、B5 或对账调度。
代码基线为 FC 核心 SHA 1717f4c47e26918e7f582d0c00ddd23b732ab98a；旧 MQ WIP 保留在原 worktree。

## 身份与路由

- `application_info.id` 是业务应用主身份；`appKey/appSecret` 是签名凭据；`appCode` 只用于部署/寻址以及现有注册查询。
- 兼容现有 v2 协议：`sourceAppKey/consumerAppKey` 仍携带凭据键，不改名、不把业务 id 填进去、不迁移已有业务绑定。
- source 默认引用最终 `yh.app-auth.app-key`；显式 source 与签名键不一致时拒绝。真正发布前还按本应用的部署 code 调已有 `getAppByCode`，核验注册行的正整数 id、appCode、appKey。允许 id != appKey。不可达/错配进入有界失败退避，不记 broker 成功。
- 不使用答卷的资源 `snapshot.appCode` 推断发布者身份。该字段是资源所属应用技术标识，原样保留。
- v2 routing key 固定为 `fc.snapshot.v2.<consumer credential key>.<schoolId>`，不能把应用主键或 appCode 代入。拒绝能扩展 topic 段的通配符/额外分隔符与非正学校号。
- SH 的 binding、信封消费身份与最终签名凭据必须同源；不硬编码为 100008 或 100018。

## 投递状态裁决

| 输入 | 条件 | 结果 |
|---|---|---|
| ACK | 当前代且没有已返回事实 | BROKER_ACCEPTED；不写 consumer_applied |
| 重复 ACK | 当前代已接受 | 时间戳/计数不再改写 |
| NACK / mandatory return | 当前代，包括先前已收到 ACK | FAILED 或预算耗尽 DEAD；清 broker_accepted_at，保留原因并退避 |
| ACK 带 CorrelationData.returned | 独立 return 回调未持久化也一样 | 先按 NO_ROUTE 失败处理，不能写成功 |
| 重复负回调/迟到旧代 ACK | 负回调已推进 retry_count 或授权重放操作已变化 | 幂等忽略，不清错误、不重复扣重试预算 |
| DEAD/GRANT_REVOKED | 任意 broker 回调 | 不复活 |
| 序列化/快照损坏/注册不可达 | 未实际发送 | 失败退避；同 eventId 与不可变快照恢复，不伪造消费成功 |

回调以现有 retry_count 与重放操作键摘要标识代际，读取同一投递行时使用写锁；没有新增库列。
这是至少一次投递，不能声称 broker/数据库的真实并发恰好一次已验证。
发送通道必须配置 correlated confirm、publisher-returns 和 mandatory；缺少返回事实观察能力时不启用扫描发送。
`push_allowed=0` 保留 read/subscribe 数据权，既不建新 v2 outbox 行，也不继续发失去 push 权的旧行。

## N-1 元数据事件

`fc.events.v1` 现在显式序列化为 UTF-8 JSON Message，再调用 RabbitTemplate.send；不更换共享模板的转换器，不影响 v2。
信封仍为十字段闭集；不含 values/附件字节/凭据。messageId 与 event_id 一致，提交后使用冻结的坐标发送。
`fc.events.enabled` 默认 false，且仍须 broker host；仅平台注入 host 不会打开已修好的事件通道。
该元数据通知与 v2 push 授权是两个协议；没有引入新的订阅授权模型。
保持原 best-effort 语义：转换/声明/发送失败不反向破坏答卷提交，不增加 v1 outbox 或自动重放；后续事件可以恢复。v2 才有有界可靠重试台账。

## B-03 及验证边界

B-03 原定义是共享 `/` vhost 与同一 admin 账号，不是转换器问题。独立 vhost、分权账号与 topic 前缀约束仍需环境交付。
FC 会主动 declare 自己的 exchange；SH RabbitAdmin 会声明队列/exchange/DLX/binding。因此权限方案须包含这些实际操作，不能只写“发布方 write”就认为配置完毕。
普通资源权限与 topic binding key 权限须分开核验；依据 [RabbitMQ 官方访问控制表](https://www.rabbitmq.com/docs/access-control)，不是本轮 broker 实测结论。
本轮仅本地规则、真实 JSON 转换、Spring 条件装配测试。真实路由、NO_ROUTE、ACL、HMAC身份、DB并发与生产验收均 NOT RUN。
不得开启生产 MQ、修改 push_allowed 或 B-08。请使用独立测试 vhost 完成后续环境验证。