方案文档写作

1 方案文档写作要回答什么

方案文档是把业务诉求变成可讨论、可决定、可交付事项的共同记录。它的价值不取决于页数，也不取决于出现多少架构名词，而在于读者能否沿着证据回答：要解决什么问题，哪些条件已经确认，比较过什么选择，为什么这样选，投入多少，失败时怎么办，以及怎样判断交付完成。图可以帮助理解关系，文字则必须交代关系成立的条件。

本课持续使用零售订单 API 的案例。门店和线上商城通过同一组接口创建订单、查询订单状态。订单服务保存订单，并与库存、支付系统协作。为便于练习，先提出待业务确认的工作基线：促销峰值每秒 300 次创建请求，创建接口服务端响应时间的第 95 百分位不超过 800 毫秒，月可用性目标为 99.9%。第 95 百分位表示约 95% 的请求耗时不高于这个值；具体统计口径仍需在文档中定义。

这些数字是案例的设计输入，并不代表系统已经达到目标。文档要把“业务提出的目标”“团队采用的假设”和“测试得到的结果”分别标明。例如，每秒 300 次来自促销预测，属于待确认输入；800 毫秒属于拟定验收目标；某次压测的 620 毫秒才属于测量结果。如果把这 3 类内容写成同样确定的陈述，后续读者就无法判断哪些结论可以依赖。

订单 API 的方案还必须解释“创建成功”的业务含义。本课暂定：订单持久化成功后返回订单号和“待支付”状态，支付结果稍后更新；库存尚未确认时只能返回“处理中”，不能承诺商品已锁定。这个约定需要业务签认。它决定响应内容、异常提示和验收用例，也影响是否需要异步处理。先明确承诺，再选择技术，比先画出复杂组件图更有用。

可以把方案看成可追溯的论证链：需求引出约束，约束形成候选方案，比较形成决策，决策带来成本与风险，最后由验收证据检查承诺。链条中任意位置都可以提出问题。若读者问“为什么需要多个服务实例”，答案应指向故障恢复目标和容量依据，而不是“这是行业最佳实践”。文档允许结论被挑战，但必须让挑战找到具体落点。

写作开始时，先用 1 段话概括问题与推荐结论，再展开证据。订单案例可以写为：“为支持促销期间的订单创建，建议采用无状态订单服务、共享持久化存储和明确的重复提交规则；通过多实例与故障切换降低单点中断影响。是否满足目标，需由容量测试与故障演练确认。”这段话同时交代方向和证据边界，使后续章节有清楚的中心。

2 读者、决策与证据

同一份方案通常服务于不同读者。业务负责人关心用户会看到什么、何时上线和失败后的处理；研发负责人关心接口边界、数据责任和实现依赖；运维人员关心部署、监控、恢复与值守；审批者关心成本上限、关键风险和待决事项。写作时无需为每类读者复制整份正文，但需要提供能直接进入相应结论的阅读入口。

正文首页可以放置“待决事项表”，每行只表达 1 个需要作出的决定。订单案例的事项包括：创建成功是否要求库存确认、是否允许促销时进入排队状态、首期采用哪种部署范围。表中写出推荐项、决定者、决定期限与依赖证据。这样，评审者能区分“需要批准的选择”和“实现团队自行处理的细节”，避免会议在组件命名上消耗时间，却遗漏业务承诺。

证据必须与主张相匹配。主张“用户不会因网络重试产生重复订单”，需要重复请求测试和订单记录核对；主张“服务能承受峰值”，需要说明请求比例、数据规模和持续时间的容量测试；主张“实例故障后可以恢复”，需要故障演练记录。截图可以辅助说明，但单独的绿色监控面板无法证明完整业务链路正确，更不能代替测试条件。

