工资条只给自己看:manufacturing-wechat-miniapp-starter 薪资确认与签名哈希设计详解
工资条只给自己看:manufacturing-wechat-miniapp-starter 薪资确认与签名哈希设计详解
manufacturing-wechat-miniapp-starter 是一个隐私优先的微信小程序起步框架,为中小制造企业打造员工自助服务入口:员工在熟悉的微信小程序里查看自己的工资条、完成薪资确认,而系统只保存签名内容的 SHA-256 哈希,不保存签名原文。本文用通俗的方式,讲清楚它"工资条只给自己看"背后的权限设计与签名哈希机制,适合想了解微信小程序安全边界的初学者。
一、为什么工资条"只给自己看"这么重要?
工资、考勤、签名都属于高敏感数据。很多团队的第一反应是"先把功能做出来再说",结果往往出现三类问题:
- 🔓 越权访问:接口没校验归属,员工 A 换个 ID 就能看到员工 B 的工资条;
- 📝 签名原文落库:手写签名、电子签名整张存进数据库,一旦泄露无法挽回;
- 🔁 重复确认、状态混乱:网络抖动导致确认按钮点了两次,账目对不上。
这个项目的思路是:工资确认不是"发工资",而是一个受控的自助动作。工资单由 HR/薪资系统发布,小程序端只做两件事——列出属于本人的工资单、记录本人的确认动作。相关的服务端接口统一收口在 handler.js 中,客户端只能调用 payroll.list 和 payroll.acknowledge 这两个动作,无法绕过。
二、最小可见范围:员工只能看到自己的工资单
核心逻辑在 payroll.js 的 listPayroll 函数里,规则非常直白:
- 先从已验证的平台身份解析出当前员工(而不是信任客户端传的员工 ID);
- 遍历工资单时,只保留
employeeId === 当前员工且published === true的记录; - 返回给页面的只有期间类型、期间、金额、币种和确认时间,不带任何多余字段。
身份解析依赖 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 中的隐私与安全清单补齐:
- 接入企业自己的身份提供方,身份从服务端上下文派生;
- 数据库集合禁止小程序客户端直读直写(员工、工资、签名、考勤、审计数据全部留在服务端);
- 加密存储、审计保留、限流、备份与监控;
- 制定数据最小化、保留期、删除与用户告知策略。
小结
manufacturing-wechat-miniapp-starter 用一份极小的代码量,示范了员工端敏感业务的完整安全姿势:身份由服务端验证、数据只给本人看、确认必须显式、重复操作幂等、签名只存哈希。对于要搭建工资条确认、电子签收、员工自助类小程序的团队,这套"薪资确认 + 签名哈希"的边界设计可以直接当作参考模板。