SmartEDT/系统开发技术方案.md

# 智能电动汽车数字孪生系统开发技术方案（V1）
智能电动车数字孪生系统软件通过集成高精度数据采集、实时同步控制、三维虚拟仿真、智能算法验证与系统运维管理等功能，构建了一个覆盖教学、科研与产业应用的智能电动汽车虚实融合实验平台。它不仅能实现真实驾驶环境的沉浸式再现与数据级同步，还能为科研人员提供精准可追溯的数据支持、灵活的算法验证接口和可扩展的数据分析工具，充分满足智能电动汽车领域对实验真实性、可靠性与创新性的高标准要求，推动智能驾驶与数字孪生技术的深度融合与发展。
本文基于《智能电动车数字孪生系统功能规划（2026）》的目标，给出一套可落地的软件开发技术方案。Unity 三维驾驶仿真作为独立工程（独立代码库与发布包），通过标准接口与本系统对接。


## 1. 建设目标与原则

### 1.1 建设目标
- 实现多源设备数据采集、统一管理与实时可视化展示
- 构建“实体车—数字孪生体”数据交互：状态同步、数据采集、事件回放
- 支撑多场景驾驶仿真联动（Unity 独立运行），实现同屏/多屏展示与协同操作
- 实现实验管理与记录：仿真记录创建、过程记录、视频录制、数据持久化、历史回放
- 本地化部署与数据安全：本地存储、最小暴露接口、路径越界防护

### 1.2 设计原则
- 分层解耦：设备接入、业务编排、数据服务、可视化展示相互独立
- 实时优先：以事件/流式数据驱动为核心（WebSocket + HTTP）
- 可扩展：设备类型、消息类型、算法模块、Unity 场景可插拔扩展
- 可运维：统一配置、日志、诊断接口、打包发布与自动启动链路

## 2. 总体架构

### 2.1 架构分解
系统由三类可独立发布、独立升级的可执行程序组成：

1) **后端数据与控制服务（Python EXE）**
- 负责设备采集、数据处理、仿真记录管理、持久化、文件存储、对外 API
- 对前端提供 HTTP REST + WebSocket（实时推送）
- 对 Unity 提供联动接口（可选双向：状态推送/指令下发）

2) **桌面端可视化应用（Electron + Vue EXE）**
- 负责 UI 展示、实验流程操作、多屏组织、外部程序（后端/Unity）启动与守护
- 作为“应用入口”，统一呈现与统一运维

3) **车辆驾驶仿真（Unity EXE，外部项目）**
- 负责 3D 场景、动力学/视觉化仿真、互动控制
- 与后端通过约定协议交换数据（HTTP/WebSocket/本地端口均可）

### 2.2 数据流与控制流
- **采集流**：设备/传感器 → 设备接入层 → 统一事件总线 → 处理/校准 → 入库/落盘 → WebSocket 推送
- **控制流**：前端操作 → REST 指令 → 业务编排 → 下发到设备/控制柜，或同步给 Unity
- **回放流**：历史仿真记录 → 查询元数据（数据库）→ 拉取文件（静态映射）→ 前端播放/曲线回放，或驱动 Unity 回放

### 2.3 系统两大部分划分
系统整体可分为两大部分（对应团队分工与发布包边界）：

1) **数据采集与处理（后端）**
- 采集：方向盘/踏板/档位/手刹/车速轮速/灯光/电参/温度等
- 处理：滤波、校准、融合、异常检测、指标计算
- 管理：仿真记录、文件、数据库、权限（可选）
- 服务：REST + WebSocket + 静态文件映射

2) **界面显示与交互（Electron + Vue）**
- 显示大屏：系统介绍、仿真监控、数据看板
- 车载屏（驾驶员）：驾驶视角信息与仪表盘
- 控制屏：场景配置、系统配置、用户/权限、数据查询、数据分析

### 2.4 推荐工程目录结构（本仓库）
建议把“后端服务”和“前端桌面端”放在同一仓库便于协同开发；Unity 工程保持外部独立仓库，仅提交接口文档与发布包获取方式。