当比较多个技术选择时，可以用架构决策记录，即 ADR，保存决定。入门阶段不必追求复杂格式，只需包含背景、候选项、决定、理由、代价和重新评估的触发条件。例如，候选 A 让订单创建等待支付完成，候选 B 先保存待支付订单再接收支付结果。若业务允许待支付状态，B 能减少创建接口对支付耗时的直接依赖，但会增加状态查询和超时关闭的处理责任。

ADR 的理由不能只写“性能更好”。应写明：在支付结果可能延迟的条件下，推荐 B；用户拿到订单号不等于支付成功；需要补充状态通知与超时处理；若业务要求创建响应即代表收款完成，则重新评估。尚未测量的性能收益要标为预期。记录限制并不会削弱结论，反而使读者知道结论何时有效，也能在需求变化时判断是否需要重做决策。

3 范围、假设与风险清单

范围的作用是把承诺边界变成可以核对的清单。本课首期范围包括创建订单、查询状态、重复提交识别、支付结果接收和必要的运行监控。退款、会员积分、跨境税费计算暂不包含，但必须写明它们与订单数据的接口关系。排除范围不能成为忽略依赖的借口：即使退款本期不实现，订单状态设计也不能宣称所有售后场景已经覆盖。

假设要写成能够确认或证伪的句子。“库存系统稳定”无法检查；“库存预留接口具有请求标识，并允许按该标识查询处理结果，负责人在接口联调前确认”则可以跟踪。每条重要假设至少写出来源、确认人、截止节点和失效影响。若库存接口不能查询结果，订单服务在请求超时后就无法仅凭超时判断是否预留成功，需要重新设计对账和人工处理流程。

风险与问题也应区分。风险是尚未发生、但可能影响目标的事件；问题是已经出现、需要处理的事实。“促销流量可能高于预测”是风险，“压测在每秒 240 次创建时已出现持续排队”是问题。前者需要触发条件与预案，后者需要整改任务和验证结果。把已发生的问题放在风险表里，会让交付状态显得比实际更乐观。

订单案例可维护 1 张简洁的风险表。每条记录包含事件、影响、预警信号、应对措施、责任角色与剩余风险。例如，支付回调延迟会使订单长时间停留在待支付；信号是待支付订单的年龄分布异常；措施包括按约定查询支付结果、提示用户稍后查看和启动人工核对。即使这些措施可用，短时间内状态不一致的风险仍然存在，应告知业务并约定处理时限。

高可用性也必须放进边界讨论。部署多个订单服务实例，只能降低其中部分实例故障的影响；若持久化存储、库存接口或入口仍存在单点，整体服务仍可能中断。方案应分别写清正常路径、实例故障路径和依赖故障路径。对于存储切换期间的请求，要说明返回失败还是处理中、客户端能否重试、怎样核对已有订单。不要把“部署在多个可用区”直接写成“订单不会失败”。

本课暂以恢复时间目标 5 分钟、已确认订单的恢复点目标为 0 作为需要验证的设计目标。前者指在约定故障范围内恢复核心服务所需的时间，后者指希望不丢失已经确认的数据。它们不是任何部署方式天然具备的能力，必须核对存储确认规则、故障范围和演练结果。若当前方案无法提供证据，就应公开缺口、调整承诺或安排补充验证，而不是在文档里省略。

4 动手：改写一节为可验收条款

先看常见原句：“订单服务采用高性能架构，支持高并发，保证稳定可靠，具备完善的异常处理能力。”它表达了愿望，却没有交代负载、环境、成功含义和失败判断。改写时先圈出不能直接观察的词，再逐个询问：谁执行验证，在什么条件下，用什么输入，观察什么结果，以什么标准判定，证据保存在哪里。写作练习的目标是让另一个团队能够据此安排验证。

第 1 步是固定场景。假设测试数据为 100 万条历史订单，创建与查询请求比例为 3∶7，创建峰值每秒 300 次，对应总请求每秒 1000 次，持续 30 分钟。库存、支付依赖的响应特征必须写明采用真实联调还是模拟。模拟结果只能说明设定条件下的能力；如果模拟忽略依赖延迟，就不能把报告当作真实链路的验收结论。测试资源配置也应作为报告附件保存。

