5.5 KiB
5.5 KiB
库存效期模块(定时预警任务)
本文档基于源码实现(单一事实来源),定位与说明项目中关于库存效期扫描与预警的定时任务行为。实现文件:app/schedule/notice_stock_remaining.js。
概要
- 任务名称/文件:
app/schedule/notice_stock_remaining.js - 调度配置:
interval: '30s'、type: 'worker'、immediate: false(见文件头部 schedule 配置) - 目的:扫描启用保质期管理的仓库商品与对应库存(wms_stock_warehouse / wms_storage),对即将到期的库存发送效期预警通知,并通过缓存进行去重。
主要实现要点(按代码实现逐项说明)
-
并发保护
- 使用进程级标记
ctx.app._noticeStockRemainingRunning,若上一轮尚未结束则跳过本次运行。
- 使用进程级标记
-
通知去重缓存
- 缓存键:
notice_stock_remaining_notified_list(文件常量CACHE_KEY)。 - 缓存 TTL:24 小时(
CACHE_TTL_SECONDS = 24 * 60 * 60)。 - 缓存存储格式兼容数组或对象,读取后标准化为
storage:{id}格式的键集合用于去重。
- 缓存键:
-
读取候选商品(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(用于缩小后续库存扫描时间窗口)。
- 查询条件(stockWhere):
-
计算候选库存时间窗口
- 以当前时间
now,计算maxExpiryDate = new Date(now.getTime() + maxThresholdDays * DAY_MS),其中DAY_MS = 24 * 60 * 60 * 1000。
- 以当前时间
-
查询候选库存记录(wms_storage)
- 查询条件(storageWhere):
stock_id在上一步筛选得到的stockIds列表中is_enabled: 1delete_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(无分页),因此会拉取匹配的全部候选记录并在内存中逐条处理。
- 查询条件(storageWhere):
-
单条记录处理与判断逻辑
- 对每条
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则跳过(未达到阈值);否则组装通知并发送。
- 生成去重键
- 对每条
-
通知发送与元数据
- 使用通知服务:
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) }
- 使用通知服务:
-
回写去重缓存
- 成功发送后,将
notifyKey添加到updatedNotifiedList并在本轮结束后使用ctx.app.setCacheAsync(CACHE_KEY, dedupedList, CACHE_TTL_SECONDS)回写缓存(如果setCacheAsync可用)。
- 成功发送后,将
-
日志与统计
- 任务会记录候选商品数、候选库存数、实际发送计数与跳过计数;发送失败与异常会记录 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