# data-screen

**Repository Path**: NBegin/data-screen

## Basic Information

- **Project Name**: data-screen
- **Description**: DataScreen 是一款面向企业级的可视化拖拽式智能大屏设计平台，内置 270+ 组件、35 套行业大屏模板 和 52 套主题，并集成 交互联动引擎、蓝图可视化编排、AI 智能助手、地图多级下钻 等高级能力，赋能业务人员自主构建专业数据大屏，实现"数据驱动决策"的最后一公里。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-11-06
- **Last Updated**: 2026-11-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DataScreen - 数字孪生 & 可视化大屏平台

## 项目简介

DataScreen 是一款面向企业级的可视化拖拽式智能大屏设计平台，内置 **690+ 组件**、**131 套内置模板**（**43 套行业数据大屏** + **88 套数字孪生 3D 场景**）和 **52 套主题**，并集成 **数字孪生渲染引擎**、**交互联动引擎**、**蓝图可视化编排**、**AI 智能助手**、**地图多级下钻** 等高级能力，赋能业务人员自主构建专业数据大屏，实现"数据驱动决策"的最后一公里。

> ⚠️ 本项目为**商业软件**，非开源项目。源码仅供开发者**学习、研究和技术探讨**；任何商业使用、生产部署或再分发均须购买授权。详见 [LICENSE](LICENSE) 与 [LICENSE-COMMERCIAL](LICENSE-COMMERCIAL)。