第 2 步是写出指标口径。创建接口的服务端耗时从入口接收请求开始，到写完响应结束；统计所有被正常受理的合法请求，并按成功、业务拒绝、系统错误分别报告。超过约定峰值而被限流的请求单独统计，不能静默移出报告。案例可约定合法创建请求的系统错误比例低于 0.1%，第 95 百分位耗时不超过 800 毫秒；业务拒绝是否符合规则则另做正确性检查。

第 3 步是补上业务不变量，即无论请求如何重试都应该成立的规则。对相同商户、相同请求标识且内容一致的创建请求，在约定的 24 小时去重窗口内只能形成 1 个订单，并返回同一订单号；相同标识但内容不同，应明确拒绝并返回约定错误。24 小时是本案例拟定值，仍需业务确认。测试要覆盖并发提交、首次响应丢失、超时重试和服务重启后的重试。

第 4 步是把异常变成验证步骤。执行创建后，在客户端收到响应前中断连接，再以相同请求标识重试。验收时不仅查看 HTTP 响应，还要核对订单记录、状态变化和关联日志，确认没有重复订单。若只检查第 2 次请求返回成功，就可能遗漏首次请求已经留下的多余记录。测试数据应使用专门的测试商户，并记录清理范围，避免验证动作影响真实交易。

第 5 步是分配证据与责任。可验收条款可以写为：“测试负责人在预发布环境执行上述负载与重试用例，保存带版本号的报告、指标时间区间和订单核对结果；研发负责人处理偏差，业务负责人确认成功状态语义。任意核心条款未满足时，不得以总体平均值通过验收。”这使验收从口头印象变成可追踪任务，也让失败后的处理方式提前明确。

最后检查条款之间是否相容。月可用性 99.9% 不能由 30 分钟压测直接证明，压测只能提供容量方面的证据。可用性还需要约定统计周期、探测方式、故障范围与排除项；恢复目标需要演练；重复提交规则需要正确性测试。将这些证据分别关联到条款，能够避免用某份“全部通过”的报告包办所有承诺。没有证据的条款应保留为待验证项。

5 完整与可读取舍

完整不是把全部资料塞进正文，而是让每个重要结论都能找到足够依据。建议按阅读任务组织层次：首页交代问题、推荐结论与待决事项；正文解释范围、主要路径、候选方案和关键取舍；附录保存接口字段、估算明细与测试记录。正文引用附录时写出版本与位置，避免“详见附件”却没有可定位对象。读者应能先理解决定，再按需要追查细节。

订单方案通常需要 3 种互补视角：系统边界说明谁与谁交互，请求流程说明先后关系，运行视角说明如何发现与处理异常。每张图只承担清楚的阅读任务，并与文字采用同一组名称。如果图里叫“交易中心”、接口里叫“订单服务”、成本表里又叫“核心平台”，读者很难判断是否为同一个组件。命名一致是减少阅读成本的基础，不只是排版问题。

成本章节尤其需要可读取舍。先列订单服务计算资源、持久化存储、网络、日志与监控、备份以及演练环境，再补充建设和日常维护的人力。以月度资源成本为例，可以用“固定配置成本＋请求相关用量成本＋容量余量”表达估算结构，同时标注币种、估算日期、含税口径和用量假设。没有可靠单价时可以给区间和待补项，不应编造精确到个位的预算。

成本与可靠性之间也不能只写“增加副本，费用翻倍”。实例数变化只影响部分资源，存储、备份、网络和维护工作可能遵循不同规律。评审应看到增加投入具体缓解什么故障，以及还有什么缺口。若预算暂时只支持有限的容灾范围，应写明可接受的中断与数据风险，并由有权承担该风险的角色决定。技术团队负责提供依据，不能用模糊措辞代替风险接受。

