# tes

**Repository Path**: zd_g/tes

## Basic Information

- **Project Name**: tes
- **Description**: 通用型遥测数据仿真平台，基于 Java 21 + Spring Boot 3.3、React 18 + TypeScript 前后端分离技术栈：从仿真造数、协议编解码、实时推送，到外部系统对接、3D 轨道可视化、虚拟卫星整星仿真与开发者调试，覆盖完整链路。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-30
- **Last Updated**: 2026-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 遥测, 数据仿真, 协议编码解码, 轨道, 虚拟卫星整星仿真

## README

# 遥测数据生成仿真系统

<p align="center"><img src="frontend/public/logo.png" alt="遥测数据生成仿真系统" width="96" /></p>

<p align="center">数据生成 · 协议编解码 · 实时推送 · 3D 可视化 · 虚拟卫星 · AI 助手 · 调试工具</p>

通用型遥测数据仿真平台，基于 Java 21 + Spring Boot 3.3、React 18 + TypeScript 前后端分离技术栈：从仿真造数、协议编解码、实时推送，到外部系统对接、3D 轨道可视化、虚拟卫星整星仿真与开发者调试，覆盖完整链路。

## 一、界面预览

> 📷 以下为各页面截图占位，截图统一存放于 `docs/images/` 目录。


