SKILLπ JOURNAL ↗ 教程

架构评审 PPT:系统绘图、证据叙事与视觉验收

用温室监测平台离线恢复案例,连起系统结构与失败路径、数据口径、整套汇报和逐页视觉验收,保留可编辑源与未决问题。

技术方案汇报应帮助听众判断一个改变是否值得推进。架构图、数据页和视觉样式必须服务于同一个问题,不能分别生成后随意拼在一起。这里以虚构的温室监测平台为例,准备一份“离线期间如何保留读数”的评审材料,覆盖系统绘图、整份汇报组织和最终视觉检查。数字与规则均为教学设定,不代表实际部署或测试结果。

从评审问题建立材料清单

先明确要比较的选择:边缘设备临时保存读数,还是只依赖网络恢复后重新采集。听众需要知道断网时发生什么、恢复后怎样避免重复,以及增加复杂度是否合理。输入包包含当前组件说明、通信约定、已批准的脱敏运行摘要、限制与待决定问题;没有资料支持的可靠性百分比和成本节约不得由模型补写。

给每个输入编号,区分现有、拟议和未知。传感器、网关、接收服务、读数存储和告警界面的存在必须有来源;消息队列、缓存或云产品名称只有在材料确认时才进入现状图。需要把计划画出来时单独标明拟议视图,并写清假设,避免听众误认为已经上线。

先列页面计划:评审问题、现状边界、断网时序、方案比较、证据与限制、需要批准的下一步。每页只有一个主要判断,附支持它的来源编号。生成前先检查这些页面是否覆盖原始问题;如果只是封面、目录和漂亮架构图,仍然没有可供评审的论据。

场景一:画清系统结构与关键运行路径

先用组件与关系表确定图的语义。对每个组件记录职责和边界,对每条边记录方向、数据与协议已知程度。静态结构图表达传感器经网关向接收服务提交读数,存储被告警与查询功能使用;运行流程另画,避免用同一根箭头同时代表网络连接、调用顺序与数据持久化。

断网视图必须回答读数在哪里、何时可能丢失、恢复后谁重试、服务端如何处理重复事件。若事件标识、时间顺序和容量策略尚未决定,在图旁列待决项,不能让 Agent 自动设计后宣称这是现有机制。把正常与失败路径一起评审,能比单纯增加模块更早暴露未知。

选图源时考虑后续维护。Mermaid 文本便于查看关系差异,图形编辑器源文件便于手动布局;SVG、PNG 和 PDF 主要用于展示,不能一概视为可继续编辑的业务对象。源文件、导出图和引用它的幻灯片使用同一版本号,修改后重新生成,防止上一版图仍在报告里。

GitHub 的 Mermaid CLI 是 MIT 许可的既有开源渲染方案,可把 Mermaid 定义转换成 SVG、PNG 或 PDF。参考它是为了复用成熟的格式转换能力;实际采用前核对所选版本的运行环境、浏览器依赖、字体与命令选项。本文未安装或执行该工具,也不把生成了图源称为已经渲染完成。内部拓扑不要未经授权上传到公共编辑器。

实操:把重复读数风险画进评审

设网关保存了事件 A、B、C,网络恢复后 A 的确认响应丢失。若网关再次发送 A,接收端应怎样判断是否同一次读数?这是需要明确的接口和业务规则,不能仅用“自动去重”四个字遮住。写出事件标识的候选定义、保留时间、重发条件及异常处理,由实际工程评审作决定。

让 Agent 先整理“产生读数→本地保存→发送→收到确认→清理”的步骤表,再指出每一步失败后的状态。断电前是否确保持久化、容量不足是否停止采集、设备时钟变化怎样处理,都应写进问题清单。只在规则确认后画详细时序,不用猜测填满缺口。

任务可写成:“仅依据 architecture-notes.md 和 approved-summary.csv,生成现状结构、拟议离线流程和未决问题。每个节点附来源编号,现状与提议分开。列出确认丢失、重复发送和容量耗尽路径。提供可编辑图源与渲染计划,不连接设备或修改生产配置,不声称实验已运行。”先审关系,再看渲染,最后看它进入幻灯片后的可读性。