这里的交互用文档篇幅预算演示取舍：预算较小时优先保留结论、范围、证据索引和最高风险；预算增加时再展开候选比较、故障场景与成本敏感项。滑块表示教学用的内容分配规则，不预测工程效果。压缩篇幅不能删除关键假设和验收口径，展开篇幅也不能靠重复定义填充。合理的精简是把可独立查阅的细节移到附录，并保留从结论到证据的链接。

交付前可请未参与设计的同事进行限时阅读：在 10 分钟内找到推荐方案、核心业务承诺、最高风险和待决定事项。找不到时，先调整结构与结论位置，再考虑补充文字。这类阅读检查评价的是信息可达性，不能替代技术评审。方案需要同时做到“容易找到”和“依据可靠”，任何一项缺失都会增加交付中的沟通成本。

6 常见坑：堆砌术语无结论

第 1 类问题是术语代替判断。例如“采用微服务、缓存、消息队列实现高可用”，没有说明各组件承担什么责任，也没有解释为何适合订单场景。改写时可以逐句追问：它解决哪条需求，代价是什么，没有它会发生什么，需要什么证据。若无法回答，就先移出主方案，或标为待研究候选。初学者无需讲解这些组件的内部算法，但必须说明引入它们的理由。

第 2 类问题是把候选方案写成配置列表。列出 A、B 的实例数量，却不比较创建语义、依赖失败影响、运维能力和成本，就无法支持决策。比较维度应来自真实约束，并允许出现“不满足必须条件”的结论。例如，若同步等待支付的选项无法在已知支付延迟下满足响应目标，就应说明冲突，不能通过给其他优点打高分把硬约束平均掉。

第 3 类问题是错误使用数字。平均耗时掩盖慢请求，日均流量掩盖促销峰值，资源单价掩盖总用量，单组件可用性掩盖完整链路故障。数字必须带上对象、时间窗口、单位和来源。“支持 1000 并发”尤其含糊，它可能指连接数、在途请求数或每秒请求数。订单方案应使用明确的负载描述，并把并发连接等补充条件放在测试说明中。

第 4 类问题是故障章节只有“自动重试”。网络超时只说明调用方没有按时拿到结果，不能证明服务端没有创建订单。若客户端换用新的请求标识重试，就可能产生重复业务。文档必须画出不确定结果出现的位置，说明如何使用原标识查询或重试，何时提示处理中，何时进入人工核对。高级一致性机制可以留到后续学习，业务结果的承诺边界现在就要写清。

第 5 类问题是把“未来补齐”散落在各段落。诸如限流阈值待定、恢复演练待安排、库存接口待确认，都可能影响上线。应汇总为待办清单，注明负责人、截止节点、阻塞关系和当前状态。若某项阻塞验收，就直接标注；若允许带风险上线，则记录决定者、有效期限和后续措施。没有责任人与期限的待办，只是在把不确定性向交付阶段转移。

还要防止文档之间互相矛盾。正文说创建成功代表待支付，接口示例却返回已完成；ADR 决定先做单区域部署，成本表却按多区域估算。这些问题往往来自复制旧版本。维护时应指定关键事实的权威位置，在其他位置引用它，并在变更时检查关联条款。无需建立复杂工具，先把版本号、术语表和变更清单用好，就能减少大量误解。

7 案例：需求理解偏差靠文档暴露

某零售团队收到需求：“促销时也要快速下单，不能重复扣款，门店可以立即看到订单。”研发最初理解为先保存待支付订单，支付完成后更新状态；业务负责人理解为用户看到成功页面时，库存与付款都已确认；门店则把“立即看到”理解为订单可直接进入备货。口头讨论中，所有人都同意“下单成功”，实际却指向不同的业务状态。

方案作者没有先扩展架构图，而是补上创建响应示例、状态说明和故障流程。示例写明：“返回订单号与待支付状态；该响应不表示已付款，也不表示允许备货。”业务随即指出，这不符合原先对成功页的理解。偏差在开发前暴露，修改成本主要是评审和文档调整。若直到门店试运行才发现，接口、页面和操作培训都可能需要重做。

