break
370fd3e67f
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 10m49s
51 lines
3.9 KiB
Markdown
51 lines
3.9 KiB
Markdown
## Context
|
||
|
||
见 proposal.md。当前代理开放接口的查询 Module 持有读取型观测分发能力；其 Interface 只暴露一次分发调用，却隐藏了三阶梯任务、Redis 协调记录、Gateway 请求和 Integration Log。该能力与由稳定 Outbox 事实触发的可靠观测复用同一实现，导致高频查询获得了不属于它的可靠副作用。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
|
||
- 让代理开放接口查询的 Interface 只包含认证、数据范围校验和本地事实读取。
|
||
- 在查询 Module 与可靠观测 Module 之间移除读取型触发的 Seam，阻断查询量向 Redis/Asynq 放大的路径。
|
||
- 保持持久化业务事实经 Outbox 触发可靠观测的现有行为不变。
|
||
|
||
**Non-Goals:**
|
||
|
||
- 不改变查询响应字段、认证、数据范围或把查询改为同步 Gateway 查询。
|
||
- 不修改 Redis `maxmemory`、淘汰策略或手工删除可靠协调、队列、流量事实 key。
|
||
- 不迁移个人客户、后台资产读取或设备控制入口；这些入口在本变更后仍需单独审查其是否应持有读取型观测能力。
|
||
- 不在本变更中缩短可靠业务事实的 24 小时协调保留时间。
|
||
|
||
## Decisions
|
||
|
||
### 删除查询后的观测触发，而非增加节流层
|
||
|
||
代理开放接口的查询在组装响应前读取的是本地持久化事实，随后才异步提交观测；该提交不会改善当前响应。删除查询成功后的卡与设备绑定卡分发调用，能使一次查询不产生 Redis 写入、Asynq 任务或 Gateway 请求。
|
||
|
||
不采用按卡节流、开关或另一套短 TTL 协调 Module。它们会保留“读取隐式发起外部副作用”的错误 Interface，并继续让调用方承担隐藏的资源成本。若未来确有查询新鲜度承诺，应以独立 Change 定义新鲜度语义和有界实现。
|
||
|
||
### 将可靠观测的触发 Seam 收回到持久化业务事实
|
||
|
||
可靠观测继续由业务事务写入 Outbox、Worker 消费稳定事件并触发。稳定事件键、三阶梯任务和 Redis 协调 Adapter 都留在可靠观测 Module 的实现内；代理开放接口查询不再接触该 Module。
|
||
|
||
这保持可靠业务写的幂等语义，同时让查询 Module 的 Interface 不再拥有无界任务创建能力。修改集中在代理开放接口 Module 及其 bootstrap 装配，获得更好的 Locality。
|
||
|
||
### 本次不全局缩短 24 小时协调保留
|
||
|
||
`cardsync:schedule`、`cardsync:attempt` 和完成标记目前共同使用 24 小时保留。它们同时覆盖三阶梯任务执行、Outbox 重投和迟到重复投递；全局缩短会改变可靠业务事实的重复消费语义。
|
||
|
||
自动 Outbox 重试上限为 10 次，指数退避累计约 73 分钟，但人工重放和任务积压的可接受窗口尚未形成业务契约。本变更先消除产生 95% key 的读取源头；后续应根据可靠事件的重放窗口，将不同协调记录拆分为各自有明确上限的保留策略。
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- [调用方曾依赖查询后最终刷新本地事实] → 当前开放接口 Spec 未承诺该行为，且查询不等待刷新结果；继续由既有轮询、回调和业务事实驱动更新。若确认存在新鲜度承诺，另建 Change 定义该承诺。
|
||
- [旧版 API 二进制回滚] → 回滚会恢复高频查询触发；发布后优先观察 Redis key 数、OOM 错误和开放接口调用量，只有 API 可用性故障才回滚。
|
||
- [其他读取入口仍保留同类能力] → 本变更只切断已证实的生产主来源；后续按入口的真实新鲜度契约审查，不在事故修复中猜测性改动。
|
||
|
||
## Migration Plan
|
||
|
||
1. 发布包含本变更的 API 二进制；Worker、Redis 配置和现有队列不作迁移或清理。
|
||
2. 发布后以只读方式核对开放接口成功查询不再增长 `cardsync:*`，并持续观察 `DBSIZE`、`INFO memory` 和 `INFO errorstats`。
|
||
3. 已有协调 key 按现有 TTL 自然过期。若 API 功能不可用，恢复前一 API 二进制；不得通过清空 Redis 处理回滚。
|