谱面评分与评论

曲目/谱面评论：1–5 星评分、评论正文、按曲目/谱面聚合统计，以及评论串与审核状态。

「谱面评论」是 RankHub 的社区内容：用户针对某个游戏的某张谱面打 1–5 星并写一段评论。一条谱面评论同时是一条社区帖子，所以它也有评论串、点赞、举报与审核状态。

支持的游戏：maimai、phigros、arcaea。

scope 与门槛

读 /v0/social/** 需要 social:read，写需要 social:write（写覆盖读）。 发布内容要求账号已绑定并验证手机号（未验证 ⇒ 403 A verified phone number is required to publish content）；账号在注销流程中同样 403。

这一族是过渡例外

/v0/social/** 现在只服务 RankHub 自有客户端（公开档案、社交主页等），第三方令牌打过去会得到 403 game.firstPartyOnly。谱面评论是两族例外之一：它的 v1 形状还没设计，所以过渡期内第三方继续用 /v0，行为不变。过渡结束后会迁到 v1 并另行公告。整体边界见权限范围与可用 API。

谱面标识

创建评论时必须给出可解析的 chartKey，平台会把它解析成谱面快照（标题、难度、定数、谱师、封面）：

游戏	`songId`	`chartKey`
`maimai`	数字曲目 ID（字符串形式）	`standard-0` … `standard-4`、`dx-0` … `dx-4`、`utage-0` … `utage-4`（数字是难度下标：Basic/Advanced/Expert/Master/Re:MASTER）
`phigros`	曲目 ID	`EZ` / `HD` / `IN` / `AT` / `Legacy`
`arcaea`	曲目 ID	`PST` / `PRS` / `FTR` / `BYD` / `ETR` / `INS`

解析失败（曲目不存在 / 谱面不存在）⇒ 404。

创建

curl -sS -X POST https://api.rankhub.cc/v0/social/chart-reviews \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "game": "maimai",
    "songId": "834",
    "chartKey": "dx-3",
    "rating": 5,
    "markdownBody": "谱面很爽，副歌前的交互需要练。",
    "imageAssetIds": []
  }'

字段	约束
`game`	`maimai` / `phigros` / `arcaea`
`songId`	1–128 字符
`chartKey`	1–64 字符，见上表
`rating`	整数 1–5
`markdownBody`	1–50000 字符（Markdown）
`imageAssetIds`	可选，≤8 个已上传的图片资产 ID

两条硬规则：

一个人对同一张谱面只能有一条生效中的评论。重复创建返回 409，并在响应体里带上已有评论：

{
  "statusCode": 409,
  "error": "ChartReviewAlreadyExists",
  "message": "Each user can publish only one review per chart",
  "action": "edit_review",
  "reviewId": "1c2f…"
}

拿到 reviewId 就应引导用户去编辑，而不是再建一条。

发帖权限按分区判定：没有该游戏评论分区的发帖权限 ⇒ 403 You cannot post in this section。

新建后状态是 pending_review（进入社区审核）；审核通过后才对所有人可见。创建响应会立即返回内容，但不要把它当成已公开——列表里的公开结果只包含已发布的评论。

列表与统计

GET /v0/social/chart-reviews?game=maimai&songId=834&chartKey=dx-3&limit=20&cursor=

参数	说明
`game`	可选；过滤游戏
`songId`	可选；过滤曲目
`chartKey`	可选；过滤谱面
`limit`	默认 20，上限 50
`cursor`	上一页响应里的 `nextCursor`，原样回传

两个组合约束（不满足会 400）：给 songId 时必须同时给 game；给 chartKey 时必须同时给 game 与 songId。

{
  "items": [
    {
      "id": "1c2f…",
      "postId": "1c2f…",
      "game": "maimai",
      "songId": "834",
      "chartKey": "dx-3",
      "rating": 5,
      "chart": {
        "title": "スパイダー",
        "artist": "…",
        "difficulty": "DX MASTER",
        "level": "13+",
        "charter": "…",
        "artworkUrl": "https://assets2.lxns.net/maimai/jacket/834.png"
      },
      "markdownBody": "…",
      "imageAssetIds": [],
      "imageUrls": [],
      "status": "published",
      "author": { "uid": "12345", "displayName": "…", "avatarUrl": "…" },
      "likeCount": 3,
      "bookmarkCount": 1,
      "commentCount": 2,
      "viewerLiked": false,
      "viewerBookmarked": false,
      "canEdit": false,
      "publishedAt": "2026-10-21T00:00:00.000Z",
      "createdAt": "2026-10-20T00:00:00.000Z",
      "updatedAt": "2026-10-21T00:00:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

id 与 postId 相同：评论的 reviewId 就是帖子 ID，评论串、点赞、举报都用这个 ID。

曲目评分统计

GET /v0/social/chart-reviews/statistics?game=maimai&songId=834

{
  "game": "maimai",
  "songId": "834",
  "averageRating": 4.4,
  "ratingCount": 18,
  "distribution": { "1": 0, "2": 1, "3": 2, "4": 5, "5": 10 },
  "charts": [
    {
      "chartKey": "dx-3",
      "averageRating": 4.6,
      "ratingCount": 12,
      "distribution": { "1": 0, "2": 0, "3": 1, "4": 4, "5": 7 }
    }
  ]
}

averageRating 在无人评分时是 null；charts 按谱面给出同样的三项统计。

读取 / 编辑 / 删除单条

操作	路径
读取	`GET /v0/social/chart-reviews/{reviewId}`
编辑	`PATCH /v0/social/chart-reviews/{reviewId}`（`rating` / `markdownBody` / `imageAssetIds`，都可选）
删除	`DELETE /v0/social/chart-reviews/{reviewId}`（软删除，作者或版主）

编辑与删除会重新进入审核流程；已软删除的内容不再出现在列表与统计里。

评论串

评论挂在「帖子」上，所以对谱面评论留言就是给 postId（= reviewId）发评论：

操作	路径	身份
评论列表	`GET /v0/social/posts/{postId}/comments?limit=20&cursor=`	可选登录（公开读）
发表评论	`POST /v0/social/posts/{postId}/comments`	必须登录（`social:write`）
删除评论	`DELETE /v0/social/comments/{commentId}`	必须登录（作者或版主）

{
  "markdownBody": "同感，副歌前那段最容易掉。",
  "parentCommentId": null,
  "imageAssetIds": [],
  "references": []
}

字段	约束
`markdownBody`	1–20000 字符
`parentCommentId`	可选；回复某条评论时传它的 ID（顶层评论不传）
`imageAssetIds`	可选，≤8
`references`	可选，≤20；元素是 `{ targetType, targetId }`，`targetType` 取 `post` / `comment` / `user`

规则与状态：

发表评论同样要求已验证手机号；帖子被作者关闭评论（commentsClosed）⇒ 403 Comments are closed for this post（列表接口则返回空结果的 200，不报错）。
评论的可见性受帖子所在分区的 commentPolicy 约束（所有人 / 仅关注者 / 关注满 7 天）。
评论发布即公开（不走 pending_review），但会被举报/审核下线（status 变成 soft_deleted）。
列表分页是游标：返回 { items, nextCursor, hasMore }，把 nextCursor 原样传回。
parentCommentId 只表示「回复哪一条」；响应里的 rootCommentId 指向顶层评论，便于组装楼层。

状态与审核

`status`	含义
`draft`	草稿（用户面不产生）
`pending_review`	等待审核（新建评论的初始状态）
`published`	已公开
`rejected`	审核未通过
`soft_deleted`	已删除/下线（不再出现在列表与统计）

列表接口默认只返回 published 的内容；viewerLiked / viewerBookmarked / canEdit 是「带身份时」的个性化字段，匿名请求里恒为 false / false / false。

谱面评分与评论

谱面标识

创建

列表与统计

曲目评分统计

读取 / 编辑 / 删除单条

评论串

状态与审核

下一步

曲目别名投票

游戏档案

业务 API 总览

本页内容