接着，团队把原需求拆成可决定的问题。用户何时获得订单号，何时显示支付成功，门店何时看见记录，何时允许备货，支付超时后怎样提示，分别由业务确认。最终约定创建响应只承诺订单已保存；门店可以看见待支付订单，但只有进入已支付且库存已确认的状态才允许备货。各状态的责任系统与转换条件成为接口与验收的共同输入。

“不能重复扣款”也被拆开处理。订单 API 的去重规则只能直接约束重复订单，不能自动证明支付系统不会重复扣款。支付请求需要独立的业务标识，支付结果需要核对，责任边界由支付接口约定说明。方案记录这项依赖，并安排支付团队提供相应测试证据。这样既保留业务目标，也避免订单团队承诺超出自身控制范围的结果。

这次澄清还改变了成本与风险判断。先保存待支付订单意味着需要维护超时关闭、状态查询和异常核对；门店可见性又增加了状态展示与权限要求。ADR 因此补充了新增工作量和剩余风险，成本表随之更新。技术选择并没有因为文档更清楚而变得免费，但评审者终于能看到承诺背后的完整责任，而不只是创建接口的响应速度。

案例的关键证据是需求确认前后的差异记录，而不是会议参加人数。记录应包括原句、发现的歧义、确认后的条款、影响的接口与测试、决定者和日期。后续如果有人要求“所有订单立即备货”，团队可以指出这改变了已确认状态规则，进而评估库存与支付依赖。文档由此成为变更讨论的起点，帮助团队追溯理由，而不是阻止合理变化。

8 把文档模板写进交付规范

模板应规定每份方案必须回答的问题，并允许作者按项目规模调整篇幅。订单 API 的交付规范可以要求：问题与目标、读者和待决事项、范围及假设、主要流程、候选比较与 ADR、成本、风险及高可用安排、验收与发布准备。小项目可以简写，但关键项目不能仅因篇幅短而省略。没有相关内容时，应说明为何不适用，避免留下无法判断的空白。

每个章节最好附上完成条件。例如，需求章节需要需求编号与确认状态；成本章节需要日期、用量和排除项；风险章节需要责任人与剩余风险；高可用章节需要故障范围、恢复目标和验证计划。完成条件比“写得详细”更容易执行，也能帮助新作者发现缺口。模板中的示例必须标明是示例，避免案例数字未经确认就流入正式承诺。

交付包可以包含正文、ADR、接口说明、证据索引和变更记录。证据索引记录文档版本、软件版本、测试环境、报告位置及结论，方便上线前核对。依赖的报告暂未生成时，索引应显示待完成状态和责任人。不能提前写“验收通过”，再等报告补齐；也不能让某次旧版本测试无条件证明新版本能力。证据与被证明对象必须对应。

评审流程宜区分不同目的。需求确认检查业务含义，设计评审检查选择与边界，交付检查核对实现证据和遗留问题。它们可以在小团队中合并会议，但检查目标仍然要清楚。评审记录需要注明批准了什么、附带什么条件、哪些事项仍待决定。条件批准不能被转述为所有条款已满足，未关闭条件应持续出现在交付清单中。

规范还需要变更规则。需求、流量预测、部署范围或关键依赖变化时，作者要评估受影响的 ADR、成本、风险和验收条款，再更新相关版本。例如峰值由每秒 300 次创建调整为 600 次，不能只替换需求表里的数字，还应重新检查容量证据、限流策略与资源估算。小幅文字修正可直接留痕，影响承诺的变化则需要对应角色重新确认。

最后明确维护责任。方案负责人协调更新，不代表独自承担所有结论；业务、研发、测试、运维各自确认负责的部分。交付后保留实际运行中发现的偏差，并把它们反馈给下一次方案写作。模板是否有效，可以观察评审中反复追问的事项是否减少、验收是否容易执行、变更能否找到依据，而不应仅统计文档数量或平均页数。

