JhHardwareWRS/docs/api.md

嘉恒智能报工小程序接口边界

小程序端不能直连 MySQL。生产环境需要一个 HTTPS 后端服务，使用环境变量读取数据库连接信息，并调用微信服务端接口完成手机号解密、订阅通知和小程序码生成。

Excel 字段

本次读取到的 /Users/souplearn/Downloads/产品清单.xlsx 表头为：

项目号、型材号、产品名称、物料编码、物料名称、使用设备、工序、冲压方式、操作人数、不包含物料转运节拍、标准节拍

导入产品时：

• 型材号 保存到 products.profile_no。
• 使用设备 保存到 products.device_no。
• 不包含物料转运节拍 忽略，不进入小程序业务。
• 标准工作量 如果 Excel 没有提供，由后端按 28800 / 标准节拍 生成 8 小时日标准量。
• Excel 中空白 项目号 建议沿用上一行项目号，导入前端也应展示导入预览和错误行。

推荐接口

登录

• POST /api/auth/wechat-login
• GET /api/auth/me：获取当前账号和同一手机号下的所有角色。
• POST /api/auth/switch-role：已登录账号切换当前角色，返回新的 token。
• 入参：code、encryptedData、iv 或新版本手机号授权凭证。
• 逻辑：获取手机号后，在 personnel 表匹配；多个手机号时返回人员表中存在的手机号供用户选择。
• 返回：当前人员、角色、token。

产品

• POST /api/products/import：上传《产品清单》Excel，解析并 upsert。
• GET /api/products：分页、关键词、设备号筛选。
• POST /api/products：新增或修改产品。
• DELETE /api/products：按 project_no + product_name + device_no + process_name 删除产品。

产品唯一键为：项目号 + 产品名称 + 使用设备号 + 工序。

人员

• POST /api/people/import：上传《人员清单》Excel，字段为电话号、姓名、角色。
• GET /api/people：分页和关键词筛选。
• POST /api/people：新增或修改人员。
• DELETE /api/people/:phone?role=worker：删除手机号下的某个角色。

人员口径：一个手机号绑定一个姓名，同一手机号可以有多个角色；登录时如果该手机号只有一个角色，直接登录，如果有多个角色，小程序会要求选择本次登录角色。

设备二维码

• POST /api/devices/:deviceNo/qrcode
• 后端调用微信 getUnlimitedQRCode，scene 建议为 deviceNo=20%23，page 为 pages/clock/clock。
• 返回可打印的小程序码图片地址。

扫码报工

• GET /api/clock/state?deviceNo=20%23
• POST /api/clock/start
• POST /api/clock/switch-device
• POST /api/clock/finish

状态规则：

• 没有 active session：只返回 开始上班。
• 有 active session 且设备没出现过：只返回 换设备。
• 有 active session 且设备出现过：只返回 下班报工。
• 点击 下班报工 后进入 reporting session，30 分钟内返回 继续报工，员工可继续填写原报工。
• 超过 30 分钟未提交时返回 重新报工，员工点击后更新下班时间为重新报工时间，再重新填写报工。

报工提交

• GET /api/reports/draft?sessionId=...：按设备号拉取产品候选项。
• POST /api/reports：员工确认提交，report_date 使用确认提交当天日期。
• 报工草稿和提交都会校验 30 分钟填写有效期；超时必须重新扫码点击 重新报工。
• GET /api/reports/mine：员工按日期查看自己的报工记录。

审核

• GET /api/reviews/pending：管理员待审核报工。
• POST /api/reviews/:reportId/approve：管理员通过，或修正明细后通过。
• POST /api/reviews/:reportId/reject：管理员驳回并写原因。
• PATCH /api/reports/:reportId/break-minutes：仅经理可修改休息间隔，必须写 report_audit_logs。
• GET /api/reviews/mine：管理员自己的审核记录，支持日期筛选。

经理看板

• GET /api/dashboard/reports?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&page=1
• 后端只统计 approved 报工，并按 report_date + employee_phone 合并。
• 返回实际节拍、标准节拍、节拍正负百分比、报工数量、标准工作量、工作量正负百分比。

关键计算口径

• 报工日期：员工点击提交后再确认的日期。
• 有效工时：下班时间 - 上班时间 - 休息间隔，休息间隔只能经理修改。
• 实际节拍：有效工时秒数 / (成品数量 + 不良数量)，报废计入不良数量。
• 标准节拍：按明细产出数量加权平均。
• 标准工作量：使用产品表导入或手动维护的 标准工作量，多条明细时累加。
• 工作量对比：(成品数量 - 标准工作量) / 标准工作量。