班前安全确认怎么填?manufacturing-wechat-miniapp-starter 动态表单模板与草稿提交实战

原创2026-11-12 15:03:591,457 阅读

班前安全确认怎么填?manufacturing-wechat-miniapp-starter 动态表单模板与草稿提交实战

在制造业一线,班前安全确认、设备点检、异常上报往往还靠纸质单据或群消息,信息滞后且难以追溯。manufacturing-wechat-miniapp-starter 是一个隐私优先的微信小程序 Starter,帮中小制造企业把员工熟悉的微信小程序变成一线数据入口:员工在手机上填写"班前安全确认"这类动态表单,数据经服务端校验后回传给 MES 系统。本文用一个真实的"班前安全确认"示例,带你从零理解动态表单模板、必填校验、草稿保存与提交留痕的完整链路。

一、动态表单模板长什么样?

项目内置了一份合成种子数据,其中就包含一个名为**"班前安全确认"**的表单模板 src/seed.js:

字段 key 字段标签 类型 是否必填
equipment 设备状态 select ✅ 必填
note 补充说明 text 选填

模板定义了哪些字段允许出现、哪些字段必须填写。这就是"动态表单"的核心思路:表单结构由模板驱动,而不是写死在页面里,以后要加"防护用品检查""风险提示"等字段,只需新增模板,无需改页面逻辑。

模板加载时会做一次活性检查:只有 active: true 的模板才能被使用,否则会抛出 FORM_TEMPLATE_NOT_FOUND 错误(见 src/forms.js)。

二、员工端怎么填?一个极简页面

小程序端的表单页位于 miniprogram/pages/forms/forms.wxml,结构非常直白:

  • 卡片标题:班前安全确认
  • 输入项 1:设备状态(占位提示"正常/需检查")
  • 输入项 2:补充说明(占位提示"仅填写完成工作所需的信息")
  • 一个"提交表单"按钮

填写逻辑在 miniprogram/pages/forms/forms.js 中:员工输入两个字段后点击提交,页面调用 API 层的 submitForm,成功时显示 表单已提交:submission-xxxx,失败时把服务端的错误信息展示出来。整个过程不需要员工安装任何 App,也不需要额外学习成本。

💡 小贴士:补充说明字段是选填的,但不要写空泛内容,只填与工作相关、完成确认所需的信息,这既是隐私最小化原则,也方便后续审计。

三、服务端三道校验:缺项、错项、未知项一个都别想混

提交表单时,服务端会在 src/forms.js 中执行 validateValues 校验,规则是fail-closed(拒绝优先):

  1. 未知字段直接拒绝 —— 如果提交里带了模板没声明的字段(例如偷偷多塞一个 hidden),返回 FORM_FIELD_UNKNOWN;
  2. 必填字段不能为空 —— equipment 缺失或为空字符串,返回 FORM_FIELD_REQUIRED;
  3. 身份必须已绑定 —— 表单归属通过已验证的员工身份解析,未绑定员工档案的用户无法保存或提交。

这些边界行为都有对应的自动化测试覆盖,见 tests/forms.test.js,包括"必填字段强制校验""未知字段拒绝""提交成功"等用例,可以直接阅读了解每条规则的具体断言。

四、草稿保存:填到一半也不慌

班前时间紧,员工可能填了一半就被叫去处理异常。Starter 支持草稿机制:

  • 草稿以"员工 + 模板"为粒度保存(同一员工同一模板只保留一份最新草稿);
  • 草稿里记录保存时间 savedAt,方便追踪填写进度;
  • 提交成功后,对应草稿会被自动清除,避免残留脏数据。

对应实现在 src/forms.js 的 saveDraft 与 submitForm 中;tests/forms.test.js 里有一条 submission clears matching draft 用例,验证了"先存草稿、再提交、草稿被清空"的完整流程。

五、提交之后:编号、时间戳与"只留痕不留内容"的审计

成功提交后,服务端会:

  1. 生成带序号的提交编号,如 submission-0001;
  2. 记录提交人、模板 ID、字段快照和提交时间 submittedAt;
  3. 写入一条 form.submitted 审计事件。

这里有一个值得注意的设计:📝 审计事件只记录事件身份(提交编号、模板 ID、时间),不包含表单正文内容。这意味着管理者可以回答"谁在什么时间提交了哪张表单",但审计日志本身不会扩散员工的填写细节——这在隐私合规上是一个很好的默认姿态。相关断言可参考 tests/forms.test.js 中 form submission is audited without body 用例。

六、从表单数据到 MES:数据如何流转?

整体链路如下(来自 README.md 的架构说明):

微信小程序页面(forms 页面)
       │ action + payload
       ▼
云函数网关 employeeGateway(校验身份)
       │
       ├─ forms.submit → submitForm 领域服务
       └─ mes.export → MES 连接器(幂等键 + 载荷哈希 + 回执)
  • 网关 cloudfunctions/employeeGateway/handler.js 负责把 forms.submit 等动作路由到对应服务,并把领域错误包装成安全的错误信封(只暴露 code 和 message);
  • API 封装层 miniprogram/services/api.js 统一处理"成功返回数据、失败抛出带 code 的错误";
  • 需要把表单结果回传 MES 时,MES 连接器要求携带稳定的幂等键:同一键重复提交会返回原回执而不会重复写入,同键不同内容则直接失败,防止网络抖动导致数据被计入两次。

七、上手建议清单 📋

如果你是刚接触这个 Starter 的开发者,按下面顺序走一遍最顺畅:

  1. 看模板:先读 src/seed.js,理解"班前安全确认"模板的字段定义;
  2. 看校验:再读 src/forms.js,掌握必填、未知字段、模板活性三条规则;
  3. 看页面:对照 miniprogram/pages/forms/forms.wxml 和 miniprogram/pages/forms/forms.js,看前端如何发起提交并展示结果;
  4. 跑测试:执行 npm test,重点观察 tests/forms.test.js 的六个用例输出;
  5. 扩展模板:在自己的环境配置里新增模板(如"设备点检""质量异常上报"),字段结构完全沿用"key + label + type + required"即可。

小结

manufacturing-wechat-miniapp-starter 把"班前安全确认怎么填、填完去哪儿"这个问题拆成了清晰的一层一层的边界:模板驱动表单结构,服务端 fail-closed 校验,草稿可存可清,提交自动编号并留痕,审计只记身份不记内容。你不需要在小程序里发明新的安全规则,只需要按模板定义好字段,剩下的校验、审计与 MES 回传模式都已经在 src/ 和 cloudfunctions/employeeGateway/ 里就位。对于想让一线员工"打开手机就能填、填完就有据可查"的团队来说,这套动态表单模板 + 草稿提交的实战模式,可以直接作为生产改造的参考起点。

登录后查看全文
manufacturing-wechat-miniapp-starter