# 使用方法

## 安装与验证

安装 MoonBit 后，在仓库根目录运行：

```bash
moon version
moon check --deny-warn
moon test -p sujy123456/voltweave --deny-warn
```

项目没有第三方 MoonBit 包依赖。第一次构建只需要本地 MoonBit 工具链。

## 内置场景

| 场景 | 命令 | 用途 |
|---|---|---|
| 晴天家庭 | `moon run cmd/voltweave -- demo` | 分时电价、光伏、电池和多类电器的综合演示 |
| 紧凑公寓 | `moon run cmd/voltweave -- compact` | 无电池、小功率配电限制下的移峰 |
| 风暴停电 | `moon run cmd/voltweave -- outage` | 长停电和关键负载保供压力测试 |

`compare` 会运行五组目标权重并给出策略比较；`simulate` 使用固定种子运行 64 个扰动场景；`validate` 输出校验报告；`chart` 输出终端曲线。

## 作为 MoonBit 库使用

```moonbit
let input = @voltweave.home_day_example()
let validation = @voltweave.validate_input(input)
if validation.is_valid() {
  let adequacy = @voltweave.assess_adequacy(input)
  let plan = @voltweave.solve(input)
  let audit = @voltweave.audit_plan(input, plan)
  println(@voltweave.plan_markdown(plan))
  println(adequacy.to_json_string())
  println(audit.to_json_string())
}
```

消费包时，将 `sujy123456/voltweave` 以 `@voltweave` 别名加入包的 `import`，并按照 Mooncakes 上发布的版本固定依赖。

## 构建自定义输入

可以从 `PlanningInput::empty(title, slots)` 开始，再替换同长度时间序列并添加任务：

```moonbit
let base = @voltweave.PlanningInput::empty("my-home", 24)
let task = @voltweave.LoadTask::shiftable(
  "washer",
  "Washing machine",
  900,
  2,
  8,
  18,
  12,
)
let input = {
  ..base,
  tariff_micro_per_kwh: @voltweave.IntSeries::new(
    "tariff",
    "micro/kWh",
    60,
    [320000, 320000, 280000, 280000, 280000, 320000,
     480000, 650000, 650000, 480000, 350000, 300000,
     260000, 260000, 300000, 400000, 620000, 820000,
     820000, 620000, 480000, 400000, 350000, 320000],
  ),
}.with_task(task)
```

所有功率曲线、价格曲线、碳强度曲线和配电上限曲线必须包含 `horizon_slots` 个值，且 `slot_minutes` 一致。调用 `validate_input` 后再调用 `solve`。

## JSON

`moon run cmd/voltweave -- input` 输出完整示例输入；`json` 输出计划结果。领域对象派生了 `ToJson`/`FromJson`，可以在宿主程序中解析或持久化。金额字段使用微单位，`1000000` 表示 1 个货币单位。

## 报告

- `plan_markdown`：完整计划、指标和解释；
- `plan_csv`：逐时负载、电网、光伏、缺供和电池状态；
- `plan_ascii_chart`：适合终端和 CI 日志；
- `simulation_markdown`：样本分布、风险等级和建议；
- `audit_markdown`：约束审计结果。

## 浏览器演示

浏览器必须通过 HTTP 访问，不能直接双击 `index.html`，否则浏览器的本地文件策略会阻止 `fetch` Wasm。构建和启动命令见 README。页面的三种场景、曲线和风险指标都由 `web/engine/engine.mbt` 导出；页面不会发送网络请求到业务后端。