**在线预览**：[https://data-screen-3hc.pages.dev/](https://data-screen-3hc.pages.dev/)

## 界面预览

### 项目 / 模板中心

内置 131 套模板，其中 88 套为数字孪生场景，创建即用。

![项目与模板中心](./public/readme/项目模板.png)

### 数字孪生场景（three.js + Blender 实景资产）

> 下面每一屏都是可交互的 3D 场景：轨道环视、视角预设、巡航运镜、热点标注、射线拾取、构件巡览、时段/天气切换，并与看板数据双向联动。

| 现代化都市中枢 · 智慧城市 | 全球碳排放监测 · 地球孪生 |
| --- | --- |
| ![现代化都市中枢](./public/readme/1.png) | ![全球碳排放监测](./public/readme/4.png) |

| 智慧港口集群 | 海上风电场群 |
| --- | --- |
| ![智慧港口集群](./public/readme/2.png) | ![海上风电场群](./public/readme/3.png) |

| 农业大棚 | 智慧机场 |
| --- | --- |
| ![农业大棚](./public/readme/5.png) | ![智慧机场](./public/readme/6.png) |

| 水电站大坝 | 光伏储能电站 |
| --- | --- |
| ![水电站大坝](./public/readme/7.png) | ![光伏储能电站](./public/readme/8.png) |

| 江南水乡古镇 | 柔性产线 / 核电站 / 低轨星座 / 智慧管廊 …（共 88 套） |
| --- | --- |
| ![江南水乡古镇](./public/readme/9.png) | 覆盖城市、能源、港口、机场、水利、农业、工业、航天、深海、极地等 30+ 行业 |

### 传统数据大屏

| 企业运营数据监控中心 | 交通视频监控中心 | 自媒体矩阵分析平台 |
| --- | --- | --- |
| ![企业运营数据监控中心](./public/readme/10.png) | ![交通视频监控中心](./public/readme/11.png) | ![自媒体矩阵分析平台](./public/readme/13.png) |

## 核心功能

### 数字孪生大屏引擎（`packages/ui/src/twin/`）

基于 **three.js r186 + WebGL2** 的实景数字孪生引擎，是 88 套孪生模板的统一底座。每个场景由 `builder` 函数返回统一契约 `{ root, refs, update(dt, elapsed), dispose }`，配合 `SceneKernel` 渲染内核、`CameraRig` 相机、`binding` 数据绑定、`realismKit` 实景增强层等模块协作。

**渲染与画质**
- `EffectComposer` 后处理链：Bloom → GTAO（环境光遮蔽）→ SMAA → Vignette → Grain，可逐项开关
- 像素预算：有效 DPR = min(设备 DPR, 档位上限) × 超采样，**硬顶 2.6 + 900 万像素**（≈4K），大屏 3840 宽自动收敛
- 三档画质（high / mid / low）+ 作品级 `cinematic` 画质档（默认交付）
- 首帧为无贴图 PBR 材质注入共享程序化法线 / 粗糙度扰动图，破除塑料高光；噪声 / 沥青 / 草地 / 混凝土 / 玻璃幕墙 / 熔岩 / 水体全部 Canvas 程序化生成

**资产管线（Blender → GLB）**
- **200+ 个 GLB 实景资产**（`packages/ui/src/twin/assets/twin/`），由 `scripts/blender/twin_landmark.py` 等 Blender 脚本程序化建模，烘焙 PBR 贴图后导出
- 地标建筑（楼阁 / 长城 / 港口岸桥 / 货轮 / 展馆…）走「Blender 实景 GLB 优先 + 程序化兜底」双路径
- 资产按需加载：`twinAssetLibrary({ names, prefix })` 只拉取本场景需要的 GLB，按 key 缓存并跨场景复用，并发加载去重

**数据驱动（模板级 4 数据焦点）**

| 绑定属性 | 语义 | 典型用途 |
| --- | --- | --- |
| `scaleY` | 高度缩放 | 液位 / 柱高 / 偏差柱 |
| `lift` | 升降位移 | 吊具 / 车厢 / 传感器箱 / 闸门 |
| `heat` | 自发光强度 | 状态灯 / 警示灯 / 功率活跃度 |

**交互能力**
- 轨道相机（拖拽环视 / 滚轮缩放 / 待机慢旋）、视角预设、**巡航运镜**（Catmull-Rom 平滑曲线 + 每站停留）、**构件巡览**（逐个飞近带数据构件并弹面板）
- HTML 投影**热点标注**（无手写热点时由 `autoHotspots` 从 bindings 反推）、**射线拾取**（悬停高亮 / 单击聚焦）
- **量测**（距离 / 高差 / 面积）、图层过滤、构件搜索、罗盘、**昼·黄昏·夜**整场景重建、晴·雨·雾·雪天气无缝切换、开场运镜

**模型 ↔ 看板双向联动**
- 模型 → 看板：点中构件发 `object-click`、点中热点发 `hotspot-click`，载荷含 `{ twinId, label, world, screenX, screenY, value }`，可参与联动规则与动作调用
- 看板 → 模型：`TwinScene` 暴露 `focusTwin / highlightTwin / clearHighlight / resetView / goViewpoint / startCruise / stopCruise / startTour / stopTour / listTwinIds`，交互动作新增 **`twinCommand`**（focus / highlight / resetView / viewpoint / cruise / timeOfDay / weather + 构件 twinId）

**场景编辑**
- 场景树展开 / 搜索任意 GLB 节点，拾取支持业务 `twinId`、楼群 `InstancedMesh`、任意子节点稳定路径
- 显隐 / 位移 / 旋转 / 缩放（TransformControls）、颜色 / 粗糙度 / 金属度 / 自发光 / 不透明度覆写（只改 clone 不回写共享资产）
- 吸附、撤销 / 重做（快照栈 60 步）、隔离显示、聚焦、一键重置、包围盒读数、方向键微调、Ctrl+C/V 复制姿态
- 编辑经 `scene-edit` 防抖写入 `config.sceneEdits`，场景重建时按稳定路径回放

### 可视化设计器

- **可视化画布**：自由拖拽布局，组件可移动、缩放、旋转、对齐、分布
- **组件配置面板**：样式、数据源、交互、图表、主题、屏幕设置全方位配置（Schema 驱动）
- **屏幕适配**：等比缩放、自适应宽度等多种适配模式
- **撤销/重做**：完整的操作历史记录（UndoHistoryPanel）
- **图层管理**：图层树形管理、显隐锁定、层级调整、右键上下文菜单
- **版本管理**：大屏版本快照与回滚
- **快捷键与新手引导**：丰富键盘快捷键；基于 driver.js 的交互式引导教程

### 交互联动引擎

独立于组件库的事件驱动交互系统（`src/interactions/`），支持组件间通信与业务编排：

- **InteractionManager**：组件事件订阅中心，覆盖 `click / change / submit / select / focus / blur / hover / drilldown` 等
- **LinkageEngine**：联动规则引擎，支持 `source / sourceType / trigger / targets / condition / priority / debounce`，顺序/并行执行目标
- **ActionRegistry**：内置 **25+ 种动作**：
  - 组件类：显示/隐藏/更新/切换组件
  - 变量类：全局变量读写
  - 导航类：页面跳转、更新标题/favicon
  - 弹窗类：Toast / Confirm / Dialog / Loading
  - 数据类：API 请求、WebSocket / MQTT 消息
  - 系统类：下载文件、延迟、播放动画
  - 联动/事件类：规则触发与事件转发
  - 孪生类：`twinCommand` 驱动 3D 模型（聚焦/高亮/视角/巡航/时段/天气）

### 蓝图编辑器（Blueprint Editor）

节点连线的可视化交互编排器（`src/components/BlueprintEditor.vue`），在设计态编排组件交互逻辑链，预览/分享态由 `blueprintExecutor` 执行：

- 左侧节点库（搜索与分类折叠）、画布缩放/平移、网格背景与对齐辅助线
- SVG 三阶贝塞尔连接线，端口拖拽创建连接（含自连接与重复连接校验）
- 内置节点类型：`click / hover / data-change / interval / show-component / hide-component / update-component / navigate / if-else / switch-case / api-request / websocket-message / mqtt-message / show-toast / play-animation` 等
- 节点属性表单、组件 ID / 动作 / 全局变量 / 联动规则动态选择器、撤销/重做

### AI 智能助手

集成式 AI 辅助设计能力（`AIAssistantDialog.vue` + `src/services/aiService.js` + `aiDesignService.js`）：

- **组件推荐**：基于当前画布组件、行业（smartcity / logistics / energy 等）与主题偏好加权推荐
- **布局优化**：空白画布初始布局方案（单中心 / 上下 / 三栏 / 网格 / 左右）
- **配色方案**：主题色板智能应用
- **智能防重叠定位**：添加组件时自动避让已有组件
- **模板匹配**：根据描述匹配行业模板

### 地图组件与多级下钻

基于 **Leaflet + 高德瓦片** 的真实地图方案（`packages/ui/src/components/maps/`），**不依赖高德 JS API / VITE_AMAP_KEY**：

| 组件 | 能力 |
|------|------|
| `MapL7Base` | 基础地图、瓦片切换、标记点、点击下钻 |
| `MapL7Scatter` | 地理散点图、数值颜色映射、图例范围 |
| `MapL7Heatmap` | 热力图（leaflet.heat）、最近点点击判断 |
| `MapL7Flyline` | 飞线图、贝塞尔曲线、动态移动点、脉冲标记 |
| `MapL7Track` | 轨迹回放、播放/暂停/重置、速度控制、进度条、自动跟随 |
| `DrillDownBreadcrumb` | 下钻层级面包屑导航 |

- **瓦片类型**：高德标准 / 卫星 / 暗色 / 浅色 / OSM，配置中心化于 `utils/leafletSetup.js`
- **多级下钻**：层级栈管理、面包屑生成、下钻字段配置、`drilldown / change` 事件
- **GeoJSON 本地化**：`public/maps/` 托管中国及省级数据，运行时经 `geoData.js` fetch + 内存缓存，不通外网；未托管时回退阿里云 DataV CDN

### 全局变量 / URL 参数 / 国际化

- **全局状态**：跨组件共享变量，支持交互动作读写
- **URL 参数绑定**（`useUrlParamBindings.js`）：URL query ↔ globalState 双向同步，支持默认值与类型推断，实现参数化大屏
- **国际化**：基于 vue-i18n，内置 `zh-CN` / `en-US`

### 组件库（690+）

设计态组件目录（`@nbreak/ui` catalog）共 **690 个组件**，底层实现为 **726 个 `.vue` 实体**（含内部辅助组件）。

| 分类 | 数量 | 说明 |
|------|------|------|
| 图表（G2 + ECharts） | 55 | 折线、柱状、饼图、散点、雷达、仪表盘、面积、堆叠、环形、玫瑰、箱线、热力、瀑布、K线、漏斗、关系、桑基、词云、水球等 |
| 装饰 | 356 | 装饰线条/点/粒子/网格 + 照片资产类 + 写实/HUD 装饰 |
| 边框 | 60 | 科技风、装饰风、简约风、DataV 风格等 |
| 标题 | 40 | 翼展 / HUD / 流光 / 菱形等多种标题风格 |
| 3D 组件 | 39 | echarts-gl / CSS 3D（立方体、风车等） |
| 基础控件 | 31 | 文本、按钮、数字翻牌器、指标卡、排行榜、进度条、水波球、状态指示等 |
| 列表 | 18 | 基础列表、卡片列表、时间线、滚动列表、头像列表、统计卡片列表 |
| 天气 | 18 | 天气卡片、天气预报、空气质量、天气仪表盘等 |
| 时间 | 15 | 数字时钟、模拟时钟、日历、倒计时、世界时钟、翻牌时钟 |
| 媒体 | 15 | 图片、视频、音频、跑马灯、轮播、矩阵、回放、PTZ、告警列表 |
| 容器 | 13 | 基础容器、弹性容器、网格容器、标签容器、发光面板 |
| 表格 | 13 | 基础表格、高级表格、树形表格、可编辑表格、统计表格、排名表格 |
| 表单 | 7 | 输入框、选择器、单选、复选、开关、滑块、日期选择 |
| 地图 | 5 | 基础地图、散点、热力、飞线、轨迹回放（+ 下钻面包屑） |
| 数据源面板 | 5 | 数据源/数据集配置面板 |

> 另有 13 个设计器配置面板（ChartConfigPanel / DataSourceManagerPanel / InteractionManagerPanel / ThemeSettingPanel / VersionPanel / UndoHistoryPanel 等）与布局/通用基础设施组件。

### 内置模板（131 套）

- **43 套行业数据大屏**：智慧城市、企业运营、智能制造、工业 IoT、国防军工、农业/畜牧/林业/矿业、物流、电商促销、短视频/自媒体、安防监控、气象预警、网络安全、航天发射、深空探测、音乐数据、MES 生产、采购供应、智慧交通、电网、房地产、金融风控、用户增长、医疗器械、医药研发、IC 测试、政务、视频监控、音视频广播、交通视频监控、AI 智算、大模型服务、低空经济、数字乡村、海洋牧场、乐器产业等
- **88 套数字孪生场景**：现代都市中枢、深海算力母舰、极地冰盖监测、低轨星座管控、智慧港口集群、核电站运行监测、柔性产线智造、地下综合管廊、海上风电场群、高铁枢纽沙盘、火山地质监测、全球碳排放、水利大坝、光伏储能、江南水乡古镇、数智农场、量子实验室、体育场馆、船坞码头、会展中心、半导体晶圆厂、氢能工厂、抽水蓄能、深部采矿、燃煤电厂、生物医药、粮仓、LNG 接收站、海水淡化、聚变示范、深空站、月球基地、火星基地、轨道站、空间太阳能、太空电梯、eVTOL 枢纽、无人机枢纽、BCI 实验室、轨道工厂、漂浮城市等

### 数据源与绑定

`src/datasources/adapters/` 提供 **8 个数据源适配器**：

| 适配器 | 说明 |
|--------|------|
| `StaticAdapter` | JSON 静态数据 |
| `ApiAdapter` | REST API（GET/POST，可配置请求头与参数） |
| `WebSocketAdapter` | 实时数据推送 |
| `ExcelAdapter` | Excel 文件上传解析 |
| `CsvAdapter` | CSV 数据解析 |
| `DatabaseAdapter` | 通过后端代理查询 MySQL / PostgreSQL |
| `DatasetAdapter` | 数据集绑定 |
| `MockAdapter` | 本地 Mock 数据 |

### 分享与发布

- **生成分享链接**：支持设置密码、有效期、访问次数上限
- **iframe 嵌入**：提供嵌入代码，可设置宽高和边框
- **导出**：支持导出为 PNG 图片或 PDF
- **发布安全**：密码使用 `crypto.scryptSync` 哈希 + `timingSafeEqual` 防时序攻击，密码验证接口独立限流

## 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.5+ | 前端框架（Composition API） |
| Vite | 8.0+ | 构建工具 |
| **three.js** | **0.186+** | **数字孪生 3D 渲染引擎（WebGL2）** |
| Ant Design Vue | 4.2+ | UI 组件库 |
| ECharts | 5.5+ | 图表引擎（含 echarts-gl / echarts-wordcloud） |
| AntV (G2/G6/L7) | 5.x | 可视化引擎 |
| Leaflet | 1.9+ | 地图引擎（+ leaflet.heat） |
| Pinia | 3.0+ | 状态管理 |
| Vue Router | 4.4+ | 路由（Hash 模式） |
| Vue I18n | 9.14+ | 国际化 |
| GridStack | 12.6+ | 拖拽布局引擎 |
| GSAP | 3.14+ | 动画引擎 |
| driver.js | 1.7+ | 新手引导教程 |
| Axios | 1.14+ | HTTP 客户端 |
| html2canvas / jsPDF | - | 截图与 PDF 导出 |
| MSW | 2.14+ | 接口 Mock（开发环境） |
| Sass / Less | - | CSS 预处理器 |
| Express | 4.x | 后端服务（Node.js） |

## 快速开始

### 环境要求
- Node.js 18.0+
- npm 9.0+ / pnpm 9.0+（用于 SDK 包开发与 Monorepo）

### 安装与运行

```bash
# 安装依赖
npm install

# 开发模式（端口 5173）
npm run dev

# 构建生产版本
npm run build

# 预览生产构建（端口 5174）
npm run preview
```

> 数字孪生场景需要支持 WebGL2 的浏览器。首次进入 3D 场景会按需加载 GLB 资产，建议使用 Chrome / Edge 以获得最佳画质与性能。

### 后端服务（可选）

项目自带 Express 后端（`server/`），提供大屏持久化、数据库代理、发布与 AI 服务：

```bash
cd server
npm install
npm run dev    # 端口 3000，--watch 热重启
npm start
```

前端通过 `VITE_API_BASE_URL=/api` 访问后端。未部署后端时，可启用 MSW Mock（`VITE_ENABLE_MSW=true`）。

### SDK 包构建

项目使用 pnpm workspaces 管理 8 个可独立发布的 SDK 包。

```bash
pnpm install            # 安装所有工作区依赖
pnpm build:packages     # 构建全部 SDK 包
pnpm --filter @nbreak/ui build   # 构建单个包
pnpm --filter @nbreak-app/web dev  # 运行参考应用
pnpm test:run           # 运行测试
```

## 项目结构

```
data-screen/
├── public/
│   ├── maps/                   # 地图 GeoJSON（china.json + provinces/，运行时 fetch，不打进 JS chunk）
│   └── readme/                 # README 截图
├── server/                     # Express 后端服务
│   ├── routes/                 # dashboards / templates / publish / ai / components / db
│   ├── middleware/             # auth(API Key) / rateLimit / errorHandler
│   ├── utils/fileStorage.js    # 文件级持久化（文件锁 + 原子写入）
│   └── data/                   # 本地 JSON 存储（dashboards/publish/templates.json）
├── packages/ui/src/
│   ├── twin/                   # ★ 数字孪生引擎
│   │   ├── SceneKernel.js      # 渲染内核（渲染器/后处理/相机/光照）
│   │   ├── CameraRig.js        # 轨道相机与视角预设
│   │   ├── binding.js          # 数据绑定（scaleY/lift/heat）
│   │   ├── builders*.js        # 100+ 场景构建器（pack A~N + 地标/世界）
│   │   ├── landmarkGlb.js      # 地标 GLB 装配（Blender 实景资产）
│   │   ├── realismKit.js / matReal.js / matLib.js  # 实景增强与材质库
│   │   ├── sky.js / weather.js / shadowFit.js / waterReflect.js / groundReflect.js  # 大气/天气/阴影/反射
│   │   ├── measure.js / labels.js / tour.js / flyPath.js  # 量测/标注/巡览/巡航
│   │   ├── editModel.js / envOverrides.js  # 场景编辑与环境层覆写
│   │   └── assets/twin/        # 200+ GLB 实景资产（landmark / port / rail / city / ...）
│   ├── components/             # 726 个画布组件实体（P5 全量下沉）
│   │   ├── borders/            # 边框（60）
│   │   ├── decorations/        # 装饰（407，含照片资产）
│   │   ├── time/ controls/ lists/ media/ tables/ weather/ layout/ forms/ containers/  # 批次 3
│   │   ├── echarts/            # ECharts 图表（32）
│   │   ├── charts/             # G2 图表（43，含 ChartToolbar 辅助组件）
│   │   ├── three-d/            # 3D 组件（40，echarts-gl/CSS 3D）
│   │   ├── maps/               # Leaflet 地图组件（6，含 DrillDownBreadcrumb）
│   │   └── filters/            # 筛选组件（5，GlobalState 经 interactionBridge 桥接）
│   ├── composables/            # useChart / useFitScale / useMapDrillDown / useGlobalState
│   ├── utils/                  # 图表工具集群 + leafletSetup / geoData / interactionBridge
│   ├── categories/             # 16 个分类加载器（type → 异步组件映射）
│   ├── generated/catalog.js    # 690 条组件目录（由设计器单向同步生成）
│   └── registerBuiltinComponents.js  # 全量注册工厂（@nbreak/ui/builtin）
├── src/
│   ├── api/                    # 前端 API 请求模块
│   ├── components/             # 设计器组件（面板/画布/渲染器等宿主组件）
│   │   ├── panels/             # 配置面板（13）
│   │   ├── canvas/             # 画布工具（AlignToolbar/ContextMenu）
│   │   ├── common/             # 通用组件（ErrorBoundary/Skeleton/VirtualList）
│   │   ├── AIAssistantDialog.vue / BlueprintEditor.vue / CanvasDesigner.vue
│   │   └── ComponentRenderer.vue / LeftPanel.vue / HeaderToolbar.vue
│   ├── composables/            # 组合式函数（宿主侧，30+）
│   │   ├── useInteractions.js / useBlueprintNodes.js / useBlueprintConnections.js
│   │   ├── useAIAssistant.js / useUrlParamBindings.js / useCanvasDragDrop.js
│   │   ├── useLayerManager.js / useVersionManager.js / usePersistence.js / useGuideTour.js
│   ├── interactions/           # 交互联动引擎
│   │   ├── InteractionManager.js / LinkageEngine.js / DrillDown.js / blueprintExecutor.js
│   │   └── actions/            # 动作注册表（25+ 动作）
│   ├── datasources/            # 数据源适配器（8 个）
│   ├── i18n/                   # 国际化（zh-CN / en-US）
│   ├── mocks/                  # MSW 接口 Mock
│   ├── themes/                 # 主题（dark / light）
│   ├── data/
│   │   ├── builtinTemplates.js # 131 套模板入口（43 传统 + 88 孪生）
│   │   ├── templates/          # 各模板定义（含 digitalTwin/ 88 套孪生模板）
│   │   ├── componentLibrary.js # 组件库目录（690 条，同步到 @nbreak/ui）
│   │   └── componentSchemas.js # 组件 Schema 与默认值
│   ├── services/               # 业务服务（aiService / aiDesignService / exportService / templateService）
│   ├── store/modules/          # Pinia 状态管理（dashboardStore）
│   ├── styles/tokens/          # 全局样式与设计令牌（SCSS）
│   ├── views/                  # 页面视图（DashboardList / Designer / Preview / TemplateMarket / PublishManager）
│   ├── App.vue
│   └── main.js
├── scripts/blender/            # ★ Blender 程序化建模脚本（twin_landmark.py 等）
├── packages/                   # 可独立发布的 SDK 包（pnpm workspaces）
│   ├── shared/ core/ sdk/ runtime-loader/ vue/ themes/ datasources/ ui/
├── apps/web/                   # 参考应用 - 演示 SDK 集成方式
├── pnpm-workspace.yaml
├── vitest.config.js
├── vite.config.js
└── package.json
```

## 路由

| 路径 | 页面 | 说明 |
|------|------|------|
| `/` | - | 重定向到 `/dashboard-list` |
| `/dashboard-list` | DashboardList | 项目列表（首页） |
| `/designer` | Designer | 大屏设计器（`keepAlive`） |
| `/preview/:id?` | Preview | 预览大屏（id 可选） |
| `/share/:id` | Preview | 分享访问大屏 |
| `/template-market` | TemplateMarket | 模板市场 |
| `/publish-manager` | PublishManager | 发布管理 |

## 后端服务

`server/` 提供 Express 后端（默认端口 3000，CORS 指向 `http://localhost:5173`）：

| 路由前缀 | 模块 | 说明 |
|----------|------|------|
| `GET /api/health` | - | 健康检查（无需认证） |
| `/api/dashboards` | dashboards.js | 大屏 CRUD、列表搜索分页、详情、持久化 |
| `/api/templates` | templates.js | 模板列表与详情 |
| `/api/publish` | publish.js | 发布记录创建、分享 URL、密码校验（scrypt 哈希） |
| `/api/publish/:id/verify` | publish.js | 密码验证（独立限流 10 次/分钟） |
| `/api/ai` | aiService.js | AI 服务代理 |
| `/api/components` | componentMarket.js | 组件市场 |
| `/api/db` | database.js | 数据库代理查询（MySQL / PostgreSQL 只读 SQL） |

**中间件**：`auth.js`（API Key 认证，`x-api-key` ↔ `API_KEY`）、`rateLimit.js`（全局 60 次/分钟，密码验证 10 次/分钟）、`errorHandler.js`（统一错误处理与 404）。

**持久化**：`utils/fileStorage.js` 提供文件锁 + 原子写入的 JSON 存储（`server/data/*.json`）；数据库查询通过 `mysql2` / `pg` 连接池代理。

## 构建优化

Vite 构建按依赖体积与加载时机定制了 `manualChunks` 代码分割：

| Chunk | 包含内容 |
|-------|---------|
| `decorations-chunk` / `borders-chunk` / `three-d-chunk` | 应用侧装饰 / 边框 / 3D 组件合批评分（消除 900+ 个 <5KB 碎片文件，均懒加载） |
| `echarts-vendor` | echarts + zrender |
| `echarts-gl-vendor` | echarts-gl |
| `antd-vendor` | ant-design-vue + @ant-design/* |
| `antv-g2-vendor` / `antv-g6-vendor` / `antv-l7-vendor` / `antv-vendor` | @antv 图表 / 关系图 / 地图引擎 |
| `xlsx-vendor` / `gridstack-vendor` | Excel 解析 / 拖拽布局 |

`modulePreload` 会过滤 antv / echarts-gl 等深层大依赖，仅在对应图表组件渲染时按需加载，避免首屏多拉约 2.3MB。生产构建自动移除 `console` 和 `debugger` 语句，静态资源输出到 `dist/assets/`。支持 Cloudflare Pages 部署（`npm run deploy`）。

## 地图数据

中国地图 GeoJSON 已本地化到 `public/maps/china.json`（含 `public/maps/provinces/` 省级数据），打包后无需外网即可加载。加载优先级：本地文件 → 阿里云 DataV CDN → jsDelivr CDN。

## 浏览器支持

- Chrome（推荐，数字孪生场景需 WebGL2）
- Edge / Firefox / Safari

## 开发指南

### 新增组件

1. 在 `src/data/componentLibrary.js` 中注册组件元数据（`componentMetadata`），在 `src/data/componentSchemas.js` 中定义 Schema 与默认值
2. 运行 `npm run sync:extensions` 单向同步到 `packages/ui/src/generated/catalog.js`（CI 用 `sync:extensions:check` 校验）
3. 在 `packages/ui/src/components/<分类>/` 下创建 `.vue` 实体，并在 `packages/ui/src/categories/<分类>.js` 导出 type → 异步组件映射

### 新增模板

- **传统数据大屏**：在 `src/data/templates/` 下新建模板定义并 `export default`，在 `src/data/builtinTemplates.js` 中 import 并加入 `builtinTemplates` 数组；结构为 `{ id, name, canvasWidth, canvasHeight, screenSetting, pages: [{ id, name, components: [...] }] }`
- **数字孪生场景**：在 `src/data/templates/digitalTwin/` 用 `createTwinTemplate({...})` 定义模板（`builder` / `camera` / `metricSource` / `bindingProp` / `hotspots` 等），并在对应 `twinTemplatesPack*.js` 注册；同时在 `packages/ui/src/twin/builders*.js` 实现 builder（返回 `{ root, refs, update, dispose }`）

### 新增交互动作

1. 在 `src/interactions/actions/handlers.js` 中实现动作处理函数
2. 在 `schemas.js` 中定义动作参数 Schema
3. 在 `types.js` 的 `ACTION_TYPES` 中注册类型

### 主题定制

项目基于 CSS 变量的主题系统，内置 52 套主题（`packages/themes/src/themes/`），涵盖科技风（techcyan/techblue/techpurple）、商务风（biznavy/bizcrimson/bizgold）、节日风（springfestival/midautumn/christmas/halloween）、行业风（smartcity/medical/finance/cybersecurity）等。设计态可经 ThemeSettingPanel 实时切换。

## SDK 扩展系统

项目提供完整的 npm 可发布 SDK 包与扩展能力，采用 Monorepo 架构（pnpm workspaces），支持应用方按需引入内置扩展或自定义扩展。

### 包一览

| 包名 | 说明 | 体积（ESM） | peerDependencies |
|------|------|------------|-----------------|
| `@nbreak/shared` | 常量、类型、Schema 规范、manifest 校验、工具函数 | 15 KB | - |
| `@nbreak/core` | 扩展注册表、插件系统、事件总线 | 19 KB | - |
| `@nbreak/sdk` | `define*` 工厂函数、CLI 工具链、manifest 规范 | 9 KB | - |
| `@nbreak/runtime-loader` | 运行时动态加载（ESM / UMD / Module Federation） | 11 KB | - |
| `@nbreak/vue` | Vue 3 插件、属性字段编辑器注册表、SchemaForm 渲染器 | 19 KB | `vue: ^3.5.0` |
| `@nbreak/themes` | 52 套内置主题扩展 | 48 KB | - |
| `@nbreak/datasources` | 数据源适配器（static/api/websocket/excel/csv/database/dataset/mock） | 18 KB | `xlsx: ^0.18.5`（可选） |
| `@nbreak/ui` | 内置组件扩展；16 个分类子路径（726 个 .vue 实体）+ `@nbreak/ui/builtin` 全量注册工厂 + `@nbreak/ui/catalog`（690 条目录） | 44 MB（含照片/GeoJSON 类资产，es+cjs 双份） | `vue: ^3.5.0`, `echarts: ^5.5.0` + 重依赖（可选）peers |

### 包能力边界（重要）

packages 是**运行时内核 + 扩展机制**，设计器（`src/`）是**编辑器宿主**，两者定位不同。当前包能力与设计器完整能力基本对齐（P0~P5 架构演进已完成），差异仅在编辑器专属能力（拖拽画布、蓝图编排、场景编辑、版本管理、持久化等）留在宿主。

| 能力 | packages 内核 | 设计器（src/） | 复用状态 |
|------|--------------|---------------|---------|
| 组件实体 | 726 个 `.vue` 实体全部迁入 `@nbreak/ui`，经 16 个分类子路径导出 + `@nbreak/ui/builtin` 全量注册工厂 | 726 个 `.vue` 组件 | ✅ P5 批次 1-5 全部完成 |
| 组件目录/Schema | 690 条目录数据（`@nbreak/ui` catalog，含去重 `SCHEMA_BUNDLES`） | 同左（单一数据源） | ✅ 桥接同步 |
| 主题 | 52 套 | 52 套 | ✅ 单一数据源 |
| 数据源取数 | 7 种适配器（A 层） | B 层运行态壳 | ✅ 分层复用 |
| 扩展注册表 | ExtensionRegistry | ✅ 内置组件经注册桥注册为扩展，渲染查找 = 文件约定优先 + registry 兜底 | ✅ |
| 属性面板 | propertyFieldRegistry（14 种内置编辑器）+ SchemaForm 薄壳 | ✅ 面板控件迁为 property-field 注册制 | ✅ |
| 远程扩展加载 | runtime-loader | ✅ 清单中心合并（本地 + 远程 UMD 演示） | ✅ |
| 数字孪生渲染 | —— | `packages/ui/src/twin/`（SceneKernel + builders + GLB 资产） | 引擎随包，宿主提供页面壳 |

**防漂移机制**：设计器组件目录（`src/data/componentLibrary.js` + `componentSchemas.js`）通过 `npm run sync:extensions` 单向同步到 `packages/ui/src/generated/catalog.js`；CI 用 `npm run sync:extensions:check` 校验，不一致即失败。

### 6 种扩展类型

| 类型 | 说明 | define 工厂函数 |
|------|------|----------------|
| `component` | 组件扩展 | `defineComponentExtension` |
| `theme` | 主题扩展 | `defineThemeExtension` |
| `datasource` | 数据源扩展 | `defineDataSourceExtension` |
| `template` | 模板扩展 | `defineTemplateExtension` |
| `action` | 动作扩展 | `defineActionExtension` |
| `property-field` | 属性字段编辑器扩展 | `definePropertyFieldExtension` |

### 构建产物结构

每个包输出 ESM + CJS 双格式，分别位于 `dist/esm/` 和 `dist/cjs/`。带样式的包（`@nbreak/vue`、`@nbreak/ui`）CSS 文件随格式输出，通过 `exports["./styles.css"]` 引入。

### 安装与使用

#### 最小集成（Vue 项目推荐）

```bash
pnpm add @nbreak/vue @nbreak/themes @nbreak/datasources @nbreak/ui
```

```javascript
import { createApp } from 'vue';
import App from './App.vue';
import { setupDataScreen } from '@nbreak/vue';
import '@nbreak/ui/styles.css';
import '@nbreak/vue/styles.css';

const app = createApp(App);

// 方式 A（推荐）：一键全量注册 726 组件（catalog 元数据 + .vue 实体惰性加载）
await setupDataScreen(app, {
  builtin: { ui: true },
  autoRegisterComponents: true,
});

app.mount('#app');
```

#### 按需引入 / 纯核心 / 运行时动态加载

```javascript
// 按需：仅注册所需主题
import { setupDataScreen } from '@nbreak/vue';
import { techcyan, cyberpunk } from '@nbreak/themes';
await setupDataScreen(app, { extensions: [techcyan, cyberpunk] });

// 纯核心：只用注册表
import { extensionRegistry } from '@nbreak/core';
import { defineComponentExtension } from '@nbreak/sdk';
await extensionRegistry.register(defineComponentExtension({ /* ... */ }));

