zWhiteBoard - 共享记事本前端

textarea + WebSocket 实时同步的共享记事本：多人同写一块白板，400ms debounce、3s 心跳、断线 2s 重连。复用 zTools2 后端 API（/api/wb/* 与 /api/ws/wb/*）。便携式组件，可独立运行，亦可作为 mainPage 的子模块经构建期组件 import 集成展示（像 timeTableFix）。

功能

• 多人实时同步同一块白板文本（全量同步，last-writer-wins，非 OT/CRDT）
• 应用远端更新时按最长公共前后缀做区间替换，保留本地光标位置
• 3s 心跳保活 + 断线 2s 固定重连
• 页面切到后台时 flush 未发送编辑，切回前台时若掉线自动重连
• 清空白板（广播 cleared 帧）、复制文本/链接

项目结构

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 项）

外部依赖

项	说明
Node.js	≥ 18
zTools2	后端 /api/wb/* 与 /api/ws/wb/*（同源调用，cookie 自动管理）

前端纯静态，无运行期后端依赖；API/WS 由 zTools2 提供。生产部署经 zMainPage 作为子模块集成，由其 apache2 静态托管 + /api 反代到 zTools2（含 WebSocket 升级，无独立 apache2 配置）。

如何使用

# 克隆并安装
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 的 git submodule，经构建期组件 import 集成（非 iframe）。详见 docs/integration.md。

技术栈

项	选择
框架	Vue 3.5（SFC，<script setup>）
构建	Vite 6
国际化	vue-i18n 9（中文同步，英文懒加载）
状态管理	composable 单例
测试	Vitest
包源	npmmirror.com（中国镜像加速）

了解更多

• 嵌入 mainPage（构建期组件 import）
• 错误处理与日志约定
• 后端 API 与 WS 协议见 zTools2 README