朱园亮 / xingyun-erp · Commits

Commit c505683bbbf18c5b5f06f269b52cc62973b905de

Authored by 房远帅
1 parent 375ec3ee

采购：业务员报价看板-同行报价信息

Inline Side-by-side
Showing 2 changed files with 0 additions and 636 deletions
1 -# 同行报价信息 WebSocket 联调说明  
2 -  
3 -## 1. 功能说明  
4 -  
5 -本功能用于支撑业务员报价实时看板，采用 WebSocket 协议向前端实时推送“当日同行报价信息全量数据”。  
6 -  
7 -注意：  
8 -  
9 -- 本功能为独立新增能力，不影响原有查询接口  
10 -- 服务端仅推送“当日产生”的同行报价信息  
11 -- 新增、修改成功并事务提交后，会向所有在线客户端广播最新当日全量数据  
12 -- 前端断线重连后，可主动发起补推请求  
13 -  
14 -## 2. WebSocket 地址  
15 -  
16 -服务端路径：  
17 -  
18 -```text  
19 -/ws/procurement/salesmanQuotationPeer/realtime  
20 -```  
21 -  
22 -联调示例：  
23 -  
24 -```text  
25 -ws://localhost:8080/ws/procurement/salesmanQuotationPeer/realtime  
26 -```  
27 -  
28 -请将 `localhost:8080` 替换为实际后端服务地址。  
29 -  
30 -  
31 -## 4. 服务端推送规则  
32 -  
33 -### 4.1 建连后初始化推送  
34 -  
35 -客户端连接成功后，服务端会立即回推一份“当日完整数据”：  
36 -  
37 -- `eventType = INIT`  
38 -- `messageType = FULL_SYNC`  
39 -  
40 -### 4.2 新增后广播  
41 -  
42 -当日同行报价基础数据新增成功并事务提交后：  
43 -  
44 -- 向所有在线客户端广播  
45 -- `eventType = CREATE`  
46 -- `messageType = FULL_SYNC`  
47 -  
48 -### 4.3 修改后广播  
49 -  
50 -当日同行报价基础数据修改成功并事务提交后：  
51 -  
52 -- 向所有在线客户端广播  
53 -- `eventType = UPDATE`  
54 -- `messageType = FULL_SYNC`  
55 -  
56 -### 4.4 断线重连补推  
57 -  
58 -客户端重连成功后，可主动发送以下文本消息之一：  
59 -  
60 -- `SYNC_TODAY`  
61 -- `RESYNC`  
62 -  
63 -服务端收到后，会重新回推“当日完整数据”：  
64 -  
65 -- `eventType = RESYNC`  
66 -- `messageType = FULL_SYNC`  
67 -  
68 -## 5. 消息结构  
69 -  
70 -### 5.1 服务端返回消息体  
71 -  
72 -```json  
73 -{  
74 - "messageType": "FULL_SYNC",  
75 - "eventType": "INIT",  
76 - "businessDate": "2026-07-10",  
77 - "pushTime": "2026-07-10T16:30:00",  
78 - "records": [  
79 - {  
80 - "id": "1900000000000000001",  
81 - "peerName": "某同行",  
82 - "peerProductId": "1900000000000000002",  
83 - "peerProductName": "紫铜",  
84 - "peerProductCode": "ZT001",  
85 - "peerPrice": 76800.50,  
86 - "remark": "测试数据",  
87 - "createById": "1001",  
88 - "createBy": "张三",  
89 - "updateById": "1001",  
90 - "updateBy": "张三",  
91 - "createTime": "2026-07-10T16:28:10",  
92 - "updateTime": "2026-07-10T16:29:45"  
93 - }  
94 - ]  
95 -}  
96 -```  
97 -  
98 -### 5.2 字段说明  
99 -  
100 -| 字段 | 类型 | 说明 |  
101 -| --- | --- | --- |  
102 -| `messageType` | `String` | 当前固定为 `FULL_SYNC`，表示推送的是当日全量数据 |  
103 -| `eventType` | `String` | 事件类型，可能为 `INIT`、`CREATE`、`UPDATE`、`RESYNC` |  
104 -| `businessDate` | `LocalDate` | 当前业务日期 |  
105 -| `pushTime` | `LocalDateTime` | 本次推送时间 |  
106 -| `records` | `Array` | 当日同行报价信息列表 |  
107 -  
108 -`records` 中主要字段如下：  
109 -  
110 -| 字段 | 类型 | 说明 |  
111 -| --- | --- | --- |  
112 -| `id` | `String` | 主键 ID |  
113 -| `peerName` | `String` | 同行名称 |  
114 -| `peerProductId` | `String` | 同行品种 ID |  
115 -| `peerProductName` | `String` | 同行品种名称 |  
116 -| `peerProductCode` | `String` | 同行品种代号 |  
117 -| `peerPrice` | `BigDecimal` | 同行报价 |  
118 -| `remark` | `String` | 备注 |  
119 -| `createById` | `String` | 创建人 ID |  
120 -| `createBy` | `String` | 创建人 |  
121 -| `updateById` | `String` | 更新人 ID |  
122 -| `updateBy` | `String` | 更新人 |  
123 -| `createTime` | `LocalDateTime` | 创建时间 |  
124 -| `updateTime` | `LocalDateTime` | 更新时间 |  
125 -  
126 -## 6. 前端接入建议  
127 -  
128 -建议前端采用“收到即全量覆盖”的方式刷新看板数据，不需要自己做增量合并。  
129 -  
130 -推荐接入流程：  
131 -  
132 -1. 页面加载后先确认用户已登录  
133 -2. 建立 WebSocket 连接  
134 -3. 收到首包 `INIT` 后，用 `records` 初始化看板  
135 -4. 收到 `CREATE`、`UPDATE` 后，直接用最新 `records` 覆盖页面数据  
136 -5. 连接关闭后执行自动重连  
137 -6. 重连成功后主动发送 `RESYNC`  
138 -  
139 -## 7. 联调自测建议  
140 -  
141 -### 7.1 单连接测试  
142 -  
143 -1. 使用已登录且有权限的账号打开测试页  
144 -2. 连接 WebSocket  
145 -3. 确认收到 `INIT` 全量数据  
146 -  
147 -### 7.2 多客户端广播测试  
148 -  
149 -1. 同时打开 2 个或以上客户端连接  
150 -2. 调用新增接口新增一条当日同行报价  
151 -3. 检查所有客户端是否都收到 `CREATE`  
152 -4. 调用修改接口修改一条当日同行报价  
153 -5. 检查所有客户端是否都收到 `UPDATE`  
154 -  
155 -### 7.3 断线重连测试  
156 -  
157 -1. 建立连接并收到初始化数据  
158 -2. 手动断开连接或模拟网络波动  
159 -3. 重连成功后发送 `RESYNC`  
160 -4. 检查是否重新收到当日全量数据  
161 -  
162 -### 7.4 回归验证  
163 -  
164 -联调过程中同步回归以下原有能力：  
165 -  
166 -- 同行报价信息原分页查询接口  
167 -- 同行报价信息详情接口  
168 -- 同行报价信息新增接口  
169 -- 同行报价信息修改接口  
170 -  
171 -确认新增 WebSocket 能力未影响原有接口行为。  
172 -  
173 -## 8. 本地测试页  
174 -  
175 -仓库中已提供本地测试页：  
176 -  
177 -```text  
178 -docs/salesman-quotation-peer-websocket-test.html  
179 -```  
180 -  
181 -可直接使用浏览器打开。  
182 -  
183 -注意：  
184 -  
185 -- 建议使用已登录系统的同一浏览器用户环境测试  
186 -- 如果浏览器环境没有把登录态带到 WebSocket 握手中，连接会返回 `403`  
187 -- 如出现该情况，请优先在已登录业务系统页面同浏览器环境中测试  
1 -<!DOCTYPE html>  
2 -<html lang="zh-CN">  
3 -<head>  
4 - <meta charset="UTF-8">  
5 - <meta name="viewport" content="width=device-width, initial-scale=1.0">  
6 - <title>同行报价信息 WebSocket 测试页</title>  
7 - <style>  
8 - body {  
9 - margin: 0;  
10 - font-family: Arial, sans-serif;  
11 - background: #f5f7fa;  
12 - color: #1f2329;  
13 - }  
14 -  
15 - .page {  
16 - max-width: 1200px;  
17 - margin: 0 auto;  
18 - padding: 24px;  
19 - }  
20 -  
21 - .card {  
22 - background: #fff;  
23 - border-radius: 8px;  
24 - box-shadow: 0 2px 12px rgba(31, 35, 41, 0.08);  
25 - padding: 16px;  
26 - margin-bottom: 16px;  
27 - }  
28 -  
29 - .title {  
30 - margin: 0 0 12px;  
31 - font-size: 20px;  
32 - font-weight: 700;  
33 - }  
34 -  
35 - .desc {  
36 - margin: 0;  
37 - line-height: 1.7;  
38 - color: #4e5969;  
39 - }  
40 -  
41 - .row {  
42 - display: flex;  
43 - gap: 12px;  
44 - flex-wrap: wrap;  
45 - margin-bottom: 12px;  
46 - }  
47 -  
48 - .field {  
49 - flex: 1;  
50 - min-width: 280px;  
51 - }  
52 -  
53 - label {  
54 - display: block;  
55 - margin-bottom: 6px;  
56 - font-size: 14px;  
57 - font-weight: 600;  
58 - }  
59 -  
60 - input,  
61 - textarea,  
62 - button {  
63 - box-sizing: border-box;  
64 - font-size: 14px;  
65 - font-family: Arial, sans-serif;  
66 - }  
67 -  
68 - input,  
69 - textarea {  
70 - width: 100%;  
71 - padding: 10px 12px;  
72 - border: 1px solid #d0d7de;  
73 - border-radius: 6px;  
74 - background: #fff;  
75 - }  
76 -  
77 - textarea {  
78 - min-height: 120px;  
79 - resize: vertical;  
80 - }  
81 -  
82 - .actions {  
83 - display: flex;  
84 - gap: 12px;  
85 - flex-wrap: wrap;  
86 - }  
87 -  
88 - button {  
89 - border: none;  
90 - border-radius: 6px;  
91 - padding: 10px 16px;  
92 - cursor: pointer;  
93 - color: #fff;  
94 - background: #1677ff;  
95 - }  
96 -  
97 - button.secondary {  
98 - background: #00b578;  
99 - }  
100 -  
101 - button.warn {  
102 - background: #ff7d00;  
103 - }  
104 -  
105 - button.danger {  
106 - background: #f53f3f;  
107 - }  
108 -  
109 - button.gray {  
110 - background: #86909c;  
111 - }  
112 -  
113 - .status {  
114 - font-weight: 700;  
115 - }  
116 -  
117 - .status.connected {  
118 - color: #00b578;  
119 - }  
120 -  
121 - .status.closed {  
122 - color: #f53f3f;  
123 - }  
124 -  
125 - .muted {  
126 - color: #86909c;  
127 - font-size: 13px;  
128 - }  
129 -  
130 - pre {  
131 - margin: 0;  
132 - padding: 12px;  
133 - background: #111827;  
134 - color: #e5e7eb;  
135 - border-radius: 6px;  
136 - overflow: auto;  
137 - white-space: pre-wrap;  
138 - word-break: break-word;  
139 - line-height: 1.6;  
140 - }  
141 -  
142 - .log-box {  
143 - max-height: 360px;  
144 - overflow: auto;  
145 - background: #111827;  
146 - color: #e5e7eb;  
147 - border-radius: 6px;  
148 - padding: 12px;  
149 - font-size: 13px;  
150 - line-height: 1.6;  
151 - }  
152 -  
153 - .log-line {  
154 - margin-bottom: 6px;  
155 - }  
156 -  
157 - table {  
158 - width: 100%;  
159 - border-collapse: collapse;  
160 - background: #fff;  
161 - }  
162 -  
163 - th,  
164 - td {  
165 - border-bottom: 1px solid #edf1f5;  
166 - padding: 10px 8px;  
167 - text-align: left;  
168 - font-size: 13px;  
169 - vertical-align: top;  
170 - }  
171 -  
172 - th {  
173 - background: #f7f8fa;  
174 - }  
175 - </style>  
176 -</head>  
177 -<body>  
178 - <div class="page">  
179 - <div class="card">  
180 - <h1 class="title">同行报价信息 WebSocket 测试页</h1>  
181 - <p class="desc">  
182 - 使用说明：请先在同一浏览器中登录业务系统，再打开本页测试。当前服务端握手鉴权依赖现有登录态，  
183 - 如果浏览器没有把登录态带到 WebSocket 握手，请求会返回 403。  
184 - </p>  
185 - </div>  
186 -  
187 - <div class="card">  
188 - <div class="row">  
189 - <div class="field">  
190 - <label for="wsUrl">WebSocket 地址</label>  
191 - <input id="wsUrl" value="ws://localhost:8081/ws/procurement/salesmanQuotationPeer/realtime">  
192 - </div>  
193 - <div class="field">  
194 - <label for="statusText">连接状态</label>  
195 - <input id="statusText" value="未连接" readonly>  
196 - </div>  
197 - </div>  
198 -  
199 - <div class="actions">  
200 - <button id="connectBtn">连接</button>  
201 - <button id="disconnectBtn" class="danger">断开</button>  
202 - <button id="syncBtn" class="secondary">发送 SYNC_TODAY</button>  
203 - <button id="resyncBtn" class="warn">发送 RESYNC</button>  
204 - <button id="clearBtn" class="gray">清空日志</button>  
205 - </div>  
206 -  
207 - <p class="muted" style="margin-top: 12px;">  
208 - 建连成功后，服务端会自动推送一份 <code>INIT</code> 全量数据；重连后可手动发送 <code>RESYNC</code>。  
209 - </p>  
210 - </div>  
211 -  
212 - <div class="card">  
213 - <h2 class="title">自定义消息</h2>  
214 - <div class="row">  
215 - <div class="field">  
216 - <label for="customMessage">发送内容</label>  
217 - <textarea id="customMessage">RESYNC</textarea>  
218 - </div>  
219 - </div>  
220 - <div class="actions">  
221 - <button id="sendCustomBtn">发送自定义消息</button>  
222 - </div>  
223 - </div>  
224 -  
225 - <div class="card">  
226 - <h2 class="title">最新消息摘要</h2>  
227 - <div class="row">  
228 - <div class="field">  
229 - <label for="messageType">messageType</label>  
230 - <input id="messageType" readonly>  
231 - </div>  
232 - <div class="field">  
233 - <label for="eventType">eventType</label>  
234 - <input id="eventType" readonly>  
235 - </div>  
236 - <div class="field">  
237 - <label for="businessDate">businessDate</label>  
238 - <input id="businessDate" readonly>  
239 - </div>  
240 - <div class="field">  
241 - <label for="pushTime">pushTime</label>  
242 - <input id="pushTime" readonly>  
243 - </div>  
244 - <div class="field">  
245 - <label for="recordCount">records 数量</label>  
246 - <input id="recordCount" readonly>  
247 - </div>  
248 - </div>  
249 - </div>  
250 -  
251 - <div class="card">  
252 - <h2 class="title">最新原始消息</h2>  
253 - <pre id="rawMessage">暂无数据</pre>  
254 - </div>  
255 -  
256 - <div class="card">  
257 - <h2 class="title">数据预览</h2>  
258 - <table>  
259 - <thead>  
260 - <tr>  
261 - <th>ID</th>  
262 - <th>同行名称</th>  
263 - <th>品种名称</th>  
264 - <th>品种代号</th>  
265 - <th>同行报价</th>  
266 - <th>备注</th>  
267 - <th>创建时间</th>  
268 - <th>更新时间</th>  
269 - </tr>  
270 - </thead>  
271 - <tbody id="recordsBody">  
272 - <tr>  
273 - <td colspan="8">暂无数据</td>  
274 - </tr>  
275 - </tbody>  
276 - </table>  
277 - </div>  
278 -  
279 - <div class="card">  
280 - <h2 class="title">运行日志</h2>  
281 - <div id="logBox" class="log-box"></div>  
282 - </div>  
283 - </div>  
284 -  
285 - <script>  
286 - let socket = null;  
287 -  
288 - const wsUrlInput = document.getElementById("wsUrl");  
289 - const statusText = document.getElementById("statusText");  
290 - const customMessage = document.getElementById("customMessage");  
291 - const rawMessage = document.getElementById("rawMessage");  
292 - const logBox = document.getElementById("logBox");  
293 - const recordsBody = document.getElementById("recordsBody");  
294 - const messageTypeInput = document.getElementById("messageType");  
295 - const eventTypeInput = document.getElementById("eventType");  
296 - const businessDateInput = document.getElementById("businessDate");  
297 - const pushTimeInput = document.getElementById("pushTime");  
298 - const recordCountInput = document.getElementById("recordCount");  
299 -  
300 - function nowText() {  
301 - return new Date().toLocaleString();  
302 - }  
303 -  
304 - function addLog(message) {  
305 - const line = document.createElement("div");  
306 - line.className = "log-line";  
307 - line.textContent = "[" + nowText() + "] " + message;  
308 - logBox.prepend(line);  
309 - }  
310 -  
311 - function setStatus(text, connected) {  
312 - statusText.value = text;  
313 - statusText.className = connected ? "status connected" : "status closed";  
314 - }  
315 -  
316 - function renderSummary(data) {  
317 - messageTypeInput.value = data.messageType || "";  
318 - eventTypeInput.value = data.eventType || "";  
319 - businessDateInput.value = data.businessDate || "";  
320 - pushTimeInput.value = data.pushTime || "";  
321 - recordCountInput.value = Array.isArray(data.records) ? String(data.records.length) : "0";  
322 - }  
323 -  
324 - function renderTable(records) {  
325 - if (!Array.isArray(records) || records.length === 0) {  
326 - recordsBody.innerHTML = "<tr><td colspan=\"8\">暂无数据</td></tr>";  
327 - return;  
328 - }  
329 -  
330 - const rows = records.map(function(record) {  
331 - return "<tr>"  
332 - + "<td>" + escapeHtml(record.id) + "</td>"  
333 - + "<td>" + escapeHtml(record.peerName) + "</td>"  
334 - + "<td>" + escapeHtml(record.peerProductName) + "</td>"  
335 - + "<td>" + escapeHtml(record.peerProductCode) + "</td>"  
336 - + "<td>" + escapeHtml(record.peerPrice) + "</td>"  
337 - + "<td>" + escapeHtml(record.remark) + "</td>"  
338 - + "<td>" + escapeHtml(record.createTime) + "</td>"  
339 - + "<td>" + escapeHtml(record.updateTime) + "</td>"  
340 - + "</tr>";  
341 - });  
342 -  
343 - recordsBody.innerHTML = rows.join("");  
344 - }  
345 -  
346 - function escapeHtml(value) {  
347 - if (value === null || value === undefined) {  
348 - return "";  
349 - }  
350 -  
351 - return String(value)  
352 - .replace(/&/g, "&amp;")  
353 - .replace(/</g, "&lt;")  
354 - .replace(/>/g, "&gt;")  
355 - .replace(/\"/g, "&quot;")  
356 - .replace(/'/g, "&#39;");  
357 - }  
358 -  
359 - function connect() {  
360 - const url = wsUrlInput.value.trim();  
361 - if (!url) {  
362 - addLog("连接失败：WebSocket 地址不能为空");  
363 - return;  
364 - }  
365 -  
366 - if (socket && socket.readyState === WebSocket.OPEN) {  
367 - addLog("当前已连接，无需重复连接");  
368 - return;  
369 - }  
370 -  
371 - addLog("开始连接：" + url);  
372 - socket = new WebSocket(url);  
373 -  
374 - socket.onopen = function() {  
375 - setStatus("已连接", true);  
376 - addLog("连接成功");  
377 - };  
378 -  
379 - socket.onmessage = function(event) {  
380 - addLog("收到消息：" + event.data);  
381 - rawMessage.textContent = event.data;  
382 -  
383 - try {  
384 - const data = JSON.parse(event.data);  
385 - renderSummary(data);  
386 - renderTable(data.records);  
387 - } catch (error) {  
388 - addLog("消息解析失败：" + error.message);  
389 - }  
390 - };  
391 -  
392 - socket.onerror = function() {  
393 - addLog("连接出现错误，请检查登录态、服务地址和网络");  
394 - };  
395 -  
396 - socket.onclose = function(event) {  
397 - setStatus("已断开", false);  
398 - addLog("连接关闭，code=" + event.code + "，reason=" + (event.reason || "无"));  
399 - };  
400 - }  
401 -  
402 - function disconnect() {  
403 - if (!socket) {  
404 - addLog("当前没有可断开的连接");  
405 - return;  
406 - }  
407 - socket.close();  
408 - }  
409 -  
410 - function sendMessage(message) {  
411 - if (!socket || socket.readyState !== WebSocket.OPEN) {  
412 - addLog("发送失败：当前连接未建立");  
413 - return;  
414 - }  
415 -  
416 - socket.send(message);  
417 - addLog("已发送消息：" + message);  
418 - }  
419 -  
420 - document.getElementById("connectBtn").addEventListener("click", connect);  
421 - document.getElementById("disconnectBtn").addEventListener("click", disconnect);  
422 - document.getElementById("syncBtn").addEventListener("click", function() {  
423 - sendMessage("SYNC_TODAY");  
424 - });  
425 - document.getElementById("resyncBtn").addEventListener("click", function() {  
426 - sendMessage("RESYNC");  
427 - });  
428 - document.getElementById("sendCustomBtn").addEventListener("click", function() {  
429 - sendMessage(customMessage.value.trim());  
430 - });  
431 - document.getElementById("clearBtn").addEventListener("click", function() {  
432 - logBox.innerHTML = "";  
433 - rawMessage.textContent = "暂无数据";  
434 - renderSummary({  
435 - messageType: "",  
436 - eventType: "",  
437 - businessDate: "",  
438 - pushTime: "",  
439 - records: []  
440 - });  
441 - renderTable([]);  
442 - addLog("日志已清空");  
443 - });  
444 -  
445 - setStatus("未连接", false);  
446 - addLog("页面已加载，可开始测试");  
447 - </script>  
448 -</body>  
449 -</html>