refactor: 清理死代码/提前失败/日志/高内聚低耦合

死代码移除:
- 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 链接)

README.md

@@ -1,26 +1,78 @@
-# zWhiteBoard
+# zWhiteBoard - 共享记事本前端
 
-共享记事本前端 -- textarea + WebSocket 实时同步、心跳、断线重连。复用 zTools2 后端 API。
+textarea + WebSocket 实时同步的共享记事本：多人同写一块白板，400ms debounce、3s 心跳、断线 2s 重连。复用 [zTools2](https://git.zikai.wang/zikai/zTools2) 后端 API（`/api/wb/*` 与 `/api/ws/wb/*`）。便携式组件，可独立运行，亦可作为 [mainPage](https://git.zikai.wang/zikai/zMainPage) 的子模块经构建期组件 import 集成展示（像 [timeTableFix](https://git.zikai.wang/zikai/timeTableFix)）。
 
-## 集成方式
+## 功能
 
-便携式组件，两种运行模式：
+- 多人实时同步同一块白板文本（全量同步，last-writer-wins，非 OT/CRDT）
+- 应用远端更新时按最长公共前后缀做区间替换，保留本地光标位置
+- 3s 心跳保活 + 断线 2s 固定重连
+- 页面切到后台时 flush 未发送编辑，切回前台时若掉线自动重连
+- 清空白板（广播 cleared 帧）、复制文本/链接
 
-- **独立运行**：`npm run dev` / `npm run build`，自带 i18n 与全局样式。
-- **嵌入 mainPage**：作为 git submodule 挂在 zMainPage `third_party/zWhiteBoard`，经构建期组件 import 集成（非 iframe）。mainPage 侧包装器 `Whiteboard.vue` 套 `PageShell` 并透传 `:locale` / `:boardId` props。
+## 项目结构
 
-## 后端接口（zTools2 提供，不改动）
+```
+zWhiteBoard/
+├── index.html                  Vite 入口
+├── package.json
+├── vite.config.js              base:'./' 便携式构建；dev 代理 /api（含 ws:true）
+├── vitest.config.js
+├── .npmrc                      npmmirror 镜像加速
+├── src/
+│   ├── main.js                 应用挂载（i18n + 全局样式）
+│   ├── App.vue                 便携式根组件（接受 :locale/:boardId prop，独立/嵌入两用）
+│   ├── i18n/                   独立 vue-i18n 实例 + 中英 locale
+│   ├── composables/
+│   │   ├── useWhiteboard.js    WS 客户端 + 同步状态机（与 DOM 解耦，可单测）
+│   │   └── useLocale.js        语言辅助（直读自身 i18n 实例）
+│   ├── components/
+│   │   └── WbEditor.vue        textarea + 工具栏 + 状态条（渲染与事件转发）
+│   └── styles/global.css       全局重置 + 设计令牌
+└── test/                       Vitest 单元测试（19 项）
+```
 
-- `GET /api/wb/{id}` -- 预取白板内容（不存在则服务端新建）
-- `WS /api/ws/wb/{id}` -- 实时同步：hello / edit / ping / clear（C->S）；init / pong / update / cleared / error（S->C）
+## 外部依赖
 
-全量文本同步（非 OT/CRDT，last-writer-wins），400ms debounce，3s 心跳，2s 固定重连。
+| 项 | 说明 |
+|----|------|
+| Node.js | ≥ 18 |
+| zTools2 | 后端 `/api/wb/*` 与 `/api/ws/wb/*`（同源调用，cookie 自动管理） |
 
-## 开发
+> 前端纯静态，无运行期后端依赖；API/WS 由 zTools2 提供。生产部署经 [zMainPage](https://git.zikai.wang/zikai/zMainPage) 作为子模块集成，由其 apache2 静态托管 + `/api` 反代到 zTools2（含 WebSocket 升级，无独立 apache2 配置）。
+
+## 如何使用
 
 ```bash
-npm install
-npm test        # 单元测试
-npm run dev     # 开发服务器（代理 /api -> 本地 zTools2:6867，含 ws:true）
-npm run build   # 产物在 dist/
+# 克隆并安装
+git clone https://git.zikai.wang/zikai/zWhiteBoard.git
+cd zWhiteBoard
+npm install        # 已配 npmmirror 镜像加速
+
+npm run dev        # 开发服务器 http://localhost:5176（vite.config.js 已配 /api 代理到 zTools2:6867，含 ws:true）
+npm run build      # 构建到 dist/
+npm test           # 单元测试（19 项）
 ```
+
+> 开发时 `/api/wb/*` 与 `/api/ws/wb/*` 由 vite 代理到本地 zTools2（127.0.0.1:6867，`ws:true` 覆盖 WebSocket）；生产环境由 mainPage 同源反代到 zTools2。
+
+## 嵌入 mainPage
+
+作为 [mainPage](https://git.zikai.wang/zikai/zMainPage) 的 git submodule，经构建期组件 import 集成（非 iframe）。详见 [`docs/integration.md`](./docs/integration.md)。
+
+## 技术栈
+
+| 项 | 选择 |
+|----|------|
+| 框架 | Vue 3.5（SFC，`<script setup>`） |
+| 构建 | Vite 6 |
+| 国际化 | vue-i18n 9（中文同步，英文懒加载） |
+| 状态管理 | composable 单例 |
+| 测试 | Vitest |
+| 包源 | npmmirror.com（中国镜像加速） |
+
+## 了解更多
+
+- [嵌入 mainPage（构建期组件 import）](./docs/integration.md)
+- [错误处理与日志约定](./docs/error-handling.md)
+- 后端 API 与 WS 协议见 [zTools2](https://git.zikai.wang/zikai/zTools2) README