StandardSence/README.md

# StandardScene

`StandardScene` 是一个基于 `.NET 8`（`net8.0-windows`）的场景插件库，运行时由 `SimpleLite.exe` 作为宿主加载。项目面向 AGV/AMR 场内调度与联动控制，覆盖搬运任务、环线任务、区域交通管制、充电管理、门禁联动，以及 HTTP / MQTT / Modbus 等对外通信能力。

> 历史说明：早期版本基于 `.NET Framework 4.8` 并由 `SimpleComposer.exe` 加载；现已迁移到 `net8.0-windows` + `SimpleLite.exe` 宿主，并拆分为「基座 + 4 个卫星」共 5 个插件 DLL。界面正逐步从 WinForms 迁移到 CycleGUI（与宿主同栈），任务列表 `DeliveryViewer` 已完成迁移。

## 文档入口

- `DocumentHub.html`：单文件文档门户，双击即可在浏览器中打开
- `Doc/ARCHITECTURE.md`：整体代码架构文档（模块地图、插件机制、扩展点、接手清单）
- `Doc/DEVELOPMENT_GUIDE.md`：面向整个仓库的开发指南
- `Doc/QUICK_REFERENCE.md`：高频开发速查表
- `Doc/INDEX.md`：阅读顺序与导航说明

## 项目定位

- 工程类型：类库插件（基座 + 4 个卫星，共 5 个 DLL），不是独立 EXE
- 宿主程序：`SimpleLite.exe`（CycleGUI 应用）
- 目标框架：`net8.0-windows`
- 主要语言：`C#`
- 界面技术：逐步从 WinForms 迁移到 CycleGUI（宿主同栈）；`DeliveryViewer`（任务列表）已迁移
- 典型场景：仓储搬运、区域流控、充电协同、门控联动、车辆协议接入

## 插件构成

| 插件 DLL | 场景 id | 职责 |
| --- | --- | --- |
| `StandardScene.dll`（Core，基座） | —（alwaysLoad） | 任务调度、交通互锁、充电编排、门禁/按钮盒、HTTP API、数据模型、抽象契约 |
| `StandardScene.Magnetic.dll` | `scene.mag` | 磁导航平台车型与磁循迹 Coder |
| `StandardScene.QrLidar.dll` | `scene.qrlidar` | 激光 SLAM + 二维码导航，多种车型 |
| `StandardScene.Devices.dll` | `scene.device` | 具体硬件驱动（Modbus 门控、充电桩、按钮盒） |
| `StandardScene.Protocol.VDA5050.dll` | `scene.vda5050` | VDA5050（MQTT）标准协议栈与标准车型 |

卫星插件依赖基座（星型，单向，无循环引用）；各卫星附带 `<dll>.scene.json` 清单，由宿主按 `active-scenes.json` 选择性加载。

## 顶层模块

| 目录 | 作用 |
| --- | --- |
| `CarTypes` | 各车型与协议适配，如叉车、Kiva、VDA5050、多车联动 |
| `Chained` | 链式搬运与环线任务主流程 |
| `Charge` | 充电策略、充电桩管理、状态监控 |
| `ChargeStationType` | 充电桩类型实现 |
| `InterLock` | 区域互锁与交通控制 |
| `Scheduler` | 场景级辅助任务，如心跳、区域流控、安全信号 |
| `ExtendDevice/Door` | 门控设备接入与联动 |
| `Model` | 任务、配置、地图等数据模型 |
| `TCP` / `Utils` | TCP、JSON、WebAPI、Modbus 等基础工具 |

## 构建与运行

> 重要：StandardScene 通过 `HintPath` 引用宿主产物，必须先构建 Simple 解决方案，否则会出现 `SimpleCore` 版本不匹配等编译错误。

1. 先构建宿主依赖：`dotnet build Simple\SimpleLite\SimpleLite.csproj`（会一并构建 `SimpleCore` 项目），产出：
   - `Simple\SimpleLite\bin\Debug\SimpleLite.dll`
   - `Simple\SimpleCore\bin\Debug\netstandard2.0\SimpleCore.dll`
2. 确认本机依赖路径存在（见各 `.csproj` 的 `HintPath`）：
   - `D:\MDCS\Dependencies\Commons\CommonUsage.dll`、`MDCSToolBox.dll`、`CycleGUI.dll`
   - `Simple\SimpleLite\bin\Debug\SimpleLite.dll`、`LessokajiWeaverUtilities.dll`
   - `Simple\SimpleCore\bin\Debug\netstandard2.0\SimpleCore.dll`
3. 使用 Visual Studio 打开 `StandardScene.sln`，或执行 `dotnet build StandardScene.sln`
4. 编译 `Debug|x64` 或 `Release|x64`
5. 编译后 `Directory.Build.targets` 会自动将 5 个插件 DLL（+ PDB + `*.scene.json` + Devices 的 `leegKeys-sdk.dll`）复制到 `build\plugins\`
6. 将 `build\plugins\` 内容部署到 `SimpleLite.exe` 进程工作目录下的 `plugins\`，运行 `SimpleLite.exe`，由宿主按 `active-scenes.json` 选择性加载插件

## 开发阅读顺序

1. 先看 `DocumentHub.html`，快速建立全局认知
2. 再看 `DEVELOPMENT_GUIDE.md`，熟悉架构、流程与配置
3. 开发时配合 `QUICK_REFERENCE.md` 快速查常用入口
4. 新增功能前，先对照 `Scheduler\HeartBeatMission.cs` 或 `Scheduler\RegionalTrafficControlMission.cs`

## 推荐起步文件

- `Scheduler\HeartBeatMission.cs`：最小 Mission 结构参考
- `Scheduler\RegionalTrafficControlMission.cs`：事件订阅型 Mission 参考
- `Chained\TransportMission.cs`：搬运任务主流程
- `Charge\StandardChargeMission.cs`：充电任务骨架
- `WebApi.cs`：HTTP 接口入口

## 本地打开 HTML 文档

直接双击 `DocumentHub.html` 即可，无需部署。页面已使用 `UTF-8` 编码，并对中文、English 和 emoji 做了兼容字体设置。