diff --git a/云台对接说明.md b/云台对接说明.md
new file mode 100644
index 0000000..1af7593
--- /dev/null
+++ b/云台对接说明.md
@@ -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
+
+-600
+
+00
+
+30
+
+-60
+
+60
+
+3A点
+
+100
+```
+
+**方向符号**:`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` |