WMS_MAIN/app/lib/ptz_client.js
liufumingren 1571de341c feat(storage): 新增收货未入库提醒定时任务(货主/客服群通知,短语可配置)
- 新增 app/service/systems/receiving_pending_notice.js:扫描「创建时间超过 min_hours 且不足 max_hours 仍未完成入库」的收货单(wms_receiving 未作废、is_deleted=0,且 status=receiving 或 storage_status<>all),
  按货主聚合成一条消息;未绑定货主的单独一批
- 新增 app/schedule/notice_receiving_pending_inbound.js:每 5 分钟单 worker 检查,按各仓库配置的提醒时间(默认 08:30,宽限 10 分钟覆盖调度抖动)执行,
  进程内防重入 + Redis 当日锁 receiving_pending_notice🔒{warehouseId}:{YYYYMMDD}(NX/EX 24h,执行异常释放锁允许窗口内重试),保证每仓库每天只提醒一次
- 仓库设置新增字段 wms_store.subject_config.receiving_pending_inbound_notice:
  enabled(是否通知收货未入库,flag,默认 0 关闭)/ notice_time(提醒时间 HH:mm,默认 08:30)/ min_hours(超时下限,默认 24)/ max_hours(超时上限,默认 48,须大于 min_hours)
  / notice_template(仓库客服群通知短语)/ store_notice_template(货主群通知短语)
- 通知短语可配置并支持变量替换:{warehouse} {warehouse_id} {store} {store_id} {count} {min_hours} {max_hours} {date} {numbers};
  未识别占位符原样保留,留空回退默认短语,最长 500 字符(超长 400)
- 消息结构统一为「短语 + 换行 + 明细(一行一条,最多 20 行,超出提示剩余单数)+ 快速查看/详情查看链接」,不再在结尾追加句号
- 新增通知事件 receiving_pending_inbound(notification_webhook 事件注册 + notice DEFAULT_REGISTERED_EVENT_CODES)与固定群订阅:
  store:receiving,fallbackTargets=warehouse:customer_service —— 有货主推货主收货群,无货主或货主未配收货群时推仓库客服群(出站仍走 notify.reply,落 wms_inbox_message)
- 文档:methods/system.json 的 setting.warehouse.getSettings/saveSettings 补充该配置字段(版本 0.3.129 -> 0.3.131),
  变更记录新增 2026.09.15-warehouse-pending-receiving-notice / -notice-template(system)、2026-09-15-warehouse-01 / -02(warehouse,事件注册与文案结构);
  AI_METHOD_ROUTING.md 同步刷新(新服务 14 个方法)
- 单测 test/app/service/systems/receiving_pending_notice.test.js(11 用例:开关关闭/未命中提醒时间不执行、超时窗口查询条件、货主群通知、无货主回退客服群、
  当日只提醒一次、推送失败不重复、扫描异常释放锁重试、行数截断、非法配置回退默认、短语变量替换与明细逐行、未识别占位符保留)全部通过;npx eslint 无告警

同时提交上一轮未提交的 camera/PTZ 改动(app/lib/ptz_client.js 新增、systems/camera.js 与 systemMethods/camera.js:PTZ 下发给打印服务时请求体统一携带 cameraId),
其文档与路由清单改动与本提交共用 methods/system.json 等文件,无法按行安全拆分,故合并为一次提交。
2026-09-15 23:49:34 +08:00

326 lines
11 KiB
JavaScript
Raw Permalink 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.

