前端对接仓库配货 / 打包

员工处罚待确认弹窗

pending-popup 接口：每日 14:00 批次、未登录则登录即弹、多端只弹一次均由后端判定；含调用时机、14 点定时参考实现与弹窗交互说明

端
仓管小程序
后端服务
supplier
状态
已上测
更新
2026-10-09
接口数
2

Markdown 原文（给 AI 用）：https://doc.xfun.fun/wms-punish-popup-api.md

总览

接口定义

POST/wms-punish-appeal/pending-popup

新增

查询处罚待确认弹窗。鉴权方式与「我的处罚列表」 /wms-punish-appeal/list 相同（Header 带 Authorization）。

请求参数

无。Body 可传空对象 {} 或不传。

响应 data 字段

字段类型说明
showFlagInteger是否弹窗：1 = 弹，0 = 不弹
pendingCountLong待处理处罚笔数（showFlag=0 时为 0）
pendingAmountBigDecimal待确认金额，单位元，已保留 2 位小数（showFlag=0 时为 0）

响应示例：需要弹窗

json
{
  "code": 0,
  "msg": "success",
  "data": { "showFlag": 1, "pendingCount": 3, "pendingAmount": 150.00 }
}

响应示例：不弹窗

json
{
  "code": 0,
  "msg": "success",
  "data": { "showFlag": 0, "pendingCount": 0, "pendingAmount": 0 }
}
说明

判断是否弹窗 只看 showFlag，不要用 pendingCount > 0 判断：已经弹过的批次后端会返回 showFlag=0、pendingCount=0，即使用户仍有待处理处罚。

注意

金额 JSON 中是数字，前端展示时请统一格式化为两位小数（Number(v).toFixed(2)），例如 150 显示为 ¥150.00。

调用时机（前端要做的）

时机说明
① 登录成功后对应需求「未登录的用户，登录时立即弹」
② 小程序 onShow（App 级或首页）带着本地 token 冷启动、从后台切回前台都算「进入系统」；也用于补偿 14:00 时小程序在后台、定时器没跑的情况
③ 在线定时：当天 14:00 + 随机 0~60 秒对应需求「已登录的用户 14:00 弹一次」。加随机延迟是为了避免所有在线用户同一秒请求

参考实现（伪代码，按项目框架调整）

js
// 统一入口：任何时机都只调这个函数，后端负责去重
async function checkPunishPopup() {
  if (!getToken()) return;
  const res = await request.post('/wms-punish-appeal/pending-popup', {});
  const d = res && res.data;
  if (d && d.showFlag === 1) {
    showPunishPopup(d.pendingCount, Number(d.pendingAmount).toFixed(2));
  }
}

// 时机③：在线时到 14:00 触发一次
let popupTimer = null;
function scheduleTwoPm() {
  clearTimeout(popupTimer);
  const now = new Date();
  const target = new Date(now);
  target.setHours(14, 0, 0, 0);
  if (now >= target) target.setDate(target.getDate() + 1);   // 今天已过 14 点则排到明天
  const jitter = Math.floor(Math.random() * 60 * 1000);       // 0~60 秒随机打散
  popupTimer = setTimeout(() => { checkPunishPopup(); scheduleTwoPm(); },
                          target - now + jitter);
}

// 登录成功回调里：checkPunishPopup(); scheduleTwoPm();
// onShow 里：      checkPunishPopup(); scheduleTwoPm();   // 切回前台时重排定时器
// 退出登录 / onHide：clearTimeout(popupTimer);
说明

设备本地时间不准没关系：定时器只决定「什么时候问一次」，弹不弹以后端（北京时间）为准。最坏情况是晚一点在下次 onShow 时弹出。

后端判定规则（了解即可）

后端以 **「最近一个已经过去的 14:00」**作为提醒批次，每个用户每个批次最多弹一次：当前 ≥ 今天 14:00 → 批次是今天；当前 < 今天 14:00 → 批次是昨天。

一个用户的一天（假设一直有 2 笔待确认处罚）

时间发生了什么
09:30登录 → 昨天的批次已经弹过 → 不弹
14:00:23在线定时器触发 → 今天批次未弹 → 弹（显示 2 笔）
15:10切回前台 onShow → 今天批次已弹 → 不弹
16:00另一台手机登录同一账号 → 今天批次已弹 → 不弹（多端只弹一次）
次日 08:50登录 → 批次仍是「昨天」，已弹过 → 不弹；等到当天 14:00 再弹

其他情况

弹窗交互

元素内容 / 行为
标题您有处罚待确认
说明您当前有处罚订单待确认，请及时前往处理。逾期未确认，系统将按规则自动确认。
待处理订单{pendingCount}笔
待确认金额¥ {pendingAmount}（两位小数）
提示条请尽快确认处罚信息，如有异议可发起申诉
【前往处理】关闭弹窗 → 跳转「我的处罚」列表，默认筛选待确认（列表接口 /wms-punish-appeal/list 传 status=0）
【稍后处理】直接关闭，不调接口
底部小字本弹窗仅作消息提醒，具体处罚信息以处罚详情为准
自动关闭弹出后 3 秒无任何操作自动关闭；用户在 3 秒内 触碰弹窗任意位置即取消倒计时，之后只能手动关闭
说明

文案全部前端写死，接口只返回两个数字。弹窗关闭（无论哪种方式）都 不需要回调后端：后端在返回 showFlag=1 的同时就已记为「已弹」。

联调注意

测试环境专用：重置弹窗标记 10-12 新增

POST/test/wms-punish-popup/reset

调试循环

text
POST /test/wms-punish-popup/reset     // 清标记
POST /wms-punish-appeal/pending-popup // → showFlag=1，弹窗
POST /wms-punish-appeal/pending-popup // → showFlag=0（已弹过）
POST /test/wms-punish-popup/reset     // 再清，下一次又会弹 …

调试期间可以在开发版里临时加一个「重置弹窗」按钮调用它；也可以用 curl：

bash
curl -X POST '<测试环境域名>/test/wms-punish-popup/reset' -H 'Authorization: <员工token>'