moonbit-returnplay

一个纯 MoonBit 实现的、确定性且可审计的重返运动决策框架。

它把多项已经完成的测试结果整合成透明的阶段结论：每项测试有明确权重、通过门槛、是否必需和说明；评估过程记录缺失数据、分数贡献、触发的硬门槛和最终状态。框架只组织和解释输入结果，不进行医疗诊断、治疗建议或自动放行。

为什么做这个项目

很多“能不能进入下一阶段”的判断不是缺少数据，而是数据分散在不同测试表里，权重、门槛和缺失项的处理方式不透明。moonbit-returnplay 提供一套可复用的领域模型，让同一份输入在不同平台上得到同一份结果，并且能解释“为什么是这个结果”。

它不是另一个通用规则引擎。Mooncakes 中已有通用规则、工作流、状态机和溯源类工具，本项目把边界收敛在重返运动协议：测试项、阶段、评分、缺失策略、流程结论和审计事件。

快速运行

需要 MoonBit 0.10.x 工具链。当前开发环境使用 moonc v0.10.4。

moon fmt
moon check --deny-warn
moon test --deny-warn
moon run ./examples/returnplay_demo

示例输出：

stage=baseline; score=87; covered=3/3; status=ready; missing=; reasons=; audit-events=4
boundary=not-medical-diagnosis

ReturnStage makes the supported progression explicit: Baseline, Reconditioning, SportSpecific, ReturnToPlay, or a non-empty Custom stage. Scores use integer arithmetic; weighted averages truncate toward zero, so the audit output remains reproducible across targets.

Remote mirrors

GitHub: https://github.com/qxjhhrr/moonbit-returnplay
GitLink: https://gitlink.org.cn/qxjhhrr/moonbit-returnplay

Both mirrors publish the main branch. The hackathon proposal remains a local delivery artifact under submission/ and is intentionally absent from the published tree.

核心 API

let definitions = [
  @returnplay.test_definition(
    id="strength",
    stage=@returnplay.return_stage_baseline(),
    name="Strength",
    weight=2,
    required=true,
    threshold=70,
    note="Generic example only",
  ),
]
let observations = [
  @returnplay.observation_entry(
    id="strength",
    value=@returnplay.observation_score(86),
  ),
]
let result = @returnplay.evaluate_stage(
  definitions=definitions,
  observations=observations,
  policy=@returnplay.stage_policy_with_gates(
    missing=@returnplay.missing_policy_block_required(),
    gates=[@returnplay.gate_minimum_score(70)],
  ),
)

观察值可以是 Pass、Fail、0—100 的定点评分或 Missing。必需项缺失不会被当作通过；可选项可显式排除或转人工复核。阶段状态包括 AwaitingData、OnHold、Ready 和 NeedsReview。

项目结构

src/returnplay/           # 领域模型、校验、评估、审计
examples/returnplay_demo/ # 可运行的最小闭环
scripts/                  # 本地 CLI 冒烟检查
docs/                     # 设计、计划与生态扫描
submission/               # 参赛项目申报书
.github/workflows/        # 三平台 MoonBit CI

质量门禁

项目 CI 参考 MoonBit 社区的 check.yml 模板，覆盖 Ubuntu、macOS 和 Windows，并执行格式化、信息生成、检查、测试和示例运行。由于不同 Moon CLI 版本的命令参数存在差异，scripts/cli-check.ps1 会优先执行严格参数，遇到当前工具链不支持的 moon fmt --deny-warn / moon info --deny-warn 时使用等价的 moon fmt --check / moon info 兼容路径，同时保留失败退出码。

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\cli-check.ps1

安全边界

这是一个流程与审计库，不是医疗器械、诊断系统或治疗建议系统。示例阈值仅用于演示 API；真实使用必须由具备资质的专业人员定义测试、阈值、阶段和复核流程。

许可证

Apache-2.0，见 LICENSE。生态查阅与差异说明见 docs/ecosystem-scan.md。

发布前仓库核对项见 docs/release-checklist.md；申报书是本地交付材料，不放入远端项目树。