'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} [{ 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} { 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} 打印服务响应 */ 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} 打印服务响应 */ 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} 打印服务响应 */ 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} 打印服务响应 */ 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;