每日、四榜与公开回放API v0.8.1#

2026-09-13 · 设计态；基路径 /api/v1。共用基础API的HTTPS、Cookie会话、CSRF、Origin、expected_user_id、UUID、UTC毫秒、安全整数和错误包络。Redis仅用于每日榜单缓存及官方录像TTL存储。P=公开/匿名会话，G=云游客或注册会话，R=活跃注册账号，O=本人操作资源，V=当前观看会话所有者；所有权限由服务端推导。

1. 公共写入规则#

登录写接口要求 Idempotency-Key；同user/route（含board_kind）/key同内容返回原回执，不同内容409。回执与对象在同一SQLite事务提交，不以网络超时判断“肯定没成功”。接管使用控制epoch/CAS。每条WS输入也重新鉴权和校验控制epoch，不能只在握手检查一次。

压缩官方证据只走本文件upload路由，不走private /blobs、/sync/push 或个人收藏接口。线上结果不能由普通run.finish升级成正式成绩。直播与PVP路由、消息枚举和专用表全部不注册，客户端不展示对应入口。

2. 服务器每日题#

历史补打由历史练习包＋私人同步完成，不创建新的历史正式attempt。当前日仅有服务器地图不存在合法本地生成降级。今日normal受伤完成可推进下一档及今日观看资格；ranked额外记录零伤段，受伤完成仍可推进下一档。每日原有经验用同一权益账本，不能因normal与ranked各领一次。

3. 四榜成绩预选与官方录像#

POST /daily/:date/leaderboards/:board_kind/scores R：主动选择参榜或已有候选自动上传设置后调用。board_kind为easy/medium/expert/overall；单项只需对应档，综合三档齐全但不要求单项Top10。具体四榜联动见四榜规格。

单项请求例（示意ID/hash，实际须合法UUID/hex）：

{
  "attempts":{"easy":"uuid-easy"},
  "client_total_ms":40000,
  "replay_manifest":[{"attempt_id":"uuid-easy","format_version":1,"codec":"gzip",
    "compressed_bytes":32000,"uncompressed_bytes":180000,
    "compressed_sha256":"64位hex","content_sha256":"64位hex"}],
  "allow_public_replay":true
}

overall的attempts强制easy/medium/expert三个key，manifest覆盖三段；单项拒绝额外档字段。已有核验段使用 {attempt_id,verified_segment_id} 替代上传描述；其他设备已登记官方清单的段用 {attempt_id,registered_manifest:true}，服务器解析为固定双hash/字节数再预选。未登记的跨端段返回SOURCE_MANIFEST_REQUIRED并标记缺失attempt，不发未绑定hash的授权。client_total_ms只是诊断，服务端从终局重算单项用时或三档之和。不能因单项未入围而拒绝独立满足综合榜条件的组合。

响应 {submission_id,board_kind,state,compared_generation,provisional_rank,expires_at,uploads:[{upload_id,attempt_id,max_compressed_bytes}],reused_segments:[]}。未入围state=not_candidate，无uploads；候选名次不等于正式占位。每账号/日期/榜最多一个pending（总计4个），每账号共享上传/请求配额。

不同设备的三段按账号在服务端关联；任何本人登录设备可读取待上传授权并提交自己持有的段，不要求综合申请设备有三份文件。未上线设备缺段时保持等待，截止前缺段不入榜。同段同时被多榜申请时按game_id/hash去重归档，不能复制一份正文到四个目录。

授权即SQLite记录＋会话归属，不使用可转发的永久预签名直链。PUT中途过期/跨日须终止；Redis暂存绑定授权TTL自然回收，无录像清理job。先限制压缩字节，服务器受控解压再查展开上限、事件数、哈希与重演；即使客户端申报小尺寸也强制实际计数。

先manifest/成绩预选，再按本人game＋规范内容SHA-256查已验证文件；有效正文仍在则返回reused_segments，不发上传授权。已有上传/验证返回原id和状态，不重建任务。PUT前预检原回执与Redis实际存在状态，重复成功请求不再读文件；并发同段返回UPLOAD_IN_PROGRESS。gzip文件hash用于传输校验，规范内容hash用于识别同一录像，首次接收两者由服务器重算；不同账号不可互查去重状态。具体流式拒收、双hash语义与竞态见Redis上传限制和去重规则。

