3. EWI系统总体架构设计
EWI（电子作业指导书）系统不是把纸质SOP简单转成网页，而是一套把工艺文件、工位终端、生产数据和权限控制串起来的工程系统。总体架构设计要回答四个问题：系统分成哪几层、每层由哪些模块组成、数据在层与模块之间怎么流动、模块之间用什么接口对接。这四个问题定下来，后续的数据库设计、前端开发和现场部署才有稳定依据。
一、分层架构：五层职责边界
EWI系统推荐采用五层架构，自下而上依次为设备接入层、数据层、服务层、应用层和展示层。分层的核心价值是限定变更影响范围：更换工位终端只影响展示层，调整工艺审批规则只影响服务层，不会牵动全局。
- 设备接入层：负责与现场硬件打交道，包括工位一体机、扫码枪、PLC、电子看板、打印机。该层把不同厂商、不同协议的设备统一抽象为“可读状态”和“可下发指令”两类能力，向上屏蔽硬件差异。
- 数据层：存放工艺文件、版本记录、工位配置、操作日志、权限数据。结构化数据用关系库，工艺图纸、视频、PDF等大文件用对象存储，二者通过文件ID关联。
- 服务层：承载业务逻辑，包括工艺文件管理、版本发布、权限校验、数据采集、消息通知。服务层不直接操作界面，也不直接驱动硬件，只对外提供接口。
- 应用层：面向角色的功能集合，如工艺员编辑端、主管审批端、产线看板端、管理后台。应用层调用服务层接口，不跨层访问数据层。
- 展示层：工位终端上真正呈现给操作员的内容，包括步骤卡片、图示、参数输入框、报警提示。展示层要针对触摸屏、强光环境、戴手套操作做适配。
二、模块划分：按职责而非按页面
模块划分常见误区是按界面切分，比如“编辑页模块”“看板页模块”，结果业务逻辑散落各处。正确做法是按职责划分，每个模块有明确的输入、输出和归属层。EWI系统可划分为以下核心模块：
| 模块 | 所属层 | 核心职责 | 关键输出 |
|---|---|---|---|
| 工艺文件管理 | 服务层 | 文件创建、编辑、附件挂载 | 文件主记录、附件ID |
| 版本与发布 | 服务层 | 版本号生成、审批流转、生效控制 | 已发布版本、生效工位列表 |
| 权限与角色 | 服务层 | 角色定义、工位授权、操作鉴权 | 鉴权结果、授权矩阵 |
| 终端渲染 | 展示层 | 按工位拉取当前版本并渲染 | 步骤卡片、输入控件 |
| 数据采集 | 设备接入层 | 采集扫码、按钮、设备状态 | 带时间戳的事件流 |
| 日志与追溯 | 数据层+服务层 | 记录谁在何时看了哪版、填了什么 | 可查询的操作记录 |
模块之间只允许通过接口通信，禁止一个模块直接读写另一个模块的私有数据表。这条约束在后期排查“为什么工位显示旧版本”这类问题时非常关键。
三、数据流：从工艺员发布到工位呈现
下面这张图描述EWI系统的主数据流：工艺员在编辑端完成文件并提交审批，审批通过后生成发布版本；发布事件写入版本库并推送到消息通道；工位终端订阅自己所属工位的版本变更，拉取最新版本并渲染；操作员的操作与扫码数据反向回流到采集与日志模块，形成追溯闭环。
图中正向链路（蓝色）是版本下发：编辑端→审批发布→版本库→消息通道→设备接入层→工位终端→操作员。反向链路（橙色）是数据回流：操作员操作、终端事件、设备状态统一汇入采集与追溯日志。两条链路分离设计，保证即使采集服务短暂不可用，工位仍能凭本地缓存继续显示工艺内容，不会因数据回传失败而停线。
四、接口设计：三类接口与关键约定
EWI系统的接口可分为三类，各自关注点不同：
- 业务接口（应用层↔服务层）：采用HTTP+JSON，按资源组织。例如获取工位当前版本用
GET /api/stations/{stationId}/active-version，返回版本号、步骤列表和附件地址。约定：所有写操作必须携带操作员身份令牌，服务端据此记录日志。 - 事件接口（服务层↔终端/设备）：版本发布、工位授权变更等用消息订阅方式推送，避免终端轮询。终端订阅主题按工位号划分，如
ewi/station/A03/version，只接收与自己相关的变更。 - 设备接口（设备接入层↔硬件）：扫码枪常用USB-HID或串口，PLC常用Modbus TCP或OPC UA。接入层把不同协议统一转换为内部事件格式，向上只暴露“事件类型+工位号+值+时间戳”四个字段。
contentHash，终端本地缓存时一并保存，下次拉取先比对哈希再决定是否重新渲染。五、技术选型原则
技术选型不应追求“最新最热”，而应围绕现场约束做取舍。EWI系统的选型可遵循四条原则：
- 现场可用优先：工位终端可能长期运行、网络不稳定、环境有粉尘和油污。前端应选择能在低配一体机上流畅渲染的方案，避免依赖持续联网的重型框架；数据同步要支持断网缓存与恢复后补传。
- 数据可追溯优先：数据库选型首先看事务能力和审计支持，其次才看扩展性。工艺版本、审批记录、操作日志属于质量追溯证据，不能只存在内存或临时文件中。
- 接口稳定优先：设备品牌和型号会随产线改造变化，接入层必须做成可替换的适配器。选型时确认目标设备是否提供开放协议文档，避免只能依赖厂商私有SDK。
- 运维成本优先：工厂IT人力有限，组件越少越好。若团队没有容器运维经验，就不必为了“架构先进”强行上Kubernetes；单机部署加定时备份，往往比复杂集群更可靠。
把上述内容落到一份可执行的架构决策上，可以用下面这张简表记录关键选择与理由，便于后续评审和交接：
| 决策项 | 选择 | 主要理由 |
|---|---|---|
| 终端渲染方式 | 轻量Web页面 + 本地缓存 | 低配一体机可运行，断网仍可显示 |
| 版本下发方式 | 消息订阅 + 启动时全量拉取 | 减少轮询，兼顾实时性与首次加载 |
| 设备接入方式 | 适配器模式，按协议分插件 | 更换设备不影响上层业务 |
| 日志存储 | 关系库存结构化事件，对象存储存附件 | 便于按工位、版本、时间检索追溯 |
总体架构设计完成后，应能回答一个检验性问题：当某工位显示内容与最新发布版本不一致时，能否沿着“版本库→消息通道→终端缓存→渲染”这条链路逐段定位？如果每一段都有明确的接口、日志和校验值，架构就是可运维的；如果某一段只能靠“重启试试”，说明该层的接口约定或数据流设计还需要补强。