'use strict';
/**
* PTZ(云台控制)客户端模块。
* 负责组装 RTSP URL 并调用打印服务的云台端点下发控制指令。
* 与 `lib/osd_client.js` 同风格:独立端点 + 独立请求体,**不带 computerId**
* (打印服务按 rtspUrl 定位摄像头,无需房间路由)。
*
* 端点与请求体(warehouse_id 为字符串、cameraId 为摄像头ID,与 setOSD 口径一致):
* - /camera/ptzControl :按下(按方向持续转动),松手时必须配对调用 stop
* { warehouse_id, cameraId, rtspUrl, action, speed }
* - /camera/ptzStop :松手(停止转动),action 必须与按下时一致
* { warehouse_id, cameraId, rtspUrl, action }
* - /camera/ptzPresetGoto :跳转预置点,一次调用即可,无需 stop
* { warehouse_id, cameraId, rtspUrl, presetId }
* - /camera/ptzPresetSet :设置预置点(把当前机位存为指定编号),一次调用即可
* { warehouse_id, cameraId, rtspUrl, presetId }
*
* 使用方式:
* const PtzClient = require('../lib/ptz_client');
* const ptzClient = new PtzClient(ctx);
* await ptzClient.control({ camera, warehouseId, action, speed });
*/
/** 打印服务云台端点路径 */
const PTZ_PATH = {
CONTROL: '/camera/ptzControl',
STOP: '/camera/ptzStop',
PRESET_GOTO: '/camera/ptzPresetGoto',
PRESET_SET: '/camera/ptzPresetSet',
};
/** 云台方向枚举(与打印服务约定的 8 个位置,顺序固定) */
const PTZ_ACTION_LIST = [
{ value: 'up', name: '上' },
{ value: 'down', name: '下' },
{ value: 'left', name: '左' },
{ value: 'right', name: '右' },
{ value: 'upleft', name: '左上' },
{ value: 'upright', name: '右上' },
{ value: 'downleft', name: '左下' },
{ value: 'downright', name: '右下' },
];
/** 云台方向值列表 */
const PTZ_ACTIONS = PTZ_ACTION_LIST.map(item => item.value);
/** 默认转速 */
const PTZ_DEFAULT_SPEED = 4;
/** 转速下限 */
const PTZ_MIN_SPEED = 1;
/** 转速上限 */
const PTZ_MAX_SPEED = 7;
/** 预置点编号下限 */
const PTZ_MIN_PRESET_ID = 1;
/** 预置点编号上限 */
const PTZ_MAX_PRESET_ID = 256;
/** 打印服务请求超时(毫秒) */
const PTZ_REQUEST_TIMEOUT = 10000;
class PtzClient {
constructor(ctx) {
this.ctx = ctx;
this.logger = ctx.logger || console;
}
/**
* 云台方向枚举(供文档/校验共用)。
* @return {Array<Object>} [{ value, name }]
*/
static getActionList() {
return PTZ_ACTION_LIST.map(item => ({ ...item }));
}
/**
* 组装摄像头 RTSP 地址。
* 与 `lib/osd_client.js#buildRtspUrl` 保持同口径(打印服务以该地址定位摄像头)。
*
* @param {Object} camera - 摄像头记录(含 ip/username/password/channel_id)
* @return {string} RTSP URL
*/
buildRtspUrl(camera) {
const ip = camera && camera.ip;
if (!ip) {
throw new Error('摄像头未配置IP地址,无法组装RTSP地址');
}
const username = camera.username || 'admin';
const password = camera.password || '';
const channelId = camera.channel_id;
const rtspPort = 554;
return `rtsp://${username}:${password}@${ip}:${rtspPort}/stream${channelId}`;
}
/**
* 校验并归一化云台方向。
*
* @param {string} action - 云台方向
* @param {string} [label] - 报错文案中的字段名
* @return {string} 归一化后的方向值
*/
static normalizeAction(action, label = '云台方向') {
const value = String(action === undefined || action === null ? '' : action).trim().toLowerCase();
if (!value) throw new Error(`${label}不能为空`);
if (!PTZ_ACTIONS.includes(value)) {
throw new Error(`${label}不合法,仅支持:${PTZ_ACTIONS.join('/')}`);
}
return value;
}
/**
* 校验并归一化云台转速(缺省 4)。
*
* @param {number|string} speed - 转速
* @return {number} 归一化后的转速
*/
static normalizeSpeed(speed) {
if (speed === undefined || speed === null || speed === '') return PTZ_DEFAULT_SPEED;
const value = Number(speed);
if (!Number.isInteger(value) || value < PTZ_MIN_SPEED || value > PTZ_MAX_SPEED) {
throw new Error(`云台转速需为 ${PTZ_MIN_SPEED}-${PTZ_MAX_SPEED} 的整数`);
}
return value;
}
/**
* 校验并归一化预置点编号。
*
* @param {number|string} presetId - 预置点编号
* @return {number} 归一化后的预置点编号
*/
static normalizePresetId(presetId) {
if (presetId === undefined || presetId === null || presetId === '') {
throw new Error('预置点编号不能为空');
}
const value = Number(presetId);
if (!Number.isInteger(value) || value < PTZ_MIN_PRESET_ID || value > PTZ_MAX_PRESET_ID) {
throw new Error(`预置点编号需为 ${PTZ_MIN_PRESET_ID}-${PTZ_MAX_PRESET_ID} 的整数`);
}
return value;
}
/**
* 下发云台指令到打印服务(独立端点,与 setOSD 同风格,不带 computerId)。
* 请求体统一携带 warehouse_id(字符串)与 cameraId(摄像头ID)。
*
* @param {Object} options - 指令参数
* @param {Object} options.camera - 摄像头记录(取 id 作为 cameraId,并用于日志)
* @param {string} options.path - 打印服务端点路径
* @param {number} options.warehouseId - 仓库ID
* @param {Object} options.data - 请求体业务字段
* @return {Promise<Object>} { success, error, response, request }
*/
async _send(options = {}) {
const { ctx } = this;
const { camera, path: targetPath, warehouseId, data } = options;
if (!targetPath) throw new Error('打印服务端点路径不能为空');
if (!camera) throw new Error('摄像头信息不能为空');
const warehouseValue = Number(warehouseId);
if (!Number.isInteger(warehouseValue) || warehouseValue <= 0) {
throw new Error('仓库ID不合法');
}
const cameraValue = Number(camera.id);
if (!Number.isInteger(cameraValue) || cameraValue <= 0) {
throw new Error('摄像头ID不合法');
}
const printServiceUrl = ctx.app.config.printService.url;
const targetUrl = `${printServiceUrl}${targetPath}`;
const requestData = {
warehouse_id: String(warehouseValue),
cameraId: cameraValue,
...data,
};
ctx.logger.info('[PTZ] 发送云台指令', { url: targetUrl, body: requestData });
let response = null;
let error = null;
try {
const res = await ctx.curl(targetUrl, {
method: 'POST',
contentType: 'json',
data: requestData,
dataType: 'json',
timeout: PTZ_REQUEST_TIMEOUT,
});
response = {
status: res.status,
headers: res.headers,
data: res.data,
};
ctx.logger.info('[PTZ] 打印服务回信', { status: res.status, data: res.data });
} catch (err) {
error = err.message;
ctx.logger.warn('[PTZ] 打印服务请求失败', {
camera_id: camera && camera.id,
url: targetUrl,
error: err.message,
});
}
const httpOk = !!response && response.status >= 200 && response.status < 300;
const body = response && response.data;
if (!error && httpOk && body && typeof body === 'object'
&& (body.status === 'fail' || body.success === false)) {
error = body.message || body.error || '打印服务返回失败';
}
return {
success: !error && httpOk,
error,
response,
request: requestData,
};
}
/**
* 按下:按指定方向转动云台。
*
* @param {Object} options - 参数
* @param {Object} options.camera - 摄像头记录
* @param {number} options.warehouseId - 仓库ID
* @param {string} options.action - 云台方向(up/down/left/right/upleft/upright/downleft/downright)
* @param {number} [options.speed] - 转速(1-7,默认 4)
* @return {Promise<Object>} 打印服务响应
*/
async control(options = {}) {
const { camera, warehouseId, action, speed } = options;
if (!camera) throw new Error('摄像头信息不能为空');
return await this._send({
camera,
path: PTZ_PATH.CONTROL,
warehouseId,
data: {
rtspUrl: this.buildRtspUrl(camera),
action: PtzClient.normalizeAction(action),
speed: PtzClient.normalizeSpeed(speed),
},
});
}
/**
* 松手:停止云台转动。
*
* @param {Object} options - 参数
* @param {Object} options.camera - 摄像头记录
* @param {number} options.warehouseId - 仓库ID
* @param {string} options.action - 云台方向(必须与按下时一致)
* @return {Promise<Object>} 打印服务响应
*/
async stop(options = {}) {
const { camera, warehouseId, action } = options;
if (!camera) throw new Error('摄像头信息不能为空');
return await this._send({
camera,
path: PTZ_PATH.STOP,
warehouseId,
data: {
rtspUrl: this.buildRtspUrl(camera),
action: PtzClient.normalizeAction(action),
},
});
}
/**
* 跳转预置点(一次调用即可,无需 stop)。
*
* @param {Object} options - 参数
* @param {Object} options.camera - 摄像头记录
* @param {number} options.warehouseId - 仓库ID
* @param {number|string} options.presetId - 预置点编号(1-256)
* @return {Promise<Object>} 打印服务响应
*/
async presetGoto(options = {}) {
const { camera, warehouseId, presetId } = options;
if (!camera) throw new Error('摄像头信息不能为空');
return await this._send({
camera,
path: PTZ_PATH.PRESET_GOTO,
warehouseId,
data: {
rtspUrl: this.buildRtspUrl(camera),
presetId: PtzClient.normalizePresetId(presetId),
},
});
}
/**
* 设置预置点:把摄像头当前机位保存为指定预置点编号(一次调用即可)。
*
* @param {Object} options - 参数
* @param {Object} options.camera - 摄像头记录
* @param {number} options.warehouseId - 仓库ID
* @param {number|string} options.presetId - 预置点编号(1-256)
* @return {Promise<Object>} 打印服务响应
*/
async presetSet(options = {}) {
const { camera, warehouseId, presetId } = options;
if (!camera) throw new Error('摄像头信息不能为空');
return await this._send({
camera,
path: PTZ_PATH.PRESET_SET,
warehouseId,
data: {
rtspUrl: this.buildRtspUrl(camera),
presetId: PtzClient.normalizePresetId(presetId),
},
});
}
}
module.exports = PtzClient;
module.exports.PTZ_PATH = PTZ_PATH;
module.exports.PTZ_ACTIONS = PTZ_ACTIONS;
module.exports.PTZ_DEFAULT_SPEED = PTZ_DEFAULT_SPEED;
module.exports.PTZ_MAX_SPEED = PTZ_MAX_SPEED;
module.exports.PTZ_MAX_PRESET_ID = PTZ_MAX_PRESET_ID;