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