生产报工与追溯参考架构

应用参考。这是一个说明性架构和范围检查清单，并非经过验证的客户项目或经测量的部署。技术、集成范围和交付内容将根据实际需求说明确定。

场景与约束

某工厂正在替换基于电子表格的生产跟踪方式。决定性要求是双向追溯：给定一个成品序列号，列出其中使用的每个物料批次；给定一个有缺陷的物料批次，列出受影响的每个成品单元。该要求决定了数据模型，不能在后期通过简单附加实现，否则必须重新处理历史记录。

层级	技术	负责内容
办公室 Web	Vue 3 + Element Plus	订单下达、BOM 维护、排程、质量审核和报表。
车间客户端	Android 手持设备 / 平板电脑（Kotlin），支持离线	每个工位由扫描驱动的报工。针对戴手套操作和 Wi-Fi 信号较差的环境设计：大尺寸操作目标、少量点击、本地队列。
API	Go + Gin	根据工艺路线进行报工校验、执行物料消耗规则以及追溯查询。
存储	MySQL	订单、工艺路线、报工记录和批次谱系。
设备网关	MQTT 或 OPC UA 桥接（可选）	在供应商提供接口的情况下，从设备获取数量或测量值，并规范化到相同的报工表中。
报表	定时聚合任务	预先计算产率、循环时间和工位负载，因为这些查询需要扫描过多历史记录，无法在每次仪表板加载时实时运行。

下表承载着其他所有功能所依赖的规则。这里出错，会使一个可运行的演示变成无法扩展的系统。

实体	关键字段、关系和规则
item / bom	具有生效日期和替代规则的多级物料清单。保留 BOM 版本而不是覆盖，因此上月生产的订单仍可根据其实际使用的 BOM 进行解析。
work_order / routing_step	订单及其按顺序排列的工序列表；每道工序都绑定一个工作中心，并包含标准工时和该工序的报工规则。
production_report	按工位记录产出：操作员、开始和结束时间、良品数量、返工和报废及其原因代码。这是所有指标的输入，因此其校验规则比仪表板更重要。
material_lot / lot_consumption	收货批次及其针对工单的领用记录。lot_consumption 是实现谱系追踪的连接关系；没有它，追溯就会退化为猜测。
serial / genealogy	将序列化成品单元与其消耗的批次关联起来，形成能够回答两个追溯方向的图。
inspection / defect	检验点、抽样规则、缺陷代码和处置方式（接收、返工、报废），每项都回溯关联到生产该单元的报工记录。

端点	用途与并发说明
POST /api/v1/reports	工位报工。校验上一道工艺路线工序是否完成、报工数量是否超过已下达数量，以及物料消耗是否处于 BOM 容差范围内；在此处拒绝错误输入，是保持报工数据可信的关键。
POST /api/v1/reports/batch	从手持设备上传离线队列，依据客户端 UUID 去重，并保留采集时间。
GET /api/v1/trace/forward/{lot}	给定物料批次，返回所有受影响的成品序列号，这是召回所依赖的查询。
GET /api/v1/trace/backward/{serial}	给定成品序列号，返回完整的物料批次谱系。
POST /api/v1/work-orders/{id}/release	下达订单，同时保存 BOM 和工艺路线版本快照，使后续主数据编辑无法改写历史。

从一开始就建立谱系模型。事后补建追溯功能意味着历史数据永远无法完整追溯。如果未来可能需要追溯，则 lot_consumption 连接关系必须从首次发布开始存在，即使报表稍后才上线。
在订单下达时保存 BOM 和工艺路线快照。主数据持续变化；订单必须继续根据其下达时使用的版本解析，否则成本和消耗偏差将失去意义。
在报工端点执行校验，而不是在仪表板中校验。根据未经校验的输入计算指标，会产生看似可信但实际错误的数字。在录入时拒绝不可能的报工，比之后解释错误的产率数据成本更低。
在手持设备上使用离线队列。工厂 Wi-Fi 在金属和机械设备附近存在信号盲区。在这些区域报工失败，就不会被完成，数据集会在不易察觉的情况下出现缺口。
与现有 ERP 共存，而不是替换它。应结合实际依赖、成本和风险，对订单与库存移动的范围化接口和 ERP 迁移进行比较；在做出选择前确认财务流程。

以下数值是用于容量规划的假设性示例，不是经过测量的客户结果、经过验证的容量建议或 SLA。在定义工作负载、设备、数据、硬件和第三方依赖后，设定项目专属的验收目标；在承诺生产目标前，通过试点和负载测试进行验证。

目标	数值与假设
扫描到确认	假设目标：对于已定义的报工和设备，本地反馈低于 1 秒。持久化保存排队记录，并区分本地确认和服务器接受；测试网络延迟和故障。
追溯查询	对于典型的谱系深度，两个方向都在几秒内返回，并使用已建立索引的批次和序列号连接；深层多级装配需要在验收期间根据真实数据进行验证。
报工仪表板	从按照与运营方约定的计划刷新的预计算聚合数据提供服务，而不是在每次页面加载时扫描原始报工记录。
离线容忍度	一个完整班次的报工可在本地排队，并在重新连接后上传，依据客户端 UUID 去重。

上述模块是起点，而不是固定套餐。我们通常将首个版本控制在一个核心工作流和一个管理工作流内，然后根据实际使用情况显示的负载和边界情况进行扩展。发送范围明确的需求说明，我们将根据此架构进行映射，并告知您哪些部分目前还不需要。