📚 课程目录第3章电子作业指导系统的技术架构选型

3. 电子作业指导系统的技术架构选型

电子作业指导系统（e-SOP）面向车间大屏、工位终端、平板和移动设备，既要稳定展示图文、视频、3D 动画等作业指导内容，又要支持多语言切换、版本追溯和与 MES/ERP 的数据联动。技术架构选型的目标不是追求“最新”，而是让内容发布、终端渲染、多语言资源加载和文件分发这四条链路各自清晰、可独立演进。本节围绕前后端分离、微服务、数据库、文件存储与多语言资源服务五个关键决策展开。

前后端分离：让终端渲染与业务逻辑解耦

e-SOP 的前端形态差异很大：车间大屏需要自动轮播和全屏展示，工位终端需要按工单自动加载对应工序，平板需要支持手势缩放和离线缓存。如果采用传统服务端渲染，每增加一种终端就要改动后端模板，迭代成本高。前后端分离后，后端只提供 REST/JSON 或 GraphQL 接口，前端按终端类型独立构建。

实际落地时，前端通常拆为两个应用：管理端（工艺工程师编辑 SOP、上传文件、配置多语言）和终端播放端（车间设备展示）。两者共用一套 API 契约，但构建产物和发布节奏独立。接口设计上，终端播放端最关键的接口是“按工单+工序+语言获取作业指导包”，返回结构应包含内容元数据、资源地址列表和版本号，便于终端做缓存比对。

GET /api/v1/sop/package?workOrder=WO20240512-001
    &process=OP30&lang=zh-CN
{
  "sopId": "SOP-A12-OP30",
  "version": "3.2.1",
  "lang": "zh-CN",
  "steps": [
    {"seq": 1, "text": "安装定位销", "media": ["img/op30-1.webp"]},
    {"seq": 2, "text": "拧紧扭矩 12N·m", "media": ["video/op30-2.mp4"]}
  ],
  "resourcesBase": "https://cdn.example.com/sop/A12/OP30/3.2.1/"
}

终端拿到 version 后与本地缓存比对，版本一致则直接使用本地资源，避免每次切换工单都重新下载大文件。这是前后端分离后终端能实现“秒开”的关键。

微服务拆分：按业务能力而非按技术分层

e-SOP 的业务能力可以归纳为五块：SOP 内容管理、工单与工序联动、多语言资源管理、文件与媒体服务、终端会话与播放控制。微服务拆分应围绕这五块，而不是按“Controller 层、Service 层”去拆。一个合理的服务划分如下：

sop-content-service：SOP 主数据、步骤、版本、审批状态。
workorder-adapter-service：对接 MES/ERP，把工单和工序映射为 SOP 查询条件。
i18n-resource-service：多语言词条、翻译状态、语言包生成。
media-service：图片、视频、3D 模型的上传、转码、分发。
terminal-session-service：终端注册、心跳、播放日志、离线包下发。

拆分粒度不宜过细。例如“多语言资源”和“SOP 内容”如果拆成两个服务，每次发布 SOP 都要跨服务事务协调，反而增加复杂度。建议初期把 i18n 作为 sop-content-service 的内部模块，当翻译团队独立作业、语言数量超过 5 种时再拆出独立服务。微服务的价值在于独立部署和独立扩缩容，而不是服务数量本身。

数据库选型：关系型为主，缓存与检索为辅

SOP 主数据、版本、审批记录具有强一致性和事务需求，应使用关系型数据库，如 PostgreSQL 或 MySQL。核心表包括 sop、sop_version、sop_step、sop_step_i18n、workorder_sop_mapping。其中 sop_step_i18n 用 (step_id, lang) 作为联合主键，存储步骤文本的翻译。

终端播放日志、心跳、资源访问记录属于高频写入、低价值密度数据，建议写入时序数据库或 ClickHouse，避免拖慢主库。SOP 全文检索（按关键词找工序）可用 Elasticsearch，但要注意索引与主库的同步延迟，检索结果只用于定位，最终内容仍以主库为准。