9 从方案文档写作走向方案讲解与答辩（P34）

完成文档后，先尝试脱离目录，用简短表达串起订单方案：业务需要促销期间稳定创建订单；我们先确认成功状态与重复提交规则，再比较同步等待和先保存待支付订单的选择；推荐方案的成本、依赖风险与恢复安排都有边界，最终通过正确性测试、容量测试和故障演练验证。若这条主线说不清，通常意味着正文仍存在结论分散或理由断裂。

讲解准备不等于把全文复制到演示页。可以从文档中提取问题、推荐决定、关键取舍、最高风险和待审批事项，并为每项准备证据入口。例如被问到“为什么不等支付完成再返回”，应先说明业务确认的成功语义与耗时约束，再展示 ADR；被问到“多实例能否保证不停机”，应指出已覆盖和未覆盖的故障，以及演练结果。回答必须与文档版本一致。

答辩中遇到未知问题，应准确区分未确认需求、未完成验证和超出当前范围的议题。对于“库存连续不可用 30 分钟会怎样”，如果现有方案没有验证，就记录待补的故障场景、责任人与决定期限，并说明当前承诺边界。现场推测可以作为讨论假设，但不能立刻变成已证明结论。保持证据边界，才能让后续补充工作有明确方向。

进入 P34 前，可以自查：任取 1 条核心承诺，是否能找到需求来源、决策理由、责任角色和验收证据；任取 1 项高风险，是否知道触发信号、处理措施和剩余影响。如果只能找到术语或组件名称，就继续补齐论证。下一课将围绕这些已经写清的内容练习讲解顺序、问题回应和决策推进，让方案在交流中得到准确理解。

放进方案里

本项目为零售订单 API 建立可评审、可验收的方案基线，覆盖创建订单、查询状态、重复提交识别与支付结果接收；退款、积分和跨境税费不在首期范围。创建成功暂定义为订单已持久化并返回待支付状态，不代表付款完成或允许备货。该定义、门店可见条件及库存确认责任须由业务与接口负责人共同确认，确认记录作为接口和验收的依据。

容量设计输入暂为峰值每秒 300 次创建，创建与查询比例为 3∶7。拟定验收条件为 100 万条历史订单、持续 30 分钟目标负载下，合法创建请求的第 95 百分位服务端耗时不超过 800 毫秒，系统错误比例低于 0.1%。报告需记录环境、依赖条件、软件版本和统计口径。相同商户与请求标识在拟定的 24 小时窗口内应返回同一订单号，内容冲突应明确拒绝；窗口长度待业务确认。

推荐先保存待支付订单，再按支付结果更新状态，ADR 同时记录同步等待方案未被采用的理由，以及超时关闭、状态查询和异常核对的新增责任。高可用设计采用多实例并检查存储与外部依赖的故障路径，恢复时间 5 分钟、已确认订单恢复点为 0 作为待验证目标。多实例配置本身不能证明目标成立，容量测试与故障演练分别提供对应证据。

成本估算覆盖计算、存储、网络、日志、备份及维护人力，标明日期、用量、区间与排除项。主要风险包括库存结果不确定、支付回调延迟及流量超预期，每项指定触发信号、责任人与剩余风险。上线前核对验收报告、恢复演练和阻塞事项；未满足的条件需关闭或由有权角色明确接受。需求与峰值变化时，同步复核 ADR、预算、风险及验收条款，并保留变更记录。

10 小结：下一步方案讲解与答辩（P34）

方案文档把需求、选择、理由、代价、风险与证据连成可追溯的链条。零售订单 API 的写作重点是明确创建成功的含义、把重复提交与故障路径写清，并为容量、成本和恢复承诺提供相应依据。

请带着当前方案进入 P34：准备说明推荐决定、最重要的取舍和仍需批准的事项，同时能够定位支持它们的证据。讲解与答辩将继续检验文档是否真正支持理解和决策。