# StandardScene 快速参考

## 1. 一眼看懂这个仓库

| 项目项 | 说明 |
| --- | --- |
| 工程类型 | 插件库（基座 `StandardScene.dll` + 4 卫星，共 5 个 DLL） |
| 运行方式 | 由 `SimpleLite.exe`（CycleGUI 宿主）从 `plugins\` 加载 |
| 目标框架 | `net8.0-windows` |
| 核心入口 | `MissionType`、`CarType`、`WebApi.cs` |
| 新手起步文件 | `Scheduler\HeartBeatMission.cs` |
| 进阶起步文件 | `Scheduler\RegionalTrafficControlMission.cs` |

## 2. 关键目录速记

| 路径 | 你通常在这里做什么 |
| --- | --- |
| `CarTypes\` | 新车型、协议接入、状态同步 |
| `Chained\` | 搬运任务、环线任务、调度逻辑 |
| `Charge\` | 充电策略、充电桩管理 |
| `InterLock\` | 互锁与交通控制 |
| `Scheduler\` | 心跳、安全、区域流控等后台 Mission |
| `ExtendDevice\Door\` | 门控联动 |
| `Model\` | 配置与数据模型 |
| `WebApi.cs` | HTTP API |
| `Commons.cs` | 标签、字段、选车、路径辅助 |

## 3. 构建运行速记

1. 先构建宿主依赖：`dotnet build Simple\SimpleLite\SimpleLite.csproj`
2. 打开 `StandardScene.sln`，确保本机依赖路径存在
3. 编译解决方案（`Debug|x64` / `Release|x64`）
4. 将 `build\plugins` 部署到宿主 `plugins\`，运行 `SimpleLite.exe`
5. 确认插件已从 `plugins\` 加载

### 注意

当前工程已是 SDK 风格 `.csproj`（`net8.0-windows`），目录下 `.cs` 文件会被自动包含，无需手工添加 `<Compile Include>`。卫星插件需在 `active-scenes.json` 中启用对应场景才会被宿主加载。

## 4. 新增功能时先看谁

| 目标 | 优先参考 |
| --- | --- |
| 新增最小 Mission | `Scheduler\HeartBeatMission.cs` |
| 做区域限流 | `Scheduler\RegionalTrafficControlMission.cs` |
| 做运输调度 | `Chained\TransportMission.cs` |
| 做环线 | `Chained\AbstractLoopMission.cs` |
| 做充电 | `Charge\StandardChargeMission.cs` |
| 做充电桩管理 | `Charge\ChargeStationManagementExample.cs` |
| 做 Web 接口 | `WebApi.cs` |

## 5. 高频代码片段

### 获取车辆与站点

```csharp
var car = SimpleLib.GetCar(carId);
var allCars = SimpleLib.GetAllCars();
var site = SimpleLib.GetSite(siteId);
var allSites = SimpleLib.GetAllSites();
var currentSiteId = car.GetLastSite();
```

### 更新标签与字段

```csharp
Commons.AddOrUpdateTag(car.tags, "occupied", "yes");
Commons.AddOrUpdateCarField(car, "group", "A");
Commons.AddOrUpdateSiteField(site, "giveWay", "true");
```

### 规划并执行路径

```csharp
var plan = new SegmentPlan { usingCar = car };
plan.fields["action"] = "move";
plan.fields["allow_destination_on_route"] = "true";
plan.FindRoute(SimpleLib.GetSite(srcId), SimpleLib.GetSite(dstId));
await plan.Compile("move").Queue();
```

### 输出日志

```csharp
Diagnosis.Post("任务已启动", "demo", true);
Diagnosis.Log("详细调试信息", "demo", true);
car.AppendDebug("车辆状态变化");
```

## 6. 常见配置文件

| 文件 | 用途 |
| --- | --- |
| `Config\traffic.json` | 交通 / 互锁配置 |
| `Config\ChargeStations.json` | 充电桩数据 |
| `Config\ChargeStrategyConfig.json` | 充电策略 |
| `Config\AlarmConfigs.json` | 充电报警 |
| `DoorConfig.json` | 门控配置 |
| `tasklist.json` | 环线任务列表 |
| `simple.json` | 宿主基础配置 |

## 7. 常见 API 路由

| 路由 | 作用 |
| --- | --- |
| `/car/createTask` | 创建任务 |
| `/car/getAllCars` | 获取车辆列表 |
| `/car/goSite` | 让车辆前往站点 |
| `/map/getMap` | 获取地图 |
| `/task/getTask` | 查询任务 |
| `/mission_reflection/get_mission_list` | 获取 Mission 列表 |
| `/mission_reflection/execute/{id}/{method}` | 反射执行 Mission 方法 |

## 8. 调试优先级

出现问题时，建议按这个顺序排查：

1. 插件是否被宿主加载
2. Mission / CarType 是否被识别
3. 配置文件和 `fields` 是否正确
4. 车辆是否在线、是否被标签占用
5. 路径规划是否成功
6. 是否被交通控制或区域流控拦截
7. 外部接口是否真的打到了 `WebApi.cs`

## 9. 常见故障速查

| 现象 | 优先检查 |
| --- | --- |
| 新增 Mission 看不到 | 特性、`Create()`、`.csproj` 引用、插件复制 |
| 任务一直不执行 | 车辆在线状态、路径、标签占用、前置条件 |
| 区域限流无效 | 站点字段是否以 `Region` 开头，值是否为整数 |
| API 调不通 | 路由路径、宿主端口、Nancy 是否已启动 |
| 车辆不动 | 路径失败、程序未下发、协议未连通 |

## 10. 推荐上手案例

### HelloMission

- 目标：理解最小插件生命周期
- 参考：`Scheduler\HeartBeatMission.cs`
- 验证：启动后 `status.status` 每秒递增

### 区域流控

- 目标：理解字段驱动 + 事件订阅
- 参考：`Scheduler\RegionalTrafficControlMission.cs`
- 验证：给站点添加 `Region1=1` 后，第二台车进入同区域会被阻止