307 lines
14 KiB
Markdown
307 lines
14 KiB
Markdown
|
# 生产插件功能完善建议
|
||
|
|
|
||
|
|
## 1. 文档目的
|
||
|
|
|
||
|
|
本文档基于当前生产插件的 Web 端、Admin 端、扫码端和后端实现整理，目标是明确后续功能补强方向，避免继续出现“页面已完成但流程数据无法追溯”或“不同端实现不一致”的问题。
|
||
|
|
|
||
|
|
涉及目录：
|
||
|
|
|
||
|
|
- 后端：`backend/plugin/produce`
|
||
|
|
- Web 端：`frontend/web/app/apps/produce`
|
||
|
|
- Admin 端：`frontend/admin/src/apps/produce`
|
||
|
|
- 扫码端：`frontend/scanapp`
|
||
|
|
|
||
|
|
## 2. 当前能力概览
|
||
|
|
|
||
|
|
### 2.1 已具备的功能
|
||
|
|
|
||
|
|
- 生产录入：订单模式、整机模式、一单多机、工序/步骤/状态联动。
|
||
|
|
- 异常处理：异常类型、原因、具体问题、图片、异常提报和异常查询。
|
||
|
|
- 维修处理：待维修订单、维修结果、责任人员、故障描述、备件更换和维修提交。
|
||
|
|
- 工艺配置：工序、工序步骤、步骤状态、步骤关系、状态转换、转换日志。
|
||
|
|
- 物料管理：物料分类、物料库、物料搜索、故障描述和备件使用频率排序。
|
||
|
|
- 查询统计：订单流程时间线、扫码数据、异常数据、维修数据、月度统计、日统计。
|
||
|
|
- 多端入口：Web 端、Admin 管理端和 `scanapp` 扫码端均已有生产相关页面。
|
||
|
|
|
||
|
|
### 2.2 当前实现特点
|
||
|
|
|
||
|
|
- 后端 Admin API 采用标准 CRUD，前台和扫码业务集中在 `DataEntryController`。
|
||
|
|
- 工序状态机已经支持前置步骤、终态校验、重复扫码策略和自动状态转换。
|
||
|
|
- 异常记录已保存工序和步骤；维修记录目前主要通过异常记录关联维修流程。
|
||
|
|
- 维修备件和责任人员采用 JSON 快照保存，能够保留提交时的名称信息。
|
||
|
|
- 统计服务已经支持异常、维修、扫码、整机数据的合并统计。
|
||
|
|
|
||
|
|
## 3. 建议优先修复的基础问题（P0）
|
||
|
|
|
||
|
|
### 3.1 维修记录保存工序/步骤快照
|
||
|
|
|
||
|
|
**现状问题**
|
||
|
|
|
||
|
|
- `produce_repair_record` 当前没有独立的 `process_id`、`step_id`、工序名称和步骤名称字段。
|
||
|
|
- 统计服务中的维修记录工序步骤来自当前“维修流程”配置，而不是维修提交当时的实际流程。
|
||
|
|
- 后台修改维修流程后，历史维修数据可能被统计到新的工序步骤，历史数据无法准确复盘。
|
||
|
|
|
||
|
|
**建议方案**
|
||
|
|
|
||
|
|
- 维修提交时保存 `process_id`、`step_id`、`process_name`、`step_name` 四个快照字段。
|
||
|
|
- 维修记录列表、详情、导出、订单时间线和月/日统计优先使用记录自身快照。
|
||
|
|
- 对历史数据执行一次回填：优先读取关联异常记录的工序步骤，无法匹配时标记为“历史数据未记录”。
|
||
|
|
- 后续修改维修流程只影响新提交数据，不改变历史统计口径。
|
||
|
|
|
||
|
|
**验收标准**
|
||
|
|
|
||
|
|
- 修改后台维修流程后，旧维修记录的工序步骤不发生变化。
|
||
|
|
- Web、Admin、扫码端和月/日统计显示同一组工序步骤。
|
||
|
|
- 维修记录导出包含工序名称、步骤名称和对应编码。
|
||
|
|
|
||
|
|
### 3.2 防止扫码、异常和维修重复提交
|
||
|
|
|
||
|
|
**现状问题**
|
||
|
|
|
||
|
|
- 当前主要依赖业务规则判断重复扫码，网络重试或用户连续点击仍可能产生重复请求。
|
||
|
|
- 扫码端更容易遇到弱网、超时和重复点击场景。
|
||
|
|
|
||
|
|
**建议方案**
|
||
|
|
|
||
|
|
- 每次提交由客户端生成 `client_request_id`，服务端建立唯一约束或幂等记录。
|
||
|
|
- 相同请求重复提交时返回第一次提交结果，而不是再次写入数据。
|
||
|
|
- 提交按钮增加处理中状态，扫码成功后短时间内锁定同一条码。
|
||
|
|
- 对订单号、工序、步骤、用户编码、数量等关键字段增加服务端事务锁和最终校验。
|
||
|
|
|
||
|
|
**验收标准**
|
||
|
|
|
||
|
|
- 同一请求重试不增加记录数量。
|
||
|
|
- 网络超时后再次点击能够得到明确的“已提交”结果。
|
||
|
|
- 并发提交不会绕过重复扫码和数量限制。
|
||
|
|
|
||
|
|
### 3.3 区分提报人、处理人和实际作业人员
|
||
|
|
|
||
|
|
**现状问题**
|
||
|
|
|
||
|
|
- 当前多个接口同时使用 `user_code`、`operator`、`reporter` 等字段，不同页面对“登录账号”和“实际作业人员”的理解容易混淆。
|
||
|
|
- 维修责任人员已经支持手工录入用户编码，但审计信息还不够统一。
|
||
|
|
|
||
|
|
**建议方案**
|
||
|
|
|
||
|
|
- 统一保存以下信息：实际作业人员编码/姓名、系统提交人 ID/姓名、最后处理人 ID/姓名、提交时间和客户端来源。
|
||
|
|
- 用户编码校验统一复用成员查询服务，不允许各端自行按不同字段判断。
|
||
|
|
- 所有列表和时间线同时展示“工号 + 姓名”，详情中展示系统操作人。
|
||
|
|
- 对手工代录场景增加“代录原因”和“授权人”字段，并写入操作日志。
|
||
|
|
|
||
|
|
### 3.4 建立异常到维修的完整闭环
|
||
|
|
|
||
|
|
**现状问题**
|
||
|
|
|
||
|
|
- 当前异常、待维修、维修提交和查询已经存在，但缺少统一的状态流转约束和超时提醒。
|
||
|
|
- 异常处理状态、维修结果和订单当前状态可能出现不一致。
|
||
|
|
|
||
|
|
**建议方案**
|
||
|
|
|
||
|
|
- 明确状态机：待处理 → 已分派 → 维修中 → 待验证 → 已完成 / 已关闭 / 已退回。
|
||
|
|
- 异常只能通过维修提交、人工关闭或退回操作改变状态，禁止直接修改造成跳状态。
|
||
|
|
- 一条异常允许多次维修尝试，但必须保留每次维修记录和失败原因。
|
||
|
|
- 增加维修超时、待验证超时和重复返修提醒。
|
||
|
|
|
||
|
|
## 4. 工艺和流程能力增强（P1）
|
||
|
|
|
||
|
|
### 4.1 工序流程可视化和发布机制
|
||
|
|
|
||
|
|
当前已有工序、步骤、步骤关系和状态转换四类配置，但配置结果缺少可视化验证。
|
||
|
|
|
||
|
|
建议增加：
|
||
|
|
|
||
|
|
- 工序流程图：显示正常流转、异常流转、前置步骤和终态。
|
||
|
|
- 流程校验：检查孤立步骤、循环关系、无初始状态、多个初始状态、无可达终态等问题。
|
||
|
|
- 草稿/发布机制：编辑中的流程不立即影响现场，发布后生成流程版本。
|
||
|
|
- 生效时间和版本回滚：历史记录绑定流程版本，支持按版本追溯。
|
||
|
|
- 流程模拟器：输入订单、步骤、状态和事件，预览下一步可执行转换。
|
||
|
|
|
||
|
|
### 4.2 前置步骤和重复扫码规则可视化
|
||
|
|
|
||
|
|
`ProcessStep` 已具备前置步骤、前置验证模式、终态要求和重复扫码状态等字段，建议在 Admin 页面完整开放：
|
||
|
|
|
||
|
|
- 用步骤选择器代替手工填写 ID。
|
||
|
|
- 用“全部完成 / 任意完成 / 无需验证”下拉框代替编码输入。
|
||
|
|
- 用状态多选展示允许重复扫码的状态。
|
||
|
|
- 保存前给出规则冲突提示，避免把当前步骤设置为自己的前置步骤。
|
||
|
|
|
||
|
|
### 4.3 状态转换配置器
|
||
|
|
|
||
|
|
状态转换中的 `event_config` 和 `side_effect_config` 当前适合技术人员维护，不适合普通管理员。
|
||
|
|
|
||
|
|
建议分层实现：
|
||
|
|
|
||
|
|
- 首期提供 JSON 格式校验、格式化和示例模板。
|
||
|
|
- 后续提供条件构造器、通知配置器、字段更新配置器和事件参数表单。
|
||
|
|
- 配置保存前执行字段白名单校验，禁止任意表达式或脚本执行。
|
||
|
|
|
||
|
|
## 5. 质量、维修和物料能力增强（P1）
|
||
|
|
|
||
|
|
### 5.1 维修备件管理从快照升级为库存业务
|
||
|
|
|
||
|
|
当前维修记录的 `parts` 以 JSON 快照保存，适合记录历史，但不能支持库存管理。
|
||
|
|
|
||
|
|
建议增加：
|
||
|
|
|
||
|
|
- 备件单位、库存数量、安全库存、库位、供应商和启用状态。
|
||
|
|
- 维修领料、退料、旧件回收和库存流水。
|
||
|
|
- 备件替代关系：一个物料允许配置可替代物料。
|
||
|
|
- 维修提交时校验库存，支持“只记录不扣库存”和“提交即扣库存”两种策略。
|
||
|
|
- 备件消耗排行、故障关联排行和库存预警。
|
||
|
|
|
||
|
|
### 5.2 故障描述和责任分析
|
||
|
|
|
||
|
|
当前已有故障描述使用次数和责任人员快照，建议补充：
|
||
|
|
|
||
|
|
- 故障描述的启用范围：按产品、物料分类、工序或步骤限制。
|
||
|
|
- 故障原因、责任类型、责任部门和责任人员的分层统计。
|
||
|
|
- 缺陷 Pareto 图、重复故障率、一次修复率和返修率。
|
||
|
|
- 支持从统计图直接下钻到异常记录和维修记录。
|
||
|
|
|
||
|
|
### 5.3 附件和图片统一管理
|
||
|
|
|
||
|
|
异常和维修均支持图片，但建议从 JSON URL 记录进一步完善为附件管理：
|
||
|
|
|
||
|
|
- 限制文件类型、单文件大小、数量和图片分辨率。
|
||
|
|
- 记录上传人、上传时间、业务类型和关联记录。
|
||
|
|
- 删除业务记录时保留附件引用检查，避免误删仍被其他记录使用的文件。
|
||
|
|
- 列表只显示缩略图，详情支持原图查看和下载。
|
||
|
|
|
||
|
|
## 6. 统计和查询能力增强（P1）
|
||
|
|
|
||
|
|
### 6.1 统一统计口径
|
||
|
|
|
||
|
|
当前月/日统计已合并扫码、整机、异常和维修数据，建议明确每类指标的定义：
|
||
|
|
|
||
|
|
- 生产量：按订单数量、扫码次数还是合格数量统计。
|
||
|
|
- 异常量：按异常单数还是异常问题数统计。
|
||
|
|
- 维修量：按维修单数、维修尝试次数还是完成数量统计。
|
||
|
|
- 维修工序步骤：必须使用提交时快照，不能读取当前配置。
|
||
|
|
|
||
|
|
### 6.2 增加质量和效率指标
|
||
|
|
|
||
|
|
建议新增以下指标：
|
||
|
|
|
||
|
|
- 首次通过率（FPY）。
|
||
|
|
- 异常率、每千台缺陷数和缺陷密度。
|
||
|
|
- 平均维修时长（MTTR）。
|
||
|
|
- 异常响应时长和待维修积压时长。
|
||
|
|
- 各工序/步骤产能、异常率、维修率和返修率。
|
||
|
|
- 按产品、物料、班组、工号、责任人员和时间段进行对比。
|
||
|
|
|
||
|
|
### 6.3 查询页面增强
|
||
|
|
|
||
|
|
- 统一异常、维修、扫码、整机四类记录的筛选条件和分页行为。
|
||
|
|
- 时间线支持按事件类型、工序、步骤、工号、操作人和状态筛选。
|
||
|
|
- 查询结果支持导出当前筛选条件，并在导出文件中保留快照字段。
|
||
|
|
- 对大时间范围查询增加异步导出，避免请求超时。
|
||
|
|
- 为常用查询保存筛选方案，例如“今日待维修”“本周高频故障”。
|
||
|
|
|
||
|
|
## 7. 扫码端和现场作业增强（P1）
|
||
|
|
|
||
|
|
### 7.1 弱网和离线队列
|
||
|
|
|
||
|
|
`scanapp` 目前以接口实时提交为主，现场网络中断时容易影响作业连续性。
|
||
|
|
|
||
|
|
建议增加：
|
||
|
|
|
||
|
|
- 本地待提交队列，保存条码、工序、步骤、状态、工号和请求编号。
|
||
|
|
- 网络恢复后自动重试，服务端按请求编号幂等处理。
|
||
|
|
- 队列状态页：待同步、同步中、成功、失败和需人工处理。
|
||
|
|
- 离线期间禁止使用无法本地校验的高风险操作，并明确提示用户。
|
||
|
|
|
||
|
|
### 7.2 扫码效率和设备能力
|
||
|
|
|
||
|
|
- 连续扫码模式和批量数量录入。
|
||
|
|
- 扫码音效、震动、闪光灯和成功/失败颜色反馈可配置。
|
||
|
|
- 设备绑定、设备编号、车间/产线绑定和异常设备上报。
|
||
|
|
- 支持扫码枪键盘输入与摄像头扫码自动切换。
|
||
|
|
- 对重复条码、无效条码和跨工序条码提供明确的现场提示。
|
||
|
|
|
||
|
|
### 7.3 现场首页
|
||
|
|
|
||
|
|
扫码端首页建议显示：
|
||
|
|
|
||
|
|
- 当前登录工号和当前班次。
|
||
|
|
- 当前工序/步骤和待完成数量。
|
||
|
|
- 待处理异常、待维修订单和离线待同步数量。
|
||
|
|
- 常用操作入口：生产录入、异常提报、维修处理、查询。
|
||
|
|
|
||
|
|
## 8. 权限、审计和安全（P0/P1）
|
||
|
|
|
||
|
|
- 按角色限制生产录入、异常提报、维修处理、流程配置、统计查看和数据导出。
|
||
|
|
- 工艺配置修改必须记录前后值、修改人、修改时间和发布版本。
|
||
|
|
- 敏感字段如用户编码、手机号和图片下载地址按权限脱敏。
|
||
|
|
- 所有导出记录写入审计日志，包含筛选条件和导出人。
|
||
|
|
- 前台公共接口只开放必要的查询和提交能力，管理接口继续使用权限中间件。
|
||
|
|
- 关键业务接口增加限流、请求编号、来源端标识和异常告警。
|
||
|
|
|
||
|
|
## 9. 多端一致性和工程维护建议
|
||
|
|
|
||
|
|
### 9.1 抽取共享业务规则
|
||
|
|
|
||
|
|
当前前台 API 和 AppAPI 都由 `DataEntryController` 承担大量业务方法，长期维护容易出现逻辑分叉。
|
||
|
|
|
||
|
|
建议：
|
||
|
|
|
||
|
|
- 将工序校验、步骤校验、重复扫码、异常关联维修、物料校验抽到领域 Service。
|
||
|
|
- Web、扫码端和后台只负责参数接收、权限处理和结果格式化。
|
||
|
|
- 为共享 Service 增加接口级测试和关键场景测试。
|
||
|
|
|
||
|
|
### 9.2 模板源优先
|
||
|
|
|
||
|
|
生产插件前端正式维护顺序应保持：
|
||
|
|
|
||
|
|
1. 先修改 `backend/plugin/produce/resource/template`。
|
||
|
|
2. 再同步到 `frontend/admin/src/apps/produce` 或 `frontend/web/app/apps/produce`。
|
||
|
|
3. 核对模板源和运行目录内容一致。
|
||
|
|
4. 对涉及安装复制的改动执行一次重装回归验证。
|
||
|
|
|
||
|
|
### 9.3 接口契约和错误码
|
||
|
|
|
||
|
|
- 统一返回字段：记录 ID、请求编号、业务状态、可重试标记和用户提示。
|
||
|
|
- 错误信息区分“用户输入错误”“流程配置错误”“权限错误”“系统暂时不可用”。
|
||
|
|
- 为工序、步骤、状态、异常、维修和统计接口补充稳定的请求/响应类型定义。
|
||
|
|
|
||
|
|
## 10. 推荐实施路线
|
||
|
|
|
||
|
|
### 第一阶段：数据正确性和现场稳定性
|
||
|
|
|
||
|
|
1. 维修记录增加工序/步骤快照并回填历史数据。
|
||
|
|
2. 增加提交幂等机制和重复点击保护。
|
||
|
|
3. 统一实际作业人员、系统操作人和代录信息。
|
||
|
|
4. 梳理异常到维修的状态闭环。
|
||
|
|
5. 修正统计和时间线的数据口径。
|
||
|
|
|
||
|
|
### 第二阶段：管理效率和统计决策
|
||
|
|
|
||
|
|
1. 工序流程可视化、规则校验和流程发布版本。
|
||
|
|
2. 统计增加 FPY、异常率、MTTR、返修率和 Pareto 分析。
|
||
|
|
3. 维修备件库存、领退料和库存预警。
|
||
|
|
4. 附件统一管理和导出能力增强。
|
||
|
|
5. 查询页面支持保存筛选方案和异步导出。
|
||
|
|
|
||
|
|
### 第三阶段：现场数字化和智能化
|
||
|
|
|
||
|
|
1. 扫码端离线队列和自动同步。
|
||
|
|
2. 设备、产线、班次和工位管理。
|
||
|
|
3. 现场首页和班组看板。
|
||
|
|
4. 流程模拟器、异常趋势预警和责任分析。
|
||
|
|
5. 在数据稳定后再评估预测性维修或智能推荐功能。
|
||
|
|
|
||
|
|
## 11. 建议优先立项的五项功能
|
||
|
|
|
||
|
|
如果只选择最有价值的五项，建议顺序如下：
|
||
|
|
|
||
|
|
1. **维修工序/步骤快照**：直接解决历史统计失真的核心问题。
|
||
|
|
2. **提交幂等和离线同步基础**：减少现场重复数据和漏数据。
|
||
|
|
3. **异常—维修状态闭环**：让待维修、维修中、验证和关闭有统一规则。
|
||
|
|
4. **流程版本和可视化校验**：降低工艺配置错误对生产现场的影响。
|
||
|
|
5. **质量效率指标看板**：把现有记录转化为可执行的管理决策。
|
||
|
|
|
||
|
|
## 12. 结论
|
||
|
|
|
||
|
|
生产插件的基础模块已经比较完整，下一步重点不应只是继续增加页面，而应优先保证“数据在提交时被正确记录、历史可追溯、现场可持续作业、统计口径一致”。
|
||
|
|
|
||
|
|
建议以第一阶段五项功能为主线，完成数据模型和接口契约后，再扩展库存、流程版本、离线和智能分析，能够以较小风险获得最大的业务收益。
|