{
  "name": "class84-pk-api",
  "version": "1.0.0",
  "title": "八年级四班 · 地理闯关双人PK接口",
  "description": "房间制在线对战接口：房主下发题目，服务端权威判分并定时推进，题目答案在揭晓前不下发。",
  "base_url": "https://pk.hm84.de5.net/api/pk",
  "websocket": "wss://pk.hm84.de5.net/api/pk/ws?room={room}&side={side}&token={token}",
  "health": "https://pk.hm84.de5.net/health",
  "transport": {
    "method": "POST",
    "content_type": "application/json",
    "cors": "Access-Control-Allow-Origin: *",
    "preflight_cache_seconds": 86400
  },
  "auth": {
    "fields": ["room", "side", "token"],
    "side_values": ["host", "guest"],
    "notes": "create / join / match 返回 token；后续请求必须携带 room + side + token"
  },
  "action": {
    "ping": {
      "params": {},
      "returns": ["ok", "now"],
      "description": "连通性探测"
    },
    "create": {
      "params": {
        "name": "string, 1-16 字符",
        "questions": "array<{province:string,type:int,options:string[],answerIndex:int}>",
        "config": "object{questionType:int,mapType:'full'|'outline'}"
      },
      "returns": ["ok", "room", "side", "token", "state"],
      "description": "创建房间，房主为 host"
    },
    "join": {
      "params": { "room": "string, 4-8 位大写字母数字", "name": "string" },
      "returns": ["ok", "room", "side", "token", "state"],
      "errors": ["409 房间已满或已结束", "410 房主久未活动，房间失效"],
      "description": "作为 guest 加入；同名重复请求按幂等处理"
    },
    "match": {
      "params": { "name": "string" },
      "returns": ["ok", "matched", "room?", "side?", "token?", "state?"],
      "description": "随机匹配一个等待中的房间"
    },
    "poll": {
      "params": { "room": "string", "side": "string", "token": "string" },
      "returns": ["ok", "state"],
      "description": "拉取最新状态，同时刷新在线心跳"
    },
    "answer": {
      "params": {
        "room": "string", "side": "string", "token": "string",
        "qIndex": "int, 必须等于当前 state.qIndex",
        "optionIndex": "int, 0..options.length-1"
      },
      "returns": ["ok", "correct", "state"],
      "errors": ["409 本题已揭晓"],
      "description": "提交作答；重复提交不会重复计分"
    },
    "next": {
      "params": { "room": "string", "side": "host", "token": "string" },
      "returns": ["ok", "state"],
      "description": "房主推进下一题（兜底，正常由服务端自动推进）"
    },
    "reset": {
      "params": { "room": "string", "side": "host", "token": "string", "questions": "array", "config": "object" },
      "returns": ["ok", "state"],
      "description": "房主重开一局，比分与拔河归零"
    },
    "leave": {
      "params": { "room": "string", "side": "string", "token": "string" },
      "returns": ["ok", "left"],
      "description": "离场；对局中离场视为认输"
    }
  },
  "state": {
    "room": "string",
    "phase": "waiting | playing | finished",
    "seq": "int, 单调递增，客户端据此丢弃旧状态",
    "qIndex": "int",
    "qTotal": "int",
    "question": "{province,type,options} | null（不含 answerIndex）",
    "revealed": "bool",
    "answerIndex": "int | null（仅 revealed 后下发）",
    "questionWinner": "host | guest | null",
    "host": "{name,score,answered,online}",
    "guest": "{name,score,answered,online} | null",
    "tug": "int，host 答对 -1，guest 答对 +1",
    "winner": "host | guest | draw | null",
    "config": "{questionType,mapType}",
    "advanceAt": "int，揭晓后的推进时间戳（毫秒），未揭晓为 0",
    "startedAt": "int"
  },
  "rules": {
    "score_per_correct": 10,
    "reveal_on_first_correct": true,
    "reveal_when_both_answered": true,
    "question_timeout_ms": 30000,
    "advance_delay_ms": 3000,
    "offline_threshold_ms": 15000,
    "offline_rescue_delay_ms": 2000,
    "finish_when_tug_abs": 10,
    "finish_when_questions_exhausted": true,
    "draw_when_tug_zero_at_end": true
  },
  "errors": {
    "400": "参数缺失或格式错误",
    "401": "token 校验失败或席位不存在",
    "403": "该操作仅房主可用",
    "409": "本题已揭晓 / 房间已满 / 对局已结束",
    "410": "房间失效（房主长时间无活动）",
    "500": "服务端内部错误"
  },
  "error_shape": { "ok": false, "error": "可读的中文说明" }
}
