# simulation

**Repository Path**: zou-lei-11/simulation

## Basic Information

- **Project Name**: simulation
- **Description**: simulation
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 电力设备仿真平台（Power Simulator）

面向 SCADA / 微电网监控系统开发与测试的能源设备仿真平台。模拟新能源设备（电表、光伏逆变器、气象站）运行，生成高真实度数据，经 **Modbus TCP** 对外提供 slave 服务，供 SCADA / 网关 / 数据采集系统对接联调与回归测试。

同一站点的气象站、逆变器、各类负荷仪表数据因果一致——随真实日照、温度、作息联动，云遮挡时发电同步下跌。配套通讯中断注入、业务告警、时间加速、工况剧本等"仿真真实"能力，覆盖接入联调与告警 / 断线回归等核心场景。

## 功能特性

### 设备联动与环境仿真
- **站点（Station）**：一个园区挂多台设备，共享同一份环境
- **环境枢纽**：经纬度 + 季节 → 真实太阳位置算法算日照；天气基调（晴 / 多云 / 阴 / 雨）+ 云事件叠加；环境温度日变化
- **发电联动**：气象站与逆变器共享日照，云遮挡同步下跌（因果一致）；逆变器出力含面板温度退效率
- **负荷联动**：仪表按真实用电设备行为曲线运行——充电桩（时间表自动插拔 + CC-CV）、空调（随环境温度）、照明（作息通断）、厨房（三餐高峰）、办公（工作日曲线）
- **时间加速**：全局仿真时钟，1× ~ 300× 倍速快进（电能按仿真步长 simDt 正确累加）
- **确定性**：环境云事件 / 设备噪声按场景级种子可复现，便于回归测试

### 协议转发（Modbus TCP slave）
- 转发器作为 Modbus TCP slave 监听，SCADA 直连读寄存器
- **块读感知**：正确处理 `FC03 addr qty` 块读；uint32 / float32 点位（占 2 寄存器）地址正确步进，空洞返回 Exception 02
- 寄存器编解码：uint16 / int16 / uint32 / int32 / float32 × ABCD / CDAB / BADC / DCBA 字节序
- **控制下行**：SCADA 写寄存器 → 解码 → 控制设备（remote_ctrl 关机、active_set 功率钳位等），Web 与 Modbus 统一汇入
- 三层映射架构（设备点位 → 转发器 → 映射地址）+ 可视化寄存器地址图（导出 PNG / CSV）

### 仿真真实（差异化能力）
- **通讯中断 / 数据坏质量注入**：设备级 / 转发器级一键注入"通讯断"——Modbus 读返回异常码 0x04、监控页置灰、WS 值冻结；恢复无跳变。供 SCADA 测断线告警 / 画面置灰 / 补采恢复
- **业务告警事件流**：独立的离散事件链——状态翻转（运行 / 故障 / 待机）、功率越限（**超限功率指令**：主站下发 `active_set` 限功率后注入 `limit_fail` 失效 → 出力突破指令触发 warning，解除失效恢复 info；满发无指令不告警）、通讯中断发生-恢复；WS 实时推 `alarm` 帧 + 全局铃铛 + 告警抽屉（critical / warning / info 分级）
- **时间戳对齐**：数据时间戳 = 仿真时钟 simNow（快进时历史曲线时间轴正确）；Modbus 保留段 `0xFFF0~0xFFF2` 暴露 [时, 分, 倍速×100]

### 运维与交付
- **实时监控台**：系统概览（设备 / 转发器运行数、站点数、仿真时刻、WS 连接数）+ 转发器实时值抽屉 + 全站设备卡片
- **累计量持久化**：日 / 总发电量重启不归零，跨日清零，优雅关闭全量落盘
- **配置整包导入导出**：站点 + 设备 + 映射 + 转发器 + 环境 + 工况一键打包（JSON），备份 / 迁移 / 演示，空库完整恢复
- **工况剧本录制回放**：录一段操作时序（环境旋钮 + 故障注入 + 控制下发）→ 可编辑时间线 → 重放，供 SCADA 回归测试
- **在线型号编辑**：厂家型号点表 YAML 可在线编辑，保存即时热加载生效
- **单文件部署**：前端构建产物经 `go:embed` 内嵌进 exe，Gin 直接托管 SPA——目标机器只需 exe + 配置文件，运行后访问 `http://localhost:8080` 即完整界面
- **注册码授权**：机器绑定 + RSA 签名离线授权，私有部署防任意拷贝

## 技术栈

### 后端
- **语言**：Go 1.25
- **Web 框架**：Gin
- **ORM / 数据库**：GORM + SQLite
- **Modbus**：`simonvetter/modbus`（slave）
- **WebSocket**：`gorilla/websocket`
- **日志**：zap + lumberjack（滚动）

### 前端
- **框架**：Vue 3.5
- **构建**：Vite 8
- **UI**：Element Plus 2.14 + Element Plus Icons
- **状态**：Pinia 3
- **路由**：vue-router 4
- **HTTP**：axios