```
SmartEDT/
  backend/                 # Python：采集/处理/管理/API
    device/                # 传感器设备接入与驱动（方向盘/踏板/灯光/电参等）
    database/              # 数据存储（PostgreSQL/TimescaleDB）与数据访问层
    config/                # 配置（ini/环境变量）与配置加载
    main.py                # 后端入口（启动 API/WS、初始化各模块）
    utils.py               # 通用工具（时间/路径/校验/日志等）
  frontend/                # Electron + Vue：桌面端与多屏展示
    src/                   # Vue 渲染进程（页面/组件/路由）
    main/                  # Electron 主进程（多窗口、多屏、拉起后端/Unity）
    (配置文件)             # package.json / vite.config.* / electron-builder 配置等
  docs/                    # 方案、接口协议、运维文档
  data/                    # 默认数据目录（开发态可用）
  release/                 # 可选：打包产物临时输出目录（不提交版本库）
```

## 3. 技术选型与理由

### 3.1 后端（Python）
- **语言**：Python 3.13.1（配合硬件 SDK、算法生态与快速迭代）
- **Web 框架**：FastAPI（异步友好、类型约束清晰、OpenAPI 自动生成）
- **实时通讯**：WebSocket（FastAPI 原生或 Starlette WebSocket），用于状态/传感数据/事件推送
- **进程内并发**：asyncio + 线程池/进程池（适配阻塞型硬件 SDK）
- **持久化**：PostgreSQL18 + TimescaleDB（用于实时采集数据的时序存储）+ SQLAlchemy（ORM/迁移支持）
- **文件存储**：本地文件系统（与数据库元数据关联）
- **打包**：PyInstaller 打包为独立 EXE；开发环境使用 venv 隔离依赖


### 3.2 前端（Electron + Vue）
- **UI 框架**：Vue 3 + Vite（开发体验与生态成熟）
- **桌面封装**：Electron（多窗口、多屏支持、可管理外部进程）
- **本地通信**：HTTP + WebSocket 访问后端；可选 IPC（主进程与渲染进程）
- **打包**：electron-builder 产出 Windows EXE 安装包/绿色包

### 3.3 Unity（外部）
- **三维仿真**：Unity（高效构建交互式驾驶场景与渲染）
- **对接方式**：建议 WebSocket（低延迟实时同步）+ HTTP（配置、仿真记录、资源拉取）
- **进程管理**：由 Electron 主进程统一拉起与关闭（可在指定显示器全屏）

## 4. 后端模块设计（Python）

### 4.1 模块划分
- **配置中心（Config）**
  - 统一读取 `config.ini`（就近优先原则：后端目录优先，其次项目根目录）
  - 管理文件根目录、数据库路径、端口、日志等级等
- **设备接入层（Adapters/Drivers）**
  - 每类设备一个管理器：相机、IMU、压力/力传感、控制柜等
  - 统一生命周期：init/connect/start/stop/disconnect
  - 统一数据模型：采集原始数据 + 时间戳 + 设备元信息
- **设备协调器（Coordinator）**
  - 负责多设备协同启动/停止、状态聚合、异常重连策略
  - 对上提供“仿真记录级操作”，对下调度各设备管理器
- **数据处理层（Pipeline）**
  - 校准/滤波/坐标变换/融合（按需求插拔）
  - 统一输出“标准事件”，写入事件总线与持久化队列
- **仿真实验管理（Simulation Experiment）**
  - 流程：场景配置 → 仿真启动 → 仿真执行 → 仿真结束
- **数据存储（Storage）**
  - 元数据：PostgreSQL（仿真记录、设备、事件索引、文件索引）
  - 实时采集数据：TimescaleDB Hypertable（高频写入、按时间范围查询与聚合）
  - 典型能力：按时间分区、压缩、保留策略、连续聚合（按需要启用）
  - 大文件：视频、原始采样、导出报告等存本地文件系统
- **录制与归档（Recording/Archiving）**
  - 仿真过程视频录制：显示大屏/车载屏/Unity 画面按需求录制（目标帧率 30fps）
  - 录制任务与仿真记录绑定：开始/停止随仿真流程联动，支持异常中止与补偿关闭
  - 文件索引入库：形成可回放、可导出的统一入口
- **对外服务（API）**
  - REST：健康检查、设备管理、仿真记录控制、数据查询、导出
  - WebSocket：实时推送（状态、传感数据、告警、进度）
- **静态文件映射（File Gateway）**
  - 按配置的根目录对外只读映射
  - 路径规范化、拒绝越界（拦截 `..`、绝对路径、UNC 路径）

### 4.2 采集数据范围与精度（本期基线）
本系统“采集与处理”侧的基线采集字段如下（用于实时显示、联动仿真与历史回放）；后续可按车型/传感器扩展。