数据类型	推荐存储	理由
SOP 主数据、版本、审批	PostgreSQL / MySQL	事务、外键、版本一致性
多语言词条	关系型 + Redis 缓存	读多写少，按语言缓存整包
终端播放日志	ClickHouse / 时序库	高写入、按时间聚合
全文检索	Elasticsearch	关键词定位，非权威源

文件存储：对象存储 + CDN，版本目录隔离

e-SOP 的媒体文件体积大、访问频繁、需要按版本追溯。推荐使用对象存储（如 MinIO 自建或云对象存储），目录结构按 sopId/process/version/ 隔离，例如 sop/A12/OP30/3.2.1/video/op30-2.mp4。这样终端缓存比对时只需比较版本号，版本升级后旧目录仍保留，便于回滚和审计。

文件上传后由 media-service 触发转码：视频统一转为 H.264 MP4，图片转为 WebP，3D 模型转为 glTF。转码完成后写入 CDN，终端通过 CDN 地址拉取。注意：对象存储的桶策略应禁止公开列目录，只允许按完整路径读取，避免未发布版本被提前访问。

多语言资源服务：词条、语言包与回退策略

多语言不是简单地把文本翻译一遍。e-SOP 的多语言资源分三层：界面词条（按钮、提示语）、SOP 步骤文本（工艺描述）、媒体资源（带文字的图片、视频字幕）。界面词条用 JSON 语言包管理，SOP 步骤文本存数据库，媒体资源按语言目录存放。

语言包生成策略：i18n 服务按 lang 聚合所有词条，生成 zh-CN.json、en-US.json 等文件，终端启动时加载当前语言包。回退策略必须明确：当 en-US 缺少某词条时，回退到 zh-CN 还是显示 key？建议回退到默认语言（通常为 zh-CN），并在管理端标记“缺失翻译”，提醒翻译人员补齐。

多语言资源服务的接口应支持按语言批量拉取，而不是逐条查询。终端一次请求 GET /api/v1/i18n/bundle?lang=en-US&namespace=sop 即可拿到整包，减少网络往返。

整体架构关系

下图把上述五个决策放在同一张架构关系图中：前端分管理端与终端播放端，后端按业务能力拆为五个服务，数据层按读写特征分库，文件走对象存储与 CDN，多语言资源服务同时服务管理端和终端。

这张图的核心信息是：前端两个应用共用一套 API 契约；后端五个服务各自对应一类业务能力；数据层按读写特征分库，关系型库承担权威数据，Redis 承担语言包缓存，ClickHouse 承担日志，对象存储承担媒体文件。多语言资源服务同时被管理端和终端调用，是跨层的关键节点。

选型时的常见取舍

第一，是否一开始就上微服务。如果团队规模小于 5 人、SOP 数量少于 500 条，建议先用模块化单体，把五个业务能力做成清晰的包边界，等终端数量超过 200 台或翻译团队独立作业时再拆服务。第二，数据库是否分库。SOP 主库和日志库应尽早分开，因为日志写入量会随终端数量线性增长，混在一起会拖慢 SOP 查询。第三，多语言资源是否独立服务。语言数量少于 3 种时，i18n 作为 sop-content 的内部模块即可；超过 5 种且翻译流程独立时，再拆为独立服务并引入翻译状态机。

不要为了“架构先进”而把 SOP 内容、多语言、媒体文件拆成三个必须跨服务事务的服务。SOP 发布是一个原子操作，跨服务事务会显著增加失败率和排查成本。拆分的前提是业务边界清晰且能独立演进。

综上，e-SOP 的技术架构选型可以概括为：前后端分离保证终端多样性，微服务按业务能力拆分保证独立演进，关系型数据库保证 SOP 权威数据一致性，对象存储加 CDN 保证媒体文件分发效率，多语言资源服务保证语言包整包加载与回退可控。五个决策相互配合，才能支撑车间环境下“秒开、可追溯、多语言”的实际需求。