Compare commits

...

4 Commits

Author SHA1 Message Date
liufumingren
8a56d80de0 1 2026-09-15 18:56:34 +08:00
liufumingren
afda527deb fix: 录像回写统一UTC时间基准并按仓库校验,失败/缺失行均落库
- 原视频表写入时间由 NOW() 改为 UTC_TIMESTAMP()(WMS Sequelize 默认 +00:00,服务器为 CST+8)

- 回信先取任务行做仓库归属校验,跨仓或不存在的任务直接拒绝写入

- receiveTask 回 ok=false 时落 status=failed,避免录像行卡在 created

- 新增 _findVideoRow:camera_id 未命中且任务仅单行时退化为按任务ID定位(多路不猜)

- 新增 _insertVideoResult:录像行缺失时兜底插入结果行,保证 WMS 能收敛状态
2026-09-11 02:22:26 +08:00
liufumingren
9d07a3e24e feat: 强制录制下发字段增加 weight=1 标记 2026-09-10 23:03:57 +08:00
liufumingren
b9078d75b0 docs: 完善 forceRecord 拆包入参说明(unpack_id 自动识别) 2026-08-25 00:39:17 +08:00
3 changed files with 399 additions and 31 deletions

View File

@ -2,8 +2,11 @@ const { Controller } = require('egg');
class HikvisionController extends Controller {
/**
* POST /hikvision/forceRecord
* 强制推送录制任务(支持打包 pack_task_id / 拆包 unpack_id+task_type),事务重置录像行并推送
* POST /hikvision/forceRecord (或 /record/force)
* 强制推送录制任务,事务重置录像行并推送
* 入参(二选一,与打包/拆包任务对应):
* - 打包任务: { pack_task_id: 123 }
* - 拆包任务: { unpack_id: 456 } (task_type: 'unpack' 可选,服务端按入参自动识别)
*/
async forceRecord() {
const { ctx } = this;

View File

@ -69,6 +69,81 @@ class HikvisionService extends BaseService {
};
}
/**
* 校验回信电脑与任务是否同仓库(防跨仓误写)
* print_computer_info 缺失(客户端未走 auth.getInfo)时只告警不阻断
* @param {Object} task 任务行(需含 warehouse_id)
* @param {string} method 调用方方法名(日志用)
* @returns {{ok: boolean, message?: string}}
*/
_checkTaskWarehouse(task, method) {
const { print_computer_info: info } = this.ctx;
const taskWarehouse = task && task.warehouse_id;
if (!info || !info.warehouse) {
console.warn(`[Hikvision] ${method} 缺少电脑绑定信息,跳过仓库校验: task=${task && task.id}, taskWarehouse=${taskWarehouse}`);
return { ok: true };
}
if (String(info.warehouse) !== String(taskWarehouse)) {
console.warn(`[Hikvision] ${method} 仓库不匹配,拒绝写入: 电脑仓库=${info.warehouse}, 任务仓库=${taskWarehouse}, task=${task.id}`);
return { ok: false, message: '任务与当前电脑仓库不匹配' };
}
return { ok: true };
}
/**
* 定位录像行:先按 任务ID + 摄像头ID 精准定位(避免多摄像头/forceRecord 并发错位);
* 精准定位不到时,仅当该任务只有一行录像行才退化为按任务ID定位(多路场景不猜)
* @returns {Promise<Object|null>} 录像行,定位不到返回 null
*/
async _findVideoRow(videoTable, fkColumn, taskIdNum, cameraIdNum) {
const { app } = this;
const mysql = app.mysql.get('wms');
const cond = { [fkColumn]: taskIdNum, deleted_at: null };
if (!isNaN(cameraIdNum)) cond.camera_id = cameraIdNum;
const [row] = await mysql.select(videoTable, {
where: cond,
orders: [ [ 'id', 'desc' ] ],
limit: 1,
});
if (row) return row;
const rows = await mysql.select(videoTable, {
where: { [fkColumn]: taskIdNum, deleted_at: null },
orders: [ [ 'id', 'desc' ] ],
limit: 2,
});
if (!rows || rows.length === 0) return null;
if (rows.length > 1) {
console.warn(`[Hikvision] 录像行定位失败且该任务存在多路录像行,跳过更新: ${fkColumn}=${taskIdNum}, camera=${cameraIdNum}`);
return null;
}
console.warn(`[Hikvision] 录像行按 camera_id 未命中,退化为按任务ID更新: ${fkColumn}=${taskIdNum}, camera=${cameraIdNum}, videoId=${rows[0].id}`);
return rows[0];
}
/**
* 兜底落结果行:录像行缺失时直接插入一行结果,
* 保证 WMS 能按原视频表(status / video_url)收敛补录请求状态
*/
async _insertVideoResult(videoTable, fkColumn, taskIdNum, cameraIdNum, { status, videoUrl = '', remark = null }) {
const { app } = this;
const cols = [ fkColumn ];
const params = [ taskIdNum ];
if (!isNaN(cameraIdNum)) {
cols.push('camera_id');
params.push(cameraIdNum);
}
cols.push('video_url', 'status', 'remark');
params.push(videoUrl, status, remark);
await app.mysql.get('wms').query(
`INSERT INTO ${videoTable} (${cols.join(', ')}, created_at, updated_at)
VALUES (${cols.map(() => '?').join(', ')}, UTC_TIMESTAMP(), UTC_TIMESTAMP())`,
params
);
}
/**
* 组装录像任务落参,并用原子 INSERT 创建录像占位记录(防止并发重复)
* 注:不使用显式事务(egg-mysql 5 + mysql2 3.23 的事务 conn.query 存在挂起 bug),
@ -112,9 +187,10 @@ class HikvisionService extends BaseService {
if (!matchedServer) continue;
// 原子插入防重:仅当该任务+摄像头没有未删除录像行时插入
// 时间统一 UTC_TIMESTAMP():WMS 侧 Sequelize 未配 timezone(默认 +00:00),库内时间为 UTC
await app.mysql.get('wms').query(
`INSERT INTO ${cfg.videoTable} (${cfg.fkColumn}, camera_id, video_url, status, created_at, updated_at)
SELECT ?, ?, '', 'created', NOW(), NOW()
SELECT ?, ?, '', 'created', UTC_TIMESTAMP(), UTC_TIMESTAMP()
FROM DUAL
WHERE NOT EXISTS (
SELECT 1 FROM ${cfg.videoTable}
@ -269,31 +345,39 @@ class HikvisionService extends BaseService {
const videoTable = isUnpack ? 'wms_return_unpack_video' : 'wms_pack_task_video';
const fkColumn = isUnpack ? 'unpack_id' : 'pack_task_id';
const cfg = this._getTaskCfg(isUnpack ? 'unpack' : 'pack');
// 取任务行:仓库归属校验 + 录像行缺失时兜底落库用
const task = await app.mysql.get('wms').get(cfg.taskTable, { id: taskIdNum });
if (!task) {
return this.errorResponse('hikvision.receiveTask', `任务不存在: ${cfg.taskTable}#${taskIdNum}`);
}
const whCheck = this._checkTaskWarehouse(task, 'hikvision.receiveTask');
if (!whCheck.ok) {
return this.errorResponse('hikvision.receiveTask', whCheck.message);
}
if (ok) {
// 任务接收成功 → 定位该摄像头录像行,状态改为 recording
const whereCond = { [fkColumn]: taskIdNum, deleted_at: null };
if (!isNaN(cameraIdNum)) whereCond.camera_id = cameraIdNum;
const existingVideo = await app.mysql.get('wms').get(videoTable, whereCond);
const existingVideo = await this._findVideoRow(videoTable, fkColumn, taskIdNum, cameraIdNum);
if (!existingVideo) {
if (!isNaN(cameraIdNum)) {
await app.mysql.get('wms').query(
`INSERT INTO ${videoTable} (${fkColumn}, camera_id, video_url, status, remark, created_at, updated_at)
VALUES (?, ?, '', 'recording', ?, NOW(), NOW())`,
VALUES (?, ?, '', 'recording', ?, UTC_TIMESTAMP(), UTC_TIMESTAMP())`,
[taskIdNum, cameraIdNum, message || '任务已接收']
);
} else {
await app.mysql.get('wms').query(
`INSERT INTO ${videoTable} (${fkColumn}, video_url, status, remark, created_at, updated_at)
VALUES (?, '', 'recording', ?, NOW(), NOW())`,
VALUES (?, '', 'recording', ?, UTC_TIMESTAMP(), UTC_TIMESTAMP())`,
[taskIdNum, message || '任务已接收']
);
}
} else if (existingVideo.status === 'created') {
await app.mysql.get('wms').query(
`UPDATE ${videoTable} SET status = 'recording', remark = ?, updated_at = NOW() WHERE id = ?`,
`UPDATE ${videoTable} SET status = 'recording', remark = ?, updated_at = UTC_TIMESTAMP() WHERE id = ?`,
[message || '任务已接收', existingVideo.id]
);
}
@ -301,8 +385,21 @@ class HikvisionService extends BaseService {
console.log(`[Hikvision] 录像开始: ${fkColumn}=${taskIdNum}, taskId=${taskId}`);
return this.successResponse('hikvision.receiveTask', { [fkColumn]: taskIdNum, status: 'recording' }, '录像已开始');
} else {
// 任务接收失败
console.log(`[Hikvision] 任务接收失败: ${fkColumn}=${taskIdNum}, message=${message}`);
// 任务接收失败(录制电脑拒绝/摄像头连不上)→ 落 failed,
// 否则该行停在 created,WMS 既非“录制中”也非“全部失败”,只能等 1 小时超时转人工
const failedRow = await this._findVideoRow(videoTable, fkColumn, taskIdNum, cameraIdNum);
if (failedRow) {
await app.mysql.get('wms').query(
`UPDATE ${videoTable} SET status = 'failed', remark = ?, updated_at = UTC_TIMESTAMP() WHERE id = ?`,
[message || '任务接收失败', failedRow.id]
);
} else {
await this._insertVideoResult(videoTable, fkColumn, taskIdNum, cameraIdNum, {
status: 'failed',
remark: message || '任务接收失败',
});
}
console.log(`[Hikvision] 任务接收失败(已落 failed): ${fkColumn}=${taskIdNum}, message=${message}`);
return this.errorResponse('hikvision.receiveTask', message || '任务接收失败');
}
} catch (error) {
@ -315,6 +412,8 @@ class HikvisionService extends BaseService {
* 客户端回调:录像任务完成
* 成功 → 写入 video_url,状态 completed
* 失败 → 写入 remark,状态 failed
* 注:按对接口径,通知方只写原视频表;wms_video_record_request 由 WMS 全权维护,
* WMS 定时任务(settleStatuses)会据此收敛补录请求状态并回信
*/
async taskComplete(data) {
const { app } = this;
@ -343,41 +442,54 @@ class HikvisionService extends BaseService {
const videoTable = isUnpack ? 'wms_return_unpack_video' : 'wms_pack_task_video';
const fkColumn = isUnpack ? 'unpack_id' : 'pack_task_id';
const cfg = this._getTaskCfg(isUnpack ? 'unpack' : 'pack');
// 按任务ID+摄像头ID精确定位录像行,避免多摄像头/forceRecord 并发错位
const whereCond = { [fkColumn]: taskIdNum, deleted_at: null };
if (!isNaN(cameraIdNum)) whereCond.camera_id = cameraIdNum;
// 取任务行:仓库归属校验(防跨仓误写)+ 录像行缺失时兜底落库用
const task = await app.mysql.get('wms').get(cfg.taskTable, { id: taskIdNum });
if (!task) {
return this.errorResponse('hikvision.taskComplete', `任务不存在: ${cfg.taskTable}#${taskIdNum}`);
}
const whCheck = this._checkTaskWarehouse(task, 'hikvision.taskComplete');
if (!whCheck.ok) {
return this.errorResponse('hikvision.taskComplete', whCheck.message);
}
if (success && status === 'completed') {
// 取该摄像头最新的录像记录 ID 精准更新
const [latestVideo] = await app.mysql.get('wms').select(videoTable, {
where: whereCond,
orders: [['id', 'desc']],
limit: 1,
});
// 定位该摄像头录像行(带单路退化兜底)
const latestVideo = await this._findVideoRow(videoTable, fkColumn, taskIdNum, cameraIdNum);
const remarkText = `大小:${(size / 1024 / 1024).toFixed(2)}MB, 时长:${duration}s, 倍速:${speed}x`;
if (latestVideo) {
const remarkText = `大小:${(size / 1024 / 1024).toFixed(2)}MB, 时长:${duration}s, 倍速:${speed}x`;
await app.mysql.get('wms').query(
`UPDATE ${videoTable} SET video_url = ?, status = 'completed', remark = ?, updated_at = NOW() WHERE id = ?`,
`UPDATE ${videoTable} SET video_url = ?, status = 'completed', remark = ?, updated_at = UTC_TIMESTAMP() WHERE id = ?`,
[fileUrl || output || '', remarkText, latestVideo.id]
);
} else {
// 录像行缺失(如未落库/被删)→ 直接落一行结果,保证 WMS 能收敛状态
await this._insertVideoResult(videoTable, fkColumn, taskIdNum, cameraIdNum, {
status: 'completed',
videoUrl: fileUrl || output || '',
remark: remarkText,
});
console.warn(`[Hikvision] 录像行缺失,已兜底插入 completed 行: ${fkColumn}=${taskIdNum}, camera=${cameraIdNum}`);
}
console.log(`[Hikvision] 录像完成: ${fkColumn}=${taskIdNum}, url=${fileUrl}, size=${size}`);
return this.successResponse('hikvision.taskComplete',
{ [fkColumn]: taskIdNum, status: 'completed' }, '录像完成');
} else {
// 录像失败 - 同样按摄像头精准更新最新记录
const [latestVideo] = await app.mysql.get('wms').select(videoTable, {
where: whereCond,
orders: [['id', 'desc']],
limit: 1,
});
// 录像失败 - 同样按摄像头精准定位最新记录
const latestVideo = await this._findVideoRow(videoTable, fkColumn, taskIdNum, cameraIdNum);
if (latestVideo) {
await app.mysql.get('wms').query(
`UPDATE ${videoTable} SET status = 'failed', remark = ?, updated_at = NOW() WHERE id = ?`,
`UPDATE ${videoTable} SET status = 'failed', remark = ?, updated_at = UTC_TIMESTAMP() WHERE id = ?`,
[errorMsg || '录像失败', latestVideo.id]
);
} else {
await this._insertVideoResult(videoTable, fkColumn, taskIdNum, cameraIdNum, {
status: 'failed',
remark: errorMsg || '录像失败',
});
console.warn(`[Hikvision] 录像行缺失,已兜底插入 failed 行: ${fkColumn}=${taskIdNum}, camera=${cameraIdNum}`);
}
console.log(`[Hikvision] 录像失败: ${fkColumn}=${taskIdNum}, error=${errorMsg}`);
@ -394,6 +506,7 @@ class HikvisionService extends BaseService {
* 强制录制:外部 HTTP 调用,按任务ID强制推送录制任务
* 支持打包(pack_task_id)与拆包(unpack_id + task_type='unpack')
* 事务内重置已有录像行,推送成功后提交
* 下发的 payload 额外带 weight=1 作为强制录制标记
*/
async forceRecord(data) {
const { app } = this;
@ -478,7 +591,7 @@ class HikvisionService extends BaseService {
await app.mysql.get('wms').query(
`INSERT INTO ${cfg.videoTable} (${cfg.fkColumn}, camera_id, video_url, status, created_at, updated_at)
VALUES (?, ?, '', 'created', NOW(), NOW())`,
VALUES (?, ?, '', 'created', UTC_TIMESTAMP(), UTC_TIMESTAMP())`,
[task.id, matchedCamera.id]
);
pushedItems.push({ cameraId, matchedCamera, matchedServer });
@ -490,6 +603,7 @@ class HikvisionService extends BaseService {
const payload = {
...cfg.buildFields(task, cameraId),
uniqueCode: `${cfg.codePrefix}${task.id}_${cameraId}`,
weight: 1, // 强制录制标记:下发 weight=1 供录制端识别
start_time: this._toISO(task.start_time, -5000),
end_time: this._toISO(task.end_time, cfg.endOffsetMs || 0),
operator: task.operator_text,

251
云台对接说明.md Normal file
View File

@ -0,0 +1,251 @@
# 云台(PTZ)通讯对接说明
> 适用版本:`services.printer`(服务端中转)+ `printServer`(打印/录制电脑客户端)
> 最后更新:2026-09-15
> 定位:**service.printer 只是中转**,外部(WMS)传入什么就原样推给客户端,不校验执行结果、不做回执、不记状态。
---
## 一、整体链路
```
WMS 主服务
│ ①HTTP POST /sendToRoom { warehouse, computerId, method, data }
▼
services.printer :4052 ← 本仓库,仅做中转,零改动
│ ②查 Redis 路由表 warehouse:{warehouse}:printer:{computerId}
│ ③WS sendTo(uniqueId, { method, data }) 原样透传
▼
printServer(仓库录制电脑)
│ ④按 method 点分路由 → services/camera.ptz.*
▼
摄像头 / NVR(仓库内网,ISAPI)
```
**关键语义**:HTTP 返回 `status: success` 只代表「消息已写进 WS 房间」,**不代表云台动了**。执行结果只落客户端本地日志,不回传。
---
## 二、WMS → services.printer(HTTP)
复用已有端点(`app/router.js` → `app/controller/home.js#sendToRoom`),**无需新增路由**:
```
POST http://{services.printer 地址}:4052/sendToRoom
Content-Type: application/json
```
```jsonc
{
"warehouse": 9, // 必填,仓库 ID
"computerId": 12, // 必填,打印电脑 ID(须为录制电脑)
"method": "camera.ptz.control", // 必填,见第三节
"data": { // 必填,且必须是非空对象
"rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601",
"action": "left",
"speed": 4
}
}
```
### 返回
| 返回 | 含义 |
|---|---|
| `{ status:'success', message:'消息发送成功', result: 1 }` | 已推送到该电脑的 WS 房间(`result` = 命中房间数) |
| `{ status:'fail', message:'缺少必要参数: warehouse, computerId, method, 或 data' }` | 入参不全 |
| `{ status:'fail', message:'未找到打印机信息,无法发送消息' }` | 该电脑不在线(Redis 无记录,TTL 300s) |
| `{ status:'fail', message:'打印电脑不在线,消息发送失败...' }` | `sendTo` 未命中房间 |
> 目标电脑怎么定:`wms_print_computer` 里 `warehouse_id = warehouse AND is_recording = 1` 的那台。WMS 侧本来就能查这张表,直接带上 `computerId` 即可。
---
## 三、services.printer → 客户端(WS 下发契约)
服务端把 `method` / `data` **原样** 透传,所以下表就是客户端必须实现的入口。
| method | 用途 | 是否持续型 |
|---|---|---|
| `camera.ptz.control` | 开始运动(方向 / 变倍 / 聚焦 / 光圈) | ✅ 必须另发 stop |
| `camera.ptz.stop` | 停止运动 | — |
| `camera.ptz.presetGoto` | 调用预置点 | ❌ 一次性 |
| `camera.ptz.presetSet` | 设置(保存)预置点 | ❌ 一次性 |
| `camera.ptz.auto` | 自动巡航(autoPan)开关 | ❌ 开关型 |
### data 字段
| 字段 | control | stop | presetGoto | presetSet | auto | 说明 |
|---|:--:|:--:|:--:|:--:|:--:|---|
| `rtspUrl` | ✔ | ✔ | ✔ | ✔ | ✔ | 设备 RTSP 地址;客户端从中解析 **账号 / 密码 / 主机 / 通道号** |
| `action` | ✔ | ✔ | — | — | — | 动作名或 SDK 索引,见下表。**stop 必须与 start 同一个 action** |
| `speed` | ○ | — | — | — | — | 1~7,默认 4 |
| `presetId` | — | — | ✔ | ✔ | — | 预置点编号(1~256) |
| `presetName` | — | — | — | ○ | — | 预置点名称,默认 `Preset{id}` |
| `on` | — | — | — | — | ✔ | `true` 开启 / `false` 关闭 |
| `channel` | ○ | ○ | ○ | ○ | ○ | 手动覆盖通道号(默认从 rtspUrl 解析) |
| `port` | ○ | ○ | ○ | ○ | ○ | 设备 ISAPI 端口,默认 **80** |
### action 取值
| action | 同义写法 | SDK 索引 | 效果 |
|---|---|:--:|---|
| `up` | — | 1 | 上 |
| `down` | — | 2 | 下 |
| `left` | — | 3 | 左 |
| `right` | — | 4 | 右 |
| `upLeft` | `up_left` | 5 | 左上 |
| `downLeft` | `down_left` | 6 | 左下 |
| `upRight` | `up_right` | 7 | 右上 |
| `downRight` | `down_right` | 8 | 右下 |
| `zoomIn` | `zoom_in` | 10 | 变倍 + |
| `zoomOut` | `zoom_out` | 11 | 变倍 − |
| `focusIn` | `focus_in` / `focusFar` | 12 | 聚焦 + |
| `focusOut` | `focus_out` / `focusNear` | 13 | 聚焦 − |
| `irisIn` | `iris_in` | 14 | 光圈 + |
| `irisOut` | `iris_out` | 15 | 光圈 − |
> 索引 9(自动巡航)不在 `control` 里支持,请用 `camera.ptz.auto`。
### 通道号来源
客户端从 `rtspUrl` 路径解析,规则:
| rtspUrl 路径 | 通道号 |
|---|---|
| `/Streaming/Channels/101` | 1 |
| `/Streaming/Channels/601` | 6(末两位是码流号) |
| `/Streaming/Channels/1201` | 12 |
| `/stream2` | 2 |
解析不准时用 `channel` 显式覆盖。
---
## 四、客户端侧实现(已完成)
`printServer` 仓库改动清单:
| 文件 | 改动 |
|---|---|
| `utils/cameraPtz.js` | **新增**。ISAPI 云台控制,含认证握手、路径回退、路径缓存、文件日志 |
| `utils/cameraOsd.js` | 3 处 `export`(`extractRTSPInfo` / `_isapiAuth` / `_isapiRequest`)+ `_isapiRequest`、`_isapiAuth` 各加可选 `port`(默认 80,行为不变) |
| `services/camera.js` | 新增 `this.ptz = { control, stop, presetGoto, presetSet, auto }`,与已有 `this.osd` 平级 |
### ⚠️ 两条硬约束
1. **这些方法一律不能有返回值。**
`core/wsClient.js` 只要拿到非 `undefined` 的返回值,就会回发 `{success:true, method, result}` 给服务端;而服务端 `app/controller/print.js` 会把这条回显**当成一次服务调用**去路由,`services.printer` 里没有 `camera.*` 服务 → 刷一堆 `服务路径 camera 不存在` 的错误。
客户端日志里若出现该报错,说明有人给这些方法加了 `return`。
2. **持续型动作必须由 WMS 补发 stop。**
ISAPI `/continuous` 是「一次 PUT 后设备持续运动」。客户端**不做自动停止**,WMS 侧必须在鼠标抬起 / 移出画面 / 窗口失焦 / 关闭时下发 `camera.ptz.stop`(同一个 `action`)。
### 日志
| 日志 | 位置 |
|---|---|
| 云台 | `%ProgramData%\printServer\cameraPtz.log`(同时输出到控制台,前缀 `[CameraPTZ]`) |
| OSD | `%ProgramData%\printServer\cameraOsd.log` |
---
## 五、动作 ↔ ISAPI 映射(客户端内部实现)
路径与报文对齐海康官方无插件 SDK(`webVideoCtrl.js`)。每种动作按候选顺序尝试,成功后缓存该设备可用的那一条。
| 动作 | 首选路径 | 回退路径 |
|---|---|---|
| 方向 / 变倍 | `/ISAPI/PTZCtrl/channels/{ch}/continuous` | `/ISAPI/ContentMgmt/PTZCtrlProxy/channels/{ch}/continuous` |
| 聚焦 | `/ISAPI/Image/channels/{ch}/focus` | `/ISAPI/ContentMgmt/ImageProxy/channels/{ch}/focus` → `/ISAPI/System/Video/inputs/channels/{ch}/focus` |
| 光圈 | `/ISAPI/Image/channels/{ch}/iris` | `/ISAPI/ContentMgmt/ImageProxy/channels/{ch}/iris` → `/ISAPI/System/Video/inputs/channels/{ch}/iris` |
| 预置点调用 | `/ISAPI/PTZCtrl/channels/{ch}/presets/{id}/goto` | `/ISAPI/ContentMgmt/PTZCtrlProxy/channels/{ch}/presets/{id}/goto` |
| 预置点设置 | `/ISAPI/PTZCtrl/channels/{ch}/presets/{id}` | `/ISAPI/ContentMgmt/PTZCtrlProxy/channels/{ch}/presets/{id}` |
| 自动巡航 | `/ISAPI/PTZCtrl/channels/{ch}/autoPan` | `/ISAPI/ContentMgmt/PTZCtrlProxy/channels/{ch}/autoPan` |
全部为 `PUT`;认证自适应 Basic / Digest(401 自动重新握手一次)。
### 报文与取值
**速度换算**(与 SDK 一致):`speed < 7 → 15 × speed`,`speed ≥ 7 → 100`;默认 `speed = 4` → `60`。**停止 = 0**。
```xml
<!-- 方向:action=left, speed=4 -->
<PTZData><pan>-60</pan><tilt>0</tilt></PTZData>
<!-- 方向停止:action=left -->
<PTZData><pan>0</pan><tilt>0</tilt></PTZData>
<!-- 变倍:action=zoomIn, speed=2 -->
<PTZData><zoom>30</zoom></PTZData>
<!-- 聚焦:action=focusOut(speed=4) -->
<FocusData><focus>-60</focus></FocusData>
<!-- 光圈:action=irisIn(speed=4) -->
<IrisData><iris>60</iris></IrisData>
<!-- 预置点设置:presetId=3, presetName=A点 -->
<PTZPreset><id>3</id><presetName>A点</presetName></PTZPreset>
<!-- 自动巡航 -->
<autoPanData><autoPan>100</autoPan></autoPanData> <!-- 开;关为 0 -->
```
**方向符号**:`pan` 正 = 右、`tilt` 正 = 上。若实机方向相反,改 `utils/cameraPtz.js` 顶部:
```js
const SIGNS = { pan: 1, tilt: 1, zoom: 1, focus: 1, iris: 1 };
```
> 预置点调用按 SDK 行为**不带请求体**。
---
## 六、WMS 需要发的完整调用序列
```jsonc
// 1) 按下:向左转
POST /sendToRoom
{ "warehouse": 9, "computerId": 12, "method": "camera.ptz.control",
"data": { "rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601",
"action": "left", "speed": 4 } }
// 2) 松手:停止(action 必须与上面一致)
POST /sendToRoom
{ "warehouse": 9, "computerId": 12, "method": "camera.ptz.stop",
"data": { "rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601",
"action": "left" } }
// 3) 转到预置点(一次即可,不用 stop)
POST /sendToRoom
{ "warehouse": 9, "computerId": 12, "method": "camera.ptz.presetGoto",
"data": { "rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601",
"presetId": 3 } }
```
---
## 七、排查手册
| 现象 | 原因 / 处理 |
|---|---|
| 云台完全不动,服务端返回 success | 客户端 method 路由未命中。看客户端日志 `[WSClient] 方法路由: camera.ptz.control MISSING` → 客户端版本过旧,未包含 `services/camera.js` 的 `ptz` |
| 客户端日志 `ISAPI 认证失败` | 设备账号密码不对(来自 `rtspUrl`)或设备不是海康系 |
| `全部候选接口失败(最后 HTTP 400/404)` | 路径不匹配:NVR 的 IP 通道、非 80 端口(用 `port`)、或非海康设备 |
| 云台转向相反 | 调 `utils/cameraPtz.js` 的 `SIGNS` |
| 云台一直转不停 | WMS 没发 `camera.ptz.stop`(或 `action` 与开始不一致) |
| 动了但控制错了通道 | 用 `channel` 显式指定通道号 |
| 服务端出现 `服务路径 camera 不存在` | 客户端给这些方法加了返回值,触发了回显 → 去掉 `return` |
---
## 八、已知限制(按当前口径接受)
1. **无回执、无状态**:设备写失败、超时,WMS 一律看不到,只能靠客户端本地日志排查。
2. **无自动停止**:WMS 侧异常 / 断网 / 忘了发 stop,云台会持续转动。
3. **无幂等/防重**:重复下发即重复执行;预置点类幂等,方向类会叠加。
4. **可攻击面**:`POST /sendToRoom`、`/camera/setOSD`、`/record/force` 均**未挂鉴权中间件**,端口可达即可调用(`app/middleware/jwtAuth.js` 已存在但未启用)。
5. ISAPI 端口默认 80,非 80 设备需显式传 `port`。
---
## 九、变更记录
| 日期 | 内容 |
|---|---|
| 2026-09-15 | 云台链路定稿:WMS 下发 start/stop,服务端只中转,无回执;客户端新增 `utils/cameraPtz.js` + `services/camera.js#ptz` |