// 运行时动态加载
import { loadExtension } from '@nbreak/runtime-loader';
await extensionRegistry.register(await loadExtension('https://cdn.example.com/my-ext.js'));
```

#### 自定义扩展开发

```bash
pnpm add -D @nbreak/sdk
npx datascreen init component my-chart ./packages/my-chart
```

```javascript
import { defineComponentExtension } from '@nbreak/sdk';
import { extensionRegistry } from '@nbreak/core';
import MyChart from './MyChart.vue';

const myExt = defineComponentExtension({
  type: 'my-chart',
  name: '我的图表',
  category: 'charts',
  component: MyChart,
  schema: [
    { field: 'title', label: '标题', type: 'input', defaultValue: '' },
    { field: 'color', label: '颜色', type: 'color', defaultValue: '#1890ff' },
  ],
  defaults: { title: '', color: '#1890ff' },
  tags: ['自定义'],
});
await extensionRegistry.register(myExt);
```

### CLI 工具

```bash
npx datascreen init component my-chart     # 初始化扩展项目
npx datascreen init theme my-theme ./path  # 在指定路径生成
npx datascreen build                        # 构建扩展包
npx datascreen pack                         # 打包为 npm tarball
npx datascreen list                         # 列出当前项目的扩展
npx datascreen validate ./datascreen.extension.json  # 校验 manifest
```

### 发布到 npm

```bash
npm login
npm run publish -- --bump patch   # 版本自增 + 构建 + 按依赖拓扑顺序发布全部 8 个包
npm run publish                   # 已升过版本，直接构建 + 发布
npm run publish:only              # 跳过构建直接发布
npm run publish -- --dry-run      # 仅打包验证，不上传
```

`publish.sh` 自动检查 pnpm 与 npm 登录状态，按拓扑顺序发布：
`shared` → `core` → `sdk` → `runtime-loader` → `themes` → `datasources` → `ui` → `vue`，单包失败不影响其余包。

### 参考应用

`apps/web` 提供完整的集成示例（主题切换、组件预览、数据源测试、注册表快照）。

```bash
cd apps/web && pnpm install && pnpm dev   # 端口 5299
```

## 许可证与授权

本项目为**商业软件**，著作权归 NBreak 所有。本作品以"源码可见"方式发布，**不是开源软件**，
默认协议为 [LICENSE](LICENSE)（Data Screen 源码许可协议，学习研究专用）。

### 允许（免费）

- 阅读、下载、克隆源码，学习实现原理与架构设计
- 在本地编译运行，用于个人学习、技术研究与功能评估
- 出于学习目的的本地修改与实验（不得发布或部署）
- 非营利教学、技术分享、学术研究中引用少量代码片段并注明来源

### 禁止（须购买授权）

- **商业使用**：商业产品、SaaS、客户交付、外包/集成项目，及任何直接或间接获利行为
- **生产部署**：部署到生产环境、对外提供访问或服务（无论是否收费）
- **企业内部使用**：用于业务运营、流程支撑等非学习用途
- **再分发**：出售、出租、转授，或上传至 npm、代码托管平台、镜像站、网盘等渠道
- **规避权利管理**：删除版权信息/水印，或反向工程、绕过授权校验

### 授权模式

| 模式 | 说明 | 适用场景 |
|------|------|---------|
| **单项目授权** | 限定 1 个项目、1 个部署域名，禁止修改核心代码 | 小型企业单次需求 |
| **企业年度授权** | 限定项目数量和域名数量，含技术支持 | 中型企业持续使用 |
| **永久买断授权** | 不限项目数量和域名，含完整源码和长期支持 | 大型企业/集成商 |

商业授权类型、范围与限制详见 [LICENSE-COMMERCIAL](LICENSE-COMMERCIAL)。

### 授权条款要点

- 源代码知识产权归原作者所有，客户仅获得使用权
- 禁止转售、再分发、公开托管源代码
- 禁止反向工程、反编译核心授权验证逻辑
- 禁止将授权转让给第三方（关联公司需另行授权）
- 违约方需承担违约金及赔偿损失，并承担权利人的维权合理支出

### 技术保护措施

交付版本内置以下技术保护：

- **代码水印**：每个客户版本嵌入唯一标识，泄露可追溯源头
- **域名绑定**：应用启动时校验部署域名是否在授权列表中
- **代码混淆**：生产构建启用代码混淆，增加逆向成本
- **核心逻辑服务端化**（可选）：关键数据处理部署在授权方服务器，无后端无法独立运行

### ⚠️ 法律风险提示

未经授权超范围使用本作品，可能承担以下责任：

- **民事责任**：依据《中华人民共和国著作权法》，权利人可要求停止侵害、消除影响、
  赔礼道歉、赔偿损失；故意侵权且情节严重的，可适用惩罚性赔偿
- **行政责任**：侵权行为损害公共利益的，可被责令停止侵权、没收违法所得并处罚款
- **刑事责任**：以营利为目的、未经许可复制发行，情节严重者可能构成
  《刑法》第二百一十七条侵犯著作权罪
- **违约责任**：违反许可协议须承担违约责任，并赔偿律师费、公证费、取证费、诉讼费等维权支出

以上为风险提示，具体责任以生效法律文书及有权机关的认定为准，不构成法律意见。

### 获取授权

如需商用授权，请邮件联系并签署《软件源代码许可协议》（必要时签署 NDA）。
未签署书面协议前，不构成任何授权。

## 联系方式

- 作者：NBreak
- 邮箱：nbreak@126.com