场景二:把图与证据组织成完整汇报

报告的标题应说明这一页的结论,例如“重传必须与确认语义一起设计”,而不是只有“技术架构”。把方案、好处、成本、依赖和未验证假设放到可比较的表中。图负责解释机制,数据负责支持观察,二者不可以互相冒充;结构图不能证明延迟下降,运行摘要也不能证明所有异常已被覆盖。

如果输入包括脱敏 CSV、TSV 或 JSON 的运行记录,可在这一阶段用 Exploratory Data Analysis 检查缺失、重复候选、时间窗口与分布。限定本地数据根目录和输出目录,准备相应 Python 环境与依赖。其作用是有边界的数据质量和探索报告,不是直接修改工作簿、生成 PPT 或证明新架构改善了可靠性。

数据页写清样本窗口、计数单位、缺失记录、筛选规则和统计口径。区分已观测的记录条数、唯一事件数和设备数;重复日志可能不是重复读数。来自不同环境的数据分开说明,不能把模拟结果与生产结果合并后给一个统一指标。任何从表中抄到幻灯片的数字都要能回溯到输入与计算说明。

生成整份演示时,先审页级大纲,再做最密页面和架构页面的样稿。检查图表、长标题、来源和备注,再扩展其余页。模板容量不足时拆页或转附录,不能静默截断。保留可编辑文稿、图源、大纲、数据摘要与内容对应清单,清楚标明哪些图在幻灯片里是图片、哪些对象可以直接改。

场景三:建立统一视觉规则,再逐页验收

先规定标题与正文层级、内容区域、间距、颜色语义和图例。现有组件、拟议组件与未知关系可用标签、边框和线型共同区分,不只靠颜色。技术图优先保证箭头和标签可读,不强制每页套固定图文比例;一张复杂图可以独占一页,关键说明另用简短文字。

需要原创静态视觉样稿时,可选 Canvas Design 确立一页 PNG/PDF 的留白、层级与配色方向。提供尺寸、用途和已许可素材,并确保 Agent 能生成和检查文件;字体与附带资源仍需核对许可。它不是技术架构校验器、PPTX 编辑器或整套自动美化服务,只用于确实需要的静态视觉参考,再把规则实施到演示文稿。

在目标演示软件中逐页打开,查看缺字、字体替换、连线穿字、对象遮挡、截图模糊、裁切与链接。以实际放映尺寸看一遍,再导出 PDF 检查。统一母版后也要复核内容,避免换字体导致原先刚好放下的标签溢出。没有检查的 Office、WPS 或 Keynote 版本留作待验收,不保证跨软件完全一致。

如需图片化备份,说明它主要用于稳定展示,会牺牲逐对象编辑、文字检索和部分无障碍能力。不能用它替代可编辑母版。交付记录写实际查看的文件、页码、软件版本、发现的问题与修复结果;“导出成功”与“内容、视觉、编辑性通过”应分别记录。

FAQ:把自动生成与真实验收分开

多久能完成?取决于输入完整度、图复杂度和目标环境,没有普遍三分钟成片保证。不懂设计能做吗?可以先用组件表和页级大纲降低门槛,但系统事实与方案决定仍需负责人确认。架构图和业务流程能用同一种表达吗?工具可能支持多种图,仍应根据结构、顺序或状态问题选择正确视图。

技能是否都经过安全审查?不能据目录或下载数字作此保证,核查来源、固定版本、许可、依赖和实际文件或网络权限。原文名称未取得本次可核验匹配记录时不制作猜测安装链接。以后目录新增技能时,用同一份脱敏温室案例复查输入输出,在适合的步骤补充关联,记录替换原因与日期。

为什么图很好看却评审过不了?回看它是否回答了确认丢失、重复事件和容量限制这些问题。为什么优化后数据变漂亮了?检查是否无意删除异常或更换分母;原始摘要与派生结果必须分开保留。最终应交付可追溯的方案与待验证清单,让团队能决定下一步,而不是将未运行的设计包装成已完成的系统。

分享文章X ↗LinkedIn ↗