RFC、ADR 与架构评审

架构决策是会影响多个模块、维护成本或用户体验的技术选择。例如资料助手生成报告要几分钟：让用户一直等着，还是先返回任务编号，完成后再通知？

团队需要把选择说清楚。RFC 用来提出方案、邀请讨论；架构评审把方案与实际需求逐项核对；ADR 保存最终决定及其理由。它们串起一个过程：提出、讨论、决定，条件变化时再复查。

1. 三种活动各自解决什么问题

RFC 是 Request for Comments，意思是“请求意见”。这里指工程团队的方案提案；文档里说明问题、备选方案和需要讨论的点。它可以修订，直到团队形成决定。

ADR 是 Architecture Decision Record，即架构决策记录。它通常围绕一个决定：当时遇到什么情况、选了什么、接受了什么代价。后人可以查到选择的背景。Michael Nygard 的 ADR 介绍提出了简短决策记录的写法。

架构评审是参与者一起检查方案的活动。开发看实现复杂度，运维看故障处理，产品看用户等待，安全人员看数据和权限。评审意见最终转成修改、待验证项或明确的决定。

可以把 RFC 想成会议前的议题材料，ADR 想成会议后的决定记录。两份材料保留不同信息：前者展示备选方案，后者方便今后追溯选择。

2. 先读一个完整提案

资料助手接受一份文档，检索资料并生成报告。产品给定目标：用户提交后 2 秒内看到确认；报告通常要 3 分钟，服务重启后仍能继续查看任务。

这些是方案设计输入。以下文档可以直接保存为 report-task-rfc.md，随正文逐项阅读：

# 提案：报告生成改为异步任务

## 问题
报告生成通常需要 3 分钟。
用户希望提交后 2 秒内知道任务是否已被接收，
并能在关闭网页后重新查看进度。

## 方案 A：同步请求
一次 HTTP 请求等待报告生成，然后返回完整结果。
接口较少，但连接长时间占用；用户刷新时较难区分
“服务还在生成”和“需要重新提交”。

## 方案 B：异步任务
提交接口保存任务后返回 task_id。
后台 worker 读取任务并生成报告。
查询接口按 task_id 返回状态和结果。
任务状态包括 queued、running、succeeded、failed。

## 倾向选择
采用方案 B，先保存任务，再返回已接收。
原因：满足快速确认与关闭页面后重新查询的需求。

## 需要讨论
1. 用户重复点击提交时，怎样复用同一任务？
2. worker 重启后，怎样恢复未完成任务？
3. 哪些身份可以查看结果？
4. 什么时候过期清理报告？

task_id 是任务编号，worker 是执行后台任务的进程。queued 表示排队，running 表示执行中，succeeded 表示成功，failed 表示失败。

这里最值得讨论的是提交时机。先返回“已接收”再保存任务，进程刚好崩溃就会丢任务。先成功保存，再确认接收，用户能拿着编号查询到它。

3. 沿一次运行过程做评审

先走成功路径：用户提交 → 保存任务 → 返回编号 → worker 生成 → 保存结果 → 用户查询。每一步问“状态放在哪里，下一步依靠什么”。

幂等键是客户端为一次业务请求提供的唯一标识；同一请求重发时，服务找到已经创建的任务。租约是一段有效时间内的任务执行权；租约到期后，其他 worker 可以领取。恢复执行时还要检查外部操作是否已完成，沿用前面学过的幂等与回读。

有了这些约定，评审结论可以是“补齐五项后接受”。每一条落实到接口、状态、代码或测试；“注意可靠性”这样的意见太笼统，很难执行。

4. 把决定写成 ADR

将下面内容保存为 report-task-adr.md。它与 RFC 使用同一个例子，读者可以对照检查：需求是否对应理由，风险是否对应措施。

# 决定：报告生成采用异步任务

状态：accepted（已接受）

## 背景
提交后 2 秒内需要确认接收；
报告生成约 3 分钟；
用户关闭页面后仍需要查询进度。

## 决定
提交接口先持久化任务，再返回 task_id。
后台 worker 生成报告。
状态和结果保存在任务存储中。
查询接口核对当前用户与任务归属。

## 备选方案
同步请求实现较短，但长连接等待与重提请求处理较难。
当前需求更重视快速确认和后续查询，选择异步。

## 后果
增加任务存储、查询接口和后台 worker。
幂等键解决重复提交。
租约与进度记录帮助执行恢复。
结果持久化后再发送通知，通知失败独立重试。
失败尝试有上限，耗尽后转为 failed。

## 验证
检查重复提交返回相同任务编号。
检查 worker 重启后可以继续领取未完成任务。
检查用户只能查看自己的报告。
检查通知失败后仍可通过查询取得结果。

## 重评条件
任务生成时间或并发量发生显著变化，
或结果保留要求发生变化时，重新比较方案。

accepted 表示决定已经被团队接受。提案讨论中可用 proposed；采用新决定替代旧决定时，旧记录变为 superseded，并注明新记录的位置。保留旧背景，才能解释当时为何选择了这条路。

上面的“验证”是实施后的检查清单。评审通过后，工程团队还要实际运行这些测试，确认系统行为与文档一致。

5. 改一个需求，看看理由是否还成立

把 RFC 中“报告生成通常需要 3 分钟。”改为“报告稳定在 100 毫秒内完成。”，其余需求保持不变。

同步方案的长时间等待问题明显减轻；但“关闭页面后查询历史报告”依然要求保存报告。两种方案可以重新比较：同步生成并持久化报告，或者继续使用异步任务。决定依据变成是否需要排队、任务取消与峰值保护，而不能沿用原先“生成很慢”的理由。

再换一种条件：报告时间仍为 3 分钟，但提交峰值从每分钟 10 份升到 300 份。异步仍方便快速确认，同时需要重新检查排队时长、worker 数量和模型配额。保留原选择、调整容量，是另一个合理结果。

架构评审也有分歧：产品想要“马上完成”，研发知道模型需要时间。先拆成“马上确认已接收”和“报告完成时间”两个目标，分别定义指标。争论于是落到可以观察和实现的条件上。

6. 让文档跟着实现更新

重要决定写成单独 ADR，RFC 中保留讨论背景。评审时同时打开接口定义、状态图和测试，检查三者对同一行为的描述是否一致。

实现改变时，先判断是细节修正还是架构选择变化：日志字段调整可以更新实现说明；同步改异步、模型调用跨越新的数据边界，值得另写一份决定。记录维护成本、已接受代价和重评条件，后来接手的人就能继续做判断。

下一次讨论“要不要加一个队列”，从用户等待、任务恢复和容量三个具体需求入手。RFC 展开选项，评审补齐运行条件，ADR 留下选择理由；这就是一次可以持续维护的架构决策过程。