{
  "service": "NeuroGolf cost syncer",
  "description": "同步 400 个 task 的已知 cost（越低越优）。记录不可变（append-only），纠错通过追加 void 记录。无鉴权。",
  "endpoints": [
    {
      "method": "GET",
      "path": "/api/best",
      "description": "全部 400 个 task 的当前最佳快照；best 为 null 表示尚无记录"
    },
    {
      "method": "GET",
      "path": "/api/tasks/{id}",
      "description": "单个 task 的完整历史记录（含作废关系）与最佳选中原因。id 取 1-400"
    },
    {
      "method": "POST",
      "path": "/api/records",
      "description": "追加一条分数记录，返回是否成为新最佳",
      "body": {
        "task_id": "int 1-400（必填）",
        "cost": "number >= 0（必填）",
        "source": "'local_scorer'（默认）| 'kaggle_confirmed'",
        "solution_name": "string（可选，自动登记为方案制品）",
        "kaggle_submission_id": "string（可选）",
        "file_hash": "string（可选）",
        "user_name": "string（可选，默认 'anonymous'）",
        "note": "string（可选）"
      },
      "response_example": {
        "ok": true,
        "record_id": 401,
        "is_new_best": true,
        "best": "…snapshot row…"
      }
    },
    {
      "method": "POST",
      "path": "/api/records/batch",
      "description": "批量追加，逐条校验并返回每条结果。atomic=true 时任一条非法则整批拒绝；合法记录始终在单事务内写入",
      "body": {
        "records": "[同 /api/records 的 body]",
        "atomic": "bool（默认 false）"
      }
    },
    {
      "method": "POST",
      "path": "/api/void",
      "description": "作废一条分数记录（追加 void 记录并重算该 task 快照），历史不删除",
      "body": {
        "record_id": "int（必填）",
        "reason": "string（必填）",
        "user_name": "string（可选）"
      }
    },
    {
      "method": "GET",
      "path": "/api/solutions",
      "description": "全部方案制品"
    },
    {
      "method": "GET",
      "path": "/api/export",
      "description": "全量 JSON 导出（solutions + records），用于备份与重建"
    }
  ]
}