- **转向与踏板**
  - 方向盘转角：左/右（单位建议：deg）
  - 刹车踏板行程：mm
  - 电门踏板行程：mm
- **车辆状态**
  - 挡位：P / N / D / S
  - 手刹状态（手状态）：0 / 1
  - 车速：单位建议 km/h
  - 车轮转速：单位建议 rpm（按轮位可扩展为 FL/FR/RL/RR）
- **灯光状态**
  - 左转向灯 / 右转向灯
  - 双闪
  - 刹车灯
- **电池与电参**
  - 电池剩余电量：%
  - 电压：测量误差 0.1V
  - 电流：测量误差 0.1A
  - 温度：测量误差 0.5℃

采集来源建议按两类接入：
- **传感器/控制柜直采**：方向盘、踏板、档位、手刹、车速/轮速、电参等（串口/CAN/以太网，取决于硬件）
- **视觉识别采集（可选）**：当部分状态仅存在于仪表或屏幕显示时，用相机 + 识别推断（需标注数据与容错策略）


### 4.3 API 设计建议（摘要）
- `GET /health`：健康检查（版本、时间、依赖状态）
- `GET /api/devices`：设备列表与状态
- `POST /api/simulation/start`：创建并启动一次三维仿真记录（返回 simulation_id）
- `POST /api/simulation/{simulation_id}/stop`：结束一次三维仿真并落盘
- `GET /api/simulation/{simulation_id}`：三维仿真记录元数据
- `GET /api/simulation/{simulation_id}/events`：事件/曲线数据查询（分页/时间窗）
- `GET /files/<path>`：静态文件访问映射（对标 README 的安全校验策略）
- `WS /ws`：统一实时通道（按 topic/room 订阅）

### 4.4 实时消息模型（建议）
采用统一 JSON Envelope，便于前端与 Unity 复用：

```json
{
  "type": "vehicle.signal",
  "ts": 1737000000.123,
  "simulation_id": "SIM202601160001",
  "device_id": "controlbox_01",
  "seq": 1024,
  "payload": {
    "steering_wheel_angle_deg": 12.3,
    "brake_pedal_travel_mm": 5.2,
    "throttle_pedal_travel_mm": 18.0,
    "gear": "D",
    "handbrake": 0,
    "vehicle_speed_kmh": 36.5,
    "wheel_speed_rpm": { "FL": 320, "FR": 319, "RL": 318, "RR": 318 },
    "lights": { "left_turn": 0, "right_turn": 1, "hazard": 0, "brake": 0 },
    "soc_percent": 78.2,
    "voltage_v": 356.4,
    "current_a": 12.7,
    "temperature_c": 28.5
  }
}
```

建议补充字段：
- `source`：device/backend/unity
- `quality`：丢包/校准状态/信噪比等
- `schema_version`：前后端与 Unity 协同升级

### 4.5 目录与文件存储规范（建议）
与 README 的建议一致，采用“根目录 + 仿真记录分层”的稳定结构：

```
<root>/
  <subject_id>/
    <simulation_id>/
      meta.json
      video/
      signals/
      exports/
```

文件根目录通过 `[FILEPATH].path` 配置；当配置为相对路径时，开发环境相对后端工作目录，打包环境相对后端 EXE 同级目录（对标 README 的路径策略）。

存储类型建议（与规划大纲一致）：
- 传感器原始数据：生成数据文件（如 `signals/raw_*.dat`），按时间段或按设备分文件落盘
- 传感器/识别后的结构化数据：实时写入 PostgreSQL/TimescaleDB（用于查询、统计、回放曲线）
- 仿真记录视频：按窗口/视角分别落入 `video/`，并在数据库中建立索引与标签（视角、分辨率、帧率等）

### 4.6 TimescaleDB 时序数据建模建议
为支持“高频写入 + 按时间范围回放/聚合”，建议将采集数据按时序表落库，并在 TimescaleDB 中转换为 Hypertable。

推荐思路：
- 一张时序主表：按 `ts` 做 Hypertable 分区
- 以 `simulation_id` 作为业务主维度，支持一次三维仿真记录的时间窗查询与回放

字段建议（可按性能需要做列化/半结构化折中）：
- `ts`：时间戳（TimescaleDB 分区键）
- `simulation_id`：三维仿真记录 ID（用于回放与归档）
- `device_id`：数据来源设备
- `signals`：结构化信号（可选 JSONB，或将高频字段拆为列以提升聚合效率）

