实践_技术文档结构规范

一、概述

本文希望通过结构化的阐述方案设计过程，以及中间需要注意的点，来帮助大家更好的完成方案设计，并在此过程中补足方案本身的缺陷。

二、技术文档结构

1、背景

说明：通过对背景的描述，来让其他业务线的同学能够理解此方案要解决的问题。

1.1 名词解释

说明：对方案内涉及到的业务、技术名词做解释。

1.2 业务背景

说明：业务相关的背景知识。纯技术项目可以跳过。

1.3 演进历史

说明：介绍之前的技术方案是如何支持业务的，以及演变过程，对现在的影响是什么。全新项目没有历史包袱，可以跳过。

1.4 阐述痛点

说明：指出目前技术和需求之间的矛盾点，也就是技术方案要解决的业务问题。此处的痛点描述应避免太过于技术，使用用户、产品能感知的话术。
比如： 菜品下发不支持撤回，门店选择器响应慢。

2、设计目标

说明：明确要实现什么功能。

2.1 现状分析/场景梳理

说明：总结方案现状需要面临的场景，尽量做到不遗不漏，并带有一定的前瞻性。 此步骤没有做，很容易导致：方案实施过程中发现不满足需求要返工，方案扩展性差，导致后续要推翻重做。

2.2 非功能需求

说明：一般非功能需求包含以下内容： 安全：越权、用户隐私、注入攻击；性能：FPS、渲染时间、内存占用；稳定性：灰度、服务可用性。

2.3 优先级说明

说明：结合业务全局的目标，从重要性和紧急性两个维度说明需求的优先级，以及为什么这么决定。说明预计投入的资源。

2.4 预期收益

说明：说明在目标达成、问题解决之后，在性能、质量上能有多少收益。如：预计性能可以提升 xx% ；预计工单数量可以降低xx%，线下bug数量可以降低xx%。

3、问题分析

说明：对需求做抽象，从技术视角给出核心问题。

3.1 定义问题

说明：首先需要明确要解决的核心技术问题，针对核心技术问题，选择要调研的对象。

3.2 决策条件

说明：确定当前重要方案的重要考量是什么，当多个方案摆在面前时，我们应该如何选择。
如：在元数据的选型中，技术的稳定性和扩展性比性能更重要。

4、调研

说明：对比业界解决办法，原则上技术方案都需要此步骤。 但如果解决方案已经确定，或者技术方案较为简单，则可以省去此步骤。

4.1 调研对象

说明：罗列出来调研对象，大致说明每个方案的应用场景。

4.2 调研结果/方案对比

说明：说明不同方案的实现思路，对比优缺点，根据【决策条件】选择方案的技术路径。

5、解决方案

说明：根据【场景梳理】和【调研结果】，明确方案的思路，确认是否能满足场景诉求。

5.1 解决思路

说明：结合上述调研结果，言简意赅的提出大体方案的解决思路，方便读者阅读后续的架构视图。

5.2 逻辑架构图

说明：静态的结构图，用来描述方案设计到的组件、模块。 逻辑架构图应该体现组件、模块之间的依赖关系和调用关系，此关系应该是单向(由上至下)。
如果出现了反向依赖(由下至上)，则需要重新审视方案是否有问题，可能是抽象不彻底，或者职责划分不清晰。

5.3 运行流程图

说明：描述运行过程中，组件的调用过程。首先需要根据业务需求描述用户有哪些操作。然后使用流程图描述如下几个过程：
（1）初始化流程
（2）用户操作流程（不同的操作对应不同的流程）
（3）事件、推送响应流程
（4）销毁流程

5.4 数据架构图

说明：每个组件内部需要什么状态、以及状态的数据结构是什么样的；不同操作会读取/修改那些状态。

5.5 部署架构图

说明：项目依赖的部署架构，用户的请求/交互会有哪几类，网关/操作系统收到用户请求/交互之后，会调用哪些物理服务/设备，以及我们的应用在物理服务/设备上是如何分布的。 如果方案中没有对部署架构做修改，则不需要此项。

5.6 接口设计

说明：定义组件之间的接口各式，或者前后端交互的接口格式。

5.7 数据库表设计

说明：定义数据库表结构。

6、风险及应对措施

说明：明确方案可能在什么场景下出现什么问题，并对每一条case给出应对办法。

7、TODO

说明：总结文档中的TODO事项，明确处理人，预计完成时间以及进度。