| 页面         | 截图位置                           | 页面内容                                                                                                     |
| ------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| 控制台       | ![控制台](img/01-dashboard.png)    | 链路状态横幅、系统运行指标卡、数据统计（最新/最大/最小/均值）、实时时序曲线 / 数值分布直方图 / 值-变化率散点 |
| 虚拟卫星     | ![虚拟卫星](img/02-vsat.png)       | 整星大屏（测点磁贴 + quality 色带 + sparkline）、事件流、6 个任务场景时间线、轨道绑定、分发与历史回放面板    |
| 数据仿真生成 | ![数据仿真](img/03-generate.png)   | 六种生成模式参数表单（含脚本编辑器 / 模板 / 试运行）、实时数据预览、接收速率统计、Webhook 与导出             |
| 协议配置     | ![协议配置](img/04-protocol.png)   | 协议 CRUD 表单与 JSON / HEX / 二进制编解码调试                                                               |
| 3D 场景      | ![3d场景](img/05-simulation3d.png) | Orekit 轨道 3D 渲染（动态卫星 + 星下点地面轨迹）、地面轨迹经纬度图、设备拓扑                                 |
| AI 助手      | ![ai](img/ai-1.png)                | 模型对话面板与八大场景化能力入口                                                                             |
| 调试工具     | ![测试](img/test.png)`             | 报文调试、编解码、参数快照、导入导出与历史回放                                                               |

## 二、系统架构

前后端分离 + 分层架构：前端 SPA 经 **REST 与 SSE 双通道**接入后端；后端以统一参数契约（`GenerateBaseDTO`）支撑**四条取数通路**（SSE 实时推送 / REST 批量拉取 / 文件导出 / Webhook 转发），并叠加**虚拟卫星独立域**（`/api/vsat/**`）：

![架构图](./img/tesspec.png)

```mermaid
flowchart LR
    subgraph FE["前端 SPA · React 18 + TypeScript · Ant Design · Zustand · ECharts / three.js"]
        PAGES["7 大页面<br/>控制台 · 虚拟卫星 · 数据仿真生成<br/>协议配置 · 3D 场景 · AI 助手 · 调试工具"]
    end

    subgraph BE["后端 · Spring Boot 3.3 · Java 21"]
        API["Controller API 层<br/>simulation / sse / protocol / codec / orbit / ai / debug / open<br/>vsat：stream · replay · history · profile · scenario · client · dataset"]
        SVC["Service 层<br/>推送循环 · 取数导出 · 协议脚本 · 卫星编排"]
        GEN["数据生成引擎<br/>6 种模式 + Rhino 脚本"]
        ORB["Orekit 轨道计算<br/>采样 · 地面轨迹 · 光照"]
        CODEC["协议编解码<br/>JSON / HEX / Binary"]
        VENG["虚拟卫星引擎<br/>物理联动 · 帧流 · 场景 · 回放 · 分发"]
        AIF["AI 客户端工厂<br/>DeepSeek / 百炼 / 通用"]
        HOOK["Webhook 转发<br/>有界队列 · 尽力投递"]
        MAPPER["持久层 · MyBatis-Flex"]
        API --> SVC
        SVC --> GEN & ORB & CODEC & VENG & AIF & HOOK
        SVC --> MAPPER
    end

    DB[("PostgreSQL<br/>协议 / 快照 / 遥测记录 / 档案 / 测点<br/>TLE / 场景 / 留存段 / 帧 / 分发客户端")]
    EXT["外部业务系统<br/>批量拉取 · 文件导出 · Webhook 接收"]
    TLE["TLE 数据源<br/>CelesTrak · space-track · KeepTrack"]
    DIST["外部分发客户端<br/>X-API-Token · scopes"]
    AIP["外部 AI 服务<br/>DeepSeek / 百炼"]

    PAGES <-->|"REST /api/** ↔ SSE 事件流"| API
    EXT -->|"batch / export"| API
    GEN -->|"orbit 模式联动"| ORB
    MAPPER --> DB
    VENG -->|"TLE 绑定 · 降级链"| TLE
    VENG -->|"整星帧流 / 回放"| DIST
    AIF -->|"OpenAI 兼容调用"| AIP
    HOOK -->|"逐条 POST"| EXT

    classDef fe fill:#e0f2fe,stroke:#0284c7,stroke-width:1.5px,color:#0c4a6e
    classDef be fill:#ecfdf5,stroke:#059669,stroke-width:1.5px,color:#064e3b
    classDef eng fill:#fefce8,stroke:#ca8a04,stroke-width:1.5px,color:#713f12
    classDef ext fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#581c87
    classDef db fill:#fff1f2,stroke:#e11d48,stroke-width:1.5px,color:#881337

    class PAGES fe
    class API,SVC,MAPPER be
    class GEN,ORB,CODEC,VENG,AIF,HOOK eng
    class EXT,TLE,DIST,AIP ext
    class DB db
```

> Mermaid 图在 GitHub / Gitee 等平台自动渲染；分层细节、扩展点与安全设计见 。

设计要点：

- **一套引擎、四条通路**：所有取数入口共用 `DataGenerator` 接口与工厂，生成器无需感知数据从哪条通路取出；
- **推送可靠性**：SSE 断线且未配 Webhook 时自动停止任务；Webhook 走有界队列尽力投递（队满丢弃并计数，不阻塞生成主链路）；
- **鉴权分层**：开放接口可选 `X-API-Token`；虚拟卫星分发放发 token（SHA-256 哈希存储），按「卫星 × 接口」scopes 限权；
- **独立域设计**：虚拟卫星以独立包 + 独立路由叠加，不复用、不侵入原有遥测数据通路。

## 三、核心功能

### 1. 数据生成（六种模式）

- `random` 随机 / `fixed` 固定 / `wave` 周期波 / `anomaly` 异常注入 / `orbit` 轨道联动（Orekit 实时推演）/ `script` 脚本生成
- 完整参数：格式（json/hex/binary）、频率、精度、波动幅度、周期、上报时长、轨道六根数
- **script 模式**：基于 Rhino 1.7.15（纯 Java JavaScript 引擎）
  - 内置 6 套脚本模板：正弦波动 / 指数衰减 / 方波阶跃 / 高斯噪声 / 随机脉冲 / 多字段对象
  - 可用变量 `tick / seconds / baseValue / waveOffset / anomalyRate / period`，内置函数 `rand / randRange / randInt / gauss / clamp`
  - `return` 数值或 `{value, field, unit}` 对象（自定义字段名与单位）
  - 启动前自动校验（语法错误提示行号）、前端「试运行」样例预览、死循环超时自动中断、运行期异常限流回退基线值不断流
  - 脚本已禁用 Java 类访问，仅保留受限函数

### 2. 协议编解码

- 全协议编解码器：JSON / HEX / 二进制(Base64) + 统一工厂（可扩展注册）
- 编解码调试接口与前端表单双向验证：结构化数据 ⇄ 报文

### 3. 实时推送与连接治理（SSE）

- 心跳定时广播、注释帧握手（注册后立即 flush 响应头）
- 连接监控 `/api/sse/status`、推送统计、任务治理（防重复启动 / 断线自动停止）
- 前端会话为模块级单例：切页不断流，含断线重连

### 4. 外部取数与转发

- 开放接口：批量拉取 `POST /api/open/data/batch`（≤10000 条）、文件导出 `POST /api/open/data/export`（CSV/JSONL，≤100000 条流式下载）
- Webhook 实时转发：默认内置演示接收端（自环验证），可替换为任意 http/https 外部地址
- 数据通路支持 `X-API-Token` 可选鉴权

### 5. 轨道与 3D 可视化

- Orekit 轨道周期采样、星下点地面轨迹（GTOD 近似地固系）
- 3D 场景：动态卫星 + 轨道线 + 星下点贴地轨迹，配套地面轨迹经纬度图与设备拓扑链路图
- 后端基于 Orekit 12.1.1 + Hipparchus 3.1（版本严格匹配，见「版本与依赖说明」）

### 6. AI 助手（八大场景化能力）

数据纠错 / 异常模拟 / 数据补全 / 趋势分析 / 场景生成 / 协议解析 / 报错诊断 / 参数优化。

- 多 AI 统一接口 + 工厂：DeepSeek / 阿里百炼 / 通用 OpenAI 兼容服务
- 默认关闭（`telemetry.ai.enable=false`），配置密钥后在 dev/prod 环境开启

### 7. 虚拟卫星数据服务（叠加式独立域 `/api/vsat/**`）

- **档案与字典**：卫星档案（profiles）与字段字典（JSON/CSV 导出）
- **物理联动引擎**：9+1 测点模型、光照判定双模式（precise 精确 / simple 简化），SSE 整星帧流（`vsat.frame` 事件，支持 rate/record/scenario 参数）
- **任务场景**：6 个内置场景（相位故事线），场景时间线切换
- **真实 TLE 绑定**：CelesTrak / space-track / KeepTrack 多源绑定与降级链，轨道切换联动
- **历史与回放**：历史帧留存 / 分页查询 / 测点时序 / 导出，SSE 回放（同构实时，支持 from/to/speed/loop/seek 与按事件跳转）
- **分发**：分发客户端 token 创建与用量统计（数据通路鉴权）
- **整星大屏前端**：测点磁贴 + quality 色带 + sparkline、事件流、接入信息（SSE 地址 / 字段字典 / 三框架示例代码）

### 8. 调试工具

- 报文调试、参数快照（保存/列表/详情/删除）、批量导入导出、历史回放

## 四、技术栈总览


| 端   | 技术栈                                                                                                                                                                       |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 后端 | Java 21 · Spring Boot 3.3 · MyBatis-Flex · PostgreSQL · SSE · Webhook 转发 · Orekit 12.1.1 · Hutool · Rhino 1.7.15 · springdoc OpenAPI · DeepSeek/阿里百炼/通用 AI |
| 前端 | React 18 + TypeScript · Vite 5 · Ant Design 6.6.5 · Zustand · react-force-graph-3d · @react-three/fiber · echarts-for-react                                            |

## 五、项目结构

```
tse/
├── backend/                        # 后端工程（Maven）
└── frontend/                       # 前端工程（Vite）
```

### 后端 backend（分层结构）

```
backend/
├── pom.xml                         # 依赖管理（Java21/MyBatis-Flex/Orekit/Rhino/Hutool/PostgreSQL）
├── src/main/resources/
│   ├── application.yml             # 全局配置（含 spring.profiles.active）
│   ├── application-dev.yml         # 开发环境（含 AI 密钥占位）
│   ├── application-test.yml        # 测试环境
│   ├── application-prod.yml        # 生产环境（密钥走环境变量）
│   ├── db/schema.sql               # 建表 SQL
│   ├── mapper/                     # MyBatis-Flex XML（可选）
│   ├── orekit-data/                # Orekit 数据目录（随包携带 tai-utc.dat）
│   └── vsat/profiles/              # 虚拟卫星档案定义
└── src/main/java/com/telemetry/sim/
    ├── TelemetrySimApplication.java  # 启动类
    ├── common/                       # 通用：result / exception / constant / enums
    ├── config/                       # 配置：Web/CORS、Orekit、AI 客户端、全局
    ├── controller/                   # 控制层：protocol/sse/simulation/ai/orbit/open/debug/vsat
    ├── service/ + impl/              # 服务层：协议、SSE 推送
    ├── mapper/                       # 持久层（MyBatis-Flex BaseMapper）
    ├── entity/                       # 模型层（表实体）
    ├── model/dto + vo                # 数据传输对象 / 视图对象
    ├── sse/                          # SSE 连接管理器
    ├── orekit/                       # 轨道仿真统一封装（采样/地面轨迹/光照）
    ├── ai/                           # 多 AI 统一接口 + DeepSeek/百炼/通用 + 工厂
    ├── protocol/ parser + encoder    # 协议解析 / 编码（可扩展）
    ├── generator/data/               # 数据生成器（接口 + 工厂 + 六种模式）
    ├── vsat/                         # 虚拟卫星域（profile/physics/frame/history/distribute/orbitsource）
    ├── webhook/                      # Webhook 转发与内置接收端
    └── util/                         # Hutool 统一封装入口
```

### 前端 frontend（Vite 工程）

```
frontend/
├── package.json / vite.config.ts / tsconfig.json / index.html
├── public/          # 品牌资源（logo.png / favicon.svg）
├── .env.development / .env.production
└── src/
    ├── main.tsx / App.tsx / vite-env.d.ts
    ├── api/           # HTTP 封装 + 协议/仿真/AI/虚拟卫星接口
    ├── router/        # 路由（控制台/虚拟卫星/数据仿真生成/协议配置/3D 场景/AI 助手/调试工具）
    ├── store/         # Zustand 状态模块（simulation / ai / vsat）
    ├── sse/           # SSE 客户端（单值流 + 整星帧流，均含断线重连）
    ├── types/         # TS 类型定义（simulation / orbit / vsat）
    ├── hooks/ utils/  # 自定义钩子与工具
    ├── components/    # common/charts/three/force-graph/protocol/ai/vsat 组件
    ├── pages/         # 7 大业务页面
    └── styles/        # 全局样式
```

## 六、环境要求

- **后端**：JDK 21、Maven 3.9+、PostgreSQL（默认库名 `telemetry_sim`）
- **前端**：Node.js 18+、npm/pnpm

## 七、快速启动

### 后端

```bash
# 1. 创建数据库
psql -U postgres -c "CREATE DATABASE telemetry_sim;"

# 2. 初始化表结构（协议配置 / 调试快照 / 遥测记录）
psql -U postgres -d telemetry_sim -f src/main/resources/db/schema.sql

# 3. 按需修改 application-dev.yml 中的数据库账号密码

# 4. 启动（默认端口 8080）
cd backend
mvn spring-boot:run
```

### 前端

```bash
cd frontend
npm install
npm run dev        # 默认 http://localhost:5173，/api 已代理到后端 8080
```

## 八、接口文档索引

- 在线接口文档（Swagger UI）：`http://localhost:8080/swagger-ui.html`（OpenAPI JSON：`/v3/api-docs`；分组 `default` / `open-api`；生产环境默认关闭）

## 九、核心接口一览


| 模块     | 方法与路径                              | 说明                                                    |
| -------- | --------------------------------------- | ------------------------------------------------------- |
| 协议     | POST`/api/protocol`                     | 新增协议配置                                            |
| 协议     | GET`/api/protocol/page`                 | 分页查询                                                |
| 协议     | GET`/api/protocol/codec/formats`        | 已注册编解码格式                                        |
| 协议     | POST`/api/protocol/codec/encode`        | 编码：结构化数据 → 报文（json/hex/binary）             |
| 协议     | POST`/api/protocol/codec/decode`        | 解码：报文 → 结构化数据                                |
| SSE      | GET`/api/sse/connect/{clientId}`        | 建立 SSE 连接（EventSource）                            |
| SSE      | GET`/api/sse/status`                    | 连接监控与推送统计                                      |
| 仿真     | POST`/api/simulation/start`             | 启动推送（可携带 webhookUrl 实时转发外部系统）          |
| 仿真     | POST`/api/simulation/stop/{clientId}`   | 停止推送                                                |
| 仿真     | GET`/api/simulation/script/templates`   | 内置脚本模板列表（script 模式）                         |
| 仿真     | POST`/api/simulation/script/validate`   | 脚本校验与试运行（返回样例数据）                        |
| 轨道     | GET`/api/orbit/position`                | Orekit 轨道位置计算                                     |
| 轨道     | GET`/api/orbit/sample`                  | 轨道周期采样（3D 轨迹点）                               |
| 轨道     | GET`/api/orbit/groundtrack`             | 地面轨迹（星下点经纬度）                                |
| AI       | GET`/api/ai/models`                     | 可用模型列表                                            |
| AI       | POST`/api/ai/chat`                      | 模型对话                                                |
| AI       | GET`/api/ai/scenarios`                  | 场景化能力列表（八大场景）                              |
| AI       | POST`/api/ai/scenario`                  | 场景化能力执行                                          |
| 调试     | POST`/api/debug/snapshot`               | 保存参数快照                                            |
| 调试     | GET`/api/debug/snapshot/list`           | 快照列表                                                |
| 调试     | GET/DELETE`/api/debug/snapshot/{id}`    | 快照详情 / 删除                                         |
| 开放     | POST`/api/open/data/batch`              | 外部系统批量取数（≤10000 条，X-API-Token 可选鉴权）    |
| 开放     | POST`/api/open/data/export`             | 文件导出 CSV / JSONL（≤100000 条，流式下载）           |
| 开放     | GET`/api/open/data/webhook/status`      | Webhook 转发运行统计                                    |
| 虚拟卫星 | GET`/api/vsat/stream/{profile}`         | SSE 整星帧流（`vsat.frame` 事件；rate/record/scenario） |
| 虚拟卫星 | GET`/api/vsat/replay/{profile}`         | SSE 历史回放（与实时同构；from/to/speed/loop/seek）     |
| 虚拟卫星 | GET`/api/vsat/profiles`                 | 卫星档案列表（`/{code}/dictionary` 字段字典 JSON/CSV）  |
| 虚拟卫星 | GET`/api/vsat/history/{profile}/frames` | 历史帧分页（另有`points` 测点时序与 `export` 导出）     |
| 虚拟卫星 | POST`/api/vsat/clients`                 | 分发客户端 token 创建（数据通路 X-API-Token 鉴权）      |

## 十、多环境与配置

通过 `spring.profiles.active`（application.yml）或启动参数切换：

```bash
mvn spring-boot:run -Dspring-boot.run.profiles=dev   # / test / prod
```

生产环境数据库与 AI 密钥通过环境变量注入（`DB_HOST/DB_USERNAME/DB_PASSWORD/DEEPSEEK_API_KEY` 等），配置完全隔离。

## 十一、版本与依赖说明

- 依赖版本集中于后端 `pom.xml` `<properties>` 与前端 `package.json`，便于统一升级。
- Orekit 与 Hipparchus 版本需严格匹配：Orekit `12.1.1` 对应 Hipparchus `3.1`（见 `pom.xml` 的 `hipparchus.version`）。
- 内置脚本生成基于 Rhino（纯 Java JavaScript 引擎），版本见 `pom.xml` 的 `rhino.version`（`1.7.15`）；脚本已禁用 Java 类访问并带执行超时保护。
- Ant Design 按需求文档指定为 `6.6.5`；若该版本在私有仓库不可用时，可调整回 5.x 稳定版（需同步适配 API）。
- Orekit 数据目录解析优先级：环境变量 `OREKIT_DATA_DIR` → 配置项 `telemetry.orekit.data-dir` → classpath 内置 `src/main/resources/orekit-data/`（已随包携带 `tai-utc.dat` 闰秒文件，满足 UTC 时标 / EME2000 传播 / GTOD 简化星下点计算）→ 工作目录相对路径回退；目录缺失时应用仍可启动，仅 `/api/orbit` 轨道接口不可用。如需 EOP、JPL 星历等高级数据，可从 `https://gitlab.orekit.org/orekit/orekit-data` 获取后放入该目录或通过前两种方式指定外部目录。
- AI 能力默认关闭（`telemetry.ai.enable=false`），配置密钥后于 dev/prod 环境开启。