WMS_MAIN/docs/stock-expiry-module.md
2026-04-17 19:21:57 +08:00

5.5 KiB
Raw Blame History

库存效期模块(定时预警任务)

本文档基于源码实现(单一事实来源),定位与说明项目中关于库存效期扫描与预警的定时任务行为。实现文件:app/schedule/notice_stock_remaining.js。

概要

  • 任务名称/文件:app/schedule/notice_stock_remaining.js
  • 调度配置:interval: '30s'、type: 'worker'、immediate: false(见文件头部 schedule 配置)
  • 目的:扫描启用保质期管理的仓库商品与对应库存(wms_stock_warehouse / wms_storage),对即将到期的库存发送效期预警通知,并通过缓存进行去重。

主要实现要点(按代码实现逐项说明)

  1. 并发保护

    • 使用进程级标记 ctx.app._noticeStockRemainingRunning,若上一轮尚未结束则跳过本次运行。
  2. 通知去重缓存

    • 缓存键:notice_stock_remaining_notified_list(文件常量 CACHE_KEY)。
    • 缓存 TTL:24 小时(CACHE_TTL_SECONDS = 24 * 60 * 60)。
    • 缓存存储格式兼容数组或对象,读取后标准化为 storage:{id} 格式的键集合用于去重。
  3. 读取候选商品(wms_stock_warehouse)

    • 查询条件(stockWhere):
      • is_shelf_life_mgmt: 'Y'
      • remaining_threshold_days: { [Op.gt]: 0 }(使用 Sequelize.Op.gt)
    • 查询字段:id, item_code, item_name, store_id, warehouse_id, remaining_threshold_days
    • 排序:remaining_threshold_days ASC, id ASC
    • 结果用于构建 stockMap(包含每个 stock 的阈值),并计算 maxThresholdDays(用于缩小后续库存扫描时间窗口)。
  4. 计算候选库存时间窗口

    • 以当前时间 now,计算 maxExpiryDate = new Date(now.getTime() + maxThresholdDays * DAY_MS),其中 DAY_MS = 24 * 60 * 60 * 1000。
  5. 查询候选库存记录(wms_storage)

    • 查询条件(storageWhere):
      • stock_id 在上一步筛选得到的 stockIds 列表中
      • is_enabled: 1
      • delete_at: null(paranoid 软删除过滤)
      • quantity: { [Op.gt]: 0 }
      • expiry_date: { [Op.ne]: null, [Op.lte]: maxExpiryDate }(到期日非空且小于等于计算窗口)
    • include:关联 LocationSpace(别名 space),属性取 space_code, custom_name,required: false。
    • 排序:expiry_date ASC, inbound_time ASC, id ASC。
    • 注意:实现中调用的是 findAll(无分页),因此会拉取匹配的全部候选记录并在内存中逐条处理。
  6. 单条记录处理与判断逻辑

    • 对每条 storageRecord:
      • 生成去重键 notifyKey = storage:{storageId}(若无法解析 id 则跳过)。
      • 若该 notifyKey 已存在于缓存集合则跳过(避免重复通知)。
      • 根据 stockMap 获取本条记录对应商品的 thresholdDays(阈值天数);若不存在或阈值 <= 0 则跳过。
      • 读取 expiry_date,将其解析为 Date;若无或解析失败则跳过并记录 warn。
      • 计算剩余天数:remainingDays = Math.max(0, Math.ceil((expiryDate - now) / DAY_MS))。
      • 若 remainingDays > thresholdDays 则跳过(未达到阈值);否则组装通知并发送。
  7. 通知发送与元数据

    • 使用通知服务:ctx.service.systems.notice.send(payload)。代码中若 noticeResult.success === false 则认为发送失败并保留重试;异常时记录错误并继续处理下一条。
    • 通知 payload 包含(示例字段):
      • warehouseId, storeId, subject(id/type/name), businessName: 'storage', event(常量 storage_transfer_completed),title, content, businessId: storageId, messageType: 'text'
      • metadata:包含 cacheKey, storageId, stockId, notifyKey, thresholdDays, remainingDays, warehouseId, storeId, stock: { id, item_code, item_name }, storage: { id, batch_no, expiry_date (ISO) }
  8. 回写去重缓存

    • 成功发送后,将 notifyKey 添加到 updatedNotifiedList 并在本轮结束后使用 ctx.app.setCacheAsync(CACHE_KEY, dedupedList, CACHE_TTL_SECONDS) 回写缓存(如果 setCacheAsync 可用)。
  9. 日志与统计

    • 任务会记录候选商品数、候选库存数、实际发送计数与跳过计数;发送失败与异常会记录 warn/error 日志。

与公开 API 的关系

  • 任务为内部定时任务(非 system API),其查询条件与模型字段直接对应数据库表 wms_stock_warehouse 与 wms_storage。
  • 若需要通过 API 查询某个商品的库存明细(包含批次与过期信息),请使用已有的 system 方法 stock.warehouse.getStockDetail(该接口支持 pagination 与 group_by_batch,API 文档位于 methods/system.json),与本任务的扫描逻辑互为补充:任务用于主动推送预警,API 用于按需查询。

注意事项(运维/集成)

  • 通知发送依赖 ctx.service.systems.notice,在无该服务或返回异常时任务仅记录日志。
  • 任务扫描不分页:对于极大库存量的仓库,建议评估 maxThresholdDays 与索引(idx_expiry_date 已存在于模型)对查询性能的影响,或考虑将查询改为分片/分页处理。
  • 去重缓存使用全局缓存接口 getCacheAsync / setCacheAsync,请保证缓存后台(如 Redis)可用以避免重复通知泛滥。

实现位置(代码参考)

  • 定时任务文件:app/schedule/notice_stock_remaining.js
  • 依赖模型:app/model/stock_warehouse.js、app/model/storage.js、app/model/location_space.js
  • 依赖服务:ctx.service.systems.notice