# MoonPlan 设计草案

## 产品定位

MoonPlan 面向需要“在多条业务规则下找到可行或较优安排”的 MoonBit 开发者。首要场景是人员排班，内核保持通用，以便复用于课程表、资源分配、配置求解、谜题和测试数据生成。

项目的差异化不只在求解速度，还包括：

- 同一个模型可在 native、JavaScript 和 wasm-gc 运行；
- 约束、搜索决策和冲突原因使用稳定的类型化表示；
- 结果不仅可执行，还能导出为适合人阅读和可视化的证据；
- 业务层 API 避免用户直接处理变量编号和底层传播器。

## 分层

```text
排班建模层       班次 / 技能 / 可用性 / 休息 / 偏好
解释与优化层     软约束 / 目标函数 / 冲突核心 / 修复建议
有限域求解层     变量 / 域 / 传播器 / 搜索 / 回溯
观测与展示层     搜索事件 / JSON / Wasm / Web 工作台
```

## 核心不变量

1. 变量句柄只能用于创建它的问题。
2. 解中的每个变量恰好绑定一个域内值。
3. 返回的每个解满足全部硬约束。
4. 相同模型和配置在各后端产生相同的第一解和搜索轨迹。
5. 优化结果必须附带目标值；冲突报告必须区分事实、推断和建议。

## 获奖级完成定义

- 不是只展示 N 皇后：至少提供一套可导入、可编辑、可求解的真实周排班案例。
- 支持硬约束与软约束，并能解释无解或偏好违背。
- 浏览器演示由 MoonBit/Wasm 求解器驱动，而非 JavaScript 重写算法。
- 公开可复现的规模基准，对比不同启发式并记录搜索节点和耗时。
- README 示例、CI、核心测试、许可证和 Mooncakes 发布全部齐备。

## 近期里程碑

- M0（已完成）：可运行的有限域求解闭环。
- M1（进行中）：已支持计数、表约束、元素约束、加权线性约束和 degree/LCV 启发式；下一步增加可撤销域与传播队列。
- M2（进行中）：已支持多人覆盖需求、个人工作量配额、连续工作硬上限、分配偏好、连续工作成本、加权与词典序多级目标、精确最小工作量跨度证明，以及组合目标 JSON 输入输出；下一步完善真实周排班规则与软目标分支定界。
- M3（进行中）：已支持命名约束、不可再删减冲突集、工作量与休息策略修复建议，以及软目标惩罚明细；下一步覆盖不可避免偏好的自动修复建议。
- M4（进行中）：已提供 JSON 边界和有界搜索事件流；下一步实现 Wasm 界面与真实案例。