# MoonEvac 技术设计

## 设计目标

MoonEvac 的核心目标是让疏散方案的输入、决策和结果都可解释、可复现、可测试。项目不追求高精度物理烟气模拟，而是提供一个零外部依赖、能够跨 MoonBit 支持目标运行的图级分析内核。

## 数据流

```text
EvacuationPlan
  ├─ validate_plan ──> Diagnostic[]
  ├─ route_to_nearest_exit ──> Route
  ├─ ScenarioState + HazardConfig
  │    └─ advance_hazard ──> risk / passage state
  └─ run_simulation
       ├─ capacity queues
       ├─ dynamic rerouting
       ├─ cohort splitting
       └─ SimulationResult
             ├─ Markdown / JSON / CSV
             ├─ plan SVG / timeline SVG
             └─ resilience analytics
```

## 模块职责

### 领域模型

`model.mbt` 定义地点、通道、人员、事件、方案和诊断。标识符使用字符串，并由验证器保证唯一性。数组顺序既是稳定输出顺序，也是在等价路径之间的确定性决胜规则。

### 验证

`validation.mbt` 分阶段执行头部、地点、通道、人口、出口可达性和出口冗余检查。验证器尽可能收集全部问题，而不是遇到第一个错误就退出。

### 路由

`routing.mbt` 使用 O(V²+VE) 的确定性 Dijkstra 实现。对黑客松规模的建筑图，这种实现比优先队列版本更容易审计。边权由距离、风险、拥堵、楼梯和宽度共同组成。无障碍模式会排除不可访问通道。

### 危险传播

`hazard.mbt` 使用 0 到 1 的归一化风险。每个时间步先应用场景事件，再计算源增长、被动衰减和沿通道的风险差传递。扩散系数根据门、走廊、楼梯、坡道和室外通道调整。

### 疏散状态机

`simulation.mbt` 将同一人口组表示为一个或多个 cohort。当通道容量不足时，cohort 会被拆分，允许部分人员前进、其余人员排队。每个时间步依次完成危险更新、队列估计、容量分配、移动和快照记录。

### 报告与分析

`report.mbt` 不依赖第三方序列化或绘图库，直接输出稳定 JSON、Markdown、CSV 和 SVG。`analytics.mbt` 提供分位数、出口使用平衡、关键节点、通道压力、阈值时间和场景排名。

## 确定性保证

- 不读取系统时间或随机源；
- 不依赖哈希表遍历顺序；
- 相同代价时保留输入顺序较早的路径；
- 事件按方案数组顺序应用；
- 所有输出数组保持稳定顺序。

## 安全边界

这是教学和方案预检模型。风险值不等价于温度、能见度或毒性浓度，通道流率也不是法规认可的工程参数。任何真实建筑的使用都应由有资质的专业人员复核。