77 lines
3.0 KiB
Markdown
77 lines
3.0 KiB
Markdown
# wc-board
|
||
|
||
词云现场互动 Web 应用，包含个人查找、大屏展示和遥控器三个页面。`demo` 可用于离线验收；其他路由会在运行时加载 WordCloud 任务的位置数据与 SVG。
|
||
|
||
## Quick Start
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
打开以下路由验证离线完整流程：
|
||
|
||
```text
|
||
/cloud/demo
|
||
/screen/demo
|
||
/control/demo
|
||
```
|
||
|
||
在同一浏览器的两个 tab 中分别打开大屏与遥控器后，遥控器提交名字可以让大屏聚焦；多个连续提交会排队展示。
|
||
|
||
## Commands
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
docker compose up -d --build
|
||
```
|
||
|
||
默认端口由 `.env` 的 `APP_PORT` 控制，例如 `APP_PORT=47880` 时通过下面地址访问：
|
||
|
||
```text
|
||
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 `jobId`。例如：
|
||
|
||
```text
|
||
/cloud/bd1f240adcb4458f857c40ac427122c6
|
||
/screen/bd1f240adcb4458f857c40ac427122c6
|
||
/control/bd1f240adcb4458f857c40ac427122c6
|
||
```
|
||
|
||
`/cloud/imported`、`/screen/imported` 与 `/control/imported` 是由 `VITE_WORDCLOUD_DEFAULT_JOB_ID` 配置的默认任务别名。应用默认从同源 `/wordcloud-api` 读取位置与 SVG，Nginx 再将其转发到 `WORDCLOUD_API_UPSTREAM`，默认值为 `http://192.168.31.213:8000`。这样浏览器不需要跨域读取 SVG，且多域名部署时仍保留访问者实际使用的域名。
|
||
|
||
本地 `npm run dev` 也会将 `/wordcloud-api` 转发到同一个后端。只有在已具备可靠 CORS 的场景，才需要把 `VITE_WORDCLOUD_API_BASE_URL` 改为完整的远端 URL。
|