## 快速开始

### 环境要求
- Go 1.25+
- Node.js 18+

### 开发模式（前后端分离）
```bash
# 后端（项目根目录）
go run main.go                              # 默认读 config/config.yaml，监听 :8080
go run main.go -c path/to/config.yaml       # 指定配置

# 前端（另一个终端）
cd web
npm install
npm run dev                                 # :5173，自动代理 /api → :8080
```
浏览器打开 `http://localhost:5173`。

### 生产构建（单文件部署）
```bash
cd web && npm run build       # 先产出 web/dist
cd .. && go build .           # 再把 web/dist 内嵌进 exe
```
得到的 exe 内含完整前端，目标机器上只需 exe + `config/config.yaml`，运行后访问 `http://localhost:8080` 即完整界面。

## 配置说明

配置文件 `config/config.yaml`：

```yaml
server:
  port: 8080
  debug: true                 # 开发期开 CORS

database:
  path: data/sim2.db

simulator:
  tick_seconds: 1             # 仿真步长（秒）
  smoothing: 0.1              # 平滑过渡系数（0~1）

websocket:
  throttle_ms: 500            # WS 推送聚合节流

log:
  level: info
  file: data/logs/app.log
```

## SCADA 接入须知

| 项 | 说明 |
|---|---|
| 数据时间戳 | 仿真时钟 simNow（快进时正确） |
| Modbus 保留段 | `0xFFF0`=时、`0xFFF1`=分、`0xFFF2`=倍速×100（只读，地址表避开） |
| 块读 | `FC03 addr qty` 支持块读，uint32 / float32 占 2 寄存器，空洞返 Exception 02 |
| 通讯中断 | 中断设备读返回异常码 0x04（从站故障），供测断线告警 |
| 控制下行 | 写寄存器解码后控制设备（remote_ctrl / active_set 等） |

## 主要 API

统一响应 `{ code, message, data }`，`code=0` 成功。

- **设备**：`/api/devices`（CRUD + `/:uuid/start|stop|interrupt`）
- **转发器**：`/api/forwarders`（CRUD + `/:id/start|stop|control|interrupt|values`）
- **映射**：`/api/forwarders/:id/mappings`、`/api/mappings/:id`
- **厂家型号**：`/api/vendors`、`/api/models`、`/api/models/:id/yaml`（在线编辑）
- **站点环境**：`/api/stations`
- **工况 / 计划 / 阈值**：`/api/scenarios`、`/api/schedules`、`/api/change-rules`
- **监控 / 告警**：`/api/monitor`、`/api/alarms`
- **仿真时钟**：`/api/sim-clock`（GET 查时刻 / 倍速，PUT 设置）
- **配置导入导出**：`/api/config/export|import`
- **工况剧本**：`/api/scripts`（录制 / 回放 / CRUD）
- **注册码**：`/api/license/status`、`/api/license/activate`
- **WebSocket**：`/ws`（实时数据 + 告警帧）

## 目录结构

```
├── config/                # 配置文件
├── data/                  # 运行时数据（db、日志；gitignore）
├── internal/
│   ├── api/               # HTTP 路由与 handler
│   ├── app/
│   │   ├── cache/         # 分片缓存（时间戳对齐 simNow）
│   │   ├── engine/        # 仿真引擎（物理模型 + 告警判定 + 累计量）
│   │   ├── environment/   # 环境枢纽（日照 / 温度 / 天气）
│   │   ├── event/         # 事件总线 + 告警总线
│   │   ├── forwarder/     # 协议转发（modbus/ 子包）
│   │   ├── recorder/      # 工况剧本录制
│   │   ├── simclock/      # 仿真时钟
│   │   └── ws/            # WebSocket hub
│   ├── auth/              # 注册码授权（机器码 + RSA 验签，内嵌公钥）
│   ├── model/             # GORM 数据模型
│   ├── pointtable/        # 点位表（内嵌 yaml + 在线热重载）
│   ├── store/             # 持久化（GORM）
│   └── pkg/               # 公共包（logger 等）
├── web/                   # 前端（Vue 3 + Element Plus）
├── website/               # 产品官网落地页（纯 HTML / CSS / JS）
├── embed.go               # 前端构建产物 go:embed（单文件部署）
└── main.go                # 入口
```

## 注册码授权

支持机器绑定 + RSA 签名的离线注册码授权，用于私有部署防任意拷贝。签发工具与私钥为 vendor 侧资产，不在本仓库；程序内嵌公钥用于验签。

## 更多文档
- `DEVLOG.md` —— 开发记录（每个特性的背景 / 决策 / 落点 / 限制）
- `TESTPLAN.md` —— 测试清单与验证状态

## 路线图
- 协议扩展：IEC104 / OPC UA（dispatcher 已预留）
- 多从站、抓包导出（CSV / PCAP）
- 各特性运行时端到端验证（见 TESTPLAN ⏳ 项）

## 许可证

MIT License