# bigscreen

**Repository Path**: bisicloud_farm/bigscreen

## Basic Information

- **Project Name**: bigscreen
- **Description**: 智慧农业六屏大屏项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: codex/video-patrol-field-groups
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智慧农业平台监控中心 / Smart Agriculture Big Screen

面向智慧农业基地的**六屏指挥中心**：2D 一张图 / 实时监测看板 / 告警与事件中心 / 指挥与控制台 / 专题大屏 / 集成与接口。

> **产品定位、视觉规范**详见 [`PRODUCT.md`](./PRODUCT.md) 与 [`DESIGN.md`](./DESIGN.md)。

## 技术栈

| 维度 | 选型 |
|---|---|
| 构建 | Vite 5 + TypeScript 5.5 strict |
| 框架 | Vue 3.4 (Composition API) + Vue Router 4 |
| 状态 | Pinia + `@vueuse/core` |
| 接口缓存 | `@tanstack/vue-query` |
| 数据契约 | Zod |
| 样式 | Tailwind CSS 3 + CSS Variables (DESIGN.md token) |
| 大屏装饰 | `@kjgl77/datav-vue3` + 自研装饰原语 + Inspira UI（M1 引入） |
| 图表 | ECharts 5 + vue-echarts |
| 动画 | GSAP + `@number-flow/vue` |
| 实时 | reconnecting-websocket（M0 仅 Mock） |
| 错误监控 | `@sentry/vue` |
| 三维舞台 | TresJS + three-mesh-bvh（**M1 引入**） |
| 视频上墙 | mpegts.js + 分级播放（**M2 引入**） |
| Lint/Format | Biome |
| 测试 | Vitest + @testing-library/vue + Playwright |
| 部署 | Docker + Nginx |

## 里程碑路线

```
M0 ✅  工程底座：主题 + 六屏导航壳 + Mock 管道 + Docker + CI
M1 ⏳  3D 舞台（TresJS）+ 摄像头单体化拾取（占位模型）
M2 ⏳  视频上墙 PoC + 分级播放（mpegts.js + ZLMediaKit）
M3 ⏳  六屏完整 + 真模型替换 + Sentry/生产部署
```

### M0 完成状态

- ✅ Vite + Vue 3.4 + TypeScript strict 工程基线
- ✅ 主题 token（CSS Variables 锁定 DESIGN.md 薄荷绿）
- ✅ 1920×1080 自适应壳（零依赖 `useScaleContainer`）
- ✅ 六屏注册表驱动的路由与底部 Tab 导航
- ✅ Zod 契约 + Mock 快照 + 实时事件流（订阅/取消 API 与 WS 一致）
- ✅ Pinia store 分层（ui-store / runtime-store）
- ✅ 自研装饰原语（PanelFrame / PanelTitle / MetricCard）+ datav-vue3 BorderBox 薄壳
- ✅ Sentry / 全局错误兜底 / 404 屏
- ✅ Vitest 17 个核心契约测试全过
- ✅ 多阶段 Dockerfile + Nginx 配置 + docker-compose
- ✅ GitHub Actions CI（typecheck/lint/test/build + 可选 docker build）

### 当前截图入口

六个一级入口均使用本地演示数据，可直接打开并截图；控制动作只更新页面状态，不触达真实设备。

| 功能 | 路由 |
|---|---|
| 2D 一张图 | `/screen/one-map` |
| 实时监测看板 | `/screen/real-time-monitoring` |
| 告警与事件中心 | `/screen/event-center` |
| 指挥与控制台 | `/screen/command-console` |
| 专题大屏 | `/screen/topic-board` |
| 集成与接口 | `/screen/integrations` |
- ✅ Biome 全量 lint 零错误，vue-tsc strict 零错误

## 快速开始

```bash
# 1. 安装依赖
pnpm install

# 2. 复制环境变量
cp .env.example .env

# 3. 启动开发
pnpm dev

# 4. 类型 + Lint + 测试 + 构建
pnpm typecheck
pnpm lint
pnpm test
pnpm build
```

## Docker

```bash
docker build -t big-screen:latest .
docker run --rm -p 8080:80 big-screen:latest
# 浏览器打开 http://127.0.0.1:8080
```

## 目录结构（M0）

```
src/
├─ app/                # 应用入口与全局 Provider
├─ config/             # 主题 token、六屏注册表、相机预设（M1）
├─ types/              # Zod schemas + TS 类型
├─ stores/             # Pinia: runtime / ui / stage
├─ services/
│  ├─ mock/            # 静态快照 + 实时流模拟
│  ├─ adapters/        # 后端字段 → 屏内 ViewModel
│  └─ ws/              # (M3) 真实 WS 网关
├─ composables/        # 通用 Vue Composition (useScaleContainer 等)
├─ components/
│  ├─ layout/          # ScaleContainer、TopHeader
│  ├─ widgets/         # PanelFrame、MetricCard、装饰原语
│  └─ screens/         # ScreenShell
├─ screens/            # 六屏：overview / twin / iot / ai-alert / farming / analytics
├─ stage/              # (M1) 三维舞台
├─ video/              # (M2) 视频播放
└─ styles/             # 全局样式 + token
```

## 设计原则

- **态势优先**：大屏不承载后台表单。
- **农业真实感先行**：科技感来自灯光与图层，不是赛博覆盖。
- **舞台连续性**：六屏共享 StageRoot，切屏跑相机预设。
- **CSS-first**：装饰用 SVG/CSS 构造，避免大量整图直铺。
- **数据契约**：UI 只订阅 Pinia store，所有网络细节在 services 层封装。

## 贡献规范

- Commit 必须中文，描述「做了什么 + 为什么」。
- 所有 PR 必须通过 `pnpm typecheck`、`pnpm lint`、`pnpm test`、`pnpm build` 四个 CI 关卡。
- 不在主分支直接 push；Demo 阶段除外。

## 参考

- 实时数据契约：[`docs/realtime/data-contracts.md`](./docs/realtime/data-contracts.md)
- 舞台架构：[`docs/realtime/stage-architecture.md`](./docs/realtime/stage-architecture.md)
- 动画原则：[`docs/realtime/animation-principles.md`](./docs/realtime/animation-principles.md)
- 视觉规则：[`docs/realtime/visual-rules.md`](./docs/realtime/visual-rules.md)