3.2 KiB
wc-board
词云现场互动 Web 应用，包含个人查找、大屏展示和遥控器三个页面。demo 可用于离线验收；其他路由会在运行时加载 WordCloud 任务的位置数据与 SVG。
Quick Start
npm install
npm run dev
打开以下路由验证离线完整流程：
/cloud/demo
/screen/demo
/control/demo
在同一浏览器的两个 tab 中分别打开大屏与遥控器后，遥控器提交名字可以让大屏聚焦；多个连续提交会排队展示。
Commands
npm run dev
npm run build
npm run preview
npm test
npm run typecheck
npm run lint
Structure
src/pages/：Personal Search、Public Display、Remote Controller。src/components/：词云、搜索 dock、QR panel、状态组件。src/data/clouds/：离线demo词云数据。src/lib/wordcloudApi.ts：WordCloud API 适配器；运行时读取位置数据与 SVG。src/hooks/useCloud.ts：为三个页面统一加载本地 demo 或远程产品词云。src/hooks/：focus lifecycle、queue 和 realtime integration。src/realtime/：BroadcastChannel adapter；后续 WebSocket/Supabase 等实现替换这一层。src/styles/global.css：从既有设计提取的全局 tokens。Design/：已确认的视觉基准和设计 handoff。
本地开发默认使用同一浏览器内的 BroadcastChannel；生产构建默认使用同源 WebSocket adapter，适合多设备访问。当前 realtime 服务是内存转发，暂不保存名单或事件。
Production Deployment
cp .env.example .env
docker compose up -d --build
默认端口由 .env 的 APP_PORT 控制，例如 APP_PORT=47880 时通过下面地址访问：
http://<server-host>:47880/cloud/demo
http://<server-host>:47880/screen/demo
http://<server-host>:47880/control/demo
生产构建使用 WebSocket adapter，浏览器连接同源 /ws；Nginx 会将该路径转发到 realtime 容器。因为二维码按当前浏览器的 origin 生成，通过 A 域名打开大屏时，扫码会进入 A 域名的 Controller，而不会跳去 B 域名。
如果 A 和 B 是不同域名并都指向同一台服务器，可以在外层网关或 DNS 上都转发到 Compose 暴露的端口；前端与二维码会保留访问者实际使用的域名。
除 demo 外，路由参数即 WordCloud productId。例如：
/cloud/prod_362d8ecaced241e5ab81dddfc880d6b0
/screen/prod_362d8ecaced241e5ab81dddfc880d6b0
/control/prod_362d8ecaced241e5ab81dddfc880d6b0
/cloud/imported、/screen/imported 与 /control/imported 是由 VITE_WORDCLOUD_DEFAULT_PRODUCT_ID 配置的默认产品别名。应用先从同源 /wordcloud-product-api 解析 Product ID 对应的最新词云归档，再从 /wordcloud-api 读取位置数据与 SVG。这样浏览器不需要读取产品管理鉴权信息，多域名部署时仍保留访问者实际使用的域名。一个 Product 下存在多个词云时，当前版本先取最新归档中的第一个词云。
本地 npm run dev 也会将 /wordcloud-api 转发到同一个后端。只有在已具备可靠 CORS 的场景，才需要把 VITE_WORDCLOUD_API_BASE_URL 改为完整的远端 URL。