b9ea2c322a
死代码移除: - useWhiteboard.js: 移除未使用的 suppressInput 变量及 6 处赋值; 移除 isInputSuppressed / _getSuppressInput / _setEditor 导出; scheduleSend 从公开 API 降为内部函数; setStatus 移除未用 isErr 形参 - useLocale.js: 移除未用的 isZh/pick/locale 返回值及 computed 导入 - App.vue: 移除未用的 ref 导入 - i18n locales: 移除 5 个死 key (switch/copied/copiedLink/copyFailed/emptyText) 提前失败/日志: - 7 处 silent catch (send/connect/onerror/onMessage JSON.parse/ applyRemoteUpdate setSelectionRange/connectBoard 预取/teardownSocket) 全部加 console.error/warn, 统一 [zWB] 前缀 - App.vue onCopyText/onCopyLink 失败 console.warn 文档: - 新增 docs/error-handling.md, docs/integration.md - README.md 重写为简洁版 (简介/结构/外部依赖/Ubuntu 安装使用/docs 链接)
23 lines
1.4 KiB
Markdown
23 lines
1.4 KiB
Markdown
# 错误处理与日志约定
|
||
|
||
zWhiteBoard 是实时同步客户端，错误处理分两层：WS 客户端 fail-fast（关键路径抛错/记日志），UI 层捕获后写控制台。
|
||
|
||
## WS 客户端（src/composables/useWhiteboard.js）
|
||
|
||
- `send`：`ws.send` 序列化失败 `console.error`（WS 通常是 RUNNING 状态，此分支极少触发，但记日志便于定位）。
|
||
- `connect`：`new WebSocket()` 抛错 `console.error` + 安排重连（URL 非法或浏览器拦截时）。
|
||
- `ws.onerror`：透传 `console.error`（浏览器仅给泛化错误，无 detail，但能标记故障时间点）。
|
||
- `onMessage`：JSON.parse 失败 `console.warn` 后忽略（不抛错，避免单条坏消息中断后续同步）。
|
||
- `applyRemoteUpdate`：`setSelectionRange` 失败 `console.warn`（光标修复非致命，文本已正确替换）。
|
||
- `connectBoard`：GET `/api/wb/{id}` 预取失败 `console.warn`，仍尝试连 WS（预取仅为优化，WS init 帧会兜底下发内容）。
|
||
- `teardownSocket`：关闭旧 WS 出错 `console.warn`（清理路径，不应阻塞切换）。
|
||
|
||
## UI 层（src/App.vue）
|
||
|
||
- `onCopyText` / `onCopyLink`：剪贴板 API 拒绝时 `console.warn`（HTTPS/权限策略限制，非致命，不影响同步）。
|
||
- `onClear`：未连接直接 return（不发 clear）；用户取消确认框直接 return。
|
||
|
||
## 控制台前缀
|
||
|
||
所有 `[zWB]` 前缀的日志来自本子项目，便于嵌入宿主时与宿主日志区分。
|