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

81 lines
5.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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