# 看板WebSocket协议

`GET /data-dashboards/ws` 经过产品身份适配和Upgrade。工作区由workspace_id查询参数或X-Workspace-ID头指定，二者并存须相同，不允许重复或首尾空白。消息内不能切换工作区。

原生客户端可使用认证头；浏览器通过会话或moi-api-key / moi-bearer凭据子协议，另可带经校验的moi-role-id候选。服务端只回显协议名或角色候选，不回显秘密值。无Origin时要求认证头；有Origin时必须单个http/https来源、与请求Host一致且无路径/用户信息/query/fragment。完整握手策略与反向代理行为待环境验证。

消息封套严格只含id、message_type、data；id非空、最多128字节、无Unicode空白或控制字符。以下是源码定义的业务动作：

| 请求类型 | data | 对应成功类型 |
| --- | --- | --- |
| dashboard_preview_execute | dashboard_id、sql_text，可选chart_id | dashboard_preview_result |
| dashboard_chart_create | dashboard_id及图表mutation字段，不能带非空chart_id | dashboard_chart_create_result |
| dashboard_chart_update | dashboard_id、chart_id及图表mutation字段 | dashboard_chart_update_result |
| ping | 无业务输入 | pong，回显id |
| preclose | 无业务输入 | 关闭连接 |

成功data分别复用SQL预览或图表DTO，不是HTTP code/msg/data封套。

一个连接只运行一个业务动作，独立reader处理心跳与断线。不同id并发请求收到error，data含status=409、code=ErrDataDashboardOperationActive、msg；相同在途id会关闭连接以免混淆终态。不会按id建立持久化去重表，不能用重连后的同id实现幂等。错误消息为message_type=error，data中status为整数、code/msg为字符串；每个业务消息重新建立请求授权上下文。

断线取消上下文，写响应有10秒预算。更新成功后回读失败可直接关闭连接；服务端写入或提交后未收到确认不能断言操作失败。前端将已发送mutation的断线/超时记为结果未知，要求重新读看板详情，不自动重放保存；预览读操作与mutation分开处理。

前端当前握手15秒、心跳30秒、pong等待10秒、业务等待360秒；这些是客户端配置，不是服务端完成时限或生产SLA。
