98 lines
4.7 KiB
Markdown
98 lines
4.7 KiB
Markdown
# 嘉恒智能报工小程序接口边界
|
||
|
||
小程序端不能直连 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` 合并。
|
||
- 返回实际节拍、标准节拍、节拍正负百分比、报工数量、标准工作量、工作量正负百分比。
|
||
|
||
## 关键计算口径
|
||
|
||
- 报工日期：员工点击提交后再确认的日期。
|
||
- 有效工时：`下班时间 - 上班时间 - 休息间隔`，休息间隔只能经理修改。
|
||
- 实际节拍：`有效工时秒数 / (成品数量 + 不良数量)`，报废计入不良数量。
|
||
- 标准节拍：按明细产出数量加权平均。
|
||
- 标准工作量：使用产品表导入或手动维护的 `标准工作量`，多条明细时累加。
|
||
- 工作量对比：`(成品数量 - 标准工作量) / 标准工作量`。
|