工资条只给自己看:manufacturing-wechat-miniapp-starter 薪资确认与签名哈希设计详解

原创2026-11-12 14:27:381,686 阅读

工资条只给自己看:manufacturing-wechat-miniapp-starter 薪资确认与签名哈希设计详解

manufacturing-wechat-miniapp-starter 是一个隐私优先的微信小程序起步框架,为中小制造企业打造员工自助服务入口:员工在熟悉的微信小程序里查看自己的工资条、完成薪资确认,而系统只保存签名内容的 SHA-256 哈希,不保存签名原文。本文用通俗的方式,讲清楚它"工资条只给自己看"背后的权限设计与签名哈希机制,适合想了解微信小程序安全边界的初学者。

一、为什么工资条"只给自己看"这么重要?

工资、考勤、签名都属于高敏感数据。很多团队的第一反应是"先把功能做出来再说",结果往往出现三类问题:

  • 🔓 越权访问:接口没校验归属,员工 A 换个 ID 就能看到员工 B 的工资条;
  • 📝 签名原文落库:手写签名、电子签名整张存进数据库,一旦泄露无法挽回;
  • 🔁 重复确认、状态混乱:网络抖动导致确认按钮点了两次,账目对不上。

这个项目的思路是:工资确认不是"发工资",而是一个受控的自助动作。工资单由 HR/薪资系统发布,小程序端只做两件事——列出属于本人的工资单、记录本人的确认动作。相关的服务端接口统一收口在 handler.js 中,客户端只能调用 payroll.list 和 payroll.acknowledge 这两个动作,无法绕过。

二、最小可见范围:员工只能看到自己的工资单

核心逻辑在 payroll.js 的 listPayroll 函数里,规则非常直白:

  1. 先从已验证的平台身份解析出当前员工(而不是信任客户端传的员工 ID);
  2. 遍历工资单时,只保留 employeeId === 当前员工 且 published === true 的记录;
  3. 返回给页面的只有期间类型、期间、金额、币种和确认时间,不带任何多余字段。

身份解析依赖 attendance.js 中的 employeeForActor:它要求请求必须携带服务端验证过的 subjectId,并用它去匹配在职员工档案。匹配不到就抛出 EMPLOYEE_NOT_BOUND,请求直接被拒。

这套"服务端身份优先"的原则也写进了网关说明——客户端永远不提交可信身份标识,生产环境必须从 CloudBase 执行上下文中派生身份,详见 README.md。对应的测试文件 payroll.test.js 里有一条专门验证:员工 A 尝试确认员工 B 的工资单,会被 FORBIDDEN 拦截。

小建议:如果你在开发类似的员工端小程序,请记住一条黄金法则——"我是谁"由服务端决定,而不是客户端声明。

三、确认规则:日结要确认,月薪要签名

acknowledgePayroll 函数定义了两种工资单的不同确认门槛(见 payroll.js):

工资单类型 确认要求 额外动作
日结(day) 必须显式传 confirmed: true 无
月薪(month) 显式确认 + 一个"认真"的签名载荷 签名长度 ≥ 12 个字符,否则返回 SIGNATURE_REQUIRED

几个细节值得新手注意:

  • 显式确认是硬要求:confirmed 不是 true 就抛 CONFIRMATION_REQUIRED,防止"默认勾选"式的静默确认;
  • 重复确认是安全的:已经确认过的工资单再次提交,会返回 replayed: true 和原确认时间,不会产生第二条记录——这正是"幂等"设计的价值,网络重试也不会出错;
  • 每次确认都会写审计日志:记录事件类型、工资单 ID、员工 ID 和时间点,方便事后追溯。

小程序端的页面逻辑很薄,payroll.list 拉取列表、payroll.acknowledge 提交确认,见 payroll.js 和页面模板 payroll.wxml,接口封装在 api.js 中。

四、签名哈希:只存"指纹",不存"原件"

月薪确认要求员工提交签名载荷,但系统绝不保存签名本身,只保存它的 SHA-256 哈希:

// 摘自 src/payroll.js
if (item.periodType === "month") {
  assertDomain(typeof input.signature === "string" && input.signature.trim().length >= 12,
    "SIGNATURE_REQUIRED", "Monthly payroll requires a deliberate signature payload");
  item.signatureHash = sha256(input.signature.trim());
}

哈希函数在 crypto.js 中实现,有两个工程亮点:

  • 规范化 JSON(canonical JSON):对对象先按键名排序再序列化,保证"内容相同、书写顺序不同"的载荷算出同一个哈希,避免对账扯皮;
  • 统一出口:MES 导出的 payloadHash(见 connector.js)和薪资签名复用同一套实现,整个项目的"完整性指纹"口径一致。

测试用例验证了这一点:确认完成后,数据行里的 signatureHash 是 64 位十六进制串,而原始签名不会出现在任何存储内容中(见 payroll.test.js 中 "stores hash instead of signature body" 用例)。

哈希能证明什么?

打个比方:签名原文像你的指纹原件,哈希值像指纹的拓印。

  • ✅ 可以事后校验:员工再次提交相同签名,哈希一致,说明是同一份确认动作;
  • ✅ 可以防篡改:数据库里的哈希被改动,一比对就能发现;
  • ❌ 不能还原原文:SHA-256 是单向函数,拿哈希推不回签名内容。

这也是安全文档 SECURITY.md 明确禁止上报真实签名数据的原因——连安全事件报告都不该附签名原文。

五、快速跑起来看看

项目零依赖,Node.js 20+ 即可运行测试和演示:

npm test
npm run demo

演示脚本 demo.js 使用全合成数据(员工、工资单都是虚构的,见 seed.js),运行结果只会输出合成标识、MES 回执和 SHA-256 载荷哈希。如果想验证薪资相关的全部边界(越权、重复确认、缺签名、确认他人工资单),直接阅读 payroll.test.js 即可,每个用例都对应一个明确的安全场景。

六、上线前还要补什么?

这个 starter 刻意不包含可部署的身份、数据库与密钥配置,目的是防止"演示身份模型"被误当成生产认证。正式落地前建议对照 README.md 中的隐私与安全清单补齐:

  1. 接入企业自己的身份提供方,身份从服务端上下文派生;
  2. 数据库集合禁止小程序客户端直读直写(员工、工资、签名、考勤、审计数据全部留在服务端);
  3. 加密存储、审计保留、限流、备份与监控;
  4. 制定数据最小化、保留期、删除与用户告知策略。

小结

manufacturing-wechat-miniapp-starter 用一份极小的代码量,示范了员工端敏感业务的完整安全姿势:身份由服务端验证、数据只给本人看、确认必须显式、重复操作幂等、签名只存哈希。对于要搭建工资条确认、电子签收、员工自助类小程序的团队,这套"薪资确认 + 签名哈希"的边界设计可以直接当作参考模板。

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