# 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 `productId`。例如：

```text
/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。