典型策略（按需启用）：
- 保留策略：只保留近 N 天原始点，长期保留用压缩或降采样结果
- 连续聚合：生成 1s/100ms 粒度的统计序列用于大屏曲线与回放加速

## 5. 前端模块设计（Electron + Vue）

### 5.1 界面体系（显示大屏 / 车载屏 / 控制屏）
界面显示功能分为三类屏幕（与规划大纲一致），由 Electron 统一创建窗口并在指定显示器呈现，Vue 负责页面实现。

1) **显示大屏（面向展示/观摩）**
- **系统介绍**
  - 系统功能介绍：图文并茂；可扩展语音播报与 AI 问答导览
  - 车辆三维展示：外观/内饰动态展示；关键部件结构展示（转向机构、驱动机构等）
  - 系统原理展示：动力/转向/制动/灯光等子系统工作原理可视化
- **数据看板**
  - 数据主屏：中间为车辆三维动态模型；周边展示车辆概况、车辆参数（示例：秦 Plus）、历次仿真记录、设备监控（CPU/内存）、模拟报警信息
  - 仿真回放屏：对单次仿真结果回放；三维仿真回放 + 采集数据动态图表回放；进度显示（总时长/当前进度）
- **仿真监控**
  - 视角切换：主视角 / 驾驶员视角
  - 主视角：路线图（动态）+ 车辆尾随视角
  - 驾驶员视角：三维场景动态 + 仪表盘（车速、转速、档位、手刹、车灯、电量等）
  - 仿真视频录制：动态录制仿真视频过程屏幕（目标 30fps），并与仿真记录绑定

2) **车载屏（驾驶员视角）**
- 仿真界面：三维仿真场景；天气与时段显示；车速显示；仿真状态标识（等待/仿真中/结束）
- 数据记录：后台记录仿真过程记录，并动态录制车载屏仿真屏幕（目标 30fps）

3) **控制屏（操作与管理）**
- 场景配置
  - 仿真场景：城市道路/高速公路/山区道路/乡村道路/校园道路
  - 气象：晴/雨/雪/雾等；时段：黎明/正午/黄昏/夜间
  - 车辆颜色：红/白/黑；最高限速：100–180 km/h
  - 仿真时长：5–60 分钟；驾驶员选择：人员/账号绑定
  - 车辆传感器校正：自检/校正
  - 场景推送：下发到车载屏与显示大屏
- 仿真控制：开始仿真 / 结束仿真
- 系统配置：功能介绍（文字）、端口与路径等基础配置入口
- 用户配置：角色与权限配置；用户与角色选择
- 数据查询：系统日志查询；仿真记录查询
- 数据分析：车辆数据分析、故障模拟诊断、CAN 总线数据模拟解析

### 5.2 与后端的通信
- REST：用于仿真记录控制、配置读写、历史查询、导出触发
- WebSocket：订阅实时 topic（设备状态、采样数据、告警、录制进度）
- 静态文件：通过后端安全映射路径访问视频与大文件（支持 Range）

### 5.3 前端路由与窗口映射（建议）
为便于多屏稳定运行，建议把“窗口类型”与“路由入口”固化：
- 显示大屏
  - `/big/system-intro`
  - `/big/dashboard`
  - `/big/sim-monitor`
- 车载屏
  - `/car/sim`
- 控制屏
  - `/control/config`
  - `/control/operate`
  - `/control/query`
  - `/control/analysis`
  - `/control/admin`

### 5.4 外部进程启动与守护（Electron 主进程）
主进程负责统一拉起与管理：
- 后端 EXE：启动时分配端口（固定端口或自动探测），轮询 `/health` 确认就绪
- Unity EXE：按用户选择显示器启动（命令行传参：端口、simulation_id、模式等）
- 异常策略：崩溃检测、重启次数限制、日志采集、用户提示

推荐机制：
- 端口管理：优先读配置，冲突时自动寻找可用端口并回写运行态配置
- 生命周期：Electron 退出时优雅关闭后端与 Unity（超时后强制）

## 6. Unity 联动方案（外部项目对接约定）

### 6.1 对接目标
- 实时同步实体车/传感器状态到 Unity（姿态、速度、踏板、方向、报警等）
- Unity 交互事件回传（场景切换、碰撞事件、驾驶行为、训练步骤等）
- 支持“实时模式”和“回放模式”

