# 库存效期模块(定时预警任务) 本文档基于源码实现(单一事实来源),定位与说明项目中关于库存效期扫描与预警的定时任务行为。实现文件: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