root aa4b14181c chore: 初始化项目并添加 .gitignore

2026-01-19 14:27:41 +08:00

20 KiB

Raw Blame History

智能电动汽车数字孪生系统开发技术方案（V1）

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

1. 建设目标与原则

1.1 建设目标

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

1.2 设计原则

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

2. 总体架构

2.1 架构分解

系统由三类可独立发布、独立升级的可执行程序组成：

后端数据与控制服务（Python EXE）

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

桌面端可视化应用（Electron + Vue EXE）

负责 UI 展示、实验流程操作、多屏组织、外部程序（后端/Unity）启动与守护
作为“应用入口”，统一呈现与统一运维

车辆驾驶仿真（Unity EXE，外部项目）

负责 3D 场景、动力学/视觉化仿真、互动控制
与后端通过约定协议交换数据（HTTP/WebSocket/本地端口均可）

2.2 数据流与控制流

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

2.3 系统两大部分划分

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

数据采集与处理（后端）

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

界面显示与交互（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 复用：

{
  "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 负责页面实现。

显示大屏（面向展示/观摩）

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

车载屏（驾驶员视角）

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

控制屏（操作与管理）

场景配置
- 仿真场景：城市道路/高速公路/山区道路/乡村道路/校园道路
- 气象：晴/雨/雪/雾等；时段：黎明/正午/黄昏/夜间
- 车辆颜色：红/白/黑；最高限速：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）

建议统一使用以下段落（可按需扩展）：

[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）