### 6.2 建议协议
建议使用同一套消息 Envelope：
- **WebSocket（实时）**：订阅 `vehicle.signal`、`control.command` 等；Unity 回传 `unity.event.*`
- **HTTP（控制/查询）**：加载仿真记录、读取配置、拉取资源、触发导出

### 6.3 同步与时钟策略
- 后端为权威时间源（服务端时间戳），Unity 按 `ts` 对齐插值
- 允许 Unity 维护环形缓冲（例如 100–300ms）平衡抖动与延迟

## 7. 配置与环境管理

### 7.1 venv 管理与依赖
- 开发环境：`python -m venv venv`，使用 `requirements.txt` 固定依赖版本
- 构建环境：单独 `requirements_build.txt`（包含 PyInstaller 等打包依赖）

### 7.2 配置文件（INI）
建议统一使用以下段落（可按需扩展）：

```ini
[SERVER]
host = 0.0.0.0
port = 5000

[FILEPATH]
path = data

[DATABASE]
url = postgresql+psycopg://smartedt:CHANGE_ME@127.0.0.1:5432/smartedt
timescaledb = True
```

## 8. 打包发布与部署

### 8.1 后端打包（PyInstaller）
产物目标：
- `Backend.exe`（单文件或目录模式）
- `config.ini`（可外置，便于现场修改）
- `data/`（默认数据目录，可按配置指向其他盘符）

建议输出：
- 内置 OpenAPI 文档（仅本机或受限网络可访问）
- 日志写入到 `logs/`（按日期切分）

### 8.2 前端打包（Electron）
产物目标：
- `SmartEDT.exe`（安装包/绿色包）
- `resources/backend/Backend.exe`（随包携带或首次运行下载）
- 统一版本号与升级策略（可选增量更新）

### 8.3 一键启动链路
1. 启动 `SmartEDT.exe`
2. Electron 主进程读取配置并拉起 `Backend.exe`
3. 后端健康检查通过后，渲染进程连接 REST/WS
4. 用户选择“仿真模式”时，拉起 Unity EXE 并注入运行参数

## 9. 多屏显示方案

### 9.1 目标
- 控制屏在主屏（操作与管理入口）
- 显示大屏在副屏/大屏（系统介绍 / 数据看板 / 仿真监控）
- 车载屏在驾驶员屏（或指定小屏）
- Unity 全屏运行在指定显示器（可与显示大屏分离）

### 9.2 Electron 实现要点
- 启动时枚举显示器，建立“显示器—窗口类型”映射
- 针对不同显示器创建多个 BrowserWindow（固定 URL/路由）
- 提供“显示器管理”设置页：拖拽绑定、保存配置、开机恢复
- Unity 启动参数附带目标显示器索引（或由 Unity 自行选择）

建议的窗口类型：
- BigScreenWindow：显示大屏（可切换 system-intro/dashboard/sim-monitor）
- CarScreenWindow：车载屏（驾驶员视角）
- ControlWindow：控制屏（配置、控制、查询、分析、管理）

## 10. 安全、可靠性与合规

### 10.1 本地数据安全
- 默认仅本机访问（可通过配置开放局域网）
- 静态文件映射做路径规范化与越界拦截（对标 README 的安全策略）
- 敏感字段脱敏显示（subject_id 映射/匿名化）

### 10.2 稳定性策略
- 设备断连：自动重连、指数退避、状态广播
- 写盘保护：异步队列 + 批量提交；异常时保证仿真记录可关闭并可恢复
- 资源管理：视频录制与采样队列限速，避免磁盘/CPU 被打满

## 11. 日志、诊断与监控
- 分级日志：设备/仿真记录/API/存储
- 诊断接口：`/health` 返回依赖与核心子系统状态（设备数量、队列长度等）
- 现场排障：一键导出日志与仿真记录元数据（不含隐私或做脱敏）

## 12. 测试与质量保证
- 单元测试：消息模型、路径安全、数据库 CRUD、仿真流程状态机
- 集成测试：模拟设备数据源（Mock Adapter），验证 WS 推送与落盘
- 性能测试：高频 IMU、视频录制并发、长时仿真稳定性（内存/磁盘增长）

## 13. 交付物清单（建议）
- 后端：可执行程序、配置模板、API 文档、设备接入开发规范
- 前端：桌面 EXE、显示器管理、实验流程 UI、日志导出
- 对接：Unity 通讯协议文档（topic/消息体/端口/参数）、联调用例
- 运维：安装说明、目录与数据管理说明、故障排查手册