状态：not_candidate；或 awaiting_upload → verifying → published | outpaced | rejected | expired。没缺失段也仍走complete（或服务端等价调度）和原子再比较，发布前在Redis确认正文及固定public_until TTL，随后在DB事务复制未变化榜、切四榜共用generation，commit后写榜单缓存；跨库不能声称原子，缓存失败回源DB；不凭“以前上传过”跳过当前日期/观看锁校验。验证报告带attempt、输入hash、规则版本，事务内重新检查它们未变。

published表示该组合在该generation正式入榜，不保证之后仍在Top10；UI同时查询当前排名。outpaced表示证据合法但不再足够快；段可在当日复用。排队越过截止返回expired，不能第二天发布昨天名次。推送 daily.submission_changed带board_kind；daily.changed带共用generation/changed_boards，仅通知状态，断线以GET重取，不重复上传。

4. 在线控制与消息#

wss://同源/api/v1/realtime 使用Cookie＋精确Origin，hello带CSRF/expected_user_id/device_id；匿名仅能订阅绑定匿名Cookie的watch。退出/改密/删除即时撤授权，命令和敏感投影都复查会话。

{"type":"game.command","game_id":"uuid-game","command_id":"uuid-command",
 "control_epoch":2,"input_epoch":3,"client_seq":42,
 "action":{"type":"chord","cell":{"x":4,"y":7}}}

action只允许 open/flag/unflag/chord＋合法cell，另允许明确resign；禁止toggle重放导致反转、任意时间/seed/XP/结果写入。seq按game/user/control_epoch单调，input_epoch在恢复时变化。消息缺口暂停输入，重新获取快照；已提交command重试取回执，未提交离线操作丢弃。

服务器消息 {type,channel_id,channel_seq,server_time,payload}，包括 game.started/state_delta/command_receipt/control_changed/result、daily.changed/submission_changed、watch.frame/revoked。ACK提供规范事件与服务器锚点供本地官方草稿追加；数据库只持久最小摘要、去重回执及当前状态。结果在写事务后确认，客户端的动画耗时不参与成绩。

5. 本期接口范围#

本版不注册直播/PVP接口、实时旁观订阅、场次与占位能力；未知旧路由返回404。普通经典/历史练习使用本地游戏与私人同步。保留每日WSS输入确认、本人候选通知与榜单变更通知，不提供任何其他玩家进行中棋盘的实时数据。watch仅接受下节定义的已发布公榜录像。

6. 观看与日切#

匿名watch使用调用方生成watch_id绑定随机匿名HttpOnly Cookie；重复创建检查原资源、close幂等，不写要求user_id的online_http_receipts。登录watch联合绑定user_id/auth_session_id，不能用他人watch_id越权。历史不创建watch_exposures；当天来源跨日后重新评估并切历史路径，不能锁新日期。

四榜GET采用DB generation＋Redis同代缓存，miss/Redis故障回源DB；昵称/注记/权限/播放可用性在响应时重查。录像读取不续TTL，DB截止已过返回REPLAY_EXPIRED，Redis连接故障返回503，健康Redis缺原正文返回REPLAY_MISSING。详见Redis契约。

各段授权不可跨资源继承。切换不同日期/榜单/录像段时重新校验；历史录像→今天录像必须先检查当日资格并提示日期锁，不能自动播放绕过确认。未完成当天者只看摘要，不因历史开放看到未结束日期棋盘。解码字节已发无法追回；服务器停止后续发放、官方播放器清缓冲。详情见观看边界。

7. 参数与验证边界#

除UTC日期、Top10容量、用户确认的规则外，以下均建议初值 [待确认][待测试]；不是上线承诺。

本期单SQLite写协调器，验证线程不能直接绕过裁决器写榜；限流内存有界，重启只允许短突发重置，奖励、截止与授权持久化不可重置。端到端验收见矩阵；DDL通过不等于HTTP/WSS/压缩/地图/重演已实现。

8. 版本记录#