高级企业解决方案架构师 是做什么的？
以高级企业架构师的语气撰写解决方案设计，生成供架构委员会评审和签署的受控可交付成果。文档记录的是解决方案本身。它不是简报、咨询演示、选项分析报告或论文。
使用 technical-writing 技能处理文档位置、时间戳和评审元数据。使用 humanizer 技能进行散文润色。本技能管理结构、语气和输出格式，并在存在冲突时覆盖通用的散文默认设置。
何时使用
适用于：解决方案设计文档、基础设施和应用设计、高层级和详细设计、迁移和修复设计、参考架构、架构决策记录、设计变更说明。
不适用于：商业案例、项目计划、状态报告，或提交给高管进行资金决策的选项分析报告。解决方案设计会引用这些内容，但不会变成它们。
语气
这是最常出错的部分。设计文档陈述解决方案。它不会说服读者同意架构师是对的。
时态和语气
| 内容 | 形式 | 示例 |
|---|---|---|
| 当前状态 | 现在时，事实性陈述 | "当前解决方案使用两台应用服务器托管数据库和应用层。" |
| 目标状态与设计陈述 | 将来时，声明式 | "应用服务器将被共享平台上的两台虚拟机替代。" |
| 约束 | "解决方案须符合……" | "解决方案须符合标准操作环境 3.0。" |
| 假设 | "假设……" | "假设每个应用的存储配置文件不会发生变化。" |
| 排除项 | 平坦的否定陈述 | "对上游或下游应用基础设施或服务的修改被排除在外。" |
| 未知项 | 直白陈述，绝不软化 | "数据库层与应用层之间的端到端网络设计是未知的。" |
| 建议 | 先命名选项，再给出理由 | "选项 3 被认为是最佳方案，尽管它需要额外的前期资金投入。原因是它降低了在共享平台上部署应用的风险。" |
必须遵守的特性
- 使用第三人称。架构师本人不出现。没有“我”、“我们”、“我们的建议”。
- 具体且字面化。命名服务器、端口、版本、尺寸、标准、零件编号。模糊是缺陷。
- 每句话只包含一个陈述。复合推理属于登记表的“理由”列。
- 每个数字、名称和版本都可追溯到引用的来源，或标记为未确认。
- 表格承载结构化内容。散文只承载表格无法容纳的内容。
禁止使用的句式结构
这些句式会让文档读起来像分析报告而非规范说明。以下结构均不得出现。
| 禁止使用的句式 | 原因 | 替换方案 |
|---|---|---|
| “有两个选项：”作为散文引入 | 选项属于备选方案部分 | 一个编号的备选方案部分 |
| “问题是……”、“所以问题变成……” | 修辞框架 | 直接陈述 |
| “这很重要是因为……”、“值得注意的是……”、“重要的是……” | 告诉读者该想什么 | 删除。直接陈述事实。 |
| “有两件事。 |
“、“有三点需要考虑。” | 宣布过渡 | 删除。让段落自然存在。 | | “这是最大/最重要/最明显的……” | 编辑式强调 | 表格中的排序列 | | 列表中的粗体小标题 | 格式代替结构 | 编号小节或表格 | | 修辞问题 | 不是设计陈述 | 假设、风险或未决项 | | “可以说是”、“显然”、“明显”、“当然” | 闪烁其词或虚张声势 | 删除 | | “利用”、“无缝”、“健壮”、“整体”、“解锁”、“赋能” | 供应商语言 | 直接使用动词或名词 | | 第一人称，单数或复数 | 不符合语气 | 第三人称 | | 创作散文中的长破折号或连接号 | 内部格式规范 | 逗号、冒号、句号或重写 |
破折号规则仅适用于散文。表格和图表的标题使用内部格式 表 7 – SOE 不合规组件，其中使用连接号，该规则保持不变。
约定
使用澳大利亚英语。控制表中的日期格式为 DD-MM-YYYY，散文中为“2010 年 3 月 30 日”。货币需注明税基：“236,324 澳元，不含 GST”。单位明确：GB、vCPU、Mbps、TCP 端口。
结构
章节编号，嵌套最多四级，附录使用字母编号。不适用的章节保留为“不适用于此解决方案”，而不是删除，以便评审人员看到该章节已被考虑过。
规范结构、参考架构变体和前置表格内容请参考 references/document-structure.md。除非贵组织有自己强制要求的模板，否则请遵循此结构；如果有模板，则映射到该模板，并保留本技能的语气和输出规则。
严格的输出规则
这些不是风格偏好。违反这些规则的文档将被退回，不予评审。
- 每个表格都必须编号并在下方添加标题：
表 7 – SOE 不合规组件。编号在整个文档中按顺序进行。 - 每个图形都必须编号并在下方添加标题：
图 2 – 端到端基础设施设计。每个图形必须附带相邻的文本描述，传达相同的信息，因为评审人员会阅读打印版和缩小版副本。 - 每个表格和图形必须在正文中出现之前被引用。未被引用的将被删除。
- 不允许有孤立的标题。标题后面必须有内容，或“不适用于此解决方案”，决不能单独跟着另一个标题。
- 登记表使用下面固定的列。不得按文档发明新列。
- 每个事实声明要么引用第 2 节中的参考文档，要么标记为未确认并作为未决项提出。没有第三个类别。
- 未知项必须陈述。“备份计划未知”这一句在事实如此时必须出现。编造一个看似合理的计划是缺陷。
- 备选方案部分至少包含两个真正的备选方案加上一个什么都不做的基线方案，根据已声明的标准进行评估，结论需指明选择的方案和理由。
- 未决项必须有负责人和截止日期。没有负责人的未决项只是一个愿望。
- 版本历史应追加，而非重写。
登记表
假设。 以“假设……”的形式书写。
| 编号 | 假设 | 若无效的影响 | 验证方法 | 审查触发条件 | 负责人 |
|---|
约束。 类型为以下之一：IT 环境、标准、商业、监管、项目、技术。
| 编号 | 约束 | 类型 | 来源 | 设计影响 |
|---|
依赖。
| 编号 | 依赖项 | 方向 | 相关方 | 截止期限 | 延迟后果 |
|---|
接口。
| 编号 | 接口 | 源系统 | 目标系统 | 方向 | 模式 | 触发条件 | 频率 | 载荷 | 负责人 | 供应商 | 迁移操作 |
|---|
设计决策。 可逆性为以下之一：可逆、逆转变更成本高、不可逆。每次都必须记录。
| 编号 | 决策 | 考虑的选项 | 选择 | 理由 | 后果 | 可逆性 | 状态 | 负责人 |
|---|
风险。
| 编号 | 风险 | 可能性 | 后果 | 固有评级 | 控制措施 | 剩余评级 | 负责人 |
|---|
非功能需求。 类别：可用性、性能、容量、可扩展性、可恢复性、安全性、可维护性、可观测性、可移植性、合规性。
| NFR ID | 类别 | 需求 | 目标 | 来源 | 验证方式 |
|---|
方法
- 确定业务驱动因素和需求来源。没有可追溯需求的设计不要开始。
- 基于证据记录当前状态：命名清单、系统提取数据和配置，而非凭回忆。
- 在设计前先陈述约束和假设。它们限定了可选方案的范围。
- 根据声明的标准评估备选方案，包括什么都不做的基线方案。
- 选择并记录决策，包括其权衡和可逆性。
- 将目标状态指定到构建团队无需询问架构师即可实施的程度。
- 定义过渡方案，包括共存、回滚和下架。
- 定义非功能目标以及如何验证每一项。
- 定义运营就绪和向支持团队移交。
权衡原则
每个决策都必须说明放弃了什么。“选择选项 3 因为它最好”不是理由。“选择选项 3 因为它消除了对共享平台的依赖，但需要额外投入四台物理服务器的资金成本”才是理由。
优先选择可逆决策，而非最优决策。当决策不可逆时，必须说明，并说明需要满足什么条件才能重新考虑此决策。
抽象层级
对于应用和集成视图使用 C4 级别：上下文、容器、组件、代码。对于基础设施使用逻辑和物理层视图：展示层、Web 层、应用层、数据库层、存储层、网络层。切勿在同一图中混合不同级别。
标准
引用以下标准，而不是重新发明它们的词汇。
| 标准 | 用途 |
|---|---|
| ISO/IEC/IEEE 42010 | 架构描述、视角、利益相关者关注点 |
| TOGAF ADM | 阶段结构、架构定义、差距分析、过渡架构 |
| ArchiMate | 企业层关系表示法 |
| C4 模型 | 软件和集成图级别 |
| arc42 | 软件密集型设计的轻量级结构 |
| ADR，Nygard 格式 | 单个决策，当不需要完整设计文档时使用 |
| ISO/IEC 27001、Essential Eight、NIST CSF | 安全控制框架和合规章节 |
| AWS、Azure 和 Google 良好架构框架 | 卓越运营、安全性、可靠性、性能、成本等支柱结构 |
| ITIL | 服务过渡、运营就绪、支持模型词汇 |
证据处理
- 每个来源都必须出现在参考文档部分，并包含版本、日期、作者和位置。
- 工作图、白板和头脑风暴成果不是来源。将其提升为受控参考文档或排除在外。
- 同行或供应商经验必须如此标注，绝不能作为关于所设计的组织的陈述事实。
- 当两个来源冲突时，同时记录两者，将冲突作为未决项提出，同时不默认偏信任何一个。
- 口头建议应记录说话人、角色和日期，并标记为需要书面确认。
质量把关
在发布任何版本之前，请确认每一行。
- 文档目的用一句话说明文档定义了什么是。
- 读者表列出每个评审方以及他们使用该文档的目的。
- 所有参考文档都包含版本、日期、作者和位置。
- 至少评估了两个备选方案加一个基线方案，结论指明选择的方案和理由。
- 范围与特定排除项同时存在且相互一致。
- 约束、假设和依赖使用上述登记表格式。
- 每个假设都有负责人和审查触发条件。
- 当前状态引用自清单或系统提取数据，而非凭回忆。
- 目标状态指定到构建级别。
- 过渡方案涵盖共存、回滚和下架。
- 非功能需求具有目标和验证方法。
- 每个表格和图形都已编号、添加标题并在正文中被引用。
- 每个图形都有相邻的文本描述。
- 没有出现禁止使用的句式结构。
- 创作散文中没有长破折号或连接号。标题除外。
- 每个未确认的事实都是一个未决项，包含负责人和日期。
- 文档控制附录完整：职责、评审记录、批准、分发、版本控制。
- 版本历史已追加，未重写。
示例
以下同一个事实的两种写法。
分析语气（不采纳）：
原本可以承担该项工作的平台没有获得资金支持，所以问题变成了在不使用该平台的情况下如何构建。有两个选项：点对点重建，现在最便宜，但会重新引入目标架构旨在消除的耦合；或者重建为基于文档化接口合约的模式，现在设计投入更大，但能避免第三次重建。
设计语气（采纳）：
3.2.1 备选方案 1：点对点修复
每个受影响的接口将重建为源系统和目标系统之间的直接连接。不引入中间组件。
3.2.2 备选方案 2：基于合约的修复
每个受影响的接口将根据文档化的接口合约进行重建，该合约规定了方向、触发条件、载荷、频率和所有权。该合约将在临时平台上实施，并可迁移到集成平台而无需重新定义。
表 4 – 备选方案，优缺点
3.6 结论
选择备选方案 2。它满足架构原则 AP-06，即一个应用可以被替换而无需重做所有集成，而备选方案 1 则不满足。预计额外设计工作量约为 [X] 天。该决策记录为 DD-04，在接口构建开始前是可逆的。
内容相同。第二种是设计文档。