Initial screen starter scaffold

This commit is contained in:
zhougf committed 2026-05-29 00:26:43 +08:00
commit d136b9dddc
49 files changed
+2966

No files matched your search

+74
View File
@@ -0,0 +1,74 @@
# 大屏项目交付流程
## 1. 接需求
确认内容:
- 屏幕尺寸和播放设备。
- 是否 1920x1080、4K、拼接屏或特殊比例。
- 页面数量。
- 指标定义。
- 数据接口来源。
- 刷新频率。
- 是否需要实时推送。
- 是否需要离线展示。
- 客户视觉参考。
## 2. 新建项目
```bash
pnpm new customer-a 客户A运营大屏
pnpm install
pnpm --filter @dev-screen-starter/customer-a dev
```
## 3. 实现页面
推荐顺序:
1. 先定设计稿尺寸和布局。
2. 写静态页面。
3. 接 mock 数据。
4. 接真实接口。
5. 做不同屏幕适配验证。
6. 做截图验收。
## 4. 数据接入
低频数据:
- HTTP + `usePollingData`
中频数据:
- SSE 或 WebSocket
高频数据:
- 项目单独实现实时通道,不放进 starter 的默认能力。
## 5. 验收
检查项:
- 目标屏幕比例下没有裁切错误。
- 4K 或客户实际设备下文字清晰。
- 图表 resize 正常。
- loading、empty、error 状态可接受。
- 接口断开时页面不崩溃。
- 浏览器全屏展示正常。
- 构建产物可以独立部署。
## 6. 部署
推荐:
- `pnpm --filter <project> build`
- 将 `dist/` 部署到 Nginx 或客户静态服务。
- 数据接口通过环境变量配置。
后续可以补充:
- Dockerfile
- Nginx config
- CI 构建脚本
+144
View File
@@ -0,0 +1,144 @@
# 项目框架说明
## 1. 框架原则
Dev Screen Starter 只复用基础能力,不复用完整业务页面。每个客户大屏都应该是明确的代码实现,而不是通用 JSON 配置渲染。
框架关注:
- 屏幕适配
- 图表生命周期
- 数据刷新
- 调试体验
- 项目模板
- 部署约定
业务项目关注:
- 客户视觉风格
- 页面布局
- 指标定义
- 图表配置
- 数据接口
- 动效和交互
## 2. screen-core
`screen-core` 提供大屏运行的基础组件。
### ScreenStage
职责:
- 固定设计稿尺寸,默认 `1920x1080`。
- 根据浏览器窗口自动缩放。
- 支持 `fit`、`fill`、`stretch`、`none`。
使用方式:
```tsx
<ScreenStage background="#061826">
<YourScreen />
</ScreenStage>
```
### Panel
用于常规图表面板或信息区域。
### MetricCard
用于指标展示。项目中可以直接使用,也可以复制后按客户视觉重写。
## 3. charts
`charts` 提供 ECharts 基础封装。
### EChart
职责:
- 初始化 ECharts 实例。
- 监听容器尺寸变化并自动 resize。
- 支持 loading 状态。
- 组件卸载时自动 dispose。
### withChartDefaults
提供基础 tooltip、grid、文字风格配置。项目里可以按客户视觉覆盖。
### 图表工厂
图表工厂只生成 ECharts option,不限制项目继续覆盖配置。
当前提供:
- `createLineOption`:折线图,支持单序列和多序列。
- `createBarOption`:柱状图,支持单序列和多序列。
- `createRankBarOption`:横向排名条。
- `createPieOption`:饼图/环图。
- `createGaugeOption`:仪表盘。
- `createRadarOption`:雷达图。
推荐用法:
```tsx
<EChart
option={createLineOption({
categories: ['08:00', '10:00', '12:00'],
values: [120, 240, 380],
name: '订单'
})}
/>
```
## 4. data
`data` 提供轻量数据工具。
### requestJson
封装基础 JSON 请求。
### usePollingData
用于定时刷新接口数据。
适合:
- 30 秒刷新指标。
- 5 秒刷新告警。
- 项目开发时接 mock loader。
不适合:
- 高频毫秒级数据。
- 大规模实时流。
这些场景建议按项目单独实现 WebSocket、SSE 或 MQTT。
## 5. debug
`debug` 提供开发时调试组件。
### DebugBadge
显示缩放比例、数据更新时间等轻量信息。生产环境默认不显示,项目可显式打开。
## 6. 项目模板
`templates/project-basic` 是新客户项目起点。
创建命令:
```bash
pnpm new customer-a 客户A运营大屏
```
生成:
```txt
apps/customer-a/
```
然后开发人员在该目录内自由实现客户页面。
+109
View File
@@ -0,0 +1,109 @@
# Dev Screen Starter 项目计划
## 1. 项目目标
Dev Screen Starter 不做拖拽式大屏设计器,而是提供一套项目型大屏开发基础框架。每次接到客户项目时,开发人员基于模板新建项目页面,根据客户需求定制布局、图表、数据接口和视觉风格。
核心目标:
- 5 分钟创建一个新客户大屏项目。
- 复用屏幕适配、图表容器、数据刷新、调试工具和部署骨架。
- 保持每个项目的代码自由度,避免被低代码配置体系限制。
- 让客户只看到高质量运行页,不接触编辑器。
## 2. 不做什么
- 不做拖拽编辑器。
- 不做组件市场。
- 不做配置化属性面板。
- 不做客户自助搭屏。
- 不做通用低代码平台。
## 3. 技术路线
基础技术栈:
- React
- TypeScript
- Vite
- ECharts
- pnpm workspace
推荐部署方式:
- 静态构建产物部署到 Nginx、对象存储或客户服务器。
- 数据接口由客户系统、轻量代理服务或项目后端提供。
- 高频实时数据按项目需要接 WebSocket、SSE 或 MQTT。
## 4. 项目结构
```txt
apps/
demo-screen/ 示例大屏项目
packages/
screen-core/ 屏幕适配、舞台、基础面板、指标卡
charts/ ECharts 容器和通用图表默认配置
data/ 请求、轮询、mock、数据转换
debug/ 开发调试浮层
templates/
project-basic/ 新客户项目模板
scripts/
create-project.mjs 新建项目脚本
doc/
project-plan.md
framework.md
delivery-workflow.md
```
## 5. 第一阶段
目标:建立可复用基础框架和示例大屏。
交付内容:
- `ScreenStage`:负责设计稿尺寸和屏幕适配。
- `Panel`:常规大屏面板容器。
- `MetricCard`:常见指标卡。
- `EChart`:ECharts 自动初始化、销毁和 resize。
- `usePollingData`:基础轮询数据 hook。
- `DebugBadge`:开发环境调试浮层。
- `demo-screen`:示例大屏项目。
- `project-basic`:新客户项目模板。
- `pnpm new <name> [title]`:新建项目命令。
## 6. 第二阶段
目标:提升项目交付效率。
计划内容:
- 增加 `ChartPanel` 组合组件。
- 增加常用图表 option 工厂:
- 折线图
- 柱状图
- 饼图
- 排名列表
- 增加 mock/real 数据切换约定。
- 增加 `.env` 示例。
- 增加 Dockerfile 和 Nginx 静态部署模板。
## 7. 第三阶段
目标:沉淀项目经验和可复制交付流程。
计划内容:
- 建立客户项目目录规范。
- 建立视觉主题模板。
- 建立数据接口适配规范。
- 建立截图验收清单。
- 建立大屏上线检查清单。
## 8. 成功标准
- 新项目能通过模板快速创建。
- 示例大屏可运行、可构建。
- 1920x1080 设计稿能适配不同屏幕。
- 图表容器能自动 resize。
- 项目开发时能清楚看到调试信息。
- 每个客户项目可以自由写代码,不受设计器配置限制。