同行报价信息 WebSocket 联调说明

1. 功能说明

本功能用于支撑业务员报价实时看板，采用 WebSocket 协议向前端实时推送“当日同行报价信息全量数据”。

注意：

• 本功能为独立新增能力，不影响原有查询接口
• 服务端仅推送“当日产生”的同行报价信息
• 新增、修改成功并事务提交后，会向所有在线客户端广播最新当日全量数据
• 前端断线重连后，可主动发起补推请求

2. WebSocket 地址

服务端路径：

/ws/procurement/salesmanQuotationPeer/realtime

联调示例：

ws://localhost:8080/ws/procurement/salesmanQuotationPeer/realtime

请将 localhost:8080 替换为实际后端服务地址。

4. 服务端推送规则

4.1 建连后初始化推送

客户端连接成功后，服务端会立即回推一份“当日完整数据”：

• eventType = INIT
• messageType = FULL_SYNC

4.2 新增后广播

当日同行报价基础数据新增成功并事务提交后：

• 向所有在线客户端广播
• eventType = CREATE
• messageType = FULL_SYNC

4.3 修改后广播

当日同行报价基础数据修改成功并事务提交后：

• 向所有在线客户端广播
• eventType = UPDATE
• messageType = FULL_SYNC

4.4 断线重连补推

客户端重连成功后，可主动发送以下文本消息之一：

• SYNC_TODAY
• RESYNC

服务端收到后，会重新回推“当日完整数据”：

• eventType = RESYNC
• messageType = FULL_SYNC

5. 消息结构

5.1 服务端返回消息体

{
  "messageType": "FULL_SYNC",
  "eventType": "INIT",
  "businessDate": "2026-07-10",
  "pushTime": "2026-07-10T16:30:00",
  "records": [
    {
      "id": "1900000000000000001",
      "peerName": "某同行",
      "peerProductId": "1900000000000000002",
      "peerProductName": "紫铜",
      "peerProductCode": "ZT001",
      "peerPrice": 76800.50,
      "remark": "测试数据",
      "createById": "1001",
      "createBy": "张三",
      "updateById": "1001",
      "updateBy": "张三",
      "createTime": "2026-07-10T16:28:10",
      "updateTime": "2026-07-10T16:29:45"
    }
  ]
}

5.2 字段说明

字段	类型	说明
messageType	String	当前固定为 FULL_SYNC，表示推送的是当日全量数据
eventType	String	事件类型，可能为 INIT、CREATE、UPDATE、RESYNC
businessDate	LocalDate	当前业务日期
pushTime	LocalDateTime	本次推送时间
records	Array	当日同行报价信息列表

records 中主要字段如下：

字段	类型	说明
id	String	主键 ID
peerName	String	同行名称
peerProductId	String	同行品种 ID
peerProductName	String	同行品种名称
peerProductCode	String	同行品种代号
peerPrice	BigDecimal	同行报价
remark	String	备注
createById	String	创建人 ID
createBy	String	创建人
updateById	String	更新人 ID
updateBy	String	更新人
createTime	LocalDateTime	创建时间
updateTime	LocalDateTime	更新时间

6. 前端接入建议

建议前端采用“收到即全量覆盖”的方式刷新看板数据，不需要自己做增量合并。

推荐接入流程：

1. 页面加载后先确认用户已登录
2. 建立 WebSocket 连接
3. 收到首包 INIT 后，用 records 初始化看板
4. 收到 CREATE、UPDATE 后，直接用最新 records 覆盖页面数据
5. 连接关闭后执行自动重连
6. 重连成功后主动发送 RESYNC

7. 联调自测建议

7.1 单连接测试

1. 使用已登录且有权限的账号打开测试页
2. 连接 WebSocket
3. 确认收到 INIT 全量数据

7.2 多客户端广播测试

1. 同时打开 2 个或以上客户端连接
2. 调用新增接口新增一条当日同行报价
3. 检查所有客户端是否都收到 CREATE
4. 调用修改接口修改一条当日同行报价
5. 检查所有客户端是否都收到 UPDATE

7.3 断线重连测试

1. 建立连接并收到初始化数据
2. 手动断开连接或模拟网络波动
3. 重连成功后发送 RESYNC
4. 检查是否重新收到当日全量数据

7.4 回归验证

联调过程中同步回归以下原有能力：

• 同行报价信息原分页查询接口
• 同行报价信息详情接口
• 同行报价信息新增接口
• 同行报价信息修改接口

确认新增 WebSocket 能力未影响原有接口行为。

8. 本地测试页

仓库中已提供本地测试页：

docs/salesman-quotation-peer-websocket-test.html

可直接使用浏览器打开。

注意：

• 建议使用已登录系统的同一浏览器用户环境测试
• 如果浏览器环境没有把登录态带到 WebSocket 握手中，连接会返回 403
• 如出现该情况，请优先在已登录业务系统页面同浏览器环境中测试