# 架构与技术路线

## 目标与边界

VoltWeave 接收规则化家庭用能场景，输出确定性调度、逐时能源流、风险摘要和审计结果。核心不连接逆变器、电表或智能家居设备，不执行真实控制。将“计划”与“执行”分开，可以让模型在没有设备权限和网络的环境中演示、测试和复现。

## 数据流

```text
PlanningInput
  ├─ validate_input ──> ValidationReport
  ├─ assess_adequacy ─> AdequacyProfile
  └─ solve
       ├─ task candidate search
       ├─ deterministic placement
       ├─ solar/grid/battery dispatch
       └─ PlanResult
            ├─ audit_plan ───────> AuditSummary
            ├─ plan_markdown/csv > human reports
            └─ simulate ─────────> SimulationSummary
```

## 模块职责

| 模块 | 职责 | 关键输出 |
|---|---|---|
| `domain.mbt` | 单位、枚举、领域对象、JSON 合约 | `PlanningInput`, `PlanResult` |
| `validation.mbt` | 输入形状、数值范围和跨字段约束 | 稳定错误码、警告、修复建议 |
| `optimizer.mbt` | 候选生成、排程、能源分派与策略比较 | 计划、解释、Pareto 前沿 |
| `simulation.mbt` | 确定性采样、分位数和敏感性分析 | 风险分布与建议 |
| `analytics.mbt` | 独立计划审计和资源充足性评估 | 审计结果、方案差异 |
| `report.mbt` | 无外部依赖的文本渲染 | Markdown、CSV、ASCII |
| `web/engine` | 小型数值 ABI | 浏览器 Wasm-GC 场景指标 |

## 单位和确定性

浮点舍入会让不同后端的排序边界变得难以解释，所以核心使用整数：功率为 W、能量为 Wh、价格为每 kWh 的微货币单位、效率和概率为千分比。候选项按总分及稳定次级键排序，仿真 PRNG 使用显式 `UInt` 状态与固定种子。因此相同输入、配置、版本和目标后端应产生相同结果。

## 调度流程

1. 校验所有序列长度、时间粒度、任务窗口、电池参数、停电范围和权重。
2. 将固定任务、关键任务、低松弛任务优先排序。
3. 为连续任务枚举允许起点；为可中断任务逐时生成候选。
4. 对增量费用、碳排、舒适偏移、停电风险、容量超限和光伏重叠评分。
5. 选择稳定最优候选，将任务功率写入负载曲线；可选任务在不满足阈值时可跳过。
6. 按时段使用光伏、电网和电池满足负载；维护容量、效率、备用电量和停电边界。
7. 汇总费用、碳排、峰值、缺供、任务完成率、韧性和解释记录。

求解器是可解释的确定性有界搜索，不承诺数学意义上的全局最优。这个边界在报告和 README 中明确保留。

## 不确定性与审计

仿真使用同一求解器运行多个受控样本，扰动包含光伏缩放、基础负载噪声和尖峰、停电起止抖动。摘要通过排序后的整数样本计算 P10/P50/P90/P95，并按缺供和可行率划分风险等级。

审计器不调用求解器内部函数，而是从输入与结果重建约束；这使其能够发现求解流程本身的回归。供需残差允许小量整数效率舍入，同时单独报告最大残差，避免把近似隐藏成“完全平衡”。

## 接口设计

MoonBit 库公开完整类型与纯函数；CLI 负责选择内置场景和文本输出。浏览器演示采用无字符串参数的数值 Wasm ABI，减少 JavaScript 与 Wasm-GC 的边界复杂度。HTML 只负责布局、Canvas 绘制和格式化，所有演示指标与曲线来自 MoonBit 导出函数。

## 后续维护方向

- 增加 15/30 分钟粒度的大规模基准和真实匿名数据适配器；
- 增加分阶段电池寿命模型和需求电费；
- 为自定义 JSON 增加浏览器文件导入，但保持默认离线；
- 研究精确求解器后端，并与当前启发式